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

package/dist/services/controller-fanout.js

@@ -12,7 +12,8 @@ import { requireProjectByRoot } from "./projects.js";
 import { stageAttempt, stageWorkIds } from "./stage-work-graph.js";
 import { runtimeCommand } from "./runtime-command.js";
 import { promptDeliveryInstruction } from "./prompt-delivery.js";
-function semanticCompletionPrompt(stage, completed) {
+import { currentStageFinishCommand } from "./lifecycle-invocations.js";
+function semanticCompletionPrompt(stage, completed, command) {
     const task = stage === "plan-review"
         ? "Classify the reviewer findings, apply every accepted correction in the current PLAN-REVIEW Work, and write the authoritative review decision."
         : stage === "code-review"
@@ -21,7 +22,7 @@ function semanticCompletionPrompt(stage, completed) {
     return [
         `All declared ${stage} child Work has settled (${completed} completed).`,
         task,
-        "Then invoke the exact Stage finish command from the original authoritative packet.",
+        `Then invoke this exact currently issued Stage finish command:\n\n${command}\n\nRefresh the authoritative verification evidence first; an earlier rejected or successful nonterminal command only reads its retained outcome.`,
         "If that command returns either outcome = repair_required with a repair Work ID, or error.details.continuation.kind = repair_required, the repair Work is already registered. End this Turn so the controller can dispatch it. Otherwise follow the command's actual result.",
         "Do not create speculative repair Work or start a successor Stage."
     ].join(" ");
@@ -37,10 +38,13 @@ export function controllerStageEntryPrompt(stage, command) {
         stageLifecycleInstruction
     ].join("\n\n");
 }
-export function controllerStageResumePrompt(pauseId, command) {
+export function controllerStageResumePrompt(packet, resumedPromptPath) {
     return [
-        `The user supplied the raw answer for pause ${pauseId}. Your first tool call must be this exact standalone command:`,
-        command,
+        `The accepted canonical answer for pause ${packet.pause_id} (${packet.stage}, ${packet.work_id}) is retained at this absolute read-only path: ${JSON.stringify(packet.answer_file)} (sha256 ${packet.answer_sha256}). Do not replace it with a placeholder or ask the user to supply it again. A null pause.answer_path before resume does not mean the answer is missing.`,
+        resumedPromptPath
+            ? `This exact answer was already committed. Do not invoke stage resume again. Read the recovered authoritative continuation at ${JSON.stringify(resumedPromptPath)} and perform its current Stage instructions.`
+            : `Only while this exact pause still awaits its answer, your first tool call must be this exact standalone command. It applies the already accepted bound answer file:\n\n${packet.command}`,
+        ...(packet.resume_source_path ? [`If this pause has already resumed, do not invoke stage resume again. Read the complete recovered result.worker_prompt_markdown in ${JSON.stringify(packet.resume_source_path)} instead, and follow that authoritative continuation. The controller restores this committed packet before dispatch. A different pause requires its own accepted answer.`] : []),
         `Do not alter the answer. ${promptDeliveryInstruction} Follow the returned packet, then stop at this Stage boundary.`,
         stageLifecycleInstruction
     ].join("\n\n");
@@ -205,7 +209,10 @@ export async function nextControllerFanout(context, input) {
             ].join("\n\n"));
         }
     }
-    return prompt("semantic_completion", semanticCompletionPrompt(input.stage, fanout.works.completed));
+    const finish = currentStageFinishCommand(context, input.stage);
+    if (!finish)
+        throw new AppError("controller_finish_authority_missing", "Settled child Work has no current issued Stage finish; reconcile lifecycle authority", 1, { stage: input.stage });
+    return prompt("semantic_completion", semanticCompletionPrompt(input.stage, fanout.works.completed, finish));
 }
 /** Shared pinned runtime normalization; preserve structured errors at the TS boundary. */
 export function controllerNativeChildren(receipt, rootSessionId) {

package/dist/services/controller-memory-worker.js

@@ -6,6 +6,7 @@ import { launchExternalWork } from "./external-work-launch.js";
 import { requireProjectByRoot } from "./projects.js";
 import { assertControllerLeaseAllowed } from "./run-controller-process.js";
 import { assertManagedProcessLease } from "./managed-processes.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
 if (!parentPort)
     throw new AppError("controller_memory_task_invalid", "Memory worker requires its controller thread", 1);
 const port = parentPort, cancellation = new AbortController();
@@ -18,8 +19,8 @@ try {
     context = createContext(env, "prepared_existing");
     const project = requireProjectByRoot(context, task.input.projectRoot);
     const run = context.db.get("SELECT flow_kind FROM runs WHERE project_id=? AND id=?", [project.id, task.input.runId]);
-    if (!run || !["mb-init", "mb-upgrade"].includes(run.flow_kind))
-        throw new AppError("controller_memory_task_invalid", "Memory worker requires the selected memory RUN", 1, { effect: "no_effect" });
+    if (!run || !["mb-init", "mb-upgrade"].includes(run.flow_kind) && !isDiagnosticFlow(run.flow_kind))
+        throw new AppError("controller_memory_task_invalid", "Worker requires the selected memory or diagnostic RUN", 1, { effect: "no_effect" });
     if (task.operation === "external") {
         const work = context.db.get("SELECT project_id,run_id FROM works WHERE work_id=?", [task.input.workId]);
         if (!work || work.project_id !== project.id || work.run_id !== task.input.runId)

package/dist/services/dashboard.js

@@ -216,10 +216,10 @@ export function autoRefreshDashboards(context, input) {
     if (projectRecoveryGuarded(context, project.id))
         return { ok: true, skipped: true, reason: "run_recovery_guarded" };
     const configured = readProjectConfig(context, project.id);
-    // Automatic observation must not change either memory flow's source baseline.
+    // Automatic observation must not change a memory or diagnostic source baseline.
     // Keep projections in Home; do not hide runtime-created paths in Git or
     // weaken source preservation by excluding user-owned .tasks directories.
-    const initializing = context.db.get("SELECT 1 FROM runs WHERE project_id=? AND flow_kind IN ('mb-init','mb-upgrade') AND (id=? OR status IN ('created','running','paused','waiting_for_user','blocked')) LIMIT 1", [project.id, input.runId ?? null]);
+    const initializing = context.db.get("SELECT 1 FROM runs WHERE project_id=? AND flow_kind IN ('mb-init','mb-upgrade','mb-audit','project-review') AND (id=? OR status IN ('created','running','paused','waiting_for_user','blocked')) LIMIT 1", [project.id, input.runId ?? null]);
     const config = initializing ? { ...configured, dashboard: { ...configured.dashboard,
             markdown_path: path.join(projectDashboardDir(context.ddFlowHome, project.id), "project-dashboard.md") } } : configured;
     if (!config.dashboard.auto_refresh) {

package/dist/services/descriptor-run-settlement.js

@@ -62,17 +62,19 @@ export class PreparedDescriptorRunSettlement {
         const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
         const matchKeys = entityReferenceVariants(input.runId).map(reference => stageLifecycleMatchKey("stage_finish", reference, input.stage, input.projectRoot));
         const snapshot = context.db.readSnapshot(() => ({ owner: selected(context, scope, bundle, matchKeys), generation: assertRunMutationAllowed(context, scope.projectId, scope.runId) }));
-        const git = snapshot.owner.prior?.git ?? gitFacts(bundle.execution.snapshot().scope.workspace);
+        const operational = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        const git = snapshot.owner.prior?.git ?? gitFacts(operational.workspace_root ?? operational.project_root);
         return new PreparedDescriptorRunSettlement(scope, bundle, snapshot.owner, git, snapshot.generation, matchKeys);
     }
     apply(context, assertHandlerCustody) {
         if (typeof assertHandlerCustody !== "function")
             refuse("handler_fence_required");
-        const bundle = readFlowRunExecutionBundle(context, { projectRoot: this.#bundle.execution.snapshot().scope.projectRoot, runId: this.#scope.runId });
+        const operational = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#bundle);
+        const bundle = readFlowRunExecutionBundle(context, { projectRoot: operational.project_root, runId: this.#scope.runId });
         if (!bundle || bundle.sha256 !== this.#bundle.sha256)
             refuse("bundle_changed");
         const observed = context.db.readSnapshot(() => selected(context, this.#scope, this.#bundle, this.#matchKeys));
-        if (!observed.prior && hybridDigest(gitFacts(this.#bundle.execution.snapshot().scope.workspace)) !== hybridDigest(this.#git))
+        if (!observed.prior && hybridDigest(gitFacts(operational.workspace_root ?? operational.project_root)) !== hybridDigest(this.#git))
             refuse("git_observation_changed");
         const receipt = { run_id: this.#scope.runId, work_id: this.#owner.rootId, binding: this.#owner.binding, git: this.#git };
         const changed = withStageSettlement(context, () => {

package/dist/services/descriptor-run-start.js

@@ -20,6 +20,8 @@ import { allocateDescriptorRootWork, readDescriptorRootWork } from "./descriptor
 import { nextRunId } from "./ids.js";
 import { readMemoryInitRunAllocation } from "./memory-init-run-allocation.js";
 import { readMemoryUpgradeEvidence, readMemoryUpgradeTargetEvidence, upgradeEvidenceFilePath, upgradeEvidenceIndexPath, upgradeTargetIndexPath } from "./memory-upgrade-evidence.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
 const encode = (value) => Buffer.from(JSON.stringify(value));
 const owner = (directory) => {
     const stat = fs.lstatSync(directory);
@@ -91,6 +93,13 @@ function memoryBootstrap(context, projectId, bundle) {
     if (bundle.descriptor.descriptor.id === "sdlc")
         return;
     const scope = bundle.execution.snapshot().scope;
+    if (isDiagnosticFlow(bundle.manifest.flow_id)) {
+        const snapshot = readDiagnosticSnapshotCustody(context, { projectId, projectRoot: scope.projectRoot,
+            sourceRoot: scope.projectRoot, requestId: scope.requestId, flowId: bundle.manifest.flow_id });
+        if (!snapshot || snapshot.root !== scope.workspace || bundle.manifest.bootstrap_receipts.length !== 0)
+            refuseRunStart("diagnostic_snapshot_authority_changed");
+        return;
+    }
     if (bundle.descriptor.descriptor.id === "mb-init") {
         const retained = readMemoryInitBootstrapReadiness(context, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace });
         const reference = bundle.manifest.bootstrap_receipts[0];
@@ -113,6 +122,16 @@ function memoryBootstrap(context, projectId, bundle) {
         || !bundle.blob(reference.path).equals(encode(retained.authority.receipt)))
         refuseRunStart("memory_bootstrap_authority_changed");
 }
+function observeRunWorkspace(context, bundle, projectId) {
+    const scope = bundle.execution.snapshot().scope;
+    if (!isDiagnosticFlow(bundle.manifest.flow_id))
+        return observeDescriptorWorkspace(context, scope.projectRoot, scope.workspace);
+    const snapshot = readDiagnosticSnapshot(context, { projectId, projectRoot: scope.projectRoot,
+        sourceRoot: scope.projectRoot, requestId: scope.requestId, flowId: bundle.manifest.flow_id });
+    if (!snapshot || snapshot.root !== scope.workspace)
+        refuseRunStart("diagnostic_snapshot_authority_changed");
+    return observeDescriptorWorkspace(context, snapshot.root, snapshot.root);
+}
 /** RUN allocation and SQL bundle authority are one request-owned transaction.
  * Physical publication is separate, replayable and gates lifecycle writes.
  * This does not register missing handlers or qualify a provider/storage route.
@@ -164,11 +183,11 @@ export class PreparedDescriptorRunStart {
         const home = fs.realpathSync(context.ddFlowHome), runRoot = projectRunHome(home, selected.id, bundle.manifest.run_id);
         if (fs.existsSync(runRoot))
             refuseRunStart("foreign_run_root");
-        const facts = observeDescriptorWorkspace(context, scope.projectRoot, scope.workspace), now = context.now(), artifacts = [
+        const facts = observeRunWorkspace(context, bundle, selected.id), now = context.now(), artifacts = [
             { path: "engine-binding.json", base64: bundle.blob(bundle.manifest.engine_binding.path).toString("base64") }
         ];
         const isSdlc = bundle.descriptor.descriptor.id === "sdlc", flowKind = isSdlc ? "vnext_specify" : bundle.descriptor.descriptor.id;
-        if (!["vnext_specify", "mb-init", "mb-upgrade"].includes(flowKind))
+        if (!["vnext_specify", "mb-init", "mb-upgrade"].includes(flowKind) && !isDiagnosticFlow(flowKind))
             refuseRunStart("unsupported_flow_kind");
         if (flowKind === "mb-upgrade") {
             const upgradeScope = { requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace };
@@ -250,7 +269,7 @@ export class PreparedDescriptorRunStart {
     revalidatePhysical(context) {
         this.revalidateDirectoryOwners(context);
         const p = this.#payload;
-        if (hybridDigest(observeDescriptorWorkspace(context, p.project_root, p.workspace_root)) !== hybridDigest(p.git))
+        if (hybridDigest(observeRunWorkspace(context, this.#bundle, p.project_id)) !== hybridDigest(p.git))
             refuseRunStart("physical_scope_changed");
         this.#bundle.engine();
     }

package/dist/services/descriptor-stage-coordinator.js

@@ -8,11 +8,14 @@ import { hybridDigest } from "./hybrid-contracts.js";
 import { readDescriptorRootWork } from "./descriptor-root-work.js";
 import { bindStageWork, stageWorkIds } from "./stage-work-graph.js";
 import { appendAudit } from "./audit.js";
-import { acceptStagePacket, prepareStagePacket, publishStagePacket } from "./stage-report-renderer.js";
+import { acceptStagePacket, prepareStagePacket, publishStagePacket, resolveStagePublicationPath } from "./stage-report-renderer.js";
 import { assertRunMutationAllowed } from "./run-recovery-guard.js";
 import { assertStageSettlementAllowed, PreparedRecoveryCoordinatorRead } from "./run-recovery.js";
 import { loadExternalStageContextBytes, renderExternalStageContext } from "./stage-context.js";
 import { runtimeCommand } from "./runtime-command.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { diagnosticAspects } from "../domain/diagnostic-aspects.js";
+import { readDiagnosticSnapshot } from "./diagnostic-snapshot.js";
 const event = "flow_run.descriptor_coordinator";
 const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
 function refuse(reason) {
@@ -45,7 +48,18 @@ function readDescriptorStageInputCustody(context, scope, bundle, run, settlement
         || typeof stage.attempt !== "string" || typeof stage.input_sha256 !== "string")
         refuse("inactive_stage");
     const file = path.join(run.run_root, declared.directory, "stage-input.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,'$.file')=? LIMIT 2", [scope.projectId, scope.runId, scope.stage, file]);
+    // Imported receipts retain their original locators and exact input bytes.
+    // Match their current publication through trusted RUN lineage, as accepted
+    // result readers do, rather than requiring rewritten historical SQL.
+    const candidates = 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')=? LIMIT 33", [scope.projectId, scope.runId, scope.stage, stage.attempt]);
+    if (candidates.length > 32)
+        refuse("input_custody_missing");
+    const rows = candidates.filter(row => {
+        if (Buffer.byteLength(row.payload_json) > 8 * 1024 * 1024)
+            refuse("input_custody_changed");
+        const candidate = JSON.parse(row.payload_json);
+        return typeof candidate?.file === "string" && resolveStagePublicationPath(context, scope.projectId, scope.runId, candidate.file) === file;
+    });
     if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
         refuse("input_custody_missing");
     const packet = JSON.parse(rows[0].payload_json), content = Buffer.from(packet.base64, "base64");
@@ -58,7 +72,8 @@ function readDescriptorStageInputCustody(context, scope, bundle, run, settlement
         || input.descriptor_sha256 !== bundle.descriptor.sha256 || input.execution_sha256 !== bundle.execution.sha256)
         refuse("foreign_input");
     const starts = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.descriptor_stage_start' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? LIMIT 2", [scope.projectId, scope.runId, scope.stage]);
-    if (starts.length !== 1 || hybridDigest(JSON.parse(starts[0].payload_json)) !== hybridDigest({ schema_id: "dd-flow/descriptor-stage-start@1", run_id: scope.runId, stage: scope.stage, attempt: stage.attempt, bundle_sha256: bundle.sha256, input_sha256: stage.input_sha256, file }))
+    const start = starts.length === 1 ? JSON.parse(starts[0].payload_json) : null;
+    if (!start || typeof start.file !== "string" || hybridDigest({ ...start, file: resolveStagePublicationPath(context, scope.projectId, scope.runId, start.file) }) !== hybridDigest({ schema_id: "dd-flow/descriptor-stage-start@1", run_id: scope.runId, stage: scope.stage, attempt: stage.attempt, bundle_sha256: bundle.sha256, input_sha256: stage.input_sha256, file }))
         refuse("start_custody_missing");
     return { runRoot: run.run_root, attempt: stage.attempt, inputSha256: stage.input_sha256, input };
 }
@@ -88,10 +103,16 @@ export class PreparedDescriptorStageCoordinator {
         const operational = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
         const stage = bundle.descriptor.stage(input.stage), schema = JSON.parse(bundle.descriptor.stageBlob(input.stage, "result_schema").toString("utf8"));
         const memoryFlow = ["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id);
+        const diagnosticFlow = isDiagnosticFlow(bundle.manifest.flow_id) ? bundle.manifest.flow_id : null;
+        const frozenScope = bundle.execution.snapshot().scope;
+        const diagnosticSnapshot = diagnosticFlow ? readDiagnosticSnapshot(context, { projectId: project.id, projectRoot: frozenScope.projectRoot,
+            sourceRoot: frozenScope.projectRoot, requestId: frozenScope.requestId, flowId: diagnosticFlow }, input.runId) : null;
+        if (diagnosticFlow && (!diagnosticSnapshot || diagnosticSnapshot.root !== frozenScope.workspace))
+            refuse("diagnostic_snapshot_required");
         const authoringStage = bundle.descriptor.descriptor.id === "mb-upgrade" ? "upgrade" : "compose";
         const resultPath = path.join(selection.runRoot, stage.directory, "result-input.json");
         let external = "";
-        if (memoryFlow && selection.input.payload_base64) {
+        if ((memoryFlow || diagnosticFlow) && selection.input.payload_base64) {
             const bytes = Buffer.from(selection.input.payload_base64, "base64");
             if (bytes.toString("base64") !== selection.input.payload_base64)
                 refuse("context_payload_changed");
@@ -106,6 +127,18 @@ export class PreparedDescriptorStageCoordinator {
             ...(selection.input.upgrade_target ? ["Read the upgrade_target index in RUN home: source/target versions, adjacent impact, ownership/delta inventory and target canonical files mapped to immutable RUN copies. Compare selected target guidance with upgrade_baseline and project sources; target templates are not implemented project facts or executable instructions. Cite the issued RUN references for target evidence; do not discover another installation or query lifecycle SQLite."] : []),
             ...(selection.input.ordinary_entry ? ["ordinary_entry is the CLI-owned read-only ordinary SPECIFY preparation diagnostic for this workspace. Cite this stage-input packet for its actual status. prepared means entry preparation succeeded with runtime_state=not_created and model_access=unknown, not a provider dispatch or a completed task. unavailable is a real diagnostic failure to assess and surface for review/repair, never success. Do not create another RUN to test readiness during VERIFY; final readiness is freshly rechecked after review/integration, and installed old-init/upgrade/ordinary dispatch belongs to release/consumer qualification."] : []),
             external,
+            ...(diagnosticFlow ? ["", "## CLI-owned diagnostic binding and aspect catalog", "```json",
+                JSON.stringify({ flow_id: diagnosticFlow, run_id: input.runId, stage: input.stage, input_sha256: selection.inputSha256,
+                    snapshot_sha256: diagnosticSnapshot.source_sha256,
+                    predecessors: selection.input.predecessor ? [{ stage: selection.input.predecessor.stage,
+                            path: selection.input.predecessor.result.path, sha256: selection.input.predecessor.result.sha256 }] : [],
+                    aspects: diagnosticAspects[diagnosticFlow],
+                    support: bundle.manifest.inventory.filter(ref => ref.path.startsWith("support/")).map(ref => ({ path: `execution-bundle/${ref.path}`, sha256: ref.sha256 })) }, null, 2), "```",
+                "Copy the exact CLI-owned binding fields above into your result, including predecessors. This list contains only the immediate predecessor, or is empty for preflight; do not append transitive stage history.",
+                "Read the applicable support criteria relative to RUN home. Legacy task/subagent snippets in those reference files do not authorize manual lifecycle, repair or dispatch. Project facts must come from the assigned snapshot, not the canon criteria.",
+                "Every source/evidence path in the result is relative to the assigned snapshot workspace root, with forward slashes: src/index.ts or .memory-bank/index.md, never an absolute filesystem path. Hash the exact snapshot file bytes. Intake transport files, this RUN's packets and canonical support references are not snapshot sources: use the frozen input to interpret the request, but do not insert them into sources or evidence. Do not fabricate a snapshot-relative spelling for a file outside the snapshot.",
+                "Files under .dd-flow/review-evidence are CLI-generated observations, not original project sources: do not put them in sources/evidence or infer the original repository's history or unborn state from the working copy's Git metadata. For missing linked targets cite the existing referring project document and describe the absence as a limitation, not as a source file.",
+                "Every baseline aspect needs an explicit applicability row. The runtime registers applicable analytical Work and independent critics from the accepted predecessor; do not allocate or dispatch your own Work. Do not edit either the original project or snapshot. Read completed assigned Work results before proposing analysis/review. Keep all candidates, rejected findings, critic disagreement and limitations; a completed diagnostic is not a claim that the project is clean."] : []),
             ...(selection.input.ordinary_defaults ? ["", "## Ordinary SDLC technical defaults", "Use ordinary_defaults.proposals from the frozen input verbatim as project-owned JSON. Assign each missing configuration to an applicable unit with its exact workspace write scope and reviewed output artifact. Preserve valid existing configs. These defaults do not authorize future work, push, deletion or standing project policy. Do not invent a bootstrap command. If ordinary_defaults.missing is nonempty, resolve that actual choice through the existing stage pause/answer path before composing; do not guess."] : []),
             ...(memoryFlow ? ["", "## Request support reference", "```json",
                 JSON.stringify({ root: "run", path: `${stage.directory}/stage-input.json`, sha256: selection.inputSha256 }), "```",

package/dist/services/descriptor-stage-settlement.js

@@ -174,7 +174,8 @@ export class PreparedDescriptorStageSettlement {
      * It keeps bootstrap/check/reviewer custody in the same acceptance writer.
      */
     apply(context, assertHandlerCustody) {
-        const current = readFlowRunExecutionBundle(context, { projectRoot: this.#bundle.execution.snapshot().scope.projectRoot, runId: this.#scope.runId });
+        const operational = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#bundle);
+        const current = readFlowRunExecutionBundle(context, { projectRoot: operational.project_root, runId: this.#scope.runId });
         if (!current || current.sha256 !== this.#bundle.sha256)
             refuse("bundle_changed");
         const receipt = { run_id: this.#scope.runId, stage: this.#scope.stage, work_id: this.#owner.workId, work_session_id: this.#owner.workSessionId, binding: this.binding() };

package/dist/services/diagnostic-evidence.js

@@ -0,0 +1,73 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+const refuse = (reason, details = {}) => {
+    const correctable = ["invalid_source_reference", "source_hash_changed", "source_missing"].includes(reason);
+    const message = reason === "source_hash_changed"
+        ? "Citation sha256 does not match its assigned snapshot file; correct the result using source_path and actual_source_sha256, then retry. No result was accepted."
+        : reason === "source_missing" ? "Citation is absent from the original project snapshot. Cite an existing project source instead; generated .dd-flow/review-evidence observations are not project sources. For a missing link target cite the existing referring document and record the absence as a limitation. Correct the result, then retry; no result was accepted."
+            : correctable ? "Use snapshot-relative evidence paths with forward slashes (for example src/index.ts), without absolute paths, dot segments or .git; sha256 must be 64 lowercase hex characters"
+                : "Diagnostic evidence does not match the assigned snapshot and coverage";
+    throw new AppError("diagnostic_evidence_invalid", message, 2, { ...details, reason, effect: "no_effect", ...(correctable ? { phase: "prepare", recoverable: true } : {}) });
+};
+/** Run after schema validation; schema-shaped hashes are not evidence by themselves. */
+export function verifyDiagnosticSources(root, sources) {
+    const canonicalRoot = fs.realpathSync(root), seen = new Map();
+    for (const source of sources) {
+        if (!source.path || source.path.length > 4096 || source.path.includes("\\") || path.posix.isAbsolute(source.path) || path.win32.isAbsolute(source.path)
+            || source.path.split("/").some(part => !part || part === "." || part === ".." || part === ".git")
+            || !/^[a-f0-9]{64}$/.test(source.sha256))
+            refuse("invalid_source_reference");
+        if (seen.has(source.path) && seen.get(source.path) !== source.sha256)
+            refuse("conflicting_source_reference");
+        seen.set(source.path, source.sha256);
+        let bytes;
+        try {
+            const file = fs.realpathSync(path.join(canonicalRoot, source.path)), relative = path.relative(canonicalRoot, file);
+            if (relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative))
+                refuse("escaping_source_reference");
+            const stat = fs.statSync(file);
+            if (!stat.isFile() || stat.size > 16 * 1024 * 1024)
+                refuse("unbounded_source_reference");
+            bytes = fs.readFileSync(file);
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            if (["ENOENT", "ENOTDIR"].includes(error.code ?? "")) {
+                return refuse("source_missing", { source_path: source.path });
+            }
+            return refuse("source_unavailable");
+        }
+        const actual = createHash("sha256").update(bytes).digest("hex");
+        if (actual !== source.sha256)
+            refuse("source_hash_changed", {
+                source_path: source.path, provided_source_sha256: source.sha256, actual_source_sha256: actual
+            });
+    }
+}
+export function verifyDiagnosticCoverage(root, baseline, coverage) {
+    const ids = coverage.map(value => value.id);
+    if (new Set(ids).size !== ids.length || ids.length !== baseline.length || baseline.some(id => !ids.includes(id)))
+        refuse("incomplete_aspect_coverage");
+    for (const value of coverage) {
+        if (!value.reason.trim())
+            refuse("missing_applicability_reason");
+        verifyDiagnosticSources(root, value.evidence);
+    }
+}
+/** Each independent critic must account for every candidate, including rejected findings. */
+export function verifyDiagnosticCritic(root, candidates, decisions) {
+    const ids = candidates.map(value => value.id), reviewed = decisions.map(value => value.finding_id);
+    if (new Set(ids).size !== ids.length || new Set(reviewed).size !== reviewed.length
+        || ids.length !== reviewed.length || ids.some(id => !reviewed.includes(id)))
+        refuse("incomplete_critic_coverage");
+    for (const candidate of candidates) {
+        if (!candidate.evidence.length)
+            refuse("finding_without_evidence");
+        verifyDiagnosticSources(root, candidate.evidence);
+    }
+    for (const decision of decisions)
+        verifyDiagnosticSources(root, decision.evidence);
+}

package/dist/services/diagnostic-report-publication.js

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { prepareStagePacket, acceptStagePacket } from "./stage-report-renderer.js";
+import { publishImmutableInput } from "../storage/immutable-input.js";
+import { renderDiagnosticReport } from "./diagnostic-report.js";
+function refuse(reason) { throw new AppError("diagnostic_report_publication_invalid", "Diagnostic report publication requires its owned stage and exact bytes", 2, { reason, effect: "no_effect" }); }
+/** Files are immutable candidates until retain is called in the Stage acceptance
+ * writer. Interrupted publication can replay before any terminal acceptance. */
+export function prepareDiagnosticReportPublication(context, scope, report) {
+    const run = context.db.get("SELECT run_root,index_json FROM runs WHERE project_id=? AND id=?", [scope.projectId, scope.runId]);
+    const stage = run ? JSON.parse(run.index_json).stage_runs.find((value) => value.stage === scope.stage) : null;
+    if (!run?.run_root || scope.stage !== "report" || stage?.attempt !== scope.attempt || stage.input_sha256 !== scope.inputSha256
+        || report.run.id !== scope.runId || !["running", "done"].includes(stage.status))
+        refuse("foreign_stage");
+    const directory = path.join(run.run_root, stage.dir);
+    if (fs.realpathSync(run.run_root) !== run.run_root || fs.realpathSync(directory) !== directory
+        || !directory.startsWith(run.run_root + path.sep))
+        refuse("unsafe_report_directory");
+    const rendered = renderDiagnosticReport(report);
+    const packets = Object.entries(rendered).map(([kind, bytes]) => {
+        if (bytes.length > 4 * 1024 * 1024)
+            refuse("report_exceeds_bound");
+        const suffix = kind === "markdown" ? "md" : kind;
+        const file = path.join(directory, `diagnostic-report.${suffix}`);
+        try {
+            if (!fs.lstatSync(file).isFile() || fs.lstatSync(file).isSymbolicLink())
+                refuse("unsafe_report_file");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        return prepareStagePacket(file, bytes);
+    });
+    const manifest = { schema_id: "dd-flow/diagnostic-report-publication@1", run_id: scope.runId, stage: scope.stage, attempt: scope.attempt,
+        input_sha256: scope.inputSha256, artifacts: packets.map(packet => ({ path: path.relative(run.run_root, packet.file).split(path.sep).join("/"), sha256: packet.sha256 })) };
+    const retained = (writer) => writer.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='diagnostic.report' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.attempt')=? LIMIT 2", [scope.projectId, scope.runId, scope.attempt]);
+    return {
+        manifest,
+        publish() {
+            if (fs.realpathSync(directory) !== directory)
+                refuse("report_directory_changed");
+            for (const packet of packets)
+                publishImmutableInput(packet.file, packet.bytes, "diagnostic_report_conflict");
+        },
+        /** SQL-only. The existing packet ledger retains recoverable authoritative
+         * bytes in the same transaction as Stage completion. */
+        retain(writer) {
+            const rows = retained(writer);
+            if (rows.length) {
+                if (rows.length !== 1 || hybridDigest(JSON.parse(rows[0].payload_json)) !== hybridDigest(manifest))
+                    refuse("report_custody_changed");
+                for (const packet of packets) {
+                    const records = writer.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')=? LIMIT 2", [scope.projectId, scope.runId, scope.stage, scope.attempt, packet.file]);
+                    if (records.length !== 1 || Buffer.byteLength(records[0].payload_json) > 6 * 1024 * 1024
+                        || hybridDigest(JSON.parse(records[0].payload_json)) !== hybridDigest({ run_id: scope.runId, stage: scope.stage,
+                            attempt: scope.attempt, file: packet.file, sha256: packet.sha256, base64: packet.bytes.toString("base64") }))
+                        refuse("report_packet_custody_changed");
+                }
+                return;
+            }
+            if (stage.status !== "running")
+                refuse("report_receipt_missing");
+            for (const packet of packets)
+                acceptStagePacket(writer, { ...scope, prepared: packet });
+            appendAudit(writer, { projectId: scope.projectId, eventType: "diagnostic.report", payload: manifest });
+        }
+    };
+}

package/dist/services/diagnostic-report.js

@@ -0,0 +1,67 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { collectDiagnosticCandidates } from "./diagnostic-work-results.js";
+function refuse(reason) { throw new AppError("diagnostic_report_invalid", "Diagnostic report requires the reviewed candidate and critic registers", 2, { reason, effect: "no_effect" }); }
+/** Projection only. The handler separately owns source checks, physical critic
+ * independence, SQL custody, publication and terminal RUN settlement. */
+export function prepareDiagnosticReport(result, analysis, critics) {
+    if (result.stage !== "report" || !critics.length
+        || [...analysis, ...critics].some(work => work.workId !== work.result.work_id || work.result.run_id !== result.run_id || work.result.flow_id !== result.flow_id))
+        refuse("foreign_work");
+    const candidates = collectDiagnosticCandidates(analysis);
+    if (hybridDigest(candidates.findings) !== hybridDigest(result.details.findings))
+        refuse("candidate_register_changed");
+    for (const critic of critics) {
+        const ids = critic.result.decisions.map(value => value.finding_id);
+        if (critic.result.stage !== "review" || critic.result.findings.length || new Set(ids).size !== ids.length
+            || ids.length !== candidates.findings.length || candidates.findings.some(value => !ids.includes(value.id)))
+            refuse("incomplete_critic");
+    }
+    const decisions = new Map(result.details.decisions.map(value => [value.finding_id, value]));
+    if (decisions.size !== candidates.findings.length || result.details.decisions.length !== decisions.size
+        || candidates.findings.some(value => !decisions.has(value.id)))
+        refuse("incomplete_resolution");
+    const findings = candidates.findings.map((finding, index) => ({ ...finding, origin: candidates.origins[index],
+        resolution: decisions.get(finding.id),
+        critic_decisions: critics.map(work => ({ work_id: work.workId, decision: work.result.decisions.find(value => value.finding_id === finding.id) })) }));
+    const incomplete = result.details.coverage.some(value => value.applicability === "blocked" || value.applicability === "out_of_scope")
+        || result.details.missing_expected_sources.length > 0 || result.details.limitations.length > 0;
+    const accepted = findings.filter(value => !["rejected", "duplicate"].includes(value.resolution.disposition));
+    const sourceMap = new Map();
+    for (const source of [...result.details.sources, ...result.details.coverage.flatMap(value => value.evidence),
+        ...analysis.flatMap(value => value.result.sources), ...critics.flatMap(value => value.result.sources),
+        ...findings.flatMap(value => [...value.evidence, ...value.resolution.evidence, ...value.critic_decisions.flatMap(critic => critic.decision.evidence)])]) {
+        if (sourceMap.has(source.path) && sourceMap.get(source.path).sha256 !== source.sha256)
+            refuse("conflicting_source_versions");
+        sourceMap.set(source.path, structuredClone(source));
+    }
+    return {
+        schema_id: "dd-flow/diagnostic-report@1",
+        run: { id: result.run_id, flow_id: result.flow_id, snapshot_sha256: result.snapshot_sha256 },
+        summary: result.summary, review_focus: structuredClone(result.details.focus), source_map: [...sourceMap.values()],
+        aspect_coverage: structuredClone(result.details.coverage),
+        critic_pass: critics.map(work => ({ work_id: work.workId, role: work.result.aspect_id, summary: work.result.summary,
+            semantic_sha256: hybridDigest(work.result), decisions: structuredClone(work.result.decisions), limitations: [...work.result.limitations] })),
+        findings_register: findings,
+        conformance_summary: { assessment: incomplete ? "incomplete" : accepted.length ? "findings" : "no_accepted_findings_in_selected_scope",
+            accepted_findings: accepted.length, rejected_or_duplicate_findings: findings.length - accepted.length,
+            applicable_aspects: result.details.coverage.filter(value => value.applicability === "applicable").length,
+            blocked_aspects: result.details.coverage.filter(value => value.applicability === "blocked").length,
+            missing_expected_sources: [...result.details.missing_expected_sources] },
+        review_fix_recommendation: { authorization: "not_granted", candidate_ids: findings.filter(value => value.resolution.disposition === "review_fix_candidate").map(value => value.id) },
+        deferrals: { authorization: "not_granted", candidate_ids: findings.filter(value => value.resolution.disposition === "def_candidate").map(value => value.id),
+            observed_sources: [...sourceMap.values()].filter(value => /(?:^|\/)DEF(?:-MBU)?-[^/]+/.test(value.path)) },
+        limitations: [...result.details.limitations],
+        dashboard_links: critics.map(work => ({ work_id: work.workId, result: `run://${result.run_id}/works/${work.workId}/result.json` }))
+    };
+}
+/** HTML embeds exactly the authoritative JSON value; untrusted prose is text,
+ * never HTML or executable script. Markdown remains a compact companion. */
+export function renderDiagnosticReport(report) {
+    const json = Buffer.from(JSON.stringify(report, null, 2) + "\n");
+    const escape = (text) => text.replace(/[&<>"']/g, value => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[value]);
+    const embedded = json.toString("utf8").replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
+    const markdown = Buffer.from(`# ${report.run.flow_id} · ${report.run.id}\n\n${report.summary}\n\nAssessment: ${report.conformance_summary.assessment}\n\n${report.findings_register.length} findings retained; ${report.critic_pass.length} independent critic passes.\n\nAuthoritative data: diagnostic-report.json\n`);
+    const html = Buffer.from(`<!doctype html><html lang="en"><meta charset="utf-8"><title>${escape(report.run.flow_id)} · ${escape(report.run.id)}</title><body><h1>${escape(report.review_focus.title)}</h1><p>${escape(report.summary)}</p><p>${escape(report.conformance_summary.assessment)}</p><h2>Coverage</h2><ul>${report.aspect_coverage.map(value => `<li>${escape(value.id)}: ${escape(value.applicability)} — ${escape(value.reason)}</li>`).join("")}</ul><h2>Findings</h2><pre>${escape(JSON.stringify(report.findings_register, null, 2))}</pre><script id="diagnostic-report-data" type="application/json">${embedded}</script></body></html>\n`);
+    return { json, markdown, html };
+}

package/dist/services/diagnostic-run-bundle.js

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { PreparedInstalledFlowSource } from "./installed-flow-source.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { readDiagnosticSnapshot } from "./diagnostic-snapshot.js";
+import { requireProjectByRoot } from "./projects.js";
+import { nextDescriptorRunId } from "./descriptor-run-start.js";
+import { bundledHandlerContext } from "./stage-handlers.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const bytes = (value) => Buffer.from(JSON.stringify(value));
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+function refuse(reason) { throw new AppError("diagnostic_run_bundle_invalid", "Diagnostic bundle requires its frozen source, execution and snapshot", 2, { reason, effect: "no_effect" }); }
+/** Initial construction only. Retry after allocation restores the retained RUN
+ * bundle, never current operator settings/canon. boundAt belongs to the request. */
+export function prepareDiagnosticRunBundle(context, input) {
+    if (!(input.source instanceof PreparedInstalledFlowSource) || !(input.execution instanceof FrozenGenericExecution)
+        || !(input.engine instanceof AdmittedFrozenEngine) || !Number.isFinite(Date.parse(input.boundAt)))
+        refuse("unprepared_selection");
+    const frozen = input.execution.snapshot(), flowId = frozen.settings.flow_id;
+    if (!isDiagnosticFlow(flowId))
+        refuse("diagnostic_flow_required");
+    const project = requireProjectByRoot(context, frozen.scope.projectRoot);
+    const snapshot = readDiagnosticSnapshot(context, { projectId: project.id, projectRoot: frozen.scope.projectRoot,
+        sourceRoot: frozen.scope.projectRoot, requestId: frozen.scope.requestId, flowId });
+    if (!snapshot || snapshot.root !== frozen.scope.workspace)
+        refuse("snapshot_selection_changed");
+    input.source.revalidate();
+    const flow = input.source.resolveRegisteredFlow();
+    if (flow.descriptor.id !== flowId || flow.sha256 !== frozen.settings.descriptor_sha256)
+        refuse("flow_selection_changed");
+    input.engine.admitDiagnosticFlow(input.source, flowId);
+    const manifest = input.engine.manifest(), checksum = manifest.integrity.checksum;
+    if (typeof checksum !== "string")
+        refuse("engine_identity_missing");
+    const runId = nextDescriptorRunId(context, { projectRoot: frozen.scope.projectRoot, requestId: frozen.scope.requestId, slug: flowId });
+    const binding = { schema_id: "dd-flow/run-engine-binding@1", run_id: runId,
+        project_root: frozen.scope.projectRoot, bound_at: input.boundAt, source: "run_creation", reason: "Request-bound read-only diagnostic",
+        engine: { package_name: manifest.package_name, package_version: manifest.package_version, engine_version: manifest.engine_version,
+            integrity_checksum: checksum, snapshot_root: manifest.snapshot_root }, probe: { status: "not_required", command: null } };
+    const blobs = input.source.blobs();
+    const put = (logical, content) => {
+        if (blobs.has(logical))
+            refuse("bundle_path_collision");
+        blobs.set(logical, content);
+        return { path: logical, sha256: hash(content) };
+    };
+    for (const ref of [frozen.settings.attached_session_receipt, frozen.settings.delegation.native_capacity_receipt]) {
+        if (!ref)
+            continue;
+        const content = input.receiptBytes?.get(ref.sha256);
+        if (!content || hash(content) !== ref.sha256 || !input.receipts?.has(ref.sha256))
+            refuse("execution_receipt_missing");
+        put(ref.path, Buffer.from(content));
+    }
+    const profiles = { schema_id: "dd-flow/profile-settings@1", profiles: frozen.profiles, aliases: {}, default_profile: null };
+    const profile = put("runtime/profiles.json", bytes({ ...profiles, revision: hybridDigest(profiles) }));
+    const execution = put("runtime/execution.json", bytes(frozen.settings));
+    const engineBinding = put("runtime/engine-binding.json", bytes(binding));
+    const engineManifest = put("runtime/engine-manifest.json", input.engine.manifestBytes());
+    put("runtime/diagnostic-snapshot.json", bytes(snapshot));
+    const provenance = { canon: input.source.canonProvenance(), project_pack: null };
+    const bundle = { schema_id: "dd-flow/execution-bundle@1", run_id: runId, flow_id: flowId,
+        descriptor: input.source.descriptorReference(), execution_settings: execution, profile_settings: profile,
+        engine_binding: engineBinding, engine_manifest: engineManifest, bootstrap_receipts: [], ...provenance,
+        inventory: [...blobs].map(([logical, content]) => ({ path: logical, sha256: hash(content) })) };
+    const encoded = bytes(bundle);
+    return RetainedExecutionBundle.admit(encoded, hash(encoded), blobs, { runId, executionScope: frozen.scope,
+        bundleProjectRoot: frozen.scope.projectRoot, descriptorSha256: flow.sha256, engineChecksum: checksum,
+        engineBindingSha256: engineBinding.sha256, engineManifestSha256: engineManifest.sha256,
+        descriptorContext: bundledHandlerContext(new Map()), bundleProvenance: provenance, receipts: input.receipts ?? new Map() });
+}