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

package/dist/services/run-controller.js

@@ -1,15 +1,18 @@
-import { assertLifecycleOutcomes, currentLifecycleFailure, managedInvocationContext, managedLifecycleCommand } from "./lifecycle-invocations.js";
+import { assertLifecycleOutcomes, currentLifecycleFailure, managedInvocationContext, managedLifecycleCommand, awaitLifecycleInvocation, assertLifecycleInvocationCurrent } from "./lifecycle-invocations.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
 export function recoveryPacketMatchesStage(packet, scope) {
     return packet.schema_id === 'dd-flow/root-recovery-packet@1' && packet.continuation === 'unfinished_work'
         && packet.run_id === scope.runId && packet.generation === scope.generation && packet.stage === scope.stage
         && packet.work_id === scope.workId && packet.paused === false;
 }
 import crypto from "node:crypto";
+import { nativeShutdownConfirmed } from "../harness-runtime/lib/native-children.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import { quote } from "shell-quote";
+import { retainedBrowserEnvironment, validateCheckEnvironment } from "./check-environment.js";
 import { ensureRunControllerStorage, getDatabase } from "../storage/database.js";
 import { canonicalPath, resolveProjectRoot } from "../storage/paths.js";
 import { publishImmutableInput } from "../storage/immutable-input.js";
@@ -20,7 +23,7 @@ import { requireProjectByRoot } from "./projects.js";
 import { assertRunMutationAllowed, recoveryGuard } from "./run-recovery.js";
 import { getFlowRunStatus, setFlowRunRecoveryPaused, assertPreparedRunBundleSqlAuthority } from "./runs.js";
 import { loadExternalStageContext } from "./stage-context.js";
-import { flowCommand } from "./stage-pause.js";
+import { flowCommand, stageResumeSourcePath } from "./stage-pause.js";
 import { sameSessionProfile, runtimeHarness } from "./execution-policy.js";
 import { selectControllerExecution } from "./controller-execution.js";
 import { resolveHarnessCommand, harnessRuntimeArguments } from "./harness-config.js";
@@ -33,6 +36,8 @@ import { initCodexHome } from "./hooks.js";
 import { launchExternalWork } from "./external-work-launch.js";
 import { runControllerMemoryTask } from "./controller-memory-task.js";
 import { controllerNativeChildren, controllerStageEntryPrompt, controllerStageResumePrompt, nextControllerFanout } from "./controller-fanout.js";
+import { publishPromptDelivery } from "./prompt-delivery.js";
+import { publishStagePacket } from "./stage-report-renderer.js";
 import { claimQueuedMergeRequest } from "./merge-server.js";
 import { prepareVnextCodeWorkspace } from "./vnext-code.js";
 import { requireRun, requireController, controllerReceipt, appendEvent, saveState, retainControllerContinuation, retainControllerCapacityIntent, digest, digestBytes, errorRecord } from "./run-controller-state.js";
@@ -135,7 +140,8 @@ export function retainRunControllerLaunch(context, input, prepared = prepareRunC
     }
     const manifest = { schema_id: routing.kind === "descriptor" ? "dd-flow/run-controller-manifest@2" : "dd-flow/run-controller-manifest@1", request,
         ...(routing.kind === "descriptor" ? { execution_binding: routing.binding } : { execution_profile: routing.legacy }),
-        contexts: frozenContexts, adapters, flow_executable: flowExecutable, resource_home: resourceHome(context), budget };
+        contexts: frozenContexts, adapters, flow_executable: flowExecutable, resource_home: resourceHome(context), budget,
+        ...(retainedBrowserEnvironment(context.env) ? { check_environment: retainedBrowserEnvironment(context.env) } : {}) };
     const token = crypto.randomUUID();
     const now = context.now();
     const state = { stage: null, sessions: [], current_session: null, turns: 0, last_continuation: null };
@@ -533,7 +539,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
     const routing = selectControllerExecution(context, requireRun(context, row.project_id, row.run_id), manifest);
     const policy = routing.policy;
     const profiles = routing.profiles;
-    let executionContext = { ...context, env: { ...context.env, DD_FLOW_BIN: manifest.flow_executable, DD_FLOW_RESOURCE_HOME: manifest.resource_home, DD_FLOW_RUNTIME_BUDGET: manifest.budget ? JSON.stringify(manifest.budget) : undefined, DD_FLOW_CODE_READINESS_OWNER: row.controller_id } };
+    let executionContext = { ...context, env: { ...context.env, ...validateCheckEnvironment(manifest.check_environment), DD_FLOW_BIN: manifest.flow_executable, DD_FLOW_RESOURCE_HOME: manifest.resource_home, DD_FLOW_RUNTIME_BUDGET: manifest.budget ? JSON.stringify(manifest.budget) : undefined, DD_FLOW_CODE_READINESS_OWNER: row.controller_id } };
     const bindInvocationScope = (session) => {
         executionContext = managedInvocationContext(executionContext, { harness: runtimeHarness(session.profile), stateDir: session.state_dir, sessionId: session.id,
             projectRoot: manifest.request.project_root, runId: row.run_id, generation: row.generation });
@@ -634,9 +640,9 @@ async function executeController(context, row, manifest, state, assertOwnership,
     const call = (session, args, productive = true) => controllerAdapter(executionContext, row, manifest, session, args, productive ? assertOwner : undefined, undefined, productive ? cancellation.signal : undefined, productive ? renewLease : undefined);
     const confirmStopped = async (stateDir, receipt) => {
         const fail = () => new AppError("controller_native_shutdown_unproven", "The managed daemon is not proven clean and closed", 1, { state_dir: stateDir, receipt });
-        if (receipt.stopped !== true || receipt.clean !== true)
-            throw fail();
         const binding = requireManagedDaemonBinding(executionContext, { stateDir, projectId: row.project_id, runId: row.run_id });
+        if (!binding.state.daemon_id || receipt.stopped !== true || !nativeShutdownConfirmed(receipt, { daemonId: binding.state.daemon_id }))
+            throw fail();
         const deadline = performance.now() + 30_000;
         while (processTreeIsAlive(binding.process) && performance.now() < deadline)
             await delay(100);
@@ -681,6 +687,45 @@ async function executeController(context, row, manifest, state, assertOwnership,
         if (!pending)
             await reconcilePromptPredecessor(session);
         const firstOperationId = pending?.root_operation_id ?? operationId ?? `${row.controller_id}:prompt:${crypto.randomUUID()}`;
+        const hitlText = async () => {
+            const answerId = firstOperationId.slice(0, -`:prompt:${row.generation}`.length);
+            const answer = context.db.get("SELECT input_json,receipt_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND status IN ('accepted','completed')", [answerId, row.controller_id]);
+            const accepted = answer && JSON.parse(answer.input_json);
+            const packet = answer?.receipt_json && JSON.parse(answer.receipt_json).hitl_packet;
+            if (!packet || !accepted || packet.generation !== row.generation || packet.pause_id !== accepted.pause_id || packet.stage !== accepted.stage || packet.work_id !== accepted.work_id || packet.answer_file !== accepted.file || packet.answer_sha256 !== accepted.sha256)
+                throw new AppError("controller_hitl_packet_invalid", "Accepted HITL continuation lost its exact binding", 1);
+            const issued = context.db.get("SELECT id,status,scope_json,command FROM lifecycle_invocations WHERE id = ?", [packet.invocation_id ?? null]);
+            if (!issued || issued.scope_json !== executionContext.env.DD_FLOW_INVOCATION_SCOPE)
+                throw new AppError("controller_hitl_packet_invalid", "Accepted HITL command belongs to another scope", 1);
+            if (issued.status === "executing" || issued.status === "settled") {
+                const recovered = await awaitLifecycleInvocation(executionContext, { id: issued.id, command: issued.command, assertCurrent: scope => assertLifecycleInvocationCurrent(executionContext, scope, issued.command) });
+                if (!recovered.replay)
+                    throw new AppError("controller_hitl_reconciliation_required", "Accepted resume is not committed", 1);
+                const outcome = recovered.outcome;
+                if (!outcome.result)
+                    throw new AppError("controller_hitl_reconciliation_required", "Accepted resume has no committed continuation", 1);
+                if (outcome.result.resume_source_path !== packet.resume_source_path || typeof outcome.result.answer_path !== "string")
+                    throw new AppError("controller_hitl_packet_invalid", "Committed resume differs from the accepted packet locator", 1);
+                publishStagePacket(executionContext, row.project_id, row.run_id, packet.stage, outcome.result.answer_path);
+                publishStagePacket(executionContext, row.project_id, row.run_id, packet.stage, packet.resume_source_path);
+                const bytes = fs.readFileSync(outcome.result.answer_path);
+                if (digestBytes(bytes) !== packet.answer_sha256)
+                    throw new AppError("context_checksum_mismatch", "Committed answer differs from its accepted bytes", 1);
+                fs.mkdirSync(path.dirname(packet.answer_file), { recursive: true, mode: 0o700 });
+                publishImmutableInput(packet.answer_file, bytes, "hitl_answer_conflict");
+                publishPromptDelivery(outcome.result);
+                const delivery = outcome.result.prompt_delivery;
+                const promptPath = delivery?.path ?? outcome.result.prompt_path;
+                if (typeof promptPath !== "string" || !path.isAbsolute(promptPath))
+                    throw new AppError("controller_hitl_packet_invalid", "Committed resume has no absolute prompt delivery", 1);
+                // Keep continuation bytes stable across a retained overload episode.
+                // Its conditional instructions point at this restored exact custody.
+                return controllerStageResumePrompt(packet);
+            }
+            if (issued.status !== "issued" || digestBytes(fs.readFileSync(packet.answer_file)) !== packet.answer_sha256)
+                throw new AppError("context_checksum_mismatch", "Accepted HITL answer or command changed before resume", 1);
+            return controllerStageResumePrompt(packet);
+        };
         const send = (value, id) => {
             const retained = context.db.get("SELECT input_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND generation = ?", [id, row.controller_id, row.generation]);
             if (retained) {
@@ -714,7 +759,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 promptPending = true;
                 observedPromptOperation = firstOperationId;
                 try {
-                    receipt = await send(text, firstOperationId);
+                    receipt = await send(hitl ? await hitlText() : text, firstOperationId);
                 }
                 finally {
                     promptPending = false;
@@ -722,9 +767,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 }
             }
             catch (error) {
-                const resumeCommand = hitl ? text.split("\n\n")[1] : undefined;
-                if (hitl && !resumeCommand?.includes(" stage resume "))
-                    throw error;
+                const hitlContinuationText = hitl && terminalProviderOverload(error, session.id) ? await hitlText() : undefined;
                 const inspect = (args, id) => runHarnessAdapter({ executable: manifest.adapters[runtimeHarness(session.profile)].executable,
                     args, env: controllerEnvironment(context, manifest, session), runtimeOwner: session.owner, operationId: id, timeoutMs: 30_000, signal: cancellation.signal });
                 const resumed = await continueProviderCapacity({ error, sessionId: session.id, operationId: firstOperationId, signal: cancellation.signal, allowSettledDescendants: true, atomicIntent: true,
@@ -781,7 +824,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     },
                     retainIntent: intent => retainControllerCapacityIntent(context, row, state, intent, session.id, kind ?? "stage", assertOwner),
                     prompt: (id, value) => send(value, id),
-                    ...(resumeCommand ? { continuationText: `Continue the same accepted HITL task in this Session. First inspect current durable RUN and pause state. Only if the exact pause still awaits the accepted answer, run this previously issued command once:\n\n${resumeCommand}\n\nNever replay an already committed answer. Otherwise use only the current issued successor.` } : {}) });
+                    ...(hitlContinuationText ? { continuationText: hitlContinuationText } : {}) });
                 if (!resumed)
                     throw error;
                 receipt = resumed;
@@ -845,6 +888,17 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 await prompt(session, fs.readFileSync(file, "utf8"), pending.root_operation_id, pending.kind === "stage" ? undefined : pending.kind);
                 continue;
             }
+            if (next.kind !== "paused" && state.current_session !== null) {
+                const committed = context.db.get("SELECT operation_id,receipt_json FROM run_controller_operations WHERE controller_id = ? AND status = 'accepted' AND json_extract(input_json,'$.action') = 'user_answer' AND json_extract(receipt_json,'$.hitl_packet.generation') = ? AND json_extract(receipt_json,'$.hitl_packet.stage') = ? ORDER BY created_at LIMIT 1", [row.controller_id, row.generation, state.stage]);
+                if (committed) {
+                    const packet = JSON.parse(committed.receipt_json).hitl_packet;
+                    const receipt = await prompt(state.sessions[state.current_session], controllerStageResumePrompt(packet), `${committed.operation_id}:prompt:${row.generation}`, "hitl");
+                    context.db.run("UPDATE run_controller_operations SET status = 'completed', receipt_json = json_set(receipt_json,'$.delivered',json('true'),'$.session_id',?), updated_at = ? WHERE operation_id = ? AND status = 'accepted'", [adapterSessionId(receipt), context.now(), committed.operation_id]);
+                    state.last_continuation = null;
+                    saveState(context, row, state);
+                    continue;
+                }
+            }
             const completed = state.stage && view.index.stage_runs.find(stage => stage.stage === state.stage && ["done", "skipped"].includes(stage.status));
             if (state.current_session !== null && (completed || next.stage !== state.stage) && childObserver(state.sessions[state.current_session])?.failed().length)
                 throw new AppError("fanout_dispatch_fenced", "A retained child failure forbids completing or advancing its Stage", 1);
@@ -890,13 +944,29 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 assertOwner();
                 // The accepted answer is logical intent; only its generation-bound
                 // adapter operation represents a physical dispatch that stop must drain.
-                const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage resume ${run.id} --stage ${next.stage} --work ${input.work_id} --project-root ${quote([run.project_root])} --answer-file ${quote([input.file])} --json`, { replaceUnobservedAnswer: true });
-                const receipt = await prompt(state.sessions[state.current_session], controllerStageResumePrompt(pause.id, command), `${answer.operation_id}:prompt:${row.generation}`, "hitl");
+                let invocationId;
+                const capture = executionContext.captureLifecycleAssignment;
+                executionContext.captureLifecycleAssignment = id => { invocationId = id; capture?.(id); };
+                let command;
+                try {
+                    command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage resume ${run.id} --stage ${next.stage} --work ${input.work_id} --project-root ${quote([run.project_root])} --answer-file ${quote([input.file])} --json`, { replaceUnobservedAnswer: true });
+                }
+                finally {
+                    if (capture)
+                        executionContext.captureLifecycleAssignment = capture;
+                    else
+                        delete executionContext.captureLifecycleAssignment;
+                }
+                if (!invocationId)
+                    throw new AppError("controller_hitl_packet_invalid", "Accepted resume did not capture its issued identity", 1);
+                const packet = { pause_id: pause.id, stage: next.stage, work_id: input.work_id, answer_file: input.file, answer_sha256: input.sha256, command, generation: row.generation, invocation_id: invocationId, resume_source_path: stageResumeSourcePath(pause, fs.readFileSync(input.file, "utf8")) };
+                context.db.run("UPDATE run_controller_operations SET receipt_json = ?, updated_at = ? WHERE operation_id = ? AND status = 'accepted'", [JSON.stringify({ hitl_packet: packet }), context.now(), answer.operation_id]);
+                const receipt = await prompt(state.sessions[state.current_session], controllerStageResumePrompt(packet), `${answer.operation_id}:prompt:${row.generation}`, "hitl");
                 const afterAnswer = getFlowRunStatus(executionContext, { projectRoot: run.project_root, runId: run.id });
                 if (afterAnswer.index.stage_runs.some(stage => stage.status === "paused" && stage.pause?.id === pause.id)) {
                     throw new AppError("controller_answer_not_applied", "The answer Turn completed without resuming the assigned HITL pause", 1, { pause_id: pause.id, operation_id: answer.operation_id, stage: next.stage, effect: "no_progress" });
                 }
-                context.db.run("UPDATE run_controller_operations SET status = 'completed', receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify({ delivered: true, session_id: adapterSessionId(receipt) }), context.now(), answer.operation_id]);
+                context.db.run("UPDATE run_controller_operations SET status = 'completed', receipt_json = json_set(receipt_json,'$.delivered',json('true'),'$.session_id',?), updated_at = ? WHERE operation_id = ?", [adapterSessionId(receipt), context.now(), answer.operation_id]);
                 state.last_continuation = null;
                 saveState(context, row, state);
                 setStatus("running");
@@ -1129,7 +1199,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     continue;
                 }
             }
-            const memoryFlow = ["mb-init", "mb-upgrade"].includes(run.flow_kind);
+            const memoryFlow = ["mb-init", "mb-upgrade"].includes(run.flow_kind) || isDiagnosticFlow(run.flow_kind);
             const fanoutInput = { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles, dispatchFence: retainedFailures.length > 0 };
             const fanout = memoryFlow ? await runControllerMemoryTask(executionContext, { operation: "fanout", input: fanoutInput }, cancellation.signal)
                 : await nextControllerFanout(executionContext, fanoutInput);

package/dist/services/run-fork.js

@@ -28,7 +28,7 @@ export function prepareRunFork(input) {
     }
     prepareForkEngine(engineVersion, input.integrityChecksum);
     const manifest = prepareEvalRunSnapshot(snapshot);
-    if (manifest.schema_id !== "dd-flow/eval-run-snapshot@5" || manifest.purpose !== "stage_entry" || typeof manifest.stage_entry !== "string" || typeof manifest.run_id !== "string") {
+    if (!["dd-flow/eval-run-snapshot@5", "dd-flow/eval-run-snapshot@7"].includes(manifest.schema_id) || manifest.purpose !== "stage_entry" || typeof manifest.stage_entry !== "string" || typeof manifest.run_id !== "string") {
         throw new AppError("fork_checkpoint_invalid", "Fork requires a sealed stage-entry snapshot", 2, { snapshot });
     }
     const operational = prepareSnapshotOperationalDecision({ snapshot, runId: manifest.run_id, projectRoot: path.join(output, "project"), now: new Date().toISOString(), ...(input.operationalDecisionFile ? { file: input.operationalDecisionFile } : {}) });

package/dist/services/runs.js

@@ -27,6 +27,7 @@ import { RetainedExecutionBundle } from "./execution-bundles.js";
 import { admitBundledFlow, bundledHandlerContext } from "./stage-handlers.js";
 import { hybridDigest } from "./hybrid-contracts.js";
 import { projectPacketLocators, runContextRelocations } from "./stage-context.js";
+import { readRunEngineBinding } from "./run-engine-bindings.js";
 const runSchemaId = "dd-flow/flow-run@3";
 const runtimeSchemaId = "dd-flow/flow-run@3";
 const allowedRunFlowKinds = [
@@ -36,6 +37,7 @@ const allowedRunFlowKinds = [
     "mb-init",
     "mb-upgrade",
     "mb-audit",
+    "project-review",
     "mb-distill",
     "mb-upgrade-review",
     "mb-sdlc-review",
@@ -1843,7 +1845,10 @@ export function readFlowRunExecutionBundle(context, input) {
         throw new AppError("run_bundle_authority_invalid", "RUN bundle admission authority changed", 1);
     }
     const admission = { ...retained, receipts: new Map(retained.receipts), descriptorContext: bundledHandlerContext(new Map()) };
-    const bundle = RetainedExecutionBundle.read(path.join(runArtifactRoot(run), "execution-bundle"), anchor.manifest_sha256, admission);
+    const relocations = runContextRelocations(context, run.project_id, run.id);
+    const binding = relocations.length ? readRunEngineBinding(path.join(runArtifactRoot(run), "engine-binding.json")) : null;
+    const relocation = binding?.source === "fork_upgrade" ? { binding, relocations } : undefined;
+    const bundle = RetainedExecutionBundle.read(path.join(runArtifactRoot(run), "execution-bundle"), anchor.manifest_sha256, admission, relocation);
     assertBundleRunIdentity(context, run, bundle);
     if (bundle.manifest.descriptor.sha256 !== anchor.descriptor_sha256 || bundle.manifest.flow_id !== anchor.flow_id) {
         throw new AppError("run_bundle_anchor_invalid", "RUN bundle descriptor identity changed", 1);

package/dist/services/runtime-scope-resume.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { nativeShutdownConfirmed } from "../harness-runtime/lib/native-children.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -16,15 +17,19 @@ import { cleanupScopeWriters } from "./scope-writer-cleanup.js";
 import { harnessKey } from "./harness-config.js";
 import { canonicalNativeOperation } from "../harness-runtime/lib/adapter-timeouts.mjs";
 import { retainedDaemonReply } from "../harness-runtime/lib/daemon-observation.mjs";
+import { validateNativeLaunchEnvironment } from "../harness-runtime/lib/daemon-operations.mjs";
 const hash = (value) => crypto.createHash("sha256").update(value).digest("hex");
-const nativeLaunchEnvironmentKeys = ["CODEX_HOME", "DD_FLOW_CONFIG_HOME", "DD_FLOW_HOME", "DD_FLOW_BIN", "DD_FLOW_RESOURCE_HOME"];
 function nativeLaunchEnvironment(context, saved) {
     const env = { ...context.env };
     for (const name of ["DD_FLOW_CONTROLLER_TOKEN", "DD_FLOW_CONTROL_TOKEN", "DD_FLOW_SCOPE_CONTROL_TOKEN", "DD_FLOW_DAEMON_ID", "DD_FLOW_RUNTIME_OWNER"])
         delete env[name];
-    if (!saved || Object.keys(saved).some(name => !nativeLaunchEnvironmentKeys.includes(name)))
-        throw new AppError("runtime_scope_native_launch_required", "Native launch has an unsupported environment", 1);
-    for (const name of nativeLaunchEnvironmentKeys) {
+    try {
+        validateNativeLaunchEnvironment(saved);
+    }
+    catch {
+        throw new AppError("runtime_scope_native_launch_required", "Native launch has an unsupported or invalid configuration environment", 1);
+    }
+    for (const name of Object.keys(saved)) {
         if (saved[name] === null)
             delete env[name];
         else if (typeof saved[name] === "string")
@@ -460,8 +465,9 @@ async function retireScopeNative(context, intent, source, assertCurrent) {
     }
     if (!launch || launch.schema_id !== "dd-flow/native-launch@1" || launch.executable !== source.runtime_owner?.adapter_executable || !path.isAbsolute(launch.executable) || !path.isAbsolute(launch.cwd) || !Array.isArray(launch.args) || launch.args[0] !== "daemon" || launch.args[1] !== "start" || launch.args[launch.args.indexOf("--state-dir") + 1] !== source.state_dir || !isDeepStrictEqual(launchOwner, source.runtime_owner))
         throw new AppError("runtime_scope_native_launch_required", "Native recovery requires the original owned launch contract", 1);
-    if (!launch.env || Object.keys(launch.env).some(name => !nativeLaunchEnvironmentKeys.includes(name)) || nativeLaunchEnvironmentKeys.some(name => launch.env[name] !== null && typeof launch.env[name] !== "string") || launch.args.some(arg => typeof arg !== "string"))
+    if (launch.args.some(arg => typeof arg !== "string"))
         throw new AppError("runtime_scope_native_launch_required", "Native recovery requires explicit configuration presence before retiring its owner", 1);
+    nativeLaunchEnvironment(context, launch.env);
     let dispatch = false;
     const preparedInventory = db.get("SELECT 1 FROM managed_resources WHERE resource_kind = 'scope-resume-native' AND resource_key = ?", [key]) ? null : nativeInventoryVersion(source.state_dir);
     const operation = db.writeTransaction(() => {
@@ -494,7 +500,7 @@ async function retireScopeNative(context, intent, source, assertCurrent) {
         assertOwner();
         db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-resume-native' AND resource_key = ?", [JSON.stringify(operation), context.now(), key]);
     }
-    if (operation.receipt.stopped !== true || operation.receipt.clean !== true || state().shutdown_state !== "clean" || processTreeIsAlive(record))
+    if (operation.receipt.stopped !== true || !nativeShutdownConfirmed(operation.receipt, { daemonId: source.daemon_id }) || state().shutdown_state !== "clean" || processTreeIsAlive(record))
         return { ...source, ...operation, pending: true, reason: "native_retirement_settlement_required" };
     assertOwner();
     operation.status = "retired";

package/dist/services/runtime-scope-stop.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { nativeShutdownConfirmed } from "../harness-runtime/lib/native-children.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
@@ -30,7 +31,7 @@ export async function stopRuntimeScope(context, scopeId, requestId) {
             if (!state.daemon_id || !owner || owner.budget?.scope_id !== scopeId || owner.owner_id !== record.owner_id || owner.role !== metadata.role || owner.state_dir !== metadata.state_dir || owner.adapter_executable !== metadata.adapter_executable || !retainedResourceHomeMatches(context, owner.resource_home) || (owner.project_id ?? null) !== record.project_id || (owner.run_id ?? null) !== record.run_id || (owner.work_id ?? null) !== record.work_id || !record.operation_id?.startsWith(`${owner.operation_id}:`) || state.resource_process?.id !== record.id || state.resource_process.lease_token !== record.lease_token || state.pid !== record.pid)
                 throw new AppError("runtime_scope_owner_unknown", "Native owner does not match its registration", 1);
             const closed = state.shutdown_state === "clean" && state.active_tree === false && !processTreeIsAlive(record)
-                ? retainedDaemonOperations(metadata.state_dir).find(operation => operation.daemon_id === state.daemon_id && operation.operation === "daemon.stop" && operation.state === "completed" && operation.result?.stopped === true && operation.result?.clean === true) : undefined;
+                ? retainedDaemonOperations(metadata.state_dir).find(operation => operation.daemon_id === state.daemon_id && operation.operation === "daemon.stop" && operation.state === "completed" && operation.result?.stopped === true && nativeShutdownConfirmed(operation.result, { daemonId: state.daemon_id ?? "" })) : undefined;
             const operationId = closed ? String(closed.operation_id) : `scope-stop:${crypto.createHash("sha256").update(JSON.stringify([scopeId, record.id, state.daemon_id])).digest("hex")}`;
             const requested = path.join(metadata.state_dir, "operations", crypto.createHash("sha256").update(operationId).digest("hex"), "requested.json");
             const prior = fs.existsSync(requested);
@@ -56,7 +57,7 @@ export async function stopRuntimeScope(context, scopeId, requestId) {
             const finalOwner = managedProcessStatus(context).find(item => item.id === record.id);
             if (!finalOwner || finalOwner.lease_token !== record.lease_token || finalOwner.pid !== record.pid || finalOwner.pid_started_at !== record.pid_started_at || after.resource_process?.id !== record.id || after.resource_process.lease_token !== record.lease_token || JSON.stringify(after.config?.runtime_owner) !== JSON.stringify(owner))
                 throw new AppError("runtime_scope_owner_changed", "Native ownership changed during control", 1);
-            if (result?.stopped !== true || result.clean !== true || after.daemon_id !== state.daemon_id || after.shutdown_state !== "clean" || after.active_tree !== false || processTreeIsAlive(finalOwner))
+            if (result?.stopped !== true || !nativeShutdownConfirmed(result, { daemonId: state.daemon_id }) || after.daemon_id !== state.daemon_id || after.shutdown_state !== "clean" || after.active_tree !== false || processTreeIsAlive(finalOwner))
                 throw new AppError("runtime_scope_not_settled", "Native close has not proved whole-tree settlement", 1);
             const processes = managedProcessStatus(context).filter(item => managedProviderBelongsToDaemon(item, finalOwner, after) && item.operation_id?.startsWith(`${owner.operation_id}:`) && !processTreeIsAlive(item)).map(item => ({ process_id: item.id, native_settled: true, binding: managedProcessBinding(item, resourceHome(context)) }));
             return { process_id: record.id, state_dir: metadata.state_dir, settled: true, native_settled: true, physical_stopped: true, operation_id: operationId, owner_operation_id: owner.operation_id, processes };

package/dist/services/runtime-service.js

@@ -7,6 +7,7 @@ import { assertRunMutationAllowed } from "./run-recovery.js";
 import { requireProjectByRoot } from "./projects.js";
 import { resolveRun } from "./runs.js";
 import { codeExecutionEnvironment, runCheck } from "./code-checks.js";
+import { retainedBrowserEnvironment } from "./check-environment.js";
 import { confirmManagedProcess, finishManagedProcess, renewManagedProcess, managedProcessStatus, processTreeIsAlive, registerManagedProcess, reservePorts, resourceHome, stopManagedProcess } from "./managed-processes.js";
 export function prepareRuntimeService(context, input) {
     validateObservationDuration(input.timeoutMs);
@@ -33,7 +34,7 @@ export async function startRuntimeService(context, input) {
     const save = () => { const temporary = `${receiptPath}.${process.pid}.tmp`; fs.writeFileSync(temporary, JSON.stringify(receipt, null, 2)); fs.renameSync(temporary, receiptPath); };
     try {
         const allocation = await reservePorts(context, { ownerId: record.owner_id, processId: record.id, names: input.ports });
-        const environment = { ...codeExecutionEnvironment(run.workspace_root), ...Object.fromEntries(Object.entries(allocation.ports).map(([name, port]) => [`DD_FLOW_PORT_${name.toUpperCase()}`, String(port)])), DD_FLOW_EVIDENCE_DIR: directory, DD_FLOW_CHECK_COMPLETION_FILE: path.join(directory, "completion.json") };
+        const environment = { ...codeExecutionEnvironment(run.workspace_root, retainedBrowserEnvironment(context.env)), ...Object.fromEntries(Object.entries(allocation.ports).map(([name, port]) => [`DD_FLOW_PORT_${name.toUpperCase()}`, String(port)])), DD_FLOW_EVIDENCE_DIR: directory, DD_FLOW_CHECK_COMPLETION_FILE: path.join(directory, "completion.json") };
         const quoted = (value) => `'${value.replaceAll("'", "'\\''")}'`;
         Object.assign(receipt, { ports: allocation.ports, environment: Object.fromEntries(Object.entries(environment).filter(([key]) => key.startsWith("DD_FLOW_PORT_"))), stop_command: `DD_FLOW_HOME=${quoted(context.ddFlowHome)} DD_FLOW_RESOURCE_HOME=${quoted(resourceHome(context))} dd-flow runtime process stop --id ${record.id} --lease-token ${record.lease_token} --json` });
         save();

package/dist/services/stage-handlers.js

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

package/dist/services/stage-pause.js

@@ -19,6 +19,9 @@ import { prepareAgentOutputFile } from "../storage/agent-output.js";
 import { latestRunVerificationMatrix } from "./verification-matrix.js";
 import { acceptedIntentReviewFingerprint, prepareAcceptedIntentSources, validatePreparedAcceptedIntentReview } from "./accepted-intent.js";
 export { flowCommand } from "./runtime-command.js";
+export function stageResumeSourcePath(pause, answer) {
+    return path.join(path.dirname(pause.question_path), `resume-${crypto.createHash("sha256").update(`${pause.id}\0${answer}`).digest("hex")}.json`);
+}
 export function prepareStagePause(context, input) {
     if (typeof input.question !== "string" || !input.question.trim())
         throw new AppError("validation", "stage pause requires a non-empty user question", 2);
@@ -119,7 +122,7 @@ export function resumeStageAfterUser(context, input) {
     // Capture the exact continuation inputs and already-issued commands before
     // accepting the answer. A publication retry must not issue new authority.
     const retryCommands = lifecycleRetryCommands(context, stage.stage);
-    const resumeSourcePath = path.join(path.dirname(pause.question_path), `resume-${crypto.createHash("sha256").update(`${pause.id}\0${input.answer}`).digest("hex")}.json`);
+    const resumeSourcePath = stageResumeSourcePath(pause, input.answer);
     let review;
     let reviewPreparationError;
     const previousAnswer = context.db.get("SELECT MAX(id) AS id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ?", [project.id, run.id])?.id ?? 0;

package/dist/services/version-status.js

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

package/dist/services/vnext-code.js

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

package/dist/services/vnext-fanout.js

@@ -15,6 +15,8 @@ import { renderNativeChildFollowupInstruction } from "../harness-runtime/lib/del
 import { readDescriptorRootWork } from "./descriptor-root-work.js";
 import { selectMemoryCompositionRegistration } from "./memory-composition-registration.js";
 import { safeNativeFailure } from "../harness-runtime/lib/native-children.mjs";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { readRegisteredDiagnosticGraph } from "./diagnostic-work-registration.js";
 export const subagentCapacityKey = "runtime.subagent.available_slots";
 /** External concurrency is policy, never evidence of native child qualification. */
 export function getStageFanoutCapacity(context, input) {
@@ -176,6 +178,30 @@ export function memoryStageFanoutDescriptor(context, input) {
     }
     return { schema_id: "dd-flow/work-fanout@2", kind: "work_fanout", scope, stage: input.stage, parent_work_id: root.workId, dispatch: "none", capacity_required: true };
 }
+/** Diagnostic graphs are registered by the Stage handler, never fanout.json. */
+export function diagnosticStageFanoutDescriptor(context, input) {
+    if (!["audit", "analyze", "review"].includes(input.stage))
+        return null;
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = context.db.get("SELECT flow_kind,index_json FROM runs WHERE project_id=? AND id=?", [project.id, input.runId]);
+    if (!run || !isDiagnosticFlow(run.flow_kind))
+        return null;
+    const index = JSON.parse(run.index_json);
+    if (index.current_stage !== input.stage || !index.stage_runs.some(stage => stage.stage === input.stage && stage.status === "running"))
+        return null;
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.manifest.flow_id !== run.flow_kind)
+        throw new AppError("stage_graph_conflict", "Diagnostic graph requires its frozen bundle", 1);
+    const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+    const root = readDescriptorRootWork(context, scope, bundle), graph = readRegisteredDiagnosticGraph(context, scope);
+    const members = stageWorkIds(context, project.id, input.runId, input.stage);
+    if (!graph || graph.parent_work_id !== root.workId || graph.bundle_sha256 !== bundle.sha256 || root.status !== "running"
+        || !members.has(root.workId) || members.size !== Object.keys(graph.work_ids).length + 1
+        || Object.values(graph.work_ids).some(id => !members.has(id)))
+        throw new AppError("stage_graph_conflict", "Diagnostic graph requires its exact registered Work; replay the issued Stage entry if registration was interrupted", 1);
+    return { schema_id: "dd-flow/work-fanout@2", kind: "work_fanout", scope: stageGraphScope(context, project.id, input.runId, input.stage),
+        stage: input.stage, parent_work_id: root.workId, dispatch: "none", capacity_required: true };
+}
 /** Read-only projection for an external orchestrator.  dd-flow keeps the graph authority. */
 export function getVnextFanoutStatus(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
@@ -189,7 +215,8 @@ export function getVnextFanoutStatus(context, input) {
     const bundle = index.execution_bundle ? readFlowRunExecutionBundle(context, { projectRoot, runId: input.runId }) : null;
     const stageRoot = path.join(run.run_root, bundle ? bundle.descriptor.stage(input.stage).directory : vnextStageDirectory(input.stage));
     const memoryDescriptor = memoryStageFanoutDescriptor(context, input);
-    let descriptor = memoryDescriptor ?? readFanoutDescriptor(stageRoot);
+    const diagnosticDescriptor = diagnosticStageFanoutDescriptor(context, input);
+    let descriptor = memoryDescriptor ?? diagnosticDescriptor ?? (bundle && isDiagnosticFlow(bundle.manifest.flow_id) ? null : readFanoutDescriptor(stageRoot));
     // Registration is authoritative even if projection publication was interrupted,
     // or an otherwise review-off stage acquired an aggregate repair graph.
     if (!descriptor && context.db.get("SELECT 1 FROM sqlite_master WHERE name = 'repair_intents'")) {
@@ -218,6 +245,9 @@ export function getVnextFanoutStatus(context, input) {
     // Only SQL-owned memory registration can attest a deliberately empty
     // graph. A mutable fanout.json must never turn missing Work into success.
     let registeredEmpty = false;
+    if (diagnosticDescriptor && !hasWork) {
+        registeredEmpty = Object.keys(readRegisteredDiagnosticGraph(context, { projectId: project.id, runId: input.runId, stage: input.stage }).work_ids).length === 0;
+    }
     if (memoryDescriptor && input.stage === "upgrade" && !hasWork
         && context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.composition_registration' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.stage')='upgrade' AND json_extract(payload_json,'$.scope.attempt')=? AND json_extract(payload_json,'$.scope.cycle')=? AND json_extract(payload_json,'$.scope.parent_work_id')=? LIMIT 1", [project.id, input.runId, currentScope.attempt, currentScope.cycle, descriptor.parent_work_id])) {
         const registered = selectMemoryCompositionRegistration(context, { ...currentScope, stage: "upgrade", parent_work_id: descriptor.parent_work_id });