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

package/dist/services/vnext-code.js

@@ -1,43 +1,66 @@
-import crypto from "node:crypto";
-import { spawn } from "node:child_process";
+import { managedLifecycleCommand } from "./lifecycle-invocations.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, workspaceChangedPaths, 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 { 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,
@@ -57,12 +80,25 @@ export async function startVnextCode(context, input) {
         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 });
+        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: `${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")) } };
+    }
     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, {
@@ -73,15 +109,16 @@ 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);
+    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 });
     appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "code_started", work_id: rootWork.work_id, graph });
     return {
@@ -105,8 +142,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, {
@@ -135,7 +174,8 @@ 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, runRoot: home });
+    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." };
     }
@@ -149,34 +189,21 @@ export async function finishVnextCode(context, input) {
             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. Run the returned repair Work, then update code-verification.json and invoke this same stage finish command again." };
+        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) {
         throw new AppError("code_gate_failed", "CODE remains running because the aggregate project gate failed", 2, {
@@ -184,23 +211,21 @@ export async function finishVnextCode(context, input) {
             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`
+            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`,
+            retry_command: finishCommand(context, run.id, projectRoot, input.verificationFile, failed[0].id)
         });
     }
-    const allReceipts = checkReceipts(context, { projectId: project.id, runId: run.id });
-    const finalReceipts = latestReceiptsByCommand(allReceipts);
-    const projectedVerification = verificationProjection(works, finalReceipts, { historicalReceipts: allReceipts, runId: run.id, runHome: home });
+    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 reportedPaths = [...new Set(works.flatMap((work) => resultPaths(work.result)))];
-    const observedChangedPaths = workspaceChangedPaths(run.workspace_root);
-    const changedPaths = observedChangedPaths ?? reportedPaths;
-    const missingReportedPaths = observedChangedPaths === null ? [] : reportedPaths.filter((item) => !observedChangedPaths.includes(item));
-    if (missingReportedPaths.length)
-        throw new AppError("changed_path_not_materialized", "CODE Work reported paths that are not changed in the accepted workspace", 2, { paths: missingReportedPaths });
+    // 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);
     const report = {
         schema_id: "dd-flow/stage-report@1",
@@ -239,31 +264,41 @@ export async function finishVnextCode(context, input) {
     // 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.
-    const mergeRequest = next === "start_merge" ? ensureVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths: changedPaths }) : 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)
+    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 });
-    }
     return {
         ok: true,
         run_id: run.id,
@@ -271,19 +306,44 @@ 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, `${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: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`) } } : {})
     };
 }
-export function addVnextCodeRepair(context, input) {
+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);
+        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 && !input.semanticUnresolved?.length) {
+    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,
         input.checkReceiptId
@@ -304,10 +364,10 @@ export function addVnextCodeRepair(context, input) {
     // 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 = finalCodeCheckDeclarations(run.workspace_root, codeWorks(context, project.id, run.id)
+    const declaredChecks = effectiveCheckDeclarations(run.workspace_root, codeWorks(context, project.id, run.id)
         .map((work) => packet(work))
         .filter((value) => !value.repair)
-        .flatMap((value) => value.checks));
+        .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, {
@@ -316,7 +376,7 @@ export function addVnextCodeRepair(context, input) {
         });
     }
     const semanticRepair = Boolean(input.semanticUnresolved?.length);
-    const key = input.reviewFindingIds?.length ? "code-review-repair" : semanticRepair ? "code-verification-repair" : "code-gate-repair";
+    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",
@@ -326,8 +386,12 @@ 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)) } : {}),
-            ...(semanticRepair ? { semantic_unresolved: unique(input.semanticUnresolved ?? []), verification_path: input.verificationPath } : {})
+            ...(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: {
@@ -335,14 +399,14 @@ export function addVnextCodeRepair(context, input) {
             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}` : semanticRepair ? `Resolve CODE verification gap(s): ${input.semanticUnresolved.join("; ")}` : `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 ?? []), ...(semanticRepair && input.verificationPath ? [input.verificationPath] : []), ...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.
@@ -357,34 +421,32 @@ export function addVnextCodeRepair(context, input) {
             ...(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 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 registered = addWorkBatch(context, { parentWorkId, prepared: items });
     const id = String(registered.work_ids[key]);
     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 } : input.reviewFindingIds?.length ? { review_finding_ids: input.reviewFindingIds } : { semantic_unresolved: input.semanticUnresolved })
+        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) };
 }
-/** Retain the causal declaration for worker context; run_at keeps aggregate gates at stage scope. */
+/** Retain the causal declaration for worker context; run_at still records its original gate. */
 export function selectRepairChecks(input) {
-    // Gate placement belongs to the accepted PLAN. `runCodeChecks` executes only
-    // work-scoped entries, while retaining the aggregate declaration tells the
-    // worker exactly what will be rerun by the coordinator.
     const candidates = input.failedCheck ? [input.failedCheck] : 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);
@@ -414,10 +476,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}`,
@@ -439,8 +498,8 @@ 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.",
+        "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: " + `${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 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. Its repair_command only creates the repair Work; use it with the required origin Work IDs, then end the Turn. Do not invoke that new 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. 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.`,
         `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.",
@@ -462,76 +521,6 @@ 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.
- */
-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;
-    }
-}
 /**
  * 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
@@ -545,8 +534,8 @@ export function verificationProjection(works, receipts, options = {}) {
     for (const work of works) {
         const result = readJsonResult(work.result);
         for (const item of result.evidence ?? [])
-            if (item.criterion_id)
-                rawEvidence.set(item.criterion_id, unique([...(rawEvidence.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 historicalReceiptRefs = new Set((options.historicalReceipts ?? receipts).flatMap((receipt) => receiptReferences(receipt, options)));
@@ -561,18 +550,16 @@ export function verificationProjection(works, receipts, options = {}) {
         return [item.criterion_id, { evidenceRefs, historical }];
     }));
     const hasEvidence = (criterionId) => (acceptanceEvidence.get(criterionId)?.evidenceRefs.length ?? 0) > 0;
-    const isPassed = (checkId, criterionId) => receiptByDeclaration.get(checkId)?.status === "passed" || (declarations.find((check) => check.id === checkId)?.run_at === "external" && hasEvidence(criterionId));
+    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);
+            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 ? (external ? "confirmed_with_external_evidence" : "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 } : {}) };
+            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 } : {}) };
         })
     };
 }
@@ -642,69 +629,72 @@ function requireRun(context, projectId, runId) {
     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_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) {
+    const retry = retryCheckId ? ` --retry-check ${retryCheckId} --reason "<environment recovery evidence>"` : "";
+    return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage code --verification-file ${JSON.stringify(verificationFile)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl${retry}`);
 }
 function readVerification(context, input) {
-    const file = path.resolve(input.file);
-    validateSchema({ schemaName: "code-verification", file, projectRoot: input.projectRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.runRoot });
-    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);
@@ -726,6 +716,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;
@@ -741,19 +733,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 [];
@@ -772,6 +764,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);
 }