@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/diagnostic-report.js

@@ -0,0 +1,97 @@
+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` }))
+    };
+}
+/** Pure repair-intake selection, not acceptance or mutation authority. The
+ * caller must obtain report bytes from the completed RUN's committed custody,
+ * then separately bind the user's approved write scope. Never infer selection
+ * from severity, recommendations or a non-empty findings register. */
+export function selectDiagnosticFindings(report, findingIds) {
+    const invalid = (reason) => {
+        throw new AppError("repair_selection_invalid", "Select exact reviewed finding IDs before preparing repair scope", 2, { reason, effect: "no_effect" });
+    };
+    if (!Array.isArray(findingIds) || !findingIds.length || findingIds.length > 4096
+        || findingIds.some(id => typeof id !== "string" || !id.trim()) || new Set(findingIds).size !== findingIds.length)
+        invalid("explicit_unique_selection_required");
+    const register = new Map(report.findings_register.map(finding => [finding.id, finding]));
+    if (register.size !== report.findings_register.length)
+        invalid("ambiguous_finding_register");
+    const selected = findingIds.map(id => {
+        const finding = register.get(id);
+        if (!finding)
+            return invalid("unknown_finding");
+        if (!["accepted", "downgraded", "def_candidate", "review_fix_candidate"].includes(finding.resolution.disposition))
+            invalid("finding_not_accepted");
+        return structuredClone(finding);
+    });
+    return {
+        source: { ...structuredClone(report.run), report_sha256: hybridDigest(report) },
+        selected_findings: selected,
+        unselected_ids: report.findings_register.filter(finding => !findingIds.includes(finding.id)).map(finding => finding.id),
+        limitations: [...report.limitations],
+        authorization: "not_granted"
+    };
+}
+/** 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,113 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
+import { isDeliveryFlow } from "../domain/delivery-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";
+import { readDiagnosticRequest } from "./diagnostic-start.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) {
+    return prepareRequestRunBundle(context, input, "source_snapshot");
+}
+/** Delivery shares immutable request/engine/profile retention, not diagnosis's
+ * read-only cloned workspace or its permission model. No effect is admitted. */
+export function prepareDeliveryRunBundle(context, input) {
+    return prepareRequestRunBundle(context, input, "delivery");
+}
+function prepareRequestRunBundle(context, input, mode) {
+    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 (mode === "delivery" ? !isDeliveryFlow(flowId) : !isSourceSnapshotFlow(flowId))
+        refuse("registered_request_flow_required");
+    if (mode === "delivery" && frozen.settings.stage_session_mode === "same_session")
+        refuse("independent_delivery_verifier_session_required");
+    if (flowId === "review-fix" && frozen.settings.stage_session_mode === "same_session")
+        refuse("independent_scope_review_session_required");
+    if ((mode === "delivery" || flowId === "mb-distill" || flowId === "review-fix") && (typeof input.requestText !== "string" || !input.requestText.trim()
+        || Buffer.byteLength(input.requestText) > 64 * 1024))
+        refuse(mode === "delivery" ? "original_delivery_request_required" : flowId === "mb-distill" ? "original_distill_request_required" : "original_review_fix_request_required");
+    const request = flowId === "review-fix" ? readDiagnosticRequest(context, { projectRoot: frozen.scope.projectRoot,
+        requestId: frozen.scope.requestId, flowId }) : null;
+    if (flowId === "review-fix" && (!request?.repair_source || request.created_at !== input.boundAt
+        || request.objective !== input.requestText || request.source_sha256 !== input.source.sha256
+        || request.execution_sha256 !== input.execution.sha256))
+        refuse("original_repair_request_required");
+    const project = requireProjectByRoot(context, frozen.scope.projectRoot);
+    const snapshot = isSourceSnapshotFlow(flowId) ? readDiagnosticSnapshot(context, { projectId: project.id, projectRoot: frozen.scope.projectRoot,
+        sourceRoot: frozen.scope.projectRoot, requestId: frozen.scope.requestId, flowId }) : null;
+    if (mode === "source_snapshot" && (!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");
+    if (isDeliveryFlow(flowId))
+        input.engine.admitDeliveryFlow(input.source, flowId);
+    else if (flowId === "review-fix")
+        input.engine.admitReviewFixFlow(input.source);
+    else if (flowId === "mb-distill")
+        input.engine.admitDistillFlow(input.source);
+    else if (flowId === "mb-audit" || flowId === "project-review")
+        input.engine.admitDiagnosticFlow(input.source, flowId);
+    else
+        refuse("registered_request_flow_required");
+    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: isDeliveryFlow(flowId) ? "Request-bound delivery; startup grants no productive mutation approval" : flowId === "review-fix" ? "Request-bound selected finding scope and explicit formalization handoff" : flowId === "mb-distill" ? "Request-bound practice distillation with separate destination authority" : "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) };
+    };
+    // Use the retained request verbatim, not the coordinator's interpretation or
+    // a later mutable intake file. It is task data, never implicit write scope.
+    if (mode === "delivery" || flowId === "mb-distill" || flowId === "review-fix")
+        put("runtime/source-request.md", Buffer.from(input.requestText));
+    if (request?.repair_source)
+        put(request.repair_source.path, Buffer.from(request.repair_source.base64, "base64"));
+    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());
+    if (snapshot)
+        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() });
+}

package/dist/services/diagnostic-snapshot.js

@@ -0,0 +1,159 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { reviewSourceHash, reviewSourceFilter, reviewExecutionCopyHash } from "./review-copy.js";
+import { projectPacketLocators, runContextRelocations } from "./stage-context.js";
+const intentEvent = "diagnostic.snapshot_intent", readyEvent = "diagnostic.snapshot_ready";
+function refuse(reason) { throw new AppError("diagnostic_snapshot_invalid", "Read-only diagnosis requires its retained unchanged snapshot", 1, { reason, effect: "no_effect" }); }
+const inside = (root, file) => { const relative = path.relative(root, file); return relative === "" || !relative.startsWith(".." + path.sep) && relative !== ".." && !path.isAbsolute(relative); };
+function rows(context, input, event) {
+    return context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.requestId')=? LIMIT 2", [input.projectId, event, input.requestId]);
+}
+function destination(context, input) {
+    return path.join(context.ddFlowHome, "diagnostic-snapshots", hybridDigest(input), "workspace");
+}
+/** Deterministic destination for freezing execution before the first copy. */
+export function diagnosticSnapshotRoot(context, input) {
+    validate(context, input);
+    return destination(context, input);
+}
+function physicalSnapshot(context, value, runId) {
+    return runId ? JSON.parse(projectPacketLocators(JSON.stringify(value), runContextRelocations(context, value.projectId, runId))) : value;
+}
+/** Only physical locators are projected through existing RUN import receipts.
+ * The immutable source selection and SQL custody remain byte-for-byte original. */
+export function diagnosticSnapshotPaths(context, value, runId) {
+    const physical = physicalSnapshot(context, value, runId);
+    return { root: physical.root, sourceRoot: physical.sourceRoot };
+}
+function validate(context, input, runId) {
+    const physical = physicalSnapshot(context, input, runId);
+    if (!isSourceSnapshotFlow(input.flowId) || !input.requestId?.trim() || input.requestId.length > 200
+        || !path.isAbsolute(physical.projectRoot) || physical.projectRoot !== physical.sourceRoot
+        || fs.realpathSync(physical.sourceRoot) !== physical.sourceRoot)
+        refuse("invalid_selection");
+    const project = context.db.get("SELECT root,status FROM projects WHERE id=?", [input.projectId]);
+    if (project?.root !== physical.projectRoot || project.status !== "active")
+        refuse("project_not_active");
+    if (inside(physical.sourceRoot, context.ddFlowHome))
+        refuse("runtime_inside_source");
+}
+function retained(context, input, runId) {
+    const records = rows(context, input, intentEvent);
+    if (records.length > 1)
+        refuse("ambiguous_snapshot");
+    if (!records.length)
+        return null;
+    if (Buffer.byteLength(records[0].payload_json) > 16 * 1024)
+        refuse("unbounded_snapshot");
+    const value = JSON.parse(records[0].payload_json);
+    if (value.schema_id !== "dd-flow/diagnostic-snapshot@1" || physicalSnapshot(context, value, runId).root !== destination(context, input)
+        || hybridDigest({ ...value, ...input }) !== hybridDigest(value) || !/^[a-f0-9]{64}$/.test(value.source_sha256))
+        refuse("snapshot_selection_changed");
+    return value;
+}
+function verifyFiles(value, requirePrivateGit = true) {
+    if (!fs.lstatSync(value.root).isDirectory() || fs.realpathSync(value.root) !== value.root
+        || reviewSourceHash(value.sourceRoot) !== value.source_sha256
+        || reviewExecutionCopyHash(value.root, value.sourceRoot, false) !== value.source_sha256)
+        refuse("source_or_copy_changed");
+    if (requirePrivateGit && !fs.lstatSync(path.join(value.root, ".git")).isDirectory())
+        refuse("private_git_required");
+}
+function seal(context, input, value) {
+    context.db.writeTransaction(() => {
+        if (hybridDigest(retained(context, input)) !== hybridDigest(value))
+            refuse("snapshot_custody_changed");
+        const ready = rows(context, input, readyEvent);
+        if (ready.length > 1 || ready.length === 1 && hybridDigest(JSON.parse(ready[0].payload_json)) !== hybridDigest(value))
+            refuse("snapshot_custody_changed");
+        if (!ready.length)
+            appendAudit(context, { projectId: input.projectId, eventType: readyEvent, payload: { ...value } });
+    });
+}
+/** SQL-owned selection plus freshly checked physical source/copy; never adopts a caller's claimed path. */
+export function readDiagnosticSnapshot(context, input, runId) {
+    validate(context, input, runId);
+    const value = readDiagnosticSnapshotCustody(context, input, runId);
+    if (!value)
+        return null;
+    verifyFiles(physicalSnapshot(context, value, runId));
+    return value;
+}
+/** SQL-only custody check for an already physically validated selection.
+ * Callers must perform readDiagnosticSnapshot before entering a writer. */
+export function readDiagnosticSnapshotCustody(context, input, runId) {
+    const value = retained(context, input, runId);
+    if (!value)
+        return null;
+    const ready = rows(context, input, readyEvent);
+    if (ready.length !== 1 || hybridDigest(JSON.parse(ready[0].payload_json)) !== hybridDigest(value))
+        refuse("snapshot_not_ready");
+    return value;
+}
+export function assertDiagnosticSnapshot(context, snapshot) {
+    const input = { projectId: snapshot.projectId, projectRoot: snapshot.projectRoot, sourceRoot: snapshot.sourceRoot, requestId: snapshot.requestId, flowId: snapshot.flowId };
+    const selected = readDiagnosticSnapshot(context, input);
+    if (!selected || hybridDigest(selected) !== hybridDigest(snapshot))
+        refuse("snapshot_binding_changed");
+}
+/** Copies only established review-visible inputs, never environment files or Git internals.
+ * Existing partial copies are verified, not overwritten. Reports belong outside this workspace. */
+export function prepareDiagnosticSnapshot(context, input) {
+    validate(context, input);
+    const prior = retained(context, input);
+    if (prior) {
+        if (rows(context, input, readyEvent).length)
+            return readDiagnosticSnapshot(context, input);
+        verifyFiles(prior);
+        seal(context, input, prior);
+        return prior;
+    }
+    const root = destination(context, input), env = { ...context.env, GIT_OPTIONAL_LOCKS: "0" };
+    for (const key of Object.keys(env))
+        if (key.startsWith("GIT_") && key !== "GIT_OPTIONAL_LOCKS")
+            delete env[key];
+    const git = (...args) => {
+        try {
+            return execFileSync("git", ["-c", "core.fsmonitor=false", "-C", input.sourceRoot, ...args], { env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 1024 * 1024 }).trim();
+        }
+        catch {
+            return null;
+        } // Git absence is explicit missing evidence, never a clean verdict.
+    };
+    const value = { ...input, schema_id: "dd-flow/diagnostic-snapshot@1", root, source_sha256: reviewSourceHash(input.sourceRoot),
+        git: { head: git("rev-parse", "HEAD"), branch: git("symbolic-ref", "--quiet", "--short", "HEAD"), status: git("status", "--porcelain=v1") } };
+    let current = context.ddFlowHome;
+    for (const part of path.relative(context.ddFlowHome, path.dirname(root)).split(path.sep)) {
+        current = path.join(current, part);
+        if (fs.existsSync(current)) {
+            if (!fs.lstatSync(current).isDirectory() || fs.realpathSync(current) !== current)
+                refuse("unsafe_snapshot_parent");
+        }
+        else
+            fs.mkdirSync(current, { mode: 0o700 });
+    }
+    if (fs.existsSync(root))
+        refuse("unowned_snapshot_directory");
+    context.db.writeTransaction(() => {
+        if (rows(context, input, intentEvent).length)
+            refuse("snapshot_already_reserved");
+        appendAudit(context, { projectId: input.projectId, eventType: intentEvent, payload: { ...value } });
+    });
+    fs.mkdirSync(root, { mode: 0o700 });
+    fs.cpSync(input.sourceRoot, root, { recursive: true, verbatimSymlinks: true, force: false, errorOnExist: true, filter: reviewSourceFilter(input.sourceRoot) });
+    verifyFiles(value, false);
+    // A private, independent index makes ordinary controller Git observations safe.
+    // No project worktree/index, hooks, commits or branch is changed.
+    execFileSync("git", ["-c", "init.templateDir=", "init", "--quiet", "--initial-branch=diagnostic-snapshot", root], { env, stdio: "pipe" });
+    // A tracked source can also match .gitignore. Keep the selected safe files
+    // tracked in the private index so subsequent review copies cannot omit it.
+    execFileSync("git", ["-C", root, "add", "--force", "--all", "--", "."], { env, stdio: "pipe" });
+    verifyFiles(value);
+    seal(context, input, value);
+    return value;
+}

package/dist/services/diagnostic-stage-handlers.js

@@ -0,0 +1,109 @@
+import { AppError } from "../shared/errors.js";
+import { isDiagnosticFlow, diagnosticFlowStages } from "../domain/diagnostic-flows.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { diagnosticSnapshotPaths, readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator, readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { PreparedDescriptorRunSettlement } from "./descriptor-run-settlement.js";
+import { assertDiagnosticCriticResolution, assertDiagnosticReportData, assertDiagnosticStageScope, materializeDiagnosticRetainedFields, sealDiagnosticStageLimitations, validateDiagnosticStageResult } from "./diagnostic-stage-results.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { registerDiagnosticStageGraph } from "./diagnostic-work-registration.js";
+import { PreparedDiagnosticWorkCollection } from "./diagnostic-work-collection.js";
+import { collectDiagnosticCandidates, sealDiagnosticCandidateIds } from "./diagnostic-work-results.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareDiagnosticReport } from "./diagnostic-report.js";
+import { prepareDiagnosticReportPublication } from "./diagnostic-report-publication.js";
+export const diagnosticStageHandlers = Object.freeze(Object.entries(diagnosticFlowStages).flatMap(([flowId, stages]) => stages.map(stage => Object.freeze({ flowId, stage, entryId: "diagnostic-stage-entry", finishId: "diagnostic-stage-finish",
+    entry: startDiagnosticStage, finish: finishDiagnosticStage }))));
+function refuse(reason) { throw new AppError("diagnostic_stage_invalid", "Diagnostic stage cannot accept this result", 2, { reason, effect: "no_effect" }); }
+function select(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input), project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    if (!bundle || !isDiagnosticFlow(bundle.manifest.flow_id)
+        || !diagnosticFlowStages[bundle.manifest.flow_id].includes(input.stage))
+        refuse("registered_diagnostic_stage_required");
+    const frozen = bundle.execution.snapshot().scope;
+    const snapshotSelection = { projectId: project.id, projectRoot: frozen.projectRoot, sourceRoot: frozen.projectRoot,
+        requestId: frozen.requestId, flowId: bundle.manifest.flow_id };
+    const snapshot = readDiagnosticSnapshot(context, snapshotSelection, input.runId);
+    if (!snapshot || snapshot.root !== frozen.workspace)
+        refuse("snapshot_required");
+    return { bundle, snapshot, snapshotSelection, scope: { projectId: project.id, runId: input.runId, stage: input.stage } };
+}
+export function startDiagnosticStage(context, input) {
+    const selected = select(context, input);
+    const fence = (writer) => {
+        if (hybridDigest(readDiagnosticSnapshotCustody(writer, selected.snapshotSelection, input.runId)) !== hybridDigest(selected.snapshot))
+            refuse("snapshot_changed");
+    };
+    const start = PreparedDescriptorStageStart.prepare(context, input).apply(context);
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, input).apply(context, fence);
+    if (["audit", "analyze", "review"].includes(input.stage))
+        registerDiagnosticStageGraph(context, input);
+    return { ...start, ...coordinator };
+}
+/** Findings are data, not permission to repair. Only registered independent Work
+ * may contribute analysis/criticism; terminal acceptance closes runtime only. */
+export function finishDiagnosticStage(context, input) {
+    const selected = select(context, input), { bundle, snapshot, scope } = selected;
+    const stageInput = readDescriptorStageInput(context, scope, bundle, true, true);
+    const previousStage = stageInput.input.predecessor?.stage;
+    const previous = previousStage ? readAcceptedStageData(context, { ...scope, stage: previousStage }) : null;
+    const prior = previous ? JSON.parse(previous.bytes.toString("utf8")) : null;
+    const collection = ["audit", "analyze", "review"].includes(input.stage) ? PreparedDiagnosticWorkCollection.prepare(context, input) : null;
+    const proposal = materializeDiagnosticRetainedFields(input.bytes, prior, input.stage);
+    const candidates = ["audit", "analyze"].includes(input.stage) ? sealDiagnosticCandidateIds(proposal, collection.results()) : proposal;
+    const bytes = sealDiagnosticStageLimitations(candidates, [
+        ...(prior?.details.limitations ?? []), ...(collection?.results() ?? []).flatMap(work => work.result.limitations)
+    ], prior?.details.missing_expected_sources ?? []);
+    const result = validateDiagnosticStageResult(bytes, bundle.descriptor.stageBlob(input.stage, "result_schema"), {
+        flowId: selected.snapshotSelection.flowId, runId: input.runId, stage: input.stage,
+        inputSha256: stageInput.inputSha256, snapshotSha256: snapshot.source_sha256, snapshotRoot: diagnosticSnapshotPaths(context, snapshot, input.runId).root,
+        predecessors: stageInput.input.predecessor ? [{ stage: stageInput.input.predecessor.stage,
+                path: stageInput.input.predecessor.result.path, sha256: stageInput.input.predecessor.result.sha256 }] : []
+    });
+    if (prior) {
+        assertDiagnosticStageScope(result, prior);
+        if (prior.details.limitations.some(value => !result.details.limitations.includes(value)))
+            refuse("limitation_dropped");
+    }
+    if (collection) {
+        const works = collection.results();
+        if (works.some(work => work.result.limitations.some(value => !result.details.limitations.includes(value))))
+            refuse("worker_limitation_dropped");
+        if (input.stage !== "review") {
+            if (hybridDigest(result.details.findings) !== hybridDigest(collectDiagnosticCandidates(works).findings))
+                refuse("analysis_not_from_work");
+        }
+        else {
+            if (!prior || hybridDigest(result.details.findings) !== hybridDigest(prior.details.findings))
+                refuse("candidate_register_changed");
+            for (const decision of result.details.decisions) {
+                assertDiagnosticCriticResolution(decision, works.map(work => work.result.decisions));
+            }
+        }
+    }
+    if (input.stage === "report")
+        assertDiagnosticReportData(result, prior);
+    const analysis = input.stage === "report" ? PreparedDiagnosticWorkCollection.prepare(context, { ...input, stage: snapshot.flowId === "mb-audit" ? "audit" : "analyze" }) : null;
+    const critics = input.stage === "report" ? PreparedDiagnosticWorkCollection.prepare(context, { ...input, stage: "review" }) : null;
+    const publication = analysis && critics ? prepareDiagnosticReportPublication(context, { ...scope, attempt: stageInput.attempt, inputSha256: stageInput.inputSha256 }, prepareDiagnosticReport(result, analysis.results(), critics.results())) : null;
+    publication?.publish();
+    const fence = (writer) => {
+        if (hybridDigest(readDiagnosticSnapshotCustody(writer, selected.snapshotSelection, input.runId)) !== hybridDigest(snapshot))
+            refuse("snapshot_changed");
+        if (previous && hybridDigest(readAcceptedStageData(writer, { ...scope, stage: previousStage })) !== hybridDigest(previous))
+            refuse("predecessor_changed");
+        collection?.assertCustody(writer);
+        analysis?.assertCustody(writer);
+        critics?.assertCustody(writer);
+        publication?.retain(writer);
+    };
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, bytes }).apply(context, fence);
+    if (input.stage === "report")
+        return { ...settlement,
+            ...PreparedDescriptorRunSettlement.prepare(context, input).apply(context, fence), reports: publication.manifest.artifacts };
+    return settlement;
+}

package/dist/services/diagnostic-stage-results.js

@@ -0,0 +1,158 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { diagnosticFlowStages } from "../domain/diagnostic-flows.js";
+import { diagnosticAspects } from "../domain/diagnostic-aspects.js";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { verifyDiagnosticCoverage, verifyDiagnosticSources } from "./diagnostic-evidence.js";
+const refuse = (reason) => {
+    throw new AppError("diagnostic_stage_result_invalid", "Diagnostic result does not match its frozen stage", 2, { reason, effect: "no_effect", ...(reason === "result_schema_invalid" ? { phase: "prepare", recoverable: true } : {}) });
+};
+/** Retained fields are CLI data, not a transcription task for the coordinator. */
+export function materializeDiagnosticRetainedFields(bytes, prior, stage) {
+    if (!prior || !bytes.length || bytes.length > 1024 * 1024)
+        return bytes;
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return bytes;
+    }
+    if (!value || typeof value !== "object" || !value.details || typeof value.details !== "object" || Array.isArray(value.details))
+        return bytes;
+    const retained = stage === "report" ? Object.entries(prior.details).filter(([key]) => key !== "limitations")
+        : ["focus", "coverage"].map(key => [key, prior.details[key]]);
+    for (const [key, expected] of retained) {
+        if (Object.hasOwn(value.details, key) && hybridDigest(value.details[key]) !== hybridDigest(expected))
+            throw new AppError("diagnostic_stage_invalid", "A proposal cannot replace CLI-retained predecessor data", 2, { reason: `accepted_${key}_changed`, effect: "no_effect", phase: "prepare", recoverable: true });
+        value.details[key] = structuredClone(expected);
+    }
+    if (!Object.hasOwn(value.details, "limitations"))
+        value.details.limitations = [];
+    if (!Object.hasOwn(value.details, "missing_expected_sources"))
+        value.details.missing_expected_sources = structuredClone(prior.details.missing_expected_sources);
+    return Buffer.from(JSON.stringify(value));
+}
+/** Accepted limitations and missing-source observations belong to predecessor/Work custody, not a coordinator's
+ * transcription. Keep its annotations too; validate the complete sealed result
+ * with the frozen schema afterwards, without truncating overflowing data. */
+export function sealDiagnosticStageLimitations(bytes, required, acceptedMissingSources = []) {
+    if ((!required.length && !acceptedMissingSources.length) || !bytes.length || bytes.length > 1024 * 1024)
+        return bytes;
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return bytes;
+    }
+    let changed = false;
+    for (const [key, expected] of [["limitations", required], ["missing_expected_sources", acceptedMissingSources]]) {
+        if (!expected.length)
+            continue;
+        const proposed = value?.details?.[key];
+        if (!Array.isArray(proposed) || proposed.some(item => typeof item !== "string"))
+            return bytes;
+        const missing = [...new Set(expected.filter(item => !proposed.includes(item)))];
+        if (missing.length) {
+            value.details[key] = [...missing, ...proposed];
+            changed = true;
+        }
+    }
+    return changed ? Buffer.from(JSON.stringify(value)) : bytes;
+}
+export function assertDiagnosticStageScope(result, prior) {
+    const coverageScope = (value) => value.details.coverage.map(({ id, applicability }) => ({ id, applicability }));
+    if (result.details.focus.mode !== prior.details.focus.mode
+        // New source gaps are analytical observations, not an expansion of scope.
+        // Previously accepted gaps still cannot disappear from the result.
+        || prior.details.missing_expected_sources.some(source => !result.details.missing_expected_sources.includes(source))
+        || hybridDigest(coverageScope(result)) !== hybridDigest(coverageScope(prior)))
+        throw new AppError("diagnostic_stage_invalid", "Diagnostic stage cannot accept this result", 2, { reason: "accepted_scope_changed", effect: "no_effect" });
+    // Focus prose is retained selection, not a new stage heading. A different
+    // proposal is never accepted, but can copy the exact predecessor and retry.
+    if (hybridDigest(result.details.focus) !== hybridDigest(prior.details.focus))
+        throw new AppError("diagnostic_stage_invalid", "Copy details.focus unchanged from the accepted predecessor; put the stage summary in summary, not the retained focus", 2, { reason: "accepted_focus_changed", effect: "no_effect", phase: "prepare", recoverable: true });
+    // Applicability is already accepted. Analytical progress belongs in findings,
+    // sources and limitations, not edits to the retained preflight annotations.
+    if (hybridDigest(result.details.coverage) !== hybridDigest(prior.details.coverage))
+        throw new AppError("diagnostic_stage_invalid", "Copy details.coverage unchanged from the accepted predecessor; put new observations in findings, sources or limitations", 2, { reason: "accepted_coverage_annotations_changed", effect: "no_effect", phase: "prepare", recoverable: true });
+}
+export function assertDiagnosticReportData(result, prior) {
+    // Reporting may disclose additional uncertainty, never revise reviewed facts
+    // or erase any accepted limitation. This comparison does not rewrite either result.
+    if (!prior || prior.details.limitations.some(value => !result.details.limitations.includes(value))
+        || hybridDigest({ ...result.details, limitations: prior.details.limitations }) !== hybridDigest(prior.details))
+        throw new AppError("diagnostic_stage_invalid", "Diagnostic stage cannot accept this result", 2, { reason: "report_changed_reviewed_data", effect: "no_effect" });
+}
+export function assertDiagnosticCriticResolution(decision, critics) {
+    const selected = decision;
+    const votes = critics.flat().filter(item => item.finding_id === decision.finding_id);
+    // Duplicate/rejected entries remain trace, not accepted findings. Their
+    // supported severity may be reconciled separately without inventing a vote.
+    // An accepted finding still requires one critic to endorse the whole pair.
+    const nonAccepting = ["duplicate", "rejected"].includes(selected.disposition);
+    if (votes.some(item => item.disposition === selected.disposition && item.severity === selected.severity)
+        || nonAccepting && votes.some(item => item.disposition === selected.disposition)
+            && votes.some(item => item.severity === selected.severity))
+        return;
+    throw new AppError("diagnostic_stage_invalid", "Use a supported critic resolution; preserve all independent critic decisions and explain disagreements", 2, { reason: "unsupported_critic_resolution", effect: "no_effect", phase: "prepare", recoverable: true,
+        finding_id: selected.finding_id, supported_resolutions: votes.map(item => ({ disposition: item.disposition, severity: item.severity })) });
+}
+/** Frozen schema and exact CLI-issued identity precede semantic evidence checks.
+ * This does not assert that independent Work/critics have settled. */
+export function validateDiagnosticStageResult(bytes, schemaBytes, binding) {
+    if (!bytes.length || bytes.length > 1024 * 1024 || schemaBytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    const validate = (() => {
+        try {
+            const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(schemaBytes));
+            if (schema.$id !== "dd-flow/diagnostic-stage-result@1")
+                refuse("frozen_schema_invalid");
+            return new Ajv2020({ strict: false, validateFormats: false }).compile(schema);
+        }
+        catch {
+            return refuse("frozen_schema_invalid");
+        }
+    })();
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("result_schema_invalid");
+    }
+    if (!validate(value))
+        refuse("result_schema_invalid");
+    if (value.flow_id !== binding.flowId || value.run_id !== binding.runId || value.stage !== binding.stage
+        || !diagnosticFlowStages[binding.flowId].includes(binding.stage)
+        || value.input_sha256 !== binding.inputSha256 || value.snapshot_sha256 !== binding.snapshotSha256
+        || hybridDigest(value.predecessors) !== hybridDigest(binding.predecessors))
+        refuse("foreign_result_binding");
+    if ((binding.flowId === "mb-audit") !== (value.details.focus.mode === "memory_bank"))
+        refuse("foreign_focus");
+    verifyDiagnosticCoverage(binding.snapshotRoot, diagnosticAspects[binding.flowId].map(item => item.id), value.details.coverage);
+    verifyDiagnosticSources(binding.snapshotRoot, value.details.sources);
+    const ids = new Set();
+    for (const finding of value.details.findings) {
+        if (ids.has(finding.id) || !value.details.coverage.some(item => item.id === finding.aspect_id && item.applicability === "applicable")
+            || !finding.evidence.length)
+            refuse("finding_outside_coverage");
+        ids.add(finding.id);
+        verifyDiagnosticSources(binding.snapshotRoot, finding.evidence);
+    }
+    const decided = new Set();
+    for (const decision of value.details.decisions) {
+        if (!ids.has(decision.finding_id) || decided.has(decision.finding_id))
+            refuse("foreign_or_duplicate_decision");
+        decided.add(decision.finding_id);
+        verifyDiagnosticSources(binding.snapshotRoot, decision.evidence);
+    }
+    if (binding.stage === "preflight" && (ids.size || decided.size))
+        refuse("preflight_cannot_claim_analysis");
+    if (["audit", "analyze"].includes(binding.stage) && decided.size)
+        refuse("analysis_cannot_claim_independent_review");
+    if (["review", "report"].includes(binding.stage) && decided.size !== ids.size)
+        refuse("unresolved_finding");
+    return value;
+}