vigiles 2.4.0 → 2.6.0

package/dist/compile.js

@@ -16,6 +16,9 @@ exports.validateCommandRef = validateCommandRef;
 exports.validateSymbolRef = validateSymbolRef;
 exports.compileClaude = compileClaude;
 exports.compileSkill = compileSkill;
+exports.compileAgent = compileAgent;
+exports.validateRailway = validateRailway;
+exports.compileRailway = compileRailway;
 exports.checkFileHash = checkFileHash;
 exports.adoptDiff = adoptDiff;
 const node_fs_1 = require("node:fs");
@@ -641,6 +644,267 @@ function compileSkill(spec, options = {}) {
     const content = renderSkillFrontmatter(spec) + "\n\n" + sections.trim() + "\n";
     return { markdown: addHash(content, specFile), errors };
 }
+// ---------------------------------------------------------------------------
+// Compile a subagent spec → agents/<name>.md
+// ---------------------------------------------------------------------------
+// The tool contract a subagent may declare — the rails it runs on. Anything
+// else must be an MCP tool (mcp__server__tool), else it's a typo / nonexistent
+// tool the dispatched worker could never call.
+const KNOWN_AGENT_TOOLS = [
+    "Read",
+    "Write",
+    "Edit",
+    "Bash",
+    "Grep",
+    "Glob",
+    "WebSearch",
+    "WebFetch",
+    "NotebookEdit",
+    "TodoWrite",
+    "Task",
+    "Skill",
+];
+const MCP_TOOL_RE = /^mcp__[a-z0-9_-]+__[a-z0-9_-]+$/i;
+// Tools the platform never exposes to a subagent, whatever the list says — so a
+// subagent listing one is a guaranteed-dead reference only a compiler catches.
+const NEVER_AVAILABLE_TOOLS = new Set([
+    "Agent",
+    "AskUserQuestion",
+    "EnterPlanMode",
+    "ExitPlanMode",
+    "ScheduleWakeup",
+    "WaitForMcpServers",
+]);
+/** Closest known tool by edit distance (≤ 3), for a "did you mean" hint. */
+function closestTool(tool) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const known of KNOWN_AGENT_TOOLS) {
+        const d = (0, linters_js_1.editDistance)(tool.toLowerCase(), known.toLowerCase());
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = known;
+        }
+    }
+    return bestDistance <= 3 ? best : null;
+}
+/** Verify a subagent's allowed-tools contract — the rails are real tools. */
+function validateAgentTools(tools) {
+    const errors = [];
+    for (const tool of tools) {
+        if (NEVER_AVAILABLE_TOOLS.has(tool)) {
+            errors.push({
+                type: "unknown-tool",
+                message: `Tool "${tool}" is never available to a subagent — remove it from the tools list.`,
+            });
+            continue;
+        }
+        if (KNOWN_AGENT_TOOLS.includes(tool))
+            continue;
+        if (MCP_TOOL_RE.test(tool))
+            continue;
+        const near = closestTool(tool);
+        const hint = near ? ` Did you mean "${near}"?` : "";
+        errors.push({
+            type: "unknown-tool",
+            message: `Unknown tool "${tool}" in agent tools — use a built-in tool (${KNOWN_AGENT_TOOLS.join(", ")}) or an MCP tool (mcp__server__tool).${hint}`,
+        });
+    }
+    return errors;
+}
+/** Build the subagent YAML frontmatter (name / description / model / tools). */
+function renderAgentFrontmatter(spec) {
+    const fm = [
+        "---",
+        "",
+        `name: ${spec.name}`,
+        `description: ${spec.description}`,
+    ];
+    if (spec.model !== undefined)
+        fm.push(`model: ${spec.model}`);
+    if (spec.tools && spec.tools.length > 0) {
+        fm.push(`tools: ${spec.tools.join(", ")}`);
+    }
+    fm.push("", "---");
+    return fm.join("\n");
+}
+/** Render the subagent's named `##` system-prompt sections (verified like CLAUDE.md). */
+function renderAgentSections(sections, basePath) {
+    const lines = [];
+    const errors = [];
+    for (const [name, content] of Object.entries(sections)) {
+        if (name.toLowerCase() === "rules") {
+            errors.push({
+                type: "reserved-section-key",
+                message: `Section key "${name}" is reserved — use the \`rules\` field instead.`,
+            });
+        }
+        const heading = name.charAt(0).toUpperCase() + name.slice(1);
+        if (typeof content === "string") {
+            errors.push(...validateSectionContent(name, content));
+            lines.push(`## ${heading}\n\n${content.trim()}`);
+        }
+        else {
+            errors.push(...validateRefs(content, basePath));
+            const rendered = content.map(renderFragment).join("");
+            errors.push(...validateSectionContent(name, rendered));
+            lines.push(`## ${heading}\n\n${rendered.trim()}`);
+        }
+    }
+    return { lines, errors };
+}
+/** Render a result-contract track shape as a compact `{ "f": type, … }` line. */
+function renderShape(shape) {
+    const fields = Object.entries(shape)
+        .map(([k, t]) => `"${k}": ${t}`)
+        .join(", ");
+    return fields ? `{ ${fields} }` : "{}";
+}
+/**
+ * Render the subagent's typed result contract — the `## Output contract` section
+ * that turns a flat worker into a railway step: it must end its turn with a
+ * `vigiles:ok` / `vigiles:err` block matching one of these shapes, so its
+ * outcome is parseable (`parseAgentResult`) and testable (`assertAgentOk`).
+ */
+function renderOutputContract(contract) {
+    return [
+        "## Output contract",
+        "",
+        "Finish your turn with exactly one fenced block — success or error — matching one of these shapes.",
+        "",
+        "On success:",
+        "",
+        "```vigiles:ok",
+        renderShape(contract.ok),
+        "```",
+        "",
+        "On error:",
+        "",
+        "```vigiles:err",
+        renderShape(contract.err),
+        "```",
+    ].join("\n");
+}
+/** Render the rules a subagent must follow as a `## Rules` section. */
+function renderAgentRules(rules) {
+    const parts = ["## Rules", ""];
+    for (const [id, rule] of Object.entries(rules)) {
+        parts.push(compileRule(id, rule), "");
+    }
+    return parts.join("\n").trim();
+}
+/**
+ * Compile an AgentSpec into a subagent markdown file with YAML frontmatter.
+ * Verifies the tool contract and the body's references; the marks the body
+ * carries (`vigiles:symbol`, file/cmd refs) are the same ones `audit` re-checks.
+ */
+function compileAgent(spec, options = {}) {
+    const basePath = options.basePath ?? process.cwd();
+    const specFile = options.specFile ?? "agent.md.spec.ts";
+    const errors = [];
+    if (!specFile.endsWith(".spec.ts")) {
+        errors.push({
+            type: "spec-name-mismatch",
+            message: `Spec file "${specFile}" must end with .spec.ts`,
+        });
+    }
+    else if (!/\.md$/i.test((0, node_path_1.basename)(specFile, ".spec.ts"))) {
+        errors.push({
+            type: "spec-name-mismatch",
+            message: `Spec file "${specFile}" should be named <output>.spec.ts (e.g., agents/reviewer.md.spec.ts)`,
+        });
+    }
+    if (spec.tools)
+        errors.push(...validateAgentTools(spec.tools));
+    if (Array.isArray(spec.body)) {
+        errors.push(...validateRefs(spec.body, basePath));
+    }
+    const sections = [];
+    if (spec.body !== undefined)
+        sections.push(renderBody(spec.body).trim());
+    if (spec.sections) {
+        const result = renderAgentSections(spec.sections, basePath);
+        sections.push(...result.lines);
+        errors.push(...result.errors);
+    }
+    if (spec.rules && Object.keys(spec.rules).length > 0) {
+        sections.push(renderAgentRules(spec.rules));
+    }
+    if (spec.output)
+        sections.push(renderOutputContract(spec.output));
+    const body = sections.join("\n\n");
+    errors.push(...checkInlineCode(body, DEFAULT_MAX_INLINE_CODE_LINES));
+    const content = renderAgentFrontmatter(spec) + "\n\n" + body.trim() + "\n";
+    return { markdown: addHash(content, specFile), errors };
+}
+/** Verify a railway: non-empty, bounded recovery, every delegate target real. */
+function validateRailway(rw, knownAgents) {
+    const errors = [];
+    if (rw.steps.length === 0) {
+        errors.push({
+            type: "invalid-railway",
+            message: `Railway "${rw.name}" has no steps.`,
+        });
+    }
+    if (rw.recover && rw.recover.max < 1) {
+        errors.push({
+            type: "invalid-railway",
+            message: `Railway "${rw.name}" recover.max must be ≥ 1 (got ${String(rw.recover.max)}).`,
+        });
+    }
+    if (knownAgents) {
+        const known = new Set(knownAgents);
+        const refs = [...rw.steps];
+        if (rw.onError)
+            refs.push(rw.onError);
+        if (rw.recover)
+            refs.push(rw.recover.step);
+        for (const s of refs) {
+            if (!known.has(s.agent)) {
+                errors.push({
+                    type: "stale-ref",
+                    message: `Railway "${rw.name}" delegates to unknown agent "${s.agent}".`,
+                    path: s.agent,
+                });
+            }
+        }
+    }
+    return errors;
+}
+/** Render the orchestrator command markdown for a railway. */
+function renderRailwayMarkdown(rw) {
+    const lines = [
+        `# Railway: ${rw.name}`,
+        "",
+        "Dispatch these subagents on the **success track**, in order. Each returns a " +
+            "result block (`vigiles:ok` / `vigiles:err`). If a step returns an error, " +
+            "stop the success track and run the error handler with that error payload.",
+        "",
+        "## Success track",
+        "",
+    ];
+    rw.steps.forEach((s, i) => {
+        const task = s.task ? ` — ${s.task}` : "";
+        lines.push(`${String(i + 1)}. **${s.agent}**${task}`);
+    });
+    if (rw.recover) {
+        lines.push("", "## Recovery", "", `If a step errors, retry it via **${rw.recover.step.agent}** up to ${String(rw.recover.max)}× before falling to the error track.`);
+    }
+    if (rw.onError) {
+        lines.push("", "## On error", "", `Run **${rw.onError.agent}** with the failing step's error payload.`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Compile a railway into an orchestrator command markdown (with integrity hash),
+ * resolving every delegate target against `knownAgents` when provided.
+ */
+function compileRailway(rw, options = {}) {
+    const errors = validateRailway(rw, options.knownAgents);
+    const specFile = options.specFile ?? `${rw.name}.railway.spec.ts`;
+    const content = renderRailwayMarkdown(rw) + "\n";
+    return { markdown: addHash(content, specFile), errors };
+}
 /** Check if a generated file's hash is intact. */
 function checkFileHash(filePath) {
     if (!(0, node_fs_1.existsSync)(filePath)) {
@@ -673,6 +937,10 @@ function adoptDiff(filePath, spec, basePath) {
         const { markdown } = compileSkill(spec, { basePath, specFile: filePath });
         compiledContent = markdown;
     }
+    else if (spec._specType === "agent") {
+        const { markdown } = compileAgent(spec, { basePath, specFile: filePath });
+        compiledContent = markdown;
+    }
     // Simple line-based diff
     const currentLines = currentContent.replace(HASH_RE, "").split("\n");
     const compiledLines = (compiledContent ?? "")

package/dist/egress-proxy.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=egress-proxy.d.ts.map

package/dist/egress-proxy.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Recording egress proxy — runs INSIDE the sandbox netns (on loopback), so a
+ * confined hook configured with `HTTP(S)_PROXY` routes its network attempts here.
+ * It RECORDS each target (`host:port`) to an ndjson log and BLOCKS it (responds
+ * 502 / closes) — the netns already has no external route, so nothing actually
+ * leaves; this just turns "silently blocked" into "blocked AND recorded", so a
+ * test can assert what a hook/skill tried to reach (phone-home / which registry
+ * an install would hit).
+ *
+ * Honest limit: this records what PROXY-honoring tools (npm, pip, curl, fetch)
+ * attempt. Raw-socket egress bypasses the proxy — but the netns still blocks it
+ * hard, so it can't get out; it just won't appear in the record. The block is the
+ * boundary; the record is best-effort observability over it.
+ *
+ * Run as: `node dist/egress-proxy.js <egress-log-path> <port-file-path>`.
+ */
+/* v8 ignore start -- a standalone subprocess run only inside the sandbox netns;
+   exercised by the bwrap-gated end-to-end test, not the unit gate. The pure
+   parser (parseEgressLog) carries the testable logic. */
+const node_http_1 = require("node:http");
+const node_fs_1 = require("node:fs");
+const [, , logPath, portPath] = process.argv;
+function record(host, port) {
+    try {
+        (0, node_fs_1.appendFileSync)(logPath, JSON.stringify({ host, port, ts: Date.now() }) + "\n");
+    }
+    catch {
+        /* best-effort: a recording failure must not crash the hook under test */
+    }
+}
+const server = (0, node_http_1.createServer)((req, res) => {
+    // Plain HTTP via a proxy: req.url is absolute, e.g. http://host:port/path.
+    try {
+        const u = new URL(req.url ?? "");
+        record(u.hostname, Number(u.port) || 80);
+    }
+    catch {
+        /* unparseable target — skip */
+    }
+    res.writeHead(502, { "content-type": "text/plain" });
+    res.end("blocked by vigiles egress recorder\n");
+});
+// HTTPS via a proxy: the client sends `CONNECT host:port`. Record + refuse.
+server.on("connect", (req, socket) => {
+    const [host, port] = (req.url ?? "").split(":");
+    record(host, Number(port) || 443);
+    socket.write("HTTP/1.1 502 Blocked\r\n\r\n");
+    socket.end();
+});
+server.on("clientError", (_e, socket) => socket.destroy());
+server.listen(0, "127.0.0.1", () => {
+    const addr = server.address();
+    const port = typeof addr === "object" && addr ? addr.port : 0;
+    // Hand the chosen port back to the wrapper, which exports HTTP(S)_PROXY.
+    (0, node_fs_1.writeFileSync)(portPath, String(port));
+});
+/* v8 ignore stop */
+//# sourceMappingURL=egress-proxy.js.map

package/dist/eval-baseline.d.ts

@@ -0,0 +1,68 @@
+import type { EvalReport } from "./eval.js";
+import { type Comparison } from "./stats.js";
+/** Bumped only on a breaking change to the on-disk shape. */
+export declare const BASELINE_VERSION = 1;
+/** The committed baseline: the recorded `EvalReport`s, keyed by report name. */
+export interface BaselineFile {
+    readonly version: number;
+    /** ISO-8601 timestamp the baseline was recorded (provenance / future trend). */
+    readonly recordedAt: string;
+    /** Recorded reports, keyed by `report.name` (so multiple eval files coexist). */
+    readonly reports: Record<string, EvalReport>;
+}
+/** How a metric moved between baseline and current run. */
+export type DiffStatus = "regressed" | "improved" | "unchanged";
+/** One arm×metric comparison of a current run against the baseline. */
+export interface MetricDiff {
+    /** The `report.name` this entry belongs to. */
+    readonly report: string;
+    readonly arm: string;
+    readonly metric: string;
+    readonly status: DiffStatus;
+    /** Welch comparison, current vs. baseline (`delta = current − baseline`). */
+    readonly comparison: Comparison;
+}
+export interface BaselineDiff {
+    /** Every arm×metric present in BOTH the baseline and the current run. */
+    readonly entries: readonly MetricDiff[];
+    /** The subset that regressed (significant move in the bad direction). */
+    readonly regressions: readonly MetricDiff[];
+    /** The subset that improved (significant move in the good direction). */
+    readonly improvements: readonly MetricDiff[];
+    /** True when there are no regressions — the gate. */
+    readonly passed: boolean;
+}
+export interface DiffOptions {
+    /** Significance level for the Welch test. Default 0.05. */
+    readonly alpha?: number;
+    /**
+     * Metrics where a DECREASE is the improvement (e.g. `cost`, `latency`,
+     * `turns`). For these, a significant increase is the regression. Everything
+     * else is treated as higher-is-better.
+     */
+    readonly lowerIsBetter?: readonly string[];
+}
+/** Build a `BaselineFile` envelope from a run's reports (keyed by name). */
+export declare function toBaselineFile(reports: readonly EvalReport[], recordedAt?: string): BaselineFile;
+/** Parse + validate a baseline JSON string (throws on a bad version/shape). */
+export declare function parseBaselineFile(json: string): BaselineFile;
+/**
+ * Diff a current run against a committed baseline. Compares every arm×metric
+ * present in both (by report name), flagging a *significant* move in the
+ * undesired direction as a regression. Metrics absent from one side are skipped
+ * (a new arm/metric is not a regression).
+ */
+export declare function diffReports(baseline: BaselineFile, current: readonly EvalReport[], opts?: DiffOptions): BaselineDiff;
+/** Format a baseline diff as a compact console report. */
+export declare function formatBaselineDiff(diff: BaselineDiff): string;
+/**
+ * Render a baseline diff as JUnit XML — one `<testcase>` per arm×metric, a
+ * `<failure>` for each regression. Lets a CI provider show eval regressions in
+ * the same place as unit-test failures.
+ */
+export declare function diffToJUnit(diff: BaselineDiff): string;
+/** Read + parse a baseline file, or null if it doesn't exist yet. */
+export declare function readBaseline(path: string): BaselineFile | null;
+/** Write reports as the committed baseline (pretty JSON, parent dirs created). */
+export declare function writeBaseline(path: string, reports: readonly EvalReport[]): void;
+//# sourceMappingURL=eval-baseline.d.ts.map

package/dist/eval-baseline.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASELINE_VERSION = void 0;
+exports.toBaselineFile = toBaselineFile;
+exports.parseBaselineFile = parseBaselineFile;
+exports.diffReports = diffReports;
+exports.formatBaselineDiff = formatBaselineDiff;
+exports.diffToJUnit = diffToJUnit;
+exports.readBaseline = readBaseline;
+exports.writeBaseline = writeBaseline;
+/**
+ * vigiles — eval regression gating (Phase C).
+ *
+ * The eval tier reports mean ± se per arm; `src/stats.ts` turns a gap into a
+ * significance verdict. This module points that machinery at a *committed
+ * baseline*: record one run's `EvalReport`s to `.vigiles/eval-baseline.json`,
+ * then on a later run flag any arm×metric that moved **significantly in the bad
+ * direction** vs. that baseline. "jest snapshots for agent behaviour, with a real
+ * noise floor" — a bare pass-rate can't tell a true regression from sampling
+ * noise, but a Welch t-test over the two runs' summary stats can.
+ *
+ * Pure + model-free (the diff/serialize/JUnit are fully unit-tested); the only
+ * side effects are the two small fs helpers (`readBaseline` / `writeBaseline`).
+ * Reuses `welchTTest` from `src/stats.ts` — the current run is the "arm", the
+ * baseline is the "baseline", so `delta = current − baseline`.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const stats_js_1 = require("./stats.js");
+/** Bumped only on a breaking change to the on-disk shape. */
+exports.BASELINE_VERSION = 1;
+/** Build a `BaselineFile` envelope from a run's reports (keyed by name). */
+function toBaselineFile(reports, recordedAt = new Date().toISOString()) {
+    const byName = {};
+    for (const r of reports)
+        byName[r.name] = r;
+    return { version: exports.BASELINE_VERSION, recordedAt, reports: byName };
+}
+/** Parse + validate a baseline JSON string (throws on a bad version/shape). */
+function parseBaselineFile(json) {
+    const data = JSON.parse(json);
+    if (typeof data !== "object" || data === null) {
+        throw new Error("baseline: expected a JSON object");
+    }
+    const obj = data;
+    if (obj.version !== exports.BASELINE_VERSION) {
+        throw new Error(`baseline: unsupported version ${String(obj.version)} (expected ${String(exports.BASELINE_VERSION)})`);
+    }
+    if (typeof obj.reports !== "object" || obj.reports === null) {
+        throw new Error("baseline: missing `reports`");
+    }
+    return {
+        version: exports.BASELINE_VERSION,
+        recordedAt: typeof obj.recordedAt === "string" ? obj.recordedAt : "",
+        reports: obj.reports,
+    };
+}
+/** Classify one comparison given the metric's direction. */
+function classify(cmp, lowerIsBetter) {
+    if (!cmp.significant || cmp.delta === 0)
+        return "unchanged";
+    const improved = lowerIsBetter ? cmp.delta < 0 : cmp.delta > 0;
+    return improved ? "improved" : "regressed";
+}
+/** Append a diff entry for every arm×metric common to both reports. */
+function collectReportDiffs(baseline, current, cfg, out) {
+    for (const [arm, curArm] of Object.entries(current.arms)) {
+        const baseArm = baseline.arms[arm];
+        if (!baseArm)
+            continue;
+        for (const [metric, curStat] of Object.entries(curArm.stats)) {
+            const baseStat = baseArm.stats[metric];
+            if (!baseStat)
+                continue;
+            const comparison = (0, stats_js_1.welchTTest)(curStat, baseStat, cfg.alpha);
+            out.push({
+                report: current.name,
+                arm,
+                metric,
+                status: classify(comparison, cfg.lower.has(metric)),
+                comparison,
+            });
+        }
+    }
+}
+/**
+ * Diff a current run against a committed baseline. Compares every arm×metric
+ * present in both (by report name), flagging a *significant* move in the
+ * undesired direction as a regression. Metrics absent from one side are skipped
+ * (a new arm/metric is not a regression).
+ */
+function diffReports(baseline, current, opts = {}) {
+    const cfg = {
+        alpha: opts.alpha ?? 0.05,
+        lower: new Set(opts.lowerIsBetter ?? []),
+    };
+    const entries = [];
+    for (const cur of current) {
+        const base = baseline.reports[cur.name];
+        if (base)
+            collectReportDiffs(base, cur, cfg, entries);
+    }
+    const regressions = entries.filter((e) => e.status === "regressed");
+    const improvements = entries.filter((e) => e.status === "improved");
+    return {
+        entries,
+        regressions,
+        improvements,
+        passed: regressions.length === 0,
+    };
+}
+const STATUS_MARK = {
+    regressed: "✗",
+    improved: "✓",
+    unchanged: "·",
+};
+function formatDelta(c) {
+    const sign = c.delta >= 0 ? "+" : "";
+    return `Δ=${sign}${c.delta.toFixed(3)} p=${c.pValue.toFixed(3)}`;
+}
+/** Format a baseline diff as a compact console report. */
+function formatBaselineDiff(diff) {
+    const head = diff.passed
+        ? "baseline OK — no significant regressions"
+        : `baseline FAIL — ${String(diff.regressions.length)} regression(s)`;
+    const lines = [head];
+    for (const e of diff.entries) {
+        lines.push(`  ${STATUS_MARK[e.status]} ${e.report}/${e.arm}/${e.metric}  ${formatDelta(e.comparison)}`);
+    }
+    return lines.join("\n");
+}
+function xmlEscape(s) {
+    return s
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function junitCase(e) {
+    const name = xmlEscape(`${e.report}.${e.arm}.${e.metric}`);
+    const open = `  <testcase classname="${xmlEscape(e.report)}" name="${name}">`;
+    if (e.status !== "regressed")
+        return `${open}</testcase>`;
+    const msg = xmlEscape(`regression: ${formatDelta(e.comparison)}`);
+    return `${open}\n    <failure message="${msg}"/>\n  </testcase>`;
+}
+/**
+ * Render a baseline diff as JUnit XML — one `<testcase>` per arm×metric, a
+ * `<failure>` for each regression. Lets a CI provider show eval regressions in
+ * the same place as unit-test failures.
+ */
+function diffToJUnit(diff) {
+    const cases = diff.entries.map(junitCase).join("\n");
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<testsuite name="vigiles-eval" tests="${String(diff.entries.length)}" failures="${String(diff.regressions.length)}">`,
+        cases,
+        "</testsuite>",
+        "",
+    ].join("\n");
+}
+/** Read + parse a baseline file, or null if it doesn't exist yet. */
+function readBaseline(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    return parseBaselineFile((0, node_fs_1.readFileSync)(path, "utf-8"));
+}
+/** Write reports as the committed baseline (pretty JSON, parent dirs created). */
+function writeBaseline(path, reports) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, JSON.stringify(toBaselineFile(reports), null, 2) + "\n");
+}
+//# sourceMappingURL=eval-baseline.js.map

package/dist/eval-cache.d.ts

@@ -0,0 +1,33 @@
+import { type SHA256Hash } from "./hash.js";
+import type { RunOut } from "./eval.js";
+/** Cache behaviour: never touch the cache / read-only / read-and-write. */
+export type CacheMode = "off" | "read" | "readwrite";
+/** Everything that determines a trial's model output (the cache key inputs). */
+export interface CacheKeyInput {
+    readonly task: string;
+    readonly model: string;
+    readonly tools: readonly string[];
+    /** The resolved fixture + arm + plugin files written before the run. */
+    readonly files: Record<string, string>;
+    /** The resolved `.claude/settings.json` for the arm (or undefined). */
+    readonly settings: unknown;
+    /** Which trial this is — distinct trials are distinct samples, cached apart. */
+    readonly trialIndex: number;
+}
+/** A recorded trial: its raw output plus the post-run cwd snapshot. */
+export interface CacheRecord {
+    readonly out: RunOut;
+    /** Text files present in the cwd after the run (relative path → contents). */
+    readonly files: Record<string, string>;
+}
+/** Deterministic content hash of the key inputs (order-independent). */
+export declare function cacheKey(input: CacheKeyInput): SHA256Hash;
+/** Read a cached record by key, or null on miss / unreadable / malformed. */
+export declare function readCache(dir: string, key: SHA256Hash): CacheRecord | null;
+/** Write a cached record by key (creating the cache dir as needed). */
+export declare function writeCache(dir: string, key: SHA256Hash, record: CacheRecord): void;
+/** Snapshot the text files under `cwd` as `relativePath → contents` (bounded). */
+export declare function snapshotDir(cwd: string): Record<string, string>;
+/** Restore a snapshot into `cwd`, recreating directories as needed. */
+export declare function restoreDir(cwd: string, files: Record<string, string>): void;
+//# sourceMappingURL=eval-cache.d.ts.map