@deksden-com/dd-flow-cli 0.9.0-beta.1 → 0.9.0-beta.100

package/dist/services/vnext-code.js

@@ -1,43 +1,68 @@
-import crypto from "node:crypto";
-import { spawn } from "node:child_process";
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
+import { ensureAggregateRepair, ensureRepairIntent } from "./repair-intents.js";
+import { runWorkspaceBootstrap } from "./workspace-bootstrap.js";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
-import { aggregateCheckDeclarations, checkReceipts, codeExecutionEnvironment, finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceFingerprint } from "./code-checks.js";
+import { aggregateCheckDeclarations, effectiveCheckDeclarations, finalCodeCheckDeclarations, runCodeChecks, validateFailedCheckRetry, workspaceChangedPaths } from "./code-checks.js";
 import { requireProjectByRoot } from "./projects.js";
-import { appendFlowRunTimelineEvent, advanceFlowRun, attachFlowRunStage, completeFlowRunStage, completeFlowRun, getFlowRunVariables, gitFacts } from "./runs.js";
+import { appendFlowRunTimelineEvent, advanceFlowRun, attachFlowRunStage, prepareFlowRunStageAttachment, completeFlowRunStage, completeFlowRun, withStageSettlement, getFlowRunVariables, gitFacts } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
-import { flowCommand } from "./stage-pause.js";
+import { runtimeCommand, checkRetryArgs } from "./runtime-command.js";
+import { stageCycle, stageGraphScope } from "./stage-work-graph.js";
 import { validateVnextCodeHandoff } from "./vnext-plan.js";
 import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
 import { readVnextSpecifyResult } from "./vnext-specify.js";
-import { addWorkBatch, bindStageCoordinatorWork, codeWorkGraph, finishWork, refreshRunWorkProjection, validateWorkBatchFile, workStartCommand } from "./work-registry.js";
+import { addWorkBatch, prepareWorkBatch, bindStageCoordinatorWork, codeWorkGraph, finishStageCoordinatorWork, refreshRunWorkProjection, validateWorkBatchFile, workStartCommand } from "./work-registry.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { writeStageReport } from "./stage-report-renderer.js";
-import { ensureVnextMergeRequest } from "./vnext-merge.js";
+import { prepareVnextMergeRequest } from "./vnext-merge.js";
 import { assertStageStartHookEvent } from "./hooks.js";
-import { applyExternalStageContext } from "./stage-context.js";
+import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
 const stage = "code";
 const stageDir = vnextStageDirectory("code");
-export async function startVnextCode(context, input) {
+/** A controller prepares slow, deterministic project tooling before it asks an
+ * agent to enter CODE or a restored CODE_REVIEW. The subsequent lifecycle tool call remains the sole
+ * authority for attaching and binding the Stage. */
+export async function prepareVnextCodeWorkspace(context, input) {
+    if (context.env.DD_FLOW_CODE_READINESS_OWNER !== input.ownerId) {
+        throw new AppError("code_readiness_owner_mismatch", "CODE readiness preparation must use its controller's frozen owner", 1, { owner_id: input.ownerId });
+    }
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
-    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    assertRunMutationAllowed(context, project.id, run.id);
+    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, stage: input.stage ?? stage });
+    const root = path.join(requireHome(run), stageDir);
+    fs.mkdirSync(root, { recursive: true });
+    return ensureCodeWorkspaceReady(context, project.id, run, root, [], input.progress, { force: input.stage !== "code-review" });
+}
+export function prepareVnextCodeStart(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const home = requireHome(run);
     requireVnextWorkspaceRoute({ projectRoot, runId: input.runId, runHome: home, workspaceRoot: run.workspace_root, stage });
     const existingRoot = path.join(home, stageDir);
     const existingPrompt = path.join(existingRoot, "stage-prompt.md");
     const existingStage = stageStatus(run, stage);
+    const sourceRepairAttempt = isMergeSourceRepairAttempt(run);
+    const rootWork = requireRootWork(context, project.id, input.runId);
+    if (input.externalContext)
+        prepareExternalStageContext({ stageRoot: existingRoot, loaded: input.externalContext });
+    prepareOutputFile(existingPrompt);
+    prepareOutputFile(path.join(existingRoot, "fanout.json"));
+    const common = { projectRoot, project, run, home, root: existingRoot, promptPath: existingPrompt, rootWork, sourceRepairAttempt };
     if (existingStage && fs.existsSync(existingPrompt)) {
-        const externalContext = applyExternalStageContext({ stageRoot: existingRoot, promptPath: existingPrompt, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
-        const prompt = fs.readFileSync(existingPrompt, "utf8");
-        const rootWork = requireRootWork(context, project.id, input.runId);
-        const orchestration = readFanoutDescriptor(existingRoot) ?? writeFanoutDescriptor(existingRoot, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
-        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: existingStage, prompt_path: existingPrompt, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), orchestration, graph: codeWorkGraph(context, project.id, run.id), next: { refresh_graph_command: `${flowCommand(context)} work ls --run ${run.id} --ready --project-root ${JSON.stringify(projectRoot)} --json`, finish_command: finishCommand(context, input.runId, projectRoot, path.join(existingRoot, "code-verification.json")) } };
+        return { ...common, resumed: true, existingStage, prompt: fs.readFileSync(existingPrompt, "utf8"), orchestration: readFanoutDescriptor(existingRoot) };
     }
+    if (!sourceRepairAttempt)
+        prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
     const batch = path.join(home, "03-plan", "code-work-batch.json");
     const handoffFailures = validateVnextCodeHandoff(context, {
         projectRoot,
@@ -53,15 +78,29 @@ export async function startVnextCode(context, input) {
         file: batch,
         projectRoot: run.workspace_root,
         ddFlowHome: context.ddFlowHome,
-        runId: input.runId
+        runId: input.runId,
+        runRoot: home
     });
     validateWorkBatchFile(batch);
-    const root = path.join(home, stageDir);
+    const template = fs.readFileSync(path.join(run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code.md"), "utf8");
+    const variables = getFlowRunVariables(context, { projectRoot, runId: run.id });
+    return { ...common, resumed: false, template, capacity: variables.variables?.["runtime.subagent.available_slots"] };
+}
+export async function startVnextCode(context, input, prepared = prepareVnextCodeStart(context, input)) {
+    const { projectRoot, project, run, root, promptPath, rootWork, sourceRepairAttempt } = prepared;
+    assertRunMutationAllowed(context, project.id, run.id);
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    if (prepared.resumed) {
+        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+        const orchestration = prepared.orchestration ?? writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true, scope: stageGraphScope(context, project.id, run.id, stage) });
+        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prepared.existingStage, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, graph: codeWorkGraph(context, project.id, run.id), next: { refresh_graph_command: runtimeCommand(context, ["work", "ls", "--run", run.id, "--ready", "--project-root", projectRoot, "--json"]), finish_command: finishCommand(context, input.runId, projectRoot, path.join(root, "code-verification.json")) } };
+    }
     fs.mkdirSync(root, { recursive: true });
     const readiness = await ensureCodeWorkspaceReady(context, project.id, run, root, [], input.progress);
-    const rootWork = requireRootWork(context, project.id, input.runId);
-    const promptPath = path.join(root, "stage-prompt.md");
-    const prompt = coordinatorPrompt(context, { projectRoot, run, root, rootWork, readiness });
+    // Graph rendering may issue managed child commands; it belongs to execution.
+    const graph = codeWorkGraph(context, project.id, run.id);
+    const prompt = coordinatorPrompt(context, { projectRoot, run, root, rootWork, readiness, template: prepared.template, capacity: prepared.capacity, graph });
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, {
@@ -72,16 +111,17 @@ export async function startVnextCode(context, input) {
         resultPath: path.join(root, "stage-report.json"),
         ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {})
     });
-    attachFlowRunStage(context, {
-        projectRoot,
-        runId: input.runId,
-        stage,
-        dir: stageDir,
-        status: "running",
-        dataSchemaId: "dd-flow/stage-report@1"
-    });
-    const graph = codeWorkGraph(context, project.id, input.runId);
-    const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
+    if (!sourceRepairAttempt) {
+        attachFlowRunStage(context, {
+            projectRoot,
+            runId: input.runId,
+            stage,
+            dir: stageDir,
+            status: "running",
+            dataSchemaId: "dd-flow/stage-report@1"
+        });
+    }
+    const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true, scope: stageGraphScope(context, project.id, run.id, stage) });
     appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "code_started", work_id: rootWork.work_id, graph });
     return {
         ok: true,
@@ -95,7 +135,7 @@ export async function startVnextCode(context, input) {
         graph,
         orchestration,
         readiness,
-        next: { refresh_graph_command: `${flowCommand(context)} work ls --run ${run.id} --ready --project-root ${JSON.stringify(projectRoot)} --json`, finish_command: finishCommand(context, input.runId, projectRoot, path.join(root, "code-verification.json")) }
+        next: { refresh_graph_command: runtimeCommand(context, ["work", "ls", "--run", run.id, "--ready", "--project-root", projectRoot, "--json"]), finish_command: finishCommand(context, input.runId, projectRoot, path.join(root, "code-verification.json")) }
     };
 }
 export async function finishVnextCode(context, input) {
@@ -104,8 +144,10 @@ export async function finishVnextCode(context, input) {
     const run = requireRun(context, project.id, input.runId);
     const home = requireHome(run);
     const root = path.join(home, stageDir);
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
     requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage });
     if (stageStatus(run, stage) === "done" && fs.existsSync(path.join(root, "stage-report.json"))) {
+        resumeAcceptedCodeStage(context, run, projectRoot, stage, JSON.parse(fs.readFileSync(path.join(root, "stage-report.json"), "utf8")), nextAction(run, changedPathsFromReport(path.join(root, "stage-report.json"))));
         return { ok: true, resumed: true, run_id: run.id, stage, outcome: "accepted", report_path: path.join(root, "stage-report.json"), next_action: nextAction(run, changedPathsFromReport(path.join(root, "stage-report.json"))) };
     }
     const handoffFailures = validateVnextCodeHandoff(context, {
@@ -134,58 +176,67 @@ export async function finishVnextCode(context, input) {
         throw new AppError("obligation_coverage_incomplete", "CODE graph does not cover every accepted obligation", 2, { missing });
     }
     // Reject a malformed semantic receipt before running the expensive gate.
-    const verification = verificationForFinish(context, { file: input.verificationFile, projectRoot: run.workspace_root, runId: run.id });
-    if (verification.verdict !== "passed" || verification.unresolved.length > 0) {
-        throw new AppError("code_verification_incomplete", "CODE verification is not accepted; create or complete the necessary repair Work first", 2, { verification });
+    const verification = input.verification ?? verificationForFinish(context, { file: input.verificationFile, projectRoot: run.workspace_root, runId: run.id, runRoot: home });
+    validateSchema({ schemaName: "code-verification", file: input.verificationFile, data: verification, projectRoot: run.workspace_root, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: home });
+    if (verification.verdict === "blocked") {
+        return { ok: true, run_id: run.id, stage, outcome: "blocked", verification, instruction: "CODE remains running. Resolve the stated external or user-input blocker in this same coordinator session, update code-verification.json, then invoke this same stage finish command again." };
+    }
+    if (verification.verdict === "passed" && verification.unresolved.length > 0) {
+        throw new AppError("verification_contradictory", "A passed CODE verification cannot contain unresolved obligations", 2, { unresolved: verification.unresolved });
+    }
+    if (verification.verdict === "needs_repair") {
+        const repair = addVnextCodeRepair(context, {
+            projectRoot,
+            runId: run.id,
+            originWorkIds: works.filter((work) => work.status === "completed").map((work) => work.work_id),
+            semanticUnresolved: verification.unresolved.length ? verification.unresolved : [verification.summary],
+            verificationPath: input.verificationFile,
+            verification,
+            objective: verification.summary
+        });
+        return { ok: true, run_id: run.id, stage, outcome: "repair_required", verification, repair, instruction: "The semantic verification is not accepted. The repair Work is already registered: do not invoke its start_command in this coordinator Session. End this Turn so the controller can launch it in a fresh child Session. After that Work completes, update code-verification.json and invoke this same stage finish command again." };
     }
     const checks = finalCodeCheckDeclarations(run.workspace_root, works.flatMap((work) => packet(work)?.checks ?? []));
-    const unchangedFailures = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: checks });
-    if (unchangedFailures.length)
-        throw new AppError("code_gate_repair_required", "CODE final gate already failed for the unchanged workspace; repair the evidenced failure before retrying", 2, { outcome: "repair_required", retry_after_workspace_change: true, workspace_fingerprint: unchangedFailures[0].workspace_fingerprint, failures: unchangedFailures });
-    let receipts = reusableAggregateGateReceipts(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, checks });
-    if (!receipts) {
-        const release = acquireAggregateGateLock(root);
-        try {
-            // A prior caller may have completed the slow gate while this caller was
-            // waiting to acquire the lock. Reuse that immutable evidence.
-            receipts = reusableAggregateGateReceipts(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, checks }) ?? await runCodeChecks(context, {
-                projectId: project.id,
-                runId: run.id,
-                runHome: home,
-                workspaceRoot: run.workspace_root,
-                scope: "aggregate",
-                checks,
-                ...(input.progress ? { progress: input.progress } : {})
-            });
-        }
-        finally {
-            release();
-        }
-    }
+    if (input.retryCheckId) {
+        validateFailedCheckRetry(context, { projectId: project.id, runId: run.id, receiptId: input.retryCheckId, declarations: checks, reason: input.retryReason });
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "check_retry_requested", check_receipt_id: input.retryCheckId, stage, reason: input.retryReason ?? "operator retry" });
+    }
+    const receipts = await runCodeChecks(context, {
+        projectId: project.id, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, scope: "aggregate", checks,
+        ...(input.retryCheckId ? { retryReceiptId: input.retryCheckId, retryReason: input.retryReason } : {}),
+        ...(input.progress ? { progress: input.progress } : {})
+    });
     const failed = receipts.filter((receipt) => receipt.status !== "passed");
     if (failed.length) {
+        const continuation = registerAggregateCodeRepair(context, { projectRoot, runId: run.id, stage, failures: failed, checks, generation });
         throw new AppError("code_gate_failed", "CODE remains running because the aggregate project gate failed", 2, {
             failures: failed,
             outcome: "repair_required",
             retry_after_workspace_change: true,
             workspace_fingerprint: failed[0].workspace_fingerprint,
-            repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-stdin --project-root ${JSON.stringify(projectRoot)} --json`
+            continuation,
+            instruction: "Repair Work is already registered. End this coordinator Turn; the controller will launch a fresh child. After it completes, update semantic verification and finish the Stage."
         });
     }
-    const allReceipts = checkReceipts(context, { projectId: project.id, runId: run.id });
-    const finalReceipts = latestReceiptsByCommand(allReceipts);
+    const finalReceipts = receipts;
+    const projectedVerification = verificationProjection(works, finalReceipts, { historicalReceipts: finalReceipts, runId: run.id, runHome: home });
+    const unresolvedAcceptance = (projectedVerification.acceptance ?? []).filter((item) => item.status === "unresolved");
+    if (unresolvedAcceptance.length)
+        throw new AppError("code_acceptance_unresolved", "CODE cannot finish until every due acceptance criterion has current checks and evidence", 2, { unresolved: unresolvedAcceptance });
     const now = context.now();
     const timing = stageTiming(home, stage, now);
-    const changedPaths = [...new Set(works.flatMap((work) => resultPaths(work.result)))];
+    // Work result paths are provenance, not a mutable filesystem oracle. The
+    // stage reports one shared Git observation; ignored machine repairs are
+    // rejected before a Work can become completed.
+    const changedPaths = workspaceChangedPaths(run.workspace_root);
     const next = nextAction(run, changedPaths);
-    writeProtocolFlowStatus(run.workspace_root, home, run.id, next === "start_code_review" ? "CODE complete; CODE-REVIEW is next." : next === "start_merge" ? "CODE complete; MERGE is queued." : "CODE complete; this RUN reached its configured terminal boundary.");
     const report = {
         schema_id: "dd-flow/stage-report@1",
         run_id: run.id,
         stage,
         generated_at: now,
         verdict: "done",
-        verification: verificationProjection(works, finalReceipts),
+        verification: projectedVerification,
         semantic: {
             result: `Completed ${works.length} CODE Work item${works.length === 1 ? "" : "s"}; ${finalReceipts.filter((receipt) => receipt.status === "passed").length} current final check receipt${finalReceipts.length === 1 ? "" : "s"} passed.`,
             acceptance: [...expected],
@@ -207,37 +258,50 @@ export async function finishVnextCode(context, input) {
             wall_clock_ms: timing.wall_clock_ms,
             git: gitFacts(run.workspace_root),
             graph: codeWorkGraph(context, project.id, run.id),
-            session_stats_command: `${flowCommand(context)} stat run sessions ls --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json`,
-            usage_stats_command: `${flowCommand(context)} stat usage --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json`
+            session_stats_command: runtimeCommand(context, ["stat", "run", "sessions", "ls", "--run", run.id, "--project-root", projectRoot, "--json"]),
+            usage_stats_command: runtimeCommand(context, ["stat", "usage", "--run", run.id, "--project-root", projectRoot, "--json"])
         },
         artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html", summary: "stage-report.md" },
         validation: { permission_scope: "known_targets_only", memory_bank_scope: "changed_files_and_links_only", status: "passed" }
     };
-    writeReport(root, report);
-    completeFlowRunStage(context, {
-        projectRoot,
-        runId: run.id,
-        stage,
-        status: "done",
-        data: "stage-report.json",
-        dataSchemaId: "dd-flow/stage-report@1",
-        report: "stage-report.md",
-        stageReport: "stage-report.html"
-    });
-    const rootWork = requireRootWork(context, project.id, run.id);
-    appendFlowRunTimelineEvent(context, project.id, run.id, {
-        type: "code_accepted",
-        work_id: rootWork.work_id,
-        checks: finalReceipts.map((receipt) => receipt.id)
+    // Creating the MERGE request is part of accepting this terminal handoff.
+    // Do it before materialising a terminal stage report or changing RUN state,
+    // so an invalid merge policy leaves CODE safely running and retryable.
+    let mergeRequest = null;
+    assertRunMutationAllowed(context, project.id, run.id, generation);
+    const prepareMerge = next === "start_merge" ? prepareVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths: changedPaths }) : null;
+    withStageSettlement(context, () => {
+        assertRunMutationAllowed(context, project.id, run.id, generation);
+        const currentWorks = codeWorks(context, project.id, run.id);
+        if (currentWorks.length !== works.length || currentWorks.some(work => work.status !== "completed" || !works.some(accepted => accepted.work_id === work.work_id && accepted.result === work.result))) {
+            throw new AppError("code_graph_incomplete", "CODE results changed while the final checks were running", 2);
+        }
+        mergeRequest = prepareMerge?.() ?? null;
+        writeReport(root, report);
+        completeFlowRunStage(context, {
+            projectRoot,
+            runId: run.id,
+            stage,
+            status: "done",
+            data: "stage-report.json",
+            dataSchemaId: "dd-flow/stage-report@1",
+            report: "stage-report.md",
+            stageReport: "stage-report.html"
+        });
+        const rootWork = requireRootWork(context, project.id, run.id);
+        appendFlowRunTimelineEvent(context, project.id, run.id, {
+            type: "code_accepted",
+            work_id: rootWork.work_id,
+            checks: finalReceipts.map((receipt) => receipt.id)
+        });
+        if (next === "code_completed") {
+            finishStageCoordinatorWork(context, rootWork.work_id, JSON.stringify(report, null, 2));
+            completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "code_completed", nextAction: undefined });
+        }
+        else {
+            advanceFlowRun(context, { settlementStage: "code", projectRoot, runId: run.id, status: "running", verdict: "code_completed", nextAction: next });
+        }
     });
-    if (next === "code_completed") {
-        await finishWork(context, rootWork.work_id, JSON.stringify(report, null, 2));
-        completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "code_completed", nextAction: undefined });
-    }
-    else {
-        advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "code_completed", nextAction: next });
-    }
-    const mergeRequest = next === "start_merge" ? ensureVnextMergeRequest(context, { projectRoot, runId: run.id }) : null;
     return {
         ok: true,
         run_id: run.id,
@@ -245,18 +309,57 @@ export async function finishVnextCode(context, input) {
         outcome: "accepted",
         report_path: path.join(root, "stage-report.json"),
         next_action: next,
-        ...(next === "start_code_review" ? { next: { kind: "start_stage", stage: "code-review", command: `${flowCommand(context)} stage start ${run.id} --stage code-review --project-root ${JSON.stringify(projectRoot)} --json` } } : next === "start_merge" ? { merge_request: mergeRequest, next: { kind: "start_stage", stage: "merge", command: `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl` } } : {})
+        ...(next === "start_code_review" ? { next: { kind: "start_stage", stage: "code-review", command: managedLifecycleCommand(context, runtimeCommand(context, ["stage", "start", run.id, "--stage", "code-review", "--project-root", projectRoot, "--json"])) } } : next === "start_merge" ? { merge_request: mergeRequest, next: { kind: "start_stage", stage: "merge", command: managedLifecycleCommand(context, runtimeCommand(context, ["stage", "start", run.id, "--stage", "merge", "--project-root", projectRoot, "--json", "--progress-jsonl"])) } } : {})
     };
 }
-export function addVnextCodeRepair(context, input) {
+export function registerAggregateCodeRepair(context, input) {
+    const project = requireProjectByRoot(context, input.projectRoot);
+    const origins = codeWorks(context, project.id, input.runId).filter(work => !packet(work)?.repair && work.status === "completed");
+    const failedDeclarations = new Set(input.failures.flatMap(receipt => [receipt.declaration_id, ...receipt.check_refs]));
+    const objective = ["Investigate and repair all retained aggregate check failures while preserving accepted requirements and non-goals. If evidence proves an external blocker or a contradiction, report it; do not invent a product change.", ...input.failures.map(receipt => `Receipt: ${receipt.receipt_path}\nstdout: ${receipt.stdout_path}\nstderr: ${receipt.stderr_path}`)].join("\n\n");
+    try {
+        return ensureAggregateRepair(context, { projectId: project.id, runId: input.runId, stage: input.stage, failures: input.failures, origins: origins.map(work => work.work_id), ...(input.generation !== undefined ? { generation: input.generation } : {}) }, () => String(addVnextCodeRepair(context, { registrationOwned: true, projectRoot: input.projectRoot, runId: input.runId, stage: input.stage, ...(input.stage === "code-review" ? { reviewCycle: stageCycle(context, project.id, input.runId, input.stage) } : {}), checkReceiptId: input.failures[0].id, originWorkIds: origins.map(work => work.work_id), objective, reviewChecks: input.checks.filter(check => failedDeclarations.has(check.id) || failedDeclarations.has(check.canonical_ref ?? "")) }).repair_work_id));
+    }
+    catch (error) {
+        if (!(error instanceof AppError))
+            throw error;
+        throw new AppError(error.code, error.message, error.exitCode, { ...error.details, stage: input.stage, run_id: input.runId, failures: input.failures, cause: { code: input.stage === "code" ? "code_gate_failed" : "code_review_gate_failed", message: "Aggregate checks failed; repair registration was rejected" } });
+    }
+}
+export function prepareVnextCodeRepair(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const home = requireHome(run);
-    if (!input.objective.trim())
+    if (input.reviewCycle) {
+        const previous = codeWorks(context, project.id, run.id).find((work) => packet(work)?.review_cycle === input.reviewCycle && (input.checkReceiptId ? packet(work)?.repair?.check_receipt_id === input.checkReceiptId : Boolean(packet(work)?.repair?.review_findings?.length)));
+        if (previous)
+            return { kind: "replay", project, run, previous };
+    }
+    if (typeof input.objective !== "string" || !input.objective.trim())
         throw new AppError("validation", "Repair objective must not be empty", 2);
-    if (!input.checkReceiptId && !input.reviewFindingIds?.length) {
-        throw new AppError("validation", "Repair needs a failed check receipt or CODE-REVIEW finding", 2);
+    if (input.semanticUnresolved !== undefined && (!Array.isArray(input.semanticUnresolved) || input.semanticUnresolved.some(value => typeof value !== "string" || !value.trim())))
+        throw new AppError("validation", "Semantic unresolved items must be nonempty strings", 2);
+    if (input.reviewFindings !== undefined && !Array.isArray(input.reviewFindings))
+        throw new AppError("validation", "Review findings must be an array", 2);
+    if (input.reviewChecks !== undefined && !Array.isArray(input.reviewChecks))
+        throw new AppError("validation", "Review checks must be an array", 2);
+    if (!Array.isArray(input.originWorkIds) || !input.originWorkIds.length || input.originWorkIds.some(id => typeof id !== "string" || !id.trim()))
+        throw new AppError("validation", "Repair requires at least one origin Work", 2);
+    if (!input.checkReceiptId && !input.reviewFindings?.length && !input.semanticUnresolved?.length) {
+        throw new AppError("validation", "Repair needs failed check evidence, a CODE-REVIEW finding, or an unresolved CODE verification", 2);
+    }
+    if ([Boolean(input.checkReceiptId), Boolean(input.reviewFindings?.length), Boolean(input.semanticUnresolved?.length)].filter(Boolean).length !== 1)
+        throw new AppError("validation", "Repair requires exactly one evidence source", 2);
+    if (input.semanticUnresolved?.length) {
+        if (!input.verificationPath)
+            throw new AppError("usage", "Semantic repair requires a verification file", 2);
+        const verification = input.verification ?? readVerification(context, { file: input.verificationPath, projectRoot: run.workspace_root, runId: run.id, runRoot: home });
+        if (input.verification !== undefined)
+            validateSchema({ schemaName: "code-verification", file: input.verificationPath, data: verification, projectRoot: run.workspace_root, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: home });
+        const unresolved = verification.unresolved.length ? verification.unresolved : [verification.summary];
+        if (verification.verdict !== "needs_repair" || input.semanticUnresolved.some(value => !unresolved.includes(value)))
+            throw new AppError("validation", "Semantic repair must reference unresolved items from a needs_repair verification", 2);
     }
     const receipt = input.checkReceiptId ? context.db.get("SELECT id, declaration_id, run_id, command, status, receipt_path, stdout_path, stderr_path FROM check_receipts WHERE project_id = ? AND id = ?", [
         project.id,
@@ -269,11 +372,19 @@ export function addVnextCodeRepair(context, input) {
     }
     const origins = [...new Set(input.originWorkIds)].map((id) => requireCodeWork(context, project.id, run.id, id));
     const packets = origins.map((work) => packet(work));
-    const invariantPackets = receipt
+    const invariantPackets = receipt || input.semanticUnresolved?.length
         ? codeWorks(context, project.id, run.id).map((work) => packet(work)).filter((value) => !value.repair)
         : packets;
     const first = packets[0];
-    const declaredChecks = finalCodeCheckDeclarations(run.workspace_root, packets.flatMap((value) => value.checks));
+    // A later repair may be caused by any accepted aggregate declaration, not
+    // only the checks copied into its immediate repair parent.  Otherwise a
+    // repair that fixes one failed aggregate check can make a second, already
+    // declared aggregate failure impossible to repair.  The immutable source
+    // of repair eligibility is the original CODE graph.
+    const declaredChecks = effectiveCheckDeclarations(run.workspace_root, codeWorks(context, project.id, run.id)
+        .map((work) => packet(work))
+        .filter((value) => !value.repair)
+        .flatMap((value) => value.checks), ["work", "code", "readiness", "merge"]);
     const failedCheck = receipt ? declaredChecks.find((check) => check.id === receipt.declaration_id) : undefined;
     if (receipt && !failedCheck) {
         throw new AppError("repair_check_declaration_missing", "Repair receipt is not backed by an accepted CODE check declaration", 2, {
@@ -281,7 +392,8 @@ export function addVnextCodeRepair(context, input) {
             declaration_id: receipt.declaration_id
         });
     }
-    const key = input.reviewFindingIds?.length ? "code-review-repair" : "code-gate-repair";
+    const semanticRepair = Boolean(input.semanticUnresolved?.length);
+    const key = input.reviewFindings?.length ? "code-review-repair" : semanticRepair ? "code-verification-repair" : "code-gate-repair";
     const receiptWriteScope = receipt ? receiptRepairPaths(run.workspace_root, receipt) : [];
     const repair = {
         schema_id: "dd-flow/code-work-packet@5",
@@ -291,22 +403,27 @@ export function addVnextCodeRepair(context, input) {
         repair: {
             origin_work_ids: origins.map((work) => work.work_id),
             ...(receipt ? { check_receipt_id: receipt.id, failure_receipt_path: receipt.receipt_path } : {}),
-            ...(input.reviewFindingIds?.length ? { review_finding_ids: unique(input.reviewFindingIds), review_evidence_refs: unique(input.reviewEvidenceRefs ?? []), review_check_refs: unique(input.reviewCheckRefs ?? (input.reviewChecks ?? []).map((check) => check.id)) } : {})
+            ...(input.reviewFindings?.length ? { review_findings: input.reviewFindings } : {}),
+            ...(semanticRepair ? { semantic_unresolved: unique(input.semanticUnresolved ?? []), verification_path: input.verificationPath } : {}),
+            // `run_at` remains the accepted aggregate placement. This separate
+            // repair obligation is deliberately executed before this repair Work is
+            // accepted, so a local fix cannot close without re-proving its cause.
+            verification_check_refs: selectRepairChecks({ ...(failedCheck ? { failedCheck } : {}), ...(input.reviewChecks ? { reviewChecks: input.reviewChecks } : {}), ...(semanticRepair ? { semanticChecks: declaredChecks } : {}) })
         },
         task: input.objective,
         semantic_spine: {
-            user_outcome: receipt ? `Restore the accepted behavior after aggregate failure: ${input.objective}` : `Resolve accepted CODE-REVIEW finding: ${input.objective}`,
+            user_outcome: receipt ? `Restore the accepted behavior after aggregate failure: ${input.objective}` : semanticRepair ? `Close the unresolved CODE verification: ${input.objective}` : `Resolve accepted CODE-REVIEW finding: ${input.objective}`,
             component_responsibility: "Diagnose and repair the failed accepted CODE result without changing unrelated behavior.",
             must_preserve: unique(invariantPackets.flatMap((value) => value.semantic_spine.must_preserve)),
             non_goals: unique(invariantPackets.flatMap((value) => value.semantic_spine.non_goals)),
-            acceptance_contribution: receipt ? `Make failed check pass: ${receipt.command}` : `Resolve CODE-REVIEW finding(s): ${input.reviewFindingIds.join(", ")}`
+            acceptance_contribution: receipt ? `Make failed check pass: ${receipt.command}` : semanticRepair ? `Resolve CODE verification gap(s): ${input.semanticUnresolved.join("; ")}` : `Resolve CODE-REVIEW finding(s): ${input.reviewFindings.map((finding) => finding.finding_ref).join(", ")}`
         },
         requirements: uniqueBy(invariantPackets.flatMap((value) => value.requirements), (value) => value.id),
         acceptance: uniqueBy(invariantPackets.flatMap((value) => value.acceptance), (value) => JSON.stringify(value)),
         // A CODE-REVIEW repair changes delivered code/evidence, never the
         // already accepted PLAN or its ownership declaration.
         document_updates: [],
-        required_read: unique([...(receipt ? [receipt.receipt_path] : input.reviewEvidenceRefs ?? []), ...packets.flatMap((value) => value.required_read)]),
+        required_read: unique([...(receipt ? [receipt.receipt_path] : input.reviewFindings?.flatMap((finding) => finding.evidence_refs) ?? []), ...(semanticRepair && input.verificationPath ? [input.verificationPath] : []), ...packets.flatMap((value) => value.required_read)]),
         discovery_boundary: unique(packets.flatMap((value) => value.discovery_boundary)),
         // These are collision-avoidance hints. Receipt paths enrich the coordinator
         // picture but never restrict the repair's project-local edits.
@@ -314,41 +431,44 @@ export function addVnextCodeRepair(context, input) {
         // Receipts record the resolved shell command. A repair must retain the
         // accepted declaration (including its immutable @check alias) and only
         // change when it runs, so work finish can validate it again.
-        checks: selectRepairChecks({ ...(failedCheck ? { failedCheck } : {}), ...(input.reviewChecks ? { reviewChecks: input.reviewChecks } : {}) }),
+        checks: selectRepairChecks({ ...(failedCheck ? { failedCheck } : {}), ...(input.reviewChecks ? { reviewChecks: input.reviewChecks } : {}), ...(semanticRepair ? { semanticChecks: declaredChecks } : {}) }),
         provides_checks: [],
         stop_conditions: unique([
             ...invariantPackets.flatMap((value) => value.stop_conditions),
             ...(receipt ? ["Stop and report the blocker if the proposed repair contradicts an accepted requirement or non-goal."] : ["Do not modify accepted PLAN artifacts, code-work-batch.json, or review decisions. Stop and report if the finding cannot be repaired within accepted scope."])
         ]),
         depends_on: origins.map((work) => work.work_id),
-        result_schema: "dd-flow/code-work-result@2"
+        result_schema: "dd-flow/code-work-result@3",
+        ...(input.reviewCycle ? { review_cycle: input.reviewCycle } : {})
     };
-    const file = path.join(home, stageDir, `.repair-${crypto.randomUUID()}.json`);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, `${JSON.stringify({ works: [repair] }, null, 2)}\n`);
-    let registered;
-    try {
-        registered = addWorkBatch(context, { parentWorkId: requireRootWork(context, project.id, run.id).work_id, file });
-    }
-    finally {
-        fs.rmSync(file, { force: true });
-    }
-    const id = String(registered.work_ids[key]);
+    const parentWorkId = requireRootWork(context, project.id, run.id).work_id;
+    const items = prepareWorkBatch(context, { parentWorkId, value: { works: [repair] } });
+    return { kind: "create", project, run, input, parentWorkId, items, key, receipt };
+}
+export function addVnextCodeRepair(context, input, prepared = prepareVnextCodeRepair(context, input)) {
+    const { project, run } = prepared;
+    if (prepared.kind === "replay")
+        return { ok: true, run_id: run.id, repair_work_id: prepared.previous.work_id, start_command: workStartCommand(context, prepared.previous), reused: true };
+    const { parentWorkId, items, key, receipt } = prepared;
+    const create = () => String(addWorkBatch(context, { parentWorkId, prepared: items, stage: input.stage ?? (input.reviewCycle ? "code-review" : "code"), ...(input.reviewCycle ? { cycle: input.reviewCycle } : {}) }).work_ids[key]);
+    const id = input.registrationOwned ? create() : ensureRepairIntent(context, {
+        projectId: project.id, runId: run.id, stage: input.stage ?? (input.reviewCycle ? "code-review" : "code"),
+        causes: input.checkReceiptId ? { receipt: input.checkReceiptId, origins: [...input.originWorkIds].sort() } : input.reviewCycle ? { review_cycle: input.reviewCycle, findings: input.reviewFindings } : { verification: input.verification, unresolved: input.semanticUnresolved, origins: [...input.originWorkIds].sort() }
+    }, create).work_id;
     const work = context.db.get("SELECT * FROM works WHERE work_id = ?", [id]);
     appendFlowRunTimelineEvent(context, project.id, run.id, {
         type: "code_repair_created",
         work_id: id,
-        origin_work_ids: input.originWorkIds,
-        ...(receipt ? { check_receipt_id: receipt.id } : { review_finding_ids: input.reviewFindingIds })
+        origin_work_ids: prepared.input.originWorkIds,
+        ...(receipt ? { check_receipt_id: receipt.id } : prepared.input.reviewFindings?.length ? { review_finding_ids: prepared.input.reviewFindings.map((finding) => finding.finding_ref) } : { semantic_unresolved: prepared.input.semanticUnresolved })
     });
     refreshRunWorkProjection(context, project.id, run.id);
     return { ok: true, run_id: run.id, repair_work_id: id, start_command: workStartCommand(context, work) };
 }
-/** The repair Work runs only the check that motivated it; the stage retains the aggregate gate. */
+/** Retain the causal declaration for worker context; run_at still records its original gate. */
 export function selectRepairChecks(input) {
-    const checks = input.failedCheck
-        ? [{ ...input.failedCheck, purpose: "Re-run the failed accepted check.", run_at: "work" }]
-        : (input.reviewChecks ?? []).map((check) => ({ ...check, purpose: `Prove the CODE-REVIEW repair: ${check.purpose}`, run_at: "work" }));
+    const candidates = input.failedCheck ? [input.failedCheck, ...(input.reviewChecks ?? [])] : input.reviewChecks ?? input.semanticChecks ?? [];
+    const checks = candidates.map((check) => ({ ...check, purpose: `${input.semanticChecks ? "Prove the CODE verification repair" : "Prove the CODE-REVIEW repair"}: ${check.purpose}` }));
     return uniqueBy(checks, (check) => check.id);
 }
 function receiptRepairPaths(workspaceRoot, receipt) {
@@ -376,10 +496,7 @@ function receiptRepairPaths(workspaceRoot, receipt) {
     return [...paths].sort();
 }
 function coordinatorPrompt(context, input) {
-    const graph = codeWorkGraph(context, input.run.project_id, input.run.id);
-    const variables = getFlowRunVariables(context, { projectRoot: input.projectRoot, runId: input.run.id });
-    const capacity = variables.variables?.["runtime.subagent.available_slots"];
-    const template = fs.readFileSync(path.join(input.run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code.md"), "utf8");
+    const { graph, capacity, template } = input;
     return [
         "<stage_identity>",
         `- RUN: ${input.run.id}`,
@@ -401,17 +518,18 @@ function coordinatorPrompt(context, input) {
         "</code_graph>",
         "",
         "<execution_commands>",
-        "Launch only entries listed in graph.ready. Use at most the known available slot count. Every registered CODE Work runs in a fresh child Session, including a serial dependency chain; the coordinator owns dispatch and the stage conclusion, not implementation Work. Every child starts with its exact start_command and receives its complete packet from dd-flow. After a Work finishes, use the graph returned by work finish to launch newly ready Work. To refresh the parent graph yourself use the exact command: " + `${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(input.projectRoot)} --json`,
-        "A quiet child is still running until the harness reports its turn completed, failed, cancelled or explicitly needs attention. An elapsed nominal wait, silence, or no new artifact is not an unresponsive-worker failure. Never interrupt, replace, relaunch, or stage-block a still-running child for that reason, even if an external controller asks. Long work finish and stage finish commands emit check progress on stderr. After you issue the exact CODE stage finish command, wait for that same command to return: do not inspect its PID, start a second finish command, or infer failure from quiet output. Close a disposable child only after its Work is accepted or explicitly failed/cancelled and the harness reports the turn settled.",
-        `A repairable engine, harness, or environment failure is not a user question. Record it without finishing CODE: ${flowCommand(context)} stage block ${input.run.id} --stage code --work ${input.rootWork.work_id} --kind <engine|harness|environment> --code <stable-code> --summary-stdin --retryable --project-root ${JSON.stringify(input.projectRoot)} --json. Repair it externally, then run the exact unblock_command returned by dd-flow and continue this same stage.`,
+        "Do not choose a provider delegation tool from this stage prompt. At each work_fanout boundary, stop at the Work-graph boundary; the shared controller supplies the selected adapter's native tool, exact parameters, child task, and wait contract. It launches only entries listed in graph.ready and uses at most the qualified capacity. Every registered CODE Work runs in a fresh child Session, including a serial dependency chain. The coordinator launches those children only through the controller-supplied native delegation instruction; it must never invoke a Work start_command itself. Each child receives its complete packet from dd-flow and runs its own exact start_command. After a Work finishes, the controller uses the graph returned by work finish to launch newly ready Work. To refresh the parent graph yourself use the exact command: " + runtimeCommand(context, ["work", "ls", "--run", input.run.id, "--ready", "--project-root", input.projectRoot, "--json"]),
+        "A quiet child is still running until the harness reports its turn completed, failed, cancelled or explicitly needs attention. An elapsed nominal wait, silence, or no new artifact is not an unresponsive-worker failure. Never interrupt, replace, relaunch, or stage-block a still-running child for that reason, even if an external controller asks. Long work finish and stage finish commands emit check progress on stderr. After you issue the exact CODE stage finish command, wait for that same command to return once: a completed command with a non-zero exit and structured `code_gate_failed` output is its terminal result, not a reason to keep waiting. A repair_required continuation already registered the repair: end this Turn. Do not invoke that Work's start_command from the coordinator Session, inspect its PID, start a second finish command, or infer failure from quiet output. Close a disposable child only after its Work is accepted or explicitly failed/cancelled and the harness reports the turn settled.",
+        `A repairable engine, harness, or environment failure is not a user question. Write the evidence summary to ${path.join(requireHome(input.run), "works", input.rootWork.work_id, "block-summary.md")}, then record it with a separate command: ${runtimeCommand(context, ["stage", "block", input.run.id, "--stage", "code", "--work", input.rootWork.work_id, "--kind", "<engine|harness|environment>", "--code", "<stable-code>", "--summary-file", `@run/works/${input.rootWork.work_id}/block-summary.md`, "--retryable", "--project-root", input.projectRoot, "--json"])}. Choose kind and stable-code from evidence; this example is not an executable continuation. Repair it externally, then run the exact unblock_command returned by dd-flow and continue this same stage.`,
         `When every CODE and repair Work is completed, write ${path.join(input.root, "code-verification.json")} using the exact contract below. Mark passed only when all accepted requirements and current-gate acceptance criteria are implemented or explicitly evidenced; list every remaining issue in unresolved. Every evidence_refs item must already exist as a relative workspace path or run://${input.run.id}/ path. Do not claim a browser or other check receipt that was not retained. Then finish: ${finishCommand(context, input.run.id, input.projectRoot, path.join(input.root, "code-verification.json"))}`,
-        "If the aggregate gate fails, do not stop after `code_gate_failed`: that rejected finish does not create a repair Work. In the same coordinator Turn, use its returned repair command with the relevant completed origin Work IDs and a concise repair objective, then stop so the runner can dispatch the newly declared repair. Do not edit invisibly in the root orchestrator.",
+        "A code_gate_failed response with continuation.kind=repair_required has already registered one repair Work with all failed receipts. End this Turn so the controller can dispatch it in a fresh child. Do not recreate the repair, copy origin IDs, write a repair task file or execute the child start command yourself. After repair, update semantic verification and finish again.",
         "</execution_commands>",
         "",
         "<verification_contract>",
         "```json",
-        JSON.stringify({ schema_id: "dd-flow/code-verification@2", verdict: "passed | needs_repair | blocked", summary: "Evidence-backed conclusion.", unresolved: [], deviations: [] }, null, 2),
+        JSON.stringify({ schema_id: "dd-flow/code-verification@2", verdict: "passed", summary: "Evidence-backed conclusion.", unresolved: [], deviations: [] }, null, 2),
         "```",
+        "Allowed verdict values are passed, needs_repair, and blocked. The example is valid JSON using passed; choose exactly one value.",
         "The CLI verifies graph coverage and executes all deterministic checks. Do not duplicate its report; record only your semantic conclusion and evidence.",
         "</verification_contract>",
         "",
@@ -424,103 +542,57 @@ function coordinatorPrompt(context, input) {
 export function profileCommands(workspaceRoot) {
     return aggregateCheckDeclarations(workspaceRoot).map((check) => check.command);
 }
-function latestReceiptsByCommand(receipts) {
-    const latest = new Map();
-    for (const receipt of receipts)
-        for (const ref of receipt.check_refs)
-            latest.set(ref, receipt);
-    return [...new Set(latest.values())];
-}
 /**
- * A CODE finish may be retried after a client loses the long command's output.
- * Reusing complete, same-workspace receipts is correct; rerunning them is both
- * expensive and can race the still-settling original invocation.
+ * The immutable Work result is a repair history. The stage report is a current
+ * acceptance projection, so a registered receipt from an older check epoch
+ * must never stand in for the receipt that currently proves the declaration.
  */
-export function reusableAggregateGateReceipts(context, input) {
-    const expected = new Set(input.checks.map((check) => check.id));
-    const current = workspaceFingerprint(input.workspaceRoot);
-    const latest = new Map();
-    for (const receipt of checkReceipts(context, { projectId: input.projectId, runId: input.runId })) {
-        if (receipt.scope === "aggregate")
-            for (const ref of receipt.check_refs)
-                if (expected.has(ref))
-                    latest.set(ref, receipt);
-    }
-    if (latest.size !== expected.size)
-        return null;
-    const receipts = input.checks.map((check) => latest.get(check.id));
-    return receipts.every((receipt) => receipt.status === "passed" && receipt.workspace_fingerprint === current) ? receipts : null;
-}
-/** One aggregate gate per RUN; a second invocation must wait, never duplicate it. */
-function acquireAggregateGateLock(root) {
-    const directory = path.join(root, "checks");
-    const lock = path.join(directory, ".aggregate-gate.lock");
-    fs.mkdirSync(directory, { recursive: true });
-    try {
-        const descriptor = fs.openSync(lock, "wx");
-        fs.writeFileSync(descriptor, JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }));
-        fs.closeSync(descriptor);
-    }
-    catch (error) {
-        if (!isExistingLock(error))
-            throw error;
-        const activePid = lockPid(lock);
-        if (activePid && processAlive(activePid)) {
-            throw new AppError("code_gate_in_progress", "CODE aggregate gate is already running; wait for that exact stage finish command to return", 1, { pid: activePid, lock });
-        }
-        fs.rmSync(lock, { force: true });
-        return acquireAggregateGateLock(root);
-    }
-    return () => fs.rmSync(lock, { force: true });
-}
-function isExistingLock(error) {
-    return Boolean(error && typeof error === "object" && error.code === "EEXIST");
-}
-function lockPid(lock) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(lock, "utf8"));
-        return Number.isInteger(parsed.pid) && Number(parsed.pid) > 0 ? Number(parsed.pid) : null;
-    }
-    catch {
-        return null;
-    }
-}
-function processAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export function verificationProjection(works, receipts) {
+export function verificationProjection(works, receipts, options = {}) {
     const packets = works.map((work) => packet(work)).filter((value) => value !== null);
     const declarations = uniqueBy(packets.flatMap((value) => value.checks), (value) => value.id);
     const receiptByDeclaration = new Map(receipts.flatMap((receipt) => receipt.check_refs.map((ref) => [ref, receipt])));
-    const evidence = new Map();
+    const rawEvidence = new Map();
     for (const work of works) {
         const result = readJsonResult(work.result);
         for (const item of result.evidence ?? [])
-            if (item.criterion_id)
-                evidence.set(item.criterion_id, unique([...(evidence.get(item.criterion_id) ?? []), ...(item.refs ?? [])]));
+            if (item.obligation_ref)
+                rawEvidence.set(item.obligation_ref, unique([...(rawEvidence.get(item.obligation_ref) ?? []), ...(item.refs ?? [])]));
     }
     const acceptance = uniqueBy(packets.flatMap((value) => value.acceptance), (value) => value.criterion_id);
-    const hasEvidence = (criterionId) => (evidence.get(criterionId)?.length ?? 0) > 0;
-    const isPassed = (checkId, criterionId) => receiptByDeclaration.get(checkId)?.status === "passed" || (declarations.find((check) => check.id === checkId)?.run_at === "external" && hasEvidence(criterionId));
+    const historicalReceiptRefs = new Set((options.historicalReceipts ?? receipts).flatMap((receipt) => receiptReferences(receipt, options)));
+    const acceptanceEvidence = new Map(acceptance.map((item) => {
+        const reported = rawEvidence.get(item.criterion_id) ?? [];
+        const current = unique(item.check_refs.flatMap((checkRef) => {
+            const receipt = receiptByDeclaration.get(checkRef);
+            return receipt?.status === "passed" ? [currentReceiptRef(receipt, options)] : [];
+        }));
+        const evidenceRefs = unique([...reported.filter((ref) => !historicalReceiptRefs.has(ref)), ...current]);
+        const historical = reported.filter((ref) => historicalReceiptRefs.has(ref) && !current.includes(ref));
+        return [item.criterion_id, { evidenceRefs, historical }];
+    }));
+    const hasEvidence = (criterionId) => (acceptanceEvidence.get(criterionId)?.evidenceRefs.length ?? 0) > 0;
+    const isPassed = (checkId) => receiptByDeclaration.get(checkId)?.status === "passed";
     return {
         checks: declarations.map((check) => {
             const receipt = receiptByDeclaration.get(check.id);
-            const externallyEvidenced = check.run_at === "external" && acceptance.some((item) => item.check_refs.includes(check.id) && hasEvidence(item.criterion_id));
-            return { id: check.id, run_at: check.run_at, status: receipt?.status ?? (externallyEvidenced ? "evidence_recorded" : ["work", "code", "readiness"].includes(check.run_at) ? "failed" : "not_due"), receipt_ref: receipt?.receipt_path ?? null };
+            return { id: check.id, run_at: check.run_at, status: receipt?.status ?? (["work", "code", "readiness"].includes(check.run_at) ? "failed" : "not_due"), receipt_ref: receipt?.receipt_path ?? null };
         }),
         acceptance: acceptance.map((item) => {
-            const external = item.check_refs.some((id) => declarations.find((check) => check.id === id)?.run_at === "external");
-            const confirmed = item.check_refs.every((id) => isPassed(id, item.criterion_id)) && hasEvidence(item.criterion_id);
-            return { criterion_id: item.criterion_id, gate: item.gate, status: confirmed ? (external ? "confirmed_with_external_evidence" : "confirmed") : ["work", "code", "readiness"].includes(item.gate) ? "unresolved" : "not_due", check_refs: item.check_refs, evidence_refs: evidence.get(item.criterion_id) ?? [] };
+            const confirmed = item.check_refs.every((id) => isPassed(id)) && hasEvidence(item.criterion_id);
+            const evidence = acceptanceEvidence.get(item.criterion_id) ?? { evidenceRefs: [], historical: [] };
+            return { criterion_id: item.criterion_id, gate: item.gate, status: confirmed ? "confirmed" : ["work", "code", "readiness"].includes(item.gate) ? "unresolved" : "not_due", check_refs: item.check_refs, evidence_refs: evidence.evidenceRefs, ...(evidence.historical.length ? { reported_evidence_refs: evidence.historical } : {}) };
         })
     };
 }
+function currentReceiptRef(receipt, options) {
+    if (!options.runId || !options.runHome)
+        return receipt.receipt_path;
+    const relative = path.relative(options.runHome, receipt.receipt_path).split(path.sep).join("/");
+    return relative && !relative.startsWith("../") ? `run://${options.runId}/${relative}` : receipt.receipt_path;
+}
+function receiptReferences(receipt, options) {
+    return unique([receipt.receipt_path, currentReceiptRef(receipt, options)]);
+}
 function readJsonResult(value) { try {
     const parsed = JSON.parse(value ?? "{}");
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
@@ -572,75 +644,77 @@ function requireRootWork(context, projectId, runId) {
     return work;
 }
 function requireRun(context, projectId, runId) {
-    const run = context.db.get("SELECT id, project_id, run_home_path, workspace_root, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const run = context.db.get("SELECT id, project_id, run_root, workspace_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;
 }
 /** CODE, not PROTOCOLIZE, makes a checkout ready for project tooling. */
-async function ensureCodeWorkspaceReady(context, projectId, run, root, readinessChecks, progress) {
+export function isReusablePreparedCodeReadiness(value, expected) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const receipt = value;
+    return receipt.schema_id === "dd-flow/workspace-readiness@2"
+        && receipt.status === "passed"
+        && receipt.prepared_by === expected.ownerId
+        && receipt.workspace_root === expected.workspaceRoot
+        && receipt.command === expected.command
+        && receipt.policy_ref === expected.policyRef;
+}
+function readPreparedReadiness(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function ensureCodeWorkspaceReady(context, projectId, run, root, readinessChecks, progress, options = {}) {
     const profile = JSON.parse(run.index_json);
     const bootstrap = profile.execution_profile?.settings?.code_bootstrap;
     if (!bootstrap || typeof bootstrap.command !== "string" || typeof bootstrap.policy_ref !== "string") {
         throw new AppError("execution_profile_invalid", "CODE requires a frozen bootstrap command in the RUN execution profile", 1, { run_id: run.id });
     }
     const receiptPath = path.join(root, "workspace-readiness.json");
-    const prior = readReadiness(receiptPath);
-    if (prior?.workspace_root === run.workspace_root && prior.command === bootstrap.command && prior.status === "passed" && JSON.stringify(prior.check_declarations ?? []) === JSON.stringify(readinessChecks))
-        return { ...prior, reused: true };
+    const ownerId = context.env.DD_FLOW_CODE_READINESS_OWNER;
+    if (!options.force && ownerId && isReusablePreparedCodeReadiness(readPreparedReadiness(receiptPath), {
+        ownerId,
+        workspaceRoot: run.workspace_root,
+        command: bootstrap.command,
+        policyRef: bootstrap.policy_ref
+    })) {
+        progress?.("workspace bootstrap already prepared by this controller");
+        return readPreparedReadiness(receiptPath);
+    }
+    // Unowned and stale receipts are never trusted: a direct stage entry still
+    // performs its own readiness check.  Only the same controller can hand a
+    // freshly prepared workspace to its immediately following lifecycle call.
     const startedAt = new Date().toISOString();
     progress?.(`workspace bootstrap started: ${bootstrap.command}`);
-    const result = await runBootstrap(bootstrap.command, run.workspace_root, codeExecutionEnvironment(run.workspace_root), progress);
+    const result = await runWorkspaceBootstrap(context, { projectId, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, command: bootstrap.command, artifactDir: "05-code/readiness", progress });
     const bootstrapPassed = result.exit_code === 0 && !result.error;
     const checks = bootstrapPassed && readinessChecks.length
         ? await runCodeChecks(context, { projectId, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, scope: "aggregate", artifactDir: "05-code/readiness", checks: readinessChecks, ...(progress ? { progress } : {}) })
         : [];
-    const receipt = { schema_id: "dd-flow/workspace-readiness@2", workspace_root: run.workspace_root, command: bootstrap.command, policy_ref: bootstrap.policy_ref, started_at: startedAt, finished_at: new Date().toISOString(), status: bootstrapPassed && checks.every((check) => check.status === "passed") ? "passed" : "failed", exit_code: result.exit_code, stdout: result.stdout, stderr: result.stderr, check_declarations: readinessChecks, checks: checks.map((check) => ({ id: check.id, status: check.status, receipt_path: check.receipt_path })), ...(result.error ? { error: result.error } : {}), receipt_path: receiptPath };
+    const receipt = { schema_id: "dd-flow/workspace-readiness@2", workspace_root: run.workspace_root, command: bootstrap.command, policy_ref: bootstrap.policy_ref, started_at: startedAt, finished_at: new Date().toISOString(), status: bootstrapPassed && checks.every((check) => check.status === "passed") ? "passed" : "failed", ...(ownerId ? { prepared_by: ownerId } : {}), process_id: result.process_id, stdout_path: result.stdout_path, stderr_path: result.stderr_path, completion_path: result.completion_path, exit_code: result.exit_code, stdout: result.stdout, stderr: result.stderr, check_declarations: readinessChecks, checks: checks.map((check) => ({ id: check.id, status: check.status, receipt_path: check.receipt_path })), ...(result.error ? { error: result.error } : {}), receipt_path: receiptPath };
     fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
     if (receipt.status !== "passed")
         throw new AppError("workspace_readiness_failed", "CODE workspace bootstrap failed", 1, receipt);
     progress?.("workspace bootstrap passed");
     return receipt;
 }
-function runBootstrap(command, cwd, environment, progress) {
-    return new Promise((resolve) => {
-        const started = Date.now();
-        const child = spawn("/bin/sh", ["-lc", command], { cwd, env: environment, stdio: ["ignore", "pipe", "pipe"] });
-        let stdout = "";
-        let stderr = "";
-        let error = null;
-        child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout += chunk; });
-        child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk; });
-        const heartbeat = setInterval(() => progress?.(`workspace bootstrap still running (${Math.floor((Date.now() - started) / 1000)}s)`), 15_000);
-        const timeout = setTimeout(() => child.kill("SIGTERM"), 15 * 60 * 1000);
-        child.once("error", (value) => { error = value.message; });
-        child.once("close", (exitCode, signal) => {
-            clearInterval(heartbeat);
-            clearTimeout(timeout);
-            resolve({ exit_code: exitCode, stdout, stderr, error: error ?? (signal ? `terminated by ${signal}` : null) });
-        });
-    });
-}
-function readReadiness(file) {
-    try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
-    }
-    catch {
-        return null;
-    }
-}
 function requireHome(run) {
-    if (!run.run_home_path)
-        throw new AppError("runtime_missing", "RUN workspace is unavailable", 1);
-    return run.run_home_path;
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1);
+    return run.run_root;
 }
-function finishCommand(context, runId, projectRoot, verificationFile) {
-    return `${flowCommand(context)} stage finish ${runId} --stage code --verification-file ${JSON.stringify(verificationFile)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`;
+export function finishCommand(context, runId, projectRoot, verificationFile, retryCheckId) {
+    return managedLifecycleCommand(context, runtimeCommand(context, ["stage", "finish", runId, "--stage", "code", "--verification-file", verificationFile, "--project-root", projectRoot, "--json", "--progress-jsonl", ...checkRetryArgs(context, projectRoot, runId, retryCheckId)]));
 }
 function readVerification(context, input) {
-    const file = path.resolve(input.file);
-    validateSchema({ schemaName: "code-verification", file, projectRoot: input.projectRoot, ddFlowHome: context.ddFlowHome, runId: input.runId });
-    return JSON.parse(fs.readFileSync(file, "utf8"));
+    return prepareJsonSchema(input.file, "CODE verification", {
+        schemaName: "code-verification", projectRoot: input.projectRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.runRoot
+    }).value;
 }
 function verificationForFinish(context, input) {
     return readVerification(context, input);
@@ -662,6 +736,8 @@ export function writeProtocolFlowStatus(workspaceRoot, runHome, runId, status) {
 }
 function nextAction(run, changedPaths) {
     const index = JSON.parse(run.index_json);
+    if (index.variables?.["merge.source_repair"])
+        return "start_code_review";
     const requested = index.settings?.code_review?.mode ?? "auto";
     const enabled = requested === "off" ? false : requested === "auto" ? changedPaths.length > 0 : true;
     const stopTarget = index.execution_profile?.settings?.stop_target;
@@ -677,19 +753,19 @@ function stageStatus(run, name) {
         return null;
     }
 }
-function changedPathsFromReport(file) {
+function isMergeSourceRepairAttempt(run) {
     try {
-        const value = JSON.parse(fs.readFileSync(file, "utf8"));
-        return Array.isArray(value.semantic?.changed_files) ? value.semantic.changed_files.filter((item) => typeof item === "string") : [];
+        const value = JSON.parse(run.index_json);
+        return Boolean(value.variables?.["merge.source_repair"]);
     }
     catch {
-        return [];
+        return false;
     }
 }
-function resultPaths(result) {
+function changedPathsFromReport(file) {
     try {
-        const value = JSON.parse(result ?? "");
-        return Array.isArray(value.changed_paths) ? value.changed_paths.filter((item) => typeof item === "string") : [];
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        return Array.isArray(value.semantic?.changed_files) ? value.semantic.changed_files.filter((item) => typeof item === "string") : [];
     }
     catch {
         return [];
@@ -708,6 +784,28 @@ function uniqueBy(values, key) {
         return true;
     });
 }
+/** Repair pre-atomic terminal stages without repeating accepted checks or rewinding a successor. */
+export function resumeAcceptedCodeStage(context, run, projectRoot, stage, report, next) {
+    const index = JSON.parse(run.index_json);
+    if ((index.current_stage ?? index.stage_runs.at(-1)?.stage) !== stage)
+        return;
+    const terminal = next === "code_completed" || next === "code_review_completed";
+    if (!terminal && index.next_action === next)
+        return;
+    withStageSettlement(context, () => {
+        if (!terminal) {
+            advanceFlowRun(context, { settlementStage: stage, projectRoot, runId: run.id, status: "running", verdict: `${stage.replaceAll("-", "_")}_completed`, nextAction: next });
+            return;
+        }
+        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", [run.project_id, run.id]);
+        if (!work)
+            throw new AppError("runtime_missing", "Accepted stage has no root coordinator", 1);
+        if (work.status !== "completed")
+            finishStageCoordinatorWork(context, work.work_id, JSON.stringify(report, null, 2));
+        if (index.status !== "done")
+            completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: next });
+    });
+}
 function writeReport(root, report) {
     writeStageReport(root, report);
 }