@kylecheng3146/agent-ops 0.5.2 → 0.6.0

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

@@ -1,3 +1,4 @@
+import { registeredRunWriter } from "../run/ownership.js";
 import { realpath } from "node:fs/promises";
 import { basename, dirname, join, relative, sep } from "node:path";
 import { insideWorktreeDirectory, mayUseWorktree, readWorktreeRecord, WORKTREE_DIRECTORY } from "./service.js";
@@ -54,7 +55,10 @@ agentId) {
             // session's mixes two tasks' changes into one review and one merge.
             const name = relative(join(mainRoot, WORKTREE_DIRECTORY), target).split(sep)[0] ?? "";
             const record = await readWorktreeRecord(join(mainRoot, WORKTREE_DIRECTORY, name));
-            if (record !== null && !mayUseWorktree(record, sessionId, agentId)) {
+            const permitted = record === null || (record.runId === undefined
+                ? mayUseWorktree(record, sessionId, agentId)
+                : await registeredRunWriter(record, sessionId, agentId));
+            if (record !== null && !permitted) {
                 const owner = record.sessionId;
                 const sameSession = owner === sessionId;
                 let own = "";

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

@@ -0,0 +1,416 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { calculateConfigHash } from "../config/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { sha256 } from "../fs/hash.js";
+import { resolveReviewScope } from "../review/scope.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { checkTaskVerificationEvidence } from "../task/completion.js";
+import { validateEvidence } from "../schema/validate.js";
+import { FileEvidenceStore } from "../verify/evidence.js";
+import { REVIEW_ATTESTATION_DIRECTORY } from "../review/attestation.js";
+import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
+import { collectChangeSurface } from "../verify/change-surface.js";
+import { listWorktrees } from "./manage.js";
+function error(code, message) {
+    return new AgentOpsError(code, message);
+}
+async function git(deps, cwd, args) {
+    const result = await deps.git(cwd, args);
+    if (result.exitCode !== 0)
+        throw error("WORKTREE_INTEGRATION_FAILED", `${args.join(" ")}: ${result.stderr.trim()}`);
+    return result.stdout.trim();
+}
+function runner(deps, cwd) {
+    return { run: async (args) => {
+            const result = await deps.git(cwd, args);
+            return { exitCode: result.exitCode, stdout: Buffer.from(result.stdout, "utf8") };
+        } };
+}
+function markerPath(record) {
+    return join(record.path, ".agent-ops", "tasks", "integrated-children.json");
+}
+function journalPath(record) {
+    return join(record.path, ".agent-ops", "tasks", "integration-journal.json");
+}
+function deliveryPath(record) {
+    return join(record.path, ".agent-ops", "tasks", "delivery.json");
+}
+function deliveryArchivePath(record, child) {
+    return join(record.path, ".agent-ops", "tasks", "deliveries", `${child.name}.json`);
+}
+async function readJournal(record) {
+    const source = await readPrivateFile(journalPath(record), record.path);
+    if (source === null)
+        return null;
+    try {
+        const value = JSON.parse(source);
+        if (value.schemaVersion !== 1 || typeof value.transactionId !== "string" || value.transactionId.length === 0 || value.transactionId.length > 256 ||
+            !/^[a-f0-9]{40,64}$/u.test(value.expectedTarget ?? "") ||
+            !/^[a-f0-9]{40,64}$/u.test(value.coordinatorBefore ?? "") ||
+            !["prepared", "merging", "importing", "recorded", "rolled-back"].includes(String(value.status)) ||
+            !Array.isArray(value.steps) || value.steps.some((step) => typeof step !== "object" || step === null ||
+            typeof step.name !== "string" ||
+            !/^[a-f0-9]{40,64}$/u.test(step.commit ?? "") ||
+            !["changed", "no-change"].includes(String(step.kind)) ||
+            !["prepared", "merged", "imported", "recorded"].includes(String(step.status)) ||
+            !Array.isArray(step.taskIds) ||
+            !Array.isArray(step.sourceArtifacts))) {
+            throw new Error("invalid integration journal");
+        }
+        return value;
+    }
+    catch (cause) {
+        throw error("WORKTREE_INTEGRATION_JOURNAL_INVALID", "Integration journal is invalid; preserve the worktree for recovery.");
+    }
+}
+/** Read the coordinator's durable integration transaction for finish/recovery. */
+export async function readIntegrationJournal(record) {
+    return await readJournal(record);
+}
+async function writeJournal(record, journal) {
+    await mkdir(join(record.path, ".agent-ops", "tasks"), { recursive: true });
+    await writePrivateFile(journalPath(record), `${JSON.stringify(journal, null, 2)}\n`, record.path);
+}
+/** Stable digest used by finish receipts to bind journal bookkeeping. */
+export function integrationJournalDigest(journal) {
+    return sha256(JSON.stringify(journal));
+}
+/** Persist a coordinator journal update so recovery can resume the same transaction. */
+export async function writeIntegrationJournal(record, journal) {
+    await writeJournal(record, journal);
+}
+async function readNoChangeDelivery(record) {
+    const source = await readPrivateFile(deliveryPath(record), record.path);
+    if (source === null)
+        return null;
+    try {
+        const value = JSON.parse(source);
+        if (value.schemaVersion !== 1 || value.deliveryKind !== "no-change" ||
+            typeof value.sourceCommit !== "string" || !/^[a-f0-9]{40,64}$/u.test(value.sourceCommit) ||
+            typeof value.deliveryDigest !== "string" || !/^[a-f0-9]{40,64}$/u.test(value.deliveryDigest) ||
+            typeof value.contractDigest !== "string" || !/^[a-f0-9]{40,64}$/u.test(value.contractDigest) ||
+            typeof value.reviewScope !== "string" || value.reviewScope.length === 0 ||
+            typeof value.runId !== "string" || typeof value.workerId !== "string" ||
+            !Number.isSafeInteger(value.generation) || value.generation < 1 ||
+            !Array.isArray(value.artifactRefs) || value.artifactRefs.some((ref) => typeof ref !== "string" || ref.length === 0 || ref.length > 4096 || ref.includes("\0"))) {
+            throw new Error("invalid no-change delivery");
+        }
+        return value;
+    }
+    catch {
+        throw error("WORKTREE_NO_CHANGE_DELIVERY_INVALID", `Child ${record.name} has an invalid no-change delivery manifest.`);
+    }
+}
+function parseNoChangeReviewScope(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw error("WORKTREE_NO_CHANGE_SCOPE_INVALID", "No-change review scope is not valid JSON.");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        throw error("WORKTREE_NO_CHANGE_SCOPE_INVALID", "No-change review scope is invalid.");
+    const scope = parsed;
+    const safePaths = (paths) => Array.isArray(paths) && paths.length > 0 && paths.every((path) => {
+        if (typeof path !== "string" || path.length === 0 || path.includes("\\") || path.startsWith("/") || path.includes("\0"))
+            return false;
+        return path.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+    });
+    const noChange = scope.noChange === true;
+    if (scope.mode === "worktree" && safePaths(scope.changedFiles)) {
+        return { mode: "worktree", changedFiles: scope.changedFiles, ...(noChange ? { noChange: true } : {}) };
+    }
+    if (scope.mode === "base" && typeof scope.baseRef === "string" && typeof scope.resolvedBase === "string" &&
+        /^[a-f0-9]{40,64}$/u.test(scope.resolvedBase) && safePaths(scope.changedFiles)) {
+        return { mode: "base", baseRef: scope.baseRef, resolvedBase: scope.resolvedBase, changedFiles: scope.changedFiles, ...(noChange ? { noChange: true } : {}) };
+    }
+    throw error("WORKTREE_NO_CHANGE_SCOPE_INVALID", "No-change review scope must list at least one safe supporting path.");
+}
+/** Persist a coordinator-issued no-change handoff before the worker is fenced. */
+export async function writeNoChangeDelivery(record, delivery) {
+    if (delivery.runId !== record.runId || delivery.workerId !== record.workerId || delivery.generation !== record.workerGeneration) {
+        throw error("WORKTREE_NO_CHANGE_OWNERSHIP", `No-change delivery does not match worktree ${record.name}.`);
+    }
+    await writePrivateFile(deliveryPath(record), `${JSON.stringify(delivery, null, 2)}\n`, record.path);
+}
+async function previous(record) {
+    const source = await readPrivateFile(markerPath(record), record.path);
+    if (source === null)
+        return [];
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        value = null;
+    }
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "object" || item === null ||
+        typeof item.name !== "string" || typeof item.commit !== "string" ||
+        !/^[a-f0-9]{40,64}$/u.test(item.commit) ||
+        !Array.isArray(item.taskIds) || item.taskIds.some((id) => typeof id !== "string"))) {
+        throw error("WORKTREE_INTEGRATION_STATE_INVALID", "Child integration record is invalid.");
+    }
+    return value;
+}
+/** Integrate only this session's agent-owned branches; local proof is never promoted as final proof. */
+export async function integrateSessionChildren(deps, coordinator, parentTaskId, eligibleRunWorkerIds) {
+    const statuses = await listWorktrees(deps, coordinator.mainRoot);
+    const children = statuses.map(({ record }) => record)
+        .filter((record) => record.name !== coordinator.name && record.sessionId === coordinator.sessionId &&
+        (record.agentId !== undefined || (coordinator.runId !== undefined && record.runId === coordinator.runId)))
+        .filter(record => eligibleRunWorkerIds === undefined || (record.workerId !== undefined && eligibleRunWorkerIds.includes(record.workerId)))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const integrated = await previous(coordinator);
+    if (children.length === 0)
+        return integrated;
+    const config = await deps.loadConfig(coordinator.path);
+    const configHash = calculateConfigHash(config);
+    const deliveries = [];
+    const existing = new Map(integrated.map((item) => [item.name, item]));
+    for (const record of children) {
+        if (record.mainRoot !== coordinator.mainRoot || record.targetBranch !== coordinator.targetBranch ||
+            record.name === coordinator.name ||
+            await git(deps, record.path, ["symbolic-ref", "--short", "HEAD"]) !== record.branch) {
+            throw error("WORKTREE_CHILD_MISMATCH", `Child ${record.name} does not belong to this candidate branch.`);
+        }
+        if ((await collectChangeSurface(runner(deps, record.path))).paths.length > 0) {
+            throw error("WORKTREE_CHILD_DIRTY", `Commit the changes in child ${record.name} before integration.`);
+        }
+        const head = await git(deps, record.path, ["rev-parse", "HEAD"]);
+        const prior = existing.get(record.name);
+        if (prior !== undefined) {
+            if (prior.commit !== head)
+                throw error("WORKTREE_CHILD_MOVED", `Child ${record.name} changed after delivery; keep its worktree and replan integration.`);
+            continue;
+        }
+        const ahead = Number(await git(deps, record.path, ["rev-list", "--count", `${record.base}..${head}`]));
+        const noChange = ahead === 0;
+        const manifest = noChange ? await readNoChangeDelivery(record) : null;
+        if (noChange && manifest === null)
+            throw error("WORKTREE_CHILD_EMPTY", `Child ${record.name} has no committed delivery.`);
+        if (coordinator.runId !== undefined &&
+            (record.runId !== coordinator.runId || record.workerId === undefined || record.ownerSessionId === undefined || record.workerGeneration === undefined ||
+                (coordinator.coordinatorId !== undefined && record.coordinatorId !== coordinator.coordinatorId))) {
+            throw error("WORKTREE_CHILD_RUN_OWNERSHIP", `Child ${record.name} is not explicitly registered to run ${coordinator.runId}.`);
+        }
+        if (manifest !== null && (manifest.runId !== coordinator.runId || manifest.workerId !== record.workerId || manifest.generation !== record.workerGeneration || manifest.sourceCommit !== head)) {
+            throw error("WORKTREE_NO_CHANGE_OWNERSHIP", `Child ${record.name} no-change manifest does not match its registered worker and source.`);
+        }
+        const childConfig = await deps.loadConfig(record.path);
+        if (calculateConfigHash(childConfig) !== configHash) {
+            throw error("WORKTREE_CHILD_CONFIG_CHANGED", `Child ${record.name} uses a different verifier policy.`);
+        }
+        const tasks = await deps.tasks(record.path).list();
+        const roots = tasks.filter(({ task }) => task.parentTaskId === undefined);
+        if (roots.length !== 1 || tasks.some(record => record.status === "archived" && record.supersededBy === undefined)) {
+            throw error("WORKTREE_CHILD_TASK_INVALID", `Child ${record.name} must deliver one active task tree.`);
+        }
+        const suppliedScope = manifest === null ? undefined : parseNoChangeReviewScope(manifest.reviewScope);
+        const scope = manifest === null
+            ? await resolveReviewScope({ root: record.path, runner: runner(deps, record.path), base: record.base })
+            : await resolveReviewScope({ root: record.path, runner: runner(deps, record.path), base: head,
+                noChangePaths: suppliedScope.changedFiles });
+        const fingerprint = await calculateSourceFingerprint(record.path, scope, runner(deps, record.path));
+        for (const task of tasks) {
+            if (task.supersededBy !== undefined)
+                continue;
+            if (task.task.intent === undefined || task.task.intent.trim() === "") {
+                throw error("WORKTREE_CHILD_INTENT_MISSING", `Child task ${task.task.id} needs its pre-work modification intent.`);
+            }
+            const problem = await checkTaskVerificationEvidence(task, {
+                root: record.path, config: childConfig, sourceFingerprint: fingerprint,
+                evidenceStore: new FileEvidenceStore(record.path, record.path)
+            });
+            if (problem !== null) {
+                throw error("WORKTREE_CHILD_UNVERIFIED", `Child task ${task.task.id}: ${problem.remedy}`);
+            }
+        }
+        deliveries.push({
+            record,
+            head,
+            tasks,
+            kind: noChange ? "no-change" : "changed",
+            sourceArtifacts: manifest?.artifactRefs ?? [],
+            reviewScope: manifest?.reviewScope ?? null,
+            deliveryDigest: manifest?.deliveryDigest ?? null,
+            contractDigest: manifest?.contractDigest ?? null,
+            runId: manifest?.runId ?? record.runId ?? null,
+            workerId: manifest?.workerId ?? record.workerId ?? null,
+            workerGeneration: manifest?.generation ?? record.workerGeneration ?? null
+        });
+    }
+    if (deliveries.length === 0)
+        return integrated;
+    const before = await git(deps, coordinator.path, ["rev-parse", "HEAD"]);
+    const expectedTarget = await git(deps, coordinator.mainRoot, ["rev-parse", "--verify", `${coordinator.targetBranch}^{commit}`]);
+    const priorJournal = await readJournal(coordinator);
+    if (priorJournal !== null && priorJournal.status !== "rolled-back" &&
+        priorJournal.expectedTarget !== expectedTarget && priorJournal.status !== "recorded") {
+        throw error("WORKTREE_INTEGRATION_TARGET_MOVED", "The integration target moved while a journal is pending; re-run final proof.");
+    }
+    let journal = priorJournal !== null && priorJournal.status !== "rolled-back"
+        ? priorJournal
+        : {
+            schemaVersion: 1,
+            transactionId: `integration-${randomUUID()}`,
+            expectedTarget,
+            coordinatorBefore: before,
+            status: "prepared",
+            steps: [],
+            updatedAt: new Date().toISOString()
+        };
+    await writeJournal(coordinator, journal);
+    if ((await collectChangeSurface(runner(deps, coordinator.path))).paths.length > 0) {
+        throw error("WORKTREE_DIRTY", "Commit the candidate worktree before integrating children.");
+    }
+    try {
+        for (const delivery of deliveries) {
+            const priorStep = journal.steps.find((step) => step.name === delivery.record.name);
+            if (priorStep !== undefined && priorStep.commit !== delivery.head)
+                throw error("WORKTREE_CHILD_MOVED", `Child ${delivery.record.name} changed after its journaled delivery.`);
+            if (priorStep?.status === "recorded")
+                continue;
+            const step = {
+                name: delivery.record.name,
+                commit: delivery.head,
+                kind: delivery.kind,
+                status: "prepared",
+                taskIds: delivery.tasks.map(({ task }) => task.id),
+                sourceArtifacts: delivery.sourceArtifacts,
+                reviewScope: delivery.reviewScope,
+                deliveryDigest: delivery.deliveryDigest,
+                contractDigest: delivery.contractDigest
+            };
+            journal = { ...journal, status: "merging", steps: [...journal.steps.filter((candidate) => candidate.name !== delivery.record.name), step], updatedAt: new Date().toISOString() };
+            await writeJournal(coordinator, journal);
+            if (delivery.kind === "changed" && (await deps.git(coordinator.path, ["merge-base", "--is-ancestor", delivery.head, "HEAD"])).exitCode !== 0) {
+                const merge = await deps.git(coordinator.path, ["merge", "--no-ff", "--no-edit", delivery.head]);
+                if (merge.exitCode !== 0) {
+                    const files = (await deps.git(coordinator.path, ["diff", "--name-only", "--diff-filter=U"])).stdout.trim();
+                    await deps.git(coordinator.path, ["merge", "--abort"]);
+                    throw error("WORKTREE_INTEGRATION_CONFLICT", `Child ${delivery.record.name} conflicts in ${files || "unknown files"}. Resolve both recorded intents before retrying.`);
+                }
+            }
+            if (await git(deps, delivery.record.path, ["rev-parse", "HEAD"]) !== delivery.head) {
+                throw error("WORKTREE_CHILD_MOVED", `Child ${delivery.record.name} moved during integration.`);
+            }
+            journal = {
+                ...journal,
+                status: "merging",
+                steps: journal.steps.map((candidate) => candidate.name === delivery.record.name ? { ...candidate, status: "merged" } : candidate),
+                updatedAt: new Date().toISOString()
+            };
+            await writeJournal(coordinator, journal);
+        }
+        journal = { ...journal, status: "importing", updatedAt: new Date().toISOString() };
+        await writeJournal(coordinator, journal);
+        for (const delivery of deliveries)
+            await copyDeliveryHistory(delivery.record, coordinator, delivery.tasks);
+        await deps.tasks(coordinator.path).importDelivery(parentTaskId, deliveries.flatMap(({ tasks }) => tasks));
+        for (const delivery of deliveries) {
+            if (delivery.sourceArtifacts.length > 0) {
+                const manifest = await readPrivateFile(deliveryPath(delivery.record), delivery.record.path);
+                if (manifest !== null) {
+                    await mkdir(join(coordinator.path, ".agent-ops", "tasks", "deliveries"), { recursive: true });
+                    await writePrivateFile(deliveryArchivePath(coordinator, delivery.record), manifest, coordinator.path);
+                }
+            }
+        }
+        journal = { ...journal, status: "recorded", steps: journal.steps.map((step) => ({ ...step, status: "recorded" })), updatedAt: new Date().toISOString() };
+        await writeJournal(coordinator, journal);
+        const next = [...integrated, ...deliveries.map(({ record, head, tasks, kind, sourceArtifacts, reviewScope, deliveryDigest, contractDigest, runId, workerId, workerGeneration }) => ({
+                name: record.name,
+                commit: head,
+                taskIds: tasks.map(({ task }) => task.id),
+                ...(kind === "no-change" ? {
+                    deliveryKind: kind,
+                    ...(sourceArtifacts.length === 0 ? {} : { sourceArtifacts }),
+                    ...(reviewScope === null ? {} : { reviewScope }),
+                    ...(deliveryDigest === null ? {} : { deliveryDigest }),
+                    ...(contractDigest === null ? {} : { contractDigest }),
+                    ...(runId === null ? {} : { runId }),
+                    ...(workerId === null ? {} : { workerId }),
+                    ...(workerGeneration === null ? {} : { workerGeneration })
+                } : {
+                    ...(runId === null ? {} : { runId }),
+                    ...(workerId === null ? {} : { workerId }),
+                    ...(workerGeneration === null ? {} : { workerGeneration })
+                })
+            }))];
+        await writePrivateFile(markerPath(coordinator), `${JSON.stringify(next, null, 2)}\n`, coordinator.path);
+        return next;
+    }
+    catch (failure) {
+        await deps.git(coordinator.path, ["merge", "--abort"]);
+        await deps.git(coordinator.path, ["reset", "--hard", before]);
+        await writeJournal(coordinator, { ...journal, status: "rolled-back", updatedAt: new Date().toISOString() });
+        throw failure;
+    }
+}
+/** Preserve immutable local proof for historical review; import never promotes it to final proof. */
+async function copyDeliveryHistory(child, coordinator, tasks) {
+    const source = new FileEvidenceStore(child.path, child.path);
+    const target = new FileEvidenceStore(coordinator.path, coordinator.path);
+    const references = new Set(tasks.flatMap(record => [record.evidence,
+        ...(record.revisions ?? []).map(revision => revision.previousEvidence)].flatMap(evidence => Object.values(evidence).flat())));
+    for (const reference of references) {
+        if (reference.startsWith("review:"))
+            continue;
+        const checked = validateEvidence(await source.load(reference));
+        if (!checked.ok || !tasks.some(record => record.task.id === checked.value.taskId))
+            throw error("WORKTREE_CHILD_HISTORY_INVALID", "Historical evidence must resolve to the delivered task tree.");
+        const saved = await target.save(checked.value);
+        if (saved !== reference)
+            throw error("WORKTREE_CHILD_HISTORY_INVALID", "Historical evidence has a noncanonical identity.");
+        const artifact = checked.value.acceptance?.executionArtifact;
+        if (artifact === undefined)
+            continue;
+        const content = await readPrivateFile(join(child.path, artifact), child.path);
+        if (content === null || Buffer.byteLength(content) > 4 * 1024 * 1024 ||
+            artifact !== ".agent-ops/tasks/acceptance/" + sha256(content) + ".json")
+            throw error("WORKTREE_CHILD_HISTORY_INVALID", "Acceptance execution history is missing or changed.");
+        const destination = join(coordinator.path, artifact);
+        const existing = await readPrivateFile(destination, coordinator.path);
+        if (existing !== null && existing !== content)
+            throw error("WORKTREE_CHILD_HISTORY_INVALID", "Acceptance artifact collision.");
+        if (existing === null)
+            await writePrivateFile(destination, content, coordinator.path);
+    }
+    const directory = join(child.path, REVIEW_ATTESTATION_DIRECTORY);
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (cause) {
+        if (cause.code !== "ENOENT")
+            throw cause;
+        names = [];
+    }
+    for (const name of names.filter(name => /^[a-f0-9]{64}\.[a-z][a-z0-9-]{0,127}\.reports\.json$/u.test(name))) {
+        const content = await readPrivateFile(join(directory, name), child.path);
+        if (content === null || Buffer.byteLength(content) > 512 * 1024)
+            continue;
+        let value;
+        try {
+            value = JSON.parse(content);
+        }
+        catch {
+            continue;
+        }
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            continue;
+        const artifact = value;
+        if (artifact.status !== "FAIL" || !tasks.some(task => task.task.id === artifact.taskId) ||
+            name !== artifact.sourceFingerprint + "." + artifact.taskId + ".reports.json")
+            continue;
+        const destination = join(coordinator.path, REVIEW_ATTESTATION_DIRECTORY, name);
+        const existing = await readPrivateFile(destination, coordinator.path);
+        if (existing !== null && existing !== content)
+            throw error("WORKTREE_CHILD_HISTORY_INVALID", "Failed review history collision.");
+        if (existing === null)
+            await writePrivateFile(destination, content, coordinator.path);
+    }
+}

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

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { collectChangeSurface } from "../verify/change-surface.js";
-import { assertSessionId, assertWorktreeName, bindSession, insideWorktreeDirectory, parseWorktreeListPorcelain, readWorktreeRecord, removeCheckout, resolveCheckouts, worktreePath, writeWorktreeRecord } from "./service.js";
+import { assertSessionId, assertWorktreeName, bindSession, insideWorktreeDirectory, parseWorktreeListPorcelain, readWorktreeRecord, assertRunWorktreeOwnership, removeCheckout, resolveCheckouts, worktreePath, writeWorktreeRecord } from "./service.js";
 /**
  * A baseline no source state hashes to. A resumed session inherits whatever
  * the last one left in the worktree, so none of it counts as "unchanged".
@@ -180,6 +180,9 @@ export async function commitWorktree(deps, options) {
     if (record.sessionId !== options.sessionId) {
         throw manageError("WORKTREE_COMMIT_FOREIGN", `${record.path} belongs to session ${record.sessionId}, not ${options.sessionId}.`);
     }
+    if (options.runOwnership !== undefined) {
+        assertRunWorktreeOwnership(record, options.runOwnership);
+    }
     const step = async (args, code, message) => {
         const result = await deps.git(record.path, args);
         if (result.exitCode !== 0) {

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

@@ -0,0 +1,153 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { findReviewAttestation, readReviewReportArtifact, REVIEW_ATTESTATION_DIRECTORY } from "../review/attestation.js";
+import { resolveReviewScope } from "../review/scope.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { checkTaskCompletionEvidence } from "../task/completion.js";
+import { FileEvidenceStore } from "../verify/evidence.js";
+import { validateEvidence } from "../schema/validate.js";
+import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
+import { validateRunIntegrationReceipt } from "../run/integration.js";
+function seal(value) {
+    return { digest: sha256(JSON.stringify(value)), value };
+}
+function validSeal(value) {
+    return value.digest === sha256(JSON.stringify(value.value));
+}
+function receiptPath(commonDir, record, head) {
+    return join(commonDir, "agent-ops", "receipts", `${sha256(record.sessionId)}-${head}.json`);
+}
+/** Complete local proof is copied into the Git common directory before the branch moves. */
+export async function prepareFinishReceipt(options) {
+    const { record, candidateHead, targetCommit, tasks, config } = options;
+    if (options.integrationJournal !== undefined) {
+        validateRunIntegrationReceipt(options.integrationJournal, {
+            candidateHead, targetCommit, integrationJournal: options.integrationJournal
+        });
+    }
+    const scope = options.noChange?.reviewScope ?? await resolveReviewScope({ root: record.path, runner: options.gitRunner, base: targetCommit });
+    if (options.noChange !== undefined && options.noChange.sourceCommit !== candidateHead) {
+        throw new AgentOpsError("WORKTREE_NO_CHANGE_SOURCE_MISMATCH", "Verified-no-change receipt must pin the current candidate commit.");
+    }
+    const sourceFingerprint = await calculateSourceFingerprint(record.path, scope, options.gitRunner);
+    if (sourceFingerprint !== options.expectedFingerprint) {
+        throw new AgentOpsError("WORKTREE_FINAL_SOURCE_CHANGED", "The final candidate no longer matches the reviewed fingerprint.");
+    }
+    const evidenceStore = new FileEvidenceStore(record.path, record.path);
+    const verification = {};
+    const executionArtifacts = {};
+    const reviews = {};
+    const residualRisks = new Set();
+    const modes = new Set();
+    for (const task of tasks) {
+        const problem = await checkTaskCompletionEvidence(task, {
+            root: record.path, config, sourceFingerprint, evidenceStore
+        });
+        if (problem !== null) {
+            throw new AgentOpsError("WORKTREE_FINAL_EVIDENCE_MISSING", `Task ${task.task.id}: ${problem.remedy}`);
+        }
+        for (const references of [task.evidence, ...(task.revisions ?? []).map(revision => revision.previousEvidence)]
+            .flatMap(evidence => Object.values(evidence))) {
+            for (const reference of references) {
+                if (reference.startsWith("review:"))
+                    continue;
+                const value = await evidenceStore.load(reference);
+                if (value === null)
+                    throw new AgentOpsError("WORKTREE_FINAL_EVIDENCE_MISSING", `Missing ${reference}.`);
+                verification[reference] = seal(value);
+                const checked = validateEvidence(value);
+                if (!checked.ok)
+                    throw new AgentOpsError("WORKTREE_FINAL_EVIDENCE_MISSING", "Historical verification evidence is invalid.");
+                const artifact = checked.value.acceptance?.executionArtifact;
+                if (artifact !== undefined) {
+                    const content = await readPrivateFile(join(record.path, artifact), record.path);
+                    if (content === null || Buffer.byteLength(content) > 4 * 1024 * 1024 ||
+                        artifact !== ".agent-ops/tasks/acceptance/" + sha256(content) + ".json")
+                        throw new AgentOpsError("WORKTREE_FINAL_EVIDENCE_MISSING", "Paired execution artifact is missing or changed.");
+                    executionArtifacts[artifact] = seal(content);
+                }
+            }
+        }
+        const attestation = await findReviewAttestation(record.path, sourceFingerprint, task.task.id);
+        const report = await readReviewReportArtifact(record.path, sourceFingerprint, task.task.id);
+        if (attestation === null || report === null || report.status !== "PASS" || report.taskId !== task.task.id) {
+            throw new AgentOpsError("WORKTREE_FINAL_EVIDENCE_MISSING", `Missing review for ${task.task.id}.`);
+        }
+        modes.add(attestation.tree === undefined ? "per-task-fallback" : "tree");
+        for (const risk of [...(report.report?.residualRisks ?? []), ...(report.adversarial?.report.residualRisks ?? [])]) {
+            residualRisks.add(risk);
+        }
+        reviews[task.task.id] = { attestation: seal(attestation), report: seal(report) };
+    }
+    if (modes.size !== 1 || (modes.has("tree") && new Set(Object.values(reviews)
+        .map(({ attestation }) => JSON.stringify(attestation.value.tree))).size !== 1)) {
+        throw new AgentOpsError("WORKTREE_FINAL_REVIEW_MISMATCH", "Final tasks do not share one complete review mode and tree scope.");
+    }
+    const historicalReviews = {};
+    let names;
+    try {
+        names = await readdir(join(record.path, REVIEW_ATTESTATION_DIRECTORY));
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            names = [];
+        else
+            throw cause;
+    }
+    for (const name of names.filter(name => /^[a-f0-9]{64}\.[a-z][a-z0-9-]{0,127}\.reports\.json$/u.test(name))) {
+        const path = REVIEW_ATTESTATION_DIRECTORY + "/" + name;
+        const content = await readPrivateFile(join(record.path, path), record.path);
+        if (content === null || Buffer.byteLength(content) > 512 * 1024)
+            continue;
+        let artifact;
+        try {
+            artifact = JSON.parse(content);
+        }
+        catch {
+            continue;
+        }
+        if (artifact === null || typeof artifact !== "object" || artifact.status !== "FAIL" ||
+            !tasks.some(task => task.task.id === artifact.taskId) ||
+            name !== artifact.sourceFingerprint + "." + artifact.taskId + ".reports.json")
+            continue;
+        historicalReviews[path] = seal(content);
+    }
+    const receipt = {
+        schemaVersion: 1,
+        sessionId: record.sessionId,
+        candidateHead,
+        targetCommit,
+        sourceFingerprint,
+        reviewMode: modes.has("tree") ? "tree" : "per-task-fallback",
+        tasks,
+        children: options.children,
+        verification,
+        executionArtifacts,
+        historicalReviews,
+        reviews,
+        residualRisks: [...residualRisks],
+        createdAt: new Date().toISOString(),
+        ...(options.noChange === undefined ? {} : {
+            noChange: {
+                sourceCommit: options.noChange.sourceCommit,
+                contractDigest: options.noChange.contractDigest,
+                reviewScope: JSON.stringify(options.noChange.reviewScope),
+                artifactRefs: options.noChange.artifactRefs
+            }
+        }),
+        ...(options.integrationJournal === undefined ? {} : { integrationJournal: options.integrationJournal })
+    };
+    const content = `${JSON.stringify(receipt, null, 2)}\n`;
+    const path = receiptPath(options.commonDir, record, candidateHead);
+    await writePrivateFile(path, content, options.commonDir);
+    const reread = await readPrivateFile(path, options.commonDir);
+    if (reread !== content || Object.values(verification).some((item) => !validSeal(item)) ||
+        Object.values(executionArtifacts).some(item => !validSeal(item)) ||
+        Object.values(historicalReviews).some(item => !validSeal(item)) ||
+        Object.values(reviews).some(({ attestation, report }) => !validSeal(attestation) || !validSeal(report))) {
+        throw new AgentOpsError("WORKTREE_RECEIPT_INVALID", "The local finish receipt could not be read back intact.");
+    }
+    return { path, digest: sha256(content), receipt };
+}