@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.141

package/dist/services/vnext-code.js

@@ -1,44 +1,73 @@
-import crypto from "node:crypto";
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
+import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { ensureAggregateRepair, ensureRepairIntent } from "./repair-intents.js";
 import { runWorkspaceBootstrap } from "./workspace-bootstrap.js";
+import crypto from "node:crypto";
 import fs from "node:fs";
+import { prepareAgentOutputFile } from "../storage/agent-output.js";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
+import { assertSourceRepairEligible } from "./check-runner-evidence.js";
 import { resolveProjectRoot } from "../storage/paths.js";
-import { aggregateCheckDeclarations, checkReceipts, finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceChangedPaths, workspaceFingerprint } from "./code-checks.js";
+import { aggregateCheckDeclarations, checkReceipts, 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, prepareFlowRunStageCompletion, 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 { acceptStageReport, prepareStageReport } from "./stage-report-renderer.js";
+import { prepareVnextMergeRequest } from "./vnext-merge.js";
 import { assertStageStartHookEvent } from "./hooks.js";
-import { applyExternalStageContext } from "./stage-context.js";
+import { currentStagePrompt, 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";
+import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, publishVerificationMatrix, latestRunVerificationMatrix } from "./verification-matrix.js";
+import { stageSuccessor } from "./vnext-contracts.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(context, { 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 });
+    requireVnextWorkspaceRoute(context, { 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) };
     }
+    const attachment = sourceRepairAttempt ? null : 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,
@@ -58,14 +87,32 @@ 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 });
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "input", completeness: "declared", ...(attachment ? { stageAttempt: attachment.attempt } : {}) });
+    return { ...common, resumed: false, template, capacity: variables.variables?.["runtime.subagent.available_slots"], matrix };
+}
+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 } : {}) });
+    prepareAgentOutputFile(path.join(requireHome(run), "works", rootWork.work_id, "block-summary.md"));
+    if (prepared.resumed) {
+        resumeVerificationMatrix(context, project.id, run.id, stage);
+        const externalContext = applyExternalStageContext({ context, 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, ...currentStagePrompt(context, promptPath), ...(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")) } };
+    }
+    if (!sourceRepairAttempt)
+        prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" }, true);
     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 })}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, prepared.home, "implementation and code-verification.json")}\n`;
     fs.writeFileSync(promptPath, prompt);
-    const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    const externalContext = applyExternalStageContext({ context, stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, {
         workId: rootWork.work_id,
         hookEventId: input.hookEventId,
@@ -75,17 +122,20 @@ export async function startVnextCode(context, input) {
         ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {})
     });
     if (!sourceRepairAttempt) {
-        attachFlowRunStage(context, {
+        const attachmentInput = {
             projectRoot,
             runId: input.runId,
             stage,
             dir: stageDir,
             status: "running",
             dataSchemaId: "dd-flow/stage-report@1"
-        });
+        };
+        const attachment = prepareFlowRunStageAttachment(context, attachmentInput);
+        commitVerificationMatrixStart(context, prepared.matrix, () => attachFlowRunStage(context, attachmentInput, attachment));
     }
-    const graph = codeWorkGraph(context, project.id, input.runId);
-    const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
+    else
+        commitVerificationMatrixStart(context, prepared.matrix, () => undefined);
+    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,
@@ -93,13 +143,12 @@ export async function startVnextCode(context, input) {
         stage,
         root_work_id: rootWork.work_id,
         id: binding.work_session_id,
-        prompt_path: promptPath,
-        worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"),
+        ...currentStagePrompt(context, promptPath),
         ...(externalContext ? { external_context: externalContext } : {}),
         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) {
@@ -108,8 +157,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);
-    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage });
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
+    requireVnextWorkspaceRoute(context, { 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, {
@@ -138,9 +189,12 @@ 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 });
+    const retainedMatrix = latestRunVerificationMatrix(context, project.id, run.id, stage);
+    const retainedMatrixInstruction = verificationMatrixInstruction(retainedMatrix?.metadata ?? null, home, "the current semantic verification and repair");
     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." };
+        return { ok: true, run_id: run.id, stage, outcome: "blocked", verification, ...(retainedMatrix ? { verification_matrix: retainedMatrix.metadata } : {}), 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.\n${retainedMatrixInstruction}` };
     }
     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 });
@@ -152,58 +206,59 @@ 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, ...(retainedMatrix ? { verification_matrix: retainedMatrix.metadata } : {}), 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.\n${retainedMatrixInstruction}` };
     }
     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");
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "output", receipts, semanticFile: input.verificationFile });
+    const matrixInstruction = matrix ? verificationMatrixInstruction(matrix.metadata, home, "semantic verification in code-verification.json") : "";
     if (failed.length) {
+        assertSourceRepairEligible(failed);
+        context.db.writeTransaction(() => acceptVerificationMatrix(context, matrix));
+        publishVerificationMatrix(context, matrix);
+        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,
+            ...(matrix ? { verification_matrix: matrix.metadata, verification_matrix_instruction: matrixInstruction } : {}),
+            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.\n${matrixInstruction}`
         });
     }
-    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;
+    if (verification.verdict === "needs_checks") {
+        context.db.writeTransaction(() => acceptVerificationMatrix(context, matrix));
+        publishVerificationMatrix(context, matrix);
+        return { ok: true, run_id: run.id, stage, outcome: "verification_required", verification,
+            ...(matrix ? { verification_matrix: matrix.metadata, verification_matrix_instruction: matrixInstruction } : {}),
+            receipts: finalReceipts.map(receipt => ({ id: receipt.id, receipt_path: receipt.receipt_path, input_hash: receipt.input_hash, status: receipt.status })),
+            next: { kind: "verification_required", finish_command: finishCommand(context, run.id, projectRoot, input.verificationFile) },
+            instruction: `Aggregate receipts are available. Keep CODE running. Inspect them, update code-verification.json to passed or needs_repair, then invoke only the issued successor finish_command. A material document change belongs to the registered fresh repair Work, not this coordinator Session.\n${matrixInstruction}` };
+    }
+    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",
@@ -233,8 +288,8 @@ 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" }
@@ -242,31 +297,38 @@ 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;
+    if (matrix)
+        Object.assign(report.semantic, { verification_matrix: matrix.metadata });
+    const preparedReport = prepareStageReport(report);
+    const completionInput = { 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", dataSha256: preparedReport.sha256, git: report.mechanical.git };
+    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;
+        const preparedCompletion = prepareFlowRunStageCompletion(context, completionInput);
+        acceptVerificationMatrix(context, matrix);
+        acceptStageReport(context, { projectId: project.id, runId: run.id, stage, root, prepared: preparedReport });
+        completeFlowRunStage(context, completionInput, preparedCompletion);
+        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,
@@ -274,19 +336,69 @@ 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: stageSuccessor(context, { projectRoot, runId: run.id, stage: "code-review", command: runtimeCommand(context, ["stage", "start", run.id, "--stage", "code-review", "--project-root", projectRoot, "--json"]) }) } : next === "start_merge" ? { merge_request: mergeRequest, next: stageSuccessor(context, { projectRoot, runId: run.id, stage: "merge", command: 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 (input.semanticUnresolved?.length && input.verificationPath) {
+        const previous = codeWorks(context, project.id, run.id).find(work => {
+            const repair = packet(work)?.repair;
+            return Boolean(repair && repair.verification_path === input.verificationPath
+                && JSON.stringify(repair.semantic_unresolved) === JSON.stringify(unique(input.semanticUnresolved ?? [])));
+        });
+        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.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);
+    let semanticVerification = input.verification;
+    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 });
+        semanticVerification = verification;
+        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
@@ -296,6 +408,8 @@ export function addVnextCodeRepair(context, input) {
             check_receipt_id: input.checkReceiptId
         });
     }
+    if (input.checkReceiptId)
+        assertSourceRepairEligible(checkReceipts(context, { projectId: project.id, runId: run.id }).filter(item => item.id === input.checkReceiptId));
     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 || input.semanticUnresolved?.length
@@ -307,10 +421,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, {
@@ -330,7 +444,11 @@ export function addVnextCodeRepair(context, input) {
             origin_work_ids: origins.map((work) => work.work_id),
             ...(receipt ? { check_receipt_id: receipt.id, failure_receipt_path: receipt.receipt_path } : {}),
             ...(input.reviewFindings?.length ? { review_findings: input.reviewFindings } : {}),
-            ...(semanticRepair ? { semantic_unresolved: unique(input.semanticUnresolved ?? []), verification_path: input.verificationPath } : {})
+            ...(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: {
@@ -344,7 +462,17 @@ export function addVnextCodeRepair(context, input) {
         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: [],
+        document_updates: semanticRepair ? uniqueBy((semanticVerification?.document_updates ?? []).map(relative => {
+            const declared = invariantPackets.flatMap(value => value.document_updates).find(value => value.path === relative);
+            if (!declared)
+                throw new AppError("document_update_unknown", "CODE verification selected a document absent from accepted Work ownership", 2, { path: relative });
+            const file = path.resolve(run.workspace_root, relative);
+            if (!file.startsWith(`${path.resolve(run.workspace_root)}${path.sep}`))
+                throw new AppError("document_update_invalid", "CODE verification document path escapes the workspace", 2, { path: relative });
+            const exists = fs.existsSync(file);
+            return { ...declared, action: exists ? "update" : "create",
+                baseline_sha256: exists ? crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") : null };
+        }), value => value.path) : [],
         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
@@ -363,33 +491,33 @@ export function addVnextCodeRepair(context, input) {
         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, { preview: true }), 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 } : input.reviewFindings?.length ? { review_finding_ids: input.reviewFindings.map((finding) => finding.finding_ref) } : { 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) };
+    return { ok: true, run_id: run.id, repair_work_id: id, start_command: workStartCommand(context, work, { preview: true }) };
 }
-/** 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 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);
 }
@@ -417,16 +545,14 @@ 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");
+export function coordinatorPrompt(context, input) {
+    const { graph, capacity, template } = input;
     return [
         "<stage_identity>",
         `- RUN: ${input.run.id}`,
         `- root Work: ${input.rootWork.work_id}`,
         "- stage: code",
+        "Before any project edit, change into the immutable write workspace shown below with cd --. Write only that workspace and the named CODE verification artifacts under the stage workspace; never another RUN/native home or Git/worktree control data.",
         "</stage_identity>",
         "",
         "<trusted_runtime_context>",
@@ -443,17 +569,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.`,
-        `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.",
+        "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. If closing an accepted document depends on aggregate checks that have not run yet, use verdict needs_checks; the first finish returns receipts and a successor finish_command while CODE remains open. After checking those receipts, use needs_repair with document_updates naming only assigned documents that must change, or passed if the current documents already prove acceptance. 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"))}`,
+        "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@3", verdict: "passed", summary: "Evidence-backed conclusion.", unresolved: [], deviations: [], document_updates: [] }, null, 2),
         "```",
+        "Allowed verdict values are passed, needs_checks, needs_repair, and blocked. The example is valid JSON using passed; choose exactly one value. A verification_required result is successful receipt gathering, not Stage completion; use its issued successor command after updating this file.",
         "The CLI verifies graph coverage and executes all deterministic checks. Do not duplicate its report; record only your semantic conclusion and evidence.",
         "</verification_contract>",
         "",
@@ -466,76 +593,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
@@ -552,7 +609,13 @@ export function verificationProjection(works, receipts, options = {}) {
             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 byCriterionGate = new Map();
+    for (const entry of packets.flatMap((value) => value.acceptance)) {
+        const key = JSON.stringify([entry.criterion_id, entry.gate]);
+        const previous = byCriterionGate.get(key);
+        byCriterionGate.set(key, { criterion_id: entry.criterion_id, gate: entry.gate, check_refs: unique([...(previous?.check_refs ?? []), ...entry.check_refs]) });
+    }
+    const acceptance = [...byCriterionGate.values()];
     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) ?? [];
@@ -565,18 +628,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 } : {}) };
         })
     };
 }
@@ -646,15 +707,45 @@ 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 });
+        throw new AppError("execution_profile_invalid", "CODE requires an evidenced bootstrap command and policy in the frozen RUN profile; configure code_bootstrap before starting a code-ready RUN", 1, { run_id: run.id });
     }
     const receiptPath = path.join(root, "workspace-readiness.json");
-    // Re-run the project bootstrap on stage entry: a prior receipt cannot prove
-    // that ignored dependencies or local services still exist.
+    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 runWorkspaceBootstrap(context, { projectId, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, command: bootstrap.command, artifactDir: "05-code/readiness", progress });
@@ -662,7 +753,7 @@ async function ensureCodeWorkspaceReady(context, projectId, run, root, readiness
     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", 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 };
+    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);
@@ -674,13 +765,13 @@ function requireHome(run) {
         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, 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);
@@ -737,15 +828,6 @@ function changedPathsFromReport(file) {
         return [];
     }
 }
-function resultPaths(result) {
-    try {
-        const value = JSON.parse(result ?? "");
-        return Array.isArray(value.changed_paths) ? value.changed_paths.filter((item) => typeof item === "string") : [];
-    }
-    catch {
-        return [];
-    }
-}
 function unique(values) {
     return [...new Set(values)];
 }
@@ -759,6 +841,25 @@ function uniqueBy(values, key) {
         return true;
     });
 }
-function writeReport(root, report) {
-    writeStageReport(root, report);
+/** 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 });
+    });
 }