@kylecheng3146/agent-ops 0.8.6 → 0.10.0

package/dist/packages/cli/src/commands/task.js

@@ -30,6 +30,44 @@ async function jsonFile(path) {
         throw new AgentOpsError("TASK_PAYLOAD_INVALID", "Invalid JSON payload.");
     }
 }
+async function escapeOrigin(args, service) {
+    return args.escapeOf === undefined ? undefined : await service.resolveOrigin({ kind: "escape-of", commit: args.escapeOf,
+        label: args.escapeLabel, ...(args.escapeReceipt === undefined ? {} : { receipt: args.escapeReceipt }),
+        ...(args.escapeFix === undefined ? {} : { fix: args.escapeFix }), ...(args.escapePromote === undefined ? {} : { promote: args.escapePromote }) });
+}
+/** Link state, label and blame hints are printed; the ledger record is committed with the fix. */
+async function withEscape(envelope, escape, service) {
+    if (escape === undefined || envelope.data === null)
+        return envelope;
+    const { link, label, agentLabel, facts, proof } = escape.record;
+    const proposal = proof?.status === "check" && proof.check !== null ? await service.escapeConfigProposal(proof.check) : undefined;
+    const lines = [
+        `Escape of ${escape.record.escapeOf}: ${link.state}${link.state === "unresolved" ? ` (${link.reason})` : ""}` +
+            `${link.state === "gated" ? ` via receipt ${link.receipt} (${link.matchedBy})` : ""}; label ${label}${label === agentLabel ? "" : ` (agent proposed ${agentLabel})`}.`,
+        ...facts.map(fact => `- ${fact.path}: ${fact.surface}`),
+        ...(proof === undefined ? [] : [proof.status === "proven"
+                ? `Proof: rule ${proof.rule} replays at the escaped commit; backtest ${proof.backtest.fires}/${proof.backtest.commits} commits (${proof.backtest.rate}).`
+                : proof.status === "unproven" ? `Proof: ${proof.code} - ${proof.reason} Finish refuses this until a tracked rule proves it.`
+                    : proof.status === "lesson" ? `Lesson (unproven, does not block): ${proof.reason}`
+                        : proof.check === null ? "Proof: ESCAPE_RULE_UNPROVEN - name the red-to-green check with --escape-promote <runnerId:checkId>."
+                            : `Proof: promoted check ${proof.check} must be a proven redCheckId of this task. Config proposal (not written):\n${JSON.stringify(proposal, null, 2)}`]),
+        `Ledger record: ${escape.path} (commit it with the fix).`,
+        escape.blame.length === 0 ? "Blame hints: none (the fix only adds lines; an omission has no author)."
+            : `Blame hints (a hint only): ${escape.blame.map(hint => `${hint.commit.slice(0, 12)} (${hint.lines} line${hint.lines === 1 ? "" : "s"})`).join(", ")}`
+    ];
+    return { ...envelope, data: { ...envelope.data, escape: { ...escape.record, blame: escape.blame, path: escape.path,
+                ...(proposal === undefined ? {} : { configProposal: proposal }) },
+            text: `${envelope.data.text ?? ""}${envelope.data.text?.endsWith("\n") === false ? "\n" : ""}${lines.join("\n")}\n` } };
+}
+/** An unreadable surface file is a missing surface, not a generic payload error. */
+async function surfaceFile(path) {
+    try {
+        return await jsonFile(path);
+    }
+    catch (error) {
+        throw new AgentOpsError("SURFACE_MISSING", `Surface file is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 function parseEvidence(values) {
     const evidence = {};
     for (const value of values) {
@@ -96,6 +134,7 @@ export async function runTaskCommand(options) {
             const worktree = sessionId === undefined || options.sessionWorktree === undefined
                 ? undefined
                 : await options.sessionWorktree(sessionId);
+            const origin = await escapeOrigin(options.args, worktree?.service ?? options.service);
             const record = await (worktree?.service ?? options.service).create({
                 title: options.args.title,
                 ...(options.args.goal === undefined ? {} : { goal: options.args.goal }),
@@ -111,19 +150,23 @@ export async function runTaskCommand(options) {
                 ...(options.args.parentTaskId === undefined
                     ? {}
                     : { parentTaskId: options.args.parentTaskId }),
-                ...(sessionId === undefined ? {} : { sessionId })
+                ...(sessionId === undefined ? {} : { sessionId }),
+                ...(options.args.surfaceFile === undefined ? {} : { surface: await surfaceFile(options.args.surfaceFile) }),
+                ...(origin === undefined ? {} : { origin }),
+                requireSurface: true
             });
+            const escape = origin === undefined ? undefined : await (worktree?.service ?? options.service).declareEscape(record.task.id);
             // An explicit CLI DEBUG intake may be the only start signal on hosts
             // without a prompt hook (notably agy). The native session owns the clock;
             // foregroundStart is idempotent for a repeated hook or command.
             if (options.args.debug && sessionId !== undefined) {
                 await (worktree?.service ?? options.service).debugService().foregroundStart(record.task.id, sessionId);
             }
-            const created = taskEnvelope(action, "TASK_CREATED", sessionId === undefined
+            const created = await withEscape(taskEnvelope(action, "TASK_CREATED", sessionId === undefined
                 ? `Created task ${record.task.id}.`
                 : record.task.parentTaskId === undefined
                     ? `Created and attached task ${record.task.id}.`
-                    : `Created subtask ${record.task.id}; the session stays on the top of its task tree.`, record);
+                    : `Created subtask ${record.task.id}; the session stays on the top of its task tree.`, record), escape, worktree?.service ?? options.service);
             if (worktree === undefined || created.data === null)
                 return created;
             return {
@@ -146,6 +189,10 @@ export async function runTaskCommand(options) {
         }
         if (action === "debug") {
             const id = requireTaskId(options.args), service = options.service.debugService();
+            if (options.args.debugAction === "origin") {
+                const declared = await service.origin(id, await jsonFile(options.args.payloadFile));
+                return await withEscape(taskEnvelope(action, "TASK_DEBUG_ORIGIN_DECLARED", "Origin bound into the contract; re-verify, re-record the confirmed hypothesis, then review.", declared.record), declared.escape, options.service);
+            }
             switch (options.args.debugAction) {
                 case "hypothesis":
                     await service.hypothesis(id, await jsonFile(options.args.payloadFile));
@@ -177,14 +224,18 @@ export async function runTaskCommand(options) {
             return taskEnvelope(action, "TASK_DEBUG_UPDATED", "Original issue debug state preserved.", await service.root(id));
         }
         if (action === "revise") {
-            const payload = await jsonFile(options.args.criteriaFile);
-            if (!Array.isArray(payload))
+            const payload = options.args.criteriaFile === undefined ? undefined : await jsonFile(options.args.criteriaFile);
+            if (payload !== undefined && !Array.isArray(payload))
                 throw new AgentOpsError("TASK_PAYLOAD_INVALID", "Criteria file must contain an array.");
+            const origin = await escapeOrigin(options.args, options.service);
             const record = await options.service.revise(requireTaskId(options.args), {
-                expectedContractHash: options.args.expectedContract, criteria: payload,
+                expectedContractHash: options.args.expectedContract,
+                ...(payload === undefined ? {} : { criteria: payload }),
+                ...(options.args.surfaceFile === undefined ? {} : { surface: await surfaceFile(options.args.surfaceFile) }),
+                ...(origin === undefined ? {} : { origin }),
                 reason: options.args.reason, ...(options.args.baseline === undefined ? {} : { baseline: options.args.baseline })
             });
-            return taskEnvelope(action, "TASK_REVISED", "Contract revised; obtain new verification and fresh review.", record);
+            return await withEscape(taskEnvelope(action, "TASK_REVISED", "Contract revised; obtain new verification and fresh review.", record), origin === undefined ? undefined : await options.service.declareEscape(record.task.id), options.service);
         }
         if (action === "replan") {
             const payload = await jsonFile(options.args.planFile);

package/dist/packages/cli/src/commands/update.js

@@ -8,6 +8,11 @@ import { okEnvelope } from "../output.js";
 import { formatOperationPlan } from "../plan-output.js";
 import { toPublicUpdatePlan } from "../public-plan.js";
 import { formatTrustChange, planTrustGrant } from "./trust.js";
+/** One plan line, so the user approves the worktrees together with the commands. */
+export function worktreeSyncLine(worktrees) {
+    return worktrees.length === 0 ? "" :
+        `Session worktrees that receive this config and its trust: ${worktrees.join(", ")}\n`;
+}
 function repairedLines(plan) {
     return plan.installation.repaired.map(({ path, reason }) => `repaired: ${path} (${reason.replace("-", " ")})`);
 }
@@ -146,19 +151,21 @@ export async function runUpdateCommand(options) {
         ...(worktree === undefined ? {} : { worktree })
     });
     const trust = await trustChange(options, plan);
+    const worktrees = await options.sessionWorktrees?.list().catch(() => []) ?? [];
     if (options.args.dryRun) {
         return okEnvelope("UPDATE_PLAN_READY", {
             applied: false,
             plan: toPublicUpdatePlan(plan, trust),
             message: "Update plan calculated; no files were changed.",
-            text: formatUpdatePlan(plan, trust)
+            text: formatUpdatePlan(plan, trust) + worktreeSyncLine(worktrees),
+            ...(worktrees.length === 0 ? {} : { worktrees })
         });
     }
     if (!options.args.yes && !options.isTTY) {
         return updateError("UPDATE_CONFIRMATION_REQUIRED", "Non-interactive update requires --yes.", plan, trust);
     }
     if (!options.args.yes &&
-        !(await options.confirm(plan, trust))) {
+        !(await options.confirm(plan, trust, worktrees))) {
         return updateError("UPDATE_CANCELLED", "Update was cancelled; no files were changed.", plan, trust);
     }
     await applyUpdatePlan(options.root, plan);
@@ -173,16 +180,21 @@ export async function runUpdateCommand(options) {
             return updateError("UPDATE_TRUST_FAILED", "Update was applied, but repository trust was not granted. Run `agent-ops trust grant --yes`.", plan, trust, true);
         }
     }
+    // Fail-open: a worktree that cannot be synced keeps its old trust and says so via trust status.
+    const synced = worktrees.length === 0 ? [] : await options.sessionWorktrees?.sync().catch(() => []) ?? [];
+    const syncedLines = synced.length === 0 ? [] : [`Synced config and trust into session worktrees: ${synced.join(", ")}.`];
     return okEnvelope("UPDATE_APPLIED", {
         applied: true,
         plan: toPublicUpdatePlan(plan, trust),
         message: `Managed installation updated to ${plan.targetVersion}.`,
-        ...(plan.installation.repaired.length === 0
+        ...(synced.length === 0 ? {} : { worktrees: synced }),
+        ...(plan.installation.repaired.length === 0 && synced.length === 0
             ? {}
             : {
                 text: [
                     `Managed installation updated to ${plan.targetVersion}.`,
-                    ...repairedLines(plan)
+                    ...repairedLines(plan),
+                    ...syncedLines
                 ].join("\n")
             })
     });

package/dist/packages/cli/src/commands/verify.js

@@ -72,7 +72,10 @@ function formatReport(report) {
     const lines = [
         `Verification task ${safe(report.taskId)}: ${report.status}`,
         `Scope: ${report.selection.reason} (${report.selection.fallback ? "fallback" : "bounded"})`,
-        ...report.results.flatMap(formatResult)
+        ...report.results.flatMap(formatResult),
+        // A timed-out runner step says which step and which limit; plain UNKNOWN left people guessing.
+        ...(report.acceptance ?? []).flatMap(row => row.detail === undefined ? [] :
+            [`- ${row.status} ${safe(row.runnerId)} (${row.criterionId}, ${row.phase}): ${safe(row.detail)}`])
     ];
     if (report.signal !== null) {
         lines.push(`Signal: ${report.signal}`);

package/dist/packages/cli/src/debug-intake.js

@@ -159,7 +159,7 @@ export async function routeDebugPrompt(root, input, host = "claude") {
     const baseline = (await gitRunner(path).run(["rev-parse", "--verify", "HEAD"])).stdout.toString().trim();
     const criteria = ["issue-regression", "related-checks"].map(id => ({ id, description: id === "issue-regression" ? "Reproduce and fix the original reported issue with relevant regression evidence." : "Pass necessary related checks and two fresh independent reviews.", verifierIds: ids,
         acceptance: { mode: "review-only", baselineCommit: baseline, bindings: [], reviewOnlyReason: "Provisional investigation intake only. Identify and revise to executable original-issue regression before debug success; this criterion cannot prove reproduction." } }));
-    const created = await tasks.create({ title: fields.prompt.split("\n")[0].slice(0, 160), goal: fields.prompt, intent: "Investigate and fix the original issue through authoritative task debug evidence.", debug: { facts: ["User-reported symptom is unverified."], unknowns: ["Baseline reproduction", "Root cause", "Relevant regression and related checks"] }, criteria, sessionId: session, policyConfigHash: calculateConfigHash(effective) });
+    const created = await tasks.create({ title: fields.prompt.split("\n")[0].slice(0, 160), goal: fields.prompt, intent: "Investigate and fix the original issue through authoritative task debug evidence.", debug: { facts: ["User-reported symptom is unverified."], unknowns: ["Baseline reproduction", "Root cause", "Relevant regression and related checks"] }, criteria, sessionId: session, policyConfigHash: calculateConfigHash(effective), requireSurface: true });
     let clockNote = "";
     if (foregroundClockSupported(host)) {
         try {
@@ -171,7 +171,7 @@ export async function routeDebugPrompt(root, input, host = "claude") {
     }
     else
         clockNote = " Native foreground timing is unsupported on this host; controlled operations remain evidence-timed and do not claim a complete active-time budget.";
-    return `DEBUG issue ${created.task.id} created in ${path}. Preserve the original goal. Investigate, record falsifiable hypotheses, revise provisional criteria to relevant behavioral regression, repair, verify, obtain two fresh independent reviews, then finish. A clean HEAD baseline is fixed automatically; do not ask permission for it or offer diagnosis-only as a fallback. Failure to reproduce alone is not a stop condition: continue discriminating checks within the budget. Defaults: 60 active minutes / 5 material repair candidates. No user-authored debug plan is required.${clockNote}`;
+    return `DEBUG issue ${created.task.id} created in ${path}. Preserve the original goal. Investigate, record falsifiable hypotheses, revise provisional criteria to relevant behavioral regression, add the surface audit (task revise --surface-file) before the first repair, repair, declare the origin (task debug --debug-action origin) once a hypothesis is confirmed, verify, obtain two fresh independent reviews, then finish. A clean HEAD baseline is fixed automatically; do not ask permission for it or offer diagnosis-only as a fallback. Failure to reproduce alone is not a stop condition: continue discriminating checks within the budget. Defaults: 60 active minutes / 5 material repair candidates. No user-authored debug plan is required.${clockNote}`;
 }
 export async function interruptDebugSession(root, sessionId, nativeInput) {
     const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(sessionId)));

package/dist/packages/cli/src/run-entry.js

@@ -163,7 +163,7 @@ export async function superviseNativeRun(root, runId) {
                     "Commit product changes before revising the contract. A contract revision stops existing generations; dirty recovery preserves the checkout and blocks takeover.",
                     "Write one request atomically to .agent-ops/tasks/run-request.json; wait for matching run-response.json before another request.",
                     "Requests require requestId (unique alphanumeric or hyphen, max 64), workerId, generation and current contractHash.",
-                    "Plan fields: action=plan,title,intent,criteria. Worker fields: action=worker,title,intent,criteria,dependencies (known worker task IDs; omit all acceptance baselines until dependencies are delivered).",
+                    "Plan fields: action=plan,title,intent,criteria,surface (the EVIDENCE-SURFACE-001 audit object, same shape as task create --surface-file). Worker fields: action=worker,title,intent,criteria,dependencies (known worker task IDs; omit all acceptance baselines until dependencies are delivered),covers (parent included surface IDs this worker delivers; every included surface needs one worker).",
                     "Only the coordinator may change execution policy: submit action=policy, configFile (relative proposed JSON), expectedPolicyHash, approvals (each changed capabilityId command:<id>/runner:<id>/setup:<index>, classification=non-dangerous, reason assessing the entire fixed definition including setup/build). Commit source changes and wait until every writer is clean before requesting policy synchronization. Never use init/update/trust grant to create permanent execution authorization. Explicit native or organization denial must not be bypassed.",
                     "Worker task baselines are frozen after dependency commits enter its checkout. Handoff fields: action=handoff,sourceFiles (explicit existing source paths when unchanged). Question fields: action=question,prompt. Coordinator finalize fields: action=finalize.",
                     "The supervisor, after stopping writers, runs final verification, two fresh reviews and finish. A native completed goal is never final proof."], diagnostic };
@@ -253,7 +253,7 @@ export async function superviseNativeRun(root, runId) {
                         generateId: () => node.taskId, completion: { root: workerRoot, gitRunner: gitRunner(workerRoot), loadConfig: async () => config }
                     });
                     await service.create({ title: plan.title, intent: plan.intent, criteria: plan.criteria, goal: current.goal,
-                        sessionId: ownerSessionId, policyConfigHash: calculateConfigHash(config) });
+                        sessionId: ownerSessionId, policyConfigHash: calculateConfigHash(config), ...(plan.covers === undefined ? {} : { surface: { covers: plan.covers } }) });
                     await start((await repository.read(runId)).workers.find(w => w.workerId === registration.workerId));
                 }
                 catch (cause) {
@@ -756,7 +756,7 @@ export async function superviseNativeRun(root, runId) {
                     try {
                         if (current.status !== "active" || request.contractHash !== current.currentContractHash)
                             throw new AgentOpsError("RUN_CONTRACT_CHANGED", "Request must bind the current run contract.");
-                        const fields = request.action === "policy" ? ["configFile", "expectedPolicyHash", "approvals"] : request.action === "plan" ? ["title", "intent", "criteria"] : request.action === "question" ? ["prompt"] : request.action === "worker" ? ["title", "intent", "criteria", "dependencies"] :
+                        const fields = request.action === "policy" ? ["configFile", "expectedPolicyHash", "approvals"] : request.action === "plan" ? ["title", "intent", "criteria", "surface"] : request.action === "question" ? ["prompt"] : request.action === "worker" ? ["title", "intent", "criteria", "dependencies", "covers"] :
                             request.action === "handoff" || request.action === "finalize" ? ["sourceFiles"] : [];
                         if (Object.keys(request).some(key => !["requestId", "workerId", "generation", "contractHash", "action", ...fields].includes(key)))
                             throw new AgentOpsError("RUN_REQUEST_INVALID", "Unknown request fields are not accepted.");
@@ -790,7 +790,8 @@ export async function superviseNativeRun(root, runId) {
                             const config = await deps.loadConfig(worker.worktree);
                             const service = new TaskService(new FileTaskStore(join(worker.worktree, ".agent-ops", "tasks", "state.json"), worker.worktree), { completion: { root: worker.worktree, gitRunner: gitRunner(worker.worktree), loadConfig: async () => config } });
                             const task = await service.create({ title: request.title, intent: request.intent, goal: current.goal,
-                                criteria: request.criteria, sessionId: worker.ownerSessionId, policyConfigHash: calculateConfigHash(config) });
+                                criteria: request.criteria, sessionId: worker.ownerSessionId, policyConfigHash: calculateConfigHash(config),
+                                ...(request.surface === undefined ? {} : { surface: request.surface }), requireSurface: true });
                             await repository.mutate(runId, saved => ({ ...saved, rootTaskId: task.task.id, currentContractHash: treeContractHash([task.task]),
                                 tasks: saved.tasks.map(node => node.taskId === worker.taskId ? { ...node, taskId: task.task.id } : node),
                                 workers: saved.workers.map(w => w.workerId === worker.workerId ? { ...w, taskId: task.task.id } : w) }));
@@ -802,7 +803,8 @@ export async function superviseNativeRun(root, runId) {
                             if (worker.workerId !== current.coordinatorId || current.rootTaskId === null)
                                 throw new AgentOpsError("RUN_COORDINATOR_REQUIRED", "Only the registered coordinator can plan child workers.");
                             const taskId = "task-" + (await import("node:crypto")).randomUUID();
-                            const plan = workerPlan({ title: request.title, intent: request.intent, criteria: request.criteria, dependencies: request.dependencies }, taskId, current);
+                            const plan = workerPlan({ title: request.title, intent: request.intent, criteria: request.criteria, dependencies: request.dependencies,
+                                ...(request.covers === undefined ? {} : { covers: request.covers }) }, taskId, current);
                             const { taskId: _id, ...specification } = plan;
                             const content = JSON.stringify(specification);
                             await writePrivateFile(join(directory, runId, "plans", taskId + ".json"), content, commonDir);

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");
+}