@deksden-com/dd-flow-cli 0.9.0-beta.144 → 0.9.0-beta.149

package/dist/services/stage-handlers.js

@@ -9,7 +9,9 @@ import { finishVnextMerge, startVnextMerge } from "./vnext-merge.js";
 import { ResolvedFlowDescriptor } from "./flow-descriptors.js";
 import { vnextStages } from "../domain/stage-catalog.js";
 import { sdlcHandlerIdentities as ids } from "../domain/stage-handler-identities.js";
-import { memoryInitStageHandlers } from "./memory-stage-dispatch.js";
+import { memoryInitStageHandlers, memoryUpgradeStageHandlers } from "./memory-stage-dispatch.js";
+import { diagnosticStageHandlers } from "./diagnostic-stage-handlers.js";
+import { isDiagnosticFlow, diagnosticFlowStages } from "../domain/diagnostic-flows.js";
 /** Engine-owned code, not a plugin registration surface or executable descriptor expression. */
 export const sdlcStageHandlers = Object.freeze({
     specify: Object.freeze({ ...ids.specify, entry: launchVnextSpecify, finish: finishVnextSpecifyStage }),
@@ -23,8 +25,8 @@ export const sdlcStageHandlers = Object.freeze({
 /** A fresh inventory cannot mutate the registered handler functions. */
 export function bundledHandlerContext(blobs) {
     return {
-        entryHandlers: new Set([...Object.values(sdlcStageHandlers), ...Object.values(memoryInitStageHandlers)].map(handler => handler.entryId)),
-        finishHandlers: new Set([...Object.values(sdlcStageHandlers), ...Object.values(memoryInitStageHandlers)].map(handler => handler.finishId)), blobs
+        entryHandlers: new Set([...Object.values(sdlcStageHandlers), ...Object.values(memoryInitStageHandlers), ...Object.values(memoryUpgradeStageHandlers), ...diagnosticStageHandlers].map(handler => handler.entryId)),
+        finishHandlers: new Set([...Object.values(sdlcStageHandlers), ...Object.values(memoryInitStageHandlers), ...Object.values(memoryUpgradeStageHandlers), ...diagnosticStageHandlers].map(handler => handler.finishId)), blobs
     };
 }
 /** Handler identity is also stage/flow scoped: a known CODE handler is not a memory handler. */
@@ -40,8 +42,9 @@ export function admitBundledFlow(input, sha256, blobs) {
             throw new AppError("flow_handler_scope_invalid", "SDLC handlers require the registered seven-stage layout and transitions", 2, { phase: "prepare", effect: "no_effect" });
         }
     }
-    if (flow.descriptor.id === "mb-init") {
-        const stages = Object.keys(memoryInitStageHandlers);
+    if (flow.descriptor.id === "mb-init" || flow.descriptor.id === "mb-upgrade") {
+        const upgrade = flow.descriptor.id === "mb-upgrade";
+        const stages = Object.keys(upgrade ? memoryUpgradeStageHandlers : memoryInitStageHandlers);
         const edges = stages.slice(0, -1).map((from, index) => ({ from, to: stages[index + 1], on: "accepted" }));
         // Historical packs have only accepted transitions; diagnostic VERIFY uses
         // the same REVIEW handler without granting another route or stage.
@@ -59,12 +62,24 @@ export function admitBundledFlow(input, sha256, blobs) {
                 schemaId = JSON.parse(flow.stageBlob(stage.id, "result_schema").toString("utf8")).$id;
             }
             catch { /* Invalid schema cannot authorize this stage handler. */ }
-            if (schemaId !== `dd-flow/mb-init-${stage.id}-result@1`)
+            if (schemaId !== (upgrade ? "dd-flow/mb-upgrade-stage-result@1" : `dd-flow/mb-init-${stage.id}-result@1`))
                 throw new AppError("flow_handler_scope_invalid", "Memory init stage requires its own registered result schema", 2, { phase: "prepare", effect: "no_effect", stage: stage.id });
         }
     }
+    if (isDiagnosticFlow(flow.descriptor.id)) {
+        const stages = diagnosticFlowStages[flow.descriptor.id];
+        if (flow.descriptor.entry_stage !== "preflight" || flow.descriptor.terminal_stages.length !== 1 || flow.descriptor.terminal_stages[0] !== "report"
+            || flow.descriptor.stages.length !== stages.length || flow.descriptor.edges.length !== stages.length - 1
+            || flow.descriptor.stages.some((stage, index) => stage.id !== stages[index] || stage.directory !== `${String(index + 1).padStart(2, "0")}-${stage.id}`)
+            || stages.slice(0, -1).some((stage, index) => !flow.descriptor.edges.some(edge => edge.from === stage && edge.to === stages[index + 1] && edge.on === "accepted"))
+            || flow.descriptor.stages.some(stage => JSON.parse(flow.stageBlob(stage.id, "result_schema").toString("utf8")).$id !== "dd-flow/diagnostic-stage-result@1")) {
+            throw new AppError("flow_handler_scope_invalid", "Diagnostic handlers require their registered four-stage layout and result schema", 2, { phase: "prepare", effect: "no_effect" });
+        }
+    }
     for (const stage of flow.descriptor.stages) {
-        const handlers = flow.descriptor.id === "sdlc" ? Object.values(sdlcStageHandlers) : flow.descriptor.id === "mb-init" ? Object.values(memoryInitStageHandlers) : [];
+        const handlers = flow.descriptor.id === "sdlc" ? Object.values(sdlcStageHandlers) : flow.descriptor.id === "mb-init" ? Object.values(memoryInitStageHandlers)
+            : flow.descriptor.id === "mb-upgrade" ? Object.values(memoryUpgradeStageHandlers)
+                : diagnosticStageHandlers.filter(handler => handler.flowId === flow.descriptor.id);
         const handler = handlers.find(candidate => candidate.stage === stage.id);
         if (!handler || stage.entry_handler !== handler.entryId || stage.finish_handler !== handler.finishId) {
             throw new AppError("flow_handler_scope_invalid", "Registered handlers do not belong to this flow stage", 2, { phase: "prepare", effect: "no_effect", flow_id: flow.descriptor.id, stage: stage.id });

package/dist/services/stage-pause.js

@@ -17,8 +17,11 @@ import { assertRunMutationAllowed } from "./run-recovery.js";
 import { runtimeCommand } from "./runtime-command.js";
 import { prepareAgentOutputFile } from "../storage/agent-output.js";
 import { latestRunVerificationMatrix } from "./verification-matrix.js";
-import { validateAcceptedIntentReview } from "./accepted-intent.js";
+import { acceptedIntentReviewFingerprint, prepareAcceptedIntentSources, validatePreparedAcceptedIntentReview } from "./accepted-intent.js";
 export { flowCommand } from "./runtime-command.js";
+export function stageResumeSourcePath(pause, answer) {
+    return path.join(path.dirname(pause.question_path), `resume-${crypto.createHash("sha256").update(`${pause.id}\0${answer}`).digest("hex")}.json`);
+}
 export function prepareStagePause(context, input) {
     if (typeof input.question !== "string" || !input.question.trim())
         throw new AppError("validation", "stage pause requires a non-empty user question", 2);
@@ -116,7 +119,31 @@ export function resumeStageAfterUser(context, input) {
     // reserving SQLite's writer; an unreferenced candidate has no flow authority.
     publishImmutableInput(answerPath, Buffer.from(input.answer), "hitl_answer_conflict");
     const answerPacket = prepareStagePacket(answerPath, Buffer.from(input.answer));
-    context.db.writeTransaction(() => {
+    // Capture the exact continuation inputs and already-issued commands before
+    // accepting the answer. A publication retry must not issue new authority.
+    const retryCommands = lifecycleRetryCommands(context, stage.stage);
+    const resumeSourcePath = stageResumeSourcePath(pause, input.answer);
+    let review;
+    let reviewPreparationError;
+    const previousAnswer = context.db.get("SELECT MAX(id) AS id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ?", [project.id, run.id])?.id ?? 0;
+    if (["plan-review", "code-review"].includes(stage.stage)) {
+        try {
+            const home = requireRunHome(run), source = latestRunVerificationMatrix(context, project.id, run.id, stage.stage, "input");
+            const reviewContext = path.join(home, stage.stage === "plan-review" ? "04-plan-review/work-context.json" : "06-code-review/review-context.json");
+            const retainedContext = fs.existsSync(reviewContext) ? JSON.parse(fs.readFileSync(reviewContext, "utf8")) : null;
+            const currentSources = acceptedIntentReviewFingerprint(source?.metadata.accepted_sources) ? prepareAcceptedIntentSources(context, { projectId: project.id, runId: run.id, home, stageDirectory: "intake", marked: true }).sources : [];
+            review = { home, source, retainedContext, currentSources };
+        }
+        catch (error) {
+            if (!(error instanceof AppError))
+                throw error;
+            reviewPreparationError = error;
+        }
+    }
+    return context.db.writeTransaction(() => {
+        const currentAnswer = context.db.get("SELECT MAX(id) AS id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ?", [project.id, run.id])?.id ?? 0;
+        if (currentAnswer !== previousAnswer)
+            throw new AppError("runtime_state_changed", "Accepted inputs changed during resume preparation", 1);
         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);
@@ -130,49 +157,56 @@ export function resumeStageAfterUser(context, input) {
         acceptStagePacket(context, { projectId: project.id, runId: run.id, stage: stage.stage, prepared: answerPacket });
         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 intentInstructions = [];
-    if (["plan-review", "code-review"].includes(stage.stage)) {
-        try {
-            const home = requireRunHome(run), source = latestRunVerificationMatrix(context, project.id, run.id, stage.stage, "input");
-            const reviewContext = path.join(home, stage.stage === "plan-review" ? "04-plan-review/work-context.json" : "06-code-review/review-context.json");
-            const retainedContext = fs.existsSync(reviewContext) ? JSON.parse(fs.readFileSync(reviewContext, "utf8")) : null;
-            validateAcceptedIntentReview(context, { projectId: project.id, runId: run.id, home, stage: stage.stage, decisionFrozen: Boolean(retainedContext?.accepted_decision) }, source?.metadata.accepted_sources, retainedContext?.accepted_intent_review_fingerprint);
+        const prompt = evidence.prompt;
+        const intentInstructions = [];
+        if (["plan-review", "code-review"].includes(stage.stage)) {
+            try {
+                if (reviewPreparationError)
+                    throw reviewPreparationError;
+                if (review) {
+                    const id = context.db.get("SELECT id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.pause_id') = ? ORDER BY id DESC LIMIT 1", [project.id, run.id, pause.id]).id;
+                    const identity = `accepted_hitl:${String(id).padStart(12, "0")}:${pause.id}`;
+                    const sources = [...review.currentSources, { role: `${identity}:0-question`, sha256: crypto.createHash("sha256").update(evidence.question).digest("hex") }, { role: `${identity}:1-answer`, sha256: crypto.createHash("sha256").update(input.answer).digest("hex") }];
+                    validatePreparedAcceptedIntentReview(context, { projectId: project.id, runId: run.id, home: review.home, stage: stage.stage, decisionFrozen: Boolean(review.retainedContext?.accepted_decision) }, review.source?.metadata.accepted_sources, review.retainedContext?.accepted_intent_review_fingerprint, sources);
+                }
+            }
+            catch (error) {
+                if (!(error instanceof AppError))
+                    throw error;
+                intentInstructions.push(`Accepted-input review boundary: ${error.code}: ${error.message}`);
+                if (error.code === "accepted_intent_review_ack_required")
+                    intentInstructions.push(`Apply/classify this own-stage clarification through the existing coordinator correction/repair route. Include this exact field in the decision: ${JSON.stringify({ accepted_intent_acknowledgement: error.details.accepted_intent_acknowledgement })}. Independent reviewer results prove only the earlier retained inputs; do not claim they reviewed the new answer.`);
+                else
+                    intentInstructions.push("Do not accept stale independent review as coverage of this answer; report the actionable upstream revision/evidence blocker.");
+            }
         }
-        catch (error) {
-            if (!(error instanceof AppError))
-                throw error;
-            intentInstructions.push(`Accepted-input review boundary: ${error.code}: ${error.message}`);
-            if (error.code === "accepted_intent_review_ack_required")
-                intentInstructions.push(`Apply/classify this own-stage clarification through the existing coordinator correction/repair route. Include this exact field in the decision: ${JSON.stringify({ accepted_intent_acknowledgement: error.details.accepted_intent_acknowledgement })}. Independent reviewer results prove only the earlier retained inputs; do not claim they reviewed the new answer.`);
-            else
-                intentInstructions.push("Do not accept stale independent review as coverage of this answer; report the actionable upstream revision/evidence blocker.");
-        }
-    }
-    const continuation = [
-        prompt.trimEnd(),
-        "",
-        "<hitl_resume>",
-        `- Pause: ${pause.id}`,
-        `- Question source: ${pause.question_path}`,
-        `- Answer source: ${answerPath}`,
-        "- Continue the same stage, Work and attempt. Do not call stage start or repeat completed preparation.",
-        ...intentInstructions,
-        ...(retryCommands.length ? ["- A prior no-effect lifecycle rejection now has these authoritative replacement commands; correct the rejected input and use only these replacements:", ...retryCommands.map(command => `  ${command}`)] : []),
-        "",
-        "<user_question>",
-        evidence.question,
-        "</user_question>",
-        "",
-        "<user_answer>",
-        input.answer,
-        "</user_answer>",
-        "</hitl_resume>",
-        ""
-    ].join("\n");
-    return { ok: true, outcome: "resumed", run_id: run.id, work_id: work.work_id, stage: stage.stage, pause_id: pause.id, question_path: pause.question_path, answer_path: answerPath, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, next_action: `continue_${stage.stage}` };
+        const continuation = [
+            prompt.trimEnd(),
+            "",
+            "<hitl_resume>",
+            `- Pause: ${pause.id}`,
+            `- Question source: ${pause.question_path}`,
+            `- Answer source: ${answerPath}`,
+            "- Continue the same stage, Work and attempt. Do not call stage start or repeat completed preparation.",
+            ...intentInstructions,
+            ...(retryCommands.length ? ["- A prior no-effect lifecycle rejection now has these authoritative replacement commands; correct the rejected input and use only these replacements:", ...retryCommands.map(command => `  ${command}`)] : []),
+            "",
+            "<user_question>",
+            evidence.question,
+            "</user_question>",
+            "",
+            "<user_answer>",
+            input.answer,
+            "</user_answer>",
+            "</hitl_resume>",
+            ""
+        ].join("\n");
+        const result = { ok: true, outcome: "resumed", run_id: run.id, work_id: work.work_id, stage: stage.stage, pause_id: pause.id, question_path: pause.question_path, answer_path: answerPath, resume_source_path: resumeSourcePath, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, next_action: `continue_${stage.stage}` };
+        const scope = context.env.DD_FLOW_INVOCATION_SCOPE ? JSON.parse(context.env.DD_FLOW_INVOCATION_SCOPE) : null;
+        const bytes = Buffer.from(`${JSON.stringify({ invocation_id: context.env.DD_FLOW_CURRENT_INVOCATION ?? null, generation: scope?.generation ?? null, result })}\n`);
+        acceptStagePacket(context, { projectId: project.id, runId: run.id, stage: stage.stage, prepared: { file: resumeSourcePath, bytes, sha256: crypto.createHash("sha256").update(bytes).digest("hex") } });
+        return result;
+    });
 }
 export function stagePauseCommand(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -180,6 +214,39 @@ export function stagePauseCommand(context, input) {
     const questionInputPath = prepareAgentOutputFile(path.join(requireRunHome(run), "works", input.workId, "question-input.md"));
     return managedLifecycleCommand(context, runtimeCommand(context, ["stage", "pause", shortEntityReference(input.runId), "--stage", input.stage, "--work", shortEntityReference(input.workId), "--question-file", questionInputPath, "--project-root", input.projectRoot, "--json"]));
 }
+/** Recover only the exact resume committed with this invocation; never resume again. */
+export function recoverCommittedStageResume(context, input) {
+    const project = requireProjectByRoot(context, input.projectRoot), run = requireRun(context, project.id, input.runId);
+    const work = requireWork(context, project.id, run.id, input.workId);
+    const index = JSON.parse(run.index_json);
+    const current = index.stage_runs.find(stage => stage.stage === input.stage);
+    if (!current || current.status !== "running" || index.current_stage && index.current_stage !== input.stage || work.status !== "running")
+        return null;
+    const resumed = context.db.get("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.stage') = ? AND json_extract(payload_json, '$.work_id') = ? ORDER BY id DESC LIMIT 1", [project.id, run.id, input.stage, work.work_id]);
+    if (!resumed)
+        return null;
+    const acceptedPause = JSON.parse(resumed.payload_json);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.stage') = ? AND json_extract(payload_json, '$.attempt') = ? AND json_extract(payload_json, '$.file') LIKE '%/resume-%.json' ORDER BY id DESC LIMIT 257", [project.id, run.id, input.stage, current.attempt]);
+    if (rows.length > 256)
+        throw new AppError("stage_resume_receipt_invalid", "Resume receipt count exceeds its bound", 1);
+    let result = null;
+    for (const row of rows) {
+        const packet = JSON.parse(row.payload_json);
+        const bytes = Buffer.from(packet.base64, "base64");
+        if (bytes.length > 8 * 1024 * 1024 || bytes.toString("base64") !== packet.base64 || crypto.createHash("sha256").update(bytes).digest("hex") !== packet.sha256)
+            throw new AppError("stage_resume_receipt_invalid", "Resume receipt custody differs from its committed bytes", 1);
+        const retained = JSON.parse(bytes.toString("utf8"));
+        if (retained.invocation_id !== input.id)
+            continue;
+        const value = retained.result;
+        if (retained.generation !== input.generation || !value || value.run_id !== run.id || value.work_id !== work.work_id || value.stage !== input.stage
+            || value.pause_id !== acceptedPause.pause_id || value.answer_path !== acceptedPause.answer_path || value.resume_source_path !== packet.file || typeof value.worker_prompt_markdown !== "string"
+            || result && JSON.stringify(result) !== JSON.stringify(value))
+            throw new AppError("stage_resume_receipt_invalid", "Resume receipt does not match the current invocation and accepted pause", 1);
+        result = value;
+    }
+    return result;
+}
 /** Render separate file-write and lifecycle-call instructions for HITL. */
 export function stagePauseCommandTemplate(command) {
     const questionFile = command.match(/--question-file\s+(?:'([^']*)'|"([^"]*)"|(\S+))/)?.slice(1).find(Boolean) ?? "<question-file-from-command>";

package/dist/services/version-status.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { parse as parseYaml } from "yaml";
-const canonicalOnlyFlowNames = ["mb-init.md", "mb-upgrade.md", "mb-distill.md"];
+export const canonicalOnlyFlowNames = Object.freeze(["mb-init.md", "mb-upgrade.md", "mb-distill.md", "mb-audit.md", "review.md"]);
 export function resolveStatusProjectRoot(input) {
     if (input.requestedRoot) {
         const absolute = path.resolve(input.requestedRoot);

package/dist/services/vnext-code.js

@@ -194,7 +194,7 @@ export async function finishVnextCode(context, input) {
     const retainedMatrix = latestRunVerificationMatrix(context, project.id, run.id, stage);
     const retainedMatrixInstruction = verificationMatrixInstruction(retainedMatrix?.metadata ?? null, home, "the current semantic verification and repair");
     if (verification.verdict === "blocked") {
-        return { ok: true, run_id: run.id, stage, outcome: "blocked", verification, ...(retainedMatrix ? { verification_matrix: retainedMatrix.metadata } : {}), instruction: `CODE remains running. Resolve the stated external or user-input blocker in this same coordinator session, update code-verification.json, then invoke this same stage finish command again.\n${retainedMatrixInstruction}` };
+        return { ok: true, run_id: run.id, stage, outcome: "blocked", verification, ...(retainedMatrix ? { verification_matrix: retainedMatrix.metadata } : {}), instruction: `CODE remains running. Resolve the stated external or user-input blocker in this same coordinator session, update code-verification.json, then invoke next.finish_command. Do not repeat while the blocker remains unresolved.\n${retainedMatrixInstruction}`, next: { finish_command: finishCommand(context, run.id, projectRoot, input.verificationFile) } };
     }
     if (verification.verdict === "passed" && verification.unresolved.length > 0) {
         throw new AppError("verification_contradictory", "A passed CODE verification cannot contain unresolved obligations", 2, { unresolved: verification.unresolved });
@@ -209,7 +209,7 @@ export async function finishVnextCode(context, input) {
             verification,
             objective: verification.summary
         });
-        return { ok: true, run_id: run.id, stage, outcome: "repair_required", verification, repair, ...(retainedMatrix ? { verification_matrix: retainedMatrix.metadata } : {}), instruction: `The semantic verification is not accepted. The repair Work is already registered: do not invoke its start_command in this coordinator Session. End this Turn so the controller can launch it in a fresh child Session. After that Work completes, update code-verification.json and invoke this same stage finish command again.\n${retainedMatrixInstruction}` };
+        return { ok: true, run_id: run.id, stage, outcome: "repair_required", verification, repair, ...(retainedMatrix ? { verification_matrix: retainedMatrix.metadata } : {}), instruction: `The semantic verification is not accepted. The repair Work is already registered: do not invoke its start_command in this coordinator Session. End this Turn so the controller can launch it in a fresh child Session. After that Work completes, update code-verification.json and invoke next.finish_command.\n${retainedMatrixInstruction}`, next: { finish_command: finishCommand(context, run.id, projectRoot, input.verificationFile) } };
     }
     const checks = finalCodeCheckDeclarations(run.workspace_root, works.flatMap((work) => packet(work)?.checks ?? []));
     if (input.retryCheckId) {

package/dist/services/vnext-fanout.js

@@ -15,6 +15,8 @@ import { renderNativeChildFollowupInstruction } from "../harness-runtime/lib/del
 import { readDescriptorRootWork } from "./descriptor-root-work.js";
 import { selectMemoryCompositionRegistration } from "./memory-composition-registration.js";
 import { safeNativeFailure } from "../harness-runtime/lib/native-children.mjs";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { readRegisteredDiagnosticGraph } from "./diagnostic-work-registration.js";
 export const subagentCapacityKey = "runtime.subagent.available_slots";
 /** External concurrency is policy, never evidence of native child qualification. */
 export function getStageFanoutCapacity(context, input) {
@@ -105,7 +107,7 @@ export function verifiedNativeWorkFailure(context, input) {
 }
 export function fanoutState(input) {
     if (!input.hasWork)
-        return input.dispatch === "none" ? "coordinator_required" : "dispatch_required";
+        return input.registeredEmpty ? "children_settled" : input.dispatch === "none" ? "coordinator_required" : "dispatch_required";
     if (input.capacityRequired && !input.capacityKnown)
         return "capacity_required";
     if (input.created || input.running)
@@ -133,14 +135,17 @@ export function readFanoutDescriptor(stageRoot) {
  * productive assignments, including reviewer/correction waves.
  */
 export function memoryStageFanoutDescriptor(context, input) {
-    if (!["compose", "review"].includes(input.stage))
+    if (!["compose", "upgrade", "review"].includes(input.stage))
         return null;
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = context.db.get("SELECT flow_kind,index_json FROM runs WHERE project_id=? AND id=?", [project.id, input.runId]);
-    if (run?.flow_kind !== "mb-init")
+    if (!run || !["mb-init", "mb-upgrade"].includes(run.flow_kind))
+        return null;
+    const authoringStage = run.flow_kind === "mb-init" ? "compose" : "upgrade";
+    if (input.stage !== authoringStage && input.stage !== "review")
         return null;
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init")
+    if (!bundle || bundle.descriptor.descriptor.id !== run.flow_kind)
         throw new AppError("stage_graph_compatibility_required", "Memory graph requires its admitted RUN bundle", 1);
     const index = JSON.parse(run.index_json);
     if (index.current_stage !== input.stage || !index.stage_runs.some(stage => stage.stage === input.stage && stage.status === "running"))
@@ -153,7 +158,7 @@ export function memoryStageFanoutDescriptor(context, input) {
         if (id === root.workId)
             continue;
         const work = context.db.get("SELECT parent_work_id,result_schema FROM works WHERE project_id=? AND run_id=? AND work_id=?", [project.id, input.runId, id]);
-        const schemas = input.stage === "compose" ? ["dd-flow/memory-composition-work-result@1"] : ["dd-flow/memory-review-work-result@1", "dd-flow/memory-repair-work-result@1"];
+        const schemas = input.stage === authoringStage ? ["dd-flow/memory-composition-work-result@1"] : ["dd-flow/memory-review-work-result@1", "dd-flow/memory-repair-work-result@1"];
         if (!work || work.parent_work_id !== root.workId || !schemas.includes(work.result_schema ?? ""))
             throw new AppError("stage_graph_conflict", "Memory graph contains an unassigned Work", 1);
         const custody = readWorkBatchCustody(context, id);
@@ -161,11 +166,11 @@ export function memoryStageFanoutDescriptor(context, input) {
             || custody.scope.cycle !== scope.cycle || custody.scope.stage !== input.stage || custody.scope.parent_work_id !== root.workId)
             throw new AppError("stage_graph_conflict", "Memory graph contains foreign allocation custody", 1);
     }
-    if (input.stage === "compose") {
+    if (input.stage === authoringStage) {
         const children = context.db.all("SELECT work_id FROM works WHERE project_id=? AND run_id=? AND parent_work_id=?", [project.id, input.runId, root.workId]).filter(work => members.has(work.work_id));
         const registered = context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.composition_registration' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=? AND json_extract(payload_json,'$.scope.cycle')=? LIMIT 1", [project.id, input.runId, scope.attempt, scope.cycle]);
         if (children.length || registered) {
-            const registration = selectMemoryCompositionRegistration(context, { ...scope, stage: "compose", parent_work_id: root.workId });
+            const registration = selectMemoryCompositionRegistration(context, { ...scope, stage: authoringStage, parent_work_id: root.workId });
             const ids = new Set(Object.values(registration.work_ids));
             if (ids.size !== children.length || children.some(work => !ids.has(work.work_id)))
                 throw new AppError("stage_graph_conflict", "Memory composition differs from its registered graph", 1);
@@ -173,6 +178,30 @@ export function memoryStageFanoutDescriptor(context, input) {
     }
     return { schema_id: "dd-flow/work-fanout@2", kind: "work_fanout", scope, stage: input.stage, parent_work_id: root.workId, dispatch: "none", capacity_required: true };
 }
+/** Diagnostic graphs are registered by the Stage handler, never fanout.json. */
+export function diagnosticStageFanoutDescriptor(context, input) {
+    if (!["audit", "analyze", "review"].includes(input.stage))
+        return null;
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = context.db.get("SELECT flow_kind,index_json FROM runs WHERE project_id=? AND id=?", [project.id, input.runId]);
+    if (!run || !isDiagnosticFlow(run.flow_kind))
+        return null;
+    const index = JSON.parse(run.index_json);
+    if (index.current_stage !== input.stage || !index.stage_runs.some(stage => stage.stage === input.stage && stage.status === "running"))
+        return null;
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.manifest.flow_id !== run.flow_kind)
+        throw new AppError("stage_graph_conflict", "Diagnostic graph requires its frozen bundle", 1);
+    const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+    const root = readDescriptorRootWork(context, scope, bundle), graph = readRegisteredDiagnosticGraph(context, scope);
+    const members = stageWorkIds(context, project.id, input.runId, input.stage);
+    if (!graph || graph.parent_work_id !== root.workId || graph.bundle_sha256 !== bundle.sha256 || root.status !== "running"
+        || !members.has(root.workId) || members.size !== Object.keys(graph.work_ids).length + 1
+        || Object.values(graph.work_ids).some(id => !members.has(id)))
+        throw new AppError("stage_graph_conflict", "Diagnostic graph requires its exact registered Work; replay the issued Stage entry if registration was interrupted", 1);
+    return { schema_id: "dd-flow/work-fanout@2", kind: "work_fanout", scope: stageGraphScope(context, project.id, input.runId, input.stage),
+        stage: input.stage, parent_work_id: root.workId, dispatch: "none", capacity_required: true };
+}
 /** Read-only projection for an external orchestrator.  dd-flow keeps the graph authority. */
 export function getVnextFanoutStatus(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
@@ -185,7 +214,9 @@ export function getVnextFanoutStatus(context, input) {
     const index = JSON.parse(run.index_json);
     const bundle = index.execution_bundle ? readFlowRunExecutionBundle(context, { projectRoot, runId: input.runId }) : null;
     const stageRoot = path.join(run.run_root, bundle ? bundle.descriptor.stage(input.stage).directory : vnextStageDirectory(input.stage));
-    let descriptor = memoryStageFanoutDescriptor(context, input) ?? readFanoutDescriptor(stageRoot);
+    const memoryDescriptor = memoryStageFanoutDescriptor(context, input);
+    const diagnosticDescriptor = diagnosticStageFanoutDescriptor(context, input);
+    let descriptor = memoryDescriptor ?? diagnosticDescriptor ?? (bundle && isDiagnosticFlow(bundle.manifest.flow_id) ? null : readFanoutDescriptor(stageRoot));
     // Registration is authoritative even if projection publication was interrupted,
     // or an otherwise review-off stage acquired an aggregate repair graph.
     if (!descriptor && context.db.get("SELECT 1 FROM sqlite_master WHERE name = 'repair_intents'")) {
@@ -211,6 +242,17 @@ export function getVnextFanoutStatus(context, input) {
     const ready = { works: all.works.filter(work => work.ready) };
     const counts = Object.fromEntries(["created", "running", "completed", "failed", "cancelled"].map((status) => [status, all.works.filter((work) => work.status === status).length]));
     const hasWork = all.works.length > 0;
+    // Only SQL-owned memory registration can attest a deliberately empty
+    // graph. A mutable fanout.json must never turn missing Work into success.
+    let registeredEmpty = false;
+    if (diagnosticDescriptor && !hasWork) {
+        registeredEmpty = Object.keys(readRegisteredDiagnosticGraph(context, { projectId: project.id, runId: input.runId, stage: input.stage }).work_ids).length === 0;
+    }
+    if (memoryDescriptor && input.stage === "upgrade" && !hasWork
+        && context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.composition_registration' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.stage')='upgrade' AND json_extract(payload_json,'$.scope.attempt')=? AND json_extract(payload_json,'$.scope.cycle')=? AND json_extract(payload_json,'$.scope.parent_work_id')=? LIMIT 1", [project.id, input.runId, currentScope.attempt, currentScope.cycle, descriptor.parent_work_id])) {
+        const registered = selectMemoryCompositionRegistration(context, { ...currentScope, stage: "upgrade", parent_work_id: descriptor.parent_work_id });
+        registeredEmpty = Object.keys(registered.work_ids).length === 0;
+    }
     const capacityKnown = capacity.available_slots !== null;
     return {
         ok: true,
@@ -221,7 +263,7 @@ export function getVnextFanoutStatus(context, input) {
             // PLAN-REVIEW has a deterministic dispatcher. CODE and CODE-REVIEW do
             // not: their coordinator first materializes the Work graph from its
             // authoritative prompt. An empty graph is therefore not a success.
-            state: fanoutState({ dispatch: descriptor.dispatch, hasWork, capacityRequired: descriptor.capacity_required, capacityKnown, created: counts.created ?? 0, running: counts.running ?? 0 }),
+            state: fanoutState({ dispatch: descriptor.dispatch, hasWork, registeredEmpty, capacityRequired: descriptor.capacity_required, capacityKnown, created: counts.created ?? 0, running: counts.running ?? 0 }),
             capacity,
             graph_revision: all.works.map(work => ({ work_id: work.work_id, status: work.status, depends_on: work.depends_on })),
             works: { ...counts, ready: ready.works.map((work) => ({ work_id: work.work_id, task: work.task, launch_policy: work.launch_policy, start_command: work.start_command })) }

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

@@ -217,8 +217,6 @@ export function dispatchVnextPlanReview(context, input) {
     const waves = plannedReviewWaves(groups, capacity.availableSlots);
     return { ok: true, run_id: run.id, stage, capacity: { available_slots: capacity.availableSlots, source: capacity.source }, routing: { group_count: groups.length, planned_waves: waves.length, waves, preference: "Use one wave when semantic compatibility permits; hard dependencies create later waves." }, review_works: reviews, next_action: "launch_ready_reviews" };
 }
-// Capacity is a RUN fact shared by every fan-out stage.
-const reviewCapacityKey = subagentCapacityKey;
 /** Capacity is observed immediately before this stage dispatches reviewers. */
 export function recordVnextPlanReviewCapacity(context, input) {
     if (!Number.isInteger(input.availableSlots) || input.availableSlots < 0 || input.availableSlots > 15) {
@@ -228,15 +226,15 @@ export function recordVnextPlanReviewCapacity(context, input) {
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, projectRoot, input.runId);
     const variables = getFlowRunVariables(context, { projectRoot, runId: run.id });
-    const prior = variables.variables[reviewCapacityKey];
+    const prior = variables.variables[subagentCapacityKey];
     if (typeof prior === "number") {
         if (prior === input.availableSlots)
             return { ok: true, run_id: run.id, capacity: { available_slots: prior, source: "harness_qualification", reused: true } };
-        setRuntimeRunVariable(context, { projectRoot, runId: run.id, key: reviewCapacityKey, value: input.availableSlots });
+        setRuntimeRunVariable(context, { projectRoot, runId: run.id, key: subagentCapacityKey, value: input.availableSlots });
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "subagent_capacity_refreshed", previous_available_slots: prior, available_slots: input.availableSlots, source: "harness_qualification" });
         return { ok: true, run_id: run.id, capacity: { available_slots: input.availableSlots, previous_available_slots: prior, source: "harness_qualification", refreshed: true } };
     }
-    setRuntimeRunVariable(context, { projectRoot, runId: run.id, key: reviewCapacityKey, value: input.availableSlots });
+    setRuntimeRunVariable(context, { projectRoot, runId: run.id, key: subagentCapacityKey, value: input.availableSlots });
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "subagent_capacity_observed", available_slots: input.availableSlots, source: "harness_qualification" });
     return { ok: true, run_id: run.id, capacity: { available_slots: input.availableSlots, source: "harness_qualification" } };
 }