@kylecheng3146/agent-ops 0.8.6 → 0.10.0

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

@@ -9,7 +9,11 @@ export function criterionContractHash(criterion) {
 export function taskContractHash(task) {
     return sha256(canonicalJson({ goalHash: goalHash(task), title: task.title,
         intent: task.intent ?? null, revision: task.contractRevision ?? 0,
-        criteria: task.criteria.map(criterionContractHash), ...(task.debug === undefined ? {} : { debug: task.debug }) }));
+        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.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.js

@@ -21,6 +21,7 @@ import { readWorktreeRecord } from "../parallel/service.js";
 import { evaluateGuardrail } from "../guardrails/evaluate.js";
 import { sameDebugText } from "./debug-intake.js";
 import { nativeProcessIdentity } from "../run/transport.js";
+import { declareEscape, LEDGER_DIRECTORY, removeEscapeRecord, resolveOrigin } from "../escape/link.js";
 function fail(code, message) { throw new AgentOpsError(code, message); }
 const bounded = (v) => typeof v === "string" && v.trim().length > 0 && v.length <= 4096 && !v.includes("\0");
 const session = (v) => bounded(v) && v.length <= 256;
@@ -93,7 +94,8 @@ export class DebugService {
         const records = await this.options.tasks.list();
         const materials = new Set(records.flatMap(r => r.task.criteria.flatMap(c => c.acceptance?.bindings.flatMap(b => b.materials.map(m => m.path)) ?? [])));
         const paths = new Set([...await collectBaseChangePaths(this.options.gitRunner, state.baselineCommit), ...(await collectChangeSurface(this.options.gitRunner)).paths]);
-        const product = [...paths].filter(path => !materials.has(path) && !/(?:^|\/)(?:tests?|fixtures)(?:\/|$)|(?:\.test|\.spec)\./u.test(path)).sort();
+        // The escape ledger is data about the fix, not a repair candidate.
+        const product = [...paths].filter(path => !materials.has(path) && !path.startsWith(LEDGER_DIRECTORY + "/") && !/(?:^|\/)(?:tests?|fixtures)(?:\/|$)|(?:\.test|\.spec)\./u.test(path)).sort();
         const entries = [];
         for (const path of product) {
             try {
@@ -243,6 +245,27 @@ export class DebugService {
         await this.#evidence(taskId, input.reference);
         await this.#mutate(root, { ...root.debug, strategy: { from: input.from, to: input.to, reason: input.reason, references: [input.reference], afterRound: debugRounds(root.debug) }, checkpoint: null });
     }
+    /** Escape Loop: where the confirmed cause came from, bound into the contract before review. */
+    async origin(taskId, input) {
+        const root = await this.root(taskId);
+        if (root.task.id !== taskId)
+            fail("ESCAPE_ORIGIN_INVALID", "Declare the origin on the original issue task.");
+        if (root.status !== "active" || root.debug.operation !== null)
+            fail("TASK_DEBUG_BUSY", "Origin needs an active idle issue.");
+        if (debugRemainingMs(root.debug) === 0)
+            fail("TASK_DEBUG_BUDGET_EXHAUSTED", "The original issue's active budget is exhausted.");
+        if (!root.debug.hypotheses.some(h => h.status === "confirmed"))
+            fail("ESCAPE_ORIGIN_EARLY", "Declare the origin only after discriminating evidence confirms a hypothesis.");
+        const origin = await resolveOrigin(this.options.gitRunner, input);
+        const record = await this.options.tasks.revise(taskId, { expectedContractHash: taskContractHash(root.task), origin, debugOrigin: true,
+            reason: `Declare issue origin: ${origin.kind === "escape-of" ? "escape-of " + origin.commit : origin.kind}.` });
+        if (origin.kind !== "escape-of") {
+            await removeEscapeRecord(this.options.root, taskId);
+            return { record };
+        }
+        return { record, escape: await declareEscape({ root: this.options.root, git: this.options.gitRunner, taskId, origin,
+                base: root.debug.baselineCommit, now: new Date().toISOString() }) };
+    }
     async remaining(taskId) { return debugRemainingMs((await this.root(taskId)).debug); }
     async #userEvent(sessionId, home, kind = "latest") {
         const record = await readWorktreeRecord(this.options.root);
@@ -348,6 +371,9 @@ export class DebugService {
         if (root.debug.receipts.length >= 256)
             fail("TASK_DEBUG_HISTORY_LIMIT", "Execution history is full; retain it and report the blocker.");
         const productDigest = await this.#productDigest(root.debug);
+        // EVIDENCE-SURFACE-001: intake may start without a surface, the first repair may not.
+        if (kind === "verify" && task.task.surfaceRequired === true && task.task.surface === undefined && productDigest !== sha256(canonicalJson([])))
+            fail("SURFACE_MISSING", "Add the surface audit with task revise --surface-file before verifying the first repair.");
         const previousCandidate = root.debug.receipts.filter(r => r.kind === "verify" && (r.outcome === "PASS" || r.outcome === "FAIL")).at(-1)?.productDigest ?? sha256("[]");
         const cause = debugStopCause(root.debug);
         // Recovery reruns the original verifier; changed product content still needs fresh proof.

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

@@ -18,6 +18,10 @@ import { commitIdentity } from "../schema/acceptance.js";
 import { createDebugState, DEBUG_DEFAULTS } from "./debug-state.js";
 import { DebugService } from "./debug.js";
 import { sameDebugText } from "./debug-intake.js";
+import { isCovers, parseSurface } from "../surface/schema.js";
+import { declareEscape, resolveOrigin } from "../escape/link.js";
+import { configProposal } from "../escape/rules.js";
+import { logGateCatch } from "../logging/local-log.js";
 const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
 function defaultTaskId() {
     return `task-${randomUUID()}`;
@@ -123,9 +127,13 @@ export class TaskService {
         const criteria = structuredClone(input.criteria).map(criterion => ({ ...criterion,
             ...(criterion.acceptance === undefined ? {} : { acceptance: { ...criterion.acceptance,
                     baselineCommit: criterion.acceptance.baselineCommit ?? createdSourceCommit } }) }));
+        const surface = input.surface === undefined ? undefined : parseSurface(input.surface);
         const task = {
             schemaVersion: TASK_SCHEMA_VERSION,
             id: this.#generateId(),
+            ...(surface === undefined ? {} : { surface }),
+            ...(input.requireSurface === true ? { surfaceRequired: true } : {}),
+            ...(input.origin === undefined ? {} : { origin: structuredClone(input.origin) }),
             title: input.title,
             ...(input.intent === undefined ? {} : { intent: input.intent }),
             criteria,
@@ -145,6 +153,10 @@ export class TaskService {
                 throw taskError("TASK_DEBUG_DISABLED", "Task debug routing is explicitly disabled.");
             debugSettings = config.features.debug ?? DEBUG_DEFAULTS;
             task.debug = { rootTaskId: task.id, facts: [...(input.debug.facts ?? [])], unknowns: [...(input.debug.unknowns ?? [])] };
+            if (input.origin !== undefined)
+                throw taskError("ESCAPE_ORIGIN_DEBUG_ACTION", "A DEBUG issue declares its origin with task debug --debug-action origin after a confirmed hypothesis.");
+            if (input.parentTaskId === undefined)
+                task.originRequired = true;
         }
         const validation = validateTask(task);
         if (!validation.ok) {
@@ -186,6 +198,14 @@ export class TaskService {
                     validation.value.debug = structuredClone(parent.task.debug);
                 }
             }
+            if (input.requireSurface === true && validation.value.debug === undefined) {
+                const parentSurface = state.tasks.find(record => record.task.id === input.parentTaskId)?.task.surface;
+                const surfacedParent = parentSurface !== undefined && !isCovers(parentSurface);
+                if (surface === undefined || isCovers(surface) !== surfacedParent)
+                    throw taskError("SURFACE_MISSING", surfacedParent
+                        ? "A subtask of a surfaced parent declares --surface-file {\"covers\": [surface-id]}."
+                        : "A new task needs --surface-file with the four-axis surface audit (EVIDENCE-SURFACE-001).");
+            }
             const record = {
                 task: validation.value,
                 ...(input.debug === undefined ? {} : { debug: createDebugState(task.id, createdSourceCommit, debugSettings, this.#completion.root) }),
@@ -250,8 +270,19 @@ export class TaskService {
             throw taskError("TASK_NOT_ACTIVE", "Only active tasks can revise acceptance.");
         if (taskContractHash(previous.task) !== input.expectedContractHash)
             throw taskError("TASK_CONTRACT_CHANGED", "Task contract changed.");
+        // With none of them, a revision only rebinds the task to the current configuration (checked below).
+        const rebindOnly = input.criteria === undefined && input.surface === undefined && input.origin === undefined;
+        if (rebindOnly && this.#completion === undefined)
+            throw taskError("TASK_REVISION_INVALID", "Revision requires criteria, a surface, an origin, or a combination.");
+        if (input.origin !== undefined && previous.task.debug !== undefined && input.debugOrigin !== true)
+            throw taskError("ESCAPE_ORIGIN_DEBUG_ACTION", "A DEBUG issue declares its origin with task debug --debug-action origin after a confirmed hypothesis.");
+        // Re-declaring the same origin only refreshes its ledger record; the contract and its proof stand.
+        if (input.criteria === undefined && input.surface === undefined && input.origin !== undefined &&
+            canonicalJson(input.origin) === canonicalJson(previous.task.origin ?? null))
+            return previous;
+        const surface = input.surface === undefined ? previous.task.surface : parseSurface(input.surface);
         const baseline = input.baseline ?? previous.createdSourceCommit;
-        const criteria = structuredClone(input.criteria).map(criterion => {
+        const criteria = input.criteria === undefined ? structuredClone(previous.task.criteria) : structuredClone(input.criteria).map(criterion => {
             if (criterion.acceptance === undefined)
                 return criterion;
             const sha = criterion.acceptance.baselineCommit ?? baseline;
@@ -263,7 +294,8 @@ export class TaskService {
             return { ...criterion, acceptance: { ...criterion.acceptance, baselineCommit: sha } };
         });
         const next = { ...previous.task, schemaVersion: TASK_SCHEMA_VERSION,
-            contractRevision: (previous.task.contractRevision ?? 0) + 1, criteria };
+            contractRevision: (previous.task.contractRevision ?? 0) + 1, criteria, ...(surface === undefined ? {} : { surface }),
+            ...(input.origin === undefined ? {} : { origin: structuredClone(input.origin) }) };
         const checked = validateTask(next);
         if (!checked.ok)
             throw taskError("TASK_INVALID", checked.errors[0]?.message ?? "Invalid criterion revision.");
@@ -278,6 +310,8 @@ export class TaskService {
                 throw taskError("TASK_INVALID", configured.errors[0]?.message ?? "Invalid binding.");
             policyConfigHash = calculateConfigHash(config);
         }
+        if (rebindOnly && policyConfigHash === previous.policyConfigHash)
+            throw taskError("TASK_REVISION_INVALID", "Nothing to revise: criteria, surface, origin and configuration are unchanged.");
         if (criteria.some(c => c.acceptance !== undefined))
             await this.#retainBaselines(next);
         const now = assertTimestamp(this.#now());
@@ -665,7 +699,10 @@ export class TaskService {
     async recordVerificationEvidence(snapshot, evidenceInput, sourceFingerprint) {
         if (snapshot.status === "active") {
             const result = await this.recordEvidence(snapshot.task.id, evidenceInput);
-            await this.clearFailure(snapshot.task.id);
+            // A verified red turning green is a gate catch (advisory, fail-open).
+            if (await this.clearFailure(snapshot.task.id) &&
+                (await this.#completion?.loadConfig().catch(() => undefined))?.profiles.includes("advisory") === true)
+                await logGateCatch("VERIFY_RED_GREEN", snapshot.task.id);
             return result;
         }
         const completion = this.#completion;
@@ -789,18 +826,48 @@ export class TaskService {
             return structuredClone(advanced);
         });
     }
+    /** Escape Loop: resolve a declared commit-ish through this repository's Git (argv only). */
+    async resolveOrigin(value) {
+        if (this.#completion === undefined)
+            throw taskError("ESCAPE_CONTEXT_REQUIRED", "Escape linking requires repository context.");
+        return await resolveOrigin(this.#completion.gitRunner, value);
+    }
+    /** Link a normal task's escape-of origin and write its tracked ledger record. */
+    async declareEscape(taskId) {
+        const completion = this.#completion;
+        const record = await this.status({ taskId });
+        const origin = record.task.origin;
+        if (completion === undefined || origin?.kind !== "escape-of" || record.createdSourceCommit === undefined)
+            throw taskError("ESCAPE_CONTEXT_REQUIRED", "Escape linking needs an escape-of origin, a creation commit and repository context.");
+        return await declareEscape({ root: completion.root, git: completion.gitRunner, taskId, origin,
+            base: record.createdSourceCommit, now: assertTimestamp(this.#now()) });
+    }
+    /** Escape Loop R2: printed only, never written; the promoted check becomes a required verifier through update. */
+    async escapeConfigProposal(check) {
+        let config;
+        try {
+            config = await this.#completion?.loadConfig();
+        }
+        catch {
+            config = undefined;
+        }
+        return configProposal(check, config);
+    }
+    /** True when a recorded verification failure was cleared (red to green). */
     async clearFailure(taskId) {
         const now = assertTimestamp(this.#now());
-        await this.#store.mutate((state) => {
+        return await this.#store.mutate((state) => {
             const current = findTask(state, taskId);
             if (current.failureFingerprint === null) {
-                return;
+                return false;
             }
             replaceTask(state, {
                 ...current,
                 updatedAt: now,
                 failureFingerprint: null
             });
+            // A source change mid-run is not a red the code fixed.
+            return current.failureFingerprint.commandId !== "source-snapshot";
         });
     }
     async coverage(taskId) {

package/dist/runtime/src/verify/acceptance-replay.js

@@ -1,4 +1,4 @@
-import { lstat, mkdir, mkdtemp, readFile, realpath, rm, writeFile, chmod } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, readFile, realpath, writeFile, chmod } from "node:fs/promises";
 import { join, delimiter, isAbsolute } from "node:path";
 import { tmpdir } from "node:os";
 import { writePrivateFile } from "../security/permissions.js";
@@ -6,6 +6,7 @@ import { redactSecrets } from "../security/redact.js";
 import { randomUUID } from "node:crypto";
 import { canonicalJson } from "../config/hash.js";
 import { sha256 } from "../fs/hash.js";
+import { removeTemporary } from "../fs/temporary.js";
 import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { criterionContractHash, taskContractHash } from "../task/contract.js";
 import { aggregateAcceptanceRun, makeAcceptanceCheck, makeAcceptanceRun } from "./acceptance-protocol.js";
@@ -13,6 +14,8 @@ import { collectNodeAcceptance, collectJestAcceptance, collectVitestAcceptance,
 import { buildVerificationEvidence } from "./evidence.js";
 import { collectChangeSurface, resolveGitCommit } from "./change-surface.js";
 import { runVerificationCommand } from "./spawn.js";
+/** Limits for runner steps without their own timeoutMs: installs are slow, git plumbing is not. */
+export const ACCEPTANCE_TIMEOUTS = { setup: 600_000, build: 300_000, testBuild: 300_000, run: 300_000, git: 60_000 };
 async function executableIdentity(command, cwd, env) {
     const paths = isAbsolute(command) ? [command] : command.includes("/") ? [join(cwd, command)] :
         (env.PATH ?? "").split(delimiter).filter(Boolean).map(path => join(path, command));
@@ -113,13 +116,21 @@ export async function replayAcceptance(options) {
             const temp = await mkdtemp(join(tmpdir(), "agent-ops-acceptance-"));
             const checkout = join(temp, "repository");
             const env = replayEnvironment(checkout, phase, executionId);
-            const command = async (executable, args, cwd, timeoutMs = 60_000) => {
+            let timedOut;
+            const command = async (executable, args, cwd, stage, own) => {
                 const remaining = await options.remainingMs?.();
                 if (remaining === 0)
                     throw new AgentOpsError("TASK_DEBUG_BUDGET_EXHAUSTED", "The original issue's active budget is exhausted.");
-                return await runVerificationCommand({ id: group.runner.id, command: executable, args: [...args], cwd: ".", required: true,
-                    evidence: { kind: "exit-code" }, timeoutMs: Math.min(timeoutMs, remaining ?? Infinity) }, { cwd, runner: options.processRunner, env, replaceEnv: true,
+                const limit = own ?? ACCEPTANCE_TIMEOUTS[stage];
+                const result = await runVerificationCommand({ id: group.runner.id, command: executable, args: [...args], cwd: ".", required: true,
+                    evidence: { kind: "exit-code" }, timeoutMs: Math.min(limit, remaining ?? Infinity) }, { cwd, runner: options.processRunner, env, replaceEnv: true,
                     outputLimitBytes: 1024 * 1024, ...(options.signal === undefined ? {} : { signal: options.signal }) });
+                if (result.failureClass === "timeout" && timedOut === undefined)
+                    timedOut = stage === "git"
+                        ? `Runner ${group.runner.id} ${phase}: git checkout exceeded ${limit} ms.`
+                        : `Runner ${group.runner.id} ${phase}: ${stage} step ${executable} exceeded ${limit} ms; raise ` +
+                            (stage === "run" ? "verification.acceptanceRunners[].timeoutMs" : `the step's timeoutMs in verification.acceptanceRunners[].${stage}`) + ".";
+                return result;
             };
             let aggregate;
             let failure = "replay-unavailable";
@@ -133,13 +144,14 @@ export async function replayAcceptance(options) {
             try {
                 for (const [cwd, args] of [[temp, ["clone", "--no-hardlinks", "--quiet", "--", options.root, checkout]],
                     [checkout, ["fetch", "--quiet", "--", options.root, commit]], [checkout, ["checkout", "--detach", "--quiet", commit]]]) {
-                    const result = await command("git", args, cwd);
+                    const result = await command("git", args, cwd, "git");
                     if (result.status !== "PASS")
                         throw new Error("checkout-unavailable");
                 }
                 const cwd = group.runner.cwd === "." ? checkout : await resolveContainedPath(checkout, group.runner.cwd);
-                for (const step of [...(group.runner.setup ?? []), ...(group.runner.build ?? [])]) {
-                    const result = await command(step.command, step.args, cwd, step.timeoutMs);
+                for (const [stage, step] of [...(group.runner.setup ?? []).map(step => ["setup", step]),
+                    ...(group.runner.build ?? []).map(step => ["build", step])]) {
+                    const result = await command(step.command, step.args, cwd, stage, step.timeoutMs);
                     steps.push({ command: step.command, args: step.args, status: result.status, failureClass: result.failureClass, stderr: result.stderr });
                     if (result.status !== "PASS")
                         throw new Error("setup-or-build-unavailable");
@@ -172,7 +184,7 @@ export async function replayAcceptance(options) {
                     await chmod(path, material.mode);
                 }
                 for (const step of group.runner.testBuild ?? []) {
-                    const result = await command(step.command, step.args, cwd, step.timeoutMs);
+                    const result = await command(step.command, step.args, cwd, "testBuild", step.timeoutMs);
                     steps.push({ command: step.command, args: step.args, status: result.status, failureClass: result.failureClass, stderr: result.stderr });
                     if (result.status !== "PASS")
                         throw new Error("test-build-unavailable");
@@ -194,7 +206,7 @@ export async function replayAcceptance(options) {
                     throw new Error("missing-executable");
                 executionDigest = sha256(canonicalJson({ commit, materialDigest, runner: group.runner, argv, dependencies,
                     executable: identity, platform: process.platform, arch: process.arch, environment: sha256(canonicalJson(env)) }));
-                output = await command(group.runner.command, argv, cwd, group.runner.timeoutMs);
+                output = await command(group.runner.command, argv, cwd, "run", group.runner.timeoutMs);
                 run = collected(group.runner, output, checkout, { executionId, phase,
                     frameworkVersion: group.runner.adapter === "node" ? process.version : "dependency-lock:" + sha256(canonicalJson(dependencies)) });
                 aggregate = aggregateAcceptanceRun(run, requested);
@@ -208,7 +220,7 @@ export async function replayAcceptance(options) {
                 failure = error instanceof AgentOpsError && error.code === "TASK_DEBUG_BUDGET_EXHAUSTED" ? "debug-budget-exhausted" : error instanceof Error && /^[a-z-]+$/u.test(error.message) ? error.message : "replay-unavailable";
             }
             finally {
-                await rm(temp, { recursive: true, force: true });
+                await removeTemporary(temp);
             }
             const finishedAt = new Date().toISOString();
             const artifactContent = redactSecrets(JSON.stringify({ schemaVersion: 1, executionId, phase, commit,
@@ -236,7 +248,8 @@ export async function replayAcceptance(options) {
                     taskContractHash: taskContractHash(options.task), acceptance: { criterionContractHash: criterionContractHash(criterion),
                         bindingHash: sha256(canonicalJson({ runnerId: group.runner.id, materials: group.binding.materials })), phase, commit, pairedCommit: phase === "baseline" ? candidate : group.baseline, materialDigest, executionDigest, executionArtifact, checks } });
                 const reference = await options.evidenceStore.save(evidence);
-                reports.push({ criterionId: criterion.id, runnerId: group.runner.id, phase, status, failureClass: evidence.failureClass, reference });
+                reports.push({ criterionId: criterion.id, runnerId: group.runner.id, phase, status, failureClass: evidence.failureClass, reference,
+                    ...(timedOut === undefined || status === "PASS" ? {} : { detail: timedOut }) });
             }
         }
     }

package/docs/en/guides/configuration.md

@@ -115,7 +115,14 @@ Capability checks and model starts are reported on stderr, including under
 `--json`; stdout remains one final JSON envelope and raw reviewer output is
 never streamed. SIGINT or SIGTERM terminates the active reviewer process tree,
 does not advance the fallback chain, and never writes an attestation. An
-exhausted timeout chain reports `timeout`, not `missing-cli`.
+exhausted timeout chain reports `timeout`, not `missing-cli`. Each reviewer
+round may take 30 minutes by default (`reviewRoles[].timeoutMs` overrides it);
+a reviewer that prints nothing for the stall window is still stopped early.
+
+Acceptance runner steps without their own `timeoutMs` get 10 minutes for
+`setup`, 5 minutes each for `build`, `testBuild` and the runner itself, and
+1 minute for the git checkout. A step that times out is reported as
+`UNKNOWN` with the step, its limit and the `timeoutMs` field that raises it.
 
 The task ID is explicit and its criteria are always used; no session fallback
 or criterion filter can replace the original task requirements. Review rechecks
@@ -200,6 +207,14 @@ evidence. Give each editing conversation its own worktree instead:
   `.env` or `local.properties`); a file Git already checked out is never
   overwritten. Trust is inherited only when the main checkout is trusted and
   the worktree's effective config is identical.
+- An approved `agent-ops update` in the main checkout copies the new config
+  into every session worktree whose copy is still the previously trusted one,
+  and trusts it for the same commands; the plan lists the session worktrees
+  before you confirm. A hand-edited worktree config is left alone, and run
+  worktrees keep their own authorization. A task created under the old config is
+  not rebound automatically: review names the
+  `agent-ops task revise --task <id> --expected-contract <hash> --reason <text>`
+  that rebinds it (criteria and surface unchanged), then verify again.
 - `setup` commands run in the new worktree (default timeout ten minutes) for
   what Git does not carry, such as installed dependencies. They are part of
   the trusted config, so they need no separate approval; a failing step

package/docs/en/guides/task-debug.md

@@ -57,6 +57,18 @@ Use `task debug --task <id> --debug-action <action>`:
   new reference and `reason`.
 - `strategy --payload-file <json>` records a different `from`/`to` method,
   substantive `reason` and discriminating `reference`. Only one switch is allowed.
+- `origin --payload-file <json>` declares where the bug came from once a
+  hypothesis is confirmed: `{"kind": "escape-of", "commit": "<commit>", "label":
+  "<earliest gate>"}` (optional `"receipt"`) or `{"kind": "pre-existing" |
+  "external", "reason": "..."}`. It revises the contract, so re-verify and
+  re-record the confirmed hypothesis before review; finish refuses
+  `ESCAPE_ORIGIN_MISSING` without it. `escape-of` prints the link state and
+  `git blame` hints and writes `.agent-ops-escapes/<task-id>.json`, which is
+  committed with the fix (see `EVIDENCE-ESCAPE-001`). A surface label also
+  needs a tracked `.agent-ops-escapes/rules/<rule-id>.json` rule that replays
+  at the escaped commit, and a criteria/verify label needs `"promote":
+  "<runnerId:checkId>"`; finish refuses `ESCAPE_RULE_UNPROVEN` otherwise (see
+  `EVIDENCE-ESCAPE-002`).
 - `checkpoint --session <id>` saves the current bound source/policy/stop cause.
 - `resume --session <id>` recovers a matching owned worktree checkpoint. Mismatches
   require human confirmation and remain preserved; this command cannot waive them.

package/docs/en/spec/acceptance-and-evidence.md

@@ -68,6 +68,158 @@ Each child worktree MUST record its modification intent before editing.
 - Positive: `A child records its planned API change, commits it, and the final receipt includes that intent and integrated verification.`
 - Negative: `A child edits first and supplies a retrospective one-line intent at delivery.`
 
+## EVIDENCE-SURFACE-001
+
+Every new task MUST record a surface audit of where else its change lands before writing criteria, and review MUST NOT run while discovery finds an unclassified place.
+
+- Trigger: Creating a task (`task create`, a run plan, or before a DEBUG task's first repair), revising its surface, or reviewing it.
+- Action: Search four axes with recorded fixed-string queries or `n/a: reason`, classify every hit as included, excluded (glob + reason) or UNKNOWN, give every surface row an observable `behavior`, and declare each shared contract compatible or breaking. Pass it with `task create|revise --surface-file <json>`.
+- Evidence: The surface is stored on the task, bound into its contract hash with revision history, replayed by `git grep -F` before review, and handed to both reviewers under the `surface-coverage` criterion.
+- Positive: `A diff token hits three copy-pasted sibling pages; the audit includes them with their behavior before review runs.`
+- Negative: `Exclude src/** because it is "out of scope", or list only the files the diff already touches.`
+
+- Axes: `dependents` (importers, callers, readers), `duplicates` (copied
+  markup, strings, logic that imports nothing), `otherPaths` (other routes,
+  modes, entry points or re-entries to the same concept) and `sharedState`
+  (storage, cache, messages, external APIs, client storage, issued URLs). The
+  design is stack-agnostic: the same axes cover frontend, backend, database,
+  cache and message flows.
+- `included` rows carry `id`, `path` glob and `behavior`; `excluded` rows carry
+  `glob` and a reason saying why the surface is unaffected ("out of scope" is
+  not a reason); `unknown` rows name a reader the repository cannot see.
+  `contracts` declare `compatible` or `breaking`. A single surface is allowed.
+- `valueChanges` `[{producer, kind, change, consumers, indirectConsumers}]`
+  list two hops whenever a value's semantics change (clear, redact, default,
+  normalize, unit/format).
+- `scenarios` cover five generic dimensions — `initialState` (empty vs
+  existing), `redo` (reload, retry, redelivery, idempotency), `timeBoundary`
+  (day, TTL, timezone), `identitySwitch` (store, role, tenant) and
+  `concurrency` — each `{applies: true, behavior}` or `{na: reason}`.
+- A parent holds the surface; its children declare `{"covers": [surface-id]}`
+  and their union must equal the parent's included list.
+- Before any reviewer runs, discovery replays with `git grep -F` through argv
+  (never a shell or a regex built from task text), cheapest source first:
+  recorded queries; enclosing function names from diff hunk headers;
+  template-literal fixed fragments (at least 4 characters, separator-bounded,
+  such as `order:`, `user_`, `menu.`); compound identifiers (snake_case,
+  camelCase or containing digits, so prose words are not queries) and string
+  literals from added and removed lines (at least 6 characters; skipped as too
+  generic above 10 file hits, changed files included). Every hit outside the diff and the surface lists stops review.
+- A derived query (diff token, template fragment or hunk-header name) whose hits
+  are incidental may be dismissed once in the surface's optional `dismissed`
+  list (`{query, reason}`, reason at most 256 characters, "out of scope" is
+  not a reason) instead of one exclusion per file. Recorded axis queries and
+  escape-rule hits cannot be dismissed, nor can a query reaching fewer than 4
+  files outside the diff (the likeliest sibling signal); at most 128
+  dismissals. Reviewers see each dismissal with its hit count, flagged when it
+  hid a file an earlier `SURFACE_UNCLASSIFIED` block named.
+  Results are cached by HEAD, base, diff, query set and config hash.
+- Review returns NOT_RUN with: `SURFACE_MISSING` (no or unparseable surface;
+  also refused at create for non-DEBUG tasks), `SURFACE_UNCLASSIFIED`,
+  `SURFACE_QUERY_TOO_BROAD` (one recorded query over 200 files),
+  `SURFACE_EXCLUSION_TOO_BROAD` (one glob over 10 files, or any file in the
+  diff), `SURFACE_DISMISSAL_TOO_BROAD` (over 128 dismissals),
+  `SURFACE_DISMISSAL_INVALID` (a recorded or rare query), `SCENARIO_MISSING`, `SURFACE_BUDGET_EXCEEDED` (120 s total, never
+  silently skipped) or `SURFACE_UNASSIGNED` (children's covers differ from the
+  parent's included list; checked by every review, including advance and batch).
+- A surface revision is a contract revision: fresh evidence and two fresh
+  reviews. Exclusions added after an `SURFACE_UNCLASSIFIED` block are flagged
+  to reviewers as post-block exclusions.
+- Tasks created before this rule shipped are grandfathered. Advisory local-log
+  metrics per discovery source are fail-open and never evidence.
+- Plain `worktree finish` writes the same local receipt as advance, including
+  both rounds' residual risks and non-blocking findings, references it in the
+  git note and prints the residual risks.
+
+## EVIDENCE-ESCAPE-001
+
+Every DEBUG fix MUST declare where its bug came from before review, and a declared escape MUST be linked, labelled and recorded mechanically.
+
+- Trigger: A DEBUG hypothesis is confirmed, or a normal task fixes a bug that passed earlier gates.
+- Action: Declare `origin` with `task debug --debug-action origin --payload-file <json>`: `{"kind": "escape-of", "commit": "<commit>", "label": "<label>"}` (optional `"receipt"`), or `{"kind": "pre-existing" | "external", "reason": "..."}`. A normal task may opt in with `task create|revise --escape-of <commit> --escape-label <label> [--escape-receipt <id>]`. Commit the `.agent-ops-escapes/<task-id>.json` record with the fix.
+- Evidence: `origin` is bound into the task contract hash; finish, `task complete` and the completion gate refuse a DEBUG task created after this rule without it as `ESCAPE_ORIGIN_MISSING`; both reviewers receive the link state, labels, facts and residual risks under the `escape-label` criterion.
+- Positive: `Hypothesis confirmed; origin escape-of 864dbbe2 label surface; replay marks the missed page surface-unseen; the record is committed with the fix.`
+- Negative: `Finish a DEBUG fix without an origin, or relabel a surface-excluded miss as review because the reviewer "should have noticed".`
+
+- The declaration comes after a confirmed hypothesis (`ESCAPE_ORIGIN_EARLY`
+  otherwise), inside the DEBUG budget. It is a contract revision: re-verify,
+  re-record the confirmed hypothesis with the new evidence, then review.
+  Re-declaring replaces the record. The output lists `git blame` hint commits
+  for lines the fix changed or removed; blame is a hint only, because an
+  omission bug lives in lines nobody wrote.
+- Finish receipts stay local in the Git common directory. Schema 2 records
+  every commit in target..candidate and a per-file diff fingerprint (blob ids
+  and hunk positions dropped, so a squash merge keeps it); schema 1 receipts
+  still load and link by exact head only.
+- Link states are counted separately: `gated` (a receipt matched),
+  `unresolved` with a reason (`receipt-not-local` when a Git note or
+  `--escape-receipt` names a receipt this machine lacks, `ambiguous-receipt`,
+  `link-unavailable`) and `ungated` (no receipt and no note). Resolution
+  order: `--escape-receipt` override, the commit inside a receipt's recorded
+  range (schema 1: exact head), per-file fingerprint match, then unresolved or
+  ungated.
+- Label: one primary label, the earliest gate that could have caught the
+  escape — `requirement`, `surface`, `scenario`, `criteria`, `verify`,
+  `review` — or `flagged` (a residual risk or finding already said it) or
+  `out-of-model`. The agent proposes it; `git grep -F` replay of the linked
+  receipt's recorded surface queries at its candidate marks each file the fix
+  touched as included, excluded, hit, unseen or absent, and `surface-excluded`
+  or `surface-unseen` overrides any later label. The two reviewers adjudicate.
+- The ledger is git-tracked and data only (commits, paths, labels, reasons,
+  counts; never file contents or transcripts), one file per task so parallel
+  worktrees never conflict. Gate catches (`SURFACE_*` and `SCENARIO_MISSING`
+  review blocks, review FAIL, verify red to green) append advisory local-log
+  `gate-catch` events with only the code and task id; logging fails open,
+  while the origin requirement fails closed.
+- Scope R1 records. Rules learned from escapes, replay proof, backtests,
+  `--escape-fix` and an `agent-ops escapes` report are R2
+  ([EVIDENCE-ESCAPE-002](#evidence-escape-002)).
+
+## EVIDENCE-ESCAPE-002
+
+A surface escape MUST become a proven, tracked rule before its fix finishes, and learned rules MUST only tighten the surface gate.
+
+- Trigger: A declared escape-of origin (EVIDENCE-ESCAPE-001), or a past escape backfilled with `task create --escape-of <commit> --escape-label <label> --escape-fix <fix-commit>`.
+- Action: For a `surface`, `surface-unseen` or `surface-excluded` label, commit a rule `.agent-ops-escapes/rules/<rule-id>.json` shaped `{"id", "escape", "label", "trigger": {"paths", "tokens"}, "expand": {"paths", "queries"}, "noExclude"}` and re-declare the origin. For `criteria` or `verify`, name the fixing task's red-to-green check with `--escape-promote <runnerId:checkId>` (DEBUG payload `"promote"`). Other labels record a lesson.
+- Evidence: Finish, `task complete` and the completion gate re-run the proof and refuse `ESCAPE_RULE_UNPROVEN`, `ESCAPE_RULE_TOO_BROAD` or `SURFACE_BUDGET_EXCEEDED`; the ledger record stores the proving rule, its content hash and its backtest fires, commits and rate.
+- Positive: `Escape surface-unseen; rule image-size-siblings fires on the escaped commit, its query hits both missed sibling pages there, and fires on 2 of the last 200 commits.`
+- Negative: `Finish a surface escape whose rule never fires on the escaped commit, or add a rule field that excludes paths.`
+
+- Rules are data only and need no trust: triggers and expands become argv
+  `git grep -F` queries and path globs, never shell or regex. The strict schema
+  has no field that removes a query, adds an exclusion or relaxes any gate.
+  An invalid rule fails closed as review NOT_RUN `ESCAPE_RULE_INVALID`; a
+  symlinked or non-regular rules directory or file as `ESCAPE_RULE_UNSAFE`.
+- Surface gate: a rule fires only when the task diff matches a trigger path
+  glob or a changed line contains a trigger token. Every expand hit of a fired
+  rule must be in the diff, included, UNKNOWN or excluded, else
+  `SURFACE_UNCLASSIFIED`; with `noExclude` an excluded hit is
+  `ESCAPE_RULE_NO_EXCLUDE`. Fires and included/excluded counts per rule go to
+  local-log `escape-rule` events (fail-open).
+- Proof: the rule must name the escaped commit, fire on that commit's own diff
+  and, replayed at that commit, hit every missed path that existed there.
+  Missed paths come from the fix commit with `--escape-fix`, otherwise from
+  the task diff. A `criteria`/`verify` escape needs its promoted check to be a
+  `redCheckIds` entry of a proven behavioral criterion of the fixing task
+  (red baseline, green candidate); the output prints a config proposal for a
+  new required verifier, and agent-ops never writes `.agent-ops/config.json`.
+  `scenario`, `review`, `requirement`, `flagged` and `out-of-model` record an
+  unproven lesson with a reason and do not block. No review or test ever runs
+  at the escaped commit.
+- Backtest: the trigger is matched against the diffs of the last 200
+  first-parent commits in one argv `git log`; a fire rate above 30% is
+  `ESCAPE_RULE_TOO_BROAD`. It is time-budgeted (over budget is
+  `SURFACE_BUDGET_EXCEEDED`, never a silent pass) and cached by HEAD and rule
+  hash. Editing a proving rule makes the ledger record stale until re-declared.
+- `agent-ops escapes [--json]` is a read-only, fail-open report: misses per
+  label from the ledger, `gate-catch` codes from the local log, origin mix,
+  link-state mix with unresolved reasons, and per-rule fire/included/excluded
+  counts with time windows, as raw counts with n and `insufficient-data`
+  when n < 10. Rules with at least 10 fires and no included hit are listed as
+  retirement candidates; removal is always a reviewed commit, never automatic.
+- R2 supersedes the phase-2 `surface.aliases` config (now tracked rules) and
+  `surface stats` (now `agent-ops escapes`).
+
 ## EVIDENCE-AGGREGATE-001
 
 The verifier MUST return FAIL when a criterion is missing, duplicated, unknown, or has empty evidence.

package/docs/en/spec/judgment.md

@@ -10,6 +10,13 @@ The operator MUST stop when requirements, authorization, or a required decision
 - Positive: `Ask whether project or user scope is intended before applying installation.`
 - Negative: `Assume project scope because it is more convenient.`
 
+Surface audit triggers ([EVIDENCE-SURFACE-001](acceptance-and-evidence.md#evidence-surface-001)) also stop before editing:
+
+- A `breaking` change to a shared contract with any UNKNOWN reader.
+- A discovered surface excluded as "intentionally different": send the human
+  one consolidated behavior table (surface, current behavior, proposed
+  behavior, reason) and wait for the decision.
+
 ## JUDGMENT-RETRY-001
 
 The operator MUST change approach after the same failure repeats without new information.

package/docs/en/spec/loop-engineering.md

@@ -53,10 +53,10 @@ This module defines the bounded loop used to plan, implement, verify, and hand o
 
 ## LOOP-START-001
 
-The operator MUST state acceptance criteria before editing and MUST stop when each criterion has evidence.
+The operator MUST audit the change's surfaces, then state acceptance criteria before editing, and MUST stop when each criterion has evidence.
 
 - Trigger: Starting a multi-step implementation or debugging loop.
-- Action: Record 2–5 observable criteria, then inspect only the files needed for the current step.
+- Action: Record the surface audit ([EVIDENCE-SURFACE-001](acceptance-and-evidence.md#evidence-surface-001)), then 2–5 observable criteria, then inspect only the files within the audited scope that the current step needs.
 - Evidence: The task record and final report link each criterion to a command or read-back.
 - Positive: `Criteria: tests pass; package builds; changed files are read back.`
 - Negative: `I changed the repository and will decide what success means afterward.`

package/docs/en/spec/review.md

@@ -84,6 +84,11 @@ successful refutation MUST make the run FAIL.
 - Negative: `Manufacture a refutation so the challenge looks effective.`
 - Note: With one configured target the same target is invoked again in a fresh
   session. A FAIL is already terminal and is never re-checked.
+- Note: For a surfaced task the second round also hunts unlisted surfaces and
+  scenarios under `surface-coverage`: it checks the five fixed scenario
+  dimensions and may run at most 3 new `git grep -F` queries per axis. Round 1
+  replays the recorded queries and reads every listed `valueChanges` consumer;
+  this is the only exception to "do not survey the repository".
 
 ## REVIEW-HOST-001