vigiles 27.1.7 → 27.3.0

package/dist/core/hook-program.js

@@ -15,6 +15,7 @@ exports.dispatchKind = dispatchKind;
 exports.hookMode = hookMode;
 exports.hookNeeds = hookNeeds;
 exports.hookRouting = hookRouting;
+exports.checkRoleEventFit = checkRoleEventFit;
 exports.compileHookProgram = compileHookProgram;
 exports.stampHook = stampHook;
 exports.verifyHookStamp = verifyHookStamp;
@@ -88,6 +89,7 @@ const hash_js_1 = require("./hash.js");
  * fails if `@iarna/toml` reappears in a decision's module graph.
  */
 const stringifyToml = (value) => require("@iarna/toml").stringify(value);
+const event_capability_js_1 = require("./event-capability.js");
 const hook_events_js_1 = require("./hook-events.js");
 const tool_contract_js_1 = require("./tool-contract.js");
 const merge_conflict_js_1 = require("./merge-conflict.js");
@@ -743,6 +745,79 @@ function renderSettingsBlock(on, matcher, gateCommand, format) {
         : { matcher, hooks: [{ type: "command", command: gateCommand }] };
     return JSON.stringify({ hooks: { [on]: [entry] } }, null, 2);
 }
+/** What payload a dispatch kind must be handed to be able to decide at all. */
+function requiredPayload(kind) {
+    switch (kind) {
+        case "bash-gate":
+        case "file-gate":
+            return "tool";
+        case "prompt-gate":
+            return "prompt";
+        case "stop-gate":
+            return "stop";
+        // An inject or a react reads whatever the event carries; neither claims a
+        // field that might be absent, so neither constrains the payload.
+        case "inject":
+        case "react":
+            return undefined;
+    }
+}
+/** Whether this dispatch kind's whole purpose is a block decision. */
+function isGate(kind) {
+    return (kind === "bash-gate" ||
+        kind === "file-gate" ||
+        kind === "prompt-gate" ||
+        kind === "stop-gate");
+}
+function checkRoleEventFit(kind, on, hasMatcher, table) {
+    const verdict = (0, event_capability_js_1.capabilityOf)(table, on);
+    if (verdict.kind === "unknown")
+        return { kind: "unknown" };
+    const cap = verdict.capability;
+    const needs = requiredPayload(kind);
+    if (needs !== undefined && cap.carries !== needs) {
+        return {
+            kind: "dead",
+            message: `a ${kind} on \`${on}\` can never decide: the role reads the event's ` +
+                `${needs}, and ${on} carries ${cap.carries === "none" ? "nothing" : cap.carries}. ` +
+                `The field it reads is absent, so the hook runs and waves everything through.`,
+        };
+    }
+    if (hasMatcher && !cap.matcher) {
+        return {
+            kind: "dead",
+            message: `a tool matcher is meaningless on \`${on}\` — it carries ` +
+                `${cap.carries === "none" ? "nothing" : cap.carries}, not a tool, so the ` +
+                `matcher can match nothing and the hook never fires.`,
+        };
+    }
+    if (isGate(kind) && !cap.honours.includes("veto")) {
+        // The degraded case: it still reaches the model, it just does not block.
+        if (cap.honours.includes("feedback")) {
+            return {
+                kind: "degraded",
+                message: `\`${on}\` does not honour a veto — a deny there reaches the model as ` +
+                    `FEEDBACK after the action already happened. Fine as a nudge, but this ` +
+                    `is a ${kind}, so it stops nothing. Use a react, or gate on an event ` +
+                    `that vetoes.`,
+            };
+        }
+        return {
+            kind: "dead",
+            message: `a ${kind} on \`${on}\` blocks nothing: the event honours ` +
+                `${cap.honours.length === 0 ? "no channel at all" : cap.honours.join(", ")}, ` +
+                `so a deny is discarded silently — no veto, and no feedback to the model.`,
+        };
+    }
+    if (kind === "inject" && !cap.honours.includes("inject")) {
+        return {
+            kind: "dead",
+            message: `an inject on \`${on}\` reaches nobody — the event does not honour ` +
+                `additionalContext, so the text goes to the debug log.`,
+        };
+    }
+    return { kind: "ok" };
+}
 /**
  * Compile a hook program from its source. Runs the capability check FIRST (an
  * out-of-API import does NOT compile), validates the event against the target
@@ -761,6 +836,26 @@ function compileHookProgram(source, hook, opts = {}) {
     if (violations.length > 0) {
         throw new HookCompileError(`hook program uses capabilities outside \`${ALLOWED_IMPORT}\`: ${violations.join(", ")} — only the sanctioned API is allowed (capability = API surface).`);
     }
+    // A BARE gate is a Bash gate by construction — `hookRouting` emits the matcher
+    // `Bash` for it unconditionally, and `HookProgram` has no `match` field. So a
+    // `match` here is a field the author wrote and the compiler ignores, and the
+    // result is the WORST of the six measured fixtures (d): not a dead hook but a
+    // LIVE one guarding the wrong thing — `defineHook({match: tools("mcp__…")})`
+    // compiled to a matcher of `Bash`, asking on every shell command while the MCP
+    // call it was written for went straight through.
+    //
+    // `tsc` rejects the excess property, which is why this looked covered. It is
+    // not: a compiled hook is often `.mjs` (this repo's own two are), and
+    // `vigiles compile` does not run `tsc` at all — so for a JS author the type
+    // was never in the path. Same defect, different population; the rule the
+    // repo already states as prevent-at-stage-1 AND detect-at-stage-3.
+    if (!("role" in hook) && "match" in hook) {
+        throw new HookCompileError(`a bare hook gate is a BASH gate — it matches \`Bash\` by construction, so ` +
+            `the \`match\` you passed is ignored and the hook would guard shell ` +
+            `commands instead of what you named. For a file tool use ` +
+            `experimental_defineFileGate; for any other tool matcher use ` +
+            `experimental_defineReact, whose event carries the tool.`);
+    }
     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.
@@ -804,6 +899,13 @@ function compileHookProgram(source, hook, opts = {}) {
             throw new HookCompileError(fatal[0].message);
         }
     }
+    // …and an event the harness DOES fire can still be one this role cannot work
+    // on. Checked against the dialect's capability table; silent where the table
+    // has no row, so our gaps never become the author's error.
+    const fit = checkRoleEventFit(dispatchKind(hook), on, rawMatcher !== undefined, opts.dialect?.eventCapabilities);
+    if (fit.kind === "dead")
+        throw new HookCompileError(fit.message);
+    const fitWarnings = fit.kind === "degraded" ? [fit.message] : [];
     // A `needs` entry that isn't a built-in provider never resolves — reject it
     // (the typo-won't-compile guarantee, for JS authors the type can't reach).
     const needs = hookNeeds(hook);
@@ -830,6 +932,7 @@ function compileHookProgram(source, hook, opts = {}) {
         hooks: { [on]: [entry] },
         settingsBlock: renderSettingsBlock(on, matcher, gateCommand, opts.settingsFormat ?? "json"),
         stamp: stampHook(source),
+        ...(fitWarnings.length > 0 ? { warnings: fitWarnings } : {}),
     };
 }
 /** Stamp a hook's source (the integrity.ts pattern, applied to a hook artifact). */

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

@@ -40,11 +40,27 @@ export interface HookProtocol {
      * **which events honor it** — and encoding it here is what makes "this harness
      * can deliver an inject hook" a TESTED contract instead of an assumption. Both
      * Claude Code and Codex support the main lifecycle events (SessionStart,
-     * UserPromptSubmit, PostToolUse); a few (Stop, SubagentStop, PreCompact) carry
-     * no context on either. An empty list means the harness cannot inject context
-     * from a hook at all. Verified for Codex against the official hooks docs
+     * UserPromptSubmit, PreToolUse, PostToolUse); beyond that they DIVERGE, which
+     * is why this is a port and not a core constant: Claude Code also honors
+     * `Stop` (measured 2026-09-15 on 2.1.273, headless), Codex instead honors
+     * `SubagentStart`. An empty list means the harness cannot inject context from
+     * a hook at all. Verified for Codex against the official hooks docs
      * (developers.openai.com/codex/hooks). The conformance kit asserts a
      * shell-hook harness declares a non-empty set.
+     *
+     * ⚠️ This comment previously asserted that "a few (Stop, SubagentStop,
+     * PreCompact) carry no context on EITHER" harness. For Claude Code's `Stop`
+     * that was wrong, and the cost was structural rather than cosmetic: an
+     * unmeasured claim in a doc-comment became the runtime's emit gate, so three
+     * react hooks were reported undeliverable-by-vocabulary when the harness
+     * would have delivered them. A per-harness fact belongs in the adapter WITH
+     * its measurement; the residue (`SubagentStop`, `PreCompact`) stays unclaimed
+     * here rather than re-asserted.   *
+     * @deprecated Superseded by `HarnessDialect.eventCapabilities`
+     * (`honours: "inject"`), which is asserted to reproduce this list exactly. It
+     * lives on the DIALECT rather than here because three sibling event facts
+     * already did, and because the browser-side engine is handed a dialect and
+     * never a protocol. Kept for third-party adapters; goes in the next major.
      */
     readonly injectableEvents: readonly string[];
     /**

package/dist/core/instruction-weight.d.ts

@@ -0,0 +1,86 @@
+/**
+ * How heavy are the instructions this harness loads WITHOUT BEING ASKED — and
+ * what does the harness do when that is too much.
+ *
+ * WHY THIS IS NOT "the size of CLAUDE.md". Measured 2026-09-16 in a consumer
+ * repo: a 4 101-line root instruction file was "cut" to 2 665 lines by moving
+ * 225 837 characters of it into a sibling directory, and the cost of a request
+ * did not move at all — because the harness loads that directory
+ * unconditionally too. Splitting a file that is loaded either way relocates
+ * bytes; it does not remove them. So the number that matters is the SUM over
+ * everything loaded without a decision, and a per-file check silently INVITES
+ * the evasion (it rewards the split that changes nothing).
+ *
+ * WHY THE UNIT IS PER-HARNESS AND NOT TOKENS. The harnesses measure different
+ * things and neither gates on tokens:
+ *
+ *   - Claude Code counts CHARACTERS and WARNS ("Large file will impact
+ *     performance"); the instructions still reach the model.
+ *   - Codex counts BYTES (`project_doc_max_bytes`, default 32 KiB) and
+ *     TRUNCATES — silently. Its own source says so: "Maximum number of bytes of
+ *     the documentation that will be embedded. Larger files are *silently
+ *     truncated*" (openai/codex#7138, CLOSED AS NOT PLANNED, so this is the
+ *     standing behaviour rather than a bug in flight).
+ *
+ * That asymmetry is the whole point of reporting `onExceed`: over budget on
+ * Claude Code costs money and attention, over budget on Codex means some of
+ * your rules DO NOT EXIST for the model and nothing tells you which. The same
+ * number carries a different severity per harness, so the harness must supply
+ * it — hence a port field, not a constant.
+ *
+ * NOT A GATE, AND THAT IS MEASURED. Both corpora this was built against sit at
+ * roughly four times the Claude Code threshold. A rule that fails every real
+ * repo on day one is switched off on day one (`lint-rule-calibration`: severity
+ * tracks confidence, and a check nobody leaves on catches nothing). So the
+ * first consumer is `audit`, as a REPORT. It earns a severity when a corpus
+ * exists that it would not immediately fail.
+ */
+/** What the harness counts, and what it does when the count is exceeded. */
+export interface InstructionBudget {
+    /** Claude Code counts characters; Codex counts bytes. Never tokens. */
+    readonly unit: "chars" | "bytes";
+    /** The harness's own threshold, in `unit`. */
+    readonly limit: number;
+    /**
+     * `warns` — the instructions still reach the model (Claude Code).
+     * `truncates` — everything past the limit DOES NOT EXIST for the model, with
+     * no signal in the session (Codex). The difference is losing money versus
+     * losing rules.
+     */
+    readonly onExceed: "warns" | "truncates";
+    /** The vendor artifact this was read from, version included. */
+    readonly capturedFrom: string;
+    /**
+     * Globs the harness loads WITHOUT the user asking — the set the SUM is taken
+     * over. A file reachable only by an explicit read does not belong here; that
+     * is exactly the distinction the relocation trick exploits.
+     */
+    readonly alwaysLoaded: readonly string[];
+}
+/** One file's contribution, so a report can say WHERE the weight is. */
+export interface WeighedFile {
+    readonly path: string;
+    readonly size: number;
+}
+export interface InstructionWeight {
+    readonly unit: "chars" | "bytes";
+    readonly limit: number;
+    readonly onExceed: "warns" | "truncates";
+    /** Heaviest first — a report's first line should name the biggest payer. */
+    readonly files: readonly WeighedFile[];
+    /** The number that matters: everything loaded without a decision. */
+    readonly total: number;
+    /** `null` when within budget; otherwise how far over, in `unit`. */
+    readonly overBy: number | null;
+}
+/** Size in the harness's own unit. Bytes and chars differ on any non-ASCII text. */
+export declare function sizeIn(text: string, unit: "chars" | "bytes"): number;
+/**
+ * Weigh every unconditionally-loaded file in a file map.
+ *
+ * Takes a MAP rather than a directory so the same function serves the CLI and
+ * the browser engine (the `scan-files.ts` split), and so a test states its
+ * input instead of building a tree.
+ */
+export declare function weighInstructions(files: Readonly<Record<string, string>>, budget: InstructionBudget): InstructionWeight;
+//# sourceMappingURL=instruction-weight.d.ts.map

package/dist/core/instruction-weight.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * How heavy are the instructions this harness loads WITHOUT BEING ASKED — and
+ * what does the harness do when that is too much.
+ *
+ * WHY THIS IS NOT "the size of CLAUDE.md". Measured 2026-09-16 in a consumer
+ * repo: a 4 101-line root instruction file was "cut" to 2 665 lines by moving
+ * 225 837 characters of it into a sibling directory, and the cost of a request
+ * did not move at all — because the harness loads that directory
+ * unconditionally too. Splitting a file that is loaded either way relocates
+ * bytes; it does not remove them. So the number that matters is the SUM over
+ * everything loaded without a decision, and a per-file check silently INVITES
+ * the evasion (it rewards the split that changes nothing).
+ *
+ * WHY THE UNIT IS PER-HARNESS AND NOT TOKENS. The harnesses measure different
+ * things and neither gates on tokens:
+ *
+ *   - Claude Code counts CHARACTERS and WARNS ("Large file will impact
+ *     performance"); the instructions still reach the model.
+ *   - Codex counts BYTES (`project_doc_max_bytes`, default 32 KiB) and
+ *     TRUNCATES — silently. Its own source says so: "Maximum number of bytes of
+ *     the documentation that will be embedded. Larger files are *silently
+ *     truncated*" (openai/codex#7138, CLOSED AS NOT PLANNED, so this is the
+ *     standing behaviour rather than a bug in flight).
+ *
+ * That asymmetry is the whole point of reporting `onExceed`: over budget on
+ * Claude Code costs money and attention, over budget on Codex means some of
+ * your rules DO NOT EXIST for the model and nothing tells you which. The same
+ * number carries a different severity per harness, so the harness must supply
+ * it — hence a port field, not a constant.
+ *
+ * NOT A GATE, AND THAT IS MEASURED. Both corpora this was built against sit at
+ * roughly four times the Claude Code threshold. A rule that fails every real
+ * repo on day one is switched off on day one (`lint-rule-calibration`: severity
+ * tracks confidence, and a check nobody leaves on catches nothing). So the
+ * first consumer is `audit`, as a REPORT. It earns a severity when a corpus
+ * exists that it would not immediately fail.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sizeIn = sizeIn;
+exports.weighInstructions = weighInstructions;
+/** Size in the harness's own unit. Bytes and chars differ on any non-ASCII text. */
+function sizeIn(text, unit) {
+    return unit === "chars" ? text.length : Buffer.byteLength(text, "utf8");
+}
+/**
+ * Match a path against one glob. Deliberately tiny: the patterns here are
+ * `alwaysLoaded` entries an ADAPTER writes, not user input — `CLAUDE.md`,
+ * `.claude/rules/**`. `*` stops at a separator, `**` crosses them.
+ */
+function matchesGlob(path, glob) {
+    const rx = glob
+        .split(/(\*\*\/|\*\*|\*)/)
+        .map((part) => part === "**/"
+        ? "(?:.*/)?"
+        : part === "**"
+            ? ".*"
+            : part === "*"
+                ? "[^/]*"
+                : part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join("");
+    return new RegExp(`^${rx}$`).test(path);
+}
+/**
+ * Weigh every unconditionally-loaded file in a file map.
+ *
+ * Takes a MAP rather than a directory so the same function serves the CLI and
+ * the browser engine (the `scan-files.ts` split), and so a test states its
+ * input instead of building a tree.
+ */
+function weighInstructions(files, budget) {
+    const weighed = Object.entries(files)
+        .filter(([path]) => budget.alwaysLoaded.some((g) => matchesGlob(path, g)))
+        .map(([path, text]) => ({ path, size: sizeIn(text, budget.unit) }))
+        .sort((a, b) => b.size - a.size || a.path.localeCompare(b.path));
+    const total = weighed.reduce((sum, f) => sum + f.size, 0);
+    return {
+        unit: budget.unit,
+        limit: budget.limit,
+        onExceed: budget.onExceed,
+        files: weighed,
+        total,
+        overBy: total > budget.limit ? total - budget.limit : null,
+    };
+}
+//# sourceMappingURL=instruction-weight.js.map

package/dist/core/linters.js

@@ -36,7 +36,6 @@ exports.parseGolangciEnabledLinters = parseGolangciEnabledLinters;
 exports.clearCedarCache = clearCedarCache;
 exports.checkLinterRule = checkLinterRule;
 const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const edit_distance_js_1 = require("./edit-distance.js");
 Object.defineProperty(exports, "editDistance", { enumerable: true, get: function () { return edit_distance_js_1.editDistance; } });
@@ -72,6 +71,7 @@ function augmentToolPath() {
     }
 }
 augmentToolPath();
+const tmp_root_js_1 = require("./tmp-root.js");
 // ---------------------------------------------------------------------------
 // Parsing enforcement references
 // ---------------------------------------------------------------------------
@@ -267,7 +267,7 @@ function getDetektDefaultRules() {
     if (DETEKT_DEFAULT_RULE_CACHE)
         return DETEKT_DEFAULT_RULE_CACHE;
     let rules = new Set();
-    const tmp = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-detekt-"));
+    const tmp = (0, tmp_root_js_1.makeTmpDir)("detekt");
     try {
         const target = (0, node_path_1.join)(tmp, "generated-default.yml");
         (0, node_child_process_1.execSync)(`detekt --generate-config --config ${target}`, {
@@ -481,7 +481,7 @@ function runCheckstyleProbe(configPath, probePath) {
  * either placement instantiates.
  */
 function checkstyleModuleInstantiates(ruleName) {
-    const tmp = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-checkstyle-"));
+    const tmp = (0, tmp_root_js_1.makeTmpDir)("checkstyle");
     try {
         const probe = (0, node_path_1.join)(tmp, "Probe.java");
         (0, node_fs_1.writeFileSync)(probe, "class Probe {}\n");

package/dist/core/test-utils.d.ts

@@ -1,6 +1,5 @@
 import type { ClaudeSpec } from "./spec.js";
-export declare function makeTmpDir(suffix?: string): string;
-export declare function cleanupTmpDir(dir: string): void;
+export { makeTmpDir, cleanupTmpDir } from "./tmp-root.js";
 export declare function makeSpec(overrides?: Partial<ClaudeSpec>): ClaudeSpec;
 declare function git(cwd: string, cmd: string): string;
 export declare function initGitRepo(dir: string): void;

package/dist/core/test-utils.js

@@ -1,20 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.makeTmpDir = makeTmpDir;
-exports.cleanupTmpDir = cleanupTmpDir;
+exports.cleanupTmpDir = exports.makeTmpDir = void 0;
 exports.makeSpec = makeSpec;
 exports.initGitRepo = initGitRepo;
 exports.git = git;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const node_os_1 = require("node:os");
 const node_child_process_1 = require("node:child_process");
-function makeTmpDir(suffix = "test") {
-    return (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), `vigiles-${suffix}-`));
-}
-function cleanupTmpDir(dir) {
-    (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
-}
+// Re-exported, not redefined: the temp root lives in `tmp-root.ts` because the
+// runtime modules that need one must not pull in `makeSpec`/`initGitRepo` and
+// their dependencies. One definition, two doors.
+var tmp_root_js_1 = require("./tmp-root.js");
+Object.defineProperty(exports, "makeTmpDir", { enumerable: true, get: function () { return tmp_root_js_1.makeTmpDir; } });
+Object.defineProperty(exports, "cleanupTmpDir", { enumerable: true, get: function () { return tmp_root_js_1.cleanupTmpDir; } });
 function makeSpec(overrides) {
     return {
         _specType: "claude",

package/dist/core/tmp-root.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Create a temporary directory and return the path with every symlink resolved.
+ *
+ * The `realpathSync` wrapper is the whole point: it must stay OUTSIDE
+ * `mkdtempSync`, because the directory has to exist before it can be resolved.
+ *
+ * @param suffix distinguishes roots in a listing; the name is `vigiles-<suffix>-*`
+ */
+export declare function makeTmpDir(suffix?: string): string;
+/** Remove a root made by {@link makeTmpDir}. Safe on a path that is already gone. */
+export declare function cleanupTmpDir(dir: string): void;
+//# sourceMappingURL=tmp-root.d.ts.map

package/dist/core/tmp-root.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeTmpDir = makeTmpDir;
+exports.cleanupTmpDir = cleanupTmpDir;
+/**
+ * The ONE way to make a temporary fixture root, with its symlinks resolved.
+ *
+ * ── THE TRAP THIS EXISTS TO ABOLISH (issue #241, measured) ──────────────────────
+ * On macOS `os.tmpdir()` returns a path under `/var/folders/…`, and `/var` is
+ * itself a symlink to `/private/var`. Node resolves a module's own URL to the
+ * REALPATH but leaves `process.argv[1]`, and any path a test composed itself,
+ * exactly as typed. A fixture built under `tmpdir()` therefore carries two
+ * spellings of one directory, and anything comparing them is red on macOS and
+ * green on Linux:
+ *
+ *     const d = mkdtempSync(join(tmpdir(), "probe-"));
+ *     // import.meta.url → "file:///private/var/folders/…/probe.mjs"
+ *     // process.argv[1] → "/var/folders/…/probe.mjs"
+ *
+ * A consumer hit that three times in one suite: a resolver's return value against
+ * a composed expectation, an `isMain` control case, and a git fixture whose
+ * repository root git reported realpath'd while the relative path was computed
+ * against the other spelling (`zernie/research-paper-pipeline#9`).
+ *
+ * 🔴 WHY A SHIPPED HELPER AND NOT THREE FIXED CALL SITES. Those call sites were
+ * hand-rolled because the product shipped nothing to roll: `mkdtempSync(join(
+ * tmpdir(), …))` is the shape a harness author reaches for, and it is the shape
+ * that carries the trap. Fixing our own sites leaves every future author to
+ * rediscover it. So this is exported from the harness surface (`vigiles`), where
+ * `recordCheck` and `skip` already live.
+ *
+ * 🔴 WHY ITS OWN MODULE. `core/test-utils.ts` also carries `makeSpec` and
+ * `initGitRepo`, which pull in spec types and `execSync`; the runtime modules
+ * that need a temp root must not drag those in. `test-utils` re-exports these two
+ * so existing imports keep working, and there is still exactly one definition.
+ *
+ * ⚠️ On Linux `realpathSync` is the identity here, so no behavioural test on this
+ * platform can hold the fix in place. What holds it is the regression test beside
+ * this file, which builds its own symlink rather than relying on the platform's.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+/**
+ * Create a temporary directory and return the path with every symlink resolved.
+ *
+ * The `realpathSync` wrapper is the whole point: it must stay OUTSIDE
+ * `mkdtempSync`, because the directory has to exist before it can be resolved.
+ *
+ * @param suffix distinguishes roots in a listing; the name is `vigiles-<suffix>-*`
+ */
+function makeTmpDir(suffix = "test") {
+    return (0, node_fs_1.realpathSync)((0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), `vigiles-${suffix}-`)));
+}
+/** Remove a root made by {@link makeTmpDir}. Safe on a path that is already gone. */
+function cleanupTmpDir(dir) {
+    (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+}
+//# sourceMappingURL=tmp-root.js.map

package/dist/core/vocabulary-consistency.js

@@ -22,17 +22,27 @@ function dialectVocabularyProblems(dialect) {
     // A block-semantics subset that names an event the dialect doesn't fire is a
     // rule about nothing.
     const events = new Set(dialect.hookEvents);
+    // 🔴 READ THE DECLARED FIELDS, not the effective answer. This check is about
+    // junk IN a dialect's own declarations, so routing it through the
+    // capability-table readers (which prefer the table) made it stop looking at
+    // the very field it polices — caught by `vocabulary.test.ts` the moment the
+    // Claude Code dialect gained a table. The readers are for CONSUMERS asking
+    // "what does this harness do?"; a consistency check is not one of those.
+    /* eslint-disable @typescript-eslint/no-deprecated -- policing the legacy
+       fields themselves is this function's entire job. */
     for (const [field, list] of [
         ["noEffectHookEvents", dialect.noEffectHookEvents ?? []],
         [
             "permissionDecisionHookEvents",
             dialect.permissionDecisionHookEvents ?? [],
         ],
+        ["eventCapabilities", Object.keys(dialect.eventCapabilities?.events ?? {})],
     ])
         for (const event of list)
             if (!events.has(event))
                 problems.push(`hook event "${event}" is in ${field} but not in hookEvents — ` +
                     `it describes an event this dialect says never fires`);
+    /* eslint-enable @typescript-eslint/no-deprecated */
     return problems;
 }
 /**

package/dist/eval.js

@@ -84,6 +84,7 @@ const check_count_js_1 = require("./check-count.js");
 const coverage_probe_js_1 = require("./coverage-probe.js");
 const tool_intercept_js_1 = require("./tool-intercept.js");
 const tool_stub_js_1 = require("./tool-stub.js");
+const tmp_root_js_1 = require("./core/tmp-root.js");
 function writeFiles(cwd, files) {
     for (const [p, content] of Object.entries(files)) {
         const full = (0, node_path_1.resolve)(cwd, p);
@@ -650,7 +651,7 @@ function whichSkillsFired(trace) {
  * falls out of one pass over the prompts (N× cheaper than re-running per pair).
  */
 async function runSkillSelectionTrial(args) {
-    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-selection-"));
+    const cwd = (0, tmp_root_js_1.makeTmpDir)("selection");
     try {
         if (args.fixture)
             writeFiles(cwd, args.fixture);
@@ -1008,7 +1009,7 @@ function seedEphemeralHome(throwawayHome, realHome, keep = exports.EPHEMERAL_HOM
 }
 /** Execute one trial in a fresh sandbox; returns its metric row + usage. */
 async function executeTrial(spec, arm, trialIndex, runner, cfg) {
-    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-eval-"));
+    const cwd = (0, tmp_root_js_1.makeTmpDir)("eval");
     try {
         const resolved = (0, plugin_loader_js_1.resolveHarness)({
             plugin: arm.plugin,
@@ -1456,7 +1457,7 @@ function packageSkillsDir(skillsDir, opts = {}) {
     const abs = (0, node_path_1.resolve)(skillsDir);
     if (!(0, node_fs_1.existsSync)(abs))
         throw new Error(`skillsDir not found: ${skillsDir} (resolved ${abs})`);
-    const root = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-skills-"));
+    const root = (0, tmp_root_js_1.makeTmpDir)("skills");
     (0, node_fs_1.mkdirSync)((0, node_path_1.join)(root, ".claude-plugin"), { recursive: true });
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"), JSON.stringify({ name: opts.name ?? "vigiles-loose-skills", version: "0.0.0" }, null, 2));
     const skillsOut = (0, node_path_1.join)(root, "skills");
@@ -1649,7 +1650,7 @@ function copySkillsInto(src, skillsOut, stub, present) {
  * dir. Pure (filesystem only).
  */
 function packageInstallSet(opts) {
-    const root = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-harness-"));
+    const root = (0, tmp_root_js_1.makeTmpDir)("harness");
     try {
         (0, node_fs_1.mkdirSync)((0, node_path_1.join)(root, ".claude-plugin"), { recursive: true });
         (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"), JSON.stringify({ name: opts.name, version: "0.0.0" }, null, 2));
@@ -1737,7 +1738,7 @@ function resolveTriggerPluginDir(spec) {
 /** Run one prompt set × trials through `runner`, aggregating fired counts. */
 /** Run one trigger trial in a throwaway cwd (fixture seeded) → fired 0/1. */
 async function runTriggerTrial(prompt, cfg, runner) {
-    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-trigger-"));
+    const cwd = (0, tmp_root_js_1.makeTmpDir)("trigger");
     try {
         if (cfg.fixture)
             writeFiles(cwd, cfg.fixture);

package/dist/harness-test.js

@@ -43,7 +43,6 @@ exports.runHarness = runHarness;
  */
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const adapter_conformance_js_1 = require("./adapter-conformance.js");
 const check_count_js_1 = require("./check-count.js");
@@ -61,6 +60,7 @@ var sandbox_js_2 = require("./sandbox.js");
 Object.defineProperty(exports, "decideSandbox", { enumerable: true, get: function () { return sandbox_js_2.decideSandbox; } });
 Object.defineProperty(exports, "specTrusted", { enumerable: true, get: function () { return sandbox_js_2.specTrusted; } });
 Object.defineProperty(exports, "sandboxAvailable", { enumerable: true, get: function () { return sandbox_js_2.sandboxAvailable; } });
+const tmp_root_js_1 = require("./core/tmp-root.js");
 function contentText(content) {
     if (typeof content === "string")
         return content;
@@ -443,7 +443,7 @@ async function runHarnessTest(spec, opts = {}) {
     if (decision.action === "sandbox" && !isClaudeCode) {
         throw new Error(`sandbox not supported for ${driver.runtime.name}: confined execution is Claude Code only. Pass sandbox: false to run ${driver.runtime.name} unconfined (you audited the code, or trust the outer container).`);
     }
-    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-harness-"));
+    const cwd = (0, tmp_root_js_1.makeTmpDir)("harness");
     const { files, settings } = (0, plugin_loader_js_1.resolveHarness)({
         plugin: spec.plugin,
         settings: spec.settings,

package/dist/hook-install.d.ts

@@ -17,7 +17,7 @@ interface HookEntry {
 /** The CC-shaped structured block a compiled hook program carries. */
 export type CompiledHooks = Record<string, readonly HookEntry[]>;
 interface SettingsJson {
-    hooks?: Record<string, HookEntry[]>;
+    hooks?: Readonly<Record<string, readonly HookEntry[]>>;
     [k: string]: unknown;
 }
 /**
@@ -58,17 +58,19 @@ export declare function normalizeHookRef(hookPath: string, cwd?: string): string
 export declare function hookGateRef(ref: string, projectRootTokens: readonly string[] | undefined): string;
 /**
  * Idempotently merge a compiled hook's block into an existing `settings.json`
- * object. Entries managed by THIS hook file (the runtime command references
- * `hookPath`) are replaced; every unrelated entry — including the user's own
- * hand-written hooks — is preserved.
+ * object. Commands managed by THIS hook file (the runtime command references
+ * `hookPath`) are replaced; every unrelated command — including the user's own
+ * hand-written hooks SHARING A MATCHER BLOCK with ours — is preserved. See
+ * {@link withoutHookCommands} for why the granularity is the command and not
+ * the entry.
  */
 export declare function mergeHooksJson(existing: SettingsJson, compiled: CompiledHooks, hookPath: string): SettingsJson;
 interface TomlHookEntry {
-    matcher?: string;
-    command: string;
+    readonly matcher?: string;
+    readonly command: string;
 }
 interface ConfigToml {
-    hooks?: Record<string, TomlHookEntry[]>;
+    hooks?: Readonly<Record<string, readonly TomlHookEntry[]>>;
     [k: string]: unknown;
 }
 /** The TOML sibling of {@link mergeHooksJson} (Codex `[[hooks.<event>]]`). */