vigiles 2.5.0 → 3.0.0

package/dist/adapters/claude-code/run-hook.js

@@ -0,0 +1,418 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseHookOutput = parseHookOutput;
+exports.decideHook = decideHook;
+exports.runHookWith = runHookWith;
+exports.egressRoutes = egressRoutes;
+exports.runHook = runHook;
+/**
+ * vigiles — the *unit* tier for Claude Code hooks.
+ *
+ * A hook is just a process: Claude Code pipes a JSON event to its stdin and
+ * reads back an exit code (0 ok, 2 = block) and, optionally, a JSON decision on
+ * stdout. `runHook` exercises exactly that contract directly — no `claude`
+ * binary, no model, no sandbox — so a hook's logic can be unit-tested in
+ * milliseconds:
+ *
+ *   const r = runHook('"$GUARD" ', {
+ *     hook_event_name: "PreToolUse",
+ *     tool_name: "Bash",
+ *     tool_input: { command: "git commit --no-verify" },
+ *   }, { env: { GUARD: guardPath } });
+ *   assert.ok(r.blocked);            // exit 2 / decision:block / permission:deny
+ *
+ * Why this exists alongside `runHarnessTest`:
+ *   - It is the cheap base of the pyramid — no CLI dependency, runs anywhere.
+ *   - It reaches every event. The deterministic `runHarnessTest` mock can drive
+ *     SessionStart/Stop/UserPromptSubmit/Bash PreToolUse|PostToolUse, but NOT
+ *     Edit/Write tool events (headless-gated), PreCompact, Notification,
+ *     SessionEnd, or SubagentStop. At this tier you hand the hook the event
+ *     JSON yourself, so all of them are testable.
+ *
+ * It does NOT prove the hook is *wired* into the harness (that the settings
+ * point at it, that `${CLAUDE_PLUGIN_ROOT}` resolves) — that is what the
+ * `plugin:` loader + `runHarnessTest` cover. Use both: unit-test the hook's
+ * logic here, then assert it fires in the assembled machine there.
+ */
+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 hook_protocol_js_1 = require("./hook-protocol.js");
+const egress_js_1 = require("./egress.js");
+const sandbox_js_1 = require("./sandbox.js");
+/** Parse stdout as a hook JSON decision (pure, testable without a process). */
+function parseHookOutput(stdout) {
+    const s = stdout.trim();
+    if (!s.startsWith("{"))
+        return null;
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide whether a hook result blocked, and the normalized decision. Pure, so
+ * the policy is unit-testable independent of spawning anything.
+ */
+function decideHook(exitCode, json, protocol = hook_protocol_js_1.claudeCodeHookProtocol) {
+    const permission = json?.hookSpecificOutput?.permissionDecision;
+    const decision = permission ?? json?.decision;
+    const blocked = exitCode === protocol.blockExitCode ||
+        (decision !== undefined && protocol.denyDecisionValues.includes(decision));
+    return { blocked, decision };
+}
+/**
+ * The hook-run orchestration with injectable spawn seams: pick direct vs.
+ * confined via the safe-by-default policy (`decideSandbox`), then parse the exit
+ * code + stdout into a normalized decision. Exported so all three branches
+ * (direct / sandbox / refuse) are unit-tested with fake spawners — no real
+ * bwrap. `runHook` is this with the real seams.
+ */
+function runHookWith(command, input, opts, deps) {
+    // Allowlisted egress is its own confined path (bwrap netns + slirp4netns + nft);
+    // it can't run unconfined, so it refuses outright when the tooling is absent
+    // rather than falling back to a direct run that would ignore the allowlist.
+    const res = opts.egress
+        ? runEgress(command, input, opts, deps)
+        : runConfinedOrDirect(command, input, opts, deps);
+    const exitCode = res.status ?? (res.signal ? 1 : 0);
+    const stdout = res.stdout ?? "";
+    const stderr = res.stderr ?? "";
+    const json = parseHookOutput(stdout);
+    const { blocked, decision: dec } = decideHook(exitCode, json);
+    return {
+        exitCode,
+        stdout,
+        stderr,
+        json,
+        blocked,
+        egress: res.egress ?? [],
+        egressDropped: res.egressDropped,
+        filesWritten: res.filesWritten ?? [],
+        decision: dec,
+    };
+}
+/** The allowlisted-egress branch: confine-with-netns, or refuse if unavailable. */
+function runEgress(command, input, opts, deps) {
+    if (!deps.egressAvailable) {
+        throw new Error("refusing to run egress: { allow } without the allowlist sandbox: it " +
+            "needs Linux + bubblewrap (bwrap) + slirp4netns + nft — install them to " +
+            "run with a packet-layer egress allowlist, or use recordEgress to record " +
+            "and block instead");
+    }
+    return deps.egress(command, input, opts);
+}
+/** The default branch: pick direct vs. confined via the safe-by-default policy. */
+function runConfinedOrDirect(command, input, opts, deps) {
+    // Confinement follows provenance: a trusted hook (the default) runs directly;
+    // marking a hook untrusted defaults it to "auto" (confine-or-refuse), so
+    // foreign code is never run unconfined by accident. An explicit `sandbox`
+    // overrides the default either way. The trust fed to decideSandbox stays
+    // `false` at this tier — a raw command has no provenance, so an explicit
+    // "auto"/"strict" here is always a request to *confine*, not "trusted→direct".
+    // recordEgress needs the netns recorder, so it forces confinement too.
+    const mode = opts.sandbox ??
+        (opts.trusted === false || opts.recordEgress ? "auto" : false);
+    const decision = (0, sandbox_js_1.decideSandbox)({
+        trusted: false,
+        mode,
+        available: deps.available,
+    });
+    if (decision.action === "throw")
+        throw new Error(decision.reason);
+    return decision.action === "sandbox"
+        ? deps.sandboxed(command, input, opts)
+        : deps.direct(command, input, opts);
+}
+/** Run the hook command directly through a shell (the default, unconfined). */
+function directSpawn(command, input, opts) {
+    const res = (0, node_child_process_1.spawnSync)(command, {
+        shell: true,
+        cwd: opts.cwd,
+        env: { ...process.env, ...opts.env },
+        input: JSON.stringify(input),
+        encoding: "utf-8",
+        timeout: opts.timeoutMs ?? 10000,
+    });
+    return {
+        status: res.status,
+        signal: res.signal,
+        stdout: res.stdout ?? "",
+        stderr: res.stderr ?? "",
+    };
+}
+/* v8 ignore start -- spawns real bwrap; exercised by the bwrap-gated integration
+   test (skipped without bwrap). The decision logic is runHookWith (unit-tested
+   with fakes); the confinement argv is bwrapArgs/setenvArgs and the egress log
+   parse is parseEgressLog (all unit-tested). */
+// When recordEgress is on: co-launch the recorder on loopback, point HTTP(S)_PROXY
+// at it, run the hook, then stop it. Paths come in via env (no shell escaping).
+const EGRESS_WRAPPER = [
+    'node "$VIG_EGRESS_ENTRY" "$VIG_EGRESS_LOG" "$VIG_EGRESS_PORT" &',
+    "EPID=$!",
+    "i=0",
+    'while [ ! -s "$VIG_EGRESS_PORT" ] && [ "$i" -lt 100 ]; do sleep 0.05; i=$((i+1)); done',
+    'export HTTP_PROXY="http://127.0.0.1:$(cat "$VIG_EGRESS_PORT")"',
+    'export HTTPS_PROXY="$HTTP_PROXY" http_proxy="$HTTP_PROXY" https_proxy="$HTTP_PROXY"',
+    // Node's fetch (undici) ignores the proxy env unless this is set — without it a
+    // hook that uses fetch() (e.g. an update check) would bypass the recorder.
+    "export NODE_USE_ENV_PROXY=1",
+    'sh -c "$VIG_HOOK_CMD"',
+    "code=$?",
+    'kill "$EPID" 2>/dev/null',
+    'exit "$code"',
+].join("\n");
+function egressProxyEntry() {
+    return ([
+        (0, node_path_1.join)(__dirname, "egress-proxy.js"),
+        (0, node_path_1.join)(__dirname, "..", "dist", "egress-proxy.js"),
+    ].find((p) => (0, node_fs_1.existsSync)(p)) ?? (0, node_path_1.join)(__dirname, "egress-proxy.js"));
+}
+/** Map every file under `dir` to a content signature (size:mtime), recursively. */
+function snapshotTree(dir) {
+    const out = {};
+    const walk = (d, rel) => {
+        for (const name of (0, node_fs_1.readdirSync)(d)) {
+            const full = (0, node_path_1.join)(d, name);
+            const r = rel ? `${rel}/${name}` : name;
+            const st = (0, node_fs_1.statSync)(full);
+            if (st.isDirectory())
+                walk(full, r);
+            else
+                out[r] = `${String(st.size)}:${String(st.mtimeMs)}`;
+        }
+    };
+    try {
+        walk(dir, "");
+    }
+    catch {
+        /* dir removed mid-walk — best effort */
+    }
+    return out;
+}
+function sandboxedSpawn(command, input, opts) {
+    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-hook-sbx-"));
+    const home = (0, node_path_1.join)(ioDir, "home");
+    (0, node_fs_1.mkdirSync)(home);
+    // The hook's confined writable work dir: the caller's cwd if given, else a
+    // dedicated `work/` under the IO dir (kept separate from the egress log/home so
+    // those don't pollute the filesWritten diff).
+    const work = opts.cwd ?? (0, node_path_1.join)(ioDir, "work");
+    (0, node_fs_1.mkdirSync)(work, { recursive: true });
+    try {
+        const baseArgs = [
+            ...(0, sandbox_js_1.bwrapArgs)({
+                cwd: work,
+                ioDir,
+                home,
+                path: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+            }),
+            ...(0, sandbox_js_1.setenvArgs)(opts.env ?? {}),
+        ];
+        const spawnOpts = {
+            cwd: work,
+            env: process.env,
+            input: JSON.stringify(input),
+            encoding: "utf-8",
+            timeout: opts.timeoutMs ?? 10000,
+        };
+        const before = snapshotTree(work);
+        let res;
+        let egress = [];
+        if (opts.recordEgress) {
+            const egressLog = (0, node_path_1.join)(ioDir, "egress.ndjson");
+            const portFile = (0, node_path_1.join)(ioDir, "egress.port");
+            (0, node_fs_1.writeFileSync)(egressLog, "");
+            res = (0, node_child_process_1.spawnSync)("bwrap", [
+                ...baseArgs,
+                "--setenv",
+                "VIG_EGRESS_ENTRY",
+                egressProxyEntry(),
+                "--setenv",
+                "VIG_EGRESS_LOG",
+                egressLog,
+                "--setenv",
+                "VIG_EGRESS_PORT",
+                portFile,
+                "--setenv",
+                "VIG_HOOK_CMD",
+                command,
+                "sh",
+                "-c",
+                EGRESS_WRAPPER,
+            ], spawnOpts);
+            egress = (0, sandbox_js_1.parseEgressLog)((0, node_fs_1.existsSync)(egressLog) ? (0, node_fs_1.readFileSync)(egressLog, "utf-8") : "");
+        }
+        else {
+            res = (0, node_child_process_1.spawnSync)("bwrap", [...baseArgs, "sh", "-c", command], spawnOpts);
+        }
+        return {
+            status: res.status,
+            signal: res.signal,
+            stdout: res.stdout ?? "",
+            stderr: res.stderr ?? "",
+            egress,
+            filesWritten: (0, sandbox_js_1.diffTrees)(before, snapshotTree(work)),
+        };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(ioDir, { recursive: true, force: true });
+    }
+}
+function egressEntry() {
+    return ([
+        (0, node_path_1.join)(__dirname, "egress-entry.js"),
+        (0, node_path_1.join)(__dirname, "..", "dist", "egress-entry.js"),
+    ].find((p) => (0, node_fs_1.existsSync)(p)) ?? (0, node_path_1.join)(__dirname, "egress-entry.js"));
+}
+// Runs INSIDE the bwrap netns: block until the parent has attached slirp4netns
+// (the netready file), load the nft allowlist, run the hook with the event on its
+// stdin, then dump the nft counters to a bound file BEFORE exiting — the netns
+// (and its counters) die with this process, so the read-back must happen here.
+const EGRESS_ALLOW_WRAPPER = [
+    "i=0",
+    'while [ ! -s "$VIG_NETREADY" ] && [ "$i" -lt 400 ]; do sleep 0.05; i=$((i+1)); done',
+    'nft -f "$VIG_NFT" > "$VIG_IODIR/nfterr" 2>&1',
+    'sh -c "$VIG_HOOK" < "$VIG_EVENT"',
+    "code=$?",
+    'nft list chain inet vig output > "$VIG_COUNTERS" 2>/dev/null',
+    'exit "$code"',
+].join("\n");
+/** Read the orchestrator's result file, or a failed-run default if it's absent. */
+function readEgressResult(resultFile) {
+    return (0, node_fs_1.existsSync)(resultFile)
+        ? JSON.parse((0, node_fs_1.readFileSync)(resultFile, "utf-8"))
+        : { status: 1, signal: null, stdout: "", stderr: "", counters: "" };
+}
+function egressSpawn(command, input, opts) {
+    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-hook-egr-"));
+    const home = (0, node_path_1.join)(ioDir, "home");
+    (0, node_fs_1.mkdirSync)(home);
+    const work = opts.cwd ?? (0, node_path_1.join)(ioDir, "work");
+    (0, node_fs_1.mkdirSync)(work, { recursive: true });
+    try {
+        // Resolve the allowlist to IPs and the system resolvers, then generate the
+        // nft ruleset (pure helpers in src/egress.ts) — the packet-layer wall.
+        const files = {
+            ioDir,
+            netready: (0, node_path_1.join)(ioDir, "netready"),
+            nft: (0, node_path_1.join)(ioDir, "rules.nft"),
+            event: (0, node_path_1.join)(ioDir, "event.json"),
+            counters: (0, node_path_1.join)(ioDir, "counters.txt"),
+        };
+        const allow = (0, egress_js_1.resolveAllow)(opts.egress?.allow ?? []);
+        const resolvers = (0, egress_js_1.parseResolvers)((0, node_fs_1.existsSync)("/etc/resolv.conf")
+            ? (0, node_fs_1.readFileSync)("/etc/resolv.conf", "utf-8")
+            : "");
+        (0, node_fs_1.writeFileSync)(files.nft, (0, egress_js_1.buildEgressNft)({ allow, resolvers }));
+        (0, node_fs_1.writeFileSync)(files.event, JSON.stringify(input));
+        // The in-netns resolv.conf: only the routable resolvers (the host's may be a
+        // 127.0.0.53 stub the netns can't reach). Bound over /etc/resolv.conf below.
+        const resolvConf = (0, node_path_1.join)(ioDir, "resolv.conf");
+        (0, node_fs_1.writeFileSync)(resolvConf, resolvers.map((r) => `nameserver ${r}`).join("\n") + "\n");
+        const bwrapArgv = (0, egress_js_1.buildEgressBwrapArgv)({
+            base: (0, sandbox_js_1.bwrapArgs)({
+                cwd: work,
+                ioDir,
+                home,
+                path: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+            }),
+            setenv: (0, sandbox_js_1.setenvArgs)(opts.env ?? {}),
+            files,
+            command,
+            wrapper: EGRESS_ALLOW_WRAPPER,
+            resolvConf,
+        });
+        const configFile = (0, node_path_1.join)(ioDir, "config.json");
+        const resultFile = (0, node_path_1.join)(ioDir, "result.json");
+        (0, node_fs_1.writeFileSync)(configFile, JSON.stringify({
+            bwrapArgv,
+            slirpArgs: ["--configure", "--disable-host-loopback"],
+            // --config-net brings up the interface + host-derived routes in the
+            // target netns. The connector is slirp4netns by default (proven local);
+            // set VIGILES_EGRESS_CONNECTOR=pasta to use pasta (passt), which routes
+            // on hosted runners where slirp4netns's tap-attach fails.
+            pastaArgs: ["--config-net"],
+            connector: process.env.VIGILES_EGRESS_CONNECTOR === "pasta"
+                ? "pasta"
+                : "slirp4netns",
+            infoFile: (0, node_path_1.join)(ioDir, "info.json"),
+            readyFile: (0, node_path_1.join)(ioDir, "ready"),
+            netreadyFile: files.netready,
+            countersFile: files.counters,
+            resultFile,
+            timeoutMs: opts.timeoutMs ?? 30000,
+        }));
+        (0, node_child_process_1.spawnSync)("node", [egressEntry(), configFile], {
+            encoding: "utf-8",
+            timeout: (opts.timeoutMs ?? 30000) + 20000,
+        });
+        const result = readEgressResult(resultFile);
+        const { egress, egressDropped } = (0, egress_js_1.countersToResult)((0, egress_js_1.parseNftCounters)(result.counters), Date.now());
+        return {
+            status: result.status,
+            signal: result.signal,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            egress,
+            egressDropped,
+        };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(ioDir, { recursive: true, force: true });
+    }
+}
+const REAL_DEPS = {
+    available: (0, sandbox_js_1.sandboxAvailable)(),
+    egressAvailable: (0, egress_js_1.egressAvailable)((0, sandbox_js_1.sandboxAvailable)()),
+    direct: directSpawn,
+    sandboxed: sandboxedSpawn,
+    egress: egressSpawn,
+};
+/**
+ * Whether allowlisted egress can ACTUALLY route here — not just whether the tools
+ * exist. On GitHub-hosted runners bwrap+slirp4netns+nft are all present, yet
+ * slirp4netns fails to attach `tap0`: the netns has only `lo`, so nothing leaves
+ * and the egress assertions can't be exercised. Run a trivial hook in the egress
+ * sandbox and check a non-loopback interface came up; memoized (the capability is
+ * fixed per run). Gates the egress e2e tests so they run for real where egress
+ * works and SKIP — honestly — where it provably can't, instead of failing red.
+ * (slirp4netns → pasta is the fix that makes it route in CI too; see
+ * research/egress-sandbox-tooling.md.)
+ */
+let egressRoutesMemo;
+function egressRoutes() {
+    if (egressRoutesMemo !== undefined)
+        return egressRoutesMemo;
+    if (!(0, egress_js_1.egressAvailable)((0, sandbox_js_1.sandboxAvailable)()))
+        return (egressRoutesMemo = false);
+    try {
+        // The only reliable signal is the egress path itself: try to reach an
+        // allowlisted host and check a packet actually got out. Filesystem probes
+        // (/proc/net/dev) and `ip` are unreliable here — bwrap may bind the host
+        // /proc (so /proc/net shows host interfaces, a false positive) and `ip` isn't
+        // on the sandbox PATH. A real reach is namespace-accurate by construction.
+        const r = egressSpawn("curl -s -m 8 -o /dev/null https://example.com/ || true", { hook_event_name: "PreToolUse" }, { egress: { allow: ["example.com"] }, timeoutMs: 20000 });
+        egressRoutesMemo = (r.egress ?? []).some((e) => e.host === "example.com" && (e.packets ?? 0) > 0);
+    }
+    catch {
+        egressRoutesMemo = false;
+    }
+    return egressRoutesMemo;
+}
+/* v8 ignore stop */
+/**
+ * Run a hook command, piping `input` as JSON to its stdin, and report the exit
+ * code + parsed decision. Synchronous (so it can be used inside an eval's
+ * `measure` too). `command` is run through a shell, so the same command string a
+ * plugin ships (with args / env refs) works verbatim. Mark a hook you didn't
+ * write with `trusted: false` and it is confined by default (or pass `sandbox:
+ * "auto"` directly) — see {@link RunHookOptions.trusted}.
+ */
+function runHook(command, input, opts = {}) {
+    return runHookWith(command, input, opts, REAL_DEPS);
+}
+//# sourceMappingURL=run-hook.js.map

package/dist/adapters/claude-code/run-scripts.d.ts

@@ -0,0 +1,52 @@
+export type ScriptStatus = "pass" | "skip" | "fail";
+export interface ScriptRunResult {
+    readonly file: string;
+    readonly code: number;
+    readonly status: ScriptStatus;
+}
+/**
+ * Exit code a harness/eval script uses to report itself SKIPPED (e.g. the
+ * deterministic tier when `claude` isn't installed) — the autotools convention.
+ * The runner surfaces it as a loud `⊘ SKIPPED` instead of a silent `✓`, and a
+ * skip never fails the run. Scripts call `skip()` (vigiles/testing) to emit it.
+ */
+export declare const SKIP_EXIT_CODE = 77;
+/** Filename extensions accepted for harness/eval scripts (JS and TS). */
+export declare const SCRIPT_EXTS: readonly ["mjs", "cjs", "js", "mts", "cts", "ts"];
+/** Glob suffix matching every accepted script extension, e.g. `harness`. */
+export declare function scriptGlob(kind: "harness" | "eval"): string;
+/** Node runtime capabilities that decide how a TypeScript script is run. */
+export interface NodeCaps {
+    /** `tsx` is installed locally (the preferred, version-agnostic TS loader). */
+    readonly tsx: boolean;
+    /** Node supports `--experimental-strip-types` (>= 22.6). */
+    readonly stripTypes: boolean;
+}
+/**
+ * The `node` argv (after the binary) to run a single script. Plain JS runs
+ * directly; a TypeScript script picks `tsx` when available, else Node's native
+ * type stripping. Throws a clear, actionable error when neither is available.
+ * Pure — exported for testing.
+ */
+export declare function interpreterArgs(file: string, caps: NodeCaps): string[];
+/** Detect TS-running capabilities for a project root. */
+export declare function detectNodeCaps(cwd: string): NodeCaps;
+/**
+ * Expand the given path/glob patterns into concrete script files. A pattern
+ * that is an existing file passes through unchanged; anything else is treated
+ * as a glob. Falls back to `defaultGlob` when no patterns are given. Results
+ * are deduped and sorted; `node_modules` and `dist` are always ignored.
+ */
+export declare function discoverScripts(patterns: readonly string[], defaultGlob: string, cwd: string): string[];
+/**
+ * Run each script as `node <file>`, inheriting stdio so the script's own report
+ * streams to the console. `env` is merged over `process.env` for every child
+ * (e.g. `VIGILES_TRIALS`). Returns the per-file exit codes.
+ */
+export declare function runScripts(files: readonly string[], cwd: string, env?: NodeJS.ProcessEnv): ScriptRunResult[];
+/** Whether any script FAILED (a skip is not a failure). */
+export declare function anyFailed(results: readonly ScriptRunResult[]): boolean;
+/** One line per file + an explicit pass/skip/fail tally. Skips are SHOWN, never
+ * folded into "passed" — a `⊘ SKIPPED` is loud, not a silent green. */
+export declare function formatScriptSummary(results: readonly ScriptRunResult[]): string;
+//# sourceMappingURL=run-scripts.d.ts.map

package/dist/adapters/claude-code/run-scripts.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCRIPT_EXTS = exports.SKIP_EXIT_CODE = void 0;
+exports.scriptGlob = scriptGlob;
+exports.interpreterArgs = interpreterArgs;
+exports.detectNodeCaps = detectNodeCaps;
+exports.discoverScripts = discoverScripts;
+exports.runScripts = runScripts;
+exports.anyFailed = anyFailed;
+exports.formatScriptSummary = formatScriptSummary;
+/**
+ * vigiles — run harness-test / eval script files via the CLI.
+ *
+ * `vigiles test` and `vigiles eval` discover `*.harness.*` / `*.eval.*`
+ * scripts and run each as a child `node` process, so the two-tier
+ * harness-testing API (`src/harness-test.ts`, `src/eval.ts`) works as a CI
+ * command, not just `node x.mjs`. Scripts may be authored in **JavaScript**
+ * (`.mjs` / `.cjs` / `.js`) **or TypeScript** (`.ts` / `.mts` / `.cts`) — a TS
+ * script is run through `tsx` when installed, else Node's built-in type
+ * stripping (Node >= 22.6). The scripts import from the built `dist/`, so they
+ * also run standalone — the CLI just discovers, runs, and aggregates exit codes.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const glob_1 = require("glob");
+/**
+ * Exit code a harness/eval script uses to report itself SKIPPED (e.g. the
+ * deterministic tier when `claude` isn't installed) — the autotools convention.
+ * The runner surfaces it as a loud `⊘ SKIPPED` instead of a silent `✓`, and a
+ * skip never fails the run. Scripts call `skip()` (vigiles/testing) to emit it.
+ */
+exports.SKIP_EXIT_CODE = 77;
+function statusForCode(code) {
+    if (code === 0)
+        return "pass";
+    if (code === exports.SKIP_EXIT_CODE)
+        return "skip";
+    return "fail";
+}
+/** Filename extensions accepted for harness/eval scripts (JS and TS). */
+exports.SCRIPT_EXTS = ["mjs", "cjs", "js", "mts", "cts", "ts"];
+/** Glob suffix matching every accepted script extension, e.g. `harness`. */
+function scriptGlob(kind) {
+    return `**/*.${kind}.{${exports.SCRIPT_EXTS.join(",")}}`;
+}
+const TS_EXT = /\.(?:m|c)?ts$/;
+/**
+ * The `node` argv (after the binary) to run a single script. Plain JS runs
+ * directly; a TypeScript script picks `tsx` when available, else Node's native
+ * type stripping. Throws a clear, actionable error when neither is available.
+ * Pure — exported for testing.
+ */
+function interpreterArgs(file, caps) {
+    if (!TS_EXT.test(file))
+        return [file];
+    if (caps.tsx)
+        return ["--import", "tsx", file];
+    if (caps.stripTypes)
+        return ["--experimental-strip-types", file];
+    throw new Error(`Cannot run TypeScript test script "${file}": install tsx ` +
+        `(npm i -D tsx) or use Node >= 22.6, or author it as a .mjs file.`);
+}
+/** Detect TS-running capabilities for a project root. */
+function detectNodeCaps(cwd) {
+    const tsx = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "node_modules/tsx/package.json")) ||
+        (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "node_modules/.bin/tsx"));
+    const stripTypes = process.allowedNodeEnvironmentFlags.has("--experimental-strip-types");
+    return { tsx, stripTypes };
+}
+/**
+ * Expand the given path/glob patterns into concrete script files. A pattern
+ * that is an existing file passes through unchanged; anything else is treated
+ * as a glob. Falls back to `defaultGlob` when no patterns are given. Results
+ * are deduped and sorted; `node_modules` and `dist` are always ignored.
+ */
+function discoverScripts(patterns, defaultGlob, cwd) {
+    const globs = patterns.length > 0 ? patterns : [defaultGlob];
+    const found = new Set();
+    for (const p of globs) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, p))) {
+            found.add(p);
+            continue;
+        }
+        for (const m of (0, glob_1.globSync)(p, {
+            cwd,
+            ignore: ["node_modules/**", "dist/**"],
+        })) {
+            found.add(m);
+        }
+    }
+    return [...found].sort();
+}
+/**
+ * Run each script as `node <file>`, inheriting stdio so the script's own report
+ * streams to the console. `env` is merged over `process.env` for every child
+ * (e.g. `VIGILES_TRIALS`). Returns the per-file exit codes.
+ */
+function runScripts(files, cwd, env = {}) {
+    const caps = detectNodeCaps(cwd);
+    const results = [];
+    for (const file of files) {
+        let argv;
+        try {
+            argv = interpreterArgs(file, caps);
+        }
+        catch (e) {
+            console.error(`✗ ${file}: ${e.message}`);
+            results.push({ file, code: 1, status: "fail" });
+            continue;
+        }
+        const res = (0, node_child_process_1.spawnSync)("node", argv, {
+            cwd,
+            stdio: "inherit",
+            env: { ...process.env, ...env },
+        });
+        const code = res.status ?? 1;
+        results.push({ file, code, status: statusForCode(code) });
+    }
+    return results;
+}
+/** Whether any script FAILED (a skip is not a failure). */
+function anyFailed(results) {
+    return results.some((r) => r.status === "fail");
+}
+const MARK = {
+    pass: "✓",
+    skip: "⊘",
+    fail: "✗",
+};
+/** One line per file + an explicit pass/skip/fail tally. Skips are SHOWN, never
+ * folded into "passed" — a `⊘ SKIPPED` is loud, not a silent green. */
+function formatScriptSummary(results) {
+    const lines = results.map((r) => {
+        if (r.status === "skip")
+            return `  ⊘ ${r.file} — SKIPPED`;
+        if (r.status === "fail")
+            return `  ✗ ${r.file} (exit ${String(r.code)})`;
+        return `  ${MARK.pass} ${r.file}`;
+    });
+    const n = (s) => results.filter((r) => r.status === s).length;
+    const parts = [`${String(n("pass"))} passed`];
+    if (n("skip") > 0)
+        parts.push(`${String(n("skip"))} skipped`);
+    if (n("fail") > 0)
+        parts.push(`${String(n("fail"))} failed`);
+    lines.push(`\n${parts.join(", ")}.`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=run-scripts.js.map

package/dist/adapters/claude-code/runtime.d.ts

@@ -0,0 +1,16 @@
+/**
+ * claudeCodeRuntime — the Claude Code `HarnessRuntime` (spawn `claude`, reach the
+ * mock via `ANTHROPIC_BASE_URL` with a dummy `ANTHROPIC_API_KEY`). The runners
+ * (`harness-test.ts`, `eval.ts`) read the binary + env from here instead of
+ * hard-coding them; a Codex adapter defines `codexRuntime` and its runner uses it.
+ */
+import type { HarnessRuntime } from "../../core/runtime.js";
+export declare const claudeCodeRuntime: HarnessRuntime;
+/**
+ * Build the spawn env that points the agent CLI at the mock model: the caller's
+ * environment plus the runtime's base-URL var (→ the mock's URL) and a dummy
+ * API key. Pure (no spawn), so it's unit-tested directly — the testable seam of
+ * the otherwise un-coverable real-subprocess path.
+ */
+export declare function mockModelEnv(runtime: HarnessRuntime, baseUrl: string, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/adapters/claude-code/runtime.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeRuntime = void 0;
+exports.mockModelEnv = mockModelEnv;
+exports.claudeCodeRuntime = {
+    name: "claude-code",
+    agentBinary: "claude",
+    modelBaseUrlEnv: "ANTHROPIC_BASE_URL",
+    modelApiKeyEnv: "ANTHROPIC_API_KEY",
+    mockApiKey: "sk-vigiles-mock",
+    /**
+     * Claude Code reaches the mock purely through env (no argv flags): the
+     * base-URL var + a dummy key. The returned `env` is the overlay the runner
+     * layers over `process.env`, so the spawn env is identical to `mockModelEnv`.
+     */
+    wireMock(baseUrl) {
+        return {
+            args: [],
+            env: {
+                [exports.claudeCodeRuntime.modelBaseUrlEnv]: baseUrl,
+                [exports.claudeCodeRuntime.modelApiKeyEnv]: exports.claudeCodeRuntime.mockApiKey,
+            },
+        };
+    },
+};
+/**
+ * Build the spawn env that points the agent CLI at the mock model: the caller's
+ * environment plus the runtime's base-URL var (→ the mock's URL) and a dummy
+ * API key. Pure (no spawn), so it's unit-tested directly — the testable seam of
+ * the otherwise un-coverable real-subprocess path.
+ */
+function mockModelEnv(runtime, baseUrl, base = process.env) {
+    return {
+        ...base,
+        [runtime.modelBaseUrlEnv]: baseUrl,
+        [runtime.modelApiKeyEnv]: runtime.mockApiKey,
+    };
+}
+//# sourceMappingURL=runtime.js.map