@deksden-com/dd-flow-cli 0.9.0-beta.8 → 0.9.0-beta.81

package/dist/services/vnext-merge.js

@@ -1,4 +1,6 @@
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
+import { runWorkspaceBootstrap } from "./workspace-bootstrap.js";
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync, spawnSync } from "node:child_process";
@@ -8,14 +10,17 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
 import { nextMergeRequestId } from "./ids.js";
 import { readProjectConfig } from "./config.js";
-import { appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, gitFacts } from "./runs.js";
+import { appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, gitFacts, prepareFlowRunStageAttachment, prepareVnextMergeSourceRepairAttempt } from "./runs.js";
 import { flowCommand, stagePauseCommandTemplate } from "./stage-pause.js";
-import { validateSchema } from "./schema-validation.js";
 import { writeStageReport } from "./stage-report-renderer.js";
-import { bindStageCoordinatorWork, createChildWork, finishFanInWork, finishWork, refreshRunWorkProjection, startStageCoordinatorWork } from "./work-registry.js";
-import { checkReceipts, effectiveCheckDeclarations, readCodeCheckProfile, runCodeChecks, unchangedFinalGateFailures, workspaceFingerprint } from "./code-checks.js";
-import { applyExternalStageContext } from "./stage-context.js";
-import { ensureLaneWorkspace, heartbeatLaneLock, releaseLaneLock, waitAcquireLaneLock } from "./lanes.js";
+import { bindStageCoordinatorWork, createChildWork, failWork, finishFanInWork, finishWork, refreshRunWorkProjection, startStageCoordinatorWork } from "./work-registry.js";
+import { addVnextCodeRepair } from "./vnext-code.js";
+import { checkReceiptEvidenceValid, checkReceipts, effectiveCheckDeclarations, readCodeCheckProfile, runCodeChecks, validateFailedCheckRetry, workspaceChangedPaths, workspaceFingerprint } from "./code-checks.js";
+import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
+import { ensureLaneWorkspace, prepareLaneWorkspace, heartbeatLaneLock, releaseLaneLock, waitAcquireLaneLock } from "./lanes.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { assertStageStartHookEvent } from "./hooks.js";
+import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
 const stage = "merge";
 const stageDir = vnextStageDirectory(stage);
 export function isVnextMergeRun(context, input) {
@@ -24,12 +29,17 @@ export function isVnextMergeRun(context, input) {
 }
 /** Terminal CODE/CODE-REVIEW calls this once; it freezes source and creates the child MERGE Work. */
 export function ensureVnextMergeRequest(context, input) {
+    return prepareVnextMergeRequest(context, input)();
+}
+/** Freeze filesystem evidence outside the stage writer lock; return only the SQL settlement. */
+export function prepareVnextMergeRequest(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
-    const existing = context.db.get("SELECT * FROM merge_requests WHERE project_id = ? AND run_id = ? ORDER BY created_at LIMIT 1", [project.id, run.id]);
+    assertRunMutationAllowed(context, project.id, run.id);
+    const existing = context.db.get("SELECT * FROM merge_requests WHERE project_id = ? AND run_id = ? AND status NOT IN ('completed','failed','cancelled','superseded') ORDER BY created_at DESC LIMIT 1", [project.id, run.id]);
     if (existing)
-        return requestView(context, existing);
+        return () => requestView(context, requireRequest(context, existing.merge_request_id));
     const settings = executionSettings(run);
     const route = settings.merge_mode ?? "same_session";
     const home = requireHome(run);
@@ -46,6 +56,7 @@ export function ensureVnextMergeRequest(context, input) {
         throw new AppError("merge_source_invalid", "MERGE could not determine the target branch", 1, { target_branch: targetBranch });
     const semantic = planChecks(run.workspace_root, protocols);
     validateMergeAcceptance(run.workspace_root, protocols, semantic);
+    const acceptanceRefs = mergeAcceptanceRefs(run.workspace_root, protocols);
     const effective = effectiveCheckDeclarations(targetWorkspace, semantic, ["work", "code", "readiness", "merge"]);
     if (run.workspace_root !== targetWorkspace && effective.length === 0)
         throw new AppError("merge_gate_missing", "A real source/target integration requires at least one semantic or policy merge check", 2, { run_id: run.id, protocol_ids: protocols });
@@ -55,18 +66,20 @@ export function ensureVnextMergeRequest(context, input) {
     const freezeFile = path.join(freezeRoot, "source-freeze.json");
     const gateFile = path.join(freezeRoot, "merge-gate.json");
     fs.mkdirSync(freezeRoot, { recursive: true });
-    freezeMergeGate(gateFile, { runId: run.id, protocols, checks: effective, profileHash: readCodeCheckProfile(targetWorkspace).hash, now: context.now() });
+    freezeMergeGate(gateFile, { runId: run.id, protocols, checks: effective, acceptanceRefs, profileHash: readCodeCheckProfile(targetWorkspace).hash, now: context.now() });
     let sourceCommit;
     let sourcePaths;
     if (fs.existsSync(freezeFile)) {
         const frozen = JSON.parse(fs.readFileSync(freezeFile, "utf8"));
         sourceCommit = frozen.run_id === run.id && typeof frozen.source_commit === "string" ? frozen.source_commit : "";
         sourcePaths = Array.isArray(frozen.paths) ? frozen.paths : [];
-        if (!sourceCommit || gitValue(run.workspace_root, ["rev-parse", "HEAD"]) !== sourceCommit || (accepted && JSON.stringify(accepted) !== JSON.stringify(sourcePaths)))
+        // A retry sees a clean tree: the original paths are already in sourceCommit.
+        // Reuse that receipt, but never accept new edits merely because names match.
+        if (!sourceCommit || frozen.source_workspace !== run.workspace_root || frozen.source_branch !== sourceBranch || gitValue(run.workspace_root, ["rev-parse", "HEAD"]) !== sourceCommit || meaningfulStatus(run.workspace_root, ignored).length)
             throw new AppError("merge_source_freeze_conflict", "Existing MERGE source freeze does not match the accepted source", 2, { freeze_file: freezeFile });
     }
     else {
-        sourcePaths = [...new Set(meaningfulStatus(run.workspace_root, ignored).map(statusPath))].sort();
+        sourcePaths = meaningfulStatus(run.workspace_root, ignored);
         if (accepted) {
             const unexpected = sourcePaths.filter((item) => !accepted.includes(item));
             const absent = accepted.filter((item) => !sourcePaths.includes(item));
@@ -82,58 +95,74 @@ export function ensureVnextMergeRequest(context, input) {
     if (!sourceCommit)
         throw new AppError("merge_source_invalid", "MERGE could not freeze source commit", 1, { source_commit: sourceCommit, target_branch: targetBranch });
     const enqueueTarget = gitValue(targetWorkspace, ["rev-parse", targetBranch], true);
-    const root = requireRootWork(context, project.id, run.id);
-    let child;
-    let requestId;
-    const now = context.now();
-    context.db.exec("BEGIN IMMEDIATE");
-    try {
-        const raced = context.db.get("SELECT * FROM merge_requests WHERE project_id = ? AND run_id = ?", [project.id, run.id]);
-        if (raced) {
-            context.db.exec("COMMIT");
+    return () => context.db.writeTransaction(() => {
+        assertRunMutationAllowed(context, project.id, run.id);
+        const root = requireRootWork(context, project.id, run.id);
+        const now = context.now();
+        const raced = context.db.get("SELECT * FROM merge_requests WHERE project_id = ? AND run_id = ? AND status NOT IN ('completed','failed','cancelled','superseded') ORDER BY created_at DESC LIMIT 1", [project.id, run.id]);
+        if (raced)
             return requestView(context, raced);
-        }
-        child = createChildWork(context, { parentWorkId: root.work_id, slug: "merge", task: `Integrate frozen source ${sourceCommit} into ${targetBranch}, resolve material conflicts, and preserve accepted behavior.`, launchPolicy: route === "server" ? "fresh_agent_required" : "reuse_allowed", resultSchema: "dd-flow/merge-result@1", payload: { kind: "merge", checks: semantic, protocol_ids: protocols } });
-        requestId = nextMergeRequestId(context);
-        context.db.run("INSERT INTO merge_requests (merge_request_id, project_id, run_id, executor_work_id, protocol_ids_json, source_workspace, source_branch, source_commit, target_workspace, target_branch, enqueue_target_head, execution_target_head, integration_commit, execution_route, status, dispatch_owner, dispatch_lease_token, dispatch_lease_expires_at, lock_acquired_at, checkpoint, profile_hash, adapter_receipt_json, result_json, last_error_json, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, ?, 'queued', NULL, NULL, NULL, NULL, 'queued', ?, NULL, NULL, NULL, ?, ?, NULL)", [requestId, project.id, run.id, child.work_id, JSON.stringify(protocols), run.workspace_root, sourceBranch, sourceCommit, targetWorkspace, targetBranch, enqueueTarget, route, readCodeCheckProfile(targetWorkspace).hash, now, now]);
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
-    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "merge_request_queued", merge_request_id: requestId, work_id: child.work_id, route, source_commit: sourceCommit, target_branch: targetBranch });
-    return requestView(context, requireRequest(context, requestId));
+        const child = createChildWork(context, { parentWorkId: root.work_id, slug: "merge", task: `Integrate frozen source ${sourceCommit} into ${targetBranch}, resolve material conflicts, and preserve accepted behavior.`, launchPolicy: route === "server" ? "fresh_agent_required" : "reuse_allowed", resultSchema: "dd-flow/merge-result@1", payload: { kind: "merge", checks: semantic, protocol_ids: protocols } });
+        const requestId = nextMergeRequestId(context);
+        context.db.run("INSERT INTO merge_requests (merge_request_id, project_id, run_id, executor_work_id, protocol_ids_json, source_workspace, source_branch, source_commit, target_workspace, target_branch, enqueue_target_head, execution_target_head, integration_commit, execution_route, status, dispatch_owner, dispatch_lease_token, dispatch_lease_expires_at, lock_acquired_at, checkpoint, profile_hash, replacement_of_merge_request_id, adapter_receipt_json, result_json, last_error_json, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, ?, 'queued', NULL, NULL, NULL, NULL, 'queued', ?, ?, NULL, NULL, NULL, ?, ?, NULL)", [requestId, project.id, run.id, child.work_id, JSON.stringify(protocols), run.workspace_root, sourceBranch, sourceCommit, targetWorkspace, targetBranch, enqueueTarget, route, readCodeCheckProfile(targetWorkspace).hash, replacementOf(run), now, now]);
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "merge_request_queued", merge_request_id: requestId, work_id: child.work_id, route, source_commit: sourceCommit, target_branch: targetBranch });
+        return requestView(context, requireRequest(context, requestId));
+    });
 }
-export async function startVnextMerge(context, input) {
+export function prepareVnextMergeStart(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const home = requireHome(run);
     const request = requestForRun(context, project.id, run.id);
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
+    const common = { projectRoot, project, run, request, generation };
     if (request.status === "completed")
+        return { ...common, terminal: true };
+    if (!["queued", "dispatching", "active", "action_required"].includes(request.status))
+        throw new AppError("merge_request_state_invalid", "MERGE request cannot be started in its current state", 1, { status: request.status, merge_request_id: request.merge_request_id });
+    const root = path.join(home, stageDir), workRoot = path.join(root, "works", request.executor_work_id);
+    const resultPath = path.join(workRoot, "result.json"), promptPath = path.join(workRoot, "prompt.md");
+    const work = context.db.get("SELECT status, project_id, run_id FROM works WHERE work_id = ?", [request.executor_work_id]);
+    if (!work || work.project_id !== project.id || work.run_id !== run.id || !["created", "running"].includes(work.status))
+        throw new AppError("runtime_artifact_invalid", "MERGE executor Work is missing or not startable", 1, { work_id: request.executor_work_id });
+    const index = JSON.parse(run.index_json);
+    if (!index.stage_runs?.some(entry => entry.stage === stage))
+        prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" });
+    prepareLaneWorkspace(context, { projectRoot, lane: "merge", workspacePath: request.target_workspace, branch: request.target_branch });
+    const checks = effectiveMergeChecks(run, request), settings = executionSettings(run);
+    const existingPrompt = ["active", "action_required"].includes(request.status) && fs.existsSync(promptPath) ? fs.readFileSync(promptPath, "utf8") : null;
+    if (existingPrompt === null || input.externalContext)
+        prepareOutputFile(promptPath);
+    if (input.externalContext)
+        prepareExternalStageContext({ stageRoot: root, loaded: input.externalContext });
+    return { ...common, terminal: false, root, workRoot, resultPath, promptPath, checks, settings, existingPrompt };
+}
+export async function startVnextMerge(context, input, prepared = prepareVnextMergeStart(context, input)) {
+    const { projectRoot, project, run, request, generation } = prepared;
+    if (prepared.terminal)
         return requestView(context, request);
-    const root = path.join(home, stageDir);
-    const workRoot = path.join(root, "works", request.executor_work_id);
+    const { root, workRoot, resultPath, promptPath, checks, settings, existingPrompt } = prepared;
+    assertRunMutationAllowed(context, project.id, run.id, generation);
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     fs.mkdirSync(workRoot, { recursive: true });
-    const resultPath = path.join(workRoot, "result.json");
-    const promptPath = path.join(workRoot, "prompt.md");
     ensureLaneWorkspace(context, { projectRoot, lane: "merge", workspacePath: request.target_workspace, branch: request.target_branch });
     const lane = await waitAcquireLaneLock(context, { projectRoot, lane: "merge", workerId: request.executor_work_id, workspacePath: request.target_workspace, timeoutSeconds: 3600, pollIntervalSeconds: 15, ttlSeconds: 7200, reason: `MERGE ${request.merge_request_id}`, ...(input.progress ? { progress: input.progress } : {}) });
     if (!lane.acquired)
         throw new AppError("merge_lane_wait_failed", "MERGE could not acquire the project integration lane", 1, { merge_request_id: request.merge_request_id, status: lane.status ?? "unknown" });
     try {
+        assertRunMutationAllowed(context, project.id, run.id, generation);
         if (["active", "action_required"].includes(request.status)) {
             const pendingWork = context.db.get("SELECT status FROM works WHERE work_id = ?", [request.executor_work_id]);
             const binding = pendingWork?.status === "created"
                 ? startStageCoordinatorWork(context, { workId: request.executor_work_id, hookEventId: input.hookEventId, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) })
                 : bindStageCoordinatorWork(context, { workId: request.executor_work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-            const prompt = fs.existsSync(promptPath) ? fs.readFileSync(promptPath, "utf8") : mergePrompt(context, { run, request, resultPath, projectRoot });
-            if (!fs.existsSync(promptPath))
+            const prompt = existingPrompt ?? mergePrompt(context, { run, request, resultPath, projectRoot }, checks, settings);
+            if (existingPrompt === null)
                 fs.writeFileSync(promptPath, prompt);
             const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
             ensureMergeStageAttached(context, run, projectRoot);
-            return startPacket(context, run, request, binding, promptPath, resultPath, prompt, projectRoot, externalContext);
+            return startPacket(context, run, request, binding, promptPath, resultPath, prompt, projectRoot, checks, externalContext);
         }
         const current = requireRequest(context, request.merge_request_id);
         const targetHead = gitValue(current.target_workspace, ["rev-parse", current.target_branch], true);
@@ -147,31 +176,40 @@ export async function startVnextMerge(context, input) {
         if (claimed.changes !== 1 && requireRequest(context, current.merge_request_id).status !== "active")
             throw new AppError("merge_claim_conflict", "MERGE request could not acquire the integration lane", 1, { merge_request_id: current.merge_request_id });
         const started = startStageCoordinatorWork(context, { workId: current.executor_work_id, hookEventId: input.hookEventId, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-        const prompt = mergePrompt(context, { run, request: requireRequest(context, current.merge_request_id), resultPath, projectRoot });
+        const prompt = mergePrompt(context, { run, request: requireRequest(context, current.merge_request_id), resultPath, projectRoot }, checks, settings);
         fs.writeFileSync(promptPath, prompt);
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         context.db.run("UPDATE work_sessions SET prompt_path = ?, result_path = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [promptPath, resultPath, context.now(), current.executor_work_id]);
         attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" });
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "merge_started", merge_request_id: current.merge_request_id, work_id: current.executor_work_id, target_head: targetHead });
-        return startPacket(context, run, current, started, promptPath, resultPath, prompt, projectRoot, externalContext);
+        return startPacket(context, run, current, started, promptPath, resultPath, prompt, projectRoot, checks, externalContext);
     }
     catch (error) {
         const latest = requireRequest(context, request.merge_request_id);
+        if (error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale"].includes(error.code)) {
+            releaseMergeLane(context, projectRoot, latest, `MERGE ${latest.merge_request_id} interrupted`);
+            throw error;
+        }
         if (["active", "dispatching"].includes(latest.status))
             context.db.run("UPDATE merge_requests SET status = 'action_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "merge_start_failed", error: error instanceof Error ? error.message : String(error) }), context.now(), latest.merge_request_id]);
         releaseMergeLane(context, projectRoot, latest, `MERGE ${latest.merge_request_id} start failed`);
         throw error;
     }
 }
-function startPacket(context, run, request, binding, promptPath, resultPath, prompt, projectRoot, externalContext) {
-    return { ok: true, run_id: run.id, stage, merge_request_id: request.merge_request_id, work_id: request.executor_work_id, session_binding: binding.session_binding ?? binding, prompt_path: promptPath, result_path: resultPath, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), queue: queueStatus(context, request), effective_checks: effectiveMergeChecks(run, request), next: { apply_command: applyCommand(context, request, projectRoot), finish_command: finishCommand(context, run.id, request, projectRoot) } };
+function startPacket(context, run, request, binding, promptPath, resultPath, prompt, projectRoot, checks, externalContext) {
+    return { ok: true, run_id: run.id, stage, merge_request_id: request.merge_request_id, work_id: request.executor_work_id, session_binding: binding.session_binding ?? binding, prompt_path: promptPath, result_path: resultPath, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), queue: queueStatus(context, request), effective_checks: checks, next: { apply_command: applyCommand(context, request, projectRoot), finish_command: finishCommand(context, run.id, request, projectRoot) } };
 }
 export function applyVnextMerge(context, input) {
     const existing = requireRequest(context, input.requestId);
     const receiptFile = applyReceiptPath(context, existing);
-    if (existing.executor_work_id === input.workId && ["apply_recorded", "integration_committed", "bootstrap_ready", "checks_passed", "delivered", "finalized"].includes(existing.checkpoint) && fs.existsSync(receiptFile))
-        return JSON.parse(fs.readFileSync(receiptFile, "utf8"));
     const request = requireOwnedActiveRequest(context, input);
+    assertRunMutationAllowed(context, request.project_id, request.run_id);
+    if (["apply_recorded", "integration_committed", "bootstrap_ready", "checks_passed", "delivered", "finalized"].includes(request.checkpoint) && fs.existsSync(receiptFile)) {
+        const receipt = JSON.parse(fs.readFileSync(receiptFile, "utf8"));
+        if (receipt.merge_request_id !== request.merge_request_id || receipt.work_id !== request.executor_work_id || receipt.source_commit !== request.source_commit)
+            throw new AppError("merge_apply_receipt_invalid", "Existing merge apply receipt does not match the active request", 1, { receipt_path: receiptFile });
+        return receipt;
+    }
     heartbeatLaneLock(context, { projectRoot: input.projectRoot, lane: "merge", workerId: request.executor_work_id, workspacePath: request.target_workspace, ttlSeconds: 7200 });
     assertExecutionBaseline(request);
     input.progress?.(`applying ${request.source_commit} to ${request.target_branch}`);
@@ -193,54 +231,77 @@ export function applyVnextMerge(context, input) {
     context.db.run("UPDATE merge_requests SET checkpoint = 'apply_recorded', result_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ apply_receipt: receiptFile }), context.now(), request.merge_request_id]);
     return { ok: true, ...receipt };
 }
-export async function finishVnextMerge(context, input) {
+export function prepareVnextMergeFinish(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const existing = requireRequest(context, input.requestId);
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
     if (existing.project_id !== project.id || existing.run_id !== run.id || existing.executor_work_id !== input.workId)
         throw new AppError("merge_request_mismatch", "MRG/Work/RUN/project identity does not match", 2);
-    if (existing.status === "completed") {
-        recoverCompletedMergeRun(context, run, projectRoot, existing);
-        return { ok: true, resumed: true, run_id: run.id, stage, outcome: "completed", merge_request_id: existing.merge_request_id, work_id: existing.executor_work_id, integration_commit: existing.integration_commit, report_path: path.join(requireHome(run), stageDir, "stage-report.json"), next_action: "merge_completed" };
-    }
-    let request = requireOwnedActiveRequest(context, input);
-    heartbeatLaneLock(context, { projectRoot, lane: "merge", workerId: request.executor_work_id, workspacePath: request.target_workspace, ttlSeconds: 7200 });
+    if (existing.status === "completed")
+        return { projectRoot, project, run, existing, generation, terminal: true };
+    const request = requireOwnedActiveRequest(context, input);
     if (request.run_id !== run.id)
         throw new AppError("merge_request_mismatch", "MRG does not belong to RUN", 2);
     if (request.checkpoint === "baseline_locked" || !fs.existsSync(applyReceiptPath(context, request)))
         throw new AppError("merge_apply_required", "Run the exact merge apply command before MERGE finish", 2, { merge_request_id: request.merge_request_id, checkpoint: request.checkpoint });
-    if (unmerged(request.target_workspace).length)
-        throw new AppError("merge_conflicts_unresolved", "Resolve every unmerged path before finishing MERGE", 2, { paths: unmerged(request.target_workspace) });
+    const conflicts = unmerged(request.target_workspace);
+    if (conflicts.length)
+        throw new AppError("merge_conflicts_unresolved", "Resolve every unmerged path before finishing MERGE", 2, { paths: conflicts });
     const resultPath = path.join(requireHome(run), stageDir, "works", request.executor_work_id, "result.json");
-    validateSchema({ schemaName: "merge-result", file: resultPath, projectRoot: request.target_workspace, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireHome(run) });
-    const semantic = JSON.parse(fs.readFileSync(resultPath, "utf8"));
-    if (semantic.outcome !== "completed")
+    const result = prepareJsonSchema(resultPath, "MERGE result", { schemaName: "merge-result", projectRoot: request.target_workspace, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireHome(run) });
+    if (result.value.outcome !== "completed")
         throw new AppError("merge_semantic_blocked", "A blocked semantic result cannot complete MERGE", 2, { result_path: resultPath });
+    const gate = readFrozenMergeGate(path.join(requireHome(run), stageDir, "merge-gate.json"), request.merge_request_id);
+    if (input.retryCheckId)
+        validateFailedCheckRetry(context, { projectId: project.id, runId: run.id, receiptId: input.retryCheckId, declarations: gate.checks, reason: input.retryReason });
+    return { projectRoot, project, run, existing, generation, terminal: false, request, resultPath, result, gate };
+}
+export async function finishVnextMerge(context, input, prepared = prepareVnextMergeFinish(context, input)) {
+    const { projectRoot, project, run, existing, generation } = prepared;
+    if (prepared.terminal) {
+        recoverCompletedMergeRun(context, run, projectRoot, existing);
+        releaseMergeLane(context, projectRoot, existing, `MERGE ${existing.merge_request_id} completion recovered`);
+        return { ok: true, resumed: true, run_id: run.id, stage, outcome: "completed", merge_request_id: existing.merge_request_id, work_id: existing.executor_work_id, integration_commit: existing.integration_commit, report_path: path.join(requireHome(run), stageDir, "stage-report.json"), next_action: "merge_completed" };
+    }
+    let request = prepared.request;
+    heartbeatLaneLock(context, { projectRoot, lane: "merge", workerId: request.executor_work_id, workspacePath: request.target_workspace, ttlSeconds: 7200 });
+    const semantic = prepared.result.value;
     if (request.checkpoint === "apply_recorded") {
         input.progress?.("bootstrapping integrated target");
-        runBootstrap(run, request.target_workspace);
+        await runBootstrap(context, run, request.target_workspace, request.merge_request_id, input.progress);
+        assertRunMutationAllowed(context, project.id, run.id, generation);
         context.db.run("UPDATE merge_requests SET checkpoint = 'bootstrap_ready', updated_at = ? WHERE merge_request_id = ?", [context.now(), request.merge_request_id]);
         request = requireRequest(context, request.merge_request_id);
     }
-    const checks = effectiveMergeChecks(run, request);
-    const unchanged = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: request.target_workspace, declarations: checks });
-    if (unchanged.length)
-        throw new AppError("merge_check_repair_required", "MERGE checks already failed for the unchanged integrated tree", 2, { failures: unchanged });
-    const receipts = request.checkpoint === "checks_passed" || request.checkpoint === "delivered" || request.checkpoint === "finalized" ? checkReceipts(context, { projectId: project.id, runId: run.id, workId: request.executor_work_id }).filter((receipt) => receipt.status === "passed" && receipt.before_fingerprint === workspaceFingerprint(request.target_workspace)) : await runCodeChecks(context, { projectId: project.id, runId: run.id, runHome: requireHome(run), workspaceRoot: request.target_workspace, workId: request.executor_work_id, artifactDir: path.join(stageDir, "works", request.executor_work_id), scope: "aggregate", checks, ...(input.progress ? { progress: input.progress } : {}) });
+    const gate = prepared.gate, checks = gate.checks;
+    if (input.retryCheckId)
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "check_retry_requested", check_receipt_id: input.retryCheckId, stage, reason: input.retryReason ?? "operator retry" });
+    const acceptancePath = path.join(requireHome(run), stageDir, "merge-gate-acceptance.json");
+    const recovered = readMergeGateAcceptance(context, acceptancePath, request, gate);
+    const resumingGate = ["checks_passed", "integration_committed", "delivered"].includes(request.checkpoint);
+    if (resumingGate && !recovered.valid)
+        return recovery(context, request, "merge_evidence_missing", { checkpoint: request.checkpoint });
+    if (request.checkpoint === "checks_passed" && request.accepted_tree && gitValue(request.target_workspace, ["write-tree"]) !== request.accepted_tree)
+        return recovery(context, request, "merge_workspace_drift_after_checks", { accepted_tree: request.accepted_tree });
+    const receipts = resumingGate ? recovered.receipts : await runCodeChecks(context, { projectId: project.id, runId: run.id, runHome: requireHome(run), workspaceRoot: request.target_workspace, workId: request.executor_work_id, artifactDir: path.join(stageDir, "works", request.executor_work_id), scope: "aggregate", checks, expectedProfileHash: gate.profileHash, ...(input.retryCheckId ? { retryReceiptId: input.retryCheckId, retryReason: input.retryReason } : {}), ...(input.progress ? { progress: input.progress } : {}) });
+    assertRunMutationAllowed(context, project.id, run.id, generation);
     const failed = receipts.filter((receipt) => receipt.status !== "passed");
     if (failed.length) {
         context.db.run("UPDATE merge_requests SET status = 'action_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "merge_gate_failed", failures: failed }), context.now(), request.merge_request_id]);
-        throw new AppError("merge_gate_failed", "Integrated target checks failed; repair in the same MERGE Work and retry finish", 2, { failures: failed });
+        throw new AppError("merge_gate_failed", "Integrated target checks failed. Classify retained evidence: source defects use source repair; restored environment uses retry.", 2, { failures: failed, repair_command: `${flowCommand(context)} merge repair ${request.merge_request_id} --project-root ${JSON.stringify(projectRoot)} --json`, retry_command: finishCommand(context, run.id, request, projectRoot, failed[0].id) });
     }
-    const requiredRefs = mergeAcceptanceRefs(run.workspace_root, JSON.parse(request.protocol_ids_json));
     const passedRefs = new Set(receipts.flatMap((receipt) => receipt.check_refs));
-    const missingRefs = requiredRefs.filter((ref) => !passedRefs.has(ref));
+    const missingRefs = frozenGateRefs(gate).filter((ref) => !passedRefs.has(ref));
     if (missingRefs.length)
-        throw new AppError("merge_acceptance_unproven", "Current MERGE receipts do not cover every merge acceptance reference", 2, { missing_check_refs: missingRefs });
-    const acceptedTree = gitValue(request.target_workspace, ["write-tree"]);
-    context.db.run("UPDATE merge_requests SET checkpoint = 'checks_passed', accepted_tree = ?, status = 'active', updated_at = ? WHERE merge_request_id = ?", [acceptedTree, context.now(), request.merge_request_id]);
-    request = requireRequest(context, request.merge_request_id);
+        throw new AppError("merge_acceptance_unproven", "Current MERGE receipts do not cover every frozen merge-gate reference", 2, { missing_check_refs: missingRefs });
+    if (!request.integration_commit) {
+        const acceptedTree = gitValue(request.target_workspace, ["write-tree"]);
+        writeMergeGateAcceptance(context, acceptancePath, request, gate, acceptedTree, receipts);
+        context.db.run("UPDATE merge_requests SET checkpoint = 'checks_passed', accepted_tree = ?, status = 'active', updated_at = ? WHERE merge_request_id = ?", [acceptedTree, context.now(), request.merge_request_id]);
+        request = requireRequest(context, request.merge_request_id);
+    }
     if (!request.integration_commit) {
         commitIntegration(request.target_workspace, run.id, ignoredGitPaths(context, project.id));
         const commit = gitValue(request.target_workspace, ["rev-parse", "HEAD"]);
@@ -251,11 +312,21 @@ export async function finishVnextMerge(context, input) {
         context.db.run("UPDATE merge_requests SET integration_commit = ?, checkpoint = 'integration_committed', updated_at = ? WHERE merge_request_id = ?", [commit, context.now(), request.merge_request_id]);
         request = requireRequest(context, request.merge_request_id);
     }
+    if (request.integration_commit && request.accepted_tree && gitValue(request.target_workspace, ["rev-parse", `${request.integration_commit}^{tree}`]) !== request.accepted_tree)
+        return recovery(context, request, "merge_committed_tree_drift", { accepted_tree: request.accepted_tree, integration_commit: request.integration_commit });
     verifyLocalDelivery(request);
     context.db.run("UPDATE merge_requests SET checkpoint = 'delivered', updated_at = ? WHERE merge_request_id = ?", [context.now(), request.merge_request_id]);
     request = requireRequest(context, request.merge_request_id);
     performConfiguredCleanup(run, request);
-    await finishWork(context, request.executor_work_id, fs.readFileSync(resultPath, "utf8"));
+    const acceptedResult = prepared.result.text;
+    const executor = context.db.get("SELECT status, result FROM works WHERE work_id = ?", [request.executor_work_id]);
+    if (!executor)
+        return recovery(context, request, "merge_executor_missing", { work_id: request.executor_work_id });
+    if (executor.status === "running")
+        await finishWork(context, request.executor_work_id, acceptedResult);
+    else if (executor.status !== "completed" || executor.result !== acceptedResult)
+        return recovery(context, request, "merge_executor_settlement_mismatch", { work_id: request.executor_work_id, status: executor.status });
+    assertRunMutationAllowed(context, project.id, run.id, generation);
     const now = context.now();
     context.db.run("UPDATE merge_requests SET status = 'completed', checkpoint = 'finalized', result_json = ?, completed_at = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify(semantic), now, now, request.merge_request_id]);
     const report = mergeReport(context, run, requireRequest(context, request.merge_request_id), semantic, receipts);
@@ -280,51 +351,124 @@ function ensureMergeStageAttached(context, run, projectRoot) {
 function recoverCompletedMergeRun(context, run, projectRoot, request) {
     const root = path.join(requireHome(run), stageDir);
     const reportPath = path.join(root, "stage-report.json");
-    if (!fs.existsSync(reportPath))
-        throw new AppError("merge_report_missing", "Completed MERGE request has no stage report", 1, { merge_request_id: request.merge_request_id, report_path: reportPath });
+    if (!fs.existsSync(reportPath)) {
+        const semantic = request.result_json ? JSON.parse(request.result_json) : null;
+        const gate = readFrozenMergeGate(path.join(root, "merge-gate.json"), request.merge_request_id);
+        const accepted = readMergeGateAcceptance(context, path.join(root, "merge-gate-acceptance.json"), request, gate);
+        if (!semantic || typeof semantic.summary !== "string" || typeof semantic.verification_summary !== "string" || !Array.isArray(semantic.residual_risks) || !semantic.residual_risks.every(item => typeof item === "string") || !accepted.valid)
+            throw new AppError("merge_report_missing", "Completed MERGE has insufficient authoritative evidence to rebuild its report", 1, { merge_request_id: request.merge_request_id, report_path: reportPath });
+        verifyLocalDelivery(request);
+        performConfiguredCleanup(run, request);
+        writeStageReport(root, mergeReport(context, run, request, semantic, accepted.receipts));
+    }
     ensureMergeStageAttached(context, run, projectRoot);
     completeFlowRunStage(context, { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@2", report: "stage-report.md", stageReport: "stage-report.html" });
     const rootWork = findRootWork(context, run.project_id, run.id);
     const rootStatus = rootWork.status;
     if (rootStatus === "running")
         finishFanInWork(context, rootWork.work_id, fs.readFileSync(reportPath, "utf8"));
+    else if (rootStatus !== "completed")
+        throw new AppError("merge_root_settlement_mismatch", "Completed MERGE cannot recover a non-completed root Work", 1, { merge_request_id: request.merge_request_id, work_id: rootWork.work_id, status: rootStatus });
     const runStatus = context.db.get("SELECT status FROM runs WHERE project_id = ? AND id = ?", [run.project_id, run.id])?.status;
     if (runStatus !== "done")
         completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "merge_completed", nextAction: undefined });
     refreshRunWorkProjection(context, run.project_id, run.id);
 }
-export function routeVnextMergeRequest(context, input) { const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)); const request = requireRequest(context, input.requestId); if (request.project_id !== project.id || request.status !== "queued")
-    throw new AppError("invalid_merge_state", "Only a queued request without an active dispatch may change route", 2, { status: request.status }); context.db.exec("BEGIN IMMEDIATE"); try {
-    context.db.run("UPDATE merge_requests SET execution_route = ?, last_error_json = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'queued'", [input.mode, JSON.stringify({ route_reason: input.reason }), context.now(), request.merge_request_id]);
-    context.db.run("UPDATE works SET launch_policy = ?, updated_at = ? WHERE work_id = ? AND status = 'created'", [input.mode === "server" ? "fresh_agent_required" : "reuse_allowed", context.now(), request.executor_work_id]);
-    context.db.exec("COMMIT");
+export function routeVnextMergeRequest(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    context.db.beginWriteTransaction();
+    let request;
+    try {
+        request = requireRequest(context, input.requestId);
+        if (request.project_id !== project.id || request.status !== "queued")
+            throw new AppError("invalid_merge_state", "Only a queued request without an active dispatch may change route", 2, { status: request.status });
+        assertRunMutationAllowed(context, request.project_id, request.run_id);
+        context.db.run("UPDATE merge_requests SET execution_route = ?, last_error_json = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'queued'", [input.mode, JSON.stringify({ route_reason: input.reason }), context.now(), request.merge_request_id]);
+        context.db.run("UPDATE works SET launch_policy = ?, updated_at = ? WHERE work_id = ? AND status = 'created'", [input.mode === "server" ? "fresh_agent_required" : "reuse_allowed", context.now(), request.executor_work_id]);
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    refreshRunWorkProjection(context, request.project_id, request.run_id);
+    return requestView(context, requireRequest(context, request.merge_request_id));
 }
-catch (error) {
-    context.db.exec("ROLLBACK");
-    throw error;
-} refreshRunWorkProjection(context, request.project_id, request.run_id); return requestView(context, requireRequest(context, request.merge_request_id)); }
-function mergePrompt(context, input) { const pause = `${flowCommand(context)} stage pause ${input.run.id} --stage merge --work ${input.request.executor_work_id} --project-root ${JSON.stringify(input.projectRoot)} --question-stdin --json`; return ["<stage_identity>", `- RUN: ${input.run.id}`, `- MERGE request: ${input.request.merge_request_id}`, `- Work: ${input.request.executor_work_id}`, "- stage: merge", "</stage_identity>", "", "<trusted_runtime_context>", `- integration workspace: ${input.request.target_workspace}`, `- source workspace: ${input.request.source_workspace}`, `- frozen source commit: ${input.request.source_commit}`, `- target branch: ${input.request.target_branch}`, `- execution target baseline: ${input.request.execution_target_head}`, `- queue route: ${input.request.execution_route}`, `- delivery: ${JSON.stringify(executionSettings(input.run).merge_delivery)}`, `- cleanup: ${JSON.stringify(executionSettings(input.run).merge_cleanup)}`, "These facts and the acquired project integration lane were established by dd-flow. Do not repeat discovery and do not run git merge/rebase/squash yourself.", "</trusted_runtime_context>", "", "<effective_merge_gate>", ...effectiveMergeChecks(input.run, input.request).map((check) => `- ${check.canonical_ref ?? check.id}: ${check.command} — ${check.purpose}`), "</effective_merge_gate>", "", "<execution_contract>", `1. Run this exact standalone command first: ${applyCommand(context, input.request, input.projectRoot)}`, "2. If it reports conflicts, resolve only the actual integration conflicts in the integration workspace. Do not repeat merge apply.", `3. Write the compact semantic result to ${input.resultPath}:`, "```json", JSON.stringify({ schema_id: "dd-flow/merge-result@1", outcome: "completed", summary: "What was integrated.", conflict_resolution: "How material conflicts were resolved, or empty when none.", verification_summary: "Why the integrated result is ready for deterministic checks.", residual_risks: [] }, null, 2), "```", `4. Finish with this exact standalone command and wait for all progress: ${finishCommand(context, input.run.id, input.request, input.projectRoot)}`, "If a check fails, inspect only the returned receipt/logs, repair the integrated target in this same Work, update the semantic result, and repeat the same finish command. Do not create a repair Work or rerun independent review.", "If a material conflict has no reasonable answer in accepted evidence, pause this same Work with the exact heredoc below, ask the returned user_message, then use the exact resume command returned by CLI:", "```sh", stagePauseCommandTemplate(pause), "```", "</execution_contract>", ""].join("\n"); }
+/** Move a failed integration gate back to the source CODE/CODE-REVIEW loop. */
+export async function repairVnextMerge(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const request = requireRequest(context, input.requestId);
+    const generation = assertRunMutationAllowed(context, project.id, request.run_id);
+    if (request.project_id === project.id && request.status === "superseded" && errorCode(request) === "merge_source_repair") {
+        const saved = JSON.parse(request.last_error_json);
+        releaseMergeLane(context, projectRoot, request, `MERGE ${request.merge_request_id} moved to source repair`);
+        return { ok: true, run_id: request.run_id, merge_request_id: request.merge_request_id, status: "superseded", source_repair: { repair_work_id: saved.repair_work_id }, next: { kind: "start_stage", stage: "code", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${request.run_id} --stage code --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`) } };
+    }
+    if (request.project_id !== project.id || request.status !== "action_required" || errorCode(request) !== "merge_gate_failed") {
+        throw new AppError("invalid_merge_repair_state", "MERGE source repair requires an action-required failed integration gate", 2, { merge_request_id: input.requestId, status: request.status, code: errorCode(request) });
+    }
+    abortIntegration(request);
+    const originWorkIds = sourceCodeWorkIds(context, request.project_id, request.run_id);
+    if (!originWorkIds.length)
+        throw new AppError("runtime_missing", "MERGE source repair requires accepted CODE Work evidence", 1, { run_id: request.run_id });
+    const failed = failedReceiptIds(request);
+    if (!failed.length)
+        throw new AppError("runtime_missing", "MERGE failure has no durable failed receipt", 1, { merge_request_id: request.merge_request_id });
+    // Settle the child while its canonical result path still exists; the next
+    // step archives the entire MERGE attempt as immutable evidence.
+    const executor = context.db.get("SELECT status FROM works WHERE work_id = ?", [request.executor_work_id]);
+    if (executor?.status !== "failed")
+        await failWork(context, request.executor_work_id, `Superseded by source repair after failed integration gate ${failed[0]}.`);
+    assertRunMutationAllowed(context, project.id, request.run_id, generation);
+    const prepared = prepareVnextMergeSourceRepairAttempt(context, { projectRoot, runId: request.run_id, mergeRequestId: request.merge_request_id });
+    const repair = addVnextCodeRepair(context, { projectRoot, runId: request.run_id, checkReceiptId: failed[0], originWorkIds, reviewCycle: `MRR-${request.merge_request_id}`, objective: `Repair source behavior evidenced by failed integration check ${failed[0]}.` });
+    const now = context.now();
+    context.db.run("UPDATE merge_requests SET status = 'superseded', checkpoint = 'source_repair_required', last_error_json = ?, completed_at = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "merge_source_repair", replacement_pending: true, failed_receipt_ids: failed, repair_work_id: repair.repair_work_id }), now, now, request.merge_request_id]);
+    releaseMergeLane(context, projectRoot, request, `MERGE ${request.merge_request_id} moved to source repair`);
+    appendFlowRunTimelineEvent(context, project.id, request.run_id, { type: "merge_source_repair_created", merge_request_id: request.merge_request_id, repair_work_id: repair.repair_work_id, cycle: prepared.cycle, failed_receipt_ids: failed });
+    return { ok: true, run_id: request.run_id, merge_request_id: request.merge_request_id, status: "superseded", source_repair: repair, next: { kind: "start_stage", stage: "code", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${request.run_id} --stage code --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`) } };
+}
+function mergePrompt(context, input, checks, settings) { const pause = managedLifecycleCommand(context, `${flowCommand(context)} stage pause ${input.run.id} --stage merge --work ${input.request.executor_work_id} --project-root ${JSON.stringify(input.projectRoot)} --question-stdin --json`); const repair = `${flowCommand(context)} merge repair ${input.request.merge_request_id} --project-root ${JSON.stringify(input.projectRoot)} --json`; return ["<stage_identity>", `- RUN: ${input.run.id}`, `- MERGE request: ${input.request.merge_request_id}`, `- Work: ${input.request.executor_work_id}`, "- stage: merge", "</stage_identity>", "", "<trusted_runtime_context>", `- integration workspace: ${input.request.target_workspace}`, `- source workspace: ${input.request.source_workspace}`, `- frozen source commit: ${input.request.source_commit}`, `- target branch: ${input.request.target_branch}`, `- execution target baseline: ${input.request.execution_target_head}`, `- queue route: ${input.request.execution_route}`, `- delivery: ${JSON.stringify(settings.merge_delivery)}`, `- cleanup: ${JSON.stringify(settings.merge_cleanup)}`, "These facts and the acquired project integration lane were established by dd-flow. Do not repeat discovery and do not run git merge/rebase/squash yourself.", "</trusted_runtime_context>", "", "<effective_merge_gate>", ...checks.map((check) => `- ${check.canonical_ref ?? check.id}: ${check.command} — ${check.purpose}`), "</effective_merge_gate>", "", "<execution_contract>", `1. Run this exact standalone command first: ${applyCommand(context, input.request, input.projectRoot)}`, "2. If it reports conflicts, resolve only the actual unmerged paths in the integration workspace. Do not repeat merge apply and do not edit product code, tests, documentation or configuration merely to make a gate pass.", `3. Write the compact semantic result to ${input.resultPath}:`, "```json", JSON.stringify({ schema_id: "dd-flow/merge-result@1", outcome: "completed", summary: "What was integrated.", conflict_resolution: "How material conflicts were resolved, or empty when none.", verification_summary: "Why the integrated result is ready for deterministic checks.", residual_risks: [] }, null, 2), "```", `4. Finish with this exact standalone command and wait for all progress: ${finishCommand(context, input.run.id, input.request, input.projectRoot)}`, `If a gate fails, read its receipt and logs and determine the cause. For a product defect use ${repair}; it restores the target baseline and opens CODE → independent CODE-REVIEW → replacement MRG. For an environment failure restore the declared environment in this MERGE and use the returned finish command with --retry-check <receipt-id> --reason "<what was restored>". The CLI reruns the real gate and retains the old receipt. Never edit product code in the integration target to make a gate pass.`, "If a material conflict has no reasonable answer in accepted evidence, pause this same Work with the exact heredoc below, ask the returned user_message, then use the exact resume command returned by CLI:", "```sh", stagePauseCommandTemplate(pause), "```", "</execution_contract>", ""].join("\n"); }
 function mergeReport(context, run, request, semantic, receipts) { const now = context.now(); const cleanup = cleanupReceiptPath(run); return { schema_id: "dd-flow/stage-report@2", run_id: run.id, stage, generated_at: now, verdict: "done", summary: semantic.summary, semantic: { result: semantic.summary, acceptance: ["source_commit_frozen", "integration_commit_created", "merge_gate_passed", "delivery_confirmed"], changed_files: [], checks: receipts.map((item) => item.command), evidence: [applyReceiptPath(context, request), ...receipts.map((item) => item.receipt_path), ...(fs.existsSync(cleanup) ? [cleanup] : [])], next_action: "merge_completed", merge: { merge_request_id: request.merge_request_id, work_id: request.executor_work_id, protocols: JSON.parse(request.protocol_ids_json), source_commit: request.source_commit, execution_target_head: request.execution_target_head, accepted_tree: request.accepted_tree, integration_commit: request.integration_commit, route: request.execution_route, delivery: executionSettings(run).merge_delivery, cleanup: executionSettings(run).merge_cleanup, verification_summary: semantic.verification_summary, residual_risks: semantic.residual_risks } }, mechanical: { started_at: request.lock_acquired_at, finished_at: now, git: gitFacts(request.target_workspace), queue: queueStatus(context, request) }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html" }, validation: { status: "passed" } }; }
 function effectiveMergeChecks(run, request) { return readFrozenMergeGate(path.join(requireHome(run), stageDir, "merge-gate.json"), request.merge_request_id).checks; }
 function planChecks(workspace, protocols) { return protocols.flatMap((protocol) => { const file = path.join(workspace, ".memory-bank", "protocol", protocol, "plan.json"); if (!fs.existsSync(file))
     return []; const plan = JSON.parse(fs.readFileSync(file, "utf8")); return (plan.checks ?? []).filter((check) => check.availability === "available").map((check) => ({ ...check, canonical_ref: `${protocol}/${check.id}` })); }); }
 function validateMergeAcceptance(workspace, protocols, checks) { const known = new Set(checks.map((check) => check.canonical_ref)); const missing = mergeAcceptanceRefs(workspace, protocols).filter((ref) => !known.has(ref)); if (missing.length)
     throw new AppError("merge_acceptance_invalid", "A merge acceptance criterion references a missing check", 2, { check_refs: missing }); }
-function freezeMergeGate(file, input) { const canonical = JSON.stringify(input.checks); const hash = cryptoHash(canonical); if (fs.existsSync(file)) {
+function freezeMergeGate(file, input) { const canonical = JSON.stringify({ checks: input.checks, acceptance_refs: [...input.acceptanceRefs].sort() }); const hash = cryptoHash(canonical); if (fs.existsSync(file)) {
     const existing = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (existing.run_id !== input.runId || existing.checks_hash !== hash)
+    if (existing.run_id !== input.runId || existing.gate_hash !== hash)
         throw new AppError("merge_gate_freeze_conflict", "MERGE gate is already frozen with different checks", 2, { file });
     return;
-} fs.writeFileSync(file, `${JSON.stringify({ schema_id: "dd-flow/merge-gate@1", run_id: input.runId, protocols: input.protocols, checks: input.checks, checks_hash: hash, profile_hash: input.profileHash, frozen_at: input.now }, null, 2)}\n`); }
+} fs.writeFileSync(file, `${JSON.stringify({ schema_id: "dd-flow/merge-gate@2", run_id: input.runId, protocols: input.protocols, checks: input.checks, acceptance_refs: [...input.acceptanceRefs].sort(), gate_hash: hash, profile_hash: input.profileHash, frozen_at: input.now }, null, 2)}\n`); }
 function readFrozenMergeGate(file, requestId) { try {
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (value.schema_id !== "dd-flow/merge-gate@1" || !Array.isArray(value.checks) || value.checks_hash !== cryptoHash(JSON.stringify(value.checks)))
+    if (value.schema_id !== "dd-flow/merge-gate@2" || !Array.isArray(value.checks) || !Array.isArray(value.acceptance_refs) || !value.acceptance_refs.every(ref => typeof ref === "string") || typeof value.gate_hash !== "string" || value.gate_hash !== cryptoHash(JSON.stringify({ checks: value.checks, acceptance_refs: [...value.acceptance_refs].sort() })))
         throw new Error("invalid gate");
-    return { checks: value.checks };
+    return { checks: value.checks, acceptanceRefs: [...value.acceptance_refs].sort(), profileHash: value.profile_hash ?? null, gateHash: value.gate_hash };
 }
 catch (cause) {
     throw new AppError("merge_gate_missing", "MERGE gate is missing or invalid", 1, { merge_request_id: requestId, file, cause: String(cause) });
 } }
+function frozenGateRefs(gate) { return [...new Set([...gate.checks.map(check => check.canonical_ref ?? check.id), ...gate.acceptanceRefs])].sort(); }
+function writeMergeGateAcceptance(context, file, request, gate, acceptedTree, receipts) { const persisted = new Map(checkReceipts(context, { projectId: request.project_id, runId: request.run_id }).map(receipt => [receipt.id, receipt])); const value = { schema_id: "dd-flow/merge-gate-acceptance@2", merge_request_id: request.merge_request_id, run_id: request.run_id, work_id: request.executor_work_id, gate_hash: gate.gateHash, profile_hash: gate.profileHash, accepted_tree: acceptedTree, receipts: receipts.map(receipt => ({ id: receipt.id, execution_refs: [...(persisted.get(receipt.id)?.check_refs ?? receipt.check_refs)].sort(), binding_refs: [...receipt.check_refs].sort(), input_hash: receipt.input_hash })) }; const temporary = `${file}.tmp-${process.pid}-${crypto.randomUUID()}`; fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`); fs.renameSync(temporary, file); }
+function readMergeGateAcceptance(context, file, request, gate) { try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (value.schema_id !== "dd-flow/merge-gate-acceptance@2" || value.merge_request_id !== request.merge_request_id || value.run_id !== request.run_id || value.work_id !== request.executor_work_id || value.gate_hash !== gate.gateHash || value.profile_hash !== gate.profileHash || value.accepted_tree !== request.accepted_tree || !Array.isArray(value.receipts) || !value.receipts.every(receipt => receipt && typeof receipt.id === "string" && typeof receipt.input_hash === "string" && Array.isArray(receipt.execution_refs) && receipt.execution_refs.every(ref => typeof ref === "string") && Array.isArray(receipt.binding_refs) && receipt.binding_refs.every(ref => typeof ref === "string")))
+        return { valid: false, receipts: [] };
+    const all = checkReceipts(context, { projectId: request.project_id, runId: request.run_id });
+    const receipts = value.receipts.map(saved => all.find(receipt => receipt.id === saved.id && receipt.input_hash === saved.input_hash && JSON.stringify([...receipt.check_refs].sort()) === JSON.stringify(saved.execution_refs))).filter((receipt) => Boolean(receipt));
+    const bindingRefs = value.receipts.flatMap(receipt => receipt.binding_refs);
+    const bindings = new Set(bindingRefs);
+    const expected = frozenGateRefs(gate);
+    if (receipts.length !== value.receipts.length || bindingRefs.length !== bindings.size || !receipts.every(checkReceiptEvidenceValid) || JSON.stringify([...bindings].sort()) !== JSON.stringify(expected) || gitValue(request.target_workspace, ["write-tree"]) !== value.accepted_tree)
+        return { valid: false, receipts: [] };
+    return { valid: true, receipts: receipts.map((receipt, index) => ({ ...receipt, check_refs: value.receipts[index].binding_refs })) };
+}
+catch {
+    return { valid: false, receipts: [] };
+} }
 function cryptoHash(value) { return crypto.createHash("sha256").update(value).digest("hex"); }
 function mergeAcceptanceRefs(workspace, protocols) { return protocols.flatMap((protocol) => { const file = path.join(workspace, ".memory-bank", "protocol", protocol, "plan.json"); if (!fs.existsSync(file))
     return []; const plan = JSON.parse(fs.readFileSync(file, "utf8")); return (plan.acceptance ?? []).filter((entry) => entry.gate === "merge").flatMap((entry) => (entry.check_refs ?? []).map((ref) => `${protocol}/${ref}`)); }); }
@@ -333,9 +477,14 @@ function protocolIds(home) { const root = path.join(home, "03-plan"); if (!fs.ex
 function workspaceRoute(home) { const file = path.join(home, "02-protocolize", "workspace-route.json"); const value = JSON.parse(fs.readFileSync(file, "utf8")); if (!value.policy?.integration_branch)
     throw new AppError("workspace_route_missing", "MERGE requires the frozen integration branch", 1, { file }); return { integration_branch: value.policy.integration_branch }; }
 function executionSettings(run) { return JSON.parse(run.index_json).execution_profile?.settings ?? {}; }
-function runBootstrap(run, cwd) { const command = executionSettings(run).code_bootstrap?.command; if (!command)
-    return; const result = spawnSync("/bin/sh", ["-lc", command], { cwd, encoding: "utf8" }); if (result.status !== 0)
-    throw new AppError("merge_bootstrap_failed", "Integrated target bootstrap failed", 2, { command, stdout: result.stdout, stderr: result.stderr, status: result.status }); }
+async function runBootstrap(context, run, cwd, mergeId, progress) {
+    const command = executionSettings(run).code_bootstrap?.command;
+    if (!command)
+        throw new AppError("execution_profile_invalid", "MERGE requires a frozen workspace bootstrap command", 2);
+    const result = await runWorkspaceBootstrap(context, { projectId: run.project_id, runId: run.id, runHome: requireHome(run), workspaceRoot: cwd, command, artifactDir: `${stageDir}/${mergeId}/readiness`, progress });
+    if (result.exit_code !== 0 || result.error)
+        throw new AppError("merge_bootstrap_failed", "Integrated target bootstrap failed; inspect its retained logs", 2, { command, ...result });
+}
 function verifyLocalDelivery(request) { const head = gitValue(request.target_workspace, ["rev-parse", request.target_branch]); if (!request.integration_commit || head !== request.integration_commit)
     throw new AppError("merge_delivery_unproven", "Local integration branch does not resolve to the accepted integration commit", 1, { target_branch: request.target_branch, expected: request.integration_commit, actual: head }); }
 function cleanupReceiptPath(run) { return path.join(requireHome(run), stageDir, "cleanup-receipt.json"); }
@@ -363,24 +512,27 @@ function releaseMergeLane(context, projectRoot, request, reason) {
     try {
         releaseLaneLock(context, { projectRoot, lane: "merge", workerId: request.executor_work_id, workspacePath: request.target_workspace, reason });
     }
-    catch { /* An expired lease cannot invalidate an already completed MERGE. */ }
+    catch (error) {
+        // An absent/replaced lease is already no longer ours. Storage and other
+        // failures must remain visible so a repeated operation can release it.
+        if (!(error instanceof AppError) || !["lane_lock_not_active", "lane_lock_owned_by_other_worker"].includes(error.code))
+            throw error;
+    }
 }
-function queueAhead(context, request) { return context.db.get("SELECT COUNT(*) AS count FROM merge_requests WHERE project_id = ? AND status NOT IN ('completed','failed','cancelled') AND (created_at < ? OR (created_at = ? AND merge_request_id < ?))", [request.project_id, request.created_at, request.created_at, request.merge_request_id])?.count ?? 0; }
+function queueAhead(context, request) { return context.db.get("SELECT COUNT(*) AS count FROM merge_requests WHERE project_id = ? AND status NOT IN ('completed','failed','cancelled','superseded') AND (created_at < ? OR (created_at = ? AND merge_request_id < ?))", [request.project_id, request.created_at, request.created_at, request.merge_request_id])?.count ?? 0; }
 function queueStatus(context, request) { return { position: queueAhead(context, request) + 1, requests_ahead: queueAhead(context, request), status: request.status, route: request.execution_route }; }
 function requireOwnedActiveRequest(context, input) { const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)); const request = requireRequest(context, input.requestId); if (request.project_id !== project.id || request.executor_work_id !== input.workId || !["active", "action_required"].includes(request.status))
     throw new AppError("invalid_merge_state", "MRG/Work/project is not the active integration owner", 2, { merge_request_id: input.requestId, work_id: input.workId, status: request.status }); return request; }
 function assertExecutionBaseline(request) { const head = gitValue(request.target_workspace, ["rev-parse", "HEAD"], true); if (request.checkpoint === "baseline_locked" && head !== request.execution_target_head)
     throw new AppError("merge_target_changed", "Integration target changed after the lane baseline was locked", 1, { expected: request.execution_target_head, actual: head }); }
 function recovery(context, request, code, detail) { context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code, detail }), context.now(), request.merge_request_id]); throw new AppError("merge_recovery_required", "MERGE mutation could not be reconciled automatically", 1, { merge_request_id: request.merge_request_id, code, detail }); }
-function commitPendingSource(cwd, runId, ignored) { const paths = meaningfulStatus(cwd, ignored).map(statusPath); if (!paths.length)
+function commitPendingSource(cwd, runId, ignored) { const paths = meaningfulStatus(cwd, ignored); if (!paths.length)
     return; git(cwd, ["add", "-A", "--", ...paths]); git(cwd, ["commit", "-m", `chore(${runId.toLowerCase()}): freeze accepted source`]); }
-function commitIntegration(cwd, runId, ignored) { const mergeHead = fs.existsSync(path.join(gitDirectory(cwd), "MERGE_HEAD")); const paths = meaningfulStatus(cwd, ignored).map(statusPath); if (!mergeHead && !paths.length)
+function commitIntegration(cwd, runId, ignored) { const mergeHead = fs.existsSync(path.join(gitDirectory(cwd), "MERGE_HEAD")); const paths = meaningfulStatus(cwd, ignored); if (!mergeHead && !paths.length)
     return; if (paths.length)
     git(cwd, ["add", "-A", "--", ...paths]); git(cwd, ["commit", "-m", `merge(${runId.toLowerCase()}): integrate accepted source`]); }
 function ignoredGitPaths(context, projectId) { return [readProjectConfig(context, projectId).dashboard.markdown_path.replaceAll("\\", "/")]; }
-function meaningfulStatus(cwd, ignored) { const result = spawnSync("git", ["status", "--porcelain=v1", "--untracked-files=all"], { cwd, encoding: "utf8" }); if (result.status !== 0)
-    return []; return result.stdout.split(/\r?\n/).filter(Boolean).filter((line) => !ignored.includes(statusPath(line))); }
-function statusPath(line) { const value = line.slice(3); const renamed = value.includes(" -> ") ? value.slice(value.lastIndexOf(" -> ") + 4) : value; return renamed.replace(/^"|"$/g, ""); }
+function meaningfulStatus(cwd, ignored) { return workspaceChangedPaths(cwd).filter((item) => !ignored.includes(item)); }
 function unmerged(cwd) { const value = gitValue(cwd, ["diff", "--name-only", "--diff-filter=U"], true); return value.split(/\r?\n/).filter(Boolean); }
 function gitDirectory(cwd) { const value = gitValue(cwd, ["rev-parse", "--git-dir"]); return path.resolve(cwd, value); }
 function git(cwd, args) { try {
@@ -392,11 +544,42 @@ catch (error) {
 function gitValue(cwd, args, allowFailure = false) { const result = spawnSync("git", args, { cwd, encoding: "utf8" }); if (result.status !== 0 && !allowFailure)
     throw new AppError("git_operation_failed", `git ${args[0]} failed`, 1, { cwd, args, stderr: result.stderr }); return result.status === 0 ? result.stdout.trim() : ""; }
 function applyReceiptPath(context, request) { const run = requireRun(context, request.project_id, request.run_id); return path.join(requireHome(run), stageDir, "works", request.executor_work_id, "apply-receipt.json"); }
-function requestForRun(context, projectId, runId) { const request = context.db.get("SELECT * FROM merge_requests WHERE project_id = ? AND run_id = ? ORDER BY created_at LIMIT 1", [projectId, runId]); if (!request)
+function requestForRun(context, projectId, runId) { const request = context.db.get("SELECT * FROM merge_requests WHERE project_id = ? AND run_id = ? ORDER BY created_at DESC LIMIT 1", [projectId, runId]); if (!request)
     throw new AppError("merge_request_missing", "MERGE request was not materialized by the prior terminal stage", 1, { run_id: runId }); return request; }
 function requireRequest(context, id) { const request = context.db.get("SELECT * FROM merge_requests WHERE merge_request_id = ?", [id]); if (!request)
     throw new AppError("not_found", "MERGE request is not registered", 1, { merge_request_id: id }); return request; }
-function requestView(context, request) { return { ok: true, merge_request_id: request.merge_request_id, run_id: request.run_id, work_id: request.executor_work_id, protocols: JSON.parse(request.protocol_ids_json), source: { workspace: request.source_workspace, branch: request.source_branch, commit: request.source_commit }, target: { workspace: request.target_workspace, branch: request.target_branch, enqueue_head: request.enqueue_target_head, execution_head: request.execution_target_head, accepted_tree: request.accepted_tree, integration_commit: request.integration_commit }, route: request.execution_route, status: request.status, checkpoint: request.checkpoint, queue: queueStatus(context, request), created_at: request.created_at, completed_at: request.completed_at }; }
+function requestView(context, request) { return { ok: true, merge_request_id: request.merge_request_id, run_id: request.run_id, work_id: request.executor_work_id, protocols: JSON.parse(request.protocol_ids_json), source: { workspace: request.source_workspace, branch: request.source_branch, commit: request.source_commit }, target: { workspace: request.target_workspace, branch: request.target_branch, enqueue_head: request.enqueue_target_head, execution_head: request.execution_target_head, accepted_tree: request.accepted_tree, integration_commit: request.integration_commit }, route: request.execution_route, status: request.status, checkpoint: request.checkpoint, ...(request.replacement_of_merge_request_id ? { replacement_of_merge_request_id: request.replacement_of_merge_request_id } : {}), queue: queueStatus(context, request), created_at: request.created_at, completed_at: request.completed_at }; }
+function replacementOf(run) { try {
+    const variables = JSON.parse(run.index_json).variables;
+    const repair = variables?.["merge.source_repair"];
+    return repair && typeof repair === "object" && !Array.isArray(repair) && typeof repair.merge_request_id === "string" ? String(repair.merge_request_id) : null;
+}
+catch {
+    return null;
+} }
+function errorCode(request) { try {
+    const value = JSON.parse(request.last_error_json ?? "{}");
+    return typeof value?.code === "string" ? value.code : null;
+}
+catch {
+    return null;
+} }
+function failedReceiptIds(request) { try {
+    const value = JSON.parse(request.last_error_json ?? "{}");
+    return (value.failures ?? []).flatMap((failure) => typeof failure === "object" && failure !== null && typeof failure.id === "string" ? [String(failure.id)] : []);
+}
+catch {
+    return [];
+} }
+function sourceCodeWorkIds(context, projectId, runId) { return context.db.all("SELECT work_id, payload_json FROM works WHERE project_id = ? AND run_id = ? AND status = 'completed' ORDER BY created_at, work_id", [projectId, runId]).flatMap((work) => { try {
+    return JSON.parse(work.payload_json ?? "").schema_id === "dd-flow/code-work-packet@5" ? [work.work_id] : [];
+}
+catch {
+    return [];
+} }); }
+function abortIntegration(request) { if (gitValue(request.target_workspace, ["rev-parse", "-q", "--verify", "MERGE_HEAD"], true))
+    git(request.target_workspace, ["merge", "--abort"]); const head = gitValue(request.target_workspace, ["rev-parse", "HEAD"]); const branch = gitValue(request.target_workspace, ["branch", "--show-current"]); const dirty = meaningfulStatus(request.target_workspace, []); if (head !== request.execution_target_head || branch !== request.target_branch || dirty.length)
+    throw new AppError("merge_recovery_required", "Integration workspace could not be restored to its locked baseline", 1, { merge_request_id: request.merge_request_id, expected_head: request.execution_target_head, head, expected_branch: request.target_branch, branch, dirty }); }
 function requireRun(context, projectId, runId) { const run = context.db.get("SELECT id, project_id, project_root, workspace_root, run_root, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]); if (!run)
     throw new AppError("not_found", "RUN is not registered", 1); return run; }
 function requireHome(run) { if (!run.run_root)
@@ -406,4 +589,4 @@ function findRootWork(context, projectId, runId) { const work = context.db.get("
 function requireRootWork(context, projectId, runId) { const work = findRootWork(context, projectId, runId); if (work.status !== "running")
     throw new AppError("runtime_missing", "vNext RUN has no running root Work", 1); return work; }
 function applyCommand(context, request, projectRoot) { return `${flowCommand(context)} merge apply ${request.merge_request_id} --work ${request.executor_work_id} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`; }
-function finishCommand(context, runId, request, projectRoot) { return `${flowCommand(context)} stage finish ${runId} --stage merge --request ${request.merge_request_id} --work ${request.executor_work_id} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`; }
+export function finishCommand(context, runId, request, projectRoot, retryCheckId) { const retry = retryCheckId ? ` --retry-check ${retryCheckId} --reason "<environment recovery evidence>"` : ""; return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage merge --request ${request.merge_request_id} --work ${request.executor_work_id} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl${retry}`); }