@deksden-com/dd-flow-cli 0.9.0-beta.0 → 0.9.0-beta.10

package/dist/services/vnext-merge.js

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync, spawnSync } from "node:child_process";
@@ -14,6 +15,7 @@ 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";
 const stage = "merge";
 const stageDir = vnextStageDirectory(stage);
 export function isVnextMergeRun(context, input) {
@@ -35,18 +37,51 @@ export function ensureVnextMergeRequest(context, input) {
     const sourceBranch = gitValue(run.workspace_root, ["branch", "--show-current"]);
     if (!sourceBranch)
         throw new AppError("merge_source_invalid", "MERGE requires a named source branch", 1, { workspace_root: run.workspace_root });
-    commitPendingSource(run.workspace_root, run.id, ignoredGitPaths(context, project.id));
-    const sourceCommit = gitValue(run.workspace_root, ["rev-parse", "HEAD"]);
     const targetBranch = workspaceRoute(home).integration_branch;
-    if (!sourceCommit || !targetBranch)
-        throw new AppError("merge_source_invalid", "MERGE could not freeze source commit or target branch", 1, { source_commit: sourceCommit, target_branch: targetBranch });
     const targetWorkspace = projectRoot;
-    const enqueueTarget = gitValue(targetWorkspace, ["rev-parse", targetBranch], true);
+    // Validate every immutable prerequisite before touching the source tree. A
+    // rejected MERGE handoff must not leave a new commit behind or let a caller
+    // subsequently mark CODE/CODE-REVIEW complete without a queue request.
+    if (!targetBranch)
+        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 effective = effectiveCheckDeclarations(run.workspace_root, semantic, ["merge"]);
+    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 });
+    const ignored = ignoredGitPaths(context, project.id);
+    const accepted = input.acceptedPaths ? [...new Set(input.acceptedPaths.filter((item) => !ignored.includes(item)))].sort() : null;
+    const freezeRoot = path.join(home, stageDir);
+    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() });
+    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)))
+            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();
+        if (accepted) {
+            const unexpected = sourcePaths.filter((item) => !accepted.includes(item));
+            const absent = accepted.filter((item) => !sourcePaths.includes(item));
+            if (unexpected.length || absent.length)
+                throw new AppError("merge_source_drift", "MERGE source differs from the accepted terminal-stage file set", 2, { unexpected, absent });
+        }
+        const sourceFingerprint = workspaceFingerprint(run.workspace_root);
+        commitPendingSource(run.workspace_root, run.id, ignored);
+        sourceCommit = gitValue(run.workspace_root, ["rev-parse", "HEAD"]);
+        if (sourceCommit)
+            fs.writeFileSync(freezeFile, `${JSON.stringify({ schema_id: "dd-flow/merge-source-freeze@1", run_id: run.id, source_workspace: run.workspace_root, source_branch: sourceBranch, source_commit: sourceCommit, precommit_workspace_fingerprint: sourceFingerprint, paths: sourcePaths, at: context.now() }, null, 2)}\n`);
+    }
+    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;
@@ -83,38 +118,50 @@ export async function startVnextMerge(context, input) {
     fs.mkdirSync(workRoot, { recursive: true });
     const resultPath = path.join(workRoot, "result.json");
     const promptPath = path.join(workRoot, "prompt.md");
-    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))
-            fs.writeFileSync(promptPath, prompt);
+    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 {
+        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))
+                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);
+        }
+        const current = requireRequest(context, request.merge_request_id);
+        const targetHead = gitValue(current.target_workspace, ["rev-parse", current.target_branch], true);
+        const checkedOutTarget = gitValue(current.target_workspace, ["branch", "--show-current"], true);
+        if (checkedOutTarget !== current.target_branch)
+            throw new AppError("merge_target_branch_mismatch", "Integration workspace is not on the configured target branch", 1, { expected: current.target_branch, actual: checkedOutTarget, target_workspace: current.target_workspace });
+        const targetStatus = meaningfulStatus(current.target_workspace, ignoredGitPaths(context, project.id));
+        if (targetStatus.length)
+            throw new AppError("merge_target_dirty", "Integration workspace must be clean before MERGE starts", 1, { target_workspace: current.target_workspace, status: targetStatus });
+        const claimed = context.db.run("UPDATE merge_requests SET status = 'active', execution_target_head = ?, lock_acquired_at = ?, checkpoint = 'baseline_locked', updated_at = ? WHERE merge_request_id = ? AND status IN ('queued','dispatching','action_required')", [targetHead, context.now(), context.now(), current.merge_request_id]);
+        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 });
+        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);
+        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);
+    }
+    catch (error) {
+        const latest = requireRequest(context, request.merge_request_id);
+        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;
     }
-    await waitForTurn(context, request, input.progress);
-    const current = requireRequest(context, request.merge_request_id);
-    const targetHead = gitValue(current.target_workspace, ["rev-parse", current.target_branch], true);
-    const checkedOutTarget = gitValue(current.target_workspace, ["branch", "--show-current"], true);
-    if (checkedOutTarget !== current.target_branch)
-        throw new AppError("merge_target_branch_mismatch", "Integration workspace is not on the configured target branch", 1, { expected: current.target_branch, actual: checkedOutTarget, target_workspace: current.target_workspace });
-    const targetStatus = meaningfulStatus(current.target_workspace, ignoredGitPaths(context, project.id));
-    if (targetStatus.length)
-        throw new AppError("merge_target_dirty", "Integration workspace must be clean before MERGE starts", 1, { target_workspace: current.target_workspace, status: targetStatus });
-    const claimed = context.db.run("UPDATE merge_requests SET status = 'active', execution_target_head = ?, lock_acquired_at = ?, checkpoint = 'baseline_locked', updated_at = ? WHERE merge_request_id = ? AND status IN ('queued','dispatching','action_required')", [targetHead, context.now(), context.now(), current.merge_request_id]);
-    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 });
-    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);
 }
 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) } };
@@ -125,6 +172,7 @@ export function applyVnextMerge(context, input) {
     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);
+    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}`);
     let outcome = "applied_clean";
@@ -157,6 +205,7 @@ export async function finishVnextMerge(context, input) {
         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 (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)))
@@ -164,22 +213,11 @@ export async function finishVnextMerge(context, input) {
     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 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 });
+    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")
         throw new AppError("merge_semantic_blocked", "A blocked semantic result cannot complete MERGE", 2, { result_path: resultPath });
-    if (!["integration_committed", "bootstrap_ready", "checks_passed", "delivered", "finalized"].includes(request.checkpoint)) {
-        commitIntegration(request.target_workspace, run.id, ignoredGitPaths(context, project.id));
-        const commit = gitValue(request.target_workspace, ["rev-parse", "HEAD"]);
-        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);
-    }
-    else if (meaningfulStatus(request.target_workspace, ignoredGitPaths(context, project.id)).length) {
-        commitIntegration(request.target_workspace, `${run.id}-fix`, ignoredGitPaths(context, project.id));
-        context.db.run("UPDATE merge_requests SET integration_commit = ?, checkpoint = 'integration_committed', updated_at = ? WHERE merge_request_id = ?", [gitValue(request.target_workspace, ["rev-parse", "HEAD"]), context.now(), request.merge_request_id]);
-        request = requireRequest(context, request.merge_request_id);
-    }
-    if (request.checkpoint === "integration_committed") {
+    if (request.checkpoint === "apply_recorded") {
         input.progress?.("bootstrapping integrated target");
         runBootstrap(run, request.target_workspace);
         context.db.run("UPDATE merge_requests SET checkpoint = 'bootstrap_ready', updated_at = ? WHERE merge_request_id = ?", [context.now(), request.merge_request_id]);
@@ -200,8 +238,19 @@ export async function finishVnextMerge(context, input) {
     const missingRefs = requiredRefs.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 });
-    context.db.run("UPDATE merge_requests SET checkpoint = 'checks_passed', status = 'active', updated_at = ? WHERE merge_request_id = ?", [context.now(), request.merge_request_id]);
+    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);
+    if (!request.integration_commit) {
+        commitIntegration(request.target_workspace, run.id, ignoredGitPaths(context, project.id));
+        const commit = gitValue(request.target_workspace, ["rev-parse", "HEAD"]);
+        const committedTree = gitValue(request.target_workspace, ["rev-parse", "HEAD^{tree}"]);
+        if (!request.accepted_tree || committedTree !== request.accepted_tree) {
+            return recovery(context, request, "merge_commit_tree_drift", { accepted_tree: request.accepted_tree, committed_tree: committedTree, integration_commit: commit });
+        }
+        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);
+    }
     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);
@@ -218,6 +267,7 @@ export async function finishVnextMerge(context, input) {
     completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "merge_completed", nextAction: undefined });
     refreshRunWorkProjection(context, project.id, run.id);
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "merge_completed", merge_request_id: request.merge_request_id, integration_commit: requireRequest(context, request.merge_request_id).integration_commit });
+    releaseMergeLane(context, projectRoot, request, `MERGE ${request.merge_request_id} completed`);
     return { ok: true, run_id: run.id, stage, outcome: "completed", merge_request_id: request.merge_request_id, work_id: request.executor_work_id, integration_commit: requireRequest(context, request.merge_request_id).integration_commit, report_path: path.join(root, "stage-report.json"), next_action: "merge_completed" };
 }
 export function getVnextMergeRequest(context, input) { const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)); const request = input.requestId ? requireRequest(context, input.requestId) : input.runId ? requestForRun(context, project.id, input.runId) : null; if (!request || request.project_id !== project.id)
@@ -254,12 +304,28 @@ catch (error) {
     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"); }
-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, 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 effectiveCheckDeclarations(request.target_workspace, planChecks(run.workspace_root, JSON.parse(request.protocol_ids_json)), ["merge"]); }
+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.run_at === "merge").map((check) => ({ ...check, canonical_ref: `${protocol}/${check.id}` })); }); }
+    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 non-merge check", 2, { check_refs: missing }); }
+    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)) {
+    const existing = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (existing.run_id !== input.runId || existing.checks_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`); }
+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)))
+        throw new Error("invalid gate");
+    return { checks: value.checks };
+}
+catch (cause) {
+    throw new AppError("merge_gate_missing", "MERGE gate is missing or invalid", 1, { merge_request_id: requestId, file, cause: String(cause) });
+} }
+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}`)); }); }
 function protocolIds(home) { const root = path.join(home, "03-plan"); if (!fs.existsSync(root))
@@ -277,15 +343,28 @@ function performConfiguredCleanup(run, request) {
     const policy = executionSettings(run).merge_cleanup?.source ?? "retain";
     const receipt = cleanupReceiptPath(run);
     let action = "retained";
-    if (policy === "delete_after_success" && path.resolve(request.source_workspace) !== path.resolve(request.target_workspace)) {
-        git(request.target_workspace, ["worktree", "remove", request.source_workspace]);
-        git(request.target_workspace, ["branch", "-d", request.source_branch]);
-        action = "deleted";
+    let error = null;
+    try {
+        if (policy === "delete_after_success" && path.resolve(request.source_workspace) !== path.resolve(request.target_workspace)) {
+            git(request.target_workspace, ["worktree", "remove", request.source_workspace]);
+            git(request.target_workspace, ["branch", "-d", request.source_branch]);
+            action = "deleted";
+        }
+    }
+    catch (cause) {
+        // Cleanup is post-delivery hygiene. It must never invalidate an integration
+        // commit which already passed the merge gate and was delivered.
+        action = "action_required";
+        error = cause instanceof Error ? cause.message : String(cause);
+    }
+    fs.writeFileSync(receipt, `${JSON.stringify({ schema_id: "dd-flow/merge-cleanup-receipt@1", merge_request_id: request.merge_request_id, policy, action, source_workspace: request.source_workspace, source_branch: request.source_branch, ...(error ? { error } : {}), at: new Date().toISOString() }, null, 2)}\n`);
+}
+function releaseMergeLane(context, projectRoot, request, reason) {
+    try {
+        releaseLaneLock(context, { projectRoot, lane: "merge", workerId: request.executor_work_id, workspacePath: request.target_workspace, reason });
     }
-    fs.writeFileSync(receipt, `${JSON.stringify({ schema_id: "dd-flow/merge-cleanup-receipt@1", merge_request_id: request.merge_request_id, policy, action, source_workspace: request.source_workspace, source_branch: request.source_branch, at: new Date().toISOString() }, null, 2)}\n`);
+    catch { /* An expired lease cannot invalidate an already completed MERGE. */ }
 }
-function waitForTurn(context, request, progress) { return new Promise((resolve) => { const poll = () => { const current = requireRequest(context, request.merge_request_id); const ahead = queueAhead(context, current); const active = context.db.get("SELECT merge_request_id FROM merge_requests WHERE project_id = ? AND status IN ('active','action_required','recovery_required') AND merge_request_id <> ? LIMIT 1", [current.project_id, current.merge_request_id]); if (ahead === 0 && !active)
-    return resolve(); progress?.(`MERGE ${current.merge_request_id} is waiting: ${ahead} request(s) ahead; next update in 15 seconds`); setTimeout(poll, 15_000); }; poll(); }); }
 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 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))
@@ -317,11 +396,11 @@ function requestForRun(context, projectId, runId) { const request = context.db.g
     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, 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 requireRun(context, projectId, runId) { const run = context.db.get("SELECT id, project_id, project_root, workspace_root, run_home_path, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]); if (!run)
+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 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_home_path)
-    throw new AppError("runtime_missing", "RUN workspace is unavailable", 1); return run.run_home_path; }
+function requireHome(run) { if (!run.run_root)
+    throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1); return run.run_root; }
 function findRootWork(context, projectId, runId) { const work = context.db.get("SELECT * FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NULL ORDER BY created_at LIMIT 1", [projectId, runId]); if (!work)
     throw new AppError("runtime_missing", "vNext RUN has no root Work", 1); return work; }
 function requireRootWork(context, projectId, runId) { const work = findRootWork(context, projectId, runId); if (work.status !== "running")