@deksden-com/dd-flow-cli 0.9.0-beta.7 → 0.9.0-beta.75

package/dist/services/vnext-code.js

@@ -1,26 +1,44 @@
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
-import { spawn } from "node:child_process";
+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, 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, 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 { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
 const stage = "code";
 const stageDir = vnextStageDirectory("code");
+/** 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);
+    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 async function startVnextCode(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
@@ -31,10 +49,12 @@ export async function startVnextCode(context, input) {
     const existingRoot = path.join(home, stageDir);
     const existingPrompt = path.join(existingRoot, "stage-prompt.md");
     const existingStage = stageStatus(run, stage);
+    const sourceRepairAttempt = isMergeSourceRepairAttempt(run);
     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);
+        bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath: existingPrompt, resultPath: path.join(existingRoot, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
         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")) } };
     }
@@ -53,7 +73,8 @@ export async function startVnextCode(context, input) {
         file: batch,
         projectRoot: run.workspace_root,
         ddFlowHome: context.ddFlowHome,
-        runId: input.runId
+        runId: input.runId,
+        runRoot: home
     });
     validateWorkBatchFile(batch);
     const root = path.join(home, stageDir);
@@ -72,14 +93,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"
-    });
+    if (!sourceRepairAttempt) {
+        attachFlowRunStage(context, {
+            projectRoot,
+            runId: input.runId,
+            stage,
+            dir: stageDir,
+            status: "running",
+            dataSchemaId: "dd-flow/stage-report@1"
+        });
+    }
     const graph = codeWorkGraph(context, project.id, input.runId);
     const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
     appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "code_started", work_id: rootWork.work_id, graph });
@@ -104,8 +127,10 @@ export async function finishVnextCode(context, input) {
     const run = requireRun(context, project.id, input.runId);
     const home = requireHome(run);
     const root = path.join(home, stageDir);
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
     requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage });
     if (stageStatus(run, stage) === "done" && fs.existsSync(path.join(root, "stage-report.json"))) {
+        resumeAcceptedCodeStage(context, run, projectRoot, stage, JSON.parse(fs.readFileSync(path.join(root, "stage-report.json"), "utf8")), nextAction(run, changedPathsFromReport(path.join(root, "stage-report.json"))));
         return { ok: true, resumed: true, run_id: run.id, stage, outcome: "accepted", report_path: path.join(root, "stage-report.json"), next_action: nextAction(run, changedPathsFromReport(path.join(root, "stage-report.json"))) };
     }
     const handoffFailures = validateVnextCodeHandoff(context, {
@@ -134,7 +159,7 @@ 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 });
+    const verification = verificationForFinish(context, { file: input.verificationFile, projectRoot: run.workspace_root, 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." };
     }
@@ -153,29 +178,15 @@ export async function finishVnextCode(context, input) {
         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." };
     }
     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, {
@@ -183,23 +194,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);
+    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",
@@ -238,31 +247,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,
@@ -270,7 +289,7 @@ 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) {
@@ -280,7 +299,12 @@ export function addVnextCodeRepair(context, input) {
     const home = requireHome(run);
     if (!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.reviewCycle) {
+        const previous = codeWorks(context, project.id, run.id).find((work) => packet(work)?.review_cycle === input.reviewCycle);
+        if (previous)
+            return { ok: true, run_id: run.id, repair_work_id: previous.work_id, start_command: workStartCommand(context, previous), reused: true };
+    }
+    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);
     }
     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 = ?", [
@@ -303,10 +327,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, {
@@ -315,7 +339,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",
@@ -325,8 +349,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: {
@@ -334,14 +362,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.
@@ -356,7 +384,8 @@ 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 });
@@ -374,16 +403,13 @@ export function addVnextCodeRepair(context, input) {
         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 })
+        ...(receipt ? { check_receipt_id: receipt.id } : input.reviewFindings?.length ? { review_finding_ids: input.reviewFindings.map((finding) => finding.finding_ref) } : { semantic_unresolved: 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);
@@ -438,8 +464,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 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, 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. Read that returned error and run its repair command; 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.",
@@ -461,103 +487,57 @@ function coordinatorPrompt(context, input) {
 export function profileCommands(workspaceRoot) {
     return aggregateCheckDeclarations(workspaceRoot).map((check) => check.command);
 }
-function latestReceiptsByCommand(receipts) {
-    const latest = new Map();
-    for (const receipt of receipts)
-        for (const ref of receipt.check_refs)
-            latest.set(ref, receipt);
-    return [...new Set(latest.values())];
-}
 /**
- * A CODE finish may be retried after a client loses the long command's output.
- * Reusing complete, same-workspace receipts is correct; rerunning them is both
- * expensive and can race the still-settling original invocation.
+ * The immutable Work result is a repair history. The stage report is a current
+ * acceptance projection, so a registered receipt from an older check epoch
+ * must never stand in for the receipt that currently proves the declaration.
  */
-export function reusableAggregateGateReceipts(context, input) {
-    const expected = new Set(input.checks.map((check) => check.id));
-    const current = workspaceFingerprint(input.workspaceRoot);
-    const latest = new Map();
-    for (const receipt of checkReceipts(context, { projectId: input.projectId, runId: input.runId })) {
-        if (receipt.scope === "aggregate")
-            for (const ref of receipt.check_refs)
-                if (expected.has(ref))
-                    latest.set(ref, receipt);
-    }
-    if (latest.size !== expected.size)
-        return null;
-    const receipts = input.checks.map((check) => latest.get(check.id));
-    return receipts.every((receipt) => receipt.status === "passed" && receipt.workspace_fingerprint === current) ? receipts : null;
-}
-/** One aggregate gate per RUN; a second invocation must wait, never duplicate it. */
-function acquireAggregateGateLock(root) {
-    const directory = path.join(root, "checks");
-    const lock = path.join(directory, ".aggregate-gate.lock");
-    fs.mkdirSync(directory, { recursive: true });
-    try {
-        const descriptor = fs.openSync(lock, "wx");
-        fs.writeFileSync(descriptor, JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }));
-        fs.closeSync(descriptor);
-    }
-    catch (error) {
-        if (!isExistingLock(error))
-            throw error;
-        const activePid = lockPid(lock);
-        if (activePid && processAlive(activePid)) {
-            throw new AppError("code_gate_in_progress", "CODE aggregate gate is already running; wait for that exact stage finish command to return", 1, { pid: activePid, lock });
-        }
-        fs.rmSync(lock, { force: true });
-        return acquireAggregateGateLock(root);
-    }
-    return () => fs.rmSync(lock, { force: true });
-}
-function isExistingLock(error) {
-    return Boolean(error && typeof error === "object" && error.code === "EEXIST");
-}
-function lockPid(lock) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(lock, "utf8"));
-        return Number.isInteger(parsed.pid) && Number(parsed.pid) > 0 ? Number(parsed.pid) : null;
-    }
-    catch {
-        return null;
-    }
-}
-function processAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export function verificationProjection(works, receipts) {
+export function verificationProjection(works, receipts, options = {}) {
     const packets = works.map((work) => packet(work)).filter((value) => value !== null);
     const declarations = uniqueBy(packets.flatMap((value) => value.checks), (value) => value.id);
     const receiptByDeclaration = new Map(receipts.flatMap((receipt) => receipt.check_refs.map((ref) => [ref, receipt])));
-    const evidence = new Map();
+    const rawEvidence = new Map();
     for (const work of works) {
         const result = readJsonResult(work.result);
         for (const item of result.evidence ?? [])
-            if (item.criterion_id)
-                evidence.set(item.criterion_id, unique([...(evidence.get(item.criterion_id) ?? []), ...(item.refs ?? [])]));
+            if (item.obligation_ref)
+                rawEvidence.set(item.obligation_ref, unique([...(rawEvidence.get(item.obligation_ref) ?? []), ...(item.refs ?? [])]));
     }
     const acceptance = uniqueBy(packets.flatMap((value) => value.acceptance), (value) => value.criterion_id);
-    const hasEvidence = (criterionId) => (evidence.get(criterionId)?.length ?? 0) > 0;
-    const isPassed = (checkId, criterionId) => receiptByDeclaration.get(checkId)?.status === "passed" || (declarations.find((check) => check.id === checkId)?.run_at === "external" && hasEvidence(criterionId));
+    const historicalReceiptRefs = new Set((options.historicalReceipts ?? receipts).flatMap((receipt) => receiptReferences(receipt, options)));
+    const acceptanceEvidence = new Map(acceptance.map((item) => {
+        const reported = rawEvidence.get(item.criterion_id) ?? [];
+        const current = unique(item.check_refs.flatMap((checkRef) => {
+            const receipt = receiptByDeclaration.get(checkRef);
+            return receipt?.status === "passed" ? [currentReceiptRef(receipt, options)] : [];
+        }));
+        const evidenceRefs = unique([...reported.filter((ref) => !historicalReceiptRefs.has(ref)), ...current]);
+        const historical = reported.filter((ref) => historicalReceiptRefs.has(ref) && !current.includes(ref));
+        return [item.criterion_id, { evidenceRefs, historical }];
+    }));
+    const hasEvidence = (criterionId) => (acceptanceEvidence.get(criterionId)?.evidenceRefs.length ?? 0) > 0;
+    const isPassed = (checkId) => receiptByDeclaration.get(checkId)?.status === "passed";
     return {
         checks: declarations.map((check) => {
             const receipt = receiptByDeclaration.get(check.id);
-            const externallyEvidenced = check.run_at === "external" && acceptance.some((item) => item.check_refs.includes(check.id) && hasEvidence(item.criterion_id));
-            return { id: check.id, run_at: check.run_at, status: receipt?.status ?? (externallyEvidenced ? "evidence_recorded" : ["work", "code", "readiness"].includes(check.run_at) ? "failed" : "not_due"), receipt_ref: receipt?.receipt_path ?? null };
+            return { id: check.id, run_at: check.run_at, status: receipt?.status ?? (["work", "code", "readiness"].includes(check.run_at) ? "failed" : "not_due"), receipt_ref: receipt?.receipt_path ?? null };
         }),
         acceptance: acceptance.map((item) => {
-            const external = item.check_refs.some((id) => declarations.find((check) => check.id === id)?.run_at === "external");
-            const confirmed = item.check_refs.every((id) => isPassed(id, item.criterion_id)) && hasEvidence(item.criterion_id);
-            return { criterion_id: item.criterion_id, gate: item.gate, status: confirmed ? (external ? "confirmed_with_external_evidence" : "confirmed") : ["work", "code", "readiness"].includes(item.gate) ? "unresolved" : "not_due", check_refs: item.check_refs, evidence_refs: evidence.get(item.criterion_id) ?? [] };
+            const confirmed = item.check_refs.every((id) => isPassed(id)) && hasEvidence(item.criterion_id);
+            const evidence = acceptanceEvidence.get(item.criterion_id) ?? { evidenceRefs: [], historical: [] };
+            return { criterion_id: item.criterion_id, gate: item.gate, status: confirmed ? "confirmed" : ["work", "code", "readiness"].includes(item.gate) ? "unresolved" : "not_due", check_refs: item.check_refs, evidence_refs: evidence.evidenceRefs, ...(evidence.historical.length ? { reported_evidence_refs: evidence.historical } : {}) };
         })
     };
 }
+function currentReceiptRef(receipt, options) {
+    if (!options.runId || !options.runHome)
+        return receipt.receipt_path;
+    const relative = path.relative(options.runHome, receipt.receipt_path).split(path.sep).join("/");
+    return relative && !relative.startsWith("../") ? `run://${options.runId}/${relative}` : receipt.receipt_path;
+}
+function receiptReferences(receipt, options) {
+    return unique([receipt.receipt_path, currentReceiptRef(receipt, options)]);
+}
 function readJsonResult(value) { try {
     const parsed = JSON.parse(value ?? "{}");
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
@@ -609,75 +589,79 @@ function requireRootWork(context, projectId, runId) {
     return work;
 }
 function requireRun(context, projectId, runId) {
-    const run = context.db.get("SELECT id, project_id, run_home_path, workspace_root, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const run = context.db.get("SELECT id, project_id, run_root, workspace_root, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     if (!run)
         throw new AppError("not_found", "RUN is not registered", 1);
     return run;
 }
 /** CODE, not PROTOCOLIZE, makes a checkout ready for project tooling. */
-async function ensureCodeWorkspaceReady(context, projectId, run, root, readinessChecks, progress) {
+export function isReusablePreparedCodeReadiness(value, expected) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const receipt = value;
+    return receipt.schema_id === "dd-flow/workspace-readiness@2"
+        && receipt.status === "passed"
+        && receipt.prepared_by === expected.ownerId
+        && receipt.workspace_root === expected.workspaceRoot
+        && receipt.command === expected.command
+        && receipt.policy_ref === expected.policyRef;
+}
+function readPreparedReadiness(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function ensureCodeWorkspaceReady(context, projectId, run, root, readinessChecks, progress, options = {}) {
     const profile = JSON.parse(run.index_json);
     const bootstrap = profile.execution_profile?.settings?.code_bootstrap;
     if (!bootstrap || typeof bootstrap.command !== "string" || typeof bootstrap.policy_ref !== "string") {
         throw new AppError("execution_profile_invalid", "CODE requires a frozen bootstrap command in the RUN execution profile", 1, { run_id: run.id });
     }
     const receiptPath = path.join(root, "workspace-readiness.json");
-    const prior = readReadiness(receiptPath);
-    if (prior?.workspace_root === run.workspace_root && prior.command === bootstrap.command && prior.status === "passed" && JSON.stringify(prior.check_declarations ?? []) === JSON.stringify(readinessChecks))
-        return { ...prior, reused: true };
+    const ownerId = context.env.DD_FLOW_CODE_READINESS_OWNER;
+    if (!options.force && ownerId && isReusablePreparedCodeReadiness(readPreparedReadiness(receiptPath), {
+        ownerId,
+        workspaceRoot: run.workspace_root,
+        command: bootstrap.command,
+        policyRef: bootstrap.policy_ref
+    })) {
+        progress?.("workspace bootstrap already prepared by this controller");
+        return readPreparedReadiness(receiptPath);
+    }
+    // Unowned and stale receipts are never trusted: a direct stage entry still
+    // performs its own readiness check.  Only the same controller can hand a
+    // freshly prepared workspace to its immediately following lifecycle call.
     const startedAt = new Date().toISOString();
     progress?.(`workspace bootstrap started: ${bootstrap.command}`);
-    const result = await runBootstrap(bootstrap.command, run.workspace_root, codeExecutionEnvironment(run.workspace_root), progress);
+    const result = await runWorkspaceBootstrap(context, { projectId, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, command: bootstrap.command, artifactDir: "05-code/readiness", progress });
     const bootstrapPassed = result.exit_code === 0 && !result.error;
     const checks = bootstrapPassed && readinessChecks.length
         ? await runCodeChecks(context, { projectId, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, scope: "aggregate", artifactDir: "05-code/readiness", checks: readinessChecks, ...(progress ? { progress } : {}) })
         : [];
-    const receipt = { schema_id: "dd-flow/workspace-readiness@2", workspace_root: run.workspace_root, command: bootstrap.command, policy_ref: bootstrap.policy_ref, started_at: startedAt, finished_at: new Date().toISOString(), status: bootstrapPassed && checks.every((check) => check.status === "passed") ? "passed" : "failed", exit_code: result.exit_code, stdout: result.stdout, stderr: result.stderr, check_declarations: readinessChecks, checks: checks.map((check) => ({ id: check.id, status: check.status, receipt_path: check.receipt_path })), ...(result.error ? { error: result.error } : {}), receipt_path: receiptPath };
+    const receipt = { schema_id: "dd-flow/workspace-readiness@2", workspace_root: run.workspace_root, command: bootstrap.command, policy_ref: bootstrap.policy_ref, started_at: startedAt, finished_at: new Date().toISOString(), status: bootstrapPassed && checks.every((check) => check.status === "passed") ? "passed" : "failed", ...(ownerId ? { prepared_by: ownerId } : {}), process_id: result.process_id, stdout_path: result.stdout_path, stderr_path: result.stderr_path, completion_path: result.completion_path, exit_code: result.exit_code, stdout: result.stdout, stderr: result.stderr, check_declarations: readinessChecks, checks: checks.map((check) => ({ id: check.id, status: check.status, receipt_path: check.receipt_path })), ...(result.error ? { error: result.error } : {}), receipt_path: receiptPath };
     fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
     if (receipt.status !== "passed")
         throw new AppError("workspace_readiness_failed", "CODE workspace bootstrap failed", 1, receipt);
     progress?.("workspace bootstrap passed");
     return receipt;
 }
-function runBootstrap(command, cwd, environment, progress) {
-    return new Promise((resolve) => {
-        const started = Date.now();
-        const child = spawn("/bin/sh", ["-lc", command], { cwd, env: environment, stdio: ["ignore", "pipe", "pipe"] });
-        let stdout = "";
-        let stderr = "";
-        let error = null;
-        child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout += chunk; });
-        child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk; });
-        const heartbeat = setInterval(() => progress?.(`workspace bootstrap still running (${Math.floor((Date.now() - started) / 1000)}s)`), 15_000);
-        const timeout = setTimeout(() => child.kill("SIGTERM"), 15 * 60 * 1000);
-        child.once("error", (value) => { error = value.message; });
-        child.once("close", (exitCode, signal) => {
-            clearInterval(heartbeat);
-            clearTimeout(timeout);
-            resolve({ exit_code: exitCode, stdout, stderr, error: error ?? (signal ? `terminated by ${signal}` : null) });
-        });
-    });
-}
-function readReadiness(file) {
-    try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
-    }
-    catch {
-        return null;
-    }
-}
 function requireHome(run) {
-    if (!run.run_home_path)
-        throw new AppError("runtime_missing", "RUN workspace is unavailable", 1);
-    return run.run_home_path;
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1);
+    return run.run_root;
 }
-function finishCommand(context, runId, projectRoot, verificationFile) {
-    return `${flowCommand(context)} stage finish ${runId} --stage code --verification-file ${JSON.stringify(verificationFile)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`;
+export function finishCommand(context, runId, projectRoot, verificationFile, retryCheckId) {
+    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 });
-    return JSON.parse(fs.readFileSync(file, "utf8"));
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    validateSchema({ schemaName: "code-verification", file, data, projectRoot: input.projectRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.runRoot });
+    return data;
 }
 function verificationForFinish(context, input) {
     return readVerification(context, input);
@@ -699,6 +683,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;
@@ -714,19 +700,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 [];
@@ -745,6 +731,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);
 }