@deksden-com/dd-flow-cli 0.9.0-beta.103 → 0.9.0-beta.105

package/dist/services/stage-pause.js

@@ -6,6 +6,7 @@ import { lifecycleRetryCommands, managedLifecycleCommand } from "./lifecycle-inv
 import { AppError } from "../shared/errors.js";
 import { entityReferenceVariants, shortEntityReference } from "../shared/entity-references.js";
 import { resolveProjectRoot } from "../storage/paths.js";
+import { publishImmutableInput } from "../storage/immutable-input.js";
 import { resolveWorkReference } from "../storage/work-references.js";
 import { findRecentMatchingHookEvent, claimStageResumeHookEvent, stageResumeMatchKey } from "./hooks.js";
 import { requireProjectByRoot } from "./projects.js";
@@ -36,21 +37,15 @@ export function pauseStageForUser(context, input) {
     const pauseRoot = path.join(requireRunHome(run), "intake", "hitl", `${pauseId}-${safeStage(input.stage)}`);
     const questionPath = path.join(pauseRoot, "question.md");
     fs.mkdirSync(pauseRoot, { recursive: true });
-    fs.writeFileSync(questionPath, question);
+    publishImmutableInput(questionPath, Buffer.from(question), "hitl_question_conflict");
     const now = context.now();
-    context.db.beginWriteTransaction();
-    try {
+    context.db.writeTransaction(() => {
         const paused = context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
         if (paused.changes !== 1)
             throw new AppError("invalid_work_state", "Work changed before pause could be accepted", 1, { work_id: work.work_id });
         pauseFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, pauseId, questionPath });
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
-    refreshRunWorkProjection(context, project.id, run.id);
+        context.db.afterCommit(() => refreshRunWorkProjection(context, project.id, run.id));
+    });
     const answerInputPath = path.join(pauseRoot, "answer-input.md");
     const resume = stageResumeCommand(context, { runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, answerInputPath });
     const resumeTemplate = `Write the complete user answer exactly to ${quote([answerInputPath])}, then run:\n${resume}`;
@@ -107,17 +102,11 @@ export function resumeStageAfterUser(context, input) {
     }).eventKey;
     const now = context.now();
     const answerPath = path.join(path.dirname(pause.question_path), `answer-${crypto.createHash("sha256").update(`${pause.id}\0${input.answer}`).digest("hex")}.md`);
-    context.db.beginWriteTransaction();
-    let identity;
-    try {
-        identity = claimStageResumeHookEvent(context, { projectId: project.id, runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, eventKey: hookEventId });
-        try {
-            fs.writeFileSync(answerPath, input.answer, { flag: "wx", mode: 0o600 });
-        }
-        catch (error) {
-            if (error.code !== "EEXIST" || fs.readFileSync(answerPath, "utf8") !== input.answer)
-                throw error;
-        }
+    // The answer is an immutable, content-addressed input. Prepare it before
+    // reserving SQLite's writer; an unreferenced candidate has no flow authority.
+    publishImmutableInput(answerPath, Buffer.from(input.answer), "hitl_answer_conflict");
+    context.db.writeTransaction(() => {
+        const identity = claimStageResumeHookEvent(context, { projectId: project.id, runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, eventKey: hookEventId });
         if (workSession.session_id !== identity.sessionId) {
             bindSessionForResume(context, work.work_id, identity, now);
             context.db.run("UPDATE work_sessions SET status = 'completed', updated_at = ?, completed_at = ? WHERE id = ?", [now, now, workSession.id]);
@@ -127,14 +116,9 @@ export function resumeStageAfterUser(context, input) {
         if (resumed.changes !== 1)
             throw new AppError("invalid_work_state", "Work changed before resume could be accepted", 1, { work_id: work.work_id });
         resumeFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, answerPath });
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
-    refreshRunWorkProjection(context, project.id, run.id);
-    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_resume_session_bound", stage: stage.stage, work_id: work.work_id, session_id: identity.sessionId });
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_resume_session_bound", stage: stage.stage, work_id: work.work_id, session_id: identity.sessionId });
+        context.db.afterCommit(() => refreshRunWorkProjection(context, project.id, run.id));
+    });
     const prompt = evidence.prompt;
     const retryCommands = lifecycleRetryCommands(context, stage.stage);
     const continuation = [

package/dist/services/stage-report-renderer.js

@@ -1,14 +1,129 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { withProjectionLock } from "../storage/projection-lock.js";
 import { writeJsonAtomic } from "../storage/paths.js";
 /** Deterministic JSON -> Markdown/HTML projection shared by every stage. */
 export function writeStageReport(root, report) {
     const json = path.join(root, "stage-report.json");
     const markdown = path.join(root, "stage-report.md");
     const html = path.join(root, "stage-report.html");
+    const normalized = normalizeStageReport(report);
+    writeJsonAtomic(json, normalized);
+    const text = renderStageReportMarkdown(normalized);
+    fs.writeFileSync(markdown, text);
+    fs.writeFileSync(html, renderStageReportHtml(normalized, text));
+    return { json, markdown, html };
+}
+export function prepareStageReport(report) {
+    const normalized = normalizeStageReport(report);
+    const json = `${JSON.stringify(normalized, null, 2)}\n`;
+    const markdown = renderStageReportMarkdown(normalized);
+    const html = renderStageReportHtml(normalized, markdown);
+    return { normalized, bytes: { json, markdown, html }, sha256: crypto.createHash("sha256").update(json).digest("hex") };
+}
+export function prepareStagePacket(file, bytes) {
+    if (fs.existsSync(file) && !bytes.equals(fs.readFileSync(file)))
+        throw new AppError("stage_packet_conflict", "An existing Stage packet differs from prepared bytes", 2, { file });
+    return { file, bytes, sha256: crypto.createHash("sha256").update(bytes).digest("hex") };
+}
+export function acceptStagePacket(context, input) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
+    const index = run ? JSON.parse(run.index_json) : null;
+    const attempt = index?.stage_runs?.find((item) => item.stage === input.stage)?.attempt;
+    if (!attempt)
+        throw new AppError("stage_packet_owner_missing", "Stage packet has no owning attempt", 1, { run_id: input.runId, stage: input.stage });
+    const payload = { run_id: input.runId, stage: input.stage, attempt, file: input.prepared.file, sha256: input.prepared.sha256, base64: input.prepared.bytes.toString("base64") };
+    context.db.run("INSERT INTO audit_events (project_id, event_type, forced, payload_json, created_at) VALUES (?, 'flow_run.stage_packet', 0, ?, ?)", [input.projectId, JSON.stringify(payload), context.now()]);
+    context.db.afterCommit(() => publishStagePacket(context, input.projectId, input.runId, input.stage, input.prepared.file));
+}
+export function publishStagePacket(context, projectId, runId, stage, file) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    withProjectionLock(`${file}.publish-lock`, () => {
+        const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+        const index = run ? JSON.parse(run.index_json) : null;
+        const currentAttempt = index?.stage_runs?.find((item) => item.stage === stage)?.attempt;
+        const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' ORDER BY id DESC", [projectId]);
+        const packet = rows.map((row) => JSON.parse(row.payload_json)).find((item) => item.run_id === runId && item.stage === stage && item.attempt === currentAttempt && item.file === file);
+        if (!packet)
+            return;
+        const bytes = Buffer.from(packet.base64, "base64");
+        if (crypto.createHash("sha256").update(bytes).digest("hex") !== packet.sha256)
+            throw new AppError("stage_packet_invalid", "Stored Stage packet hash does not match its bytes", 1, { file });
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        try {
+            fs.writeFileSync(file, bytes, { flag: "wx" });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (!bytes.equals(fs.readFileSync(file)))
+                throw new AppError("stage_packet_conflict", "Accepted Stage packet differs from the published file", 1, { file, run_id: runId, stage, attempt: currentAttempt });
+        }
+    });
+}
+/** SQL receipt and exact bytes are committed with the owning Stage transition. */
+export function acceptStageReport(context, input) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
+    const index = run ? JSON.parse(run.index_json) : null;
+    const attempt = index?.stage_runs?.find((item) => item.stage === input.stage)?.attempt;
+    if (!attempt)
+        throw new AppError("stage_report_owner_missing", "Stage report has no owning attempt", 1, { run_id: input.runId, stage: input.stage });
+    const payload = { run_id: input.runId, stage: input.stage, attempt, root: input.root, sha256: input.prepared.sha256, bytes: input.prepared.bytes };
+    context.db.run("INSERT INTO audit_events (project_id, event_type, forced, payload_json, created_at) VALUES (?, 'flow_run.stage_report', 0, ?, ?)", [input.projectId, JSON.stringify(payload), context.now()]);
+    context.db.afterCommit(() => publishStageReport(context, input.projectId, input.runId, input.stage, input.root));
+}
+/** Replays the latest committed receipt, never an obsolete attempt. */
+export function publishStageReport(context, projectId, runId, stage, root) {
+    withProjectionLock(`${root}.report-publish-lock`, () => {
+        const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+        const index = run ? JSON.parse(run.index_json) : null;
+        const currentAttempt = index?.stage_runs?.find((item) => item.stage === stage)?.attempt;
+        const events = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_report' ORDER BY id DESC", [projectId]);
+        const receipt = events.map((row) => JSON.parse(row.payload_json)).find((item) => item.run_id === runId && item.stage === stage && item.root === root && item.attempt === currentAttempt);
+        if (!receipt)
+            return;
+        fs.mkdirSync(root, { recursive: true });
+        for (const [name, bytes] of Object.entries(receipt.bytes)) {
+            const file = path.join(root, `stage-report.${name === "json" ? "json" : name === "markdown" ? "md" : "html"}`);
+            try {
+                fs.writeFileSync(file, bytes, { flag: "wx" });
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                if (fs.readFileSync(file, "utf8") !== bytes)
+                    throw new AppError("stage_report_conflict", "Accepted Stage report differs from the published file", 1, { run_id: runId, stage, attempt: currentAttempt, file });
+            }
+        }
+    });
+}
+/** Admission repair for predecessor reports; the stage being retried is archived separately. */
+export function reconcileRunStageReports(context, projectId, runId, exceptStage) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_report' ORDER BY id DESC", [projectId]);
+    const seen = new Set();
+    for (const row of rows) {
+        const receipt = JSON.parse(row.payload_json);
+        if (receipt.run_id !== runId || typeof receipt.stage !== "string" || typeof receipt.root !== "string" || receipt.stage === exceptStage || seen.has(receipt.stage))
+            continue;
+        seen.add(receipt.stage);
+        publishStageReport(context, projectId, runId, receipt.stage, receipt.root);
+    }
+    const packets = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' ORDER BY id DESC", [projectId]);
+    const packetFiles = new Set();
+    for (const row of packets) {
+        const packet = JSON.parse(row.payload_json);
+        if (packet.run_id !== runId || typeof packet.stage !== "string" || typeof packet.file !== "string" || packet.stage === exceptStage || packetFiles.has(packet.file))
+            continue;
+        packetFiles.add(packet.file);
+        publishStagePacket(context, projectId, runId, packet.stage, packet.file);
+    }
+}
+function normalizeStageReport(report) {
     const semantic = object(report.semantic);
     const sourceArtifacts = object(report.artifacts);
-    const normalized = {
+    return {
         ...report,
         schema_id: "dd-flow/stage-report@2",
         summary: string(report.summary) || string(semantic.result) || "Stage completed.",
@@ -27,11 +142,6 @@ export function writeStageReport(root, report) {
             html: string(sourceArtifacts.html) || "stage-report.html"
         }
     };
-    writeJsonAtomic(json, normalized);
-    const text = renderStageReportMarkdown(normalized);
-    fs.writeFileSync(markdown, text);
-    fs.writeFileSync(html, renderStageReportHtml(normalized, text));
-    return { json, markdown, html };
 }
 export function renderStageReportMarkdown(report) {
     const semantic = object(report.semantic);

package/dist/services/usage.js

@@ -167,8 +167,7 @@ export function recalculateRunUsage(context, input) {
     const usageFinal = final && unsettledSessions.length === 0;
     const persistRunProjection = !input.sessionId && !input.stage;
     if (persistRunProjection) {
-        context.db.exec("SAVEPOINT run_usage");
-        try {
+        context.db.writeTransaction(() => {
             context.db.run("DELETE FROM usage WHERE project_id = ? AND run_id = ?", [input.projectId, input.runId]);
             for (const row of rows) {
                 context.db.run(`INSERT INTO usage (id, project_id, run_id, session_id, checkpoint, stage, stage_attempt, observed_at, total_tokens, input_tokens, cached_input_tokens, cache_read_input_tokens, cache_write_input_tokens, uncached_input_tokens, output_tokens, reasoning_output_tokens, source_kind, source_locator, source_sha256, source_size_bytes, source_mtime_ms, token_event_at, turn_id, turn_attribution, parser_version, extraction_status, diagnostic_code, created_at)
@@ -187,13 +186,7 @@ export function recalculateRunUsage(context, input) {
             AND status = 'idle'
             AND NOT EXISTS (SELECT 1 FROM work_sessions WHERE session_id = ? AND status = 'running')`, [observedAt, session.completed_at, input.projectId, input.runId, session.session_id, session.session_id]);
             }
-            context.db.exec("RELEASE run_usage");
-        }
-        catch (error) {
-            context.db.exec("ROLLBACK TO run_usage");
-            context.db.exec("RELEASE run_usage");
-            throw error;
-        }
+        });
     }
     const observations = persistRunProjection ? runObservations(context, input.projectId, input.runId) : null;
     const legacyTools = toolCallsForLinks(context, links, accountingAt);

package/dist/services/vnext-code-review.js

@@ -1,11 +1,12 @@
 import { managedLifecycleCommand } from "./lifecycle-invocations.js";
+import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
-import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, freezeFlowRunReviewMode, gitFacts } from "./runs.js";
+import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, prepareFlowRunStageCompletion, freezeFlowRunReviewMode, gitFacts } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
 import { runtimeCommand, checkRetryArgs } from "./runtime-command.js";
 import { assertStageStartHookEvent } from "./hooks.js";
@@ -15,7 +16,7 @@ import { finalCodeCheckDeclarations, runCodeChecks, validateFailedCheckRetry, wo
 import { addWorkBatch, prepareWorkBatch, bindStageCoordinatorWork, finishStageCoordinatorWork, refreshRunWorkProjection } from "./work-registry.js";
 import { withStageSettlement, prepareFlowRunStageAttachment } from "./runs.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
-import { writeStageReport } from "./stage-report-renderer.js";
+import { acceptStageReport, prepareStageReport } from "./stage-report-renderer.js";
 import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
 import { stageGraphScope } from "./stage-work-graph.js";
@@ -85,7 +86,7 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
     fs.writeFileSync(reviewContextPath, `${JSON.stringify({ schema_id: "dd-flow/code-review-context@1", cycle, mode: mode.mode, mode_source: mode.source, mode_reason: mode.reason, ...(mode.mode !== "off" ? { read_only_input: { parent_work_id: rootWork.work_id, version: 3 } } : {}), code_report_sha256: codeReportSha256, review_batch_sha256: sha256Value(`${JSON.stringify(batch, null, 2)}\n`), aspect_map_checksums: aspectMapChecksums }, null, 2)}\n`);
     if (mode.mode === "off") {
         fs.writeFileSync(path.join(root, "decision.json"), `${JSON.stringify(disabledReviewDecision(), null, 2)}\n`);
-        const prompt = `<stage_identity>\n- RUN: ${run.id}\n- stage: code-review\n- mode: off\n</stage_identity>\n\nCODE-REVIEW is disabled by the frozen RUN configuration. Finish with: ${finishCommand(context, run.id, projectRoot, path.join(root, "decision.json"))}\n`;
+        const prompt = `<stage_identity>\n- RUN: ${run.id}\n- stage: code-review\n- mode: off\n</stage_identity>\n\nCODE-REVIEW is disabled by the frozen RUN configuration. Finish with: ${finishCommand(context, run.id, projectRoot, path.join(root, "decision.json"))}\n${stageLifecycleInstruction}\n`;
         fs.writeFileSync(promptPath, prompt);
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
@@ -94,7 +95,7 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
     }
     const batchFile = path.join(root, "review-work-batch.json");
     fs.writeFileSync(batchFile, `${JSON.stringify(batch, null, 2)}\n`);
-    const prompt = orchestratorPrompt(context, { projectRoot, run, root, rootWork, mode: mode.mode, groups, template, checks });
+    const prompt = `${orchestratorPrompt(context, { projectRoot, run, root, rootWork, mode: mode.mode, groups, template, checks })}\n${stageLifecycleInstruction}\n`;
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
@@ -244,6 +245,8 @@ export async function finishVnextCodeReview(context, input) {
     let mergeRequest = null;
     assertRunMutationAllowed(context, project.id, run.id, generation);
     const prepareMerge = nextAction === "start_merge" ? prepareVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths }) : null;
+    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 currentReviewers = reviewerWorks(context, project.id, run.id, cycle);
@@ -252,8 +255,9 @@ export async function finishVnextCodeReview(context, input) {
             throw new AppError("reviewer_jobs_incomplete", "Review or repair 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 preparedCompletion = prepareFlowRunStageCompletion(context, completionInput);
+        acceptStageReport(context, { projectId: project.id, runId: run.id, stage, root, prepared: preparedReport });
+        completeFlowRunStage(context, completionInput, preparedCompletion);
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_completed", work_id: rootWork.work_id, outcome });
         if (nextAction === "start_merge")
             advanceFlowRun(context, { settlementStage: "code-review", projectRoot, runId: run.id, status: "running", verdict: "code_review_completed", nextAction });
@@ -507,4 +511,3 @@ function readJsonString(value) { try {
 catch {
     return {};
 } }
-function writeReport(root, report) { writeStageReport(root, report); }

package/dist/services/vnext-code.js

@@ -1,4 +1,5 @@
 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 fs from "node:fs";
@@ -7,7 +8,7 @@ import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { aggregateCheckDeclarations, effectiveCheckDeclarations, finalCodeCheckDeclarations, runCodeChecks, validateFailedCheckRetry, workspaceChangedPaths } from "./code-checks.js";
 import { requireProjectByRoot } from "./projects.js";
-import { appendFlowRunTimelineEvent, advanceFlowRun, attachFlowRunStage, prepareFlowRunStageAttachment, completeFlowRunStage, completeFlowRun, withStageSettlement, 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 { runtimeCommand, checkRetryArgs } from "./runtime-command.js";
 import { stageCycle, stageGraphScope } from "./stage-work-graph.js";
@@ -16,7 +17,7 @@ import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
 import { readVnextSpecifyResult } from "./vnext-specify.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 { acceptStageReport, prepareStageReport } from "./stage-report-renderer.js";
 import { prepareVnextMergeRequest } from "./vnext-merge.js";
 import { assertStageStartHookEvent } from "./hooks.js";
 import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
@@ -100,7 +101,7 @@ export async function startVnextCode(context, input, prepared = prepareVnextCode
     const readiness = await ensureCodeWorkspaceReady(context, project.id, run, root, [], input.progress);
     // 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 });
+    const prompt = `${coordinatorPrompt(context, { projectRoot, run, root, rootWork, readiness, template: prepared.template, capacity: prepared.capacity, graph })}\n${stageLifecycleInstruction}\n`;
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, {
@@ -270,6 +271,8 @@ export async function finishVnextCode(context, input) {
     let mergeRequest = null;
     assertRunMutationAllowed(context, project.id, run.id, generation);
     const prepareMerge = next === "start_merge" ? prepareVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths: changedPaths }) : null;
+    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);
@@ -277,17 +280,9 @@ export async function finishVnextCode(context, input) {
             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 preparedCompletion = prepareFlowRunStageCompletion(context, completionInput);
+        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",
@@ -807,6 +802,3 @@ export function resumeAcceptedCodeStage(context, run, projectRoot, stage, report
             completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: next });
     });
 }
-function writeReport(root, report) {
-    writeStageReport(root, report);
-}

package/dist/services/vnext-merge.js

@@ -1,4 +1,5 @@
 import { managedLifecycleCommand } from "./lifecycle-invocations.js";
+import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 import crypto from "node:crypto";
 import { runWorkspaceBootstrap } from "./workspace-bootstrap.js";
 import fs from "node:fs";
@@ -10,10 +11,10 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
 import { nextMergeRequestId } from "./ids.js";
 import { readProjectConfig } from "./config.js";
-import { appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, gitFacts, prepareFlowRunStageAttachment, prepareVnextMergeSourceRepairAttempt } from "./runs.js";
+import { appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, gitFacts, prepareFlowRunStageAttachment, prepareFlowRunStageCompletion, prepareVnextMergeSourceRepairAttempt, withStageSettlement } from "./runs.js";
 import { stagePauseCommand, stagePauseCommandTemplate } from "./stage-pause.js";
 import { runtimeCommand, checkRetryArgs, recoveryEvidenceInput } from "./runtime-command.js";
-import { writeStageReport } from "./stage-report-renderer.js";
+import { acceptStageReport, prepareStageReport, publishStageReport } from "./stage-report-renderer.js";
 import { bindStageCoordinatorWork, createChildWork, failWork, finishFanInWork, finishWork, refreshRunWorkProjection, startStageCoordinatorWork } from "./work-registry.js";
 import { addVnextCodeRepair } from "./vnext-code.js";
 import { checkReceiptEvidenceValid, checkReceipts, codeCheckProfileHash, effectiveCheckDeclarations, runCodeChecks, validateFailedCheckRetry, workspaceChangedPaths, workspaceFingerprint } from "./code-checks.js";
@@ -45,6 +46,9 @@ export function prepareVnextMergeRequest(context, input) {
     const route = settings.merge_mode ?? "same_session";
     const home = requireHome(run);
     const protocols = protocolIds(home);
+    if (route === "same_session" && path.resolve(run.workspace_root) !== path.resolve(projectRoot)) {
+        throw new AppError("merge_session_workspace_conflict", "The existing coordinator Session is bound to the feature workspace, but MERGE executes in the integration checkout", 2, { effect: "no_effect", recoverable: false, source_workspace: run.workspace_root, target_workspace: projectRoot });
+    }
     const sourceBranch = gitValue(run.workspace_root, ["branch", "--show-current"]);
     if (!sourceBranch)
         throw new AppError("merge_source_invalid", "MERGE requires a named source branch", 1, { workspace_root: run.workspace_root });
@@ -158,7 +162,7 @@ export async function startVnextMerge(context, input, prepared = prepareVnextMer
             const binding = pendingWork?.status === "created"
                 ? startStageCoordinatorWork(context, { workId: request.executor_work_id, hookEventId: input.hookEventId, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) })
                 : bindStageCoordinatorWork(context, { workId: request.executor_work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-            const prompt = existingPrompt ?? mergePrompt(context, { run, request, resultPath, projectRoot }, checks, settings);
+            const prompt = existingPrompt ?? `${mergePrompt(context, { run, request, resultPath, projectRoot }, checks, settings)}\n${stageLifecycleInstruction}\n`;
             if (existingPrompt === null)
                 fs.writeFileSync(promptPath, prompt);
             const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
@@ -177,7 +181,7 @@ export async function startVnextMerge(context, input, prepared = prepareVnextMer
         if (claimed.changes !== 1 && requireRequest(context, current.merge_request_id).status !== "active")
             throw new AppError("merge_claim_conflict", "MERGE request could not acquire the integration lane", 1, { merge_request_id: current.merge_request_id });
         const started = startStageCoordinatorWork(context, { workId: current.executor_work_id, hookEventId: input.hookEventId, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-        const prompt = mergePrompt(context, { run, request: requireRequest(context, current.merge_request_id), resultPath, projectRoot }, checks, settings);
+        const prompt = `${mergePrompt(context, { run, request: requireRequest(context, current.merge_request_id), resultPath, projectRoot }, checks, settings)}\n${stageLifecycleInstruction}\n`;
         fs.writeFileSync(promptPath, prompt);
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         context.db.run("UPDATE work_sessions SET prompt_path = ?, result_path = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [promptPath, resultPath, context.now(), current.executor_work_id]);
@@ -330,10 +334,11 @@ export async function finishVnextMerge(context, input, prepared = prepareVnextMe
     assertRunMutationAllowed(context, project.id, run.id, generation);
     const now = context.now();
     context.db.run("UPDATE merge_requests SET status = 'completed', checkpoint = 'finalized', result_json = ?, completed_at = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify(semantic), now, now, request.merge_request_id]);
-    const report = mergeReport(context, run, requireRequest(context, request.merge_request_id), semantic, receipts);
     const root = path.join(requireHome(run), stageDir);
-    writeStageReport(root, report);
-    completeFlowRunStage(context, { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@2", report: "stage-report.md", stageReport: "stage-report.html" });
+    const retainedReport = completedMergeReport(context, run, root);
+    const report = retainedReport ?? mergeReport(context, run, requireRequest(context, request.merge_request_id), semantic, receipts);
+    if (!retainedReport)
+        commitMergeStageReport(context, run, projectRoot, root, report);
     const rootWork = requireRootWork(context, project.id, run.id);
     finishFanInWork(context, rootWork.work_id, JSON.stringify(report));
     completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "merge_completed", nextAction: undefined });
@@ -352,7 +357,11 @@ function ensureMergeStageAttached(context, run, projectRoot) {
 function recoverCompletedMergeRun(context, run, projectRoot, request) {
     const root = path.join(requireHome(run), stageDir);
     const reportPath = path.join(root, "stage-report.json");
-    if (!fs.existsSync(reportPath)) {
+    const retainedReport = completedMergeReport(context, run, root);
+    let report;
+    if (retainedReport)
+        report = retainedReport;
+    else if (!fs.existsSync(reportPath)) {
         const semantic = request.result_json ? JSON.parse(request.result_json) : null;
         const gate = readFrozenMergeGate(path.join(root, "merge-gate.json"), request.merge_request_id);
         const accepted = readMergeGateAcceptance(context, path.join(root, "merge-gate-acceptance.json"), request, gate);
@@ -360,10 +369,13 @@ function recoverCompletedMergeRun(context, run, projectRoot, request) {
             throw new AppError("merge_report_missing", "Completed MERGE has insufficient authoritative evidence to rebuild its report", 1, { merge_request_id: request.merge_request_id, report_path: reportPath });
         verifyLocalDelivery(request);
         performConfiguredCleanup(run, request);
-        writeStageReport(root, mergeReport(context, run, request, semantic, accepted.receipts));
+        report = mergeReport(context, run, request, semantic, accepted.receipts);
     }
+    else
+        report = JSON.parse(fs.readFileSync(reportPath, "utf8"));
     ensureMergeStageAttached(context, run, projectRoot);
-    completeFlowRunStage(context, { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@2", report: "stage-report.md", stageReport: "stage-report.html" });
+    if (!retainedReport)
+        commitMergeStageReport(context, run, projectRoot, root, report);
     const rootWork = findRootWork(context, run.project_id, run.id);
     const rootStatus = rootWork.status;
     if (rootStatus === "running")
@@ -375,23 +387,46 @@ function recoverCompletedMergeRun(context, run, projectRoot, request) {
         completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "merge_completed", nextAction: undefined });
     refreshRunWorkProjection(context, run.project_id, run.id);
 }
+function completedMergeReport(context, run, root) {
+    const current = requireRun(context, run.project_id, run.id);
+    const index = JSON.parse(current.index_json);
+    const entry = index.stage_runs?.find(item => item.stage === stage);
+    if (entry?.status !== "done")
+        return null;
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_report' ORDER BY id DESC", [run.project_id]);
+    const receipt = rows.map(row => JSON.parse(row.payload_json))
+        .find(item => item.run_id === run.id && item.stage === stage && item.attempt === entry.attempt && item.root === root);
+    if (receipt) {
+        if (crypto.createHash("sha256").update(receipt.bytes.json).digest("hex") !== receipt.sha256)
+            throw new AppError("stage_report_invalid", "Accepted MERGE report receipt has invalid bytes", 1, { run_id: run.id });
+        publishStageReport(context, run.project_id, run.id, stage, root);
+        return JSON.parse(receipt.bytes.json);
+    }
+    const file = path.join(root, "stage-report.json");
+    if (!fs.existsSync(file))
+        throw new AppError("merge_report_missing", "Completed MERGE has no accepted report receipt or published report", 1, { run_id: run.id, report_path: file });
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+function commitMergeStageReport(context, run, projectRoot, root, report) {
+    const preparedReport = prepareStageReport(report);
+    const completion = { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@2", report: "stage-report.md", stageReport: "stage-report.html", dataSha256: preparedReport.sha256 };
+    const preparedCompletion = prepareFlowRunStageCompletion(context, completion);
+    withStageSettlement(context, () => {
+        acceptStageReport(context, { projectId: run.project_id, runId: run.id, stage, root, prepared: preparedReport });
+        completeFlowRunStage(context, completion, preparedCompletion);
+    });
+}
 export function routeVnextMergeRequest(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    context.db.beginWriteTransaction();
-    let request;
-    try {
-        request = requireRequest(context, input.requestId);
+    const request = context.db.writeTransaction(() => {
+        const request = requireRequest(context, input.requestId);
         if (request.project_id !== project.id || request.status !== "queued")
             throw new AppError("invalid_merge_state", "Only a queued request without an active dispatch may change route", 2, { status: request.status });
         assertRunMutationAllowed(context, request.project_id, request.run_id);
         context.db.run("UPDATE merge_requests SET execution_route = ?, last_error_json = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'queued'", [input.mode, JSON.stringify({ route_reason: input.reason }), context.now(), request.merge_request_id]);
         context.db.run("UPDATE works SET launch_policy = ?, updated_at = ? WHERE work_id = ? AND status = 'created'", [input.mode === "server" ? "fresh_agent_required" : "reuse_allowed", context.now(), request.executor_work_id]);
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+        return request;
+    });
     refreshRunWorkProjection(context, request.project_id, request.run_id);
     return requestView(context, requireRequest(context, request.merge_request_id));
 }
@@ -431,7 +466,15 @@ export async function repairVnextMerge(context, input) {
     return { ok: true, run_id: request.run_id, merge_request_id: request.merge_request_id, status: "superseded", source_repair: repair, next: { kind: "start_stage", stage: "code", command: managedLifecycleCommand(context, runtimeCommand(context, ["stage", "start", request.run_id, "--stage", "code", "--project-root", projectRoot, "--json", "--progress-jsonl"])) } };
 }
 function mergePrompt(context, input, checks, settings) { const pause = stagePauseCommand(context, { runId: input.run.id, stage: "merge", workId: input.request.executor_work_id, projectRoot: input.projectRoot }); const repair = repairCommand(context, input.request, input.projectRoot); return ["<stage_identity>", `- RUN: ${input.run.id}`, `- MERGE request: ${input.request.merge_request_id}`, `- Work: ${input.request.executor_work_id}`, "- stage: merge", "</stage_identity>", "", "<trusted_runtime_context>", `- integration workspace: ${input.request.target_workspace}`, `- source workspace: ${input.request.source_workspace}`, `- frozen source commit: ${input.request.source_commit}`, `- target branch: ${input.request.target_branch}`, `- execution target baseline: ${input.request.execution_target_head}`, `- queue route: ${input.request.execution_route}`, `- delivery: ${JSON.stringify(settings.merge_delivery)}`, `- cleanup: ${JSON.stringify(settings.merge_cleanup)}`, "These facts and the acquired project integration lane were established by dd-flow. Do not repeat discovery and do not run git merge/rebase/squash yourself.", "</trusted_runtime_context>", "", "<effective_merge_gate>", ...checks.map((check) => `- ${check.canonical_ref ?? check.id}: ${check.command} — ${check.purpose}`), "</effective_merge_gate>", "", "<execution_contract>", `1. Run this exact standalone command first: ${applyCommand(context, input.request, input.projectRoot)}`, "2. If it reports conflicts, resolve only the actual unmerged paths in the integration workspace. Do not repeat merge apply and do not edit product code, tests, documentation or configuration merely to make a gate pass.", `3. Write the compact semantic result to ${input.resultPath}:`, "```json", JSON.stringify({ schema_id: "dd-flow/merge-result@1", outcome: "completed", summary: "What was integrated.", conflict_resolution: "How material conflicts were resolved, or empty when none.", verification_summary: "Why the integrated result is ready for deterministic checks.", residual_risks: [] }, null, 2), "```", `4. Finish with this exact standalone command and wait for all progress: ${finishCommand(context, input.run.id, input.request, input.projectRoot)}`, `If a gate fails, read its receipt and logs and determine the cause. For a product defect use ${repair}; it restores the target baseline and opens CODE → independent CODE-REVIEW → replacement MRG. For an environment failure restore the declared environment in this MERGE and write the returned recovery JSON file and use continuation.command_after_input. The CLI reruns the real gate and retains the old receipt. Never edit product code in the integration target to make a gate pass.`, "If a material conflict has no reasonable answer in accepted evidence, pause this same Work by writing the question file and then running the separate standalone command below, ask the returned user_message, then use the exact resume command returned by CLI:", "```sh", stagePauseCommandTemplate(pause), "```", "</execution_contract>", ""].join("\n"); }
-function mergeReport(context, run, request, semantic, receipts) { const now = context.now(); const cleanup = cleanupReceiptPath(run); return { schema_id: "dd-flow/stage-report@2", run_id: run.id, stage, generated_at: now, verdict: "done", summary: semantic.summary, semantic: { result: semantic.summary, acceptance: ["source_commit_frozen", "integration_commit_created", "merge_gate_passed", "delivery_confirmed"], changed_files: [], checks: receipts.map((item) => item.command), evidence: [applyReceiptPath(context, request), ...receipts.map((item) => item.receipt_path), ...(fs.existsSync(cleanup) ? [cleanup] : [])], next_action: "merge_completed", merge: { merge_request_id: request.merge_request_id, work_id: request.executor_work_id, protocols: JSON.parse(request.protocol_ids_json), source_commit: request.source_commit, execution_target_head: request.execution_target_head, accepted_tree: request.accepted_tree, integration_commit: request.integration_commit, route: request.execution_route, delivery: executionSettings(run).merge_delivery, cleanup: executionSettings(run).merge_cleanup, verification_summary: semantic.verification_summary, residual_risks: semantic.residual_risks } }, mechanical: { started_at: request.lock_acquired_at, finished_at: now, git: gitFacts(request.target_workspace), queue: queueStatus(context, request) }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html" }, validation: { status: "passed" } }; }
+function mergeReport(context, run, request, semantic, receipts) {
+    const now = context.now();
+    const startedAt = request.lock_acquired_at ?? request.created_at;
+    const cleanup = cleanupReceiptPath(run);
+    return { schema_id: "dd-flow/stage-report@2", run_id: run.id, stage, generated_at: now, verdict: "done", summary: semantic.summary,
+        semantic: { result: semantic.summary, acceptance: ["source_commit_frozen", "integration_commit_created", "merge_gate_passed", "delivery_confirmed"], changed_files: [], checks: receipts.map((item) => item.command), evidence: [applyReceiptPath(context, request), ...receipts.map((item) => item.receipt_path), ...(fs.existsSync(cleanup) ? [cleanup] : [])], next_action: "merge_completed", merge: { merge_request_id: request.merge_request_id, work_id: request.executor_work_id, protocols: JSON.parse(request.protocol_ids_json), source_commit: request.source_commit, execution_target_head: request.execution_target_head, accepted_tree: request.accepted_tree, integration_commit: request.integration_commit, route: request.execution_route, delivery: executionSettings(run).merge_delivery, cleanup: executionSettings(run).merge_cleanup, verification_summary: semantic.verification_summary, residual_risks: semantic.residual_risks } },
+        mechanical: { started_at: startedAt, finished_at: now, wall_clock_ms: Math.max(0, Date.parse(now) - Date.parse(startedAt)), git: gitFacts(request.target_workspace), queue: queueStatus(context, request) },
+        artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html" }, validation: { status: "passed" } };
+}
 function effectiveMergeChecks(run, request) { return readFrozenMergeGate(path.join(requireHome(run), stageDir, "merge-gate.json"), request.merge_request_id).checks; }
 function planChecks(workspace, protocols) { return protocols.flatMap((protocol) => { const file = path.join(workspace, ".memory-bank", "protocol", protocol, "plan.json"); if (!fs.existsSync(file))
     return []; const plan = JSON.parse(fs.readFileSync(file, "utf8")); return (plan.checks ?? []).filter((check) => check.availability === "available").map((check) => ({ ...check, canonical_ref: `${protocol}/${check.id}` })); }); }