@kylecheng3146/agent-ops 0.9.0 → 0.10.2

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

@@ -8,7 +8,7 @@ import { recordNativeRunAuthorization } from "../../../runtime/src/run/authoriza
 import { observeRunFailure } from "../../../runtime/src/run/verification.js";
 import { criteriaProgress, recordRunPhase } from "../../../runtime/src/run/phase.js";
 import { compareFailureObservations } from "../../../runtime/src/run/convergence.js";
-import { RunControlService } from "../../../runtime/src/run/controls.js";
+import { RunControlService, nativeResumeTime } from "../../../runtime/src/run/controls.js";
 import { beginPolicyTransition, markPolicyTransitionStage, completePolicyTransition, discoverPendingPolicyTransition } from "../../../runtime/src/run/policy-transition.js";
 import { readReviewReportArtifact } from "../../../runtime/src/review/attestation.js";
 import { execFile, spawn } from "node:child_process";
@@ -17,6 +17,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { setTimeout as delay } from "node:timers/promises";
 import { AgentOpsError, resolveContainedPath } from "../../../runtime/src/fs/paths.js";
+import { ensureRunPolicy } from "./context.js";
 import { bindRunPolicy, readRunPolicy, runRuntimeHash, validateRunPolicyChange } from "../../../runtime/src/run/policy.js";
 import { sha256 } from "../../../runtime/src/fs/hash.js";
 import { calculateConfigHash, canonicalJson } from "../../../runtime/src/config/hash.js";
@@ -27,7 +28,7 @@ import { RunSupervisor } from "../../../runtime/src/run/supervisor.js";
 import { NativeRunTransport, nativeProcessIdentity } from "../../../runtime/src/run/transport.js";
 import { workerPlan } from "../../../runtime/src/run/planning.js";
 import { RunScheduler } from "../../../runtime/src/run/scheduler.js";
-import { activeWallTimeMs } from "../../../runtime/src/run/scheduler.js";
+import { activeWallTimeMs, remainingRunTimeMs } from "../../../runtime/src/run/scheduler.js";
 import { readBootIdentity, readGuiLoginIdentity, LaunchdController } from "../../../runtime/src/run/macOS.js";
 import { readPrivateFile, writePrivateFile, withPrivateFileLock } from "../../../runtime/src/security/permissions.js";
 import { TaskService } from "../../../runtime/src/task/service.js";
@@ -42,6 +43,31 @@ const exec = promisify(execFile);
 const plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const active = (worker) => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status);
 const cli = fileURLToPath(new URL("./bin.js", import.meta.url));
+/** Release the sole native slot only after confirmed coordinator death. */
+export async function prepareSerialSchedule(repository, supervisor, runId) {
+    const current = await repository.read(runId);
+    if (current === null || current.jobs !== 1 || current.rootTaskId === null || current.status !== "active" || current.disableRestart || current.awaitingResume)
+        return null;
+    const children = current.tasks.filter(task => task.taskId !== current.rootTaskId);
+    const coordinator = current.workers.find(worker => worker.workerId === current.coordinatorId);
+    if (children.length === 0 || coordinator === undefined)
+        return null;
+    if (children.some(task => !["delivered", "complete", "blocked"].includes(task.status))) {
+        if (active(coordinator)) {
+            await supervisor.stopWorker(runId, coordinator.workerId, coordinator.generation, "handoff");
+            await repository.appendEvent(runId, { type: "diagnostic", code: "RUN_COORDINATOR_YIELDED", workerId: coordinator.workerId,
+                taskId: coordinator.taskId, detail: "Coordinator process death confirmed before assigning the sole slot to children." });
+        }
+        return null;
+    }
+    return coordinator.status === "stopped" && !current.workers.some(worker => worker.workerId !== coordinator.workerId && active(worker)) ? coordinator : null;
+}
+/** Retain the structured child failure instead of hiding it behind recovery text. */
+export function runStepError(result, fallback) {
+    const details = Array.isArray(result.errors) ? result.errors.filter(plain)
+        .map(error => typeof error.message === "string" ? error.message : "").filter(Boolean).join("; ") : "";
+    return new AgentOpsError(typeof result.code === "string" ? result.code : "RUN_INTEGRATION_RECOVERY_REQUIRED", `${fallback}${details.length === 0 ? "" : ": " + details.slice(0, 4096)}`);
+}
 /** Recheck after confirmed death and after verification, before publishing the frozen SHA. */
 export async function assertRunDeliverySnapshot(root, taskId, head, contract, tasks) {
     const runner = gitRunner(root);
@@ -104,6 +130,15 @@ export async function superviseNativeRun(root, runId) {
             await blockStartup("RUN_RESTART_STORM");
             return;
         }
+        let manualResumeAt;
+        await repository.mutate(runId, current => {
+            manualResumeAt = nativeResumeTime(current);
+            if (manualResumeAt === undefined)
+                return current;
+            // Consume the latest control durably; bounded event history is not a one-shot fence.
+            return { ...current, controls: current.controls.map((control, index) => index === current.controls.length - 1
+                    ? { ...control, appliedAt: new Date().toISOString() } : control) };
+        });
         await repository.appendEvent(runId, { type: "status", code: "RUN_SUPERVISOR_START", workerId: null, taskId: null, detail: null });
         let version;
         try {
@@ -171,7 +206,7 @@ export async function superviseNativeRun(root, runId) {
             await writePrivateFile(path, JSON.stringify(content, null, 2), worker.worktree);
             return "Read .agent-ops/tasks/run-instructions.json and carry its immutable original goal through the evidence loop. Submit a plan if rootTaskId is null; otherwise implement and repair the assigned task. A child requests handoff after local green; the coordinator waits for all child deliveries, then requests finalization. Never substitute native goal completion for agent-ops evidence.";
         }
-        async function start(worker, diagnostic) {
+        async function start(worker, diagnostic, resumeAt) {
             if (await discoverPendingPolicyTransition(repository, runId) !== null)
                 throw new AgentOpsError("RUN_POLICY_TRANSITION_PENDING", "Finish policy synchronization before acquiring a new writer generation.");
             if (worker.worktree === null)
@@ -195,7 +230,7 @@ export async function superviseNativeRun(root, runId) {
                 throw new AgentOpsError("RUN_WORKTREE_OWNERSHIP", "The worker checkout is not registered to this run.");
             await writeWorktreeRecord({ ...record, workerGeneration: worker.generation });
             const goal = await instructions(worker, diagnostic);
-            const running = await supervisor.startWorker(runId, worker.workerId, worker.generation, goal);
+            const running = await supervisor.startWorker(runId, worker.workerId, worker.generation, goal, resumeAt);
             await recordRunPhase(repository, runId, worker.workerId, (await repository.read(runId)).rootTaskId === null ? "planning" : "implementing");
             try {
                 await transport.activateRegistered(runId, running, goal);
@@ -206,14 +241,22 @@ export async function superviseNativeRun(root, runId) {
             }
         }
         async function schedule() {
+            const coordinator = await prepareSerialSchedule(repository, supervisor, runId);
+            if (coordinator !== null) {
+                await start(coordinator);
+                return;
+            }
             const current = (await repository.read(runId));
             for (const node of await scheduler.next(runId)) {
                 if (node.planDigest === undefined || node.taskId === current.rootTaskId)
                     continue;
                 const existing = current.workers.find(worker => worker.taskId === node.taskId);
                 if (existing !== undefined && existing.worktree !== null &&
-                    (await deps.tasks(existing.worktree).list()).some(r => r.task.id === node.taskId))
+                    (await deps.tasks(existing.worktree).list()).some(r => r.task.id === node.taskId)) {
+                    if (existing.status === "stopped")
+                        await start(existing);
                     continue;
+                }
                 const planPath = join(directory, runId, "plans", node.taskId + ".json");
                 const source = await readPrivateFile(planPath, commonDir);
                 if (source === null || sha256(source) !== node.planDigest)
@@ -291,12 +334,14 @@ export async function superviseNativeRun(root, runId) {
             if (absent)
                 return (await recoverRunIntegrationAfterCleanup(commonDir, runId, deps.git)).receiptPath;
             const result = await advance(saved);
-            if (result.status !== "ok" || !plain(result.data) || typeof result.data.receipt !== "string")
-                throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Recover the sealed transaction before allowing any writer to resume.");
+            if (result.status !== "ok")
+                throw runStepError(result, "Recover the sealed transaction before allowing any writer to resume");
+            if (!plain(result.data) || typeof result.data.receipt !== "string")
+                throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Recovery did not return the sealed receipt.");
             return result.data.receipt;
         }
         async function step(cwd, args, saved) {
-            const remaining = saved.budget.limitMs - activeWallTimeMs(saved.budget.activeIntervals, Date.now());
+            const remaining = remainingRunTimeMs(saved);
             if (remaining <= 0)
                 throw new AgentOpsError("RUN_BUDGET_EXHAUSTED", "No active time remains for final proof.");
             return await new Promise((resolve, reject) => {
@@ -327,7 +372,7 @@ export async function superviseNativeRun(root, runId) {
                             catch { }
                     }, 3000);
                 };
-                const timeout = setTimeout(terminate, remaining);
+                const timeout = Number.isFinite(remaining) ? setTimeout(terminate, remaining) : undefined;
                 const registration = (async () => {
                     const identity = child.pid === undefined ? null : await nativeProcessIdentity(child.pid);
                     if (identity === null || closed) {
@@ -637,11 +682,20 @@ export async function superviseNativeRun(root, runId) {
                 await synchronizePolicy();
             state = (await repository.read(runId));
             for (const worker of state.workers.filter(w => active(w) || w.status === "stopped")) {
+                if (state.jobs === 1 && state.rootTaskId !== null) {
+                    const pending = state.tasks.filter(task => task.taskId !== state.rootTaskId && !["delivered", "complete", "blocked"].includes(task.status));
+                    const node = pending.find(task => task.taskId === worker.taskId);
+                    if (pending.length > 0 && (worker.workerId === state.coordinatorId || node === undefined ||
+                        node.dependencies.some(id => !state.tasks.some(task => task.taskId === id && ["delivered", "complete"].includes(task.status)))))
+                        continue;
+                }
                 if (worker.workerId !== state.coordinatorId && (worker.worktree === null ||
                     !(await deps.tasks(worker.worktree).list()).some(r => r.task.id === worker.taskId)))
                     continue;
                 try {
-                    await start(worker);
+                    await start(worker, undefined, manualResumeAt);
+                    if (state.jobs === 1)
+                        break;
                 }
                 catch (cause) {
                     await repository.appendEvent(runId, { type: "diagnostic", code: cause instanceof AgentOpsError ? cause.code : "RUN_RECOVERY_FAILED",
@@ -677,8 +731,9 @@ export async function superviseNativeRun(root, runId) {
                     await stopAll(state.status === "budget-limited" ? "budget" : "stop");
                     return;
                 }
+                state = await ensureRunPolicy(repository, state);
                 const elapsed = activeWallTimeMs(state.budget.activeIntervals, Date.now());
-                if (elapsed >= state.budget.limitMs) {
+                if (state.budget.limitMs !== null && elapsed >= state.budget.limitMs) {
                     await repository.mutate(runId, current => ({ ...current, status: "budget-limited", disableRestart: true }));
                     await launchd.disableRestart(runDescriptor(state), "active run time budget exhausted");
                     await stopAll("budget");
@@ -688,7 +743,12 @@ export async function superviseNativeRun(root, runId) {
                         accumulatedMs: activeWallTimeMs(current.budget.activeIntervals, Date.now()), lastObservedAt: new Date().toISOString() } }));
                 await schedule();
                 state = (await repository.read(runId));
-                for (const worker of state.workers.filter(w => ["running", "idle"].includes(w.status))) {
+                for (const candidateWorker of state.workers.filter(w => ["running", "idle"].includes(w.status))) {
+                    const freshState = (await repository.read(runId));
+                    const currentWorker = freshState.workers.find(w => w.workerId === candidateWorker.workerId);
+                    if (currentWorker === undefined || !["running", "idle"].includes(currentWorker.status))
+                        continue;
+                    const worker = currentWorker;
                     await supervisor.heartbeat(runId, worker.workerId, worker.generation);
                     const observation = await supervisor.observeWorker(runId, worker.workerId, worker.generation);
                     if (!observation.processAlive) {
@@ -888,7 +948,7 @@ export async function superviseNativeRun(root, runId) {
                             await recordRunPhase(repository, runId, worker.workerId, "verifying");
                             const result = await advance(current);
                             if (result.status !== "ok")
-                                throw new AgentOpsError(result.code, "Final proof failed; inspect saved verifier and fresh review reports before repair.");
+                                throw runStepError(result, "Final proof failed; inspect saved verifier and fresh review reports before repair");
                             const data = result.data;
                             if (!plain(data) || typeof data.receipt !== "string")
                                 throw new AgentOpsError("RUN_RECEIPT_REQUIRED", "Finalization requires the receipt returned by the existing finish gate.");
@@ -904,9 +964,8 @@ export async function superviseNativeRun(root, runId) {
                         const stopped = latest.workers.find(w => w.workerId === worker.workerId);
                         if (request.action === "finalize" && latest.integration !== null && (latest.integration.status !== "prepared" ||
                             (await deps.git(root, ["rev-parse", latest.targetBranch + "^{commit}"])).stdout.trim() === latest.integration.candidate)) {
-                            const recovered = await recoverIntegration(latest);
-                            await acceptReceipt(latest, recovered);
-                            response = { requestId: request.requestId, code: "RUN_COMPLETE", receipt: recovered };
+                            // Preserve the failed step; a manual resume reconciles the sealed transaction after remediation.
+                            throw cause;
                         }
                         else if (request.action === "policy" && await discoverPendingPolicyTransition(repository, runId) !== null) {
                             await repository.appendEvent(runId, { type: "diagnostic", code: "RUN_POLICY_RECOVERY_REQUIRED", workerId: worker.workerId, taskId: worker.taskId,
@@ -936,7 +995,7 @@ export async function superviseNativeRun(root, runId) {
         }
         catch (cause) {
             await repository.appendEvent(runId, { type: "diagnostic", code: cause instanceof AgentOpsError ? cause.code : "RUN_SUPERVISOR_FAILED",
-                workerId: null, taskId: null, detail: "Supervisor stopped; worktree and proof artifacts are preserved." });
+                workerId: null, taskId: null, detail: cause instanceof AgentOpsError ? cause.message : "Supervisor stopped; worktree and proof artifacts are preserved." });
             try {
                 await stopAll("crash");
             }

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

@@ -1,6 +1,6 @@
 import { FileRunRepository } from "../../../runtime/src/run/service.js";
 import { readRunPolicy, runRuntimeHash } from "../../../runtime/src/run/policy.js";
-import { activeWallTimeMs } from "../../../runtime/src/run/scheduler.js";
+import { remainingRunTimeMs } from "../../../runtime/src/run/scheduler.js";
 import { runVerificationCommand, NodeVerificationProcessRunner } from "../../../runtime/src/verify/spawn.js";
 import { redactSecrets } from "../../../runtime/src/security/redact.js";
 import { join } from "node:path";
@@ -21,7 +21,7 @@ const policy = await readRunPolicy(state, await runRuntimeHash());
 const step = /^(?:0|[1-9][0-9]*)$/u.test(index) ? policy?.config.worktree?.setup?.[Number(index)] : undefined;
 if (step === undefined)
     throw new Error("Setup must select an authorized fixed policy command.");
-const remaining = state.budget.limitMs - activeWallTimeMs(state.budget.activeIntervals, Date.now());
+const remaining = remainingRunTimeMs(state);
 if (remaining <= 0)
     throw new Error("Run budget is exhausted.");
 const result = await runVerificationCommand({ id: "run-setup", ...step, cwd: ".", required: true,

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