vigiles 29.0.0 → 30.0.0

package/dist/eval.d.ts

@@ -1,4 +1,7 @@
-import { parseToolCalls, parseHooks, parseSubagents, type ToolCall, type Trace } from "./harness-test.js";
+import type { HarnessLiveDriver } from "./core/live-driver.js";
+import type { AgentRunArgs, AgentRunner, EvalDriver, EvalUsage, ModelOutputParser, ParsedModelRun, RunOut } from "./core/eval-driver.js";
+export type { AgentRunArgs, AgentRunner, EvalDriver, EvalUsage, ModelOutputParser, ParsedModelRun, RunOut, } from "./core/eval-driver.js";
+import { type ToolCall, type Trace } from "./harness-test.js";
 import { type CacheMode } from "./eval-cache.js";
 import { type EvalLockOptions } from "./eval-lock.js";
 import type { Check, CheckJSON } from "./check.js";
@@ -54,20 +57,6 @@ export interface EvalArm {
      */
     readonly effort?: string | number;
 }
-/** Per-run resource use, parsed from the terminal `result` event (0 when absent). */
-export interface EvalUsage {
-    /** `total_cost_usd` reported by claude. */
-    readonly costUsd: number;
-    /** Wall-clock `duration_ms` of the run. */
-    readonly durationMs: number;
-    /** Fresh (uncached) input tokens, billed at full input price. */
-    readonly inputTokens: number;
-    readonly outputTokens: number;
-    /** Tokens written to the prompt cache this run (~1.25× input price). */
-    readonly cacheCreationTokens: number;
-    /** Tokens served from the prompt cache this run (~0.1× input price). */
-    readonly cacheReadTokens: number;
-}
 /**
  * Context handed to `measure` after a run, to compute that run's metrics. It is
  * a `Trace` (so the bare predicates `usedTool` / `skillResolved` / `toolCount` /
@@ -231,52 +220,6 @@ export interface EvalReport {
     /** True if a `maxCostUsd` budget cap stopped the run before all trials ran. */
     readonly aborted: boolean;
 }
-/** The raw output of one trial: the agent's exit code + captured streams. */
-export interface RunOut {
-    code: number;
-    stdout: string;
-    /** Captured stderr, when the runner provides it (used for rate-limit detection). */
-    stderr?: string;
-}
-/** The per-trial arguments handed to an {@link AgentRunner}. */
-export interface AgentRunArgs {
-    readonly task: string;
-    readonly cwd: string;
-    readonly model: string;
-    /**
-     * Reasoning-budget level for the run (`claude --effort`). Part of the
-     * MEASUREMENT, not a run knob: it changes the model's output distribution, not
-     * the sample size — so it lives on the spec next to `model` (never an env),
-     * and it is hashed into both the cache key and the eval lock. Deliberately
-     * `string | number` rather than a literal union: the binary accepts an alias
-     * map, is case-insensitive, and takes an integer budget, and its own valid set
-     * MOVED between builds (2.1.42 had no `xhigh`, 2.1.257 does) — a hard-coded
-     * union would reject a valid level after any upstream addition. A wrong value
-     * is caught at RUNTIME instead, by {@link effortRejection}, which is what the
-     * binary actually tells us. Omit for the harness default.
-     */
-    readonly effort?: string | number;
-    readonly tools: readonly string[];
-    readonly hasSettings: boolean;
-    readonly pluginDir: string | undefined;
-    readonly timeoutMs: number;
-    /** Extra env layered over `process.env` for this run (e.g. `VIGILES_INTERCEPT_TOOLS`). */
-    readonly env?: Record<string, string>;
-    /**
-     * When true, `env` is the COMPLETE spawn environment (an ephemeral run env from
-     * `ephemeralRunEnv`) — the runner does NOT prepend `process.env`, so the
-     * real `$HOME` / secrets are scrubbed. Default false: `env` is an overlay over
-     * `process.env` (the byte-identical-to-today path). Set only by `ephemeralEnv`.
-     */
-    readonly replaceEnv?: boolean;
-}
-/**
- * Runs one trial and returns its raw output. The default (`spawnAgent`)
- * drives the real `claude` CLI; `runEvalWith` takes one explicitly, so the eval
- * orchestration is testable without a model (pass a fake returning canned
- * stream-json) and a custom runtime can be plugged in.
- */
-export type AgentRunner = (args: AgentRunArgs) => Promise<RunOut>;
 /**
  * Resolve the environment a trial's subprocess actually runs with — the
  * SECURITY-CRITICAL decision behind `ephemeralEnv`. When `replaceEnv` is set, the
@@ -528,22 +471,6 @@ export declare function checkReportToJUnit(report: CheckReport, opts?: {
 }): string;
 /** Parse per-run cost/latency/tokens from a stream — pure, model-free. */
 export declare function parseUsage(stdout: string): EvalUsage;
-/**
- * The harness-specific half of a run trace: how a real model's raw stdout maps
- * to the common fields. Claude Code's `parseClaudeRun` reads its stream-json; a
- * second harness (Codex) supplies its own parser of `codex exec --json` JSONL, so
- * the eval tier (`measureTriggerRate`/`runEval`) isn't bound to Claude's format.
- * The non-harness fields (cwd/exitCode/stdout/file/sh) stay in `makeContext`.
- */
-export interface ParsedModelRun {
-    readonly turns: number;
-    readonly output: string;
-    readonly toolCalls: ReturnType<typeof parseToolCalls>;
-    readonly hooks: ReturnType<typeof parseHooks>;
-    readonly subagents: ReturnType<typeof parseSubagents>;
-    readonly usage: EvalUsage;
-}
-export type ModelOutputParser = (out: RunOut) => ParsedModelRun;
 /** Parse Claude Code's stream-json stdout into the common trace fields. */
 export declare function parseClaudeRun(out: RunOut): ParsedModelRun;
 /**
@@ -864,37 +791,6 @@ export interface TriggerRateReport {
      */
     readonly experimental?: string;
 }
-/**
- * An eval-tier transport: how to RUN a real harness turn and PARSE its output.
- * The default is Claude Code (`claudeEvalDriver`); a second harness supplies its
- * own (e.g. `codexEvalDriver` from `vigiles/codex`) and passes it as
- * `measureTriggerRate(spec, { evalDriver })` — the eval-tier analog of
- * `runHarnessTest`'s `{ adapter }`. `runError` lets the loop drop an
- * errored/rate-limited turn instead of scoring it as a miss.
- */
-export interface EvalDriver {
-    readonly runner: AgentRunner;
-    readonly parse: ModelOutputParser;
-    readonly runError?: (out: RunOut) => string | null;
-    /**
-     * The harness this driver runs (e.g. `"claude-code"`, `"codex"`). Folded into a
-     * trigger-rate eval's LOCK hash so a report recorded on one harness is marked
-     * STALE if the eval is later switched to another (a different harness can fire a
-     * skill differently). Optional for back-compat — absent defaults to
-     * `"claude-code"`, so an existing single-harness lock is unaffected.
-     */
-    readonly harness?: string;
-    /**
-     * When set, this driver's trigger-rate number is EXPERIMENTAL and not
-     * validated — the string is the human caveat explaining why (e.g. Codex has no
-     * skill-selection event, so firing is inferred from a SKILL.md read, which can
-     * be wrong in both directions). Absent = supported/trustworthy (the default,
-     * Claude Code). `measureTriggerRate` copies it onto the report and warns; the
-     * formatter prints it. Precision-first: never let a possibly-wrong number read
-     * as a measurement.
-     */
-    readonly experimental?: string;
-}
 /**
  * The default (Claude Code) eval driver: real `claude` + stream-json parsing.
  *
@@ -909,6 +805,18 @@ export interface EvalDriver {
  * The asymmetry reflects default-vs-injected, not a hexagonal violation.
  */
 export declare const claudeEvalDriver: EvalDriver;
+/**
+ * The Claude Code {@link HarnessLiveDriver} — the EXECUTING tiers' side of the
+ * adapter, reached through `claudeCodeAdapter.liveDriver()`.
+ *
+ * It lives HERE, at the composition root, for exactly the reason
+ * `claudeEvalDriver` above does: it is assembled from the wired default runner
+ * and `whichSkillsFired`, and moving it into `src/adapters/claude-code/` would
+ * make `eval.ts → adapters/claude-code → eval.ts` a cycle. The adapter reaches
+ * it through a dynamic `import()`, so nothing pays for this graph until an
+ * executing tier actually runs.
+ */
+export declare const claudeCodeLiveDriver: HarnessLiveDriver;
 /**
  * Package loose `<skillsDir>/<name>/SKILL.md` skills into a throwaway plugin dir
  * that `claude --plugin-dir` accepts — so repo-local skills (e.g. `.claude/skills`)

package/dist/eval.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.claudeEvalDriver = exports.EPHEMERAL_HOME_KEEP = exports.spawnAgent = exports.EFFORT_ENV_VAR = void 0;
+exports.claudeCodeLiveDriver = exports.claudeEvalDriver = exports.EPHEMERAL_HOME_KEEP = exports.spawnAgent = exports.EFFORT_ENV_VAR = void 0;
 exports.resolveSpawnEnv = resolveSpawnEnv;
 exports.pinEffortEnv = pinEffortEnv;
 exports.effortRejection = effortRejection;
@@ -76,6 +76,7 @@ const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
 const runtime_js_1 = require("./adapters/claude-code/runtime.js");
 const eval_cost_js_1 = require("./eval-cost.js");
 const proofs_js_1 = require("./core/proofs.js");
+const model_access_js_1 = require("./adapters/claude-code/model-access.js");
 const harness_test_js_1 = require("./harness-test.js");
 const eval_cache_js_1 = require("./eval-cache.js");
 const eval_lock_js_1 = require("./eval-lock.js");
@@ -1413,6 +1414,38 @@ exports.claudeEvalDriver = {
     parse: parseClaudeRun,
     harness: "claude-code",
 };
+/**
+ * The Claude Code {@link HarnessLiveDriver} — the EXECUTING tiers' side of the
+ * adapter, reached through `claudeCodeAdapter.liveDriver()`.
+ *
+ * It lives HERE, at the composition root, for exactly the reason
+ * `claudeEvalDriver` above does: it is assembled from the wired default runner
+ * and `whichSkillsFired`, and moving it into `src/adapters/claude-code/` would
+ * make `eval.ts → adapters/claude-code → eval.ts` a cycle. The adapter reaches
+ * it through a dynamic `import()`, so nothing pays for this graph until an
+ * executing tier actually runs.
+ */
+exports.claudeCodeLiveDriver = {
+    evalDriver: exports.claudeEvalDriver,
+    // Env-only, and never a spent token: deciding whether to OFFER a measurement
+    // must not cost one. The three arms are what the consent prompt words
+    // differently — a key bills per token, a session is $0 metered, and neither
+    // present means the tier is skipped with `fix` printed.
+    access: (env) => (0, model_access_js_1.isMeteredAccess)(env)
+        ? { kind: "metered" }
+        : (0, model_access_js_1.hasModelAccess)(env)
+            ? { kind: "subscription" }
+            : { kind: "none", fix: model_access_js_1.CLAUDE_CODE_ACCESS_FIX },
+    // A discrete `Skill` tool_use in the trace says WHICH skill was selected, so
+    // the selection-collision matrix and the adversarial gate can run here.
+    firing: { kind: "event" },
+    // Claude Code namespaces a plugin's skill as `<plugin>:<skill>`; the manifest
+    // name is handed in by the domain, which read it off the layout.
+    firedFor: (skill, plugin) => (t) => whichSkillsFired(t).includes(plugin.name ? `${plugin.name}:${skill}` : skill),
+    // The probe may rebuild the plugin to skills-only stubs: this is the harness
+    // whose plugin shape vigiles packages, so a stubbed rebuild is validated.
+    installsStubs: true,
+};
 /**
  * Is this directory entry a skill DIRECTORY — following a symlink to one?
  *

package/dist/harness-test.d.ts

@@ -1,5 +1,7 @@
 import type { HarnessAdapter } from "./core/adapter.js";
-import type { HarnessTestDriver, ToolCall, HookFire, ParsedRun, ModelTurn, ModelRequest } from "./core/harness-driver.js";
+import type { HarnessTestDriver, ToolCall, HookFire, ParsedRun, ModelTurn } from "./core/harness-driver.js";
+import type { Trace, SubagentTrace } from "./core/eval-driver.js";
+export type { Trace, SubagentTrace } from "./core/eval-driver.js";
 import { type SandboxMode } from "./sandbox.js";
 export { scriptModel } from "./mock-model.js";
 export type { ModelTurn, ModelRequest, ToolCall, HookFire, HarnessTestDriver, } from "./core/harness-driver.js";
@@ -56,68 +58,6 @@ export interface HarnessTestSpec {
      */
     readonly sandbox?: SandboxMode;
 }
-/**
- * The observable record of ONE run — the unified shape produced by BOTH testing
- * tiers: `runHarnessTest`'s result and `runEval`'s `measure` ctx (`eval.ts`)
- * both satisfy it. That's what lets the bare predicates in `harness-assert.ts`
- * (`usedTool` / `skillResolved` / `toolCount` / `toolUsedWith` / `hookFired` /
- * `outputContains`) run over either, with the testing helpers asserting and eval
- * measuring over the same vocabulary.
- */
-export interface Trace {
-    /**
-     * The tools the agent invoked, each paired with its result — parsed from the
-     * transcript. Empty unless the run captured the stream (`transcript: true` on
-     * the harness tier; always on the eval tier). Lets a test assert on the
-     * agent's *actions* (skills, MCP tools, subagents) instead of grepping stdout.
-     */
-    readonly toolCalls: readonly ToolCall[];
-    /**
-     * The hooks that fired during the run, each with its decision — parsed from
-     * the CLI's `hook_response` stream events. Same capture requirement as
-     * `toolCalls` (empty without the stream). Lets a test assert hook firing
-     * honestly instead of via a marker file.
-     */
-    readonly hooks: readonly HookFire[];
-    /** The agent's final answer text (the terminal `result` event), or "". */
-    readonly output: string;
-    /**
-     * The requests the model received, captured by the scripted mock — each with
-     * its `system` prompt and `messages`, flattened to text. Lets a test assert
-     * what actually reached the model (a SessionStart hook's injected context, a
-     * slash command's expansion), not just that a hook fired. **Harness tier
-     * only**: the mock sees the requests, so this is populated by `runHarnessTest`
-     * (with or without `transcript`); the eval tier drives the real API, so its
-     * `modelRequests` is always empty.
-     */
-    readonly modelRequests: readonly ModelRequest[];
-    /** Number of model turns. */
-    readonly turns: number;
-    /**
-     * Sub-agent (`Task`) runs as nested traces, keyed by `subagent_type`. A
-     * subagent runs its own session; CC tags its events with `parent_tool_use_id`
-     * (= the `Task` tool call) so its tool calls are recovered into a sub-trace
-     * here, lettng a test assert what the subagent DID (not just that `Task` fired).
-     * Empty unless the stream was captured / the harness emits subagent events.
-     */
-    readonly subagents?: readonly SubagentTrace[];
-    /** Final contents of a file under the working dir, or null if absent. */
-    file(path: string): string | null;
-}
-/** A sub-agent (`Task`) run as a nested trace: its name + the tools it used. */
-export interface SubagentTrace {
-    /** The `subagent_type` from the `Task` tool input. */
-    readonly name: string;
-    /** The tools the subagent invoked (events tagged with the Task's id). */
-    readonly toolCalls: readonly ToolCall[];
-    /**
-     * The subagent's RETURNED text — the dispatch tool_result the orchestrator
-     * receives back. This is where a `result()` contract's `vigiles:ok`/`vigiles:err`
-     * block lands, so `subagent(name, [output(/vigiles:ok/)])` can assert the typed
-     * outcome. "" if not captured.
-     */
-    readonly output: string;
-}
 export interface HarnessTestResult extends Trace {
     readonly exitCode: number;
     readonly stdout: string;

package/dist/hook-install.d.ts

@@ -128,7 +128,18 @@ interface ConfigToml {
 }
 /** The TOML sibling of {@link mergeHooksJson} (Codex `[[hooks.<event>]]`). */
 export declare function mergeHooksToml(existing: ConfigToml, compiled: CompiledHooks, hookPath: string): ConfigToml;
-/** Serialize a merged config back to its on-disk text (with trailing newline). */
+/**
+ * Serialize a merged config back to its on-disk text.
+ *
+ * ⚠️ DEPRECATED IN PLACE, not deleted, and the distinction matters: the
+ * harness-driven path (`installHookFile` in `cli-main.ts`) goes through
+ * `PluginLayout.settings.render` now, so no adapter's encoding is decided here
+ * any more. The one remaining caller is `cli-main.ts`'s Codex-plugin wiring,
+ * which writes `.codex/config.toml` for a harness it names ITSELF, at the
+ * composition root — a caller that already knows the encoding, rather than one
+ * branching on a layout field. Its `format` argument is therefore a literal at
+ * the call site, not a value read off a port.
+ */
 export declare function serializeConfig(merged: Record<string, unknown>, format: "json" | "toml"): string;
 export {};
 //# sourceMappingURL=hook-install.d.ts.map

package/dist/hook-install.js

@@ -298,7 +298,18 @@ function mergeHooksToml(existing, compiled, hookPath) {
     ]));
     return { ...existing, hooks: { ...before, ...rewritten } };
 }
-/** Serialize a merged config back to its on-disk text (with trailing newline). */
+/**
+ * Serialize a merged config back to its on-disk text.
+ *
+ * ⚠️ DEPRECATED IN PLACE, not deleted, and the distinction matters: the
+ * harness-driven path (`installHookFile` in `cli-main.ts`) goes through
+ * `PluginLayout.settings.render` now, so no adapter's encoding is decided here
+ * any more. The one remaining caller is `cli-main.ts`'s Codex-plugin wiring,
+ * which writes `.codex/config.toml` for a harness it names ITSELF, at the
+ * composition root — a caller that already knows the encoding, rather than one
+ * branching on a layout field. Its `format` argument is therefore a literal at
+ * the call site, not a value read off a port.
+ */
 function serializeConfig(merged, format) {
     return format === "toml"
         ? stringifyToml(merged).trimEnd() + "\n"

package/dist/plugin-loader.d.ts

@@ -1,4 +1,4 @@
-import type { PluginLayout } from "./core/layout.js";
+import { type PluginLayout } from "./core/layout.js";
 import type { ExcludeSet } from "./exclude.js";
 export interface LoadedPlugin {
     /** A `.claude/settings.json`-shaped object with hooks resolved. */

package/dist/plugin-loader.js

@@ -36,8 +36,8 @@ exports.resolveHarness = resolveHarness;
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const toml_1 = require("@iarna/toml");
 const hash_js_1 = require("./core/hash.js");
+const layout_js_1 = require("./core/layout.js");
 const exclude_js_1 = require("./exclude.js");
 const fs_walk_js_1 = require("./fs-walk.js");
 const source_refs_js_1 = require("./core/source-refs.js");
@@ -57,34 +57,31 @@ function readHooksFile(path) {
     return safeReadJson(path)?.hooks;
 }
 /**
- * Parse the layout's manifest in its declared `settingsFormat` — JSON (Claude
- * Code's plugin.json) or TOML (Codex's `config.toml`). A TOML harness's manifest
- * (hooks, `[mcp_servers]`) would otherwise read as empty through the JSON path.
- * Behaviour-identical to `safeReadJson` when the format is JSON.
+ * Parse the layout's manifest through its own CODEC. A TOML harness's manifest
+ * (hooks, `[mcp_servers]`) would otherwise read as empty through a JSON parse.
+ *
+ * One code path now, where there used to be `if (settingsFormat === "toml")`
+ * over a JSON fallback: the codec is the branch, so a third encoding needs no
+ * edit here.
  */
 function safeReadManifest(root, layout) {
-    const path = (0, node_path_1.join)(root, layout.manifestPath);
-    if (layout.settingsFormat === "toml") {
-        try {
-            return (0, toml_1.parse)((0, node_fs_1.readFileSync)(path, "utf-8"));
-        }
-        catch {
-            return null;
-        }
+    try {
+        const text = (0, node_fs_1.readFileSync)((0, node_path_1.join)(root, layout.manifestPath), "utf-8");
+        return layout.settings.parse(text);
+    }
+    catch {
+        // Missing, unreadable, or malformed — the caller falls through to the
+        // other hook locations, exactly as it did for a bad JSON manifest.
+        return null;
     }
-    return safeReadJson(path);
 }
 /**
- * Read the `.hooks` field of a settings file in the layout's format — JSON
- * (Claude Code's settings.json) or TOML (Codex's `config.toml` `[hooks]`). A
- * TOML harness's hooks would otherwise be read as zero by the JSON path.
+ * Read the `.hooks` field of a settings file through the layout's codec. A TOML
+ * harness's hooks would otherwise be read as zero by a JSON parse.
  */
-function readSettingsHooks(path, format) {
-    if (format === "json")
-        return readHooksFile(path);
+function readSettingsHooks(path, codec) {
     try {
-        return (0, toml_1.parse)((0, node_fs_1.readFileSync)(path, "utf-8"))
-            .hooks;
+        return codec.parse((0, node_fs_1.readFileSync)(path, "utf-8")).hooks;
     }
     catch {
         return undefined;
@@ -108,12 +105,16 @@ function readHooks(root, layout) {
         if (m.hooks !== undefined)
             return m.hooks;
     }
-    const conventionPath = (0, node_path_1.join)(root, layout.hooksConventionPath);
-    if ((0, node_fs_1.existsSync)(conventionPath))
-        return readHooksFile(conventionPath);
+    // Optional: a harness whose hooks are in-process code modules has no
+    // standalone hooks FILE, so there is nothing to look for here.
+    if (layout.hooksConventionPath !== undefined) {
+        const conventionPath = (0, node_path_1.join)(root, layout.hooksConventionPath);
+        if ((0, node_fs_1.existsSync)(conventionPath))
+            return readHooksFile(conventionPath);
+    }
     const settingsPath = (0, node_path_1.join)(root, layout.settingsPath);
     if ((0, node_fs_1.existsSync)(settingsPath))
-        return readSettingsHooks(settingsPath, layout.settingsFormat);
+        return readSettingsHooks(settingsPath, layout.settings);
     return undefined;
 }
 /**
@@ -294,7 +295,7 @@ const EMPTY_LOAD = {
  */
 function surfaceHasLoadable(layout, surface, tree) {
     const keys = Object.keys(tree);
-    return surface === layout.skillDir
+    return surface === layout.surfaces.skill
         ? keys.some((k) => (0, node_path_1.basename)(k) === "SKILL.md")
         : keys.some((k) => k.endsWith(".md"));
 }
@@ -317,11 +318,11 @@ function materializeSurfaces(root, layout, files, sources, excluded = exclude_js
     /** Every surface tree of one scope, read once, keyed by surface dir. */
     const scopeTrees = (base) => {
         const trees = new Map();
-        for (const surface of layout.surfaceDirs)
+        for (const surface of (0, layout_js_1.surfaceDirs)(layout))
             trees.set(surface, surfaceTree((0, node_path_1.join)(root, base, surface)));
         return trees;
     };
-    const hasLoadable = (trees) => layout.surfaceDirs.some((s) => surfaceHasLoadable(layout, s, trees.get(s) ?? {}));
+    const hasLoadable = (trees) => (0, layout_js_1.surfaceDirs)(layout).some((s) => surfaceHasLoadable(layout, s, trees.get(s) ?? {}));
     const add = (key, content, onDisk) => {
         files[key] = content;
         sources[key] = onDisk;
@@ -342,7 +343,7 @@ function materializeSurfaces(root, layout, files, sources, excluded = exclude_js
         declaredTrees.set(base, scopeTrees(base));
     /** Copy one scope's already-read trees into `files`, keyed by that scope. */
     const materializeScope = (scope, trees) => {
-        for (const surface of layout.surfaceDirs) {
+        for (const surface of (0, layout_js_1.surfaceDirs)(layout)) {
             const tree = trees.get(surface) ?? {};
             for (const [rel, content] of Object.entries(tree))
                 add((0, surface_scopes_js_1.scopeKey)(scope, surface, rel), content, (0, node_path_1.join)(root, scope.base, surface, rel));
@@ -397,7 +398,8 @@ function materializeSurfaces(root, layout, files, sources, excluded = exclude_js
         skillName: (0, node_path_1.basename)(root),
         rootHasLoadable: hasLoadable(rootTrees),
         isPluginShaped: (0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.manifestPath)) ||
-            (0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.hooksConventionPath)),
+            (layout.hooksConventionPath !== undefined &&
+                (0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.hooksConventionPath))),
         userHasLoadable: hasLoadable(userTrees),
         declaredRoots,
     });
@@ -409,11 +411,16 @@ function materializeSurfaces(root, layout, files, sources, excluded = exclude_js
             // named (`vigiles audit <dir>`), not one this walk discovered, and refusing
             // to read the path someone explicitly pointed at is not a containment rule.
             const tree = readTree(root, root, excluded);
+            // The skill dir is CARRIED on the variant, because only a layout that has
+            // one can produce it. This used to re-read `layout.surfaces.skill` and
+            // guard the `undefined` case with a `return` that nothing could reach —
+            // see `SurfaceSource` for why that shape kept coming back.
+            const { skillDir } = source;
             for (const [rel, content] of Object.entries(tree)) {
-                add((0, node_path_1.join)(layout.materializeRoot, layout.skillDir, source.skillName, rel), content, (0, node_path_1.join)(root, rel));
+                add((0, node_path_1.join)((0, layout_js_1.materializePrefix)(layout), skillDir, source.skillName, rel), content, (0, node_path_1.join)(root, rel));
             }
-            counts[layout.skillDir] = Object.keys(tree).length;
-            harnessCounts[layout.skillDir] = counts[layout.skillDir];
+            counts[skillDir] = Object.keys(tree).length;
+            harnessCounts[skillDir] = counts[skillDir];
             return { counts, harnessCounts, scopes: [] };
         }
         case "scopes": {
@@ -474,7 +481,7 @@ function hasMcp(root, layout) {
 // so this and its browser twin (scan-files.ts) cannot disagree on them and
 // neither can omit one. See that module for the two boundary defects.
 function intraRefRe(layout) {
-    return (0, source_refs_js_1.intraRefPattern)(layout.intraRefDirs);
+    return (0, source_refs_js_1.intraRefPattern)((0, layout_js_1.executableSourceDirs)(layout));
 }
 // Shell vars that root a path OUTSIDE the plugin (the user's project / home), so
 // a `surface/…` after one is NOT a plugin-root ref. Anything else ($ROOT,
@@ -572,7 +579,7 @@ function missingRefsIn(content, re, root) {
 /** The plugin's executable (non-prose) source files under the surface dirs. */
 function executableSources(root, layout) {
     const sources = {};
-    for (const surface of layout.intraRefDirs) {
+    for (const surface of (0, layout_js_1.executableSourceDirs)(layout)) {
         const dir = (0, node_path_1.join)(root, surface);
         if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory())
             continue;

package/dist/scan-behavioral.d.ts

@@ -15,9 +15,8 @@
 import type { PluginLayout } from "./core/layout.js";
 import type { HarnessDialect } from "./core/dialect.js";
 import { type EvalDriver } from "./eval.js";
-import { type Trace } from "./harness-test.js";
-/** Which harness drives the behavioral column (default Claude Code). */
-export type ProbeHarness = "claude-code" | "codex";
+import { type EventFiringDriver, type HarnessLiveDriver } from "./core/live-driver.js";
+import type { HarnessAdapter } from "./core/adapter.js";
 /** Author-supplied prompt sets for one skill (bare skill name → these). */
 export interface SkillPrompts {
     readonly prompts: readonly string[];
@@ -53,28 +52,16 @@ export interface ProbeOptions {
     readonly model?: string;
     readonly minPrompts?: number;
     readonly minDistance?: number;
-    /** Which harness to drive (default `"claude-code"`). */
-    readonly harness?: ProbeHarness;
+    /** Which harness drives it — the adapter itself, not its name (default
+     *  {@link defaultAdapter}). A reference-only adapter reports `available: false`. */
+    readonly adapter?: HarnessAdapter;
     /** Layout + dialect for candidate discovery — so a Codex repo's skills (under
      *  the Codex layout) are found, not silently missed by the default CC layout. */
     readonly layout?: PluginLayout;
     readonly dialect?: HarnessDialect;
 }
-/**
- * Per-harness probe wiring: the eval driver (runner+parse), how to build the
- * `fired` predicate for a skill, whether to stub bodies, and an availability
- * gate. Claude detects firing via the `Skill` tool_use (namespaced by the
- * plugin name); Codex has no skill event, so firing is the SKILL.md read
- * (`codexSkillFired`, bare name) — see `research/codex-prototype-findings.md`.
- */
-export interface HarnessProbe {
-    readonly evalDriver: EvalDriver;
-    readonly firedFor: (name: string) => (t: Trace) => boolean;
-    readonly stub: boolean;
-    readonly available: () => boolean;
-}
 /** The injectable core (for tests): probe every model-invocable skill that has prompts. */
-export declare function probePluginTriggersWith(dir: string, promptSet: TriggerPromptSet, probe: HarnessProbe, opts?: ProbeOptions): Promise<BehavioralReport>;
+export declare function probePluginTriggersWith(dir: string, promptSet: TriggerPromptSet, live: HarnessLiveDriver, opts?: ProbeOptions): Promise<BehavioralReport>;
 /**
  * Probe a plugin's skills against the real harness (default Claude Code; Codex via
  * `opts.harness`). Needs that harness's binary + auth; degrades to
@@ -101,8 +88,21 @@ export interface SelectionOptions {
     readonly effort?: string | number;
     /** Parallel runs across the prompts × trials grid (default 1). */
     readonly concurrency?: number;
-    /** Which harness drives it (default `"claude-code"`; others report n/a). */
-    readonly harness?: ProbeHarness;
+    /** Which harness drives it — the adapter itself (default {@link defaultAdapter}).
+     *  A harness whose firing signal is INFERRED rather than a discrete event reports
+     *  n/a: the matrix asks WHICH skill fired, which an inference cannot answer. */
+    readonly adapter?: HarnessAdapter;
+    /**
+     * @deprecated Pass {@link SelectionOptions.adapter} instead. Kept for one
+     * release because this options type is public API (`vigiles/claude-code`);
+     * a name is resolved through the registry, never compared to a literal.
+     */
+    readonly harness?: string;
+    /** Layout + dialect for candidate discovery, mirroring {@link ProbeOptions} —
+     *  so a Codex repo's skills are found under the Codex layout, not silently
+     *  missed by the Claude Code one. */
+    readonly layout?: PluginLayout;
+    readonly dialect?: HarnessDialect;
 }
 /** One run's outcome for the matrix: which of the plugin's OWN skills fired. */
 interface SelectionRun {
@@ -142,8 +142,16 @@ export interface SelectionReport {
  * model-driving so it's unit-testable with synthetic runs (no model).
  */
 export declare function buildSelectionReport(skills: readonly string[], runs: readonly SelectionRun[]): SelectionReport;
-/** The injectable core (for tests): drive the matrix via a fake/real probe. */
-export declare function measurePluginSelectionWith(dir: string, promptSet: TriggerPromptSet, probe: HarnessProbe, opts?: SelectionOptions): Promise<SelectionReport>;
+/**
+ * The injectable core (for tests): drive the matrix via a fake/real driver.
+ *
+ * 🔴 IT TAKES AN {@link EventFiringDriver}, NOT ANY LIVE DRIVER, AND THAT IS THE
+ * RATCHET. The matrix asks WHICH of the plugin's skills fired on each prompt; a
+ * harness that only INFERS firing cannot answer that, and the old guard was a
+ * name check in the wrapper below — invisible to anyone calling this core
+ * directly. Now an inferred driver is a compile error at every call site.
+ */
+export declare function measurePluginSelectionWith(dir: string, promptSet: TriggerPromptSet, probe: EventFiringDriver, opts?: SelectionOptions): Promise<SelectionReport>;
 /**
  * Measure a plugin's cross-skill selection-collision matrix against the real
  * harness (Claude Code only — Codex has no skill-selection event). Needs the
@@ -181,7 +189,7 @@ export declare function measureSelectionMatrix(dir: string, opts?: SelectionMatr
  * Injectable core of {@link measureSelectionMatrix} (for tests): auto-derive the
  * prompts (unless supplied) and drive the matrix via a fake/real probe.
  */
-export declare function measureSelectionMatrixWith(dir: string, probe: HarnessProbe, opts?: SelectionMatrixOptions): Promise<SelectionReport>;
+export declare function measureSelectionMatrixWith(dir: string, probe: EventFiringDriver, opts?: SelectionMatrixOptions): Promise<SelectionReport>;
 /**
  * Assert a plugin's skills don't hijack each other — the gate over a
  * {@link SelectionReport} from {@link measureSelectionMatrix}. `maxOffDiagonal`
@@ -239,7 +247,8 @@ export interface GateOptions {
     readonly trials?: number;
     /** Concurrent harness runs (default 1). */
     readonly concurrency?: number;
-    readonly harness?: ProbeHarness;
+    /** Which harness drives it — the adapter itself (default {@link defaultAdapter}). */
+    readonly adapter?: HarnessAdapter;
     readonly layout?: PluginLayout;
     readonly dialect?: HarnessDialect;
     /** Author-supplied attack prompts (bare skill name → prompts); overrides derive. */