vigiles 6.0.0 → 7.0.0

package/dist/cli.js

@@ -15,6 +15,7 @@ const node_path_1 = require("node:path");
 const glob_1 = require("glob");
 const generate_types_js_1 = require("./core/generate-types.js");
 const generate_harness_js_1 = require("./core/generate-harness.js");
+const capability_diff_js_1 = require("./core/capability-diff.js");
 const validate_js_1 = require("./core/validate.js");
 const cli_flags_js_1 = require("./cli-flags.js");
 const setup_plan_js_1 = require("./setup-plan.js");
@@ -23,6 +24,7 @@ const test_coverage_js_1 = require("./test-coverage.js");
 const scaffold_test_js_1 = require("./scaffold-test.js");
 const effects_js_1 = require("./core/effects.js");
 const scan_js_1 = require("./scan.js");
+const dialect_drift_js_1 = require("./dialect-drift.js");
 const score_explainer_js_1 = require("./score-explainer.js");
 const scan_behavioral_js_1 = require("./scan-behavioral.js");
 const adapter_registry_js_1 = require("./adapter-registry.js");
@@ -37,6 +39,11 @@ const generate_schema_js_1 = require("./core/generate-schema.js");
 const compose_js_1 = require("./core/compose.js");
 const compile_generator_js_1 = require("./core/compile-generator.js");
 const action_gate_js_1 = require("./action-gate.js");
+const guards_js_1 = require("./core/guards.js");
+const hook_program_js_1 = require("./core/hook-program.js");
+const hook_install_js_1 = require("./hook-install.js");
+const hook_providers_js_1 = require("./core/hook-providers.js");
+const toml_1 = require("@iarna/toml");
 const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
 const effect_region_js_1 = require("./adapters/claude-code/effect-region.js");
 const tool_intercept_js_1 = require("./tool-intercept.js");
@@ -871,7 +878,7 @@ async function runLint(restArgs, flags, config) {
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
     const silent = summary || json;
-    const files = findInstructionFiles(restArgs);
+    const files = findInstructionFiles(restArgs, config?.exclude);
     // Resolve the active harness ONCE so the harness-specific checks below run
     // against the right adapter's dialect (tool/event catalogs) and surfaces —
     // not a hard-coded Claude Code default. A subagent-surface rule reports n/a
@@ -2441,13 +2448,19 @@ async function countGuidanceRules(silent = false) {
 // ---------------------------------------------------------------------------
 // Command handlers for main()
 // ---------------------------------------------------------------------------
-function findInstructionFiles(restArgs) {
+function findInstructionFiles(restArgs, exclude = []) {
     if (restArgs.length > 0)
         return restArgs;
     const patterns = ["**/CLAUDE.md", "**/AGENTS.md", "**/SKILL.md"];
     const files = [];
     for (const pattern of patterns) {
-        files.push(...(0, glob_1.globSync)(pattern, { ignore: IGNORE_NODE_MODULES, cwd: process.cwd() }));
+        files.push(...(0, glob_1.globSync)(pattern, {
+            // `exclude` (from .vigilesrc.json) drops vendored/benchmark fixtures the
+            // repo's own lint shouldn't police — a third-party CLAUDE.md isn't held
+            // to require-spec. node_modules/dist/.git stay always-excluded.
+            ignore: [...IGNORE_NODE_MODULES, "dist/**", ".git/**", ...exclude],
+            cwd: process.cwd(),
+        }));
     }
     return files;
 }
@@ -2456,14 +2469,26 @@ function flagValue(args, name) {
     return args.find((a) => a.startsWith(`${name}=`))?.slice(name.length + 1);
 }
 /**
- * The `scan --trigger` behavioral column: load the author-supplied per-skill
- * prompt sets, probe the plugin's model-invocable skills, print the column.
- * Model-gated and opt-in — the structural scan above stays deterministic.
+ * `vigiles measure <dir>` — the MODEL-GATED behavioral report on a plugin (the paid
+ * tier; `scan` stays free/deterministic). Loads the author-supplied per-skill prompt
+ * sets (`--prompts`) and reports BOTH behavioral columns: trigger-rate (does each
+ * skill actually FIRE — recall + precision) and the selection-collision matrix (does
+ * one skill HIJACK a sibling's prompt — the behavioral confirmation of the
+ * deterministic `description-overlap` rule). Needs the harness CLI + model auth;
+ * degrades honestly ("unavailable") when absent. The OSS-testing front door:
+ * `vigiles measure ./plugin --prompts=p.json`.
  */
-async function handleScanTrigger(root, args, json, harness) {
+async function handleMeasure(restArgs, args) {
+    const dir = (0, node_path_1.resolve)(restArgs[0] ?? ".");
+    const json = args.includes("--json");
+    const harnessFlag = harnessFlagFrom(args);
+    const adapter = harnessFlag
+        ? (0, adapter_registry_js_1.resolveAdapter)(dir, harnessFlag)
+        : (0, adapter_registry_js_1.detectAdapterResult)(dir).adapter;
+    const harness = adapter.name === "codex" ? "codex" : "claude-code";
     const promptsPath = flagValue(args, "--prompts");
     if (!promptsPath) {
-        console.error("scan --trigger needs --prompts=<file.json> (a map of skill name → { prompts, irrelevant }).");
+        console.error("measure needs --prompts=<file.json> (a map of skill name → { prompts, irrelevant }).");
         process.exitCode = 2;
         return;
     }
@@ -2472,21 +2497,37 @@ async function handleScanTrigger(root, args, json, harness) {
         promptSet = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(promptsPath), "utf-8"));
     }
     catch (e) {
-        console.error(`scan --trigger: could not read --prompts file "${promptsPath}": ${e instanceof Error ? e.message : String(e)}`);
+        console.error(`measure: could not read --prompts file "${promptsPath}": ${e instanceof Error ? e.message : String(e)}`);
         process.exitCode = 2;
         return;
     }
-    const concurrencyRaw = flagValue(args, "--concurrency");
-    const minPromptsRaw = flagValue(args, "--min-prompts");
-    const report = await (0, scan_behavioral_js_1.probePluginTriggers)(root, promptSet, {
-        concurrency: concurrencyRaw ? Number(concurrencyRaw) : undefined,
-        minPrompts: minPromptsRaw ? Number(minPromptsRaw) : undefined,
-        model: flagValue(args, "--model"),
+    const num = (f) => {
+        const v = flagValue(args, f);
+        return v ? Number(v) : undefined;
+    };
+    const model = flagValue(args, "--model");
+    const concurrency = num("--concurrency");
+    // Trigger-rate (recall + precision) AND the selection-collision matrix — the two
+    // behavioral columns, one report. Collisions report n/a where they don't apply
+    // (a single skill, or Codex — no skill-selection event), never a false pass.
+    const trigger = await (0, scan_behavioral_js_1.probePluginTriggers)(dir, promptSet, {
+        concurrency,
+        minPrompts: num("--min-prompts"),
+        model,
         harness,
     });
-    console.log(json
-        ? JSON.stringify(report, null, 2)
-        : `\n${(0, scan_behavioral_js_1.formatBehavioralReport)(report)}`);
+    const collisions = await (0, scan_behavioral_js_1.measurePluginSelection)(dir, promptSet, {
+        concurrency,
+        trials: num("--trials"),
+        model,
+        harness,
+    });
+    if (json) {
+        console.log(JSON.stringify({ trigger, collisions }, null, 2));
+        return;
+    }
+    console.log(`\n${(0, scan_behavioral_js_1.formatBehavioralReport)(trigger)}`);
+    console.log(`\n${(0, scan_behavioral_js_1.formatSelectionReport)(collisions)}`);
 }
 function handleGenerateTypes(args, restArgs) {
     const checkOnly = args.includes("--check");
@@ -2738,6 +2779,19 @@ function handleExplain(restArgs, args) {
         console.log(`Explaining "${surface}":\n`);
     console.log((0, score_explainer_js_1.formatExplanations)(exps));
 }
+/**
+ * Whole-harness capability lattice from a scanned plugin's agents (no `tools:` line →
+ * inherits-all). The substrate `scan --capability-diff` diffs. Reused for both the
+ * already-scanned "after" report and the freshly-scanned "before" dir.
+ */
+function capabilitiesOfReport(report, dialect) {
+    const agents = report.agents.map((a) => ({
+        name: a.name,
+        tools: a.tools ?? undefined,
+        file: a.path,
+    }));
+    return (0, generate_harness_js_1.computeHarnessCapabilities)(agents, dialect);
+}
 /**
  * The plugin's declared name for the namespaced skill id, read from the layout's
  * manifest (adapter-aware path, not a hardcoded `.claude-plugin/`), falling back to
@@ -2874,6 +2928,8 @@ function printUsage(command) {
     console.log("  vigiles init [flags]           Setup project (--lint, --test, --harness=, --strict, --no-gha, --force)");
     console.log("  vigiles compile [files...]     Compile .spec.ts → .md");
     console.log("  vigiles lint [files...]        Verify references, find gaps in instruction files");
+    console.log("  vigiles scan [dir...]          Report what a plugin ships + what's broken (free; 2+ dirs → leaderboard)");
+    console.log("  vigiles measure <dir>          Model-gated: does each skill FIRE / COLLIDE? (--prompts=, real model)");
     console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
     console.log("  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N, --min=N, --no-skip)");
     console.log("  vigiles explain <dir> [name]   Deterministic WHY a skill/agent underperforms + the fix (--json, --harness=)");
@@ -2928,7 +2984,7 @@ function annotateLintForGitHub(report, flags) {
  */
 function runSkillCommand(target) {
     if (!target) {
-        console.error("Usage: vigiles run-skill <SKILL.md>");
+        console.error("Usage: vigiles hook-runtime run-skill <SKILL.md>");
         process.exit(2);
     }
     const path = (0, node_path_1.resolve)(process.cwd(), target);
@@ -2983,7 +3039,7 @@ function skillHookCommand() {
 /** Mark a skill active so the Stop hook enforces its result gate. */
 function skillStartCommand(target) {
     if (!target) {
-        console.error("Usage: vigiles skill-start <SKILL.md>");
+        console.error("Usage: vigiles hook-runtime skill-start <SKILL.md>");
         process.exit(2);
     }
     (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
@@ -3056,26 +3112,29 @@ function agentHookCommand() {
         /* malformed input → no tool, allow */
     }
     const cwd = process.cwd();
-    // EXPERIMENTAL (parked P3, flat-only — do NOT auto-wire): the Task/SubagentStop
-    // bracketing below assumes one active subagent at a time and is NOT nesting-safe
-    // (CC v2.1.172 depth-5 nesting needs a stack + spawn-tool-name check). See
-    // research/effect-boundary-design.md.
-    // SubagentStop → CLOSE the window deterministically (no model `agent-done`):
-    // the subagent returned, so its contract/purity no longer apply.
+    // EXPERIMENTAL (parked P3 — do NOT auto-wire). The spawn/SubagentStop bracketing
+    // is now nesting-safe: a depth-aware STACK (push on dispatch, POP on SubagentStop)
+    // closes the contract-escape the flat single-slot model allowed under CC v2.1.172
+    // depth-5 nesting. See research/effect-boundary-design.md + AgentWindowStack.tla.
+    //
+    // SubagentStop → CLOSE the window deterministically (no model `agent-done`): the
+    // subagent returned, so POP its frame — control returns to its PARENT, whose
+    // contract the gate enforces again (NOT a full clear, which would drop the parent).
     if (event === "SubagentStop") {
-        (0, agent_runtime_js_1.clearActiveAgent)(cwd);
+        (0, agent_runtime_js_1.popActiveAgent)(cwd);
         (0, effect_region_js_1.clearEffectActive)(cwd);
         return;
     }
-    // PreToolUse(Task) → OPEN the window deterministically (no model `agent-start`
-    // / `effect-enter`): the parent is dispatching a subagent, so activate that
-    // subagent's compiled contract for the tool calls it is about to make. The
-    // Task dispatch itself is the PARENT's action — don't gate it against the
-    // subagent's contract; just open the window and allow.
-    if (tool === "Task") {
+    // PreToolUse(spawn) → OPEN the window deterministically (no model `agent-start` /
+    // `effect-enter`): the parent is dispatching a subagent, so PUSH that subagent's
+    // compiled contract for the tool calls it is about to make. Recognize both spawn
+    // tool names — `Task` (top-level dispatch) and `Agent` (nested-spawn, CC v2.1.172)
+    // — gated on a resolvable `subagent_type` so a non-spawn call never opens a frame.
+    // The dispatch itself is the PARENT's action — don't gate it; just open + allow.
+    if (tool === "Task" || tool === "Agent") {
         const agentPath = (0, agent_runtime_js_1.decideTaskDispatch)(toolInput, cwd, process.env.CLAUDE_PLUGIN_ROOT);
         if (agentPath) {
-            (0, agent_runtime_js_1.setActiveAgent)(cwd, agentPath);
+            (0, agent_runtime_js_1.pushActiveAgent)(cwd, agentPath);
             (0, effect_region_js_1.setEffectActive)(cwd);
         }
         return;
@@ -3089,7 +3148,7 @@ function agentHookCommand() {
     }
 }
 /**
- * `vigiles intercept-tool-hook` — the PreToolUse interception hook for the
+ * `vigiles hook-runtime intercept-tool` — the PreToolUse interception hook for the
  * tool-call spy. Reads the intercept list from `VIGILES_INTERCEPT_TOOLS`, decides
  * whether the called tool should be intercepted, and if so denies the real
  * execution (exit 2) with a block message — the call is intercepted (prevented),
@@ -3112,63 +3171,99 @@ function interceptToolHookCommand() {
         process.exit(2);
     }
 }
+/**
+ * `vigiles hook-runtime guard` — the PreToolUse gate for typed safe-by-construction guards
+ * (EXPERIMENTAL). Reads the live event on stdin, runs the declared guard set
+ * (`.vigiles/guards.json`) against the session ledger (`.vigiles/guard-ledger.json`),
+ * and blocks (exit 2 + reason) or records the allowed call. The command in the
+ * generated hooks block IS this gate — not user shell — so the enforcement is
+ * safe-by-construction. See src/core/guards.ts.
+ */
+function guardHookCommand() {
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    const { decision } = (0, guards_js_1.runGuardHook)(process.cwd(), raw);
+    if (!decision.allow) {
+        console.error(decision.reason ?? "Blocked by a vigiles guard.");
+        process.exit(2);
+    }
+}
 /** Mark a subagent active so the PreToolUse hook enforces its tool contract. */
 function agentStartCommand(target) {
     if (!target) {
-        console.error("Usage: vigiles agent-start <agents/<name>.md>");
+        console.error("Usage: vigiles hook-runtime agent-start <agents/<name>.md>");
         process.exit(2);
     }
-    (0, agent_runtime_js_1.setActiveAgent)(process.cwd(), target);
+    (0, agent_runtime_js_1.pushActiveAgent)(process.cwd(), target);
     console.log(`Active agent: ${target}`);
 }
 /** Dispatch the skill-runtime subcommands. Returns false if unrecognized. */
-function handleSkillCommand(command, restArgs) {
-    switch (command) {
-        case "run-skill":
-            runSkillCommand(restArgs[0]);
-            return true;
+/**
+ * `vigiles hook-runtime <kind> [args]` — the hidden umbrella for RUNTIME
+ * entrypoints: the executables the harness invokes via a block `vigiles compile`
+ * emits into your hooks config, NEVER typed by a human. They stay off the help
+ * surface by design — verbs are typed, runtime entrypoints are emitted (the
+ * cohesive-cli-surface rule). Renaming a `<kind>` breaks every already-emitted
+ * block, so it is a breaking change.
+ */
+async function handleHookRuntime(kind, restArgs) {
+    switch (kind) {
+        case "run-program":
+            await runHookProgramCommand(restArgs[0]);
+            return;
+        case "agent":
+            agentHookCommand();
+            return;
+        case "agent-start":
+            agentStartCommand(restArgs[0]);
+            return;
+        case "agent-done":
+            (0, agent_runtime_js_1.popActiveAgent)(process.cwd());
+            return;
+        case "skill":
+            skillHookCommand();
+            return;
+        case "skill-tool":
+            skillToolHookCommand();
+            return;
         case "skill-start":
             skillStartCommand(restArgs[0]);
-            return true;
+            return;
         case "skill-done":
             (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
-            return true;
-        case "skill-hook":
-            skillHookCommand();
-            return true;
-        case "skill-tool-hook":
-            skillToolHookCommand();
-            return true;
-        case "agent-start":
-            agentStartCommand(restArgs[0]);
-            return true;
-        case "agent-done":
-            (0, agent_runtime_js_1.clearActiveAgent)(process.cwd());
-            return true;
-        case "agent-hook":
-            agentHookCommand();
-            return true;
-        case "intercept-tool-hook":
+            return;
+        case "run-skill":
+            runSkillCommand(restArgs[0]);
+            return;
+        case "intercept-tool":
             interceptToolHookCommand();
-            return true;
-        case "action-hook":
+            return;
+        case "guard":
+            guardHookCommand();
+            return;
+        case "action":
             actionHookCommand();
-            return true;
+            return;
         case "refs":
-            refsCommand(restArgs[0]);
-            return true;
-        case "refs-hook":
             refsHookCommand();
-            return true;
+            return;
         case "effect-enter":
             (0, effect_region_js_1.setEffectActive)(process.cwd());
             console.log("Effect boundary entered.");
-            return true;
+            return;
         case "effect-exit":
             (0, effect_region_js_1.clearEffectActive)(process.cwd());
-            return true;
+            return;
         default:
-            return false;
+            console.error(`vigiles hook-runtime: unknown runtime entrypoint "${kind ?? ""}". ` +
+                `These are emitted into your hooks config by \`vigiles compile\` — ` +
+                `you don't run them by hand.`);
+            process.exit(2);
     }
 }
 /**
@@ -3301,6 +3396,378 @@ function refsHookCommand() {
         },
     }) + "\n");
 }
+// ---------------------------------------------------------------------------
+// Compiled hooks (`vigiles/hook`) — author a hook as a pure typed program,
+// compile it to a harness block, run it as the hooks-block command.
+// ---------------------------------------------------------------------------
+/**
+ * Load a compiled-hook program's default export. JS module formats
+ * (`.mjs`/`.cjs`/`.js`) load via dynamic import directly; a TypeScript hook
+ * loads only under a TS-capable runtime (tsx / Node >= 23.6) — otherwise an
+ * actionable error points at authoring it as `.mjs`.
+ */
+async function loadHookProgram(file) {
+    const abs = (0, node_path_1.resolve)(process.cwd(), file);
+    const { pathToFileURL } = require("node:url");
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(abs).href));
+    }
+    catch (e) {
+        if (/\.(?:m|c)?ts$/.test(file)) {
+            throw new hook_program_js_1.HookCompileError(`Cannot load TypeScript hook "${file}" in this Node runtime. Run under ` +
+                `tsx (npx tsx …) / Node >= 23.6, or author the hook as a .mjs file.`);
+        }
+        throw new hook_program_js_1.HookCompileError(`Cannot load hook "${file}": ${e.message}`);
+    }
+    // Unwrap the ESM/CJS double-default that `export default` can produce.
+    const program = mod.default?.default ?? mod.default;
+    if (!program || typeof program !== "object") {
+        throw new hook_program_js_1.HookCompileError(`${file} has no default-exported hook program ` +
+            `(use \`export default defineHook({…})\`).`);
+    }
+    return program;
+}
+/** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
+async function loadProvider(file) {
+    const abs = (0, node_path_1.resolve)(process.cwd(), file);
+    const { pathToFileURL } = require("node:url");
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(abs).href));
+    }
+    catch (e) {
+        throw new hook_program_js_1.HookCompileError(`Cannot load provider "${file}": ${e.message}`);
+    }
+    const def = mod.default?.default ?? mod.default;
+    if (!def ||
+        typeof def !== "object" ||
+        def.kind !== "provider-def") {
+        throw new hook_program_js_1.HookCompileError(`${file} has no default-exported provider ` +
+            `(use \`export default defineProvider({…})\`).`);
+    }
+    return def;
+}
+/**
+ * Compile (validate) the registered providers under `.vigiles/providers/`: each
+ * must load and be read-only unless it opted into `dangerous`. Returns the set of
+ * valid provider NAMES (so a hook's `provider()` ref can resolve at compile).
+ * Throws HookCompileError on an unsafe provider — the same fail-the-build contract
+ * as a hook.
+ */
+async function compileProviders() {
+    const names = [];
+    for (const file of (0, hook_install_js_1.discoverProviderFiles)(process.cwd())) {
+        const def = await loadProvider(file);
+        if ((0, hook_providers_js_1.unsafeProvider)(def)) {
+            throw new hook_program_js_1.HookCompileError(`provider ${file} ("${def.run}") is not provably read-only — ` +
+                `pass dangerous:true to defineProvider to acknowledge it.`);
+        }
+        names.push(def.name);
+    }
+    return names;
+}
+/** Path of the tamper-evident stamp sidecar for a hook file. */
+function hookStampPath(file) {
+    return (0, node_path_1.resolve)(process.cwd(), ".vigiles/hooks", (0, node_path_1.basename)(file) + ".json");
+}
+/**
+ * Compile ONE typed hook program (authored against `vigiles/hook`) and MERGE it
+ * into the active harness's native config — the hook half of `vigiles compile`
+ * (there is no `compile-hook` verb; the cohesive-cli-surface rule). An import
+ * outside the sanctioned API does NOT compile (capability = API surface). The
+ * emitted block routes the live event to `hook-runtime run-program`; a
+ * tamper-evident stamp sidecar lets the runtime refuse a hand-edited artifact.
+ * The merge is idempotent (keyed by the hook PATH), so recompiling updates in
+ * place and never clobbers the user's own hooks.
+ */
+async function installHookFile(file, adapter, registeredProviders = []) {
+    const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), "utf-8");
+    const program = await loadHookProgram(file);
+    const compiled = (0, hook_program_js_1.compileHookProgram)(source, program, {
+        gateCommand: `npx vigiles hook-runtime run-program ${file}`,
+        dialect: adapter.dialect,
+        hookProtocol: adapter.hookProtocol,
+        settingsFormat: adapter.layout.settingsFormat,
+        registeredProviders,
+    });
+    // Tamper-evident stamp beside the source (one dir → basename is unique).
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(hookStampPath(file)), { recursive: true });
+    (0, node_fs_1.writeFileSync)(hookStampPath(file), JSON.stringify({ file, stamp: compiled.stamp }, null, 2) + "\n");
+    // Merge into the harness's native config, idempotently.
+    const format = adapter.layout.settingsFormat;
+    const settingsAbs = (0, node_path_1.resolve)(process.cwd(), adapter.layout.settingsPath);
+    const existing = (0, node_fs_1.existsSync)(settingsAbs)
+        ? format === "toml"
+            ? (0, toml_1.parse)((0, node_fs_1.readFileSync)(settingsAbs, "utf-8"))
+            : JSON.parse((0, node_fs_1.readFileSync)(settingsAbs, "utf-8"))
+        : {};
+    const merged = format === "toml"
+        ? (0, hook_install_js_1.mergeHooksToml)(existing, compiled.hooks, file)
+        : (0, hook_install_js_1.mergeHooksJson)(existing, compiled.hooks, file);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(settingsAbs), { recursive: true });
+    (0, node_fs_1.writeFileSync)(settingsAbs, (0, hook_install_js_1.serializeConfig)(merged, format));
+    // Honest gap (no silent skips): the gate/deny path is exit-2 and cross-harness,
+    // but an inject/react hook's OUTPUT shape is confirmed only for Claude Code. On
+    // another harness it would emit CC-shaped output that may not be read — exactly
+    // the silent failure this feature exists to prevent. Flag it, loudly.
+    const role = (0, hook_program_js_1.dispatchKind)(program);
+    const warning = adapter.name !== "claude-code" && (role === "inject" || role === "react")
+        ? `${role} output is only confirmed for Claude Code. On ${adapter.name}, ` +
+            `the gate (deny→exit 2) path works, but this hook's ${role} output is ` +
+            `CC-shaped and unverified — it may silently not apply. Use a gate hook on ` +
+            `${adapter.name} for now, or confirm against the real binary first ` +
+            `(research/compiled-hooks-codex.md §Deferred).`
+        : undefined;
+    return { role, settingsPath: adapter.layout.settingsPath, warning };
+}
+/**
+ * Compile + install every hook (explicit paths, else discovered under
+ * `.vigiles/hooks/`) into the active harness's config. Returns false if any
+ * hook failed to compile.
+ */
+async function installHooks(hookFiles, harnessFlag) {
+    if (hookFiles.length === 0)
+        return true;
+    const adapter = harnessFlag
+        ? (0, adapter_registry_js_1.resolveAdapter)(process.cwd(), harnessFlag)
+        : (0, adapter_registry_js_1.detectAdapterResult)(process.cwd()).adapter;
+    // Validate registered providers first → the names a hook's provider() ref may
+    // resolve to (an unsafe provider fails the whole compile, like a bad hook).
+    let registeredProviders;
+    try {
+        registeredProviders = await compileProviders();
+    }
+    catch (e) {
+        if (e instanceof hook_program_js_1.HookCompileError) {
+            console.error(`✗ ${e.message}`);
+            return false;
+        }
+        throw e;
+    }
+    let ok = true;
+    for (const file of hookFiles) {
+        try {
+            const r = await installHookFile(file, adapter, registeredProviders);
+            console.log(`✓ ${file} → ${r.settingsPath} (role: ${r.role}, harness: ${adapter.name})`);
+            if (r.warning)
+                console.warn(`⚠ ${r.warning}`);
+        }
+        catch (e) {
+            if (e instanceof hook_program_js_1.HookCompileError) {
+                console.error(`✗ ${file} — ${e.message}`);
+                const src = (() => {
+                    try {
+                        return (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), "utf-8");
+                    }
+                    catch {
+                        return "";
+                    }
+                })();
+                if ((0, hook_program_js_1.checkHookImports)(src).length > 0) {
+                    console.error("  A compiled hook may import ONLY `vigiles/hook` — that is its " +
+                        "entire capability surface.");
+                }
+                ok = false;
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+    return ok;
+}
+/**
+ * Gather a gate's DECLARED context providers (the trusted-host I/O step). Runs
+ * each declared read-only command via execSync in the hook's cwd; a provider
+ * that can't resolve yields its default (never throws). The pure registry +
+ * decision logic live in core/hook-providers.ts — this only injects the real IO.
+ */
+async function gatherHookContext(program) {
+    const needs = (0, hook_program_js_1.hookNeeds)(program);
+    if (needs.length === 0)
+        return {};
+    // Only load the registered-provider registry if a provider() ref is declared.
+    const hasRef = needs.some((n) => typeof n !== "string" && n.kind === "provider-ref");
+    const registry = hasRef ? await loadProviderRegistry() : {};
+    const { execSync } = require("node:child_process");
+    const { isCI } = require("ci-info");
+    return (0, hook_providers_js_1.gatherContext)(needs, {
+        exec: (command) => execSync(command, {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }),
+        cwd: process.cwd(),
+        platform: process.platform,
+        isCI,
+    }, registry);
+}
+/**
+ * Load the registered providers (`.vigiles/providers/`) into a name→def registry
+ * for `provider()` ref resolution. A bad/unloadable provider file is skipped (the
+ * ref then yields its default ""), never crashes a live session.
+ */
+async function loadProviderRegistry() {
+    const registry = {};
+    for (const file of (0, hook_install_js_1.discoverProviderFiles)(process.cwd())) {
+        try {
+            const def = await loadProvider(file);
+            registry[def.name] = def;
+        }
+        catch {
+            /* skip an unloadable provider file */
+        }
+    }
+    return registry;
+}
+/** Append an observe-mode record to `.vigiles/hook-observations.jsonl` (best-effort). */
+function recordObservation(file, on, would, reason) {
+    try {
+        const dir = (0, node_path_1.resolve)(process.cwd(), ".vigiles");
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        const line = JSON.stringify({
+            ts: new Date().toISOString(),
+            hook: file,
+            event: on,
+            would,
+            reason,
+        }) + "\n";
+        (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(dir, "hook-observations.jsonl"), line);
+    }
+    catch {
+        /* recording is best-effort — never let it break a live session */
+    }
+}
+/**
+ * Emit a gate Decision in the harness protocol — the author never writes it.
+ * `observe` mode turns a would-be block/ask into a recorded no-op (exit 0): the
+ * shadow/rollout path. Harness-neutral — exit 2 / exit 0 are identical on Claude
+ * Code and Codex; the record is vigiles-local.
+ */
+function emitGate(decision, on, mode, file) {
+    const action = (0, hook_program_js_1.gateAction)(decision, mode);
+    switch (action.kind) {
+        case "block":
+            console.error(action.reason);
+            process.exit(2);
+            return;
+        case "ask":
+            process.stdout.write(JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: on,
+                    permissionDecision: "ask",
+                    permissionDecisionReason: action.reason,
+                },
+            }) + "\n");
+            return;
+        case "observe":
+            recordObservation(file, on, action.would, action.reason);
+            console.error(`⚠ [vigiles observe] ${on}: would ${action.would} — ${action.reason}`);
+            return; // exit 0 — observe never blocks
+        case "allow":
+            return; // emit nothing, exit 0
+    }
+}
+/**
+ * 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).
+ */
+function verifyStampOrRefuse(file) {
+    const stampPath = hookStampPath(file);
+    if (!(0, node_fs_1.existsSync)(stampPath))
+        return;
+    try {
+        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).`);
+            process.exit(2);
+        }
+    }
+    catch {
+        /* unreadable sidecar → don't block a live session on it */
+    }
+}
+/**
+ * `vigiles hook-runtime run-program <file>` — the runtime the compiled hooks block
+ * 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.
+ */
+async function runHookProgramCommand(file) {
+    if (!file) {
+        console.error("Usage: vigiles hook-runtime run-program <hook-file>");
+        process.exit(2);
+        return;
+    }
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    let event = {};
+    try {
+        event = JSON.parse(raw);
+    }
+    catch {
+        /* malformed → empty event */
+    }
+    let program;
+    try {
+        program = await loadHookProgram(file);
+    }
+    catch {
+        console.error(`vigiles: cannot load hook program ${file}`);
+        process.exit(2);
+        return;
+    }
+    verifyStampOrRefuse(file);
+    switch ((0, hook_program_js_1.dispatchKind)(program)) {
+        case "inject": {
+            const out = (0, hook_program_js_1.runInject)(program, { source: event.source });
+            process.stdout.write(JSON.stringify(out) + "\n");
+            return;
+        }
+        case "react": {
+            const reaction = (0, hook_program_js_1.runReact)(program, event);
+            if (reaction.kind === "run") {
+                const { spawnSync } = require("node:child_process");
+                const res = spawnSync(reaction.command, {
+                    shell: true,
+                    stdio: "inherit",
+                });
+                process.exit(res.status ?? 0);
+            }
+            if (reaction.kind === "notice")
+                console.error(reaction.message);
+            return;
+        }
+        case "file-gate": {
+            const ctx = await gatherHookContext(program);
+            emitGate((0, hook_program_js_1.decideFileGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+        case "bash-gate": {
+            const ctx = await gatherHookContext(program);
+            emitGate((0, hook_program_js_1.decideProgram)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+        case "prompt-gate": {
+            const ctx = await gatherHookContext(program);
+            emitGate((0, hook_program_js_1.decidePromptGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+        case "stop-gate": {
+            const ctx = await gatherHookContext(program);
+            emitGate((0, hook_program_js_1.decideStopGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+    }
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -3331,14 +3798,25 @@ async function main() {
             break;
         }
         case "compile": {
-            const specs = restArgs.length > 0 ? restArgs : findSpecs();
-            if (specs.length === 0) {
-                console.log("No .spec.ts files found.");
+            const harnessFlag = harnessFlagFrom(args);
+            // One verb compiles every typed authoring artifact: a .spec.ts → markdown,
+            // a hook program → its harness config + stamp (cohesive-cli-surface). With
+            // explicit args, partition by extension; bare, discover both.
+            const specs = restArgs.length > 0
+                ? restArgs.filter((f) => f.endsWith(".spec.ts"))
+                : findSpecs();
+            const hooks = restArgs.length > 0
+                ? restArgs.filter((f) => !f.endsWith(".spec.ts"))
+                : (0, hook_install_js_1.discoverHookFiles)(process.cwd());
+            if (specs.length === 0 && hooks.length === 0) {
+                console.log("No .spec.ts or .vigiles/hooks/ hook files found.");
                 console.log("Run `vigiles init` to create one.");
                 process.exit(0);
             }
-            const harnessFlag = harnessFlagFrom(args);
-            const valid = await compile(specs, config, { harnessFlag });
+            let valid = true;
+            if (specs.length > 0)
+                valid = (await compile(specs, config, { harnessFlag })) && valid;
+            valid = (await installHooks(hooks, harnessFlag)) && valid;
             console.log("");
             if (valid) {
                 console.log("Compilation complete.");
@@ -3373,7 +3851,6 @@ async function main() {
             // under one marketplace.json) expands into its members and ranks them.
             const market = dirs.length === 1 ? (0, scan_js_1.inspectMarketplace)((0, node_path_1.resolve)(dirs[0])) : null;
             const targets = market && market.onDisk.length > 0 ? [...market.onDisk] : dirs;
-            const wantTrigger = args.includes("--trigger");
             if (market && market.onDisk.length === 0 && market.total > 0) {
                 // A CURATED marketplace — every member is an external git/url plugin, so
                 // there's nothing on disk to scan. Say so honestly instead of falling
@@ -3390,12 +3867,13 @@ async function main() {
                 }
             }
             else if (targets.length > 1) {
-                // Multiple targets → rank them (the leaderboard engine).
+                // Multiple targets → rank them (the leaderboard engine). `--md` emits the
+                // publishable Markdown table (a README / gist / the leaderboard site).
                 const scores = (0, leaderboard_js_1.rankPlugins)(targets);
-                console.log(json ? JSON.stringify(scores, null, 2) : (0, leaderboard_js_1.formatLeaderboard)(scores));
-                if (wantTrigger) {
-                    console.log("\n⚠ --trigger (behavioral column) runs per single plugin; not yet wired into the leaderboard. Scan one plugin dir to probe it.");
-                }
+                const text = args.includes("--md")
+                    ? (0, leaderboard_js_1.formatLeaderboardMarkdown)(scores)
+                    : (0, leaderboard_js_1.formatLeaderboard)(scores);
+                console.log(json ? JSON.stringify(scores, null, 2) : text);
             }
             else {
                 const root = (0, node_path_1.resolve)(targets[0]);
@@ -3410,6 +3888,13 @@ async function main() {
                     if (!harnessFlag && det.ambiguousWith.length > 0) {
                         console.log(`⚠ repo also matches: ${det.ambiguousWith.join(", ")} — override with --harness=<name>`);
                     }
+                    // Freshness: warn if our hand-maintained CC catalog drifted from the
+                    // user's INSTALLED claude-code (read-local, best-effort, never throws).
+                    if (adapter.name === "claude-code") {
+                        const drift = (0, dialect_drift_js_1.formatDialectDrift)((0, dialect_drift_js_1.checkDialectDrift)());
+                        if (drift)
+                            console.log(drift);
+                    }
                     console.log("");
                 }
                 if (args.includes("--fix-plan")) {
@@ -3421,9 +3906,27 @@ async function main() {
                 else {
                     console.log(json ? JSON.stringify(report, null, 2) : (0, scan_js_1.formatScanReport)(report));
                 }
-                if (wantTrigger) {
-                    const harness = adapter.name === "codex" ? "codex" : "claude-code";
-                    await handleScanTrigger(root, args, json, harness);
+                if (args.includes("--verify-mcp")) {
+                    // Opt-in LIVE MCP tool resolution: starts each declared server and checks
+                    // the agent's mcp__server__tool refs actually exist (the dynamic check no
+                    // static linter can do). Side-effecting (spawns servers) → opt-in only.
+                    const mcpErrs = await (0, scan_js_1.verifyLiveMcpTools)(report, adapter.layout, adapter.dialect);
+                    console.log(json
+                        ? JSON.stringify({ mcpContractTools: mcpErrs }, null, 2)
+                        : "\n" + (0, scan_js_1.formatMcpContractReport)(mcpErrs));
+                }
+                const capBase = flagValue(args, "--capability-diff");
+                if (capBase) {
+                    // Did this version WIDEN the agent's blast radius vs <before>? Diffs the
+                    // two whole-harness capability lattices (moat #2). Informational by
+                    // default; `--fail-on-widen` exits non-zero (the opt-in CI gate).
+                    const beforeReport = (0, scan_js_1.scanPlugin)((0, node_path_1.resolve)(capBase), adapter.layout, adapter.dialect);
+                    const diff = (0, capability_diff_js_1.diffCapabilities)(capabilitiesOfReport(beforeReport, adapter.dialect), capabilitiesOfReport(report, adapter.dialect));
+                    console.log(json
+                        ? JSON.stringify({ capabilityDiff: diff }, null, 2)
+                        : "\n" + (0, capability_diff_js_1.formatCapabilityDiff)(diff));
+                    if (args.includes("--fail-on-widen") && diff.widened)
+                        process.exitCode = 1;
                 }
             }
             break;
@@ -3434,6 +3937,9 @@ async function main() {
         case "scaffold-test":
             handleScaffoldTest(restArgs, args);
             break;
+        case "measure":
+            await handleMeasure(restArgs, args);
+            break;
         // --- Plumbing ---
         case "generate-types":
             handleGenerateTypes(args, restArgs);
@@ -3444,9 +3950,16 @@ async function main() {
         case "generate-harness":
             await handleGenerateHarness(args, restArgs);
             break;
+        case "refs":
+            refsCommand(restArgs[0]);
+            break;
+        // Hidden umbrella for runtime entrypoints emitted into hooks configs — never
+        // typed by a human. See handleHookRuntime / the cohesive-cli-surface rule.
+        case "hook-runtime":
+            await handleHookRuntime(restArgs[0], restArgs.slice(1));
+            break;
         default:
-            if (!handleSkillCommand(command, restArgs))
-                printUsage(command);
+            printUsage(command);
             break;
     }
 }