@kylecheng3146/agent-ops 0.5.2 → 0.6.0

package/dist/packages/cli/src/run-setup-entry.js

@@ -0,0 +1,32 @@
+import { FileRunRepository } from "../../../runtime/src/run/service.js";
+import { readRunPolicy, runRuntimeHash } from "../../../runtime/src/run/policy.js";
+import { activeWallTimeMs } from "../../../runtime/src/run/scheduler.js";
+import { runVerificationCommand, NodeVerificationProcessRunner } from "../../../runtime/src/verify/spawn.js";
+import { redactSecrets } from "../../../runtime/src/security/redact.js";
+import { join } from "node:path";
+import { realpath } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+// This entry is released by run-step-entry only after its process group is registered.
+const [commonDir, runId, root, index, expectedPolicy] = process.argv.slice(2);
+if ([commonDir, runId, root, index, expectedPolicy].some(v => v === undefined))
+    throw new Error("Incomplete run setup identity.");
+const repository = new FileRunRepository(join(commonDir, "agent-ops/runs"), commonDir);
+const state = await repository.read(runId);
+const group = process.env.AGENT_OPS_RUN_PROOF_PID;
+const actualCommon = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd: root, encoding: "utf8" }).trim();
+if (state === null || state.status !== "active" || state.disableRestart || state.proofProcess?.processId !== Number(group) ||
+    state.policyBinding?.artifactDigest !== expectedPolicy || await realpath(actualCommon) !== await realpath(state.commonDir))
+    throw new Error("Stale run setup authorization.");
+const policy = await readRunPolicy(state, await runRuntimeHash());
+const step = /^(?:0|[1-9][0-9]*)$/u.test(index) ? policy?.config.worktree?.setup?.[Number(index)] : undefined;
+if (step === undefined)
+    throw new Error("Setup must select an authorized fixed policy command.");
+const remaining = state.budget.limitMs - activeWallTimeMs(state.budget.activeIntervals, Date.now());
+if (remaining <= 0)
+    throw new Error("Run budget is exhausted.");
+const result = await runVerificationCommand({ id: "run-setup", ...step, cwd: ".", required: true,
+    timeoutMs: Math.min(step.timeoutMs ?? 600000, remaining), evidence: { kind: "exit-code" } }, {
+    cwd: root, runner: new NodeVerificationProcessRunner({ processGroupId: Number(group) })
+});
+process.stdout.write(JSON.stringify({ exitCode: result.status === "PASS" ? 0 : result.exitCode ?? 1,
+    output: redactSecrets(result.stdout + result.stderr) }) + "\n");

package/dist/packages/cli/src/run-step-entry.js

@@ -0,0 +1,58 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+/** Dormant process group: the supervisor records this PID before releasing the CLI. */
+const cli = fileURLToPath(new URL("./bin.js", import.meta.url));
+const setup = fileURLToPath(new URL("./run-setup-entry.js", import.meta.url));
+const target = process.argv[2];
+if (target !== cli && target !== setup)
+    throw new Error("Run proof entry must use its own installed execution entry.");
+let input = "";
+let started = false;
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", chunk => {
+    if (started)
+        return;
+    input += chunk;
+    if (input.length > 16 || (input.includes("\n") && input !== "start\n"))
+        process.exit(1);
+    if (input !== "start\n")
+        return;
+    started = true;
+    // Keep this identity alive until the CLI finishes its signal cleanup.
+    process.on("SIGTERM", () => { });
+    process.on("SIGINT", () => { });
+    process.stdin.pause();
+    process.env.AGENT_OPS_RUN_PROOF_PID = String(process.pid);
+    const child = spawn(process.execPath, [target, ...process.argv.slice(3)], { env: process.env, stdio: ["ignore", "inherit", "inherit"] });
+    child.once("error", () => process.exit(1));
+    child.once("close", (code, signal) => {
+        const deadline = Date.now() + 3000;
+        const reconcile = () => {
+            const listing = spawn("ps", ["-axo", "pid=,pgid="], { detached: true, stdio: ["ignore", "pipe", "ignore"] });
+            let output = "";
+            listing.stdout.on("data", chunk => { output += chunk.toString(); });
+            listing.once("error", () => process.kill(-process.pid, "SIGKILL"));
+            listing.once("close", status => {
+                if (status !== 0)
+                    process.kill(-process.pid, "SIGKILL");
+                const remaining = output.split("\n").some(line => {
+                    const [pid, group] = line.trim().split(/\s+/u).map(Number);
+                    return group === process.pid && pid !== process.pid;
+                });
+                if (remaining && Date.now() < deadline) {
+                    setTimeout(reconcile, 50);
+                    return;
+                }
+                if (remaining)
+                    process.kill(-process.pid, "SIGKILL");
+                else if (signal !== null)
+                    process.exit(1);
+                else
+                    process.exit(code ?? 1);
+            });
+        };
+        reconcile();
+    });
+});
+process.stdin.on("end", () => { if (!started)
+    process.exit(1); });

package/dist/runtime/src/config/explain.js

@@ -29,6 +29,12 @@ export function explainConfig(merged) {
             source: entry.source,
             sourcePath: entry.sourcePath
         })),
+        ...(merged.provenance.acceptanceRunners === undefined ? {} : {
+            acceptanceRunners: merged.provenance.acceptanceRunners.map(entry => ({
+                id: entry.value.id, adapter: entry.value.adapter,
+                source: entry.source, sourcePath: entry.sourcePath
+            }))
+        }),
         pathMappings: merged.provenance.pathMappings.map((entry) => ({
             path: entry.value.path,
             verifierIds: [...entry.value.verifierIds],

package/dist/runtime/src/config/hash.js

@@ -1,6 +1,6 @@
 import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
-function canonicalJson(value) {
+export function canonicalJson(value) {
     if (value === null ||
         typeof value === "boolean" ||
         typeof value === "number" ||

package/dist/runtime/src/config/merge.js

@@ -105,6 +105,7 @@ export function mergeConfigLayers(inputLayers) {
     const layers = [...inputLayers].sort((left, right) => SOURCE_RANK[left.source] - SOURCE_RANK[right.source]);
     const profiles = new Map();
     const commands = new Map();
+    const acceptanceRunners = new Map();
     const mappings = new Map();
     const exceptions = new Map();
     const reviewRoles = new Map();
@@ -128,6 +129,9 @@ export function mergeConfigLayers(inputLayers) {
             }
             commands.set(command.id, effective(command, layer));
         }
+        for (const runner of layer.config.verification.acceptanceRunners ?? []) {
+            acceptanceRunners.set(runner.id, effective(runner, layer));
+        }
         for (const mapping of layer.config.pathMappings) {
             const key = mappingKey(mapping);
             if (layer.source === "project") {
@@ -162,6 +166,7 @@ export function mergeConfigLayers(inputLayers) {
         features,
         profiles: [...profiles.values()],
         verificationCommands: [...commands.values()],
+        ...(acceptanceRunners.size === 0 ? {} : { acceptanceRunners: [...acceptanceRunners.values()] }),
         pathMappings: [...mappings.values()],
         securityExceptions: [...exceptions.values()],
         reviewRoles: [...reviewRoles.values()],
@@ -171,7 +176,10 @@ export function mergeConfigLayers(inputLayers) {
         schemaVersion: schemaVersion.value,
         profiles: provenance.profiles.map(({ value }) => value),
         verification: {
-            commands: provenance.verificationCommands.map(({ value }) => value)
+            commands: provenance.verificationCommands.map(({ value }) => value),
+            ...(provenance.acceptanceRunners === undefined ? {} : {
+                acceptanceRunners: provenance.acceptanceRunners.map(({ value }) => value)
+            })
         },
         features: provenance.features.value,
         pathMappings: provenance.pathMappings.map(({ value }) => value),

package/dist/runtime/src/contracts.js

@@ -1,6 +1,6 @@
 export const CONFIG_SCHEMA_VERSION = 3;
-export const TASK_SCHEMA_VERSION = 1;
-export const EVIDENCE_SCHEMA_VERSION = 3;
+export const TASK_SCHEMA_VERSION = 2;
+export const EVIDENCE_SCHEMA_VERSION = 4;
 /** @deprecated Use the document-specific schema version constants. */
 export const SCHEMA_VERSION = CONFIG_SCHEMA_VERSION;
 /**

package/dist/runtime/src/hooks/completion-gate.js

@@ -6,6 +6,7 @@ import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../secur
 import { checkTaskCompletionEvidence, findIncompleteSubtask } from "../task/completion.js";
 import { collectBaseChangePaths, collectChangeSurface } from "../verify/change-surface.js";
 import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
+import { resolveReviewScope } from "../review/scope.js";
 import { NOTES_REF, noteSessionLine, readWorktreeRecord } from "../parallel/service.js";
 const FINGERPRINT = /^[a-f0-9]{64}$/u;
 const SESSION = /^[^\0\r\n]{1,256}$/u;
@@ -192,7 +193,7 @@ export class CompletionGateService {
      * range is recomputed here rather than trusted, so evidence for a range that
      * no longer ends at HEAD still fails.
      */
-    async #evidenceFingerprint(completionBase) {
+    async #evidenceFingerprint(completionBase, noChangePaths) {
         const worktree = await this.#fingerprint();
         if (completionBase === null) {
             return worktree;
@@ -202,6 +203,11 @@ export class CompletionGateService {
             return worktree;
         }
         try {
+            if (noChangePaths !== undefined) {
+                const scope = await resolveReviewScope({ root: this.#options.root, runner: this.#options.gitRunner,
+                    base: completionBase, noChangePaths });
+                return await calculateSourceFingerprint(this.#options.root, scope, this.#options.gitRunner);
+            }
             const changedFiles = await collectBaseChangePaths(this.#options.gitRunner, completionBase);
             if (changedFiles.length === 0) {
                 return worktree;
@@ -367,7 +373,7 @@ export class CompletionGateService {
         if (unfinished !== undefined) {
             return gateResult("block", "FAIL", "COMPLETION_GATE_SUBTASK_INCOMPLETE", `Complete subtask ${unfinished.task.id} before its parent.`);
         }
-        const sourceFingerprint = await this.#evidenceFingerprint(stored.completionBase);
+        const sourceFingerprint = await this.#evidenceFingerprint(stored.completionBase, stored.noChangePaths);
         const problem = await checkTaskCompletionEvidence(stored, {
             ...this.#options,
             sourceFingerprint

package/dist/runtime/src/install/doctor.js

@@ -548,6 +548,8 @@ export async function doctorInstallation(options) {
             ? []
             : [await checkProbe("root-ghost-files", options.probes.rootGhostFiles)])
     ];
+    if (options.probes?.acceptanceCoverage !== undefined)
+        checks.push(await checkProbe("acceptance-coverage", options.probes.acceptanceCoverage));
     return {
         checks,
         surfaces: surfaceInventory.surfaces,

package/dist/runtime/src/install/harness.js

@@ -322,7 +322,7 @@ export function managedRules(descriptor, context) {
         lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }
     if (context.capabilities.includes("task")) {
-        lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria, verification, and independent review;", "completing one never completes its parent.", "", "To review every active subtask of a parent together, run", "`agent-ops batch --parent <task-id> --yes` instead of one review per", "subtask. It needs what review needs: start it through the trusted outer", "host runner as its first and only invocation, with the same Codex", "elevation, and keep `--output <file>` instead of a shell redirect. It", "verifies, one task at a time, each task that lacks fresh evidence, and", "reviews a few tasks at once. Do not commit or edit the worktree while it", "runs: a moved HEAD voids every verify and review in the batch.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops task create` from the main checkout before your first edit:", "it creates this session's worktree and puts the task there (`agent-ops", "worktree add <name> --session <session-id>` does the same without a", "task). Work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify and review for", "each task with the printed `--base`; do not run `task complete` in the", "worktree. Leave it (Claude Code: ExitWorktree with action keep) and run", "`agent-ops worktree finish <name>` from the main checkout: it completes", "every task in the worktree, subtasks first, then merges. A finish that", "reports an incomplete task names it; verify or review that task again", "in the worktree and finish again. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "");
+        lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria and verification; final review covers all", "tasks together when their worktrees are integrated;", "completing one never completes its parent.", "", "To review every active subtask of a parent together, run", "`agent-ops batch --parent <task-id> --yes` instead of one review per", "subtask. It needs what review needs: start it through the trusted outer", "host runner as its first and only invocation, with the same Codex", "elevation, and keep `--output <file>` instead of a shell redirect. It", "verifies, one task at a time, each task that lacks fresh evidence, and", "reviews a few tasks at once. Do not commit or edit the worktree while it", "runs: a moved HEAD voids every verify and review in the batch.", "For subagents in separate worktrees, use `task advance` instead.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops task create` from the main checkout before your first edit:", "it creates this session's worktree and puts the task there (`agent-ops", "worktree add <name> --session <session-id>` does the same without a", "task). Work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify and review for", "each task with the printed `--base`; do not run `task complete` in the", "worktree. Leave it (Claude Code: ExitWorktree with action keep) and run", "`agent-ops worktree finish <name>` from the main checkout: it completes", "every task in the worktree, subtasks first, then merges. A finish that", "reports an incomplete task names it; verify or review that task again", "in the worktree and finish again. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "", "For a session with writing subagents, record each child task's complete", "modification intent with `task create --intent <text>` before editing.", "Each child commits and runs local `verify --task` in its own worktree.", "From the main checkout run `agent-ops task advance --task <parent-id>", "--session <session-id> --yes` through the trusted outer host runner,", "unsetting `CODEX_SANDBOX_NETWORK_DISABLED` on Codex. Advance integrates", "child commits and intent into the coordinator worktree, verifies every", "task on the final candidate, then runs one two-round tree review.", "Only `NOT_RUN / scope-too-large` falls back to per-task two-round review;", "a substantive FAIL must be fixed. After PASS, advance writes a local", "receipt under the main checkout's Git common directory and calls finish.", "If the target moves, it retries the final gate once. An unresolved", "failure preserves worktrees and cannot be reported as finished.", "");
     }
     if (context.capabilities.includes("lifecycle-summary")) {
         lines.push("Advisory lifecycle summaries and local logs are informational. Advisory", "failures must remain fail-open and cannot become verification evidence.", "");

package/dist/runtime/src/install/preauth.js

@@ -24,11 +24,13 @@ export const CLAUDE_PREAUTH_ALLOW = [
     "Bash(npx lint-staged *)"
 ];
 /**
- * review and batch talk to the reviewer's API, which the sandbox withholds;
+ * review, batch and task advance talk to the reviewer's API, which the sandbox withholds;
  * worktree commit and lint-staged write the main .git, which a worktree's
  * sandbox cannot.
  */
 export const CLAUDE_PREAUTH_UNSANDBOXED = [
+    "agent-ops task advance",
+    "agent-ops task advance *",
     "agent-ops review",
     "agent-ops review *",
     "agent-ops batch",
@@ -110,6 +112,13 @@ export const CODEX_RULES_CONTENT = `${[
                 match: `${env} batch --parent task-x --yes --output batch.json`,
                 notMatch: `${env} trust grant --scope project --yes`
             }),
+            rule({
+                withHost,
+                command: ["task", "advance"],
+                justification: "agent-ops task advance runs the final reviewer chain and finish outside the sandbox.",
+                match: `${env} task advance --task task-x --session session-x --yes`,
+                notMatch: `${env} trust grant --scope project --yes`
+            }),
             rule({
                 withHost,
                 command: ["doctor", "--check-auth"],

package/dist/runtime/src/parallel/finish.js

@@ -1,10 +1,16 @@
 import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { sha256 } from "../fs/hash.js";
 import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { currentGateFingerprint } from "../hooks/completion-gate.js";
 import { collectChangeSurface } from "../verify/change-surface.js";
 import { aggregateVerificationStatus, executeConfiguredCommand } from "../verify/command-executor.js";
+import { prepareFinishReceipt } from "./receipt.js";
+import { readRunIntegrationProof, readRunIntegrationReceiptBinding, markRunIntegration } from "../run/integration.js";
+import { canonicalJson } from "../config/hash.js";
+import { listWorktrees } from "./manage.js";
+import { withPrivateFileLock } from "../security/permissions.js";
 import { assertWorktreeName, NOTES_REF, noteSessionLine, parseWorktreeListPorcelain, readWorktreeRecord, removeCheckout, resolveCheckouts, worktreePath } from "./service.js";
 const LOCK_NAME = "agent-ops-finish.lock";
 const LOCK_POLL_MS = 2_000;
@@ -95,30 +101,50 @@ export async function withFinishLock(deps, commonDir, action) {
     const path = join(commonDir, LOCK_NAME);
     const deadline = Date.now() + (deps.lockWaitMs ?? LOCK_WAIT_MS);
     const sleep = deps.sleep ?? (async (ms) => await new Promise((resolve) => setTimeout(resolve, ms)));
+    const token = randomUUID();
     for (;;) {
+        let claimed = false;
         try {
-            await mkdir(path);
-            await writeFile(join(path, "owner.json"), JSON.stringify({ pid: process.pid, at: Date.now() }));
-            break;
+            claimed = await withPrivateFileLock(path + ".state", commonDir, async () => {
+                for (;;) {
+                    try {
+                        await mkdir(path);
+                        await writeFile(join(path, "owner.json"), JSON.stringify({ pid: process.pid, at: Date.now(), token }));
+                        return true;
+                    }
+                    catch (error) {
+                        if (error.code !== "EEXIST")
+                            throw error;
+                        if (!await staleLock(path))
+                            return false;
+                        await rm(path, { recursive: true, force: true });
+                    }
+                }
+            });
         }
         catch (error) {
-            if (error.code !== "EEXIST")
+            if (!(error instanceof AgentOpsError) || error.code !== "PRIVATE_STATE_LOCK_TIMEOUT")
                 throw error;
-            if (await staleLock(path)) {
-                await rm(path, { recursive: true, force: true });
-                continue;
-            }
-            if (Date.now() >= deadline) {
-                throw finishError("WORKTREE_FINISH_BUSY", "Another worktree finish is still running; try again later.");
-            }
-            await sleep(LOCK_POLL_MS);
         }
+        if (claimed)
+            break;
+        if (Date.now() >= deadline)
+            throw finishError("WORKTREE_FINISH_BUSY", "Another worktree finish is still running; try again later.");
+        await sleep(LOCK_POLL_MS);
     }
     try {
         return await action();
     }
     finally {
-        await rm(path, { recursive: true, force: true });
+        await withPrivateFileLock(path + ".state", commonDir, async () => {
+            const owner = await readFile(join(path, "owner.json"), "utf8").catch(error => {
+                if (error.code === "ENOENT")
+                    return null;
+                throw error;
+            });
+            if (owner !== null && JSON.parse(owner)?.token === token)
+                await rm(path, { recursive: true, force: true });
+        });
     }
 }
 /**
@@ -184,6 +210,7 @@ function noteText(record, tasks) {
             const indent = "  ".repeat(depth);
             return [
                 `${indent}agent-ops task ${task.task.id}: ${task.task.title}`,
+                ...(task.task.intent === undefined ? [] : [`${indent}intent: ${task.task.intent}`]),
                 `${indent}criteria:`,
                 ...task.task.criteria.map(({ id, description }) => `${indent}- ${id}: ${description}`)
             ];
@@ -206,6 +233,31 @@ export async function finishWorktree(deps, options) {
         throw finishError("WORKTREE_NOT_FOUND", `No agent-ops worktree named ${name}; see agent-ops worktree list.`);
     }
     return await withFinishLock(deps, commonDir, async () => {
+        const sessionChildren = (await listWorktrees(deps, mainRoot))
+            .map(({ record: child }) => child)
+            .filter((child) => child.path !== record.path && child.sessionId === record.sessionId &&
+            (child.agentId !== undefined || (record.runId !== undefined && child.runId === record.runId)));
+        if (options.finalProof === undefined && sessionChildren.length > 0) {
+            throw finishError("WORKTREE_CHILDREN_REQUIRE_ADVANCE", "This session has child worktrees; run task advance for integrated final evidence before finish.");
+        }
+        if (options.finalProof !== undefined && options.finalProof.recovery !== true &&
+            (sessionChildren.length !== options.finalProof.children.length ||
+                sessionChildren.some((child) => !options.finalProof.children.some(({ name }) => name === child.name)))) {
+            throw finishError("WORKTREE_CHILDREN_CHANGED", "The child worktree set changed after final review.");
+        }
+        const assertPinnedChild = async (child) => {
+            const expected = options.finalProof?.children.find(({ name }) => name === child.name)?.commit;
+            const head = await git(deps, child.path, ["rev-parse", "HEAD"], "WORKTREE_CHILDREN_CHANGED", `Cannot read child ${child.name}.`);
+            if (expected === undefined || head !== expected ||
+                (await collectChangeSurface(runner(deps, child.path))).paths.length > 0) {
+                throw finishError("WORKTREE_CHILDREN_CHANGED", `Child ${child.name} changed after integration; preserve its worktree.`);
+            }
+            return head;
+        };
+        if (options.finalProof !== undefined) {
+            for (const child of sessionChildren)
+                await assertPinnedChild(child);
+        }
         const mainRunner = runner(deps, mainRoot);
         const worktreeRunner = runner(deps, record.path);
         const onBranch = (await deps.git(mainRoot, ["symbolic-ref", "--short", "-q", "HEAD"])).stdout.trim();
@@ -230,38 +282,74 @@ export async function finishWorktree(deps, options) {
         if ((await collectChangeSurface(worktreeRunner)).paths.length > 0) {
             throw finishError("WORKTREE_DIRTY", `Commit or discard the uncommitted changes in ${record.path} first.`);
         }
-        const target = await git(deps, mainRoot, ["rev-parse", "--verify", `${record.targetBranch}^{commit}`], "WORKTREE_TARGET_MISSING", `${record.targetBranch} does not resolve to a commit.`);
+        const actualTarget = await git(deps, mainRoot, ["rev-parse", "--verify", `${record.targetBranch}^{commit}`], "WORKTREE_TARGET_MISSING", `${record.targetBranch} does not resolve to a commit.`);
+        const recovering = options.finalProof?.recovery === true;
+        if (recovering) {
+            const sealed = await readRunIntegrationProof(commonDir, record);
+            const { recovery: _recovery, ...requested } = options.finalProof;
+            if (sealed === null || canonicalJson(sealed) !== canonicalJson(requested) || actualTarget !== sealed.head)
+                throw finishError("RUN_INTEGRATION_PROOF_CHANGED", "Recovery requires the exact sealed candidate already at the target.");
+        }
+        const target = recovering ? options.finalProof.target : actualTarget;
+        if (options.finalProof !== undefined && actualTarget !== options.finalProof.target && !recovering) {
+            throw finishError("WORKTREE_TARGET_MOVED", "The target branch moved after final review; rerun the final evidence gate.");
+        }
         const ahead = Number(await git(deps, record.path, ["rev-list", "--count", `${target}..HEAD`], "WORKTREE_LOG_FAILED", "Git could not compare the branch with its target."));
-        if (ahead === 0) {
+        const noChangeProof = options.finalProof?.noChange;
+        if (ahead === 0 && noChangeProof === undefined && !recovering) {
             throw finishError("WORKTREE_NOTHING_TO_MERGE", `${record.branch} has no commits beyond ${record.targetBranch}; remove the worktree instead.`);
         }
         const worktreeConfig = await deps.loadConfig(record.path);
-        // The whole branch merges, so every task in the worktree completes first,
-        // subtasks before their parents, each over the range its review covered.
-        // Before any rebase: rebasing rewrites the commits those fingerprints name.
+        const headBeforeCompletion = await git(deps, record.path, ["rev-parse", "HEAD"], "WORKTREE_LOG_FAILED", "Git could not read HEAD.");
+        if (options.finalProof !== undefined) {
+            if (headBeforeCompletion !== options.finalProof.head) {
+                throw finishError("WORKTREE_SOURCE_MOVED", "The candidate changed after final review.");
+            }
+            if ((await deps.git(record.path, ["merge-base", "--is-ancestor", target, "HEAD"])).exitCode !== 0) {
+                throw finishError("WORKTREE_TARGET_MOVED", "The final candidate is not based on the target; rerun the final evidence gate.");
+            }
+            if (noChangeProof !== undefined && noChangeProof.sourceCommit !== headBeforeCompletion) {
+                throw finishError("WORKTREE_NO_CHANGE_SOURCE_MISMATCH", "The verified-no-change proof does not match the candidate commit.");
+            }
+        }
+        // Direct finish completes before merge. A final-proof finish checks all
+        // evidence first, then completes only after the target's fast-forward:
+        // a target that moves before that point can still be re-reviewed once.
         const tree = taskTree((await deps.tasks(record.path).list()).filter(({ status }) => status !== "archived"));
         if (tree.length === 0) {
             throw finishError("WORKTREE_TASK_INCOMPLETE", "The worktree has no task; create one, verify and review it before finishing.");
         }
-        for (const { task } of [...tree].sort((left, right) => right.depth - left.depth)) {
-            if (task.status === "complete")
-                continue;
-            const base = task.reviewBase ?? record.base;
-            try {
-                await deps.tasks(record.path, base).complete(task.task.id, {});
+        const completeTasks = async () => {
+            const noChangePaths = noChangeProof?.reviewScope.changedFiles;
+            for (const { task } of [...tree].sort((left, right) => right.depth - left.depth)) {
+                if (task.status === "complete")
+                    continue;
+                const base = options.finalProof === undefined ? task.reviewBase ?? record.base : target;
+                try {
+                    await deps.tasks(record.path, base, noChangePaths).complete(task.task.id, {});
+                }
+                catch (error) {
+                    throw finishError("WORKTREE_TASK_INCOMPLETE", `Task ${task.task.id} (${task.task.title}) could not be completed against ${base}: ${error instanceof Error ? error.message : String(error)} ` +
+                        "A task another session left here is not this session's to archive: its owner finishes or archives it, and finish never does.");
+                }
             }
-            catch (error) {
-                throw finishError("WORKTREE_TASK_INCOMPLETE", `Task ${task.task.id} (${task.task.title}) could not be completed against ${base}: ${error instanceof Error ? error.message : String(error)} ` +
-                    "A task another session left here is not this session's to archive: its owner finishes or archives it, and finish never does.");
+        };
+        const validateGate = async () => {
+            const worktreeGate = await deps.gate(record.path, worktreeConfig);
+            const problem = await worktreeGate.validate(record.sessionId);
+            if (problem !== null) {
+                throw finishError("WORKTREE_TASK_INCOMPLETE", `The worktree's task is not ready to merge (${problem.code}). ${problem.remedy ?? ""}`.trim());
             }
-        }
-        const worktreeGate = await deps.gate(record.path, worktreeConfig);
-        const problem = await worktreeGate.validate(record.sessionId);
-        if (problem !== null) {
-            throw finishError("WORKTREE_TASK_INCOMPLETE", `The worktree's task is not ready to merge (${problem.code}). ${problem.remedy ?? ""}`.trim());
+        };
+        if (options.finalProof === undefined) {
+            await completeTasks();
+            await validateGate();
         }
         const head = await git(deps, record.path, ["rev-parse", "HEAD"], "WORKTREE_LOG_FAILED", "Git could not read HEAD.");
         const fastForward = (await deps.git(record.path, ["merge-base", "--is-ancestor", target, "HEAD"])).exitCode === 0;
+        if (options.finalProof !== undefined && !fastForward) {
+            throw finishError("WORKTREE_TARGET_MOVED", "The target branch moved after final review.");
+        }
         if (!fastForward) {
             const before = await patchHash(deps, record.path, target);
             const rebase = await deps.git(record.path, ["rebase", "--no-autostash", target]);
@@ -287,19 +375,84 @@ export async function finishWorktree(deps, options) {
                 throw finishError("WORKTREE_REVERIFY_FAILED", `After rebasing onto ${target}, verification failed: ${failed.join(", ")}. The branch was reset; fix it as a new task and finish again.`);
             }
         }
+        const sealedIntegration = options.finalProof === undefined || record.runId === undefined
+            ? null
+            : await readRunIntegrationReceiptBinding(commonDir, record, { target, candidate: head });
+        const requestedIntegration = options.finalProof?.integrationJournal;
+        if (requestedIntegration !== undefined && sealedIntegration !== null &&
+            canonicalJson(requestedIntegration) !== canonicalJson(sealedIntegration)) {
+            throw finishError("RUN_INTEGRATION_PROOF_CHANGED", "The requested receipt binding differs from the sealed integration transaction.");
+        }
+        const integrationJournal = sealedIntegration ?? requestedIntegration;
+        const receiptOptions = options.finalProof === undefined ? undefined : {
+            commonDir,
+            record,
+            candidateHead: head,
+            targetCommit: target,
+            expectedFingerprint: options.finalProof.sourceFingerprint,
+            children: options.finalProof.children,
+            config: worktreeConfig,
+            gitRunner: worktreeRunner,
+            ...(noChangeProof === undefined ? {} : { noChange: noChangeProof }),
+            ...(integrationJournal === undefined ? {} : { integrationJournal })
+        };
+        let receipt = receiptOptions === undefined ? undefined : await prepareFinishReceipt({
+            ...receiptOptions,
+            tasks: await deps.tasks(record.path).list().then((tasks) => tasks.filter(({ status }) => status !== "archived"))
+        });
         const mainConfig = await deps.loadConfig(mainRoot);
         const gateEnabled = mainConfig.features.completionGate.enabled;
         const before = gateEnabled ? await currentGateFingerprint(mainRoot, mainRunner) : "";
         let mergedHead;
-        if (onTarget) {
-            await git(deps, mainRoot, ["merge", "--ff-only", record.branch], "WORKTREE_MERGE_FAILED", `Git could not fast-forward ${record.targetBranch}.`);
+        if (noChangeProof !== undefined || recovering) {
+            // A verified-no-change finish records proof and task state while leaving
+            // the target ref untouched. The ordinary finish path still rejects an
+            // empty branch, preserving its public behavior.
+            mergedHead = actualTarget;
+        }
+        else if (onTarget) {
+            if (options.finalProof !== undefined &&
+                await git(deps, mainRoot, ["rev-parse", "HEAD"], "WORKTREE_LOG_FAILED", "Git could not read HEAD.") !== target) {
+                throw finishError("WORKTREE_TARGET_MOVED", "The target changed after the final proof was prepared.");
+            }
+            const merge = await deps.git(mainRoot, ["merge", "--ff-only", record.branch]);
+            if (merge.exitCode !== 0) {
+                if (options.finalProof !== undefined &&
+                    await git(deps, mainRoot, ["rev-parse", "HEAD"], "WORKTREE_LOG_FAILED", "Git could not read HEAD.") !== target) {
+                    throw finishError("WORKTREE_TARGET_MOVED", "The target moved during finish; rerun the final evidence gate.");
+                }
+                throw finishError("WORKTREE_MERGE_FAILED", `Git could not fast-forward ${record.targetBranch}. ${merge.stderr.trim()}`);
+            }
             mergedHead = await git(deps, mainRoot, ["rev-parse", "HEAD"], "WORKTREE_LOG_FAILED", "Git could not read HEAD.");
         }
         else {
             // Compare-and-swap on the target's value read above: a target that moved
             // since fails here instead of being overwritten.
             mergedHead = await git(deps, mainRoot, ["rev-parse", "--verify", `${record.branch}^{commit}`], "WORKTREE_LOG_FAILED", `Git could not read ${record.branch}.`);
-            await git(deps, mainRoot, ["update-ref", "-m", `agent-ops finish ${record.branch}`, `refs/heads/${record.targetBranch}`, mergedHead, target], "WORKTREE_MERGE_FAILED", `Git could not fast-forward ${record.targetBranch}.`);
+            const update = await deps.git(mainRoot, ["update-ref", "-m", `agent-ops finish ${record.branch}`, `refs/heads/${record.targetBranch}`, mergedHead, target]);
+            if (update.exitCode !== 0) {
+                if (options.finalProof !== undefined &&
+                    await git(deps, mainRoot, ["rev-parse", `${record.targetBranch}^{commit}`], "WORKTREE_LOG_FAILED", "Git could not read the target.") !== target) {
+                    throw finishError("WORKTREE_TARGET_MOVED", "The target moved during finish; rerun the final evidence gate.");
+                }
+                throw finishError("WORKTREE_MERGE_FAILED", `Git could not fast-forward ${record.targetBranch}. ${update.stderr.trim()}`);
+            }
+        }
+        if (receiptOptions !== undefined) {
+            await markRunIntegration(commonDir, record, "target-moved", "target");
+            try {
+                await completeTasks();
+                await validateGate();
+                await markRunIntegration(commonDir, record, "tasks-completed", "tasks");
+                receipt = await prepareFinishReceipt({
+                    ...receiptOptions,
+                    tasks: await deps.tasks(record.path).list().then((tasks) => tasks.filter(({ status }) => status !== "archived"))
+                });
+                await markRunIntegration(commonDir, record, "receipt-written", "receipt", receipt);
+            }
+            catch (error) {
+                throw finishError("WORKTREE_FINISH_PARTIAL", `Code merged at ${mergedHead}; final task state or receipt failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
         }
         // The merge happened; everything below is cleanup, reported, never undone.
         const warnings = [];
@@ -308,10 +461,17 @@ export async function finishWorktree(deps, options) {
                 await step();
             }
             catch (error) {
-                warnings.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+                const message = `${label}: ${error instanceof Error ? error.message : String(error)}`;
+                if (options.finalProof !== undefined) {
+                    throw finishError("WORKTREE_FINISH_PARTIAL", `Code merged at ${mergedHead} with receipt ${receipt?.path}; ${message}`);
+                }
+                warnings.push(message);
             }
         };
-        await attempt("note", async () => await git(deps, mainRoot, ["notes", `--ref=${NOTES_REF}`, "add", "-f", "-m", noteText(record, tree), mergedHead], "WORKTREE_NOTE_FAILED", "Git could not write the agent-ops note."));
+        const finishNote = `${noteText(record, tree)}${noChangeProof === undefined ? "" : "\nverified-no-change: true"}${receipt === undefined ? "" : `\nreceipt: ${receipt.path}\nreceipt-sha256: ${receipt.digest}`}`;
+        await attempt("note", async () => await git(deps, mainRoot, ["notes", `--ref=${NOTES_REF}`, "add", "-f", "-m", finishNote, mergedHead], "WORKTREE_NOTE_FAILED", "Git could not write the agent-ops note."));
+        if (receiptOptions !== undefined)
+            await markRunIntegration(commonDir, record, "receipt-written", "note");
         if (gateEnabled) {
             await attempt("gate", async () => {
                 const mainGate = await deps.gate(mainRoot, mainConfig);
@@ -321,10 +481,28 @@ export async function finishWorktree(deps, options) {
                 // this session began would leave it reading the merge as its own change.
                 // Only this worktree leaves the session; its other roots stay covered.
                 await mainGate.afterFinish(record.sessionId, record.path, after);
+                if (options.finalProof !== undefined) {
+                    for (const child of sessionChildren) {
+                        await mainGate.afterFinish(record.sessionId, child.path, after);
+                    }
+                }
             });
         }
         await attempt("trust", async () => await deps.trust.revoke(record.path, worktreeConfig));
-        await attempt("remove", async () => await removeCheckout(deps, record, true));
-        return { record, mergedHead, rebased: !fastForward, taskIds: tree.map(({ task }) => task.task.id), warnings };
+        if (options.finalProof !== undefined) {
+            for (const child of sessionChildren) {
+                await attempt(`child ${child.name}`, async () => {
+                    const pinnedHead = await assertPinnedChild(child);
+                    await deps.trust.revoke(child.path, await deps.loadConfig(child.path));
+                    await removeCheckout(deps, child, false, pinnedHead);
+                    await markRunIntegration(commonDir, record, "receipt-written", "child:" + child.name);
+                });
+            }
+        }
+        await attempt("remove", async () => await removeCheckout(deps, record, options.finalProof === undefined, options.finalProof?.head));
+        if (receiptOptions !== undefined)
+            await markRunIntegration(commonDir, record, "cleaned", "coordinator");
+        return { record, mergedHead, rebased: !fastForward, taskIds: tree.map(({ task }) => task.task.id), warnings,
+            ...(receipt === undefined ? {} : { receipt: receipt.path }) };
     });
 }