@kylecheng3146/agent-ops 0.9.0 → 0.10.2

package/dist/runtime/src/run/service.js

@@ -5,6 +5,8 @@ import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
 import { budgetExpired } from "./scheduler.js";
+import { approvalRetryEvents } from "./controls.js";
+import { redactSecrets } from "../security/redact.js";
 export const RUN_PHASES = ["planning", "implementing", "verifying", "reviewing", "integrating"];
 /** Writer slots are deliberately bounded; the coordinator may occupy one. */
 export const MAX_ACTIVE_WORKERS = 2;
@@ -13,7 +15,7 @@ const ID = /^[A-Za-z0-9._:/-]{1,256}$/u;
 const SHA = /^[a-f0-9]{40,64}$/u;
 const SHA256 = /^[a-f0-9]{64}$/u;
 const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/u;
-const MAX_EVENTS = 2_000;
+export const MAX_EVENTS = 2_000;
 const MAX_GOAL_LENGTH = 64_000;
 const MAX_TIME_BUDGET_MS = 24 * 60 * 60 * 1_000;
 function invalid(message) {
@@ -101,8 +103,10 @@ export function assertRunState(value) {
         state.budget.activeIntervals.some(interval => !plain(interval)))
         return invalid("Run state contains malformed nested records.");
     if (!RUN_ID.test(state.runId) || !SHA.test(state.goalHash) || state.goal.length > MAX_GOAL_LENGTH ||
-        sha256(state.goal) !== state.goalHash || !Number.isSafeInteger(state.budget.limitMs) ||
-        state.budget.limitMs <= 0 || state.budget.limitMs > MAX_TIME_BUDGET_MS ||
+        sha256(state.goal) !== state.goalHash || (state.budget.limitMs !== null && (!Number.isSafeInteger(state.budget.limitMs) ||
+        state.budget.limitMs <= 0 || state.budget.limitMs > MAX_TIME_BUDGET_MS)) ||
+        (state.budget.legacyLimitMs !== undefined && (!Number.isSafeInteger(state.budget.legacyLimitMs) || state.budget.legacyLimitMs <= 0 || state.budget.legacyLimitMs > MAX_TIME_BUDGET_MS)) ||
+        (state.budget.upgradedAt !== undefined && !Number.isFinite(Date.parse(state.budget.upgradedAt))) ||
         !Number.isSafeInteger(state.budget.accumulatedMs) || state.budget.accumulatedMs < 0 ||
         !Array.isArray(state.budget.activeIntervals) || state.budget.activeIntervals.some((interval) => !Number.isSafeInteger(interval.startMs) || interval.startMs < 0 ||
         (interval.endMs !== null && (!Number.isSafeInteger(interval.endMs) || interval.endMs < interval.startMs))) ||
@@ -154,10 +158,8 @@ export function createRunState(input) {
     if (input.jobs !== undefined && (!Number.isSafeInteger(input.jobs) || input.jobs < 1 || input.jobs > 2)) {
         throw new AgentOpsError("RUN_JOBS_INVALID", "A run supports one or two implementation workers.");
     }
-    const limitMs = input.timeBudgetMs ?? 60 * 60 * 1_000;
-    if (!Number.isSafeInteger(limitMs) || limitMs <= 0 || limitMs > MAX_TIME_BUDGET_MS) {
-        throw new AgentOpsError("RUN_BUDGET_INVALID", "Run time budget must be a positive value no greater than 24 hours.");
-    }
+    if (input.timeBudgetMs !== undefined)
+        throw new AgentOpsError("RUN_TIME_BUDGET_UNSUPPORTED", "New runs have no total time cap; omit --time-budget. Command and review timeouts remain effective.");
     const runId = input.runId ?? `run-${randomUUID().replaceAll("-", "").slice(0, 16)}`;
     if (!RUN_ID.test(runId))
         throw new AgentOpsError("RUN_ID_INVALID", "Run id must contain 8-64 lowercase letters, digits, and hyphens.");
@@ -186,7 +188,7 @@ export function createRunState(input) {
         awaitingResume: false,
         disableRestart: false,
         budget: {
-            limitMs,
+            limitMs: null,
             activeIntervals: [],
             accumulatedMs: 0,
             startedAt: iso(now, "budget.startedAt"),
@@ -315,6 +317,48 @@ export class FileRunRepository {
         });
     }
 }
+const RECOVERABLE = new Set(["RUN_RECOVERY_DIRTY", "RUN_NATIVE_VERSION_CHANGED", "RUN_RUNTIME_CHANGED", "RUN_REPO_UNTRUSTED",
+    "RUN_NATIVE_UNAVAILABLE", "RUN_RESTART_STORM", "RUN_POLICY_RECOVERY_REQUIRED", "RUN_POLICY_EXPIRED", "RUN_POLICY_DISABLED", "NATIVE_GOAL_NOT_ACTIVE", "RUN_WORKER_STALE", "RUN_IDENTITY_INVALID", "RUN_TIME_BUDGET_EXCEEDED", "RUN_SETUP_RECOVERY_REQUIRED", "RUN_NATIVE_START_FAILED"]);
+function resumeBlocker(current, acknowledged = new Set()) {
+    return [...current.events].reverse().find(e => !acknowledged.has(e.id) && (RECOVERABLE.has(e.code) || ["RUN_NO_PROGRESS_REPEAT", "RUN_COMMAND_DENIED"].includes(e.code)));
+}
+function cannotResume(current, acknowledged = new Set()) {
+    return current.status === "complete" || current.events.some(e => e.code === "RUN_COMMAND_DENIED" && !acknowledged.has(e.id)) ||
+        (current.integration?.proofDigest === undefined && (current.workers.some(w => w.workerId === current.coordinatorId && w.status === "blocked" && w.lastFailure !== null && w.lastFailure.failureClass !== "native-start") ||
+            (current.status === "blocked" && !RECOVERABLE.has(resumeBlocker(current, acknowledged)?.code ?? ""))));
+}
+/** Observations are not proof validation; resume still reconciles every authority and sealed artifact. */
+export function describeRunRecovery(state, now = Date.now()) {
+    const diagnostics = [...state.events].reverse().filter(e => e.type === "diagnostic");
+    const event = diagnostics[0]?.code === "RUN_CLEANUP_UNCHANGED"
+        ? diagnostics.find(e => e.code === "RUN_CLEANUP_BLOCKED") ?? diagnostics[0] : diagnostics[0];
+    let cause = event === undefined ? null : { code: event.code, detail: redactSecrets(event.detail ?? "").slice(0, 4096) };
+    if (event?.code === "RUN_CLEANUP_BLOCKED") {
+        try {
+            const saved = JSON.parse(event.detail ?? "{}");
+            if (typeof saved.code === "string" && typeof saved.message === "string")
+                cause = { code: saved.code, detail: redactSecrets(saved.message).slice(0, 4096) };
+        }
+        catch { /* Retain the recorded diagnostic when old metadata cannot be decoded. */ }
+    }
+    const sealedProof = state.integration?.proofDigest !== undefined;
+    const cleanup = state.integration?.status === "cleaned" ? "complete" :
+        state.integration?.status === "receipt-written" ? "pending" : "not-ready";
+    const resumable = !cannotResume(state);
+    const code = cause?.code ?? "";
+    const remediation = state.status === "complete" ? "No action: the completed run and its receipt are immutable." :
+        state.events.some(e => e.code === "RUN_COMMAND_DENIED") ? "Obtain genuine new authorization for the recorded denial; resume cannot erase it." :
+            /TRUST/u.test(code) ? "Restore repository trust through the supported authorization process, then manually resume; trust is revalidated." :
+                /IDENTITY|GENERATION|STALE/u.test(code) ? "Confirm the old writer is dead and reconcile its owned worktree, native identity and current generation; never replay an old request." :
+                    /PROOF|RECEIPT|TARGET_CHANGED|OWNERSHIP/u.test(code) ? "Reconcile the sealed proof, receipt, target and owner mismatch; preserve the checkout and never replace sealed artifacts." :
+                        /NO_PROGRESS/u.test(code) ? "Inspect the saved failure history; ordinary resume cannot reset no-progress counters." :
+                            cleanup === "pending" ? "Resolve the recorded cleanup blocker, then manually resume the original run. Only missing steps run after proof, receipt, target and ownership validation; unchanged cleanup inputs are refused." :
+                                RECOVERABLE.has(code) ? `Resolve ${code}, then manually resume the original run; runtime, policy, identity and worktree checks still apply.` :
+                                    state.status === "awaiting-input" ? "Answer the pending question with agent-ops run respond." :
+                                        !resumable ? "Inspect agent-ops run logs and repair the recorded blocker before requesting recovery; do not blindly resume." :
+                                            "Inspect agent-ops run logs before a manual resume; reconciliation precedes any writer restart.";
+    return { phase: state.phase ?? "unknown", cause, sealedProof: sealedProof ? "recorded-unchecked" : "none", cleanup, resumable, remediation };
+}
 /**
  * Small service facade used by the CLI and supervisor. Native host execution is
  * injected; this layer owns persistent run identity and never treats a host's
@@ -374,29 +418,32 @@ export class RunService {
         }));
         return { state, message: `Run ${runId} is paused.` };
     }
-    async resume(runId) {
-        const state = await this.#repository.mutate(runId, (current) => {
-            const recoverable = new Set(["RUN_RECOVERY_DIRTY", "RUN_NATIVE_VERSION_CHANGED", "RUN_RUNTIME_CHANGED", "RUN_REPO_UNTRUSTED",
-                "RUN_NATIVE_UNAVAILABLE", "RUN_RESTART_STORM", "RUN_POLICY_RECOVERY_REQUIRED", "RUN_POLICY_EXPIRED", "RUN_SETUP_RECOVERY_REQUIRED", "RUN_NATIVE_START_FAILED"]);
-            const blocker = [...current.events].reverse().find(e => recoverable.has(e.code) || ["RUN_NO_PROGRESS_REPEAT", "RUN_COMMAND_DENIED"].includes(e.code));
-            const terminalBlocker = current.events.some(e => e.code === "RUN_COMMAND_DENIED") ||
-                current.workers.some(w => w.workerId === current.coordinatorId && w.status === "blocked" && w.lastFailure !== null && w.lastFailure.failureClass !== "native-start");
-            if (current.status === "complete" || (current.integration?.proofDigest === undefined &&
-                (terminalBlocker || (current.status === "blocked" && !recoverable.has(blocker?.code ?? ""))))) {
+    async resume(runId, retryApprovalIds = [], upgradeBudget = true) {
+        const state = await this.#repository.mutate(runId, async (current) => {
+            const acknowledged = await approvalRetryEvents(current, retryApprovalIds);
+            const recoverable = RECOVERABLE;
+            const blocker = resumeBlocker(current, acknowledged);
+            if (cannotResume(current, acknowledged)) {
                 throw new AgentOpsError("RUN_NOT_RESUMABLE", `Run ${runId} is ${current.status}.`);
             }
-            if (current.integration?.proofDigest === undefined && budgetExpired(current, Date.parse(this.#now())))
+            if (current.integration?.proofDigest === undefined && !upgradeBudget && budgetExpired(current, Date.parse(this.#now())))
                 throw new AgentOpsError("RUN_BUDGET_EXHAUSTED", "Explicit resume preserves the whole-run budget; no execution allowance remains.");
-            const recover = ["blocked", "paused"].includes(current.status) && recoverable.has(blocker?.code ?? "");
+            const recover = ["blocked", "paused", "budget-limited"].includes(current.status) && recoverable.has(blocker?.code ?? "");
             return {
                 ...current,
-                ...(recover ? { workers: current.workers.map(w => w.status === "blocked" && (w.lastFailure === null || w.lastFailure.failureClass === "native-start") ? { ...w, status: "stopped" } : w),
+                ...(upgradeBudget && current.budget.limitMs !== null ? {
+                    budget: { ...current.budget, limitMs: null, legacyLimitMs: current.budget.limitMs, upgradedAt: this.#now() },
+                    events: [...current.events, event({ type: "diagnostic", code: "RUN_BUDGET_UPGRADED", workerId: null, taskId: null,
+                            detail: `Manual resume removed legacy total cap ${current.budget.limitMs}ms; accounting and independent blockers remain.` }, this.#now())].slice(-MAX_EVENTS)
+                } : {}),
+                ...(recover ? { workers: current.workers.map(w => w.status === "blocked" && (w.lastFailure === null || w.lastFailure.failureClass === "native-start") &&
+                        !current.tasks.some(t => t.taskId === w.taskId && t.status === "blocked" && !recoverable.has(t.blockedReason ?? "")) ? { ...w, status: "stopped" } : w),
                     tasks: current.tasks.map(t => t.status === "blocked" && recoverable.has(t.blockedReason ?? "") ? { ...t, status: "ready", blockedReason: null } : t) } : {}),
                 status: "active",
                 awaitingResume: false,
                 disableRestart: false,
                 controls: [...current.controls, {
-                        action: "resume", actor: "user", reason: null, requestedAt: this.#now(), expiresAt: null, appliedAt: null
+                        action: "resume", actor: "user", reason: retryApprovalIds.length === 0 ? null : "retry-approval:" + JSON.stringify(retryApprovalIds), requestedAt: this.#now(), expiresAt: null, appliedAt: null
                     }]
             };
         });

package/dist/runtime/src/run/supervisor.js

@@ -109,13 +109,17 @@ export class RunSupervisor {
             throw error("RUN_WORKER_NOT_FOUND", `Registered worker disappeared: ${workerId}`);
         return { workerId, taskId: input.taskId, ownerSessionId: input.ownerSessionId, generation: worker.generation, worktree: worker.worktree };
     }
-    async startWorker(runId, workerId, generation, goal) {
+    async startWorker(runId, workerId, generation, goal, manualResumeAt) {
         assertId(workerId, "workerId");
         if (!Number.isSafeInteger(generation) || generation < 1)
             throw error("RUN_GENERATION_INVALID", "Worker generation is invalid.");
         const before = await this.#repository.read(runId);
         if (before === null)
             throw error("RUN_NOT_FOUND", `Run not found: ${runId}`);
+        const control = before.controls.at(-1);
+        if (manualResumeAt !== undefined && (control?.actor !== "user" || control.action !== "resume" ||
+            control.requestedAt !== manualResumeAt || !Number.isFinite(Date.parse(manualResumeAt)) || Date.parse(manualResumeAt) > Date.parse(this.#now())))
+            throw error("RUN_WORKER_STALE", "Native recovery requires the current explicit manual resume.");
         if (before.host !== this.#host.host)
             throw error("RUN_HOST_MISMATCH", `Run ${runId} is assigned to ${before.host}, not ${this.#host.host}.`);
         const worker = before.workers.find((candidate) => candidate.workerId === workerId);
@@ -126,12 +130,16 @@ export class RunSupervisor {
         const starting = await this.#repository.mutate(runId, (current) => {
             if (current.status !== "active" || current.disableRestart || current.awaitingResume)
                 throw error("RUN_START_DISABLED", "Run state no longer permits starting a writer.");
+            if (manualResumeAt !== undefined && current.controls.at(-1)?.requestedAt !== manualResumeAt)
+                throw error("RUN_WORKER_STALE", "Manual recovery changed before native start.");
             if (budgetExpired(current, Date.parse(this.#now())))
                 throw error("RUN_BUDGET_EXHAUSTED", "The cumulative run budget cannot be reset by starting another worker.");
             const currentWorker = current.workers.find((candidate) => candidate.workerId === workerId);
             if (currentWorker === undefined || currentWorker.generation !== generation || currentWorker.status !== "assigned") {
                 throw error("RUN_WORKER_STALE", `Worker ${workerId} changed before native start.`);
             }
+            if (current.workers.filter(candidate => candidate.workerId !== workerId && activeWorker(candidate)).length >= current.jobs)
+                throw error("RUN_WORKER_LIMIT", "No native execution slot is available.");
             return replaceWorker(replaceTask(current, currentWorker.taskId, { status: "running" }), {
                 ...currentWorker,
                 status: "starting",
@@ -150,7 +158,8 @@ export class RunSupervisor {
                 ownerSessionId: startingWorker.ownerSessionId,
                 generation,
                 worktree: startingWorker.worktree,
-                contractHash: before.currentContractHash
+                contractHash: before.currentContractHash,
+                ...(manualResumeAt === undefined ? {} : { manualResumeAt })
             });
         }
         catch (cause) {

package/dist/runtime/src/run/transport.js

@@ -38,6 +38,7 @@ export class NativeRunTransport {
         const saved = (await this.repository.read(input.runId))?.workers.find(w => w.workerId === input.workerId);
         const request = { runId: input.runId, workerId: input.workerId, generation: input.generation,
             contractHash: input.contractHash, cwd: input.worktree,
+            ...(input.manualResumeAt === undefined ? {} : { manualResumeAt: input.manualResumeAt }),
             env: { AGENT_OPS_SESSION_ID: input.ownerSessionId, AGENT_OPS_HOST: this.host,
                 CODEX_THREAD_ID: undefined, AGENT_OPS_AGENT_ID: undefined,
                 AGENT_OPS_RUN_ID: input.runId, AGENT_OPS_WORKER_ID: input.workerId,

package/dist/runtime/src/schema/validate.js

@@ -2,6 +2,7 @@ import { validDebugSettings, validDebugIntake } from "../task/debug-state.js";
 import { CONFIG_SCHEMA_VERSION, EVIDENCE_SCHEMA_VERSION, MANIFEST_SCHEMA_VERSION, TASK_SCHEMA_VERSION } from "../contracts.js";
 import { acceptanceError, runnerError, commitIdentity } from "./acceptance.js";
 import { parseSurface } from "../surface/schema.js";
+import { validOrigin } from "../escape/origin.js";
 const ID_PATTERN = /^[a-z][a-z0-9-]{0,127}$/;
 const HASH_PATTERN = /^[a-f0-9]{64}$/;
 const WINDOWS_RESERVED_SEGMENT = /^(?:aux|com[1-9]|con|lpt[1-9]|nul|prn)(?:\..*)?$/i;
@@ -571,7 +572,7 @@ export function validateCriterion(value, path) {
     return success(value);
 }
 export function validateTask(value) {
-    const root = validateRoot(value, ["criteria", "id", "intent", "goal", "contractRevision", "parentTaskId", "schemaVersion", "title", "debug", "surface", "surfaceRequired"], isRecord(value) && value.schemaVersion === 1 ? 1 : TASK_SCHEMA_VERSION);
+    const root = validateRoot(value, ["criteria", "id", "intent", "goal", "contractRevision", "parentTaskId", "schemaVersion", "title", "debug", "surface", "surfaceRequired", "origin", "originRequired"], isRecord(value) && value.schemaVersion === 1 ? 1 : TASK_SCHEMA_VERSION);
     if (isFailure(root)) {
         return root;
     }
@@ -587,6 +588,10 @@ export function validateTask(value) {
             return failure("INVALID_SURFACE", "$.surface", "Task surface is invalid.");
         }
     }
+    if (root.origin !== undefined && !validOrigin(root.origin))
+        return failure("INVALID_ORIGIN", "$.origin", "origin is escape-of {commit, label, receipt?} or pre-existing/external {reason}.");
+    if (root.originRequired !== undefined && (root.originRequired !== true || root.debug === undefined))
+        return failure("INVALID_ORIGIN", "$.originRequired", "originRequired is either absent or true on a DEBUG task.");
     if (root.contractRevision !== undefined && (!Number.isSafeInteger(root.contractRevision) || root.contractRevision < 0))
         return failure("INVALID_CONTRACT_REVISION", "$.contractRevision", "Invalid contract revision.");
     if (root.goal !== undefined && (!isNonEmptyString(root.goal) || Buffer.byteLength(root.goal, "utf8") > 65536))

package/dist/runtime/src/security/permissions.js

@@ -37,6 +37,7 @@ const execFile = promisify(execFileCallback);
 const lockQueues = new Map();
 const heartbeatFailures = new Map();
 const heartbeatPaths = new Set();
+const heartbeatReleases = new Map();
 // A heartbeat lives as long as the process. Its handle is held here, not only
 // by the interval below, so a reset or mocked timer can never let garbage
 // collection close it (an uncaught error since Node 26).
@@ -172,6 +173,14 @@ async function ensureProcessHeartbeat(parent, anchorDirectory) {
                 });
             });
         }, HEARTBEAT_INTERVAL_MS);
+        heartbeatReleases.set(heartbeatPath, async () => {
+            clearInterval(timer);
+            await handle.close();
+            heartbeatHandles.delete(handle);
+            heartbeatPaths.delete(heartbeatPath);
+            processHeartbeats.delete(cacheKey);
+            heartbeatReleases.delete(heartbeatPath);
+        });
         timer.unref();
         return heartbeat;
     })();
@@ -184,6 +193,82 @@ async function ensureProcessHeartbeat(parent, anchorDirectory) {
         throw error;
     }
 }
+async function fileIdentity(path) {
+    try {
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const { dev, ino } = await handle.stat({ bigint: true });
+            return { dev, ino };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Retire authenticated runtime markers without weakening Git's dirty-file guard. */
+export async function cleanupWorktreeHeartbeats(root, paths) {
+    const candidates = [];
+    for (const relativePath of paths) {
+        const match = /^\.(?:claude|codex)\/\.agent-ops-process-([1-9]\d*)-([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/u.exec(relativePath);
+        if (match === null)
+            continue;
+        const path = join(root, relativePath), pid = Number(match[1]);
+        const unsafe = () => new AgentOpsError("WORKTREE_HEARTBEAT_UNSAFE", `Preserve unverified heartbeat ${relativePath} (PID ${pid}).`);
+        const blocked = () => new AgentOpsError("WORKTREE_HEARTBEAT_ACTIVE", `Preserve heartbeat ${relativePath}: PID ${pid} is active or its death cannot be confirmed.`);
+        if (!Number.isSafeInteger(pid) || pid > 2147483647)
+            throw unsafe();
+        const parent = await lstat(dirname(path));
+        if (parent.isSymbolicLink() || !parent.isDirectory())
+            throw unsafe();
+        let handle;
+        try {
+            handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+            const status = await handle.stat({ bigint: true });
+            if (!status.isFile() || status.nlink !== 1n || status.size > 128n ||
+                await handle.readFile("utf8") !== `runtime:${match[2]}\n`)
+                throw unsafe();
+            const own = pid === process.pid && match[2] === PROCESS_INSTANCE_TOKEN && heartbeatReleases.has(path);
+            if (own) {
+                if ([...lockQueues.keys()].some(key => key.startsWith(`${resolve(root)}\0`)))
+                    throw blocked();
+            }
+            else if (isProcessActive(pid))
+                throw blocked();
+            candidates.push({ path, relative: relativePath, pid, own, dev: status.dev, ino: status.ino });
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue;
+            if (error instanceof AgentOpsError)
+                throw error;
+            throw unsafe();
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    // Validate the complete set before removing anything; foreign owners fail closed.
+    for (const candidate of candidates) {
+        const status = await lstat(candidate.path, { bigint: true });
+        // Identity is compared handle to handle, as it was captured: on Windows, Node 22.14.0
+        // reports different dev/ino for lstat and fstat of the same file.
+        const identity = await fileIdentity(candidate.path);
+        if (!status.isFile() || status.isSymbolicLink() || identity === undefined || identity.dev !== candidate.dev || identity.ino !== candidate.ino)
+            throw new AgentOpsError("WORKTREE_HEARTBEAT_UNSAFE", `Heartbeat changed before cleanup: ${candidate.relative}.`);
+        if (!candidate.own && isProcessActive(candidate.pid))
+            throw new AgentOpsError("WORKTREE_HEARTBEAT_ACTIVE", `Preserve heartbeat ${candidate.relative}: PID ${candidate.pid} is active or its death cannot be confirmed.`);
+        if (candidate.own) {
+            const release = heartbeatReleases.get(candidate.path);
+            if (release === undefined || [...lockQueues.keys()].some(key => key.startsWith(`${resolve(root)}\0`)))
+                throw new AgentOpsError("WORKTREE_HEARTBEAT_ACTIVE", `Current-process locks still protect ${candidate.relative} (PID ${candidate.pid}).`);
+            await release();
+        }
+        await rm(candidate.path);
+    }
+}
 async function assertProcessHeartbeat(parent, heartbeat) {
     const heartbeatPath = join(parent, heartbeat.file);
     try {

package/dist/runtime/src/surface/discovery.js

@@ -3,13 +3,16 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { canonicalJson } from "../config/hash.js";
 import { sha256 } from "../fs/hash.js";
+import { loadRules, ruleFires, ruleHits } from "../escape/rules.js";
+import { AgentOpsError } from "../fs/paths.js";
 import { appendLocalLog } from "../logging/local-log.js";
 import { localStatePaths, readPrivateFile, writePrivateFile } from "../security/permissions.js";
 import { globMatcher, isCovers, missingScenarios, parseSurface, SURFACE_AXES } from "./schema.js";
 /** Cheapest first: a budget overrun stops before the long tail of diff tokens. */
 export const DISCOVERY_SOURCES = ["agent", "hunk-header", "template-fragment", "diff-token"];
 export const SURFACE_LIMITS = {
-    agentQueryFiles: 200, derivedQueryFiles: 30, exclusionFiles: 10, budgetMs: 120_000, queryTimeoutMs: 30_000,
+    // ponytail: derived queries over 10 files are skipped as generic; incidental ones under that are dismissed by query.
+    agentQueryFiles: 200, derivedQueryFiles: 10, exclusionFiles: 10, dismissals: 128, dismissMinFiles: 4, budgetMs: 120_000, queryTimeoutMs: 30_000,
     tokenLength: 6, fragmentLength: 4, derivedQueries: 400
 };
 /** argv only: queries are task text and must never meet a shell or a regex engine. */
@@ -84,6 +87,14 @@ async function logMetrics(home, rows) {
     }
     catch { /* advisory only */ }
 }
+async function logRuleMetrics(home, rows) {
+    try {
+        const state = localStatePaths(home);
+        for (const row of rows)
+            await appendLocalLog(join(state.logDirectory, "events.ndjson"), { type: "escape-rule", ...row }, { anchorDirectory: state.anchorDirectory });
+    }
+    catch { /* advisory only */ }
+}
 export async function logSurfaceResidualRisks(count, home = process.env.AGENT_OPS_HOME ?? homedir()) {
     await logMetrics(home, [{ source: "review", hits: 0, included: 0, excluded: 0, postBlockExclusions: 0, residualRisks: count }]);
 }
@@ -113,6 +124,16 @@ export async function runSurfaceGate(input) {
         if (uncovered.length > 0 || unknown.length > 0)
             return notRun("SURFACE_UNASSIGNED", "Children covers must equal the parent included surfaces.", [{ uncovered, unknown }]);
     }
+    // Escape Loop R2: learned rules fail closed before any discovery.
+    let rules;
+    try {
+        rules = await loadRules(input.root);
+    }
+    catch (error) {
+        if (error instanceof AgentOpsError && (error.code === "ESCAPE_RULE_INVALID" || error.code === "ESCAPE_RULE_UNSAFE"))
+            return notRun(error.code, error.message, []);
+        throw error;
+    }
     const now = input.now ?? Date.now;
     const started = now();
     const budget = input.budgetMs ?? SURFACE_LIMITS.budgetMs;
@@ -186,6 +207,22 @@ export async function runSurfaceGate(input) {
     const skipped = [];
     const unclassified = new Map();
     const metrics = new Map(DISCOVERY_SOURCES.map(source => [source, { hits: new Set(), included: new Set(), excluded: new Set() }]));
+    const dismissals = new Map((surface.dismissed ?? []).map(row => [row.query, row.reason]));
+    if (dismissals.size > SURFACE_LIMITS.dismissals)
+        return notRun("SURFACE_DISMISSAL_TOO_BROAD", `At most ${SURFACE_LIMITS.dismissals} queries may be dismissed; split the change.`, [{ dismissed: dismissals.size }]);
+    const recorded = new Set(agent);
+    const dismissed = [];
+    for (const query of dismissals.keys()) {
+        if (recorded.has(query))
+            return notRun("SURFACE_DISMISSAL_INVALID", "A recorded axis query cannot be dismissed; classify its hits.", [{ query }]);
+        const hit = hits.find(row => row.query === query && row.source !== "agent");
+        const outside = hit === undefined ? [] : hit.files.filter(path => !changed.has(path));
+        if (hit !== undefined && outside.length < SURFACE_LIMITS.dismissMinFiles && hit.files.length <= SURFACE_LIMITS.derivedQueryFiles)
+            return notRun("SURFACE_DISMISSAL_INVALID", `A query reaching fewer than ${SURFACE_LIMITS.dismissMinFiles} files outside the diff ` +
+                "is the likeliest sibling signal and cannot be dismissed; classify its files.", [{ query, files: outside }]);
+        if (hit !== undefined)
+            dismissed.push({ query, files: outside.length, postBlock: outside.some(path => blocked.includes(path)) });
+    }
     for (const hit of hits) {
         sources[hit.source].queries += 1;
         if (hit.source === "agent" && hit.files.length > SURFACE_LIMITS.agentQueryFiles)
@@ -194,6 +231,8 @@ export async function runSurfaceGate(input) {
             skipped.push({ source: hit.source, query: hit.query, files: hit.files.length });
             continue;
         }
+        if (hit.source !== "agent" && dismissals.has(hit.query))
+            continue;
         const metric = metrics.get(hit.source);
         for (const path of hit.files) {
             metric.hits.add(path);
@@ -205,9 +244,47 @@ export async function runSurfaceGate(input) {
                 unclassified.set(path, [...(unclassified.get(path) ?? []), { source: hit.source, query: hit.query }]);
         }
     }
+    // A fired rule's hits must be classified like any other; noExclude hits cannot be excluded.
+    const ruleRows = [];
+    const noExclude = [];
+    for (const { rule } of rules) {
+        if (!ruleFires(rule, [...changed], diff))
+            continue;
+        if (remaining() <= 0)
+            return notRun("SURFACE_BUDGET_EXCEEDED", "Discovery budget exhausted before escape rules ran.", [{ rule: rule.id }]);
+        let paths;
+        try {
+            paths = await ruleHits(input.root, rule, undefined, Math.min(SURFACE_LIMITS.queryTimeoutMs, remaining()));
+        }
+        catch (error) {
+            if (error instanceof AgentOpsError)
+                return notRun("SURFACE_BUDGET_EXCEEDED", error.message, [{ rule: rule.id }]);
+            throw error;
+        }
+        const row = { ruleId: rule.id, included: 0, excluded: 0 };
+        for (const path of paths) {
+            if (changed.has(path) || included.some(match => match(path)) || unknownPaths.some(match => match(path))) {
+                row.included += 1;
+                continue;
+            }
+            const exclusion = exclusions.find(e => e.match(path));
+            if (exclusion !== undefined) {
+                row.excluded += 1;
+                if (rule.noExclude)
+                    noExclude.push({ ruleId: rule.id, path, glob: exclusion.glob });
+            }
+            else
+                unclassified.set(path, [...(unclassified.get(path) ?? []), { source: "escape-rule", query: `rule:${rule.id}` }]);
+        }
+        ruleRows.push(row);
+    }
+    if (input.metrics === true)
+        await logRuleMetrics(input.logHome ?? process.env.AGENT_OPS_HOME ?? homedir(), ruleRows);
+    if (noExclude.length > 0)
+        return notRun("ESCAPE_RULE_NO_EXCLUDE", "A learned escape rule marks these places noExclude: include them or mark them UNKNOWN.", noExclude);
     for (const source of DISCOVERY_SOURCES)
         sources[source].files = metrics.get(source).hits.size;
-    const discovery = { cached, sources, skipped: skipped.slice(0, 50), postBlockExclusions };
+    const discovery = { cached, sources, skipped: skipped.slice(0, 50), postBlockExclusions, dismissed };
     if (input.metrics === true)
         await logMetrics(input.logHome ?? process.env.AGENT_OPS_HOME ?? homedir(), DISCOVERY_SOURCES.map(source => ({ source,
             hits: metrics.get(source).hits.size, included: metrics.get(source).included.size, excluded: metrics.get(source).excluded.size,

package/dist/runtime/src/surface/schema.js

@@ -1,4 +1,5 @@
 import { AgentOpsError } from "../fs/paths.js";
+import { canonicalJson } from "../config/hash.js";
 /** EVIDENCE-SURFACE-001: where else the change lands, recorded before criteria. */
 export const SURFACE_AXES = ["dependents", "duplicates", "otherPaths", "sharedState"];
 export const SCENARIO_DIMENSIONS = ["initialState", "redo", "timeBoundary", "identitySwitch", "concurrency"];
@@ -34,7 +35,7 @@ export function parseSurface(value) {
             invalid("covers must list unique parent surface IDs.");
         return { covers: [...value.covers] };
     }
-    if (!record(value) || !exact(value, ["axes", "included", "excluded", "unknown", "contracts", "valueChanges", "scenarios"]))
+    if (!record(value) || !exact(value, ["axes", "included", "excluded", "unknown", "contracts", "valueChanges", "scenarios"], ["dismissed"]))
         invalid("Surface file needs axes, included, excluded, unknown, contracts, valueChanges and scenarios (or covers for a child).");
     const axes = value.axes;
     if (!record(axes) || !exact(axes, [...SURFACE_AXES]))
@@ -97,9 +98,23 @@ export function parseSurface(value) {
         else
             invalid(`Scenario ${key} needs {applies: true, behavior} or {na: reason}.`);
     }
+    let dismissed;
+    if (value.dismissed !== undefined) {
+        if (!list(value.dismissed, 256))
+            invalid("dismissed must be a list.");
+        const seen = new Set();
+        dismissed = value.dismissed.map(row => {
+            if (!record(row) || !exact(row, ["query", "reason"]) || !text(row.query, 256) || /[\n\r]/u.test(row.query) || seen.has(row.query))
+                invalid("Each dismissal needs a unique single-line query and a reason.");
+            seen.add(row.query);
+            if (!reason(row.reason) || row.reason.length > 256)
+                invalid(`Dismissal ${row.query}: say in at most 256 characters why its hits are incidental; "out of scope" is not a reason.`);
+            return { query: row.query, reason: row.reason };
+        });
+    }
     return {
         axes: Object.fromEntries(SURFACE_AXES.map(name => [name, axis(axes[name], name)])),
-        included, excluded, unknown, contracts, valueChanges, scenarios: parsedScenarios
+        included, excluded, unknown, contracts, valueChanges, scenarios: parsedScenarios, ...(dismissed === undefined ? {} : { dismissed })
     };
 }
 export function missingScenarios(surface) {
@@ -125,3 +140,29 @@ export function globMatcher(pattern) {
     const expression = new RegExp(`^${source}$`, "u");
     return path => expression.test(path);
 }
+/** What one revision did to the surface: list rows added/removed, other fields before/after. Size follows the edit, not the audit. */
+export function surfaceDelta(before, after) {
+    const key = (value) => canonicalJson(value ?? null);
+    if (key(before) === key(after))
+        return "unchanged";
+    const from = (before ?? {}), to = (after ?? {});
+    const added = {}, removed = {};
+    const changed = {};
+    for (const field of [...new Set([...Object.keys(from), ...Object.keys(to)])].sort()) {
+        const a = from[field], b = to[field];
+        if (key(a) === key(b))
+            continue;
+        if (Array.isArray(a) && Array.isArray(b)) {
+            const old = new Set(a.map(key)), next = new Set(b.map(key));
+            const plus = b.filter(row => !old.has(key(row))), minus = a.filter(row => !next.has(key(row)));
+            if (plus.length > 0)
+                added[field] = plus;
+            if (minus.length > 0)
+                removed[field] = minus;
+        }
+        else
+            changed[field] = { before: a ?? null, after: b ?? null };
+    }
+    return { ...(Object.keys(added).length > 0 ? { added } : {}), ...(Object.keys(removed).length > 0 ? { removed } : {}),
+        ...(Object.keys(changed).length > 0 ? { changed } : {}) };
+}

package/dist/runtime/src/task/completion.js

@@ -5,6 +5,8 @@ import { isPassingVerificationEvidence } from "../verify/evidence.js";
 import { taskContractHash } from "./contract.js";
 import { acceptanceCoverage, coverageDigest } from "../verify/acceptance-coverage.js";
 import { loadDebugProof, debugProofDigest, debugRemainingMs } from "./debug-state.js";
+import { escapeCompletionProblem } from "../escape/link.js";
+import { RULES_DIRECTORY } from "../escape/rules.js";
 export async function checkTaskCompletionEvidence(stored, options) {
     const debug = stored.task.debug === undefined ? undefined : await loadDebugProof(options.root, stored.task.debug.rootTaskId);
     if (debug?.control?.paused === true || debug?.control?.mode === "diagnose")
@@ -28,6 +30,24 @@ export async function checkTaskCompletionEvidence(stored, options) {
             attestation?.debugProofs?.[stored.task.id] !== debugProofDigest(debug))
             return { status: "FAIL", code: "TASK_DEBUG_PROOF_REQUIRED", remedy: "Confirm the original cause with current discriminating regression proof, then obtain two fresh independent reviews bound to that debug proof." };
     }
+    // Fails closed: the Escape Loop needs every DEBUG fix to say where the bug came from.
+    if (stored.task.originRequired === true && stored.task.origin === undefined)
+        return { status: "FAIL", code: "ESCAPE_ORIGIN_MISSING", remedy: "Declare the issue origin with task debug --debug-action origin --payload-file <json> (escape-of <commit> + label, pre-existing or external + reason) after the hypothesis is confirmed, then re-verify, re-record the hypothesis and obtain review." };
+    // Escape Loop R2: a declared escape finishes only with its proof (rule replay + backtest, or a promoted red-to-green check).
+    const origin = stored.task.origin, base = debug?.baselineCommit ?? stored.createdSourceCommit;
+    if (origin?.kind === "escape-of" && base !== undefined) {
+        const escape = await escapeCompletionProblem({ root: options.root, taskId: stored.task.id, origin, base });
+        if (escape !== null && "code" in escape)
+            return { status: "FAIL", code: escape.code, remedy: `${escape.reason} Add or fix a tracked ${RULES_DIRECTORY}/<id>.json rule, re-declare the origin and commit the record.` };
+        if (escape !== null) {
+            const [runnerId, checkId] = escape.check.split(":");
+            const proven = new Set((await acceptanceCoverage(stored, options.config, options.sourceFingerprint, options.evidenceStore))
+                .filter(row => row.status === "proven").map(row => row.criterionId));
+            if (!stored.task.criteria.some(c => proven.has(c.id) && c.acceptance?.mode === "behavioral" &&
+                c.acceptance.bindings.some(b => b.runnerId === runnerId && (b.redCheckIds ?? []).includes(checkId))))
+                return { status: "FAIL", code: "ESCAPE_RULE_UNPROVEN", remedy: `The promoted check ${escape.check} must be a redCheckId of a proven behavioral criterion of this task (red baseline, green candidate).` };
+        }
+    }
     if (attestation === null || attestation.taskId !== stored.task.id ||
         ((stored.task.criteria.some(c => c.acceptance !== undefined) || (stored.task.contractRevision ?? 0) > 0 || stored.task.goal !== undefined) &&
             (attestation.schemaVersion !== 3 || attestation.taskContracts?.[stored.task.id] !== taskContractHash(stored.task))) ||

package/dist/runtime/src/task/contract.js

@@ -11,7 +11,9 @@ export function taskContractHash(task) {
         intent: task.intent ?? null, revision: task.contractRevision ?? 0,
         criteria: task.criteria.map(criterionContractHash), ...(task.debug === undefined ? {} : { debug: task.debug }),
         ...(task.surface === undefined ? {} : { surface: sha256(canonicalJson(task.surface)) }),
-        ...(task.surfaceRequired === undefined ? {} : { surfaceRequired: true }) }));
+        ...(task.surfaceRequired === undefined ? {} : { surfaceRequired: true }),
+        ...(task.origin === undefined ? {} : { origin: task.origin }),
+        ...(task.originRequired === undefined ? {} : { originRequired: true }) }));
 }
 export function treeContractHash(tasks) {
     return sha256(canonicalJson(tasks.map(task => ({ id: task.id, hash: taskContractHash(task) }))

package/dist/runtime/src/task/debug-state.js

@@ -50,7 +50,7 @@ export function validDebugState(v) {
     if (new Set(v.receipts.map(r => r.id)).size !== v.receipts.length || v.receipts.filter(r => r.round).length > v.maxRounds)
         return false;
     for (const g of v.grants)
-        if (!exact(g, ["eventId", "sessionId", "sourceDigest", "grantedMs"]) || !text(g.eventId) || !text(g.sessionId) || !hash(g.sourceDigest) || g.grantedMs !== DEBUG_EXTENSION_MS)
+        if (!(exact(g, ["eventId", "sessionId", "sourceDigest", "grantedMs"]) || (exact(g, ["eventId", "sessionId", "sourceDigest", "grantedMs", "spentAtGrantMs"]) && integer(g.spentAtGrantMs))) || !text(g.eventId) || !text(g.sessionId) || !hash(g.sourceDigest) || (g.grantedMs !== DEBUG_EXTENSION_MS && g.grantedMs !== null))
             return false;
     if (new Set(v.grants.map(g => g.eventId)).size !== v.grants.length)
         return false;
@@ -79,10 +79,16 @@ export function createDebugState(rootTaskId, baselineCommit, settings = DEBUG_DE
         hypotheses: [], receipts: [], strategy: null, grants: [], foreground: null, operation: null, checkpoint: null };
 }
 export function debugRounds(state) { return state.receipts.filter(r => r.round).length; }
-export function debugRemainingMs(state, now = Date.now()) {
+export function debugSpentMs(state, now = Date.now()) {
     const starts = [state.foreground?.startedAt, state.operation?.startedAt].filter((startedAt) => startedAt !== undefined);
     const active = starts.length === 0 ? 0 : Math.max(0, now - Math.min(...starts));
-    return Math.max(0, state.budgetMs + state.grants.reduce((n, g) => n + g.grantedMs, 0) - state.consumedMs - active);
+    return state.consumedMs + active;
+}
+export function debugRemainingMs(state, now = Date.now()) {
+    if (state.grants.some(g => g.grantedMs === null))
+        return Number.POSITIVE_INFINITY;
+    const limit = state.grants.reduce((n, g) => Math.max(n, g.spentAtGrantMs ?? n) + (g.grantedMs ?? 0), state.budgetMs);
+    return Math.max(0, limit - debugSpentMs(state, now));
 }
 export function debugStopCause(state, now = Date.now()) {
     if (state.control?.paused === true)