@kylecheng3146/agent-ops 0.9.0 → 0.10.0

package/dist/packages/cli/src/args.js

@@ -13,7 +13,8 @@ export const COMMAND_NAMES = [
     "allow-stop",
     "worktree",
     "run",
-    "office"
+    "office",
+    "escapes"
 ];
 const COMMAND_SET = new Set(COMMAND_NAMES);
 const SCOPES = new Set(["project", "user"]);
@@ -91,6 +92,11 @@ export function parseArgs(argv) {
     const criterionFiles = [];
     let criteriaFile;
     let surfaceFile;
+    let escapeOf;
+    let escapeLabel;
+    let escapeReceipt;
+    let escapeFix;
+    let escapePromote;
     let planFile;
     let expectedContract;
     let expectedTreeContract;
@@ -231,7 +237,7 @@ export function parseArgs(argv) {
                 if (debugAction !== undefined)
                     duplicate(token);
                 const value = readOptionValue(argv, index++, token);
-                if (!["status", "hypothesis", "strategy", "investigate", "checkpoint", "resume", "extend"].includes(value))
+                if (!["status", "hypothesis", "strategy", "investigate", "checkpoint", "resume", "extend", "origin"].includes(value))
                     invalidValue(token, value);
                 debugAction = value;
                 break;
@@ -270,6 +276,31 @@ export function parseArgs(argv) {
                     duplicate(token);
                 surfaceFile = readOptionValue(argv, index++, token);
                 break;
+            case "--escape-of":
+                if (escapeOf !== undefined)
+                    duplicate(token);
+                escapeOf = readOptionValue(argv, index++, token);
+                break;
+            case "--escape-label":
+                if (escapeLabel !== undefined)
+                    duplicate(token);
+                escapeLabel = readOptionValue(argv, index++, token);
+                break;
+            case "--escape-receipt":
+                if (escapeReceipt !== undefined)
+                    duplicate(token);
+                escapeReceipt = readOptionValue(argv, index++, token);
+                break;
+            case "--escape-fix":
+                if (escapeFix !== undefined)
+                    duplicate(token);
+                escapeFix = readOptionValue(argv, index++, token);
+                break;
+            case "--escape-promote":
+                if (escapePromote !== undefined)
+                    duplicate(token);
+                escapePromote = readOptionValue(argv, index++, token);
+                break;
             case "--plan-file":
                 if (planFile !== undefined)
                     duplicate(token);
@@ -687,7 +718,7 @@ export function parseArgs(argv) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Debug operation options apply only to task debug.");
     if (command === "task" && action === "debug" && (taskId === undefined || debugAction === undefined || title !== undefined || intent !== undefined ||
         parentTaskId !== undefined || criteria.length > 0 || evidence.length > 0 ||
-        ((debugAction === "hypothesis" || debugAction === "strategy") !== (payloadFile !== undefined)) ||
+        ((debugAction === "hypothesis" || debugAction === "strategy" || debugAction === "origin") !== (payloadFile !== undefined)) ||
         ((debugAction === "investigate") !== (commandId !== undefined)) || ((debugAction === "extend") !== (eventId !== undefined))))
         throw new CliArgumentError("CLI_MISSING_VALUE", "Task debug requires --task, --debug-action and the operation's exact payload/command/event options.");
     if ((criterionFiles.length > 0 && !(command === "task" && (action === "create" || action === "pin-finding"))) ||
@@ -699,8 +730,16 @@ export function parseArgs(argv) {
         (reason !== undefined && !revisionAction) ||
         (baseline !== undefined && !(command === "task" && (action === "create" || action === "revise"))))
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Acceptance options are not supported by this command.");
+    if ((escapeOf !== undefined || escapeLabel !== undefined || escapeReceipt !== undefined || escapeFix !== undefined || escapePromote !== undefined) &&
+        !(command === "task" && (action === "create" || action === "revise")))
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Escape options apply only to task create and revise.");
+    if ((escapeOf === undefined) !== (escapeLabel === undefined) ||
+        ((escapeReceipt !== undefined || escapeFix !== undefined || escapePromote !== undefined) && escapeOf === undefined))
+        throw new CliArgumentError("CLI_MISSING_VALUE", "--escape-of needs --escape-label; --escape-label, --escape-receipt, --escape-fix and --escape-promote need --escape-of.");
+    if (command === "escapes" && argv.some(token => token !== "escapes" && token !== "--json"))
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "escapes accepts only --json; it is a read-only report.");
     if (revisionAction && (taskId === undefined || evidence.length > 0 || title !== undefined || intent !== undefined || parentTaskId !== undefined || sessionId !== undefined || criteria.length > 0 || base !== undefined ||
-        (action === "revise" && (expectedContract === undefined || (criteriaFile === undefined && surfaceFile === undefined) || reason === undefined)) ||
+        (action === "revise" && (expectedContract === undefined || (criteriaFile === undefined && surfaceFile === undefined && escapeOf === undefined) || reason === undefined)) ||
         (action === "replan" && (expectedTreeContract === undefined || planFile === undefined || reason === undefined)) ||
         (action === "pin-finding" && (expectedContract === undefined || findingReference === undefined || criterionFiles.length !== 1))))
         throw new CliArgumentError("CLI_MISSING_VALUE", "Acceptance revision requires task, expected contract, payload and reason.");
@@ -875,6 +914,11 @@ export function parseArgs(argv) {
         ...(criterionFiles.length === 0 ? {} : { criterionFiles }),
         ...(criteriaFile === undefined ? {} : { criteriaFile }),
         ...(surfaceFile === undefined ? {} : { surfaceFile }),
+        ...(escapeOf === undefined ? {} : { escapeOf }),
+        ...(escapeLabel === undefined ? {} : { escapeLabel }),
+        ...(escapeReceipt === undefined ? {} : { escapeReceipt }),
+        ...(escapeFix === undefined ? {} : { escapeFix }),
+        ...(escapePromote === undefined ? {} : { escapePromote }),
         ...(planFile === undefined ? {} : { planFile }),
         ...(expectedContract === undefined ? {} : { expectedContract }),
         ...(expectedTreeContract === undefined ? {} : { expectedTreeContract }),

package/dist/packages/cli/src/bin.js

@@ -52,14 +52,15 @@ import { runTrustCommand } from "./commands/trust.js";
 import { runVerifyCommand } from "./commands/verify.js";
 import { runAdvanceCommand } from "./commands/advance.js";
 import { runReviewShowCommand } from "./commands/review-show.js";
+import { runEscapesCommand } from "./commands/escapes.js";
 import { runAllowStopCommand } from "./commands/allow-stop.js";
 import { CompletionGateService } from "../../../runtime/src/hooks/completion-gate.js";
-import { formatUpdatePlan, runUpdateCommand } from "./commands/update.js";
+import { formatUpdatePlan, runUpdateCommand, worktreeSyncLine } from "./commands/update.js";
 import { errorEnvelope } from "./output.js";
 import { runAgyHeadless } from "./agy-headless.js";
 import { runWorktreeCommand } from "./commands/parallel.js";
 import { ensureSessionWorktree, readWorktreeRecord, resolveCheckouts } from "../../../runtime/src/parallel/service.js";
-import { listWorktrees, branchLockDoctorResult, worktreeDoctorResult } from "../../../runtime/src/parallel/manage.js";
+import { listWorktrees, branchLockDoctorResult, sessionWorktreeNames, syncSessionWorktrees, worktreeDoctorResult } from "../../../runtime/src/parallel/manage.js";
 import { detectGhostFiles, ghostFilesDoctorResult } from "../../../runtime/src/install/doctor.js";
 /** The repository's common Git directory, where display-only office records live; undefined when git cannot say. */
 async function officeCommonDir(dir) {
@@ -264,6 +265,8 @@ else {
                     const context = await productionRunContext(root);
                     return await runRunCommand({ args, ...context, root: context.mainRoot, office: async () => await ensureBackgroundOffice(root, undefined, openOfficeBrowser) });
                 }
+                if (args.command === "escapes")
+                    return await runEscapesCommand({ root });
                 if (args.command === "office") {
                     return await runOfficeCommand({ ensure: async () => await ensureBackgroundOffice(root, undefined, openOfficeBrowser),
                         foreground: async (onUrl) => await serveOffice(root, onUrl), writeStdout: (text) => { process.stdout.write(text); } });
@@ -422,7 +425,11 @@ else {
                             : { hookTargets: updateArgs.hookTargets }),
                         trustStore: store,
                         calculateTrustBinding: async (config) => await plannedTrustBinding(root, config),
-                        confirm: async (plan, trust) => await confirmPlan(formatUpdatePlan(plan, trust)),
+                        confirm: async (plan, trust, worktrees) => await confirmPlan(formatUpdatePlan(plan, trust) + worktreeSyncLine(worktrees)),
+                        sessionWorktrees: {
+                            list: async () => await sessionWorktreeNames(worktreeDependencies(), root),
+                            sync: async () => await syncSessionWorktrees(worktreeDependencies(), root)
+                        },
                         promptOffice: async (message, enabled) => await selectYesNo(message, { input: process.stdin, output: process.stdout }, enabled),
                         promptAutoRun: async (message, enabled) => await selectYesNo(message, { input: process.stdin, output: process.stdout }, enabled),
                         promptWorktree: async (message) => await selectYesNo(message, { input: process.stdin, output: process.stdout }, true),

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

@@ -31,6 +31,7 @@ Commands:
   review     Run an independent review or show recorded reports
   run        Start or control a supervised Claude/Codex native goal
   office     Open the local pixel office (Preview; opt-in)
+  escapes    Report escaped bugs, gate catches and learned rules (read-only)
   batch      Verify and review a parent task's subtasks together
   allow-stop Grant one fingerprint-bound completion-gate Stop permit (requires --session)
   agy-run    Run headless agy with a process-exit completion recheck
@@ -75,6 +76,14 @@ Options:
  * rejected.
  */
 export const COMMAND_HELP_TEXT = {
+    escapes: `Usage: agent-ops escapes [--json]
+
+Read-only Escape Loop report: misses per gate from the tracked
+.agent-ops-escapes ledger, gate catches from this machine's local log, origin
+and link-state mix, and per-rule fire/included/excluded counts with retirement
+candidates. Counts are raw with n; fewer than 10 observations are marked
+insufficient-data. It never writes files and fails open.
+`,
     office: `Usage: agent-ops office [--json]
 
 Office (Preview) is opt-in: select it during init/update or run
@@ -179,8 +188,8 @@ Options:
   --title <text>                        create
   --goal <text>                         create: immutable original issue/goal
   --debug                               create: task-level investigation tag
-  --debug-action <status|hypothesis|strategy|investigate|checkpoint|resume|extend>
-  --payload-file <path>                 debug hypothesis/strategy: bounded JSON
+  --debug-action <status|hypothesis|strategy|investigate|checkpoint|resume|extend|origin>
+  --payload-file <path>                 debug hypothesis/strategy/origin: bounded JSON
   --command-id <id>                     debug investigate: trusted configured command
   --event-id <native-event-id|latest>    debug extend: authentic human continue event
   --intent <text>                       create: intended behavior and constraints before editing
@@ -189,6 +198,11 @@ Options:
   --criteria-file <path>                revise: replacement criterion array
   --surface-file <path>                 create (required unless --debug), revise: EVIDENCE-SURFACE-001
                                         audit JSON, or {"covers":[surface-id]} under a surfaced parent
+  --escape-of <commit>                  create, revise: the commit this bug escaped from (Escape Loop)
+  --escape-label <label>                with --escape-of: requirement|surface|scenario|criteria|verify|review|flagged|out-of-model
+  --escape-receipt <id>                 with --escape-of: link this local finish receipt instead of resolving one
+  --escape-fix <commit>                 with --escape-of: backfill; missed paths come from this past fix commit
+  --escape-promote <runner:check>       with --escape-of: the red-to-green check proving a criteria/verify escape
   --plan-file <path>                    replan: split-task array with requirement mappings
   --expected-contract <hash>            revise, pin-finding: current task contract from status
   --expected-tree-contract <hash>       replan: current tree contract from status

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

@@ -0,0 +1,109 @@
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { LEDGER_DIRECTORY } from "../../../../runtime/src/escape/link.js";
+import { loadRules } from "../../../../runtime/src/escape/rules.js";
+import { readLocalLog } from "../../../../runtime/src/logging/local-log.js";
+import { okEnvelope } from "../output.js";
+/** Below this many observations a count is shown but not trusted. */
+export const MIN_SAMPLE = 10;
+const status = (n) => n < MIN_SAMPLE ? "insufficient-data" : "ok";
+function section(rows) {
+    const counts = {};
+    for (const row of rows)
+        counts[row.key] = (counts[row.key] ?? 0) + 1;
+    const times = rows.flatMap(row => row.at === undefined ? [] : [row.at]).sort();
+    return { n: rows.length, status: status(rows.length), window: { first: times[0] ?? null, last: times.at(-1) ?? null }, counts };
+}
+/** Tracked ledger records; a symlinked or unreadable entry is skipped with a warning, never followed. */
+async function ledger(root, warnings) {
+    const directory = join(root, LEDGER_DIRECTORY);
+    try {
+        if (!(await lstat(directory)).isDirectory()) {
+            warnings.push(`${LEDGER_DIRECTORY} is not a directory.`);
+            return [];
+        }
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const name of (await readdir(directory)).filter(n => n.endsWith(".json")).sort()) {
+        try {
+            if (!(await lstat(join(directory, name))).isFile())
+                throw new Error("not a regular file");
+            const value = JSON.parse(await readFile(join(directory, name), "utf8"));
+            if (typeof value.label === "string" && typeof value.link?.state === "string")
+                records.push(value);
+        }
+        catch {
+            warnings.push(`Skipped unreadable ledger record ${name}.`);
+        }
+    }
+    return records;
+}
+/** Advisory, read-only and fail-open: every source that cannot be read becomes a warning. */
+export async function buildEscapesReport(root, home) {
+    const warnings = [];
+    const records = await ledger(root, warnings).catch(() => { warnings.push("Ledger unreadable."); return []; });
+    const events = await readLocalLog(home);
+    let origins = [];
+    try {
+        const state = JSON.parse(await readFile(join(root, ".agent-ops", "tasks", "state.json"), "utf8"));
+        origins = (state.tasks ?? []).filter(r => r.task?.origin !== undefined || r.task?.debug !== undefined)
+            .map(r => ({ ...(r.createdAt === undefined ? {} : { at: r.createdAt }), key: r.task?.origin?.kind ?? "undeclared" }));
+    }
+    catch {
+        warnings.push("Task state unreadable; origin mix is empty.");
+    }
+    let rules = [];
+    try {
+        rules = await loadRules(root);
+    }
+    catch (error) {
+        warnings.push(`Rules unreadable: ${error instanceof Error ? error.message : "unknown error"}`);
+    }
+    const ruleEvents = events.flatMap(e => e.event.type === "escape-rule" ? [e.event] : []);
+    const ruleRows = rules.map(({ rule }) => {
+        const fired = ruleEvents.filter(e => e.ruleId === rule.id);
+        return { id: rule.id, label: rule.label, noExclude: rule.noExclude, fires: fired.length,
+            included: fired.reduce((n, e) => n + e.included, 0), excluded: fired.reduce((n, e) => n + e.excluded, 0), status: status(fired.length) };
+    });
+    const links = section(records.map(r => ({ at: r.declaredAt, key: r.link.state })));
+    const reasons = {};
+    for (const r of records)
+        if (r.link.state === "unresolved")
+            reasons[r.link.reason] = (reasons[r.link.reason] ?? 0) + 1;
+    return {
+        misses: section(records.map(r => ({ at: r.declaredAt, key: r.label }))),
+        catches: section(events.flatMap(e => e.event.type === "gate-catch" ? [{ at: e.timestamp, key: e.event.code }] : [])),
+        origins: section(origins),
+        links: { ...links, reasons },
+        rules: ruleRows,
+        // Retirement is never automatic: only rules with enough fires that never surfaced an included place are listed.
+        retirementCandidates: ruleRows.filter(r => r.fires >= MIN_SAMPLE && r.included === 0)
+            .map(r => ({ id: r.id, reason: `fired ${r.fires} times; every hit was excluded (${r.excluded}) or none was included.` })),
+        warnings
+    };
+}
+function render(report) {
+    const line = (name, s) => `${name}: n=${s.n}${s.status === "ok" ? "" : " (insufficient-data)"}` +
+        `${s.window.first === null ? "" : ` ${s.window.first} .. ${s.window.last}`}` +
+        `${Object.keys(s.counts).length === 0 ? "" : ` - ${Object.entries(s.counts).sort().map(([k, v]) => `${k} ${v}`).join(", ")}`}`;
+    return [
+        "Escape Loop report (advisory; raw counts; catches and rule fires come from this machine's local log)",
+        line("Misses by gate (ledger)", report.misses),
+        line("Catches by code (local log)", report.catches),
+        line("Origin mix (tasks)", report.origins),
+        line("Link states (ledger)", report.links) +
+            (Object.keys(report.links.reasons).length === 0 ? "" : `; unresolved reasons: ${Object.entries(report.links.reasons).sort().map(([k, v]) => `${k} ${v}`).join(", ")}`),
+        `Rules: ${report.rules.length}`,
+        ...report.rules.map(r => `- ${r.id} (${r.label}${r.noExclude ? ", noExclude" : ""}): fires ${r.fires}, included ${r.included}, excluded ${r.excluded}` +
+            `${r.status === "ok" ? "" : " (insufficient-data)"}`),
+        `Retirement candidates: ${report.retirementCandidates.length === 0 ? "none" : report.retirementCandidates.map(c => `${c.id} (${c.reason})`).join("; ")}`,
+        ...report.warnings.map(w => `Warning: ${w}`)
+    ].join("\n") + "\n";
+}
+export async function runEscapesCommand(options) {
+    const report = await buildEscapesReport(options.root, options.home);
+    return okEnvelope("ESCAPES_REPORT", { ...report, text: render(report) });
+}

package/dist/packages/cli/src/commands/review-show.js

@@ -58,7 +58,7 @@ export async function readFinishedReview(deps, mainRoot, commonDir, path) {
     catch {
         return invalid("Final review receipt is malformed.");
     }
-    if (receipt.schemaVersion !== 1 || !/^[a-f0-9]{40,64}$/u.test(receipt.candidateHead) ||
+    if ((receipt.schemaVersion !== 1 && receipt.schemaVersion !== 2) || !/^[a-f0-9]{40,64}$/u.test(receipt.candidateHead) ||
         !Array.isArray(receipt.tasks) || receipt.tasks.length === 0 ||
         !["tree", "per-task-fallback"].includes(receipt.reviewMode) ||
         typeof receipt.reviews !== "object" || receipt.reviews === null) {

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

@@ -17,7 +17,9 @@ import { calculateConfigHash, isPassingVerificationEvidence } from "../../../../
 import { validateEvidence } from "../../../../runtime/src/schema/validate.js";
 import { loadDebugProof, debugProofDigest } from "../../../../runtime/src/task/debug-state.js";
 import { logSurfaceResidualRisks, runSurfaceGate } from "../../../../runtime/src/surface/discovery.js";
-import { isCovers } from "../../../../runtime/src/surface/schema.js";
+import { escapeReviewData } from "../../../../runtime/src/escape/link.js";
+import { logGateCatch } from "../../../../runtime/src/logging/local-log.js";
+import { isCovers, surfaceDelta } from "../../../../runtime/src/surface/schema.js";
 import { okEnvelope } from "../output.js";
 /**
  * Review runs against one target. Argument parsing already rejects a
@@ -318,8 +320,45 @@ const SURFACE_REASONS = {
     SURFACE_EXCLUSION_TOO_BROAD: "surface-exclusion-too-broad",
     SCENARIO_MISSING: "scenario-missing",
     SURFACE_BUDGET_EXCEEDED: "surface-budget-exceeded",
-    SURFACE_UNASSIGNED: "surface-unassigned"
+    SURFACE_UNASSIGNED: "surface-unassigned",
+    SURFACE_DISMISSAL_TOO_BROAD: "surface-dismissal-too-broad",
+    SURFACE_DISMISSAL_INVALID: "surface-dismissal-invalid",
+    ESCAPE_RULE_INVALID: "escape-rule-invalid",
+    ESCAPE_RULE_UNSAFE: "escape-rule-unsafe",
+    ESCAPE_RULE_NO_EXCLUDE: "escape-rule-no-exclude"
 };
+/** Escape Loop: a declared escape-of origin gives a wrong label a criterion a blocking finding can name. */
+export const ESCAPE_LABEL = {
+    id: "escape-label",
+    description: "Each declared escape's primary label names the earliest gate that could have caught it (requirement, surface, " +
+        "scenario, criteria, verify, review; flagged if a residual risk or finding already said it; out-of-model if no gate could), " +
+        "is consistent with the mechanical surface facts, and its tracked .agent-ops-escapes record is current."
+};
+/** Escape Loop packet rows for every task in scope that declares an origin; linking stays advisory. */
+async function reviewEscapes(options, context, scope) {
+    if (options.root === undefined || options.gitRunner === undefined)
+        return [];
+    const rows = [];
+    for (const record of context.records) {
+        const origin = record.task.origin;
+        if (origin === undefined)
+            continue;
+        const base = record.debug?.baselineCommit ?? record.createdSourceCommit ?? (scope?.mode === "base" ? scope.resolvedBase : undefined);
+        try {
+            if (base === undefined)
+                throw new Error("no base");
+            rows.push(await escapeReviewData({ root: options.root, git: options.gitRunner, taskId: record.task.id, origin, base }));
+        }
+        catch {
+            rows.push({ taskId: record.task.id, origin, link: { state: "unresolved", reason: "link-unavailable" } });
+        }
+    }
+    return rows;
+}
+async function logCatch(options, code, taskId) {
+    if (taskId !== undefined && options.config?.profiles.includes("advisory") === true)
+        await logGateCatch(code, taskId);
+}
 /** Review-only: gives an omission a criterion that a blocking finding can name. */
 export const SURFACE_COVERAGE = {
     id: "surface-coverage",
@@ -359,8 +398,11 @@ async function reviewSurface(options, context, scope) {
         return { gate };
     return { gate, packet: {
             audit: holder.task.surface,
-            history: (holder.revisions ?? []).slice(-10).map(revision => ({ at: revision.at, reason: revision.reason, surface: revision.previousTask.surface ?? null })),
-            discovery: { cached: gate.discovery.cached, sources: gate.discovery.sources, skipped: gate.discovery.skipped },
+            // Deltas, not whole previous audits: a large audit revised a few times must still fit the review packet.
+            history: (holder.revisions ?? []).map((revision, i, all) => ({ at: revision.at, reason: revision.reason,
+                change: surfaceDelta(revision.previousTask.surface, (all[i + 1]?.previousTask ?? holder.task).surface) })).slice(-10),
+            discovery: { cached: gate.discovery.cached, sources: gate.discovery.sources, skipped: gate.discovery.skipped,
+                dismissed: gate.discovery.dismissed },
             postBlockExclusions: gate.discovery.postBlockExclusions
         } };
 }
@@ -658,16 +700,19 @@ export async function runReviewCommand(options) {
                 });
             }
             if (context.policyConfigHash !== options.policyConfigHash) {
-                return notRunEnvelope({
-                    ...resultBase,
-                    status: "NOT_RUN", reason: "reviewer-policy-changed",
-                    scope
-                });
+                const result = { ...resultBase, status: "NOT_RUN", reason: "reviewer-policy-changed", scope };
+                const own = context.records.find(r => r.task.id === context.taskId).task;
+                const message = "Independent review was not run.";
+                return { code: "REVIEW_NOT_RUN", status: "error", errors: [{ code: "REVIEW_NOT_RUN", message }], data: { message, result,
+                        text: renderReviewResult(result) +
+                            `The configuration changed after task ${context.taskId} was created. Rebind it, then verify again:\n` +
+                            `  agent-ops task revise --task ${context.taskId} --expected-contract ${taskContractHash(own)} --reason "Rebind to the current configuration"\n` } };
             }
         }
         if (context !== undefined && options.tasks !== undefined) {
             const surface = await reviewSurface(options, context, scope);
             if (surface.gate.status === "NOT_RUN") {
+                await logCatch(options, surface.gate.code, context.taskId);
                 return surfaceNotRunEnvelope({
                     ...resultBase,
                     status: "NOT_RUN",
@@ -733,9 +778,11 @@ export async function runReviewCommand(options) {
             candidateCommit: await resolveGitCommit(options.gitRunner, "HEAD"), coverageDigest: coverageDigest(rows)
         };
     }
+    const escapes = context === undefined ? [] : await reviewEscapes(options, context, scope);
     const criteria = [
         ...(context?.criteria ?? GENERIC_CRITERIA),
-        ...(surfacePacket === undefined || context?.criteria.some(c => c.id === SURFACE_COVERAGE.id) === true ? [] : [SURFACE_COVERAGE])
+        ...(surfacePacket === undefined || context?.criteria.some(c => c.id === SURFACE_COVERAGE.id) === true ? [] : [SURFACE_COVERAGE]),
+        ...(!context?.records.some(r => r.task.origin?.kind === "escape-of") || context.criteria.some(c => c.id === ESCAPE_LABEL.id) ? [] : [ESCAPE_LABEL])
     ];
     // Tree attestations bind the exact criterion list the reviewer answered.
     if (context !== undefined)
@@ -784,6 +831,7 @@ export async function runReviewCommand(options) {
         }
         packet = buildReviewPacket({
             ...(surfacePacket === undefined ? {} : { surface: surfacePacket }),
+            ...(escapes.length === 0 ? {} : { escape: escapes }),
             ...(contractManifest === undefined ? {} : { contractManifest, contractArtifacts }),
             request: context?.title ?? GENERIC_REQUEST,
             criteria,
@@ -922,6 +970,8 @@ export async function runReviewCommand(options) {
     if (finalResult.status === "PASS") {
         return okEnvelope("REVIEW_RESULT", data);
     }
+    if (finalResult.status === "FAIL")
+        await logCatch(options, "REVIEW_FAIL", context?.taskId);
     const code = finalResult.status === "FAIL" ? "REVIEW_FAILED" : "REVIEW_NOT_RUN";
     return {
         code,

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

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

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

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

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

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

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

@@ -171,7 +171,7 @@ export async function routeDebugPrompt(root, input, host = "claude") {
     }
     else
         clockNote = " Native foreground timing is unsupported on this host; controlled operations remain evidence-timed and do not claim a complete active-time budget.";
-    return `DEBUG issue ${created.task.id} created in ${path}. Preserve the original goal. Investigate, record falsifiable hypotheses, revise provisional criteria to relevant behavioral regression, add the surface audit (task revise --surface-file) before the first repair, repair, verify, obtain two fresh independent reviews, then finish. A clean HEAD baseline is fixed automatically; do not ask permission for it or offer diagnosis-only as a fallback. Failure to reproduce alone is not a stop condition: continue discriminating checks within the budget. Defaults: 60 active minutes / 5 material repair candidates. No user-authored debug plan is required.${clockNote}`;
+    return `DEBUG issue ${created.task.id} created in ${path}. Preserve the original goal. Investigate, record falsifiable hypotheses, revise provisional criteria to relevant behavioral regression, add the surface audit (task revise --surface-file) before the first repair, repair, declare the origin (task debug --debug-action origin) once a hypothesis is confirmed, verify, obtain two fresh independent reviews, then finish. A clean HEAD baseline is fixed automatically; do not ask permission for it or offer diagnosis-only as a fallback. Failure to reproduce alone is not a stop condition: continue discriminating checks within the budget. Defaults: 60 active minutes / 5 material repair candidates. No user-authored debug plan is required.${clockNote}`;
 }
 export async function interruptDebugSession(root, sessionId, nativeInput) {
     const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(sessionId)));