@kylecheng3146/agent-ops 0.8.6 → 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"]);
@@ -90,6 +91,12 @@ export function parseArgs(argv) {
     const criteria = [];
     const criterionFiles = [];
     let criteriaFile;
+    let surfaceFile;
+    let escapeOf;
+    let escapeLabel;
+    let escapeReceipt;
+    let escapeFix;
+    let escapePromote;
     let planFile;
     let expectedContract;
     let expectedTreeContract;
@@ -230,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;
@@ -264,6 +271,36 @@ export function parseArgs(argv) {
                     duplicate(token);
                 criteriaFile = readOptionValue(argv, index++, token);
                 break;
+            case "--surface-file":
+                if (surfaceFile !== undefined)
+                    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);
@@ -681,19 +718,28 @@ 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"))) ||
         (criteriaFile !== undefined && !(command === "task" && action === "revise")) ||
+        (surfaceFile !== undefined && !(command === "task" && (action === "create" || action === "revise"))) ||
         (planFile !== undefined && !(command === "task" && action === "replan")) ||
         (expectedContract !== undefined && !(command === "task" && (action === "revise" || action === "pin-finding"))) ||
         (expectedTreeContract !== undefined && !(command === "task" && action === "replan")) ||
         (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 || 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.");
@@ -867,6 +913,12 @@ export function parseArgs(argv) {
         ...(criteria.length === 0 ? {} : { criteria }),
         ...(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,14 +188,21 @@ 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
   --criterion <json>                    create, repeatable, two to five total
   --criterion-file <path>               create: one criterion object, repeatable; pin-finding: exactly one
   --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/parallel.js

@@ -1,3 +1,5 @@
+import { redactSecrets } from "../../../../runtime/src/security/redact.js";
+import { safeTaskText } from "../../../../runtime/src/task/render.js";
 import { okEnvelope } from "../output.js";
 import { resolveCommandSessionId, sessionIdFromEnvironment } from "../../../../runtime/src/hooks/codex-loop.js";
 import { addWorktree } from "../../../../runtime/src/parallel/service.js";
@@ -42,6 +44,9 @@ function finishText(result) {
         `Merged ${record.branch} into ${record.targetBranch} at ${result.mergedHead}${result.rebased ? " after a clean rebase and re-verification" : ""}.`,
         `Completed and recorded in git notes (refs/notes/agent-ops): ${result.taskIds.join(", ")}.`,
         `Removed ${record.path}.`,
+        ...(result.receipt === undefined ? [] : [`Receipt: ${result.receipt}`]),
+        ...(result.residualRisks === undefined || result.residualRisks.length === 0 ? [] :
+            ["Residual risks from review:", ...result.residualRisks.map((risk) => `- ${safeTaskText(redactSecrets(risk))}`)]),
         ...result.warnings.map((warning) => `Warning: ${warning}`)
     ].join("\n");
 }

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

@@ -16,6 +16,10 @@ import { calculateSourceFingerprint } from "../../../../runtime/src/verify/sourc
 import { calculateConfigHash, isPassingVerificationEvidence } from "../../../../runtime/src/verify/evidence.js";
 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 { 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
@@ -309,6 +313,113 @@ function scopeReason(error) {
         REVIEW_INVALID_BASE: "invalid-base"
     }[error.code];
 }
+const SURFACE_REASONS = {
+    SURFACE_MISSING: "surface-missing",
+    SURFACE_UNCLASSIFIED: "surface-unclassified",
+    SURFACE_QUERY_TOO_BROAD: "surface-query-too-broad",
+    SURFACE_EXCLUSION_TOO_BROAD: "surface-exclusion-too-broad",
+    SCENARIO_MISSING: "scenario-missing",
+    SURFACE_BUDGET_EXCEEDED: "surface-budget-exceeded",
+    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",
+    description: "Every place and scenario the change affects is listed in the surface audit and its listed behavior is " +
+        "implemented: recorded queries replayed, valueChanges consumers (both hops) read, the five scenario dimensions " +
+        "checked, and every exclusion shows why the surface is unaffected (post-block exclusions especially)."
+};
+/**
+ * EVIDENCE-SURFACE-001: the nearest surfaced task on the way to the tree root
+ * holds the audit; its direct children must cover its included surfaces.
+ */
+async function reviewSurface(options, context, scope) {
+    // Grandfathered standalone tasks never touch the discovery path.
+    if (context.records.every(r => r.task.surface === undefined && r.task.surfaceRequired !== true && r.task.parentTaskId === undefined))
+        return { gate: { status: "PASS", discovery: null } };
+    const all = await options.tasks.list();
+    const own = context.records.find(r => r.task.id === context.taskId);
+    let holder;
+    for (let record = own; record !== undefined && holder === undefined; record = all.find(r => r.task.id === record.task.parentTaskId)) {
+        if (record.task.surface !== undefined && !isCovers(record.task.surface))
+            holder = record;
+        if (record.task.parentTaskId === undefined)
+            break;
+    }
+    const children = holder === undefined ? [] : all
+        .filter(r => r.task.parentTaskId === holder.task.id && r.status !== "archived" && r.supersededBy === undefined)
+        .map(r => ({ taskId: r.task.id, covers: r.task.surface !== undefined && isCovers(r.task.surface) ? r.task.surface.covers : [] }));
+    const gate = await runSurfaceGate({
+        root: options.root, taskId: context.taskId, surface: holder?.task.surface,
+        // Grandfathered roots keep reviewing even when a newer subtask sits under them.
+        required: own.task.surfaceRequired === true, children,
+        metrics: options.config?.profiles.includes("advisory") === true,
+        ...(scope.mode === "base" ? { base: scope.resolvedBase } : {}), changedFiles: scope.changedFiles,
+        configHash: options.policyConfigHash ?? (options.config === undefined ? "" : calculateConfigHash(options.config))
+    });
+    if (gate.status === "NOT_RUN" || holder === undefined || gate.discovery === null)
+        return { gate };
+    return { gate, packet: {
+            audit: holder.task.surface,
+            // 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
+        } };
+}
+function surfaceNotRunEnvelope(result) {
+    const surface = result.surface;
+    const message = `${surface.code}: ${surface.message}`;
+    return {
+        code: surface.code,
+        status: "error",
+        data: {
+            message,
+            result,
+            text: [renderReviewResult(result), message, ...surface.details.slice(0, 50).map(detail => `- ${redactSecrets(JSON.stringify(detail))}`)].join("\n")
+        },
+        errors: [{ code: surface.code, message }]
+    };
+}
 function notRunEnvelope(result) {
     const message = "Independent review was not run.";
     return {
@@ -549,6 +660,7 @@ export async function runReviewCommand(options) {
     let scope;
     let sourceFingerprint;
     let verification;
+    let surfacePacket;
     if (options.root !== undefined && options.gitRunner !== undefined) {
         try {
             scope = await resolveReviewScope({
@@ -588,12 +700,29 @@ export async function runReviewCommand(options) {
                 });
             }
             if (context.policyConfigHash !== options.policyConfigHash) {
-                return notRunEnvelope({
+                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", reason: "reviewer-policy-changed",
-                    scope
+                    status: "NOT_RUN",
+                    reason: SURFACE_REASONS[surface.gate.code],
+                    taskId: context.taskId,
+                    scope,
+                    surface: { code: surface.gate.code, message: surface.gate.message, details: surface.gate.details }
                 });
             }
+            surfacePacket = surface.packet;
         }
         if (context !== undefined) {
             const preflight = await preflightReview(options, context, sourceFingerprint);
@@ -649,9 +778,15 @@ 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)
+        ...(context?.criteria ?? GENERIC_CRITERIA),
+        ...(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)
+        context.criteria = criteria;
     if (context?.treeTasks !== undefined && criteria.length > 128) {
         return notRunEnvelope({ ...resultBase, status: "NOT_RUN", reason: "scope-too-large" });
     }
@@ -695,6 +830,8 @@ export async function runReviewCommand(options) {
             await writePrivateFile(options.root + "/" + path, content, options.root);
         }
         packet = buildReviewPacket({
+            ...(surfacePacket === undefined ? {} : { surface: surfacePacket }),
+            ...(escapes.length === 0 ? {} : { escape: escapes }),
             ...(contractManifest === undefined ? {} : { contractManifest, contractArtifacts }),
             request: context?.title ?? GENERIC_REQUEST,
             criteria,
@@ -742,6 +879,8 @@ export async function runReviewCommand(options) {
         }))
     });
     const result = await executeReview();
+    if (surfacePacket !== undefined && result.report !== undefined && options.config?.profiles.includes("advisory") === true)
+        await logSurfaceResidualRisks(result.report.residualRisks.length + (result.adversarial?.report.residualRisks.length ?? 0));
     if (scope !== undefined && result.report !== undefined && options.root !== undefined) {
         try {
             if (result.report.changedFilesInspected.length !== scope.changedFiles.length ||
@@ -831,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,