@zq-silk/yui 0.6.0 → 0.6.2

package/dist/integration/gitIntegrationService.js

@@ -5,13 +5,19 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { selectEnvironment } from "../agent/launchEnvironment.js";
 import { controllerSocketPath } from "../core/controllerEndpoint.js";
+import { planBootstrapJobSteps, planL2JobSteps } from "../verification/verificationPlan.js";
+import { assertNoAdHocFullSuiteChecks, checkResultsFromGateArtifact, checkResultsFromGateJob, gateIdentityForCandidate, lookupReusableGateArtifact, recordGateArtifactFromJob, recordGateArtifactFromStepOutcomes, resolveVerificationGate, runGateStepsInProcess } from "../verification/verificationGateService.js";
+import { recordGateArtifactPotentialReuse, recordGateArtifactReuse } from "../verification/gateArtifact.js";
+import { touchGateArtifact } from "../verification/gateArtifactStore.js";
 import { NodeGitWorkspace, RemoteBaselineConflictError } from "../repository/gitWorkspace.js";
 import { resolveWorktreeRoot } from "../repository/taskWorkspacePreparer.js";
+import { acquireProjectMaintenanceLocks } from "../repository/projectMaintenanceLock.js";
 import { taskWorkspaceRefSegment } from "../repository/taskWorkspaceIdentity.js";
 import { FileTaskRuntimeIsolation } from "../runtime/taskRuntimeIsolation.js";
 import { yuiTmuxServerName } from "../tmux/tmuxManager.js";
-import { requireLeaderDecision, updateIntegrationAttempt } from "./integrationAttempt.js";
+import { recordIntegrationCheckJob, requireLeaderDecision, updateIntegrationAttempt } from "./integrationAttempt.js";
 import { createManagedWorkspace } from "../worktree/managedWorkspace.js";
+import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
 const executeFile = promisify(execFile);
 const INTEGRATION_OPERATIONAL_ENVIRONMENT_NAMES = [
     "PATH",
@@ -47,188 +53,383 @@ export class GitIntegrationService {
     store;
     git;
     now;
+    jobPort;
     home;
     worktreeRoot;
     environment;
     runtimeIsolation;
-    constructor(home, store, git = new NodeGitWorkspace(), now = () => new Date(), environment = process.env, runtimeIsolation = defaultIntegrationRuntimeIsolation(home)) {
+    #resourceRegistrarValue;
+    constructor(home, store, git = new NodeGitWorkspace(), now = () => new Date(), environment = process.env, runtimeIsolation = defaultIntegrationRuntimeIsolation(home), jobPort) {
         this.store = store;
         this.git = git;
         this.now = now;
+        this.jobPort = jobPort;
         this.home = resolve(home);
         this.worktreeRoot = resolveWorktreeRoot(home, store.getConfig().defaultWorkspace);
         this.environment = { ...environment };
         this.runtimeIsolation = runtimeIsolation;
     }
+    #resourceRegistrar() {
+        return this.#resourceRegistrarValue ??= new ResourceRegistrar(this.home, this.now);
+    }
     async integrate(taskId, integrationId, options = {}) {
         const initial = requireIntegration(this.store, taskId, integrationId);
-        const task = this.store.getTask(initial.taskId);
-        if (task === null || !task.projectBindings.some(({ projectId }) => projectId === initial.projectId)) {
-            throw new Error(`Integration Task Project is unavailable: ${initial.taskId}.`);
-        }
-        if (task.status !== "active") {
-            throw new Error(`Integration Task is not active: ${task.id}/${task.status}.`);
-        }
-        const project = this.store.getProject(initial.projectId);
-        if (project === null)
-            throw new Error(`Project not found: ${initial.projectId}.`);
-        let prepared;
-        let workspace;
-        let managedWorkspace;
-        try {
-            prepared = await this.git.ensureIntegrationWorktree({
-                repositoryPath: project.path,
-                container: join(this.worktreeRoot, project.name),
-                taskSegment: taskWorkspaceRefSegment(task),
-                integrationId: initial.id,
-                baseRef: initial.expectedHead
-            });
-            workspace = {
-                projectId: project.id,
-                path: prepared.path,
-                branch: prepared.branch,
-                baseCommit: prepared.baseCommit
-            };
-            const existingWorkspace = this.store.getIntegrationWorkspace(task.id, initial.id);
-            managedWorkspace = existingWorkspace ?? createManagedWorkspace({
-                owner: {
-                    type: "integration-attempt",
-                    taskId: task.id,
-                    integrationAttemptId: initial.id
-                },
-                root: prepared.path,
-                entries: [{
-                        projectId: project.id,
-                        directory: project.name,
-                        access: "write",
-                        path: prepared.path,
-                        branch: prepared.branch,
-                        baseRef: initial.expectedHead,
-                        baseCommit: prepared.baseCommit
-                    }]
-            }, this.now());
-            this.store.saveManagedWorkspace(managedWorkspace);
-        }
-        catch (error) {
-            return this.#fail(initial, error, "integration-preparation");
-        }
-        if (initial.status === "validating") {
-            return this.#recoverValidating(initial, workspace, project.path);
-        }
-        let current = initial;
+        // The whole Integration is one Git transaction against the Project's
+        // repository: worktree creation, cherry-picks, checks, and the target ref
+        // CAS. A concurrent `project migrate` must not switch the catalog path or
+        // remove the old checkout mid-Integration, so the per-Project maintenance
+        // fence is held across every Git effect and released only on exit.
+        const release = acquireProjectMaintenanceLocks(this.home, [initial.projectId]);
         try {
-            if (options.remoteBaseline !== undefined) {
-                const mergeRemote = this.git.mergeRemoteIntoWorktree;
-                if (mergeRemote === undefined) {
-                    throw new Error("Integration Git workspace does not support remote baseline reconciliation.");
-                }
-                await mergeRemote.call(this.git, {
-                    repositoryPath: prepared.path,
-                    remoteUrl: options.remoteBaseline.remoteUrl,
-                    branch: options.remoteBaseline.branch
+            const task = this.store.getTask(initial.taskId);
+            if (task === null || !task.projectBindings.some(({ projectId }) => projectId === initial.projectId)) {
+                throw new Error(`Integration Task Project is unavailable: ${initial.taskId}.`);
+            }
+            if (task.status !== "active") {
+                throw new Error(`Integration Task is not active: ${task.id}/${task.status}.`);
+            }
+            const project = this.store.getProject(initial.projectId);
+            if (project === null)
+                throw new Error(`Project not found: ${initial.projectId}.`);
+            // Issue 08: a Project with a VerificationPlan gates through its plan
+            // (bootstrap + L2) and reuses exact-SHA artifacts; an unconfigured
+            // Project keeps the existing explicit check path unchanged.
+            const gate = resolveVerificationGate(project, this.environment);
+            let prepared;
+            let workspace;
+            let managedWorkspace;
+            try {
+                prepared = await this.git.ensureIntegrationWorktree({
+                    repositoryPath: project.path,
+                    container: join(this.worktreeRoot, project.name),
+                    taskSegment: taskWorkspaceRefSegment(task),
+                    integrationId: initial.id,
+                    baseRef: initial.expectedHead
                 });
+                workspace = {
+                    projectId: project.id,
+                    path: prepared.path,
+                    branch: prepared.branch,
+                    baseCommit: prepared.baseCommit
+                };
+                const existingWorkspace = this.store.getIntegrationWorkspace(task.id, initial.id);
+                managedWorkspace = existingWorkspace ?? createManagedWorkspace({
+                    owner: {
+                        type: "integration-attempt",
+                        taskId: task.id,
+                        integrationAttemptId: initial.id
+                    },
+                    root: prepared.path,
+                    entries: [{
+                            projectId: project.id,
+                            directory: project.name,
+                            access: "write",
+                            path: prepared.path,
+                            branch: prepared.branch,
+                            baseRef: initial.expectedHead,
+                            baseCommit: prepared.baseCommit
+                        }]
+                }, this.now());
+                this.#resourceRegistrar().registerManagedWorkspace(managedWorkspace);
+                this.store.saveManagedWorkspace(managedWorkspace);
             }
-            // A remote-baseline Attempt starts from the exact previously committed
-            // Task head, so its ChangeSets are already represented by that tree.
-            // Keep their IDs as provenance/check evidence, but never cherry-pick the
-            // source commits again. A manual continuation of a remote merge carries
-            // the same semantic marker in its conflict report.
-            const remoteOnly = options.remoteBaseline !== undefined
-                || (current.resolution?.action === "manual-resolution"
-                    && current.conflict?.summary.startsWith(REMOTE_BASELINE_CONFLICT_PREFIX));
-            const plan = remoteOnly
-                ? []
-                : await integrationCommitPlan(this.store, task.id, project.path, current.changeSetIds, current.expectedHead);
-            let remaining = plan;
-            if (current.resolution?.action === "manual-resolution"
-                && current.conflict?.summary.startsWith(REMOTE_BASELINE_CONFLICT_PREFIX)) {
-                await completeRemoteBaselineResolution(prepared.path);
+            catch (error) {
+                return this.#fail(initial, error, "integration-preparation");
             }
-            else if (current.resolution?.action === "manual-resolution") {
-                const resolvedCommit = await completeManualResolution(prepared.path);
-                const resolvedIndex = plan.findIndex(({ commit }) => commit === resolvedCommit);
-                if (resolvedIndex < 0) {
-                    throw new Error(`Manual resolution commit is not part of the Integration plan: ${resolvedCommit}.`);
-                }
-                remaining = plan.slice(resolvedIndex + 1);
+            if (initial.status === "validating") {
+                return this.#recoverValidating(initial, workspace, project.path);
             }
-            const conflict = await this.#applyCommits(current, workspace, prepared.path, remaining);
-            if (conflict !== undefined) {
-                return conflict;
+            let current = initial;
+            // A check DurableJob is the source of truth for a running attempt that
+            // already bound one: never re-apply commits or spawn a second job. The
+            // job's terminal wakeup drives the resume through `integration continue`.
+            if (current.status === "running" && current.jobId !== undefined) {
+                return this.#resumeCheckJob(current, workspace, prepared.path, project.path, gate);
             }
-            const checkResults = await this.#runChecks(current, managedWorkspace, prepared.path);
-            if (checkResults.some((check) => check.outcome === "failed")) {
+            try {
+                if (options.remoteBaseline !== undefined) {
+                    const mergeRemote = this.git.mergeRemoteIntoWorktree;
+                    if (mergeRemote === undefined) {
+                        throw new Error("Integration Git workspace does not support remote baseline reconciliation.");
+                    }
+                    await mergeRemote.call(this.git, {
+                        repositoryPath: prepared.path,
+                        remoteUrl: options.remoteBaseline.remoteUrl,
+                        branch: options.remoteBaseline.branch
+                    });
+                }
+                // A remote-baseline Attempt starts from the exact previously committed
+                // Task head, so its ChangeSets are already represented by that tree.
+                // Keep their IDs as provenance/check evidence, but never cherry-pick the
+                // source commits again. A manual continuation of a remote merge carries
+                // the same semantic marker in its conflict report.
+                const remoteOnly = options.remoteBaseline !== undefined
+                    || (current.resolution?.action === "manual-resolution"
+                        && current.conflict?.summary.startsWith(REMOTE_BASELINE_CONFLICT_PREFIX));
+                const plan = remoteOnly
+                    ? []
+                    : await integrationCommitPlan(this.store, task.id, project.path, current.changeSetIds, current.expectedHead);
+                let remaining = plan;
+                if (current.resolution?.action === "manual-resolution"
+                    && current.conflict?.summary.startsWith(REMOTE_BASELINE_CONFLICT_PREFIX)) {
+                    await completeRemoteBaselineResolution(prepared.path);
+                }
+                else if (current.resolution?.action === "manual-resolution") {
+                    const resolvedCommit = await completeManualResolution(prepared.path);
+                    const resolvedIndex = plan.findIndex(({ commit }) => commit === resolvedCommit);
+                    if (resolvedIndex < 0) {
+                        throw new Error(`Manual resolution commit is not part of the Integration plan: ${resolvedCommit}.`);
+                    }
+                    remaining = plan.slice(resolvedIndex + 1);
+                }
+                const conflict = await this.#applyCommits(current, workspace, prepared.path, remaining);
+                if (conflict !== undefined) {
+                    return conflict;
+                }
+                // Static preflight: fail before any expensive check when the target
+                // moved or its worktree is dirty, so the check commands never run on a
+                // target that cannot be advanced.  advanceTargetRef re-verifies both
+                // after the checks, so a move during the gate is still fenced at CAS.
+                await assertTargetReadyForChecks(project.path, current.targetRef, current.expectedHead);
+                if (gate !== undefined) {
+                    return this.#runVerificationGate(current, workspace, prepared.path, managedWorkspace, project.path, gate);
+                }
+                if (this.jobPort !== undefined && current.checkCommands.length > 0) {
+                    return this.#startCheckJob(current, workspace, prepared.path, managedWorkspace, project.path);
+                }
+                const checkedHead = await gitLine(["-C", prepared.path, "rev-parse", "HEAD^{commit}"]);
+                const checkResults = await this.#runChecks(current, managedWorkspace, prepared.path);
+                const afterHead = await gitLine(["-C", prepared.path, "rev-parse", "HEAD^{commit}"]);
+                if (afterHead !== checkedHead) {
+                    return this.#fail(current, new Error(`Integration workspace moved during the checks: ${afterHead} != checked ${checkedHead}.`), "integration", workspace);
+                }
+                if (checkResults.some((check) => check.outcome === "failed")) {
+                    current = updateIntegrationAttempt(current, {
+                        status: "failed",
+                        checks: checkResults
+                    }, this.now());
+                    this.store.saveIntegrationAttempt(task.id, current);
+                    return this.#terminalResult("failed", current, workspace);
+                }
+                const candidateCommit = await gitLine(["-C", prepared.path, "rev-parse", "HEAD^{commit}"]);
                 current = updateIntegrationAttempt(current, {
-                    status: "failed",
+                    status: "validating",
+                    candidateCommit,
                     checks: checkResults
                 }, this.now());
                 this.store.saveIntegrationAttempt(task.id, current);
-                return this.#terminalResult("failed", current, workspace);
+                await advanceTargetRef(project.path, current.targetRef, candidateCommit, current.expectedHead);
+                const committed = updateIntegrationAttempt(current, { status: "committed" }, this.now());
+                this.store.saveIntegrationAttempt(task.id, committed);
+                return this.#terminalResult("committed", committed, workspace);
+            }
+            catch (error) {
+                if (error instanceof RemoteBaselineConflictError) {
+                    const pending = requireLeaderDecision(current, {
+                        affectedPaths: error.affectedPaths,
+                        summary: error.message
+                    }, this.now());
+                    this.store.saveIntegrationAttempt(task.id, pending);
+                    return { status: "blocked", attempt: pending, workspace };
+                }
+                if (current.status === "validating" && current.candidateCommit !== undefined) {
+                    const target = await resolveRef(project.path, current.targetRef);
+                    if (target === current.candidateCommit) {
+                        const committed = updateIntegrationAttempt(current, { status: "committed" }, this.now());
+                        this.store.saveIntegrationAttempt(task.id, committed);
+                        return this.#terminalResult("committed", committed, workspace);
+                    }
+                }
+                return this.#fail(current, error, "integration", workspace);
             }
-            const candidateCommit = await gitLine(["-C", prepared.path, "rev-parse", "HEAD^{commit}"]);
-            current = updateIntegrationAttempt(current, {
-                status: "validating",
-                candidateCommit,
-                checks: checkResults
-            }, this.now());
-            this.store.saveIntegrationAttempt(task.id, current);
-            await advanceTargetRef(project.path, current.targetRef, candidateCommit, current.expectedHead);
-            const committed = updateIntegrationAttempt(current, { status: "committed" }, this.now());
-            this.store.saveIntegrationAttempt(task.id, committed);
-            return this.#terminalResult("committed", committed, workspace);
         }
-        catch (error) {
-            if (error instanceof RemoteBaselineConflictError) {
-                const pending = requireLeaderDecision(current, {
-                    affectedPaths: error.affectedPaths,
-                    summary: error.message
-                }, this.now());
-                this.store.saveIntegrationAttempt(task.id, pending);
-                return { status: "blocked", attempt: pending, workspace };
+        finally {
+            release();
+        }
+    }
+    async cleanup(integration) {
+        // The whole cleanup is one Git transaction against the Project's
+        // repository, mirroring integrate(): a concurrent `project migrate` must
+        // not switch the catalog path or remove the old checkout mid-cleanup.
+        const release = acquireProjectMaintenanceLocks(this.home, [integration.projectId]);
+        try {
+            const task = this.store.getTask(integration.taskId);
+            if (task === null || !task.projectBindings.some(({ projectId }) => projectId === integration.projectId)) {
+                throw new Error(`Integration Task Project is unavailable: ${integration.id}.`);
+            }
+            const project = this.store.getProject(integration.projectId);
+            if (project === null)
+                throw new Error(`Project not found: ${integration.projectId}.`);
+            const managedWorkspace = this.store.getIntegrationWorkspace(integration.taskId, integration.id);
+            if (managedWorkspace !== null) {
+                const runtime = this.#runtimePreparation(integration, managedWorkspace);
+                this.runtimeIsolation.cleanup(runtime, integration.status === "committed" ? "completion" : "failure");
             }
-            if (current.status === "validating" && current.candidateCommit !== undefined) {
-                const target = await resolveRef(project.path, current.targetRef);
-                if (target === current.candidateCommit) {
-                    const committed = updateIntegrationAttempt(current, { status: "committed" }, this.now());
-                    this.store.saveIntegrationAttempt(task.id, committed);
-                    return this.#terminalResult("committed", committed, workspace);
+            const result = await this.git.removeIntegrationWorktree({
+                repositoryPath: project.path,
+                container: join(this.worktreeRoot, project.name),
+                taskSegment: taskWorkspaceRefSegment(task),
+                integrationId: integration.id,
+                discardChanges: integration.status === "failed"
+            });
+            if (result !== "dirty") {
+                if (managedWorkspace !== null) {
+                    this.#resourceRegistrar().markWorkspaceDeleted(managedWorkspace);
                 }
+                await rm(integrationCheckDirectory(this.home, task.id, integration.id), {
+                    recursive: true,
+                    force: true
+                });
+                this.store.removeManagedWorkspace({
+                    type: "integration-attempt",
+                    taskId: integration.taskId,
+                    integrationAttemptId: integration.id
+                });
             }
-            return this.#fail(current, error, "integration", workspace);
+            return result;
+        }
+        finally {
+            release();
         }
     }
-    async cleanup(integration) {
-        const task = this.store.getTask(integration.taskId);
-        if (task === null || !task.projectBindings.some(({ projectId }) => projectId === integration.projectId)) {
-            throw new Error(`Integration Task Project is unavailable: ${integration.id}.`);
+    /**
+     * Hand the check commands to a Controller-owned DurableJob. The job runs
+     * the same isolated environment the in-process checks used; the attempt
+     * stays `running` with its jobId until the job's terminal wakeup resumes
+     * it, so a Leader exit mid-checks leaves no running/no-check zombie.
+     */
+    async #startCheckJob(attempt, workspace, path, managedWorkspace, repositoryPath, gate) {
+        const runtime = this.#runtimePreparation(attempt, managedWorkspace);
+        this.runtimeIsolation.activate(runtime);
+        const environment = await integrationCheckEnvironment(this.environment, runtime);
+        const head = await gitLine(["-C", path, "rev-parse", "HEAD^{commit}"]);
+        const steps = gate === undefined
+            ? attempt.checkCommands.map((command, index) => ({
+                name: `check-${index + 1}`,
+                command,
+                timeoutMs: 30 * 60_000
+            }))
+            : [
+                ...planBootstrapJobSteps(gate.plan).map((step) => ({
+                    ...step,
+                    timeoutMs: 30 * 60_000
+                })),
+                ...planL2JobSteps(gate.plan).map((step) => ({
+                    ...step,
+                    timeoutMs: 30 * 60_000
+                }))
+            ];
+        // Persist the gate identity before starting the job so a plan edit
+        // during the gate never misattributes the evidence on resume.
+        let persisted = attempt;
+        if (gate !== undefined) {
+            persisted = updateIntegrationAttempt(attempt, {
+                gatePlanDigest: gate.planDigest,
+                gateToolchainDigest: gate.toolchainDigest
+            }, this.now());
+            this.store.saveIntegrationAttempt(attempt.taskId, persisted);
         }
-        const project = this.store.getProject(integration.projectId);
-        if (project === null)
-            throw new Error(`Project not found: ${integration.projectId}.`);
-        const managedWorkspace = this.store.getIntegrationWorkspace(integration.taskId, integration.id);
+        const job = await this.jobPort.startCheckJob({
+            taskId: attempt.taskId,
+            integrationId: attempt.id,
+            projectId: attempt.projectId,
+            head,
+            workspace: path,
+            env: environment,
+            steps
+        });
+        const bound = recordIntegrationCheckJob(persisted, job.id, this.now());
+        this.store.saveIntegrationAttempt(attempt.taskId, bound);
+        if (job.status !== "queued" && job.status !== "running") {
+            // Idempotent re-entry after a Leader exit in the bind window: the
+            // Controller returned the already-terminal job. Converge through the
+            // normal resume path instead of a checks-running zombie.
+            return this.#resumeCheckJob(bound, workspace, path, repositoryPath, gate);
+        }
+        return { status: "checks-running", attempt: bound, workspace, job };
+    }
+    /**
+     * Resume a running attempt whose check job is already bound. An active job
+     * reports checks-running without side effects; a terminal job finalizes the
+     * attempt through the same validating/committed or failed path as the
+     * in-process checks. `unknown-needs-attention` fails closed: the attempt
+     * fails and the target ref never advances.
+     */
+    async #resumeCheckJob(attempt, workspace, path, repositoryPath, gate) {
+        const job = await this.jobPort.getJob(attempt.taskId, attempt.jobId);
+        if (job.status === "queued" || job.status === "running") {
+            return { status: "checks-running", attempt, workspace, job };
+        }
+        const planStyle = gate !== undefined
+            || (job.steps?.some((step) => step.name.startsWith("bootstrap-") || step.name.startsWith("gate-")) ?? false);
+        const checks = planStyle
+            ? checkResultsFromGateJob(job, this.home)
+            : checkResultsFromJob(attempt, job);
+        const managedWorkspace = this.store.getIntegrationWorkspace(attempt.taskId, attempt.id);
         if (managedWorkspace !== null) {
-            const runtime = this.#runtimePreparation(integration, managedWorkspace);
-            this.runtimeIsolation.cleanup(runtime, integration.status === "committed" ? "completion" : "failure");
+            const runtime = this.#runtimePreparation(attempt, managedWorkspace);
+            this.runtimeIsolation.cleanup(runtime, checks.some((check) => check.outcome === "failed") ? "failure" : "completion");
         }
-        const result = await this.git.removeIntegrationWorktree({
-            repositoryPath: project.path,
-            container: join(this.worktreeRoot, project.name),
-            taskSegment: taskWorkspaceRefSegment(task),
-            integrationId: integration.id,
-            discardChanges: integration.status === "failed"
-        });
-        if (result !== "dirty") {
-            await rm(integrationCheckDirectory(this.home, task.id, integration.id), {
-                recursive: true,
-                force: true
-            });
-            this.store.removeManagedWorkspace({
-                type: "integration-attempt",
-                taskId: integration.taskId,
-                integrationAttemptId: integration.id
+        // Issue 08: record the GateArtifact for a plan-gated attempt. The
+        // identity is recomputed from the current plan and the job's exact
+        // checked head; a plan/toolchain change since the job started yields a
+        // different key, so the artifact is never misattributed (the attempt
+        // still converges from the job's own evidence).
+        if (gate !== undefined
+            && (job.result?.outcome === "succeeded" || job.result?.outcome === "failed")) {
+            // Use the digests captured at job start so a plan edit during the
+            // gate never misattributes the evidence.
+            const recordGate = attempt.gatePlanDigest !== undefined
+                ? Object.freeze({
+                    ...gate,
+                    planDigest: attempt.gatePlanDigest,
+                    toolchainDigest: attempt.gateToolchainDigest ?? gate.toolchainDigest
+                })
+                : gate;
+            const identity = gateIdentityForCandidate({
+                projectId: attempt.projectId,
+                gate: recordGate,
+                level: "L2",
+                commit: job.head,
+                targetRef: attempt.targetRef,
+                baseHead: attempt.expectedHead
             });
+            try {
+                const artifact = await recordGateArtifactFromJob(this.store, this.home, identity, gate.plan, job, this.now());
+                if (checks.every((check) => check.outcome !== "failed")) {
+                    checks.push(...checkResultsFromGateArtifact(artifact));
+                }
+            }
+            catch (error) {
+                // A failed artifact import (e.g. a lost job log) must not fake
+                // evidence: the attempt fails closed without a reusable artifact.
+                return this.#fail(attempt, error instanceof Error ? error : new Error(String(error)), "gate-artifact", workspace);
+            }
+        }
+        if (checks.some((check) => check.outcome === "failed")) {
+            const failed = updateIntegrationAttempt(attempt, {
+                status: "failed",
+                checks
+            }, this.now());
+            this.store.saveIntegrationAttempt(attempt.taskId, failed);
+            return this.#terminalResult("failed", failed, workspace);
+        }
+        const candidateCommit = await gitLine(["-C", path, "rev-parse", "HEAD^{commit}"]);
+        if (candidateCommit !== job.head) {
+            // The job proved the checks at one SHA; the workspace has since moved.
+            // Advancing the target ref would publish unchecked code, so fail closed.
+            return this.#fail(attempt, new Error(`Integration workspace moved since the check ran: ${candidateCommit} != checked ${job.head}.`), "integration", workspace);
         }
-        return result;
+        const validating = updateIntegrationAttempt(attempt, {
+            status: "validating",
+            candidateCommit,
+            checks
+        }, this.now());
+        this.store.saveIntegrationAttempt(attempt.taskId, validating);
+        await advanceTargetRef(repositoryPath, validating.targetRef, candidateCommit, validating.expectedHead);
+        const committed = updateIntegrationAttempt(validating, { status: "committed" }, this.now());
+        this.store.saveIntegrationAttempt(attempt.taskId, committed);
+        return this.#terminalResult("committed", committed, workspace);
     }
     async #runChecks(attempt, workspace, path) {
         if (attempt.checkCommands.length === 0)
@@ -248,6 +449,95 @@ export class GitIntegrationService {
             this.runtimeIsolation.cleanup(runtime, cleanupReason);
         }
     }
+    /**
+     * Issue 08: the VerificationPlan gate for a configured Project.
+     *
+     * Enforce mode rejects ad-hoc full-suite checks before the gate. Reuse mode
+     * returns an existing successful artifact for the same identity tuple
+     * (project + exact commit + plan digest + toolchain digest + target
+     * boundary); record mode always runs and only counts shadow potential
+     * reuses. The gate itself runs as bootstrap + L2 DurableJob steps (or
+     * in-process when no Controller job port is available) and records a
+     * self-contained GateArtifact. The final CAS in
+     * {@link #finalizeGateSuccess} still fences a target that moves during the
+     * gate.
+     */
+    async #runVerificationGate(attempt, workspace, path, managedWorkspace, repositoryPath, gate) {
+        if (gate.mode === "enforce") {
+            try {
+                assertNoAdHocFullSuiteChecks(gate.plan, attempt.checkCommands);
+            }
+            catch (error) {
+                return this.#fail(attempt, error instanceof Error ? error : new Error(String(error)), "verification-plan", workspace);
+            }
+        }
+        const candidateCommit = await gitLine(["-C", path, "rev-parse", "HEAD^{commit}"]);
+        const identity = gateIdentityForCandidate({
+            projectId: attempt.projectId,
+            gate,
+            level: "L2",
+            commit: candidateCommit,
+            targetRef: attempt.targetRef,
+            baseHead: attempt.expectedHead
+        });
+        if (gate.mode !== "record") {
+            const existing = await lookupReusableGateArtifact(this.store, identity);
+            if (existing !== null) {
+                touchGateArtifact(this.store, recordGateArtifactReuse(existing, this.now()));
+                const checks = checkResultsFromGateArtifact(existing, true);
+                return this.#finalizeGateSuccess(attempt, workspace, repositoryPath, candidateCommit, checks);
+            }
+        }
+        else {
+            // Record mode: observe the potential reuse without skipping the gate.
+            const existing = await lookupReusableGateArtifact(this.store, identity);
+            if (existing !== null) {
+                touchGateArtifact(this.store, recordGateArtifactPotentialReuse(existing, this.now()));
+            }
+        }
+        if (this.jobPort !== undefined) {
+            return this.#startCheckJob(attempt, workspace, path, managedWorkspace, repositoryPath, gate);
+        }
+        // Jobless fallback (queue processing without a Controller): run the
+        // plan gate in-process and record the artifact directly.
+        const runtime = this.#runtimePreparation(attempt, managedWorkspace);
+        this.runtimeIsolation.activate(runtime);
+        let cleanupReason = "failure";
+        try {
+            const environment = await integrationCheckEnvironment(this.environment, runtime);
+            const steps = [
+                ...planBootstrapJobSteps(gate.plan),
+                ...planL2JobSteps(gate.plan)
+            ];
+            const outcomes = await runGateStepsInProcess(path, steps, environment, integrationCheckDirectory(this.home, attempt.taskId, attempt.id), candidateCommit);
+            const succeeded = outcomes.length === steps.length
+                && outcomes.every((outcome) => outcome.exitCode === 0 && outcome.signal === null && !outcome.timedOut);
+            const artifact = await recordGateArtifactFromStepOutcomes(this.store, identity, gate.plan, outcomes, succeeded, this.now());
+            const checks = checkResultsFromGateArtifact(artifact);
+            cleanupReason = succeeded ? "completion" : "failure";
+            if (!succeeded) {
+                const failed = updateIntegrationAttempt(attempt, { status: "failed", checks }, this.now());
+                this.store.saveIntegrationAttempt(attempt.taskId, failed);
+                return this.#terminalResult("failed", failed, workspace);
+            }
+            return this.#finalizeGateSuccess(attempt, workspace, repositoryPath, candidateCommit, checks);
+        }
+        finally {
+            this.runtimeIsolation.cleanup(runtime, cleanupReason);
+        }
+    }
+    async #finalizeGateSuccess(attempt, workspace, repositoryPath, candidateCommit, checks) {
+        const validating = updateIntegrationAttempt(attempt, {
+            status: "validating",
+            candidateCommit,
+            checks
+        }, this.now());
+        this.store.saveIntegrationAttempt(attempt.taskId, validating);
+        await advanceTargetRef(repositoryPath, validating.targetRef, candidateCommit, validating.expectedHead);
+        const committed = updateIntegrationAttempt(validating, { status: "committed" }, this.now());
+        this.store.saveIntegrationAttempt(attempt.taskId, committed);
+        return this.#terminalResult("committed", committed, workspace);
+    }
     #runtimePreparation(attempt, workspace) {
         return this.runtimeIsolation.preflight({
             workspace,
@@ -258,6 +548,13 @@ export class GitIntegrationService {
     }
     async #applyCommits(attempt, workspace, candidatePath, commits) {
         for (const { changeSetId, commit } of commits) {
+            // Fast-forward when the commit is a direct descendant of HEAD: this
+            // preserves the original commit SHA, which exact-SHA review evidence
+            // relies on.  Fall back to cherry-pick when the target moved since the
+            // ChangeSet was based (the commit is no longer a direct descendant).
+            if (await gitSucceeds(["-C", candidatePath, "merge", "--ff-only", commit])) {
+                continue;
+            }
             try {
                 await git(["-C", candidatePath, "cherry-pick", commit]);
             }
@@ -409,6 +706,65 @@ async function completeRemoteBaselineResolution(path) {
         "commit", "--no-edit"
     ]);
 }
+/**
+ * Map a terminal check job back to the attempt's CheckResult[] shape. The
+ * runner stops at the first failing step, so unreached checks are "skipped"
+ * except for an unproven (unknown) job, which fails closed on the first
+ * missing step so the attempt never passes without evidence. A job that ended
+ * without a single failing step (cancelled before any step, or any other
+ * non-succeeded outcome) also fails closed: the target ref must never advance
+ * on an unproven check.
+ */
+function checkResultsFromJob(attempt, job) {
+    const steps = new Map((job.result?.steps ?? []).map((step) => [step.name, step]));
+    const checks = attempt.checkCommands.map((command, index) => {
+        const name = `check-${index + 1}`;
+        const step = steps.get(name);
+        const logPath = step === undefined
+            ? undefined
+            : `${job.artifactsLocator}/logs/${step.logPath}`;
+        const outputReference = logPath === undefined ? {} : { logPath };
+        if (step !== undefined && !step.timedOut && step.exitCode === 0 && step.signal === null) {
+            return { name: command, outcome: "passed", ...outputReference };
+        }
+        if (step !== undefined) {
+            const reason = step.timedOut
+                ? "Command timed out after 1800 seconds."
+                : step.signal !== null
+                    ? `Command terminated by ${step.signal}.`
+                    : `Command exited with code ${step.exitCode}.`;
+            return { name: command, outcome: "failed", details: reason, ...outputReference };
+        }
+        if (job.result?.outcome === "unknown-needs-attention") {
+            return {
+                name: command,
+                outcome: "failed",
+                details: `Check job unknown-needs-attention: ${job.result.unknownReason ?? "runner outcome is unproven"}.`
+            };
+        }
+        return { name: command, outcome: "skipped" };
+    });
+    if (checks.length > 0
+        && !checks.some((check) => check.outcome === "failed")
+        && job.result?.outcome !== "succeeded") {
+        checks[0] = {
+            name: checks[0].name,
+            outcome: "failed",
+            details: failClosedJobDetails(job)
+        };
+    }
+    return checks;
+}
+function failClosedJobDetails(job) {
+    const outcome = job.result?.outcome ?? job.status;
+    if (outcome === "cancelled") {
+        return "Check job was cancelled before it proved the checks.";
+    }
+    if (outcome === "timed-out") {
+        return "Check job timed out before it proved the checks.";
+    }
+    return `Check job ended ${outcome} without proving the checks.`;
+}
 async function runChecks(path, commands, home, taskId, integrationId, environment) {
     if (commands.length === 0)
         return [];
@@ -643,6 +999,31 @@ async function resolveRef(repositoryPath, ref) {
         `${fullTargetRef(ref)}^{commit}`
     ]);
 }
+/**
+ * Static preflight before the (potentially expensive) checks: the target ref
+ * must still equal the expected head and a checked-out target worktree must be
+ * clean.  A failure here means the check commands must not run.  The post-check
+ * {@link advanceTargetRef} re-verifies both before the CAS, so a target that
+ * moves during the gate is still fenced.
+ */
+async function assertTargetReadyForChecks(repositoryPath, targetRef, expectedHead) {
+    const current = await resolveRef(repositoryPath, targetRef);
+    if (current !== expectedHead) {
+        throw new Error(`Target moved to ${current}; expected ${expectedHead}.`);
+    }
+    const checkedOutPaths = await checkedOutWorktreePaths(repositoryPath, fullTargetRef(targetRef));
+    if (checkedOutPaths.length > 1) {
+        throw new Error(`Integration target is checked out in multiple worktrees: ${targetRef}.`);
+    }
+    if (checkedOutPaths.length === 1) {
+        const status = await git([
+            "-C", checkedOutPaths[0], "status", "--porcelain=v1", "--untracked-files=all"
+        ]);
+        if (status.trim().length > 0) {
+            throw new Error(`Integration target worktree is not clean: ${checkedOutPaths[0]}.`);
+        }
+    }
+}
 async function advanceTargetRef(repositoryPath, targetRef, candidateCommit, expectedHead) {
     const ref = fullTargetRef(targetRef);
     const checkedOutPaths = await checkedOutWorktreePaths(repositoryPath, ref);