@kylecheng3146/agent-ops 0.9.0 → 0.10.0

package/dist/runtime/src/escape/link.js

@@ -0,0 +1,317 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readdir, readFile, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { NOTES_REF } from "../parallel/service.js";
+import { readPrivateFile } from "../security/permissions.js";
+import { globMatcher, isCovers } from "../surface/schema.js";
+import { collectBaseChangePaths, collectChangeSurface } from "../verify/change-surface.js";
+import { RECEIPT_ID, validOrigin } from "./origin.js";
+import { fixPaths, gitRunner, proveEscape } from "./rules.js";
+/** Git-tracked, data only: one record per task so parallel worktrees never conflict. */
+export const LEDGER_DIRECTORY = ".agent-ops-escapes";
+const out = (result) => new TextDecoder().decode(result.stdout);
+function gitFailed(what) {
+    throw new AgentOpsError("ESCAPE_GIT_FAILED", `git ${what} failed while linking the escape.`);
+}
+/** Resolve a declared commit-ish to its full SHA (argv only), then validate the whole origin. */
+export async function resolveOrigin(git, value) {
+    const raw = typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+    let origin = raw;
+    if (raw.kind === "escape-of") {
+        const ref = raw.commit;
+        if (typeof ref !== "string" || !/^[A-Za-z0-9._/^~][A-Za-z0-9._/^~-]{0,255}$/u.test(ref))
+            throw new AgentOpsError("ESCAPE_ORIGIN_INVALID", "escape-of needs a commit.");
+        const resolved = await git.run(["rev-parse", "--verify", "--quiet", "--end-of-options", `${ref}^{commit}`]);
+        if (resolved.exitCode !== 0)
+            throw new AgentOpsError("ESCAPE_ORIGIN_INVALID", `Commit ${ref} does not exist in this repository.`);
+        origin = { ...raw, commit: out(resolved).trim() };
+        if (raw.fix !== undefined) {
+            if (typeof raw.fix !== "string" || !/^[A-Za-z0-9._/^~][A-Za-z0-9._/^~-]{0,255}$/u.test(raw.fix))
+                throw new AgentOpsError("ESCAPE_ORIGIN_INVALID", "escape fix needs a commit.");
+            const fix = await git.run(["rev-parse", "--verify", "--quiet", "--end-of-options", `${raw.fix}^{commit}`]);
+            if (fix.exitCode !== 0)
+                throw new AgentOpsError("ESCAPE_ORIGIN_INVALID", `Fix commit ${raw.fix} does not exist in this repository.`);
+            origin = { ...origin, fix: out(fix).trim() };
+        }
+    }
+    if (!validOrigin(origin))
+        throw new AgentOpsError("ESCAPE_ORIGIN_INVALID", "origin is {kind: escape-of, commit, label, receipt?, fix?, promote? (runnerId:checkId)} with label requirement|surface|scenario|criteria|verify|review|flagged|out-of-model, or {kind: pre-existing|external, reason}.");
+    return origin;
+}
+/** Per-file diff identity that survives squash: blob ids and hunk positions are dropped. */
+export async function fileFingerprints(git, from, to) {
+    const names = await git.run(["diff", "--name-only", "-z", "--no-renames", from, to, "--"]);
+    const diff = await git.run(["diff", "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames", "-U0",
+        "--src-prefix=a/", "--dst-prefix=b/", from, to, "--"]);
+    if (names.exitCode !== 0 || diff.exitCode !== 0)
+        gitFailed("diff");
+    const paths = out(names).split("\0").filter(Boolean);
+    const chunks = ("\n" + out(diff)).split("\ndiff --git ").slice(1);
+    if (chunks.length !== paths.length)
+        gitFailed("diff");
+    return paths.map((path, i) => ({ path, digest: sha256(chunks[i].split("\n").slice(1)
+            .filter(line => !line.startsWith("index ")).map(line => line.startsWith("@@") ? "@@" : line).join("\n")) }));
+}
+/** Receipt schema v2 fields: every commit in target..candidate and per-file fingerprints. */
+export async function receiptRange(git, target, candidate) {
+    const list = await git.run(["rev-list", "--reverse", `${target}..${candidate}`, "--"]);
+    if (list.exitCode !== 0)
+        gitFailed("rev-list");
+    return { commits: out(list).split("\n").filter(Boolean), fileFingerprints: await fileFingerprints(git, target, candidate) };
+}
+export async function gitCommonDir(git, root) {
+    const result = await git.run(["rev-parse", "--git-common-dir"]);
+    if (result.exitCode !== 0)
+        gitFailed("rev-parse");
+    return resolve(root, out(result).trim());
+}
+/** Unreadable or foreign files are skipped: linking is advisory. */
+export async function loadReceipts(commonDir) {
+    const directory = join(commonDir, "agent-ops", "receipts");
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const loaded = [];
+    for (const name of names.filter(n => n.endsWith(".json") && RECEIPT_ID.test(n.slice(0, -5))).sort()) {
+        try {
+            const source = await readPrivateFile(join(directory, name), commonDir);
+            const receipt = source === null ? null : JSON.parse(source);
+            if (receipt !== null && (receipt.schemaVersion === 1 || receipt.schemaVersion === 2) && typeof receipt.candidateHead === "string")
+                loaded.push({ id: name.slice(0, -5), receipt });
+        }
+        catch { /* not a receipt this version can read */ }
+    }
+    return loaded;
+}
+const newest = (list) => [...list].sort((a, b) => String(b.receipt.createdAt).localeCompare(String(a.receipt.createdAt)))[0];
+/** Override, then range (v1: exact head), then per-file fingerprint, then unresolved or ungated. */
+export async function resolveEscape(git, receipts, commit, override) {
+    if (override !== undefined)
+        return receipts.some(r => r.id === override)
+            ? { state: "gated", receipt: override, matchedBy: "override" } : { state: "unresolved", reason: "receipt-not-local", receipt: override };
+    const range = receipts.filter(r => r.receipt.schemaVersion === 2 && r.receipt.commits?.includes(commit));
+    if (range.length > 0)
+        return { state: "gated", receipt: newest(range).id, matchedBy: "range" };
+    const head = receipts.filter(r => r.receipt.schemaVersion === 1 && r.receipt.candidateHead === commit);
+    if (head.length > 0)
+        return { state: "gated", receipt: newest(head).id, matchedBy: "head" };
+    const parent = await git.run(["rev-parse", "--verify", "--quiet", `${commit}^`]);
+    if (parent.exitCode === 0) {
+        const own = await fileFingerprints(git, out(parent).trim(), commit);
+        const scored = receipts.map(r => ({ r, score: own.filter(f => r.receipt.fileFingerprints?.some(g => g.path === f.path && g.digest === f.digest)).length }));
+        const best = Math.max(0, ...scored.map(s => s.score));
+        const winners = scored.filter(s => s.score === best && best > 0);
+        if (winners.length === 1)
+            return { state: "gated", receipt: winners[0].r.id, matchedBy: "fingerprint" };
+        if (winners.length > 1)
+            return { state: "unresolved", reason: "ambiguous-receipt" };
+    }
+    // finish notes the merged commit with its receipt path; a note without the receipt means another machine.
+    const note = await git.run(["notes", `--ref=${NOTES_REF}`, "show", commit]);
+    return note.exitCode === 0 ? { state: "unresolved", reason: "receipt-not-local" } : { state: "ungated" };
+}
+/** git grep -F replay of the receipt's recorded queries at its candidate. */
+export async function surfaceFacts(git, receipt, paths) {
+    const audits = receipt.tasks.map(t => t.task.surface).filter((s) => s !== undefined && !isCovers(s));
+    if (audits.length === 0)
+        return paths.map(path => ({ path, surface: "no-audit" }));
+    const head = receipt.candidateHead;
+    const hits = new Set();
+    const queries = new Set(audits.flatMap(a => Object.values(a.axes).flatMap(axis => "queries" in axis ? axis.queries : [])));
+    for (const query of queries) {
+        const result = await git.run(["grep", "-F", "-l", "-z", "-I", "--no-color", "-e", query, head, "--"]);
+        if (result.exitCode > 1)
+            return paths.map(path => ({ path, surface: "unavailable" }));
+        for (const hit of out(result).split("\0").filter(Boolean))
+            hits.add(hit.slice(head.length + 1));
+    }
+    const included = audits.flatMap(a => a.included.map(row => globMatcher(row.path)));
+    const excluded = audits.flatMap(a => a.excluded.map(row => globMatcher(row.glob)));
+    const facts = [];
+    for (const path of paths) {
+        const surface = included.some(m => m(path)) ? "included" : excluded.some(m => m(path)) ? "excluded" :
+            (await git.run(["cat-file", "-e", `${head}:${path}`])).exitCode !== 0 ? "absent" : hits.has(path) ? "hit" : "unseen";
+        facts.push({ path, surface });
+    }
+    return facts;
+}
+/** Mechanical replay outranks the agent unless it named the only earlier gate. */
+export function primaryLabel(agentLabel, facts) {
+    if (agentLabel === "requirement")
+        return agentLabel;
+    if (facts.some(f => f.surface === "excluded"))
+        return "surface-excluded";
+    if (facts.some(f => f.surface === "unseen"))
+        return "surface-unseen";
+    return agentLabel;
+}
+/** Product files the fix touched since its base (tests and agent-ops data are not missed surfaces). */
+export async function missedPaths(git, base) {
+    const paths = new Set([...await collectBaseChangePaths(git, base), ...(await collectChangeSurface(git)).paths]);
+    return [...paths].filter(path => !path.startsWith(".agent-ops") &&
+        !/(?:^|\/)(?:tests?|fixtures)(?:\/|$)|(?:\.test|\.spec)\./u.test(path)).sort().slice(0, 200);
+}
+/** A hint only: which commits last wrote the lines the fix changed or removed. Omissions have none. */
+export async function blameHints(git, base) {
+    const diff = await git.run(["diff", "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames", "-U0",
+        "--src-prefix=a/", "--dst-prefix=b/", base, "--"]);
+    if (diff.exitCode !== 0)
+        return [];
+    const counts = new Map();
+    let path = null, hunks = 0;
+    for (const line of out(diff).split("\n")) {
+        if (line.startsWith("--- ")) {
+            path = line.startsWith("--- a/") ? line.slice(6) : null;
+            continue;
+        }
+        const hunk = /^@@ -(\d+)(?:,(\d+))? /u.exec(line);
+        if (hunk === null || path === null || hunks >= 200)
+            continue;
+        const start = Number(hunk[1]), length = hunk[2] === undefined ? 1 : Number(hunk[2]);
+        if (length === 0)
+            continue;
+        hunks += 1;
+        const blame = await git.run(["blame", "--porcelain", "-L", `${start},+${length}`, base, "--", path]);
+        if (blame.exitCode !== 0)
+            continue;
+        for (const header of out(blame).matchAll(/^([0-9a-f]{40,64}) \d+ \d+/gmu))
+            counts.set(header[1], (counts.get(header[1]) ?? 0) + 1);
+    }
+    return [...counts].map(([commit, lines]) => ({ commit, lines })).sort((a, b) => b.lines - a.lines || a.commit.localeCompare(b.commit)).slice(0, 10);
+}
+/** Linking is advisory: a Git failure leaves the escape unresolved, never blocks the declaration. */
+export async function assessEscape(input) {
+    let receipts = [], link;
+    try {
+        receipts = await loadReceipts(await gitCommonDir(input.git, input.root));
+        link = await resolveEscape(input.git, receipts, input.origin.commit, input.origin.receipt);
+    }
+    catch {
+        link = { state: "unresolved", reason: "link-unavailable" };
+    }
+    // A backfill names the past fix: its diff, not this task's, is what the gates missed.
+    const paths = input.origin.fix === undefined ? await missedPaths(input.git, input.base) : await fixPaths(input.root, input.origin.fix);
+    const linked = link.state === "gated" ? receipts.find(r => r.id === link.receipt)?.receipt : undefined;
+    let facts = [];
+    if (linked !== undefined) {
+        try {
+            facts = await surfaceFacts(input.git, linked, paths);
+        }
+        catch {
+            facts = paths.map(path => ({ path, surface: "unavailable" }));
+        }
+    }
+    return { link, agentLabel: input.origin.label, label: primaryLabel(input.origin.label, facts), missedPaths: paths, facts,
+        residualRisks: linked?.residualRisks ?? [] };
+}
+export function ledgerPath(root, taskId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u.test(taskId))
+        throw new AgentOpsError("ESCAPE_TASK_INVALID", "Invalid task ID for the escape ledger.");
+    return join(root, LEDGER_DIRECTORY, `${taskId}.json`);
+}
+/** The ledger is repository content: never follow a checked-in symlink out of the worktree. */
+async function unsafe(target, kind) {
+    try {
+        const stat = await lstat(target);
+        return stat.isSymbolicLink() || (kind === "directory" ? !stat.isDirectory() : !stat.isFile());
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function safeLedgerPath(root, taskId) {
+    const path = ledgerPath(root, taskId);
+    if (await unsafe(join(root, LEDGER_DIRECTORY), "directory") || await unsafe(path, "file"))
+        throw new AgentOpsError("ESCAPE_LEDGER_UNSAFE", `${LEDGER_DIRECTORY} must be a real directory of regular files.`);
+    return path;
+}
+/** One record per task; re-declaring replaces it. Commit it with the fix. */
+export async function declareEscape(input) {
+    const assessment = await assessEscape(input);
+    const record = { schemaVersion: 1, taskId: input.taskId, escapeOf: input.origin.commit,
+        ...(input.origin.fix === undefined ? {} : { fix: input.origin.fix }), link: assessment.link,
+        agentLabel: assessment.agentLabel, label: assessment.label, missedPaths: assessment.missedPaths, facts: assessment.facts,
+        residualRisks: assessment.residualRisks.length, proof: await proof(input.root, input.origin, assessment), declaredAt: input.now };
+    await safeLedgerPath(input.root, input.taskId);
+    await mkdir(join(input.root, LEDGER_DIRECTORY), { recursive: true });
+    const path = await safeLedgerPath(input.root, input.taskId);
+    // O_NOFOLLOW closes the lstat-to-open race on POSIX; Windows has no such flag.
+    const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | (constants.O_NOFOLLOW ?? 0), 0o644);
+    try {
+        await handle.writeFile(`${JSON.stringify(record, null, 2)}\n`, "utf8");
+    }
+    finally {
+        await handle.close();
+    }
+    return { record, path, blame: await blameHints(input.git, input.base) };
+}
+/** Proof never throws at declaration: a broken rule is recorded as unproven and finish refuses it. */
+async function proof(root, origin, assessment) {
+    try {
+        return await proveEscape({ root, escapeOf: origin.commit, label: assessment.label, missedPaths: assessment.missedPaths,
+            ...(origin.promote === undefined ? {} : { promote: origin.promote }) });
+    }
+    catch (error) {
+        return { status: "unproven", code: "ESCAPE_RULE_UNPROVEN",
+            reason: error instanceof AgentOpsError ? `${error.code}: ${error.message}` : "The rule proof could not run." };
+    }
+}
+const proofKey = (value) => value === undefined ? null : JSON.stringify([value.status,
+    "rule" in value ? value.rule ?? null : null, "ruleHash" in value ? value.ruleHash : null, "check" in value ? value.check : null]);
+/**
+ * Fails closed at finish: a fresh replay must prove the escape and match the
+ * committed ledger record. A criteria/verify label returns the check to prove.
+ */
+export async function escapeCompletionProblem(input) {
+    let assessment, current;
+    try {
+        assessment = await assessEscape({ ...input, git: gitRunner(input.root) });
+        current = await proveEscape({ root: input.root, escapeOf: input.origin.commit, label: assessment.label, missedPaths: assessment.missedPaths,
+            ...(input.origin.promote === undefined ? {} : { promote: input.origin.promote }) });
+    }
+    catch (error) {
+        const code = error instanceof AgentOpsError && ["ESCAPE_RULE_INVALID", "ESCAPE_RULE_UNSAFE"].includes(error.code) ? error.code : "ESCAPE_RULE_UNPROVEN";
+        return { code, reason: error instanceof Error ? error.message : "The escape proof could not run." };
+    }
+    if (current.status === "unproven")
+        return { code: current.code, reason: current.reason };
+    const recorded = await readEscapeRecord(input.root, input.taskId);
+    if (recorded === null || recorded.label !== assessment.label || proofKey(recorded.proof) !== proofKey(current))
+        return { code: "ESCAPE_RULE_UNPROVEN", reason: `The tracked ${LEDGER_DIRECTORY}/${input.taskId}.json record is missing or stale; re-declare the origin and commit the record.` };
+    if (current.status === "check")
+        return current.check === null
+            ? { code: "ESCAPE_RULE_UNPROVEN", reason: "A criteria/verify escape names its red-to-green check: --escape-promote <runnerId:checkId> (DEBUG payload promote)." }
+            : { check: current.check };
+    return null;
+}
+export async function removeEscapeRecord(root, taskId) {
+    await rm(await safeLedgerPath(root, taskId), { force: true });
+}
+export async function readEscapeRecord(root, taskId) {
+    try {
+        return JSON.parse(await readFile(await safeLedgerPath(root, taskId), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Review packet data: the declaration, a fresh assessment, and whether the tracked record still matches it. */
+export async function escapeReviewData(input) {
+    if (input.origin.kind !== "escape-of")
+        return { taskId: input.taskId, origin: input.origin };
+    const assessment = await assessEscape({ ...input, origin: input.origin });
+    const recorded = await readEscapeRecord(input.root, input.taskId);
+    const current = recorded !== null && JSON.stringify([recorded.escapeOf, recorded.link, recorded.label, recorded.missedPaths, recorded.facts]) ===
+        JSON.stringify([input.origin.commit, assessment.link, assessment.label, assessment.missedPaths, assessment.facts]);
+    return { taskId: input.taskId, origin: input.origin, ...assessment, recordCurrent: current, ...(recorded?.proof === undefined ? {} : { proof: recorded.proof }) };
+}

package/dist/runtime/src/escape/origin.js

@@ -0,0 +1,20 @@
+/** Escape Loop R1: where a bug came from, declared on the task that fixes it. */
+export const ESCAPE_GATES = ["requirement", "surface", "scenario", "criteria", "verify", "review"];
+/** Agent-proposed label: the earliest gate that could have caught it, or flagged / out-of-model. */
+export const ESCAPE_LABELS = [...ESCAPE_GATES, "flagged", "out-of-model"];
+export const PROMOTE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}:[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+export const RECEIPT_ID = /^[a-f0-9]{64}-[a-f0-9]{40,64}$/u;
+const record = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const keys = (v, required, optional = []) => required.every(k => Object.hasOwn(v, k)) && Object.keys(v).every(k => required.includes(k) || optional.includes(k));
+export function validOrigin(value) {
+    if (!record(value))
+        return false;
+    if (value.kind === "escape-of")
+        return keys(value, ["kind", "commit", "label"], ["receipt", "fix", "promote"]) && typeof value.commit === "string" &&
+            /^[a-f0-9]{40,64}$/u.test(value.commit) && ESCAPE_LABELS.includes(value.label) &&
+            (value.receipt === undefined || (typeof value.receipt === "string" && RECEIPT_ID.test(value.receipt))) &&
+            (value.fix === undefined || (typeof value.fix === "string" && /^[a-f0-9]{40,64}$/u.test(value.fix) && value.fix !== value.commit)) &&
+            (value.promote === undefined || (typeof value.promote === "string" && PROMOTE.test(value.promote)));
+    return (value.kind === "pre-existing" || value.kind === "external") && keys(value, ["kind", "reason"]) &&
+        typeof value.reason === "string" && value.reason.trim().length >= 10 && value.reason.length <= 2048 && !value.reason.includes("\0");
+}

package/dist/runtime/src/escape/rules.js

@@ -0,0 +1,252 @@
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { lstat, open, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { canonicalJson } from "../config/hash.js";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { globMatcher } from "../surface/schema.js";
+import { ESCAPE_LABELS } from "./origin.js";
+/** Escape Loop R2: learned, tracked, data-only rules. They can only add places a task must classify. */
+export const RULES_DIRECTORY = ".agent-ops-escapes/rules";
+export const RULE_LABELS = [...ESCAPE_LABELS, "surface-excluded", "surface-unseen"];
+/** Labels whose proof is a rule replayed at the escaped commit. */
+export const SURFACE_LABELS = ["surface", "surface-excluded", "surface-unseen"];
+/** Labels whose proof is a promoted red-to-green behavioral check of the fixing task. */
+export const CHECK_LABELS = ["criteria", "verify"];
+export const RULE_LIMITS = { backtestCommits: 200, maxFireRate: 0.3, backtestBudgetMs: 60_000, queryTimeoutMs: 30_000 };
+/** argv only: rule strings are repository data and must never meet a shell or a regex engine. */
+export function runGit(root, args, timeoutMs) {
+    return new Promise(resolve => {
+        execFile("git", [...args], { cwd: root, encoding: "buffer", timeout: Math.max(1, timeoutMs), maxBuffer: 256 * 1024 * 1024, shell: false }, (error, stdout) => {
+            const failure = error;
+            resolve({ code: failure === null ? 0 : typeof failure.code === "number" ? failure.code : null,
+                stdout: Buffer.isBuffer(stdout) ? stdout : Buffer.alloc(0), timedOut: failure?.killed === true });
+        });
+    });
+}
+export const gitRunner = (root) => ({ run: async (args) => {
+        const result = await runGit(root, args, RULE_LIMITS.queryTimeoutMs);
+        return { exitCode: result.code ?? 128, stdout: result.stdout };
+    } });
+const record = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const exact = (v, keys) => keys.every(k => Object.hasOwn(v, k)) && Object.keys(v).every(k => keys.includes(k));
+const line = (v, min) => typeof v === "string" && v.trim().length >= min && v.length <= 256 && !/[\0\n\r]/u.test(v);
+const glob = (v) => line(v, 1) && !v.startsWith("/") && !v.includes("\\") &&
+    v.split("/").every(part => part !== "" && part !== "." && part !== "..");
+const strings = (v, check) => Array.isArray(v) && v.length <= 32 && v.every(check) && new Set(v).size === v.length;
+function invalid(file, message) {
+    throw new AgentOpsError("ESCAPE_RULE_INVALID", `${RULES_DIRECTORY}/${file}: ${message}`);
+}
+/** Strict: there is no field that removes a query, adds an exclusion or relaxes a gate. */
+export function parseRule(value, file) {
+    if (!record(value) || !exact(value, ["id", "escape", "label", "trigger", "expand", "noExclude"]))
+        invalid(file, "a rule is exactly {id, escape, label, trigger: {paths, tokens}, expand: {paths, queries}, noExclude}.");
+    if (typeof value.id !== "string" || !/^[a-z][a-z0-9-]{0,63}$/u.test(value.id) || file !== `${value.id}.json`)
+        invalid(file, "id is lowercase kebab-case and names the file <id>.json.");
+    if (typeof value.escape !== "string" || !/^[a-f0-9]{40,64}$/u.test(value.escape))
+        invalid(file, "escape is the full escaped commit SHA.");
+    if (!RULE_LABELS.includes(value.label))
+        invalid(file, `label is one of ${RULE_LABELS.join(", ")}.`);
+    const { trigger, expand } = value;
+    if (!record(trigger) || !exact(trigger, ["paths", "tokens"]) || !strings(trigger.paths, glob) || !strings(trigger.tokens, v => line(v, 3)) ||
+        trigger.paths.length + trigger.tokens.length === 0)
+        invalid(file, "trigger needs 1-32 path globs and/or fixed-string tokens (3+ characters).");
+    if (!record(expand) || !exact(expand, ["paths", "queries"]) || !strings(expand.paths, glob) || !strings(expand.queries, v => line(v, 3)) ||
+        expand.paths.length + expand.queries.length === 0)
+        invalid(file, "expand needs 1-32 path globs and/or fixed-string queries (3+ characters).");
+    if (typeof value.noExclude !== "boolean")
+        invalid(file, "noExclude is true or false.");
+    return { id: value.id, escape: value.escape, label: value.label,
+        trigger: { paths: [...trigger.paths], tokens: [...trigger.tokens] }, expand: { paths: [...expand.paths], queries: [...expand.queries] },
+        noExclude: value.noExclude };
+}
+async function kind(path) {
+    try {
+        const stat = await lstat(path);
+        return stat.isSymbolicLink() ? "other" : stat.isDirectory() ? "directory" : stat.isFile() ? "file" : "other";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "missing";
+        throw error;
+    }
+}
+const unsafe = () => {
+    throw new AgentOpsError("ESCAPE_RULE_UNSAFE", `${RULES_DIRECTORY} must be a real directory of regular <id>.json files.`);
+};
+/** Fails closed: a broken or symlinked rule never silently stops tightening. */
+export async function loadRules(root) {
+    for (const directory of [".agent-ops-escapes", RULES_DIRECTORY]) {
+        const found = await kind(join(root, directory));
+        if (found === "missing")
+            return [];
+        if (found !== "directory")
+            unsafe();
+    }
+    const rules = [];
+    for (const name of (await readdir(join(root, RULES_DIRECTORY))).sort()) {
+        const path = join(root, RULES_DIRECTORY, name);
+        if (await kind(path) !== "file")
+            unsafe();
+        if (!name.endsWith(".json"))
+            invalid(name, "only <id>.json rule files belong here.");
+        // O_NOFOLLOW closes the lstat-to-open race on POSIX; Windows has no such flag.
+        const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        let source;
+        try {
+            source = await handle.readFile("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+        let value;
+        try {
+            value = JSON.parse(source);
+        }
+        catch {
+            invalid(name, "not JSON.");
+        }
+        rules.push({ rule: parseRule(value, name), hash: sha256(source) });
+    }
+    return rules;
+}
+/** Added and removed lines only: headers and context never trigger. */
+function changedLines(diff) {
+    return diff.split("\n").filter(l => /^[+-]/u.test(l) && !l.startsWith("+++") && !l.startsWith("---")).map(l => l.slice(1));
+}
+/** A rule fires when a changed path matches a trigger glob or a changed line contains a trigger token. */
+export function ruleFires(rule, paths, diff) {
+    const globs = rule.trigger.paths.map(globMatcher);
+    if (paths.some(path => globs.some(match => match(path))))
+        return true;
+    if (rule.trigger.tokens.length === 0)
+        return false;
+    const lines = changedLines(diff);
+    return rule.trigger.tokens.some(token => lines.some(l => l.includes(token)));
+}
+const zList = (value) => value.toString("utf8").split("\0").filter(Boolean);
+/** Files a fired rule puts in front of the task: path globs over tracked files plus git grep -F queries; ref absent = working tree. */
+export async function ruleHits(root, rule, ref, timeoutMs = RULE_LIMITS.queryTimeoutMs) {
+    const hits = new Set();
+    const fail = () => { throw new AgentOpsError("SURFACE_BUDGET_EXCEEDED", `Rule ${rule.id} could not list its expand hits in time.`); };
+    if (rule.expand.paths.length > 0) {
+        const files = await runGit(root, ref === undefined ? ["ls-files", "-z"] : ["ls-tree", "-r", "-z", "--name-only", ref], timeoutMs);
+        if (files.code !== 0)
+            fail();
+        const globs = rule.expand.paths.map(globMatcher);
+        for (const path of zList(files.stdout))
+            if (globs.some(match => match(path)))
+                hits.add(path);
+    }
+    for (const query of rule.expand.queries) {
+        const result = await runGit(root, ["grep", "-F", "-l", "-z", "-I", "--no-color", "-e", query, ...(ref === undefined ? [] : [ref]), "--"], timeoutMs);
+        if (result.timedOut || (result.code !== 0 && result.code !== 1))
+            fail();
+        for (const hit of zList(result.stdout))
+            hits.add(ref === undefined ? hit : hit.slice(ref.length + 1));
+    }
+    // A rule's own text names its queries; the ledger is never a product surface.
+    return [...hits].filter(path => !path.startsWith(".agent-ops-escapes/")).sort();
+}
+/** One commit's own change against its first parent (the empty tree for a root commit). */
+export async function commitChange(root, commit) {
+    const names = await runGit(root, ["show", "-m", "--first-parent", "--format=", "--name-only", "-z", "--no-renames", commit, "--"], RULE_LIMITS.queryTimeoutMs);
+    const diff = await runGit(root, ["show", "-m", "--first-parent", "--format=", "-U0", "--no-color", "--no-ext-diff", "--no-textconv",
+        "--no-renames", commit, "--"], RULE_LIMITS.queryTimeoutMs);
+    if (names.code !== 0 || diff.code !== 0)
+        throw new AgentOpsError("ESCAPE_GIT_FAILED", `git show ${commit} failed.`);
+    return { paths: zList(names.stdout), diff: diff.stdout.toString("utf8") };
+}
+/** Product files a past fix commit touched (tests and agent-ops data are not missed surfaces). */
+export async function fixPaths(root, fix) {
+    return (await commitChange(root, fix)).paths.filter(path => !path.startsWith(".agent-ops") &&
+        !/(?:^|\/)(?:tests?|fixtures)(?:\/|$)|(?:\.test|\.spec)\./u.test(path)).sort().slice(0, 200);
+}
+/**
+ * The trigger against the last 200 first-parent commits, in one argv git call.
+ * ponytail: one `git log -p` buffered in memory (256 MiB cap); stream it if huge histories need it.
+ */
+export async function backtestRule(root, loaded, budgetMs = RULE_LIMITS.backtestBudgetMs) {
+    const head = (await runGit(root, ["rev-parse", "HEAD"], RULE_LIMITS.queryTimeoutMs)).stdout.toString("utf8").trim();
+    const cachePath = join(root, ".agent-ops", "tasks", "escape", "backtest", sha256(canonicalJson({ head, rule: loaded.hash, limit: RULE_LIMITS.backtestCommits })) + ".json");
+    try {
+        const cached = await readPrivateFile(cachePath, root);
+        if (cached !== null)
+            return JSON.parse(cached);
+    }
+    catch { /* recompute */ }
+    const log = await runGit(root, ["log", "--first-parent", "-m", "-n", String(RULE_LIMITS.backtestCommits), "-p", "-U0", "--no-color",
+        "--no-ext-diff", "--no-textconv", "--no-renames", "--format=%x00commit %H", "HEAD", "--"], budgetMs);
+    if (log.timedOut)
+        throw new AgentOpsError("SURFACE_BUDGET_EXCEEDED", `Backtest of rule ${loaded.rule.id} exceeded its ${budgetMs} ms budget.`);
+    if (log.code !== 0)
+        throw new AgentOpsError("ESCAPE_GIT_FAILED", "git log failed during the rule backtest.");
+    const commits = log.stdout.toString("utf8").split("\0commit ").slice(1);
+    let fires = 0;
+    for (const chunk of commits) {
+        const paths = [...chunk.matchAll(/^diff --git a\/.+? b\/(.+)$/gmu)].map(m => m[1]);
+        if (ruleFires(loaded.rule, paths, chunk))
+            fires += 1;
+    }
+    const result = { commits: commits.length, fires, rate: commits.length === 0 ? 0 : Math.round(fires / commits.length * 1000) / 1000 };
+    await writePrivateFile(cachePath, JSON.stringify(result), root).catch(() => undefined);
+    return result;
+}
+/**
+ * Proof per label. Surface labels need a rule for this escape that fires on the
+ * escaped commit's own diff and whose hits at that commit cover every missed
+ * path that existed there; no test or review ever runs at the escaped commit.
+ */
+export async function proveEscape(input) {
+    if (CHECK_LABELS.includes(input.label))
+        return { status: "check", check: input.promote ?? null };
+    if (!SURFACE_LABELS.includes(input.label))
+        return { status: "lesson", reason: `${input.label}: no mechanical replay exists for this gate; recorded as an unproven lesson.` };
+    const rules = (await loadRules(input.root)).filter(r => r.rule.escape === input.escapeOf);
+    if (rules.length === 0)
+        return { status: "unproven", code: "ESCAPE_RULE_UNPROVEN",
+            reason: `No ${RULES_DIRECTORY}/<id>.json rule names escape ${input.escapeOf}.` };
+    const change = await commitChange(input.root, input.escapeOf);
+    const required = [];
+    for (const path of input.missedPaths)
+        if ((await runGit(input.root, ["cat-file", "-e", `${input.escapeOf}:${path}`], RULE_LIMITS.queryTimeoutMs)).code === 0)
+            required.push(path);
+    const reasons = [];
+    for (const loaded of rules) {
+        if (!ruleFires(loaded.rule, change.paths, change.diff)) {
+            reasons.push(`${loaded.rule.id} does not fire on the escaped commit`);
+            continue;
+        }
+        const hits = new Set(await ruleHits(input.root, loaded.rule, input.escapeOf));
+        const missing = required.filter(path => !hits.has(path));
+        if (missing.length > 0) {
+            reasons.push(`${loaded.rule.id} misses ${missing.slice(0, 5).join(", ")}`);
+            continue;
+        }
+        let backtest;
+        try {
+            backtest = await backtestRule(input.root, loaded, input.budgetMs);
+        }
+        catch (error) {
+            if (error instanceof AgentOpsError && error.code === "SURFACE_BUDGET_EXCEEDED")
+                return { status: "unproven", code: "SURFACE_BUDGET_EXCEEDED", reason: error.message, rule: loaded.rule.id };
+            throw error;
+        }
+        if (backtest.rate > RULE_LIMITS.maxFireRate)
+            return { status: "unproven", code: "ESCAPE_RULE_TOO_BROAD", rule: loaded.rule.id, backtest,
+                reason: `${loaded.rule.id} fires on ${backtest.fires} of the last ${backtest.commits} first-parent commits (> ${RULE_LIMITS.maxFireRate * 100}%).` };
+        return { status: "proven", rule: loaded.rule.id, ruleHash: loaded.hash, backtest };
+    }
+    return { status: "unproven", code: "ESCAPE_RULE_UNPROVEN", reason: reasons.join("; ") };
+}
+/** Printed only: agent-ops never writes .agent-ops/config.json for an executable rule. */
+export function configProposal(promote, config) {
+    const [runnerId, checkId] = promote.split(":");
+    const runner = config?.verification.acceptanceRunners?.find(r => r.id === runnerId);
+    return { note: "Proposal only: review it, then apply it yourself and confirm trust with agent-ops update; agent-ops never writes this config.",
+        promote: { runnerId, checkId },
+        verification: { commands: [{ id: `escape-${checkId}`.slice(0, 64), command: runner?.command ?? "<runner command>", args: [...runner?.args ?? []],
+                    cwd: runner?.cwd ?? ".", required: true, evidence: { kind: "exit-code" } }] } };
+}

package/dist/runtime/src/fs/temporary.js

@@ -0,0 +1,10 @@
+import { rm } from "node:fs/promises";
+/**
+ * Removes a scratch directory without letting cleanup hide the result it served.
+ * Windows can hold a just-killed child's files open for a moment (EBUSY), so rm
+ * retries; a directory that still cannot be removed stays in the OS temp dir.
+ */
+export async function removeTemporary(path) {
+    // ponytail: a leaked temp directory is the ceiling; the OS temp cleaner reclaims it.
+    await rm(path, { recursive: true, force: true, maxRetries: 10 }).catch(() => undefined);
+}