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

package/dist/services/controller-fanout.js

@@ -0,0 +1,277 @@
+import path from "node:path";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { normalizeNativeChildren, safeNativeFailure } from "../harness-runtime/lib/native-children.mjs";
+import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout, getStageFanoutCapacity, verifiedNativeWorkFailure } from "./vnext-fanout.js";
+import { dispatchVnextPlanReview } from "./vnext-plan-review.js";
+import { resolveExecutionPolicy } from "./execution-policy.js";
+import { lifecycleCommandCompletionInstruction, renderDelegationInstructions, stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { assertWorkLaunchReady, workStartCommand } from "./work-registry.js";
+import { prepareMemoryNativeReviewCopy } from "./memory-native-review-copy.js";
+import { registerMemoryRepairBaselineFromStage, reserveMemoryRepairWriterCopyFromStage, materializeMemoryRepairWriterCopyFromStage, prepareMemoryRepairDispatchFromStage, registerMemorySecondRepairBaselineFromStage, reserveMemorySecondRepairCopyFromStage, materializeMemorySecondRepairCopyFromStage, prepareMemorySecondRepairDispatchFromStage, registerMemoryRepairCurrentViewFromStage, registerMemorySecondRepairCurrentViewFromStage } from "./memory-review-handler.js";
+import { requireProjectByRoot } from "./projects.js";
+import { stageAttempt, stageWorkIds } from "./stage-work-graph.js";
+import { runtimeCommand } from "./runtime-command.js";
+import { promptDeliveryInstruction } from "./prompt-delivery.js";
+import { committedSuccessor, currentStageFinishAuthority } from "./lifecycle-invocations.js";
+import { acceptedChildWork } from "./controller-result-authority.js";
+import { explicitWorkFailure } from "./controller-work-failure.js";
+import { commandOption, parseLifecycleCommand } from "./lifecycle-command.js";
+/** A new transport ID is not progress. Read only the current assignment's
+ * committed transition and its check inputs; never inspect mutable files here. */
+export function controllerSemanticCheckpoint(context, input) {
+    const scopeJson = context.env.DD_FLOW_INVOCATION_SCOPE;
+    const scope = scopeJson ? JSON.parse(scopeJson) : null;
+    const project = scope && context.db.get("SELECT id FROM projects WHERE root=?", [scope.projectRoot]);
+    const attempt = project && scope ? stageAttempt(context, project.id, scope.runId, input.stage) : null;
+    const receipt = (id) => typeof id === "string" && project && scope
+        ? context.db.get("SELECT declaration_id,input_hash,status FROM check_receipts WHERE id=? AND project_id=? AND run_id=?", [id, project.id, scope.runId]) ?? null : null;
+    const stableSet = (values) => [...new Set(values.map(value => JSON.stringify(value)))].sort().map(value => JSON.parse(value));
+    const parsed = input.command ? parseLifecycleCommand(input.command) : null;
+    const operation = parsed && parsed.kind !== "none" ? {
+        operation: parsed.invocation.operation, positional: parsed.invocation.args.positional,
+        options: [...parsed.invocation.args.options].filter(([key]) => !["invocation-id", "hook-event-id", "json", "progress-jsonl", "response-file", "reason"].includes(key))
+            .sort(([a], [b]) => a.localeCompare(b)).map(([key, values]) => [key, key === "retry-check" ? values.map(receipt) : values])
+    } : null;
+    const transitions = scopeJson && input.invocationId ? stableSet(context.db.all("SELECT * FROM lifecycle_invocations WHERE scope_json=? AND status='settled' AND json_extract(outcome_json,'$.successor_invocation_id')=?", [scopeJson, input.invocationId]).flatMap(row => {
+        const prior = parseLifecycleCommand(row.command);
+        if (prior.kind === "none" || commandOption(prior.invocation, "stage") !== input.stage)
+            return [];
+        const outcome = JSON.parse(row.outcome_json ?? "null");
+        if (committedSuccessor(context, row, outcome)?.id !== input.invocationId)
+            return [];
+        const result = outcome.result, error = outcome.error;
+        const references = result?.receipts ?? error?.details?.failures ?? [];
+        return [{ outcome: result?.outcome ?? null, verification: result?.verification?.verdict ?? null,
+                error: error ? { code: error.code, rejection_signature: error.details?.rejection_signature ?? null, input_key: error.details?.input_key ?? null } : null,
+                receipts: stableSet((Array.isArray(references) ? references : []).map(value => receipt(value?.id))) }];
+    })) : [];
+    const memoryChecks = project && scope && input.reviewInputSha256 ? stableSet(context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='memory.correction_checks' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.wave')=? AND json_extract(payload_json,'$.review_input_sha256')=?", [project.id, scope.runId, input.wave ?? 0, input.reviewInputSha256]).map(row => { const value = JSON.parse(row.payload_json); return { corrected_input: value.corrected_input_sha256, completed_correction: value.completed_correction_sha256, receipts: stableSet((value.checks ?? []).map((check) => receipt(check.id))) }; })) : [];
+    return { phase: input.phase, ...(input.wave === undefined ? {} : { wave: input.wave }), attempt, generation: scope?.generation ?? null, operation, transitions, ...(input.reviewInputSha256 ? { memory_checks: memoryChecks } : {}) };
+}
+function semanticCompletionPrompt(stage, completed, command) {
+    const task = stage === "plan-review"
+        ? "Classify the reviewer findings, apply every accepted correction in the current PLAN-REVIEW Work, and write the authoritative review decision."
+        : stage === "code-review"
+            ? "Classify the review findings and write or retain the authoritative review decision."
+            : "Integrate the accepted child results and update the Stage's authoritative verification evidence.";
+    return [
+        `All declared ${stage} child Work has settled (${completed} completed).`,
+        task,
+        `Then invoke this exact currently issued Stage finish command:\n\n${command}\n\nRefresh the authoritative verification evidence first; an earlier rejected or successful nonterminal command only reads its retained outcome.`,
+        "If that command returns either outcome = repair_required with a repair Work ID, or error.details.continuation.kind = repair_required, the repair Work is already registered. End this Turn so the controller can dispatch it. Otherwise follow the command's actual result.",
+        "Do not create speculative repair Work or start a successor Stage."
+    ].join(" ");
+}
+/** Stage entry acknowledges the packet before the controller issues child commands. */
+export function controllerStageEntryPrompt(stage, command) {
+    return [
+        `Start the assigned ${stage} Stage now. Your first tool call must be this exact standalone command:`,
+        command,
+        promptDeliveryInstruction,
+        "If the returned packet has orchestration.kind = work_fanout, this Turn is only Stage entry: acknowledge the packet and end your Turn immediately. The packet describes the whole Stage, but its graph/dispatch/finish instructions belong to later controller continuations. Do not list, start, launch or finish Work, create children, change files, run checks, or finish the Stage in this entry Turn. The controller will inspect the graph and send the next assignment with exact issued commands (or dispatch external workers itself).",
+        "Otherwise perform this Stage's semantic work and stop at its boundary or a declared HITL boundary. Do not start a successor Stage.",
+        stageLifecycleInstruction
+    ].join("\n\n");
+}
+export function controllerStageResumePrompt(packet, resumedPromptPath) {
+    return [
+        `The accepted canonical answer for pause ${packet.pause_id} (${packet.stage}, ${packet.work_id}) is retained at this absolute read-only path: ${JSON.stringify(packet.answer_file)} (sha256 ${packet.answer_sha256}). Do not replace it with a placeholder or ask the user to supply it again. A null pause.answer_path before resume does not mean the answer is missing.`,
+        resumedPromptPath
+            ? `This exact answer was already committed. Do not invoke stage resume again. Read the recovered authoritative continuation at ${JSON.stringify(resumedPromptPath)} and perform its current Stage instructions.`
+            : `Only while this exact pause still awaits its answer, your first tool call must be this exact standalone command. It applies the already accepted bound answer file:\n\n${packet.command}`,
+        ...(packet.resume_source_path ? [`If this pause has already resumed, do not invoke stage resume again. Read the complete recovered result.worker_prompt_markdown in ${JSON.stringify(packet.resume_source_path)} instead, and follow that authoritative continuation. The controller restores this committed packet before dispatch. A different pause requires its own accepted answer.`] : []),
+        `Do not alter the answer. ${promptDeliveryInstruction} Follow the returned packet, then stop at this Stage boundary.`,
+        stageLifecycleInstruction
+    ].join("\n\n");
+}
+/** The shared controller owns this former eval-only Work-graph decision. */
+export async function nextControllerFanout(context, input) {
+    // Tree settlement is not a Work result. Keep these children visible to the
+    // association check, especially when a hook rejected work start before CLI.
+    const children = input.children;
+    const observations = { harness_id: input.harness, parent_session_id: input.sessionId, children };
+    if (children.length) {
+        const observed = observeVnextNativeChildren(context, { ...input, observations });
+        const issues = observed.issues;
+        if (issues.length)
+            throw new AppError("fanout_reconciliation_required", "Native children have unresolved lifecycle ownership", 1, { issues });
+    }
+    let fanout = getVnextFanoutStatus(context, input).orchestration;
+    if (!fanout) {
+        if (input.dispatchFence)
+            throw new AppError("fanout_reconciliation_required", "Observed native failure has no current graph; dispatch stays fenced", 1, { stage: input.stage, run_id: input.runId });
+        return { kind: "none" };
+    }
+    if (fanout.state === "compatibility_required")
+        throw new AppError("stage_graph_compatibility_required", "The retained graph cannot be dispatched by this controller; use the RUN's pinned engine", 1, { stage: input.stage, run_id: input.runId, graph: fanout });
+    if (children.length) {
+        const reconciled = await reconcileVnextFanout(context, { ...input, observations });
+        // A known settled child's Work blocker does not consume an independent
+        // ready branch. It remains running, so this cannot manufacture Stage success.
+        const issues = reconciled.issues.filter(issue => !["child_check_in_progress", "child_capacity_pending"].includes(issue.code)
+            && !(issue.code === "execution_ended_without_work_result" && issue.work_id && input.repairBlockedWorks?.includes(issue.work_id)));
+        if (issues.length)
+            throw new AppError("fanout_reconciliation_required", "Native child outcome requires reconciliation, not replay", 1, { issues });
+        const unsettled = children.filter(child => child.status === "running" || child.status === "unknown");
+        if (unsettled.length) {
+            const project = requireProjectByRoot(context, input.projectRoot);
+            return { kind: "wait", reason: unsettled.every(child => acceptedChildWork(context, { project_id: project.id, run_id: input.runId }, input.harness, input.sessionId, child.session_id)) ? "accepted_work_native_cleanup" : "native_children_unsettled" };
+        }
+        fanout = getVnextFanoutStatus(context, input).orchestration;
+    }
+    if (input.dispatchFence && !fanout.works.failed)
+        throw new AppError("fanout_reconciliation_required", "Observed native failure has no proven failed Work; dispatch stays fenced", 1, { stage: input.stage, run_id: input.runId });
+    if (fanout.state === "dispatch_required") {
+        dispatchVnextPlanReview(context, input);
+        fanout = getVnextFanoutStatus(context, input).orchestration;
+        if (fanout.state === "dispatch_required" || fanout.state === "capacity_required")
+            return { kind: "wait", reason: "qualified_capacity_required" };
+    }
+    const prompt = (action, text, checkpoint) => ({ kind: "prompt", action, prompt: action === "dispatch_work" ? text : `${text}\n\n${lifecycleCommandCompletionInstruction}`, ...(checkpoint ? { checkpoint } : {}), fingerprint: JSON.stringify({ stage: input.stage, action, parent: fanout.parent_work_id, state: fanout.state, graph: fanout.graph_revision, ...(checkpoint ? { semantic: checkpoint } : {}) }) });
+    if (fanout.state === "coordinator_required")
+        return prompt("materialize_graph", `Continue the current ${input.stage} Stage using its authoritative packet. Materialize only its required Work graph, declaring real dependencies at registration. If the packet's CLI command registers the graph, use its returned Work graph unchanged: do not add or alter dependencies after registration. Accepted predecessor Stages already fence their completed producers; do not add cross-stage edges merely to restate input provenance. Do not launch children, finish the Stage, or start a successor. Return after registering the graph; the runtime will dispatch its ready Work.`);
+    if (fanout.works.failed || fanout.works.cancelled) {
+        const projectId = requireProjectByRoot(context, input.projectRoot).id;
+        const members = stageWorkIds(context, projectId, input.runId, input.stage);
+        const failedIds = context.db.all("SELECT work_id FROM works WHERE project_id=? AND run_id=? AND parent_work_id=? AND status='failed' ORDER BY work_id", [projectId, input.runId, fanout.parent_work_id]).filter(work => members.has(work.work_id));
+        const explicit = !input.dispatchFence && !fanout.works.cancelled ? failedIds.map(work => explicitWorkFailure(context, projectId, input.runId, work.work_id)) : [];
+        const failure = explicit.length === failedIds.length && explicit.length ? explicit[0] : null;
+        if (failure && !(input.deferredFailure === failure.work_id && fanout.works.ready.length))
+            return { kind: "failure", failure, ready: fanout.works.ready.length > 0 };
+        if (!failure) {
+            const failures = context.db.all("SELECT work_id,status,result FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ? AND status IN ('failed','cancelled')", [projectId, input.runId, fanout.parent_work_id]).filter(work => members.has(work.work_id)).map(work => {
+                let receipt = {};
+                try {
+                    const value = work.result ? JSON.parse(work.result) : null;
+                    if (value && typeof value === "object" && !Array.isArray(value))
+                        receipt = value;
+                }
+                catch { /* Missing legacy metadata is unknown. */ }
+                const providerError = safeNativeFailure(receipt.provider_error);
+                const nativeBinding = verifiedNativeWorkFailure(context, { projectRoot: input.projectRoot, runId: input.runId, stage: input.stage, parentSessionId: input.sessionId, parentWorkId: fanout.parent_work_id, workId: work.work_id, receipt });
+                return { work_id: work.work_id, status: work.status, ...(providerError ? { provider_error: providerError } : {}),
+                    ...(nativeBinding ? { native_binding: nativeBinding } : {}),
+                    ...Object.fromEntries(["terminal_turn_id", "terminal_observed_at"].filter(key => typeof receipt[key] === "string" && receipt[key].length <= 256).map(key => [key, receipt[key]])) };
+            });
+            throw new AppError("fanout_child_failed", "A child Work failed or was cancelled; no retry authority has been issued", 1, { stage: input.stage, run_id: input.runId, parent_work_id: fanout.parent_work_id, failed: fanout.works.failed, cancelled: fanout.works.cancelled, failures, effect: "unknown" });
+        }
+    }
+    if (fanout.works.ready.length) {
+        const choices = fanout.works.ready.map(work => {
+            const payload = context.db.get("SELECT payload_json FROM works WHERE work_id = ?", [work.work_id])?.payload_json;
+            const override = payload ? JSON.parse(payload).execution_override : undefined;
+            return { work, resolved: resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy: input.policy, profiles: input.profiles, stage: input.stage, ...(override ? { work: override } : {}) }) };
+        });
+        const prepareRepair = (work) => {
+            const row = context.db.get("SELECT payload_json,result_schema FROM works WHERE work_id=?", [work.work_id]);
+            const payload = JSON.parse(row?.payload_json ?? "null");
+            if (payload?.kind !== "memory-repair" || row?.result_schema !== "dd-flow/memory-repair-work-result@1")
+                return null;
+            const scope = { projectRoot: input.projectRoot, runId: input.runId, workId: work.work_id };
+            const second = payload.memory_repair?.wave === 2;
+            if (!second && payload.memory_repair?.wave !== 1)
+                throw new AppError("fanout_contract_invalid", "Memory repair wave is invalid", 1);
+            const registerBaseline = second ? registerMemorySecondRepairBaselineFromStage : registerMemoryRepairBaselineFromStage;
+            try {
+                registerBaseline(context, scope);
+            }
+            catch (error) {
+                const missing = error instanceof AppError && (second
+                    ? error.code === "memory_second_repair_source_invalid" && error.details.reason === "registered_second_current_view_required"
+                    : error.code === "memory_review_handler_invalid" && error.details.reason === "current_view_registration_required");
+                if (!missing)
+                    throw error;
+                (second ? registerMemorySecondRepairCurrentViewFromStage : registerMemoryRepairCurrentViewFromStage)(context, scope);
+                registerBaseline(context, scope);
+            }
+            (second ? reserveMemorySecondRepairCopyFromStage : reserveMemoryRepairWriterCopyFromStage)(context, scope);
+            (second ? materializeMemorySecondRepairCopyFromStage : materializeMemoryRepairWriterCopyFromStage)(context, scope);
+            return (second ? prepareMemorySecondRepairDispatchFromStage : prepareMemoryRepairDispatchFromStage)(context, scope);
+        };
+        const external = choices.filter(choice => choice.resolved.delegation.mode === "external");
+        if (external.length) {
+            const maximum = Math.min(...external.map(choice => choice.resolved.delegation.max_parallel ?? 1));
+            const selected = external.slice(0, maximum).map(choice => choice.work);
+            for (const work of selected)
+                prepareRepair(work);
+            return { kind: "external", works: selected };
+        }
+        const capacity = getStageFanoutCapacity(context, { ...input, nativeOnly: true }).available_slots;
+        if (typeof capacity !== "number" || !Number.isInteger(capacity) || capacity < 1)
+            return { kind: "wait", reason: "qualified_capacity_required" };
+        const wave = choices.slice(0, capacity).map(choice => {
+            const work = choice.work;
+            const row = context.db.get("SELECT payload_json,result_schema FROM works WHERE work_id=?", [work.work_id]);
+            const payload = JSON.parse(row?.payload_json ?? "null");
+            if (payload?.kind === "memory-review" && row?.result_schema === "dd-flow/memory-review-work-result@1"
+                || payload?.kind === "interactive-review" && row?.result_schema === "dd-flow/interactive-work-result@1") {
+                const copy = prepareMemoryNativeReviewCopy(context, work.work_id, true);
+                return { ...work, start_command: `cd '${copy.root.replaceAll("'", "'\\''")}' && ${workStartCommand(context, assertWorkLaunchReady(context, work.work_id))}` };
+            }
+            const packet = prepareRepair(work);
+            const command = workStartCommand(context, assertWorkLaunchReady(context, work.work_id));
+            if (!packet)
+                return { ...work, start_command: command };
+            // Ordinary literal shell grammar, not an invented native spawn CWD field.
+            const quotedRoot = "'" + packet.copy_root.replaceAll("'", "'\\''") + "'";
+            return { ...work, start_command: `cd ${quotedRoot} && ${command}` };
+        });
+        for (const work of wave)
+            if (!work.work_id || !work.start_command)
+                throw new AppError("fanout_contract_invalid", "Ready Work omits its trusted start command", 1);
+        const totalWorks = fanout.works.created + fanout.works.running + fanout.works.completed + fanout.works.failed + fanout.works.cancelled;
+        return { ...prompt("dispatch_work", renderDelegationInstructions({ harness: input.harness, stage: input.stage, capacity, works: wave, totalWorks, remainingWorks: fanout.works.created - wave.length })), work_ids: wave.map(work => work.work_id) };
+    }
+    if (fanout.works.running)
+        return { kind: "wait", reason: "work_receipts_pending" };
+    if (fanout.works.created)
+        throw new AppError("fanout_graph_stalled", "Created Work has no ready or running dependency path", 1);
+    if (input.stage === "review") {
+        const projectId = requireProjectByRoot(context, input.projectRoot).id;
+        const run = context.db.get("SELECT flow_kind,run_root,run_dir FROM runs WHERE project_id=? AND id=?", [projectId, input.runId]);
+        if (run?.flow_kind === "mb-init" || run?.flow_kind === "mb-upgrade") {
+            const attempt = stageAttempt(context, projectId, input.runId, "review");
+            const repair = context.db.get(`SELECT CASE event_type WHEN 'memory.second_repair_registration' THEN 2 ELSE 1 END AS wave,json_extract(payload_json,'$.scope.input_sha256') AS input_sha256
+        FROM audit_events WHERE project_id=? AND event_type IN ('memory.repair_registration','memory.second_repair_registration')
+        AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=?
+        AND json_extract(payload_json,'$.scope.parent_work_id')=? ORDER BY wave DESC LIMIT 1`, [projectId, input.runId, attempt, fanout.parent_work_id]);
+            if (repair && !context.db.get(`SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.corrected_review_registration'
+        AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=?
+        AND json_extract(payload_json,'$.scope.parent_work_id')=? AND json_extract(payload_json,'$.wave')=?`, [projectId, input.runId, attempt, fanout.parent_work_id, repair.wave])) {
+                const args = ["--run", input.runId, "--project-root", input.projectRoot, "--wave", String(repair.wave), "--json"];
+                return prompt("semantic_completion", `Correction wave ${repair.wave} Work has settled. Before Stage finish, run ${runtimeCommand(context, ["memory", "corrections", "checks", ...args])}, then ${runtimeCommand(context, ["memory", "review", "selective-register", ...args])}. Read both complete responses, then end this Turn so the controller can dispatch the independent selective reviewers. Do not finish the Stage or treat repair Work completion as independent acceptance.`, controllerSemanticCheckpoint(context, { stage: input.stage, phase: "memory_correction_checks_register", wave: repair.wave, reviewInputSha256: repair.input_sha256 }));
+            }
+            const wave = repair?.wave ?? 0;
+            const runHome = run.run_root ?? run.run_dir;
+            if (!runHome || !path.isAbsolute(runHome))
+                throw new AppError("runtime_missing", "Memory review collection requires its retained absolute RUN home", 1);
+            const collectionArgs = ["--run", input.runId, "--project-root", input.projectRoot, ...(wave ? ["--wave", String(wave)] : []),
+                "--json", "--progress-jsonl", "--response-file", path.join(runHome, `memory-review-collection-wave-${wave}.json`)];
+            const collect = runtimeCommand(context, ["memory", "review", wave ? "selective-collect" : "collect", ...collectionArgs]);
+            return prompt("semantic_completion", [
+                `All declared memory review Work has settled. First run ${collect}. Read the complete canonical collection from its response_file; do not decide acceptance from a truncated preview or reviewer counts.`,
+                "Only if the collection outcome is accepted (projection.outcome = accepted), integrate its accepted results into the original Stage proposal and invoke the exact Stage finish command from the authoritative packet.",
+                wave < 2
+                    ? `If the outcome is needs_repair, use the returned canonical findings and correction_plan_binding to author substantive repair tasks with exact owned write_paths. Register that plan with the packet's issued memory corrections register command for wave ${wave + 1}, then end this Turn so the controller can dispatch it. Do not invoke Stage finish before corrections, checks and independent selective review complete.`
+                    : "If the outcome is needs_repair or blocked, the two correction waves are exhausted. Use the issued pause command for the concrete unresolved blocker; do not mark it accepted.",
+                "For blocked collection, use the issued pause command. Do not calculate finding hashes, merge or drop findings, edit project files in the coordinator, create speculative Work or start a successor Stage."
+            ].join("\n\n"), controllerSemanticCheckpoint(context, { stage: input.stage, phase: "memory_collection", wave, command: collect }));
+        }
+    }
+    const finish = currentStageFinishAuthority(context, input.stage);
+    if (!finish)
+        throw new AppError("controller_finish_authority_missing", "Settled child Work has no current Stage finish authority", 1, { stage: input.stage, reconciliation_required: true });
+    if (finish.status !== "issued" || !finish.command)
+        throw new AppError("controller_finish_authority_pending", "Observe the original Stage finish before another productive dispatch", 1, { stage: input.stage, invocation_id: finish.id, status: finish.status, reconciliation_required: true });
+    return { ...prompt("semantic_completion", semanticCompletionPrompt(input.stage, fanout.works.completed, finish.command), controllerSemanticCheckpoint(context, { stage: input.stage, phase: "stage_finish", command: finish.command, invocationId: finish.id })), authority: { id: finish.id, status: finish.status } };
+}
+/** Shared pinned runtime normalization; preserve structured errors at the TS boundary. */
+export function controllerNativeChildren(receipt, rootSessionId) {
+    try {
+        return normalizeNativeChildren(receipt, rootSessionId);
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        throw Object.assign(new AppError(record.code, record.message, record.exitCode, record.details), record);
+    }
+}

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

@@ -0,0 +1,45 @@
+import { Worker } from "node:worker_threads";
+import { AppError } from "../shared/errors.js";
+/** Keep synchronous custody/copy work off the controller's lease event loop.
+ * The thread remains inside its registered process; OS-level stop owns both.
+ * Do not resolve until exit, including after cancellation or a typed failure. */
+export function runControllerMemoryTask(context, task, signal) {
+    const aborted = () => new AppError("controller_memory_task_aborted", "Memory operation was cancelled; reconcile its retained effects", 1, { effect: "unknown" });
+    if (signal?.aborted)
+        return Promise.reject(aborted());
+    return new Promise((resolve, reject) => {
+        // Both source tests and installed runtimes use the package's compiled worker.
+        const worker = new Worker(new URL("../../dist/services/controller-memory-worker.js", import.meta.url), {
+            workerData: { task, env: { ...context.env, DD_FLOW_HOME: context.ddFlowHome } }
+        });
+        let reply, failure;
+        const abort = () => worker.postMessage({ abort: true });
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        worker.on("message", (value) => {
+            const invalid = value && typeof value === "object" && ("error" in value
+                ? !value.error || typeof value.error.code !== "string" || typeof value.error.message !== "string" || !Number.isInteger(value.error.exitCode)
+                    || !value.error.details || typeof value.error.details !== "object" || Array.isArray(value.error.details) || "result" in value
+                : !("result" in value) || !value.result || typeof value.result !== "object" || Array.isArray(value.result));
+            if (reply || !value || typeof value !== "object" || invalid) {
+                failure = new AppError("controller_memory_task_invalid", "Memory worker returned an invalid terminal reply", 1, { effect: "unknown" });
+            }
+            else
+                reply = value;
+        });
+        worker.once("error", error => { failure = error; });
+        worker.once("exit", code => {
+            signal?.removeEventListener("abort", abort);
+            if (failure)
+                return reject(failure);
+            if (reply && "error" in reply)
+                return reject(new AppError(reply.error.code, reply.error.message, reply.error.exitCode, reply.error.details));
+            if (signal?.aborted)
+                return reject(aborted());
+            if (code !== 0 || !reply || !("result" in reply))
+                return reject(new AppError("controller_memory_task_failed", "Memory worker exited without its terminal result", 1, { exit_code: code, effect: "unknown" }));
+            resolve(reply.result);
+        });
+    });
+}

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

@@ -0,0 +1,51 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { createContext } from "../runtime/context.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { nextControllerFanout } from "./controller-fanout.js";
+import { launchExternalWork } from "./external-work-launch.js";
+import { requireProjectByRoot } from "./projects.js";
+import { assertControllerLeaseAllowed } from "./run-controller-process.js";
+import { assertManagedProcessLease } from "./managed-processes.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.js";
+if (!parentPort)
+    throw new AppError("controller_memory_task_invalid", "Memory worker requires its controller thread", 1);
+const port = parentPort, cancellation = new AbortController();
+port.on("message", message => { if (message?.abort === true)
+    cancellation.abort(); });
+const { task, env } = workerData;
+let context;
+let reply;
+try {
+    context = createContext(env, "prepared_existing");
+    const project = requireProjectByRoot(context, task.input.projectRoot);
+    const run = context.db.get("SELECT flow_kind,index_json FROM runs WHERE project_id=? AND id=?", [project.id, task.input.runId]);
+    const delivery = run && isDeliveryFlow(run.flow_kind) && JSON.parse(run.index_json).execution_bundle?.flow_id === run.flow_kind;
+    if (!run || !["mb-init", "mb-upgrade", "mb-fix", "interactive"].includes(run.flow_kind) && !isSourceSnapshotFlow(run.flow_kind) && !delivery)
+        throw new AppError("controller_memory_task_invalid", "Worker requires the selected memory, interactive, source-snapshot or bound delivery RUN", 1, { effect: "no_effect" });
+    if (task.operation === "external") {
+        const work = context.db.get("SELECT project_id,run_id FROM works WHERE work_id=?", [task.input.workId]);
+        if (!work || work.project_id !== project.id || work.run_id !== task.input.runId)
+            throw new AppError("controller_memory_task_invalid", "External Work belongs to another RUN", 1, { effect: "no_effect" });
+    }
+    const owner = env.DD_FLOW_CONTROLLER_TOKEN ? context.db.get("SELECT * FROM run_controllers WHERE project_id=? AND run_id=? AND owner_token=?", [project.id, task.input.runId, env.DD_FLOW_CONTROLLER_TOKEN]) : undefined;
+    if (!owner)
+        throw new AppError("controller_owner_mismatch", "Memory task lacks its managed controller owner", 1, { effect: "no_effect" });
+    assertControllerLeaseAllowed(context, owner);
+    assertManagedProcessLease(context, { id: owner.process_id, leaseToken: owner.process_lease_token, pid: process.pid });
+    cancellation.signal.throwIfAborted();
+    if (task.operation === "fanout")
+        reply = { result: await nextControllerFanout(context, task.input) };
+    else if (task.operation === "external")
+        reply = { result: await launchExternalWork(context, { ...task.input, signal: cancellation.signal }) };
+    else
+        throw new AppError("controller_memory_task_invalid", "Unknown memory worker operation", 1, { effect: "no_effect" });
+}
+catch (error) {
+    reply = { error: errorRecord(error) };
+}
+finally {
+    context?.db.close?.();
+}
+port.postMessage(reply);
+port.close();

package/dist/services/controller-result-authority.js

@@ -0,0 +1,127 @@
+import { nextAttempt } from "./runs.js";
+import { stageAttempt, stageCycle, stageWorkIds } from "./stage-work-graph.js";
+import { storageSessionId } from "./session-identity.js";
+import { isObservationLoss } from "../harness-runtime/lib/operation-errors.mjs";
+import { terminalProviderRecovery } from "../harness-runtime/lib/provider-overload-policy.mjs";
+import { getVnextFanoutStatus } from "./vnext-fanout.js";
+import { normalizeNativeChildren, nativeTreeReadiness } from "../harness-runtime/lib/native-children.mjs";
+import { failureDecisionReady } from "./controller-work-failure.js";
+/** Disappearance from a truncated child list is not retirement evidence. */
+export function acceptedChildrenRetired(expected, receipt, sessionId, operationId) {
+    const children = normalizeNativeChildren(receipt, sessionId);
+    const settledTree = nativeTreeReadiness(receipt, { sessionId, operationId }) === "ready"
+        && Array.isArray(receipt.tree_session_ids) ? receipt.tree_session_ids : [];
+    return expected.every(id => {
+        const child = children.find(item => item.session_id === id);
+        return Boolean(child && ["completed", "failed", "cancelled"].includes(child.status)) || settledTree.includes(id);
+    });
+}
+/** Typed transport/provider failures only; integrity/ownership errors never become notes. */
+export function lateNativeFailure(error, sessionId) {
+    const value = error;
+    return isObservationLoss(error) || isObservationLoss(value?.details?.cause)
+        || value?.code === "settlement_recovery_required" || terminalProviderRecovery(error, sessionId);
+}
+/** A technical pause is an engine-recorded boundary, never an operator label. */
+export function technicalDependencyControl(context, projectId, runId, controlId) {
+    if (!context.db.get("SELECT 1 FROM sqlite_schema WHERE name='run_controller_events'"))
+        return false;
+    return Boolean(context.db.get(`SELECT 1 FROM run_controller_events e JOIN run_controllers c ON c.controller_id=e.controller_id JOIN run_controls rc ON rc.project_id=c.project_id AND rc.run_id=c.run_id WHERE c.project_id=? AND c.run_id=? AND rc.control_id=? AND rc.action='pause' AND e.event_type='technical_dependency_paused' AND json_extract(e.data_json,'$.control_id')=rc.control_id AND json_extract(e.data_json,'$.schema_id')='dd-flow/controller-dependency@1'`, [projectId, runId, controlId]));
+}
+/** A technical pause may be resumed automatically only for its own accepted Work.
+ * This is a read-only predicate and is rechecked under the resume transaction. */
+export function acceptedTechnicalWorkControl(context, row, controlId) {
+    try {
+        const control = context.db.get("SELECT request_id,recovery_id,status,action FROM run_controls WHERE project_id=? AND run_id=? AND control_id=?", [row.project_id, row.run_id, controlId]);
+        if (!control || control.action !== "pause" || control.status !== "settled")
+            return false;
+        const guard = context.db.get("SELECT recovery_id,generation,status,capture_path FROM run_recovery_guards WHERE project_id=? AND run_id=? ORDER BY generation DESC LIMIT 1", [row.project_id, row.run_id]);
+        if (!guard || guard.recovery_id !== control.recovery_id || guard.status !== "sealed" || !guard.capture_path || guard.generation <= row.generation)
+            return false;
+        const events = context.db.all("SELECT data_json FROM run_controller_events WHERE controller_id=? AND event_type='technical_dependency_paused' AND json_extract(data_json,'$.control_id')=?", [row.controller_id, controlId]).map(item => JSON.parse(item.data_json));
+        const state = JSON.parse(row.state_json), session = state.current_session === null ? null : state.sessions?.[state.current_session];
+        if (!session?.id || !session.owner?.owner_id || !events.length || events.some(event => event.schema_id !== "dd-flow/controller-dependency@1"
+            || event.request_id !== control.request_id || event.generation !== row.generation || event.state_dir !== session.state_dir
+            || event.source_operation_id !== undefined && (typeof event.source_operation_id !== "string" || !event.source_operation_id)))
+            return false;
+        // Concurrent observers may add unbound notes to the same immutable control.
+        // They do not revoke one exact accepted source; conflicting sources still do.
+        const sources = [...new Set(events.flatMap(event => event.source_operation_id ? [event.source_operation_id] : []))];
+        if (sources.length !== 1)
+            return false;
+        const op = context.db.get("SELECT generation,status,input_json FROM run_controller_operations WHERE controller_id=? AND operation_id=?", [row.controller_id, sources[0]]);
+        if (!op || op.generation !== row.generation || !["outcome_unknown", "completed"].includes(op.status))
+            return false;
+        const input = JSON.parse(op.input_json), expected = input.obligation;
+        if (input.owner !== session.owner.owner_id || input.state_dir !== session.state_dir || !Array.isArray(input.args) || input.args[0] !== "session" || input.args[1] !== "prompt" || input.args.indexOf("--session-id") < 0 || input.args[input.args.indexOf("--session-id") + 1] !== session.id || !expected || expected.action !== "work" || expected.stage !== state.stage || expected.generation !== row.generation || !Array.isArray(expected.work_ids) || !expected.work_ids.length || !Array.isArray(expected.work_session_ids))
+            return false;
+        const run = context.db.get("SELECT status,index_json FROM runs WHERE project_id=? AND id=?", [row.project_id, row.run_id]);
+        const stage = run && JSON.parse(run.index_json).stage_runs.find(item => item.stage === expected.stage && (item.attempt ?? "try-001") === expected.attempt);
+        if (!run || !["running", "paused"].includes(run.status) || stage?.status !== "running" || !controllerObligationAccepted(context, row, expected))
+            return false;
+        const stageWorks = stageWorkIds(context, row.project_id, row.run_id, expected.stage);
+        return expected.work_ids.every(id => stageWorks.has(id) && Boolean(context.db.get("SELECT 1 FROM work_sessions WHERE work_id=? AND status='completed'", [id])))
+            && expected.work_session_ids.every(id => Boolean(context.db.get(`SELECT 1 FROM work_sessions WHERE id=? AND status='completed' AND work_id IN (${expected.work_ids.map(() => "?").join(",")})`, [id, ...expected.work_ids])));
+    }
+    catch {
+        return false;
+    }
+}
+/** Persist this snapshot with the exact dispatch, never infer success from one arbitrary Work. */
+export function controllerObligation(context, row, stage, action, assignedWorkIds) {
+    const ids = [...stageWorkIds(context, row.project_id, row.run_id, stage)];
+    const works = ids.length ? context.db.all("SELECT work_id,status,parent_work_id FROM works WHERE project_id=? AND run_id=?", [row.project_id, row.run_id]).filter(work => ids.includes(work.work_id)) : [];
+    const targets = action === "work" ? works.filter(work => work.parent_work_id && ["created", "running"].includes(work.status) && (!assignedWorkIds || assignedWorkIds.includes(work.work_id))).map(work => work.work_id) : [];
+    const sessions = targets.length ? context.db.all("SELECT ws.id,ws.work_id FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id WHERE w.project_id=? AND w.run_id=? AND ws.status='running'", [row.project_id, row.run_id]).filter(session => targets.includes(session.work_id)).map(session => session.id) : [];
+    const run = context.db.get("SELECT index_json,project_root FROM runs WHERE project_id=? AND id=?", [row.project_id, row.run_id]);
+    const previous = run ? JSON.parse(run.index_json).stage_runs.find(item => item.stage === stage) : undefined;
+    return { stage, attempt: action === "entry" ? nextAttempt(previous) : stageAttempt(context, row.project_id, row.run_id, stage), cycle: stageCycle(context, row.project_id, row.run_id, stage), action, work_ids: targets, work_session_ids: sessions, generation: row.generation, ...(action === "resume" && previous?.pause ? { pause_id: previous.pause.id } : {}), ...(action === "graph" ? { graph_before: ids.sort() } : {}) };
+}
+export function controllerObligationAccepted(context, row, expected) {
+    if (expected.generation !== row.generation)
+        return false;
+    const run = context.db.get("SELECT index_json,project_root FROM runs WHERE project_id=? AND id=?", [row.project_id, row.run_id]);
+    if (!run)
+        return false;
+    const stages = JSON.parse(run.index_json).stage_runs;
+    const stage = [...stages].reverse().find(item => item.stage === expected.stage && (item.attempt ?? "try-001") === expected.attempt);
+    if (!stage || stageCycle(context, row.project_id, row.run_id, expected.stage) !== expected.cycle)
+        return false;
+    if (expected.action === "failure_resolution")
+        return Boolean(expected.failure_resolution && failureDecisionReady(expected.failure_resolution));
+    if (["done", "skipped"].includes(stage.status))
+        return true;
+    if (expected.action === "resume")
+        return Boolean(expected.pause_id && context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_resumed' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? AND json_extract(payload_json,'$.pause_id')=?", [row.project_id, row.run_id, expected.stage, expected.pause_id]));
+    if (expected.action === "entry") {
+        // Entry-only is a boundary for fanout stages. A non-fanout entry Turn
+        // also owes semantic work: merely starting SPECIFY is not its result.
+        if (stage.status === "paused" && stage.pause)
+            return Boolean(context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND work_id=? AND status='paused'", [row.project_id, row.run_id, stage.pause.work_id]));
+        if (stage.status !== "running")
+            return false;
+        try {
+            return Boolean(getVnextFanoutStatus(context, { projectRoot: run.project_root, runId: row.run_id, stage: expected.stage }).orchestration);
+        }
+        catch {
+            return false;
+        }
+    }
+    if (expected.action === "graph") {
+        const current = [...stageWorkIds(context, row.project_id, row.run_id, expected.stage)];
+        return Array.isArray(expected.graph_before) && current.length > expected.graph_before.length && expected.graph_before.every(id => current.includes(id));
+    }
+    if (expected.action !== "work" || !expected.work_ids.length)
+        return false;
+    return expected.work_ids.every(id => context.db.get("SELECT status FROM works WHERE project_id=? AND run_id=? AND work_id=?", [row.project_id, row.run_id, id])?.status === "completed")
+        && expected.work_session_ids.every(id => context.db.get("SELECT status FROM work_sessions WHERE id=?", [id])?.status === "completed");
+}
+/** A native failure cannot revoke an accepted result; unknown association is not success. */
+export function acceptedChildWork(context, row, harness, parent, child) {
+    const links = context.db.all(`SELECT ws.work_id,ws.status,w.status AS work_status FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id JOIN sessions s ON s.project_id=w.project_id AND s.session_id=ws.session_id WHERE w.project_id=? AND w.run_id=? AND ws.session_id=? AND s.parent_session_id=? ORDER BY ws.created_at DESC,ws.rowid DESC`, [row.project_id, row.run_id, storageSessionId({ harness_id: harness, session_id: child }), storageSessionId({ harness_id: harness, session_id: parent })]);
+    const current = new Map();
+    for (const link of links)
+        if (!current.has(link.work_id))
+            current.set(link.work_id, link);
+    return current.size > 0 && [...current.values()].every(link => link.status === "completed" && link.work_status === "completed");
+}