@kylecheng3146/agent-ops 0.9.0 → 0.10.0

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);

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

@@ -19,6 +19,9 @@ 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()}`;
@@ -130,6 +133,7 @@ export class TaskService {
             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,
@@ -149,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) {
@@ -262,8 +270,16 @@ 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.");
-        if (input.criteria === undefined && input.surface === undefined)
-            throw taskError("TASK_REVISION_INVALID", "Revision requires criteria, a surface, or both.");
+        // 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 = input.criteria === undefined ? structuredClone(previous.task.criteria) : structuredClone(input.criteria).map(criterion => {
@@ -278,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, ...(surface === undefined ? {} : { surface }) };
+            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.");
@@ -293,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());
@@ -680,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;
@@ -804,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

@@ -104,13 +104,22 @@ Every new task MUST record a surface audit of where else its change lands before
   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 30 file hits). Every hit outside the diff and the surface lists stops review.
+  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), `SCENARIO_MISSING`, `SURFACE_BUDGET_EXCEEDED` (120 s total, never
+  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
@@ -122,6 +131,95 @@ Every new task MUST record a surface audit of where else its change lands before
   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/zh-TW/guides/configuration.md

@@ -99,7 +99,13 @@ diagnostic。
 Capability check 與模型啟動進度都寫到 stderr，包括 `--json` 模式；stdout
 仍只有最終 JSON envelope，且不會串流 reviewer 原始輸出。SIGINT 或 SIGTERM
 會終止目前 reviewer 的完整 process tree、不進入 fallback，也不寫入
-attestation。整條 chain 逾時時回報 `timeout`，不會誤報 `missing-cli`。
+attestation。整條 chain 逾時時回報 `timeout`，不會誤報 `missing-cli`。每輪
+reviewer 預設最多 30 分鐘（可用 `reviewRoles[].timeoutMs` 覆寫）；在 stall 視窗內
+完全沒有輸出的 reviewer 仍會提早停止。
+
+Acceptance runner 的步驟若未設定自己的 `timeoutMs`，`setup` 為 10 分鐘，
+`build`、`testBuild` 與 runner 本身各 5 分鐘，git checkout 為 1 分鐘。逾時的步驟
+回報為 `UNKNOWN`，並指出是哪個步驟、上限多少，以及要調整哪個 `timeoutMs` 欄位。
 
 task ID 必須明確指定，且永遠使用該 task 的原始 criteria；不能用 session fallback
 或 criterion filter 取代需求。review 會在 adversarial session 前、以及寫入證據前
@@ -174,6 +180,13 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
   `.worktreeinclude`（gitignore 語法，例如 `.env` 或 `local.properties`）比對到
   的檔案；Git 已 checkout 的檔案一律不覆寫。只有主 checkout 已 trusted 且
   worktree 的 effective config 完全相同時才繼承 trust。
+- 在主 checkout 核准的 `agent-ops update` 會把新 config 複製到副本仍是先前已
+  信任版本的每個 session worktree，並以相同指令信任它；確認前 plan 會列出這些
+  session worktree。手動修改過的 worktree config 不會被覆寫，run 的 worktree 也
+  保留自己的授權。舊 config 下建立的 task 不會自動重新綁定：
+  review 會列出可重新綁定的
+  `agent-ops task revise --task <id> --expected-contract <hash> --reason <text>`
+  （criteria 與 surface 不變），之後再重新 verify。
 - `setup` 指令在新 worktree 中執行（預設 timeout 十分鐘），處理 Git 不會帶過去
   的東西，例如已安裝的相依套件。它屬於 trusted config 的一部分，不需另外核准；
   任一步驟失敗會移除該 worktree。

package/docs/zh-TW/guides/task-debug.md

@@ -49,6 +49,16 @@ Claude、Codex 與 agy 都使用可信 native session lifecycle，在 `UserPromp
 才封存 UNKNOWN environment receipt；這段經過時間仍會保留，不會退還不明時間。
 測試材料修改不算修復輪；兩輪停滯需要一次實質策略切換，再兩輪停滯停止。
 
+假設確認後以 `origin --payload-file <json>` 宣告 bug 來源：`{"kind": "escape-of",
+"commit": "<commit>", "label": "<最早關卡>"}`（可選 `"receipt"`），或 `{"kind":
+"pre-existing" | "external", "reason": "..."}`。它會修訂 contract，因此 review 前要重新
+verify 並重新記錄已確認的假設；沒有它時 finish 以 `ESCAPE_ORIGIN_MISSING` 拒絕。
+`escape-of` 會印出連結狀態與 `git blame` 提示，並寫入 `.agent-ops-escapes/<task-id>.json`，
+與修復一起 commit（見 `EVIDENCE-ESCAPE-001`）。surface 標記還需要一條在被逃逸 commit
+重放成立、受追蹤的 `.agent-ops-escapes/rules/<rule-id>.json` 規則；criteria/verify 標記需要
+`"promote": "<runnerId:checkId>"`；否則 finish 以 `ESCAPE_RULE_UNPROVEN` 拒絕（見
+`EVIDENCE-ESCAPE-002`）。
+
 checkpoint 保存 task/session/source/contract/config/cause；resume 只接受同一
 擁有者 worktree 的匹配 checkpoint，保留 dirty 內容及預算。失配需要人類確認。
 時間耗盡後明確「繼續」可透過 `extend --event-id latest` 讀取原生人類事件，

package/docs/zh-TW/spec/acceptance-and-evidence.md

@@ -73,13 +73,20 @@ English source version: 2026-10-06. Revalidate: when the English specification c
   不以 task 文字組 regex），由便宜的來源先跑：記錄的查詢；diff hunk header 的外層
   函式名；template literal 固定片段（至少 4 字元且以分隔符界定，例如 `order:`、
   `user_`、`menu.`）；新增與刪除行的複合識別字（snake_case、camelCase 或含數字，
-  因此一般文字單字不會成為查詢）與字串常值（至少 6 字元；命中超過 30 個檔案視為
-  太通用而略過）。diff 與 surface 清單之外的任何命中都會擋下 review。
+  因此一般文字單字不會成為查詢）與字串常值（至少 6 字元；命中超過 10 個檔案〈含
+  變更檔案〉視為太通用而略過）。diff 與 surface 清單之外的任何命中都會擋下 review。
+- 衍生查詢（diff 字詞、template 片段或 hunk header 函式名）的命中若只是巧合，可在
+  surface 選用的 `dismissed` 清單中以一筆 `{query, reason}` 排除（理由至多 256
+  字元，「out of scope」不是理由），不必逐檔排除。記錄的軸查詢與 escape rule 命中
+  不能排除；diff 以外命中少於 4 個檔案的查詢（最可能是兄弟頁面線索）也不能排除；
+  至多 128 筆。Reviewer 會看到每筆排除與其命中數，若它隱藏了先前
+  `SURFACE_UNCLASSIFIED` 阻擋所列的檔案則會標示出來。
   結果以 HEAD、base、diff、查詢集合與 config hash 快取。
 - Review 以 NOT_RUN 回報：`SURFACE_MISSING`（沒有或無法解析的 surface；非 DEBUG
   task 建立時也會拒絕）、`SURFACE_UNCLASSIFIED`、`SURFACE_QUERY_TOO_BROAD`（單一
   記錄查詢超過 200 個檔案）、`SURFACE_EXCLUSION_TOO_BROAD`（單一 glob 超過 10 個
-  檔案，或包含 diff 內的檔案）、`SCENARIO_MISSING`、`SURFACE_BUDGET_EXCEEDED`
+  檔案，或包含 diff 內的檔案）、`SURFACE_DISMISSAL_TOO_BROAD`（超過 128 筆排除）、
+  `SURFACE_DISMISSAL_INVALID`（記錄的查詢或稀有查詢）、`SCENARIO_MISSING`、`SURFACE_BUDGET_EXCEEDED`
   （總計 120 秒，絕不默默略過）或 `SURFACE_UNASSIGNED`（子 task covers 與父 task
   included 不一致；每次 review 都檢查，包含 advance 與 batch）。
 - 修訂 surface 等同修訂 contract：需要新的證據與兩次新的 review。在
@@ -90,6 +97,78 @@ English source version: 2026-10-06. Revalidate: when the English specification c
 - 一般 `worktree finish` 也會寫入與 advance 相同的本機 receipt，包含兩輪的 residual
   risks 與 non-blocking findings，在 git note 引用它並印出 residual risks。
 
+## EVIDENCE-ESCAPE-001
+
+每個 DEBUG 修復 MUST 在 review 前宣告 bug 的來源；宣告的逃逸 MUST 以機械方式連結、標記並記錄。
+
+- Trigger: DEBUG 假設已確認，或一般 task 修復一個通過了先前關卡的 bug。
+- Action: 以 `task debug --debug-action origin --payload-file <json>` 宣告 `origin`：`{"kind": "escape-of", "commit": "<commit>", "label": "<label>"}`（可選 `"receipt"`），或 `{"kind": "pre-existing" | "external", "reason": "..."}`。一般 task 可用 `task create|revise --escape-of <commit> --escape-label <label> [--escape-receipt <id>]` 選擇加入。把 `.agent-ops-escapes/<task-id>.json` 記錄與修復一起 commit。
+- Evidence: `origin` 綁進 task contract hash；本規則上線後建立的 DEBUG task 沒有它時，finish、`task complete` 與 completion gate 以 `ESCAPE_ORIGIN_MISSING` 拒絕；兩位 reviewer 在 `escape-label` 條件下收到連結狀態、標記、事實與 residual risks。
+- Positive: `假設已確認；origin escape-of 864dbbe2 label surface；重放把漏掉的頁面標為 surface-unseen；記錄與修復一起 commit。`
+- Negative: `DEBUG 修復沒有 origin 就 finish，或把 surface-excluded 的漏網改標成 review，理由是 reviewer「應該注意到」。`
+
+- 宣告必須在假設確認之後（否則 `ESCAPE_ORIGIN_EARLY`），並計入 DEBUG 預算。它是一次
+  contract revision：重新 verify、以新證據重新記錄已確認的假設，然後 review。重新宣告會
+  取代記錄。輸出會列出修復所改或刪行的 `git blame` 提示 commit；blame 只是提示，因為遺漏
+  型 bug 存在於沒人寫過的行。
+- finish receipt 留在本機 Git common directory。Schema 2 記錄 target..candidate 的每個
+  commit 與逐檔 diff fingerprint（去掉 blob id 與 hunk 位置，squash merge 後仍相同）；
+  schema 1 receipt 仍可載入，但只以 exact head 連結。
+- 連結狀態分開計數：`gated`（找到 receipt）、帶理由的 `unresolved`（Git note 或
+  `--escape-receipt` 指向本機沒有的 receipt 時為 `receipt-not-local`，另有
+  `ambiguous-receipt`、`link-unavailable`）與 `ungated`（沒有 receipt 也沒有 note）。
+  解析順序：`--escape-receipt` 覆寫、commit 位於某 receipt 記錄的範圍內（schema 1：exact
+  head）、逐檔 fingerprint 相符，最後才是 unresolved 或 ungated。
+- 標記：單一主要標記，取最早能抓到此逃逸的關卡 —— `requirement`、`surface`、
+  `scenario`、`criteria`、`verify`、`review` —— 或 `flagged`（residual risk 或 finding 已
+  提過）或 `out-of-model`。由 agent 提議；以 `git grep -F` 在被連結 receipt 的 candidate
+  上重放其記錄的 surface 查詢，把修復碰到的每個檔標為 included、excluded、hit、unseen 或
+  absent，`surface-excluded` 或 `surface-unseen` 會覆寫任何較晚的標記。兩位 reviewer 裁決。
+- ledger 受 git 追蹤且只含資料（commit、路徑、標記、理由、計數；絕不含檔案內容或對話紀錄），
+  每個 task 一個檔案，平行 worktree 不會衝突。關卡攔截（`SURFACE_*` 與 `SCENARIO_MISSING`
+  review 阻擋、review FAIL、verify 由紅轉綠）會附加僅含 code 與 task id 的參考性 local-log
+  `gate-catch` 事件；記錄失敗時 fail-open，origin 要求則 fail-closed。
+- 範圍 R1 只負責記錄。由逃逸學到的規則、重放證明、回測、`--escape-fix` 與
+  `agent-ops escapes` 報表屬於 R2（[EVIDENCE-ESCAPE-002](#evidence-escape-002)）。
+
+## EVIDENCE-ESCAPE-002
+
+surface 逃逸 MUST 在修復 finish 前變成已證明、受追蹤的規則；學到的規則 MUST 只能收緊 surface gate。
+
+- Trigger: 已宣告的 escape-of origin（EVIDENCE-ESCAPE-001），或以 `task create --escape-of <commit> --escape-label <label> --escape-fix <fix-commit>` 回填的過去逃逸。
+- Action: 標記為 `surface`、`surface-unseen` 或 `surface-excluded` 時，commit 一條規則 `.agent-ops-escapes/rules/<rule-id>.json`，形狀為 `{"id", "escape", "label", "trigger": {"paths", "tokens"}, "expand": {"paths", "queries"}, "noExclude"}`，並重新宣告 origin。`criteria` 或 `verify` 以 `--escape-promote <runnerId:checkId>`（DEBUG payload `"promote"`）指名修復 task 由紅轉綠的 check。其他標記記錄為 lesson。
+- Evidence: finish、`task complete` 與 completion gate 會重跑證明，並以 `ESCAPE_RULE_UNPROVEN`、`ESCAPE_RULE_TOO_BROAD` 或 `SURFACE_BUDGET_EXCEEDED` 拒絕；ledger 記錄保存證明用規則、其內容 hash 與回測的 fires、commits 與比率。
+- Positive: `逃逸 surface-unseen；規則 image-size-siblings 在被逃逸 commit 上觸發，其查詢在該 commit 命中兩個漏掉的兄弟頁面，且在最近 200 個 commit 中只觸發 2 次。`
+- Negative: `規則從未在被逃逸 commit 上觸發就 finish surface 逃逸，或新增可排除路徑的規則欄位。`
+
+- 規則只含資料且不需要 trust：trigger 與 expand 變成 argv `git grep -F` 查詢與路徑
+  glob，絕不經過 shell 或 regex。嚴格 schema 沒有任何能移除查詢、新增排除或放寬關卡的
+  欄位。無效規則以 review NOT_RUN `ESCAPE_RULE_INVALID` fail-closed；symlink 或非一般
+  檔案的規則目錄或檔案則為 `ESCAPE_RULE_UNSAFE`。
+- Surface gate：只有 task diff 符合 trigger 路徑 glob，或某個變更行包含 trigger token
+  時，規則才會觸發。已觸發規則的每個 expand 命中都必須位於 diff、included、UNKNOWN 或
+  excluded，否則為 `SURFACE_UNCLASSIFIED`；有 `noExclude` 時，被排除的命中為
+  `ESCAPE_RULE_NO_EXCLUDE`。每條規則的觸發與 included/excluded 計數寫入 local-log
+  `escape-rule` 事件（fail-open）。
+- 證明：規則必須指名被逃逸 commit、在該 commit 自身的 diff 上觸發，並在該 commit 重放時
+  命中當時已存在的每個漏掉路徑。有 `--escape-fix` 時漏掉路徑取自 fix commit，否則取自
+  task diff。`criteria`/`verify` 逃逸需要其 promoted check 是修復 task 某個已證明
+  behavioral 條件的 `redCheckIds` 項目（baseline 紅、candidate 綠）；輸出會印出新增
+  required verifier 的 config 提案，agent-ops 絕不寫入 `.agent-ops/config.json`。
+  `scenario`、`review`、`requirement`、`flagged` 與 `out-of-model` 記錄帶理由的未證明
+  lesson，不阻擋。絕不在被逃逸 commit 上執行 review 或測試。
+- 回測：以一次 argv `git log` 把 trigger 比對最近 200 個 first-parent commit 的 diff；
+  觸發比率超過 30% 為 `ESCAPE_RULE_TOO_BROAD`。回測有時間預算（超出為
+  `SURFACE_BUDGET_EXCEEDED`，絕不默默通過），並以 HEAD 與規則 hash 快取。編輯證明用規則
+  會讓 ledger 記錄過期，直到重新宣告。
+- `agent-ops escapes [--json]` 是唯讀、fail-open 的報表：來自 ledger 的各標記漏網數、
+  來自 local log 的 `gate-catch` code、origin 組成、帶 unresolved 理由的連結狀態組成，
+  以及每條規則的觸發/included/excluded 計數與時間窗，皆為附 n 的原始計數，n < 10 時標為
+  `insufficient-data`。至少觸發 10 次且從無 included 命中的規則列為退役候選；移除一律
+  經過審查的 commit，絕不自動。
+- R2 取代 phase-2 的 `surface.aliases` 設定（改為受追蹤規則）與 `surface stats`
+  （改為 `agent-ops escapes`）。
+
 ## EVIDENCE-AGGREGATE-001
 
 驗證器 MUST 在條件缺少、重複、未知或證據為空時回傳 FAIL。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",