@deksden-com/dd-flow-cli 0.9.0-beta.137 → 0.9.0-beta.139

package/dist/services/controller-child-capacity.js

@@ -0,0 +1,13 @@
+/** Only a proven new successful terminal Turn closes a child's retry episode. */
+export function closeSuccessfulChildCapacity(state, children, parentId) {
+    const closed = [];
+    for (const child of children) {
+        const retained = state.child_capacity?.[child.session_id];
+        if (!retained || child.parent_session_id !== parentId || child.provenance === "parent_mismatch"
+            || child.status !== "completed" || !child.terminal_turn_id || child.terminal_turn_id === retained.turn_id)
+            continue;
+        delete state.child_capacity[child.session_id];
+        closed.push(child.session_id);
+    }
+    return closed;
+}

package/dist/services/controller-child-observer.js

@@ -12,6 +12,12 @@ export function retainedChildObserver(input) {
         const provider_error = safeNativeFailure(child.provider_error);
         return { session_id: child.session_id, parent_session_id: child.parent_session_id, status: "failed", source: child.source, terminal_turn_id: child.terminal_turn_id,
             ...(typeof child.terminal_observed_at === "string" && Number.isFinite(Date.parse(child.terminal_observed_at)) ? { terminal_observed_at: child.terminal_observed_at } : {}),
+            ...(child.native_source ? { native_source: child.native_source } : {}),
+            ...(child.native_turn_items ? { native_turn_items: {
+                    ...(typeof child.native_turn_items.observed === "boolean" ? { observed: child.native_turn_items.observed } : {}),
+                    ...(typeof child.native_turn_items.possible_effects === "boolean" ? { possible_effects: child.native_turn_items.possible_effects } : {}),
+                    ...(typeof child.native_turn_items.pending === "boolean" ? { pending: child.native_turn_items.pending } : {})
+                } } : {}),
             ...(provider_error ? { provider_error } : {}) };
     };
     const accept = (children) => {
@@ -26,6 +32,8 @@ export function retainedChildObserver(input) {
             if (sameScope(observation.scope)) {
                 if (Array.isArray(observation.children))
                     accept(observation.children);
+                for (const key of observation.resolved ?? [])
+                    retained.delete(key);
                 if (Object.hasOwn(observation, "gap"))
                     gap = observation.gap ?? null;
             }
@@ -35,23 +43,31 @@ export function retainedChildObserver(input) {
             return;
         input.assertOwner();
         const failed = children.filter(child => child.parent_session_id === input.scope.root_session_id && child.status === "failed" && child.terminal_turn_id && !retained.has(`${child.session_id}:${child.terminal_turn_id}`)).map(normalized);
-        if (!failed.length && !gap)
+        // This is an authoritative current native snapshot. Older failed Turns
+        // remain in the journal/episode history, not in the current-outcome fence.
+        const resolved = [...retained].filter(([, old]) => children.some(child => child.parent_session_id === input.scope.root_session_id
+            && child.provenance !== "parent_mismatch" && child.session_id === old.session_id && ["completed", "failed"].includes(child.status)
+            && child.terminal_turn_id && child.terminal_turn_id !== old.terminal_turn_id)).map(([key]) => key);
+        if (!failed.length && !resolved.length && !gap)
             return;
         const fd = fs.openSync(input.file, "a", 0o600);
         try {
-            fs.writeSync(fd, `${JSON.stringify({ scope: input.scope, children: failed, gap: null })}\n`);
+            fs.writeSync(fd, `${JSON.stringify({ scope: input.scope, children: failed, ...(resolved.length ? { resolved } : {}), gap: null })}\n`);
             fs.fsyncSync(fd);
         }
         finally {
             fs.closeSync(fd);
         }
         accept(failed);
+        for (const key of resolved)
+            retained.delete(key);
         gap = null;
     };
     return {
         failed: () => [...retained.values()],
         gap: () => gap,
         drain: () => pending ?? Promise.resolve(),
+        observeSettledChildren: complete,
         completePostTurn(receipt) {
             const evidence = receipt.evidence;
             const tree = evidence?.subagents;

package/dist/services/controller-execution.js

@@ -0,0 +1,88 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { resolveExecutionPolicy, resolveStageTransition, stageExecutionCwd } from "./execution-policy.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+/** Adapt generic routing to shared fanout APIs, not to SDLC settings. No alias,
+ * operator file, merge policy or project default participates in this selection.
+ */
+export function genericControllerRouting(execution) {
+    if (!(execution instanceof FrozenGenericExecution) || execution.settings.execution !== "managed") {
+        throw new AppError("controller_execution_invalid", "Managed controller requires managed frozen execution", 1, { effect: "no_effect" });
+    }
+    const snapshot = execution.snapshot();
+    const profiles = Object.fromEntries(snapshot.profiles.map(value => [value.id, structuredClone(value.profile)]));
+    const delegation = { mode: execution.settings.delegation.mode,
+        ...(execution.settings.delegation.mode === "external" ? { max_parallel: execution.settings.delegation.max_parallel } : {}) };
+    const policy = { agent_profile_id: execution.settings.root_profile, delegation,
+        stage_overrides: Object.fromEntries(Object.entries(execution.settings.stage_profiles).map(([stage, id]) => [stage, { agent_profile_id: id }])) };
+    for (const profile of Object.values(profiles))
+        Object.freeze(profile);
+    Object.freeze(profiles);
+    for (const override of Object.values(policy.stage_overrides))
+        Object.freeze(override);
+    Object.freeze(policy.stage_overrides);
+    Object.freeze(delegation);
+    Object.freeze(policy);
+    return {
+        kind: "descriptor", policy, profiles, mergeMode: null,
+        transition(stage, fromStage, _currentRun) {
+            const selected = execution.stage(stage);
+            if (fromStage)
+                execution.stage(fromStage);
+            return { ...resolveExecutionPolicy({ ddFlowHome: "", policy, profiles, stage }), session_mode: selected.session_mode };
+        },
+        cwd(stage, _mergeTargetWorkspace, _currentRun) { execution.stage(stage); return path.resolve(snapshot.scope.workspace); }
+    };
+}
+/** Restore execution from RUN authority, never from a generic manifest copy.
+ * Legacy SDLC manifests retain their original settings and routing behavior.
+ */
+export function selectControllerExecution(context, run, manifest) {
+    if (manifest?.schema_id === "dd-flow/run-controller-manifest@2" || ["mb-init", "mb-upgrade"].includes(run.flow_kind)) {
+        const bundle = readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: run.id });
+        if (!bundle || bundle.descriptor.descriptor.id !== run.flow_kind || bundle.descriptor.descriptor.id === "sdlc")
+            throw new AppError("controller_execution_invalid", "Generic controller requires its retained non-SDLC bundle", 1);
+        const binding = { bundle_sha256: bundle.sha256, descriptor_sha256: bundle.descriptor.sha256, execution_sha256: bundle.execution.sha256 };
+        if (manifest && (manifest.schema_id !== "dd-flow/run-controller-manifest@2" || manifest.execution_profile !== undefined
+            || !manifest.execution_binding || Object.keys(manifest.execution_binding).length !== 3
+            || Object.entries(binding).some(([key, value]) => manifest.execution_binding[key] !== value)
+            || manifest.request?.project_root !== run.project_root || manifest.request?.run_id !== run.id)) {
+            throw new AppError("controller_execution_invalid", "Controller execution binding differs from retained RUN authority", 1);
+        }
+        return { ...genericControllerRouting(bundle.execution), bundle, binding, legacy: undefined };
+    }
+    const index = JSON.parse(run.index_json);
+    const legacy = manifest ? manifest.execution_profile : index.execution_profile;
+    if (!legacy?.settings?.execution || !legacy.agent_profiles)
+        throw new AppError("execution_profile_not_frozen", "Managed launch requires the RUN's frozen execution profiles", 1);
+    const policy = legacy.settings.execution, profiles = legacy.agent_profiles;
+    const bundle = index.execution_bundle ? readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: run.id }) : undefined;
+    if (index.execution_bundle && (!bundle || bundle.descriptor.descriptor.id !== "sdlc"))
+        throw new AppError("controller_execution_invalid", "SDLC controller lost its retained bundle authority", 1);
+    if (bundle) {
+        if (legacy.settings.stage_session_mode !== bundle.execution.settings.stage_session_mode)
+            throw new AppError("controller_execution_invalid", "SDLC session policy differs from its retained execution", 1);
+        for (const stage of bundle.descriptor.descriptor.stages) {
+            const selected = resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy, profiles, stage: stage.id });
+            const expected = bundle.execution.work(stage.id, selected.worker.id);
+            if (hybridDigest(selected.coordinator) !== hybridDigest(expected.coordinator) || hybridDigest(selected.worker) !== hybridDigest(expected.worker)
+                || selected.delegation.mode !== expected.delegation.mode
+                || selected.delegation.mode === "external" && selected.delegation.max_parallel !== expected.delegation.max_parallel) {
+                throw new AppError("controller_execution_invalid", "SDLC routing differs from its retained execution", 1, { stage: stage.id });
+            }
+        }
+    }
+    return {
+        kind: "sdlc", policy, profiles, bundle: bundle ?? undefined, binding: undefined, legacy,
+        mergeMode: legacy.settings.merge_mode,
+        transition(stage, fromStage, currentRun = run) {
+            return resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy, profiles, ...(fromStage ? { fromStage } : {}), stage,
+                projectRoot: currentRun.project_root, workspaceRoot: currentRun.workspace_root, stageSessionMode: legacy.settings.stage_session_mode, mergeMode: legacy.settings.merge_mode });
+        },
+        cwd(stage, mergeTargetWorkspace, currentRun = run) {
+            return stageExecutionCwd({ stage, projectRoot: currentRun.project_root, workspaceRoot: currentRun.workspace_root, ...(mergeTargetWorkspace ? { mergeTargetWorkspace } : {}) });
+        }
+    };
+}

package/dist/services/controller-fanout.js

@@ -1,13 +1,15 @@
 import { AppError, errorRecord } from "../shared/errors.js";
 import { normalizeNativeChildren, safeNativeFailure } from "../harness-runtime/lib/native-children.mjs";
-import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout, subagentCapacityKey, verifiedNativeWorkFailure } from "./vnext-fanout.js";
-import { getFlowRunVariables } from "./runs.js";
+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 } from "./work-registry.js";
+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 { stageWorkIds } from "./stage-work-graph.js";
+import { stageAttempt, stageWorkIds } from "./stage-work-graph.js";
+import { runtimeCommand } from "./runtime-command.js";
 function semanticCompletionPrompt(stage, completed) {
     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."
@@ -80,7 +82,7 @@ export async function nextControllerFanout(context, input) {
     }
     const prompt = (action, text) => ({ kind: "prompt", action, prompt: action === "dispatch_work" ? text : `${text}\n\n${lifecycleCommandCompletionInstruction}`, fingerprint: JSON.stringify({ stage: input.stage, parent: fanout.parent_work_id, state: fanout.state, graph: fanout.graph_revision }) });
     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 with real dependencies. Do not launch children, finish the Stage, or start a successor. Return after registering the graph; the runtime will dispatch its ready Work.`);
+        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);
@@ -106,22 +108,62 @@ export async function nextControllerFanout(context, input) {
             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));
-            return { kind: "external", works: external.slice(0, maximum).map(choice => choice.work) };
+            const selected = external.slice(0, maximum).map(choice => choice.work);
+            for (const work of selected)
+                prepareRepair(work);
+            return { kind: "external", works: selected };
         }
-        const variables = getFlowRunVariables(context, input);
-        const capacity = variables.variables[subagentCapacityKey];
+        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 => choice.work);
+        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") {
+                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);
-        if (input.stage === "plan-review" || input.stage === "code-review")
-            for (const work of wave)
-                assertWorkLaunchReady(context, work.work_id);
         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 }));
     }
@@ -129,6 +171,23 @@ export async function nextControllerFanout(context, input) {
         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 FROM runs WHERE project_id=? AND id=?", [projectId, input.runId]);
+        if (run?.flow_kind === "mb-init") {
+            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
+        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.`);
+            }
+        }
+    }
     return prompt("semantic_completion", semanticCompletionPrompt(input.stage, fanout.works.completed));
 }
 /** Shared pinned runtime normalization; preserve structured errors at the TS boundary. */

package/dist/services/dashboard.js

@@ -6,7 +6,7 @@ import { isActiveProtocolStatus, isActiveQueueStatus, isQueueHistoryStatus } fro
 import { AppError } from "../shared/errors.js";
 import { prepareOutputFile } from "../cli/input-preparation.js";
 import { ensureDir, resolveProjectRoot, resolveProtocolPlanPath } from "../storage/paths.js";
-import { dashboardMarkdownPath, globalDashboardHtmlPath, globalDashboardJsonPath, globalDashboardMarkdownPath, projectDashboardHtmlPath, projectDashboardJsonPath, projectSummaryJsonPath, protocolDashboardHtmlPath, protocolDashboardJsonPath, readProjectConfig } from "./config.js";
+import { dashboardMarkdownPath, globalDashboardHtmlPath, globalDashboardJsonPath, globalDashboardMarkdownPath, projectDashboardHtmlPath, projectDashboardJsonPath, projectDashboardDir, projectSummaryJsonPath, protocolDashboardHtmlPath, protocolDashboardJsonPath, readProjectConfig } from "./config.js";
 import { queueForProject } from "./merge-queue.js";
 import { publishProjectSummary } from "./project-summary.js";
 import { requireProjectByRoot } from "./projects.js";
@@ -215,7 +215,13 @@ export function autoRefreshDashboards(context, input) {
     // Their derived timestamp must not mutate the captured workspace.
     if (projectRecoveryGuarded(context, project.id))
         return { ok: true, skipped: true, reason: "run_recovery_guarded" };
-    const config = readProjectConfig(context, project.id);
+    const configured = readProjectConfig(context, project.id);
+    // Automatic observation must not change the source baseline owned by init.
+    // Keep projections in Home; do not hide runtime-created paths in Git or
+    // weaken source preservation by excluding user-owned .tasks directories.
+    const initializing = context.db.get("SELECT 1 FROM runs WHERE project_id=? AND flow_kind='mb-init' AND (id=? OR status IN ('created','running','paused','waiting_for_user','blocked')) LIMIT 1", [project.id, input.runId ?? null]);
+    const config = initializing ? { ...configured, dashboard: { ...configured.dashboard,
+            markdown_path: path.join(projectDashboardDir(context.ddFlowHome, project.id), "project-dashboard.md") } } : configured;
     if (!config.dashboard.auto_refresh) {
         return { ok: true, skipped: true, reason: "dashboard_auto_refresh_disabled" };
     }

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

@@ -0,0 +1,35 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { readDescriptorStageInput, readDescriptorStageInputForRecovery } from "./descriptor-stage-coordinator.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+/** SQL-only physical coordinator proof, independent of allocation/prompt
+ * custody. It creates no Session, hook claim or provider operation.
+ */
+export function readDescriptorCoordinatorSession(context, input, refuse = reason => {
+    throw new AppError("descriptor_coordinator_session_invalid", "Coordinator has no matching physical Session custody", 1, { reason, effect: "no_effect" });
+}) {
+    const { scope, bundle, workId } = input;
+    const rows = context.db.all("SELECT ws.id,ws.session_id,ws.hook_event_id,ws.prompt_path,ws.result_path,s.harness,s.provider_session_id FROM work_sessions ws JOIN sessions s ON s.session_id=ws.session_id AND s.project_id=? WHERE ws.work_id=? AND ws.status='running' AND s.run_id=? AND s.current_stage=? AND s.status='active' LIMIT 2", [scope.projectId, workId, scope.runId, scope.stage]);
+    if (rows.length !== 1)
+        refuse("active_coordinator_session_required");
+    const session = rows[0], route = bundle.execution.stage(scope.stage);
+    const selected = input.recoveryRead ? readDescriptorStageInputForRecovery(context, scope, bundle, input.recoveryRead) : readDescriptorStageInput(context, scope, bundle), directory = bundle.descriptor.stage(scope.stage).directory;
+    if (session.prompt_path !== path.join(selected.runRoot, directory, "coordinator-prompt.md")
+        || session.result_path !== path.join(selected.runRoot, directory, "result-input.json"))
+        refuse("coordinator_packet_link_changed");
+    if (session.harness !== runtimeHarness(route.profile)
+        || !context.db.get("SELECT 1 FROM hook_events WHERE project_id=? AND event_key=? AND session_id=? AND harness=? AND provider_session_id=? AND status='claimed' AND event_name='PreToolUse'", [scope.projectId, session.hook_event_id, session.session_id, session.harness, session.provider_session_id]))
+        refuse("coordinator_start_custody_missing");
+    const bindings = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='stage.coordinator_binding' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.stage')=? AND json_extract(payload_json,'$.work_session_id')=? LIMIT 33", [scope.projectId, scope.runId, scope.stage, session.id]);
+    if (!bindings.length || bindings.length > 32 || bindings.some(row => Buffer.byteLength(row.payload_json) > 32768))
+        refuse("physical_binding_missing");
+    const binding = JSON.parse(bindings[0].payload_json);
+    if (bindings.some(row => hybridDigest(JSON.parse(row.payload_json)) !== hybridDigest(binding))
+        || binding.work_id !== workId || binding.session_id !== session.session_id || binding.harness !== session.harness || binding.provider_session_id !== session.provider_session_id
+        || binding.execution_sha256 !== bundle.execution.sha256 || binding.profile_id !== route.profile.id || binding.profile_sha256 !== hybridDigest(route.profile)
+        || binding.session_mode !== route.session_mode || hybridDigest(binding.scope) !== hybridDigest({ ...stageGraphScope(context, scope.projectId, scope.runId, scope.stage), stage: scope.stage }))
+        refuse("physical_binding_changed");
+    return hybridDigest({ session, binding });
+}

package/dist/services/descriptor-root-work.js

@@ -0,0 +1,53 @@
+import { AppError } from "../shared/errors.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { nextWorkId } from "./ids.js";
+import { appendAudit } from "./audit.js";
+const event = "flow_run.descriptor_root_work";
+function refuse(reason) {
+    throw new AppError("descriptor_root_work_invalid", "RUN root Work lacks independent allocation custody", 1, { reason, effect: "no_effect" });
+}
+const binding = (scope, bundle) => ({ projectId: scope.projectId, runId: scope.runId, bundle_sha256: bundle.sha256 });
+/** SQL-only read. Root identity is retained independently, never discovered
+ * from an arbitrary root row or reconstructed after receipt loss.
+ */
+export function readDescriptorRootWork(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        const receipts = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? LIMIT 2", [scope.projectId, event, scope.runId]);
+        if (receipts.length !== 1 || Buffer.byteLength(receipts[0].payload_json) > 16 * 1024)
+            refuse("root_work_receipt_missing");
+        const receipt = JSON.parse(receipts[0].payload_json);
+        const expected = binding(scope, bundle);
+        if (typeof receipt.work_id !== "string" || hybridDigest(receipt) !== hybridDigest({ run_id: scope.runId, work_id: receipt.work_id, binding: expected }))
+            refuse("root_work_changed");
+        const roots = context.db.all("SELECT work_id,task,payload_json,status,launch_policy,result_schema,depends_on_json FROM works WHERE project_id=? AND run_id=? AND parent_work_id IS NULL LIMIT 2", [scope.projectId, scope.runId]);
+        if (roots.length !== 1)
+            refuse("ambiguous_root_work");
+        const root = roots[0];
+        if (root.work_id !== receipt.work_id || root.task !== `Coordinate ${bundle.descriptor.descriptor.id}`
+            || root.payload_json !== JSON.stringify({ descriptor_run_coordinator: expected })
+            || root.launch_policy !== "reuse_allowed" || root.result_schema !== null || root.depends_on_json !== "[]")
+            refuse("root_work_custody_missing");
+        if (JSON.parse(run.index_json).root_work_id !== root.work_id)
+            refuse("root_work_anchor_missing");
+        return { workId: root.work_id, status: root.status };
+    });
+}
+/** Called only in the same writer as fresh descriptor RUN allocation. Stage
+ * handlers consume this identity; they never allocate a second RUN root.
+ */
+export function allocateDescriptorRootWork(context, scope, bundle) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    if (context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND parent_work_id IS NULL", [scope.projectId, scope.runId])
+        || context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=?", [scope.projectId, event, scope.runId]))
+        refuse("root_work_already_allocated");
+    const workId = nextWorkId(context, scope.projectId, bundle.descriptor.descriptor.id), now = context.now();
+    const expected = binding(scope, bundle);
+    context.db.run("INSERT INTO works (work_id,project_id,run_id,parent_work_id,task,launch_policy,depends_on_json,status,payload_json,created_at,updated_at) VALUES (?,?,?,NULL,?,'reuse_allowed','[]','created',?,?,?)", [workId, scope.projectId, scope.runId, `Coordinate ${bundle.descriptor.descriptor.id}`, JSON.stringify({ descriptor_run_coordinator: expected }), now, now]);
+    context.db.run("UPDATE runs SET index_json=json_set(index_json,'$.root_work_id',?) WHERE project_id=? AND id=?", [workId, scope.projectId, scope.runId]);
+    appendAudit(context, { projectId: scope.projectId, eventType: event, payload: { run_id: scope.runId, work_id: workId, binding: expected } });
+    if (readDescriptorRootWork(context, scope, bundle).workId !== workId)
+        refuse("root_work_not_retained");
+    return workId;
+}

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

@@ -0,0 +1,105 @@
+import { AppError } from "../shared/errors.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { appendFlowRunTimelineEvent, assertPreparedRunBundleSqlAuthority, completeDescriptorRunState, gitFacts, publishRunProjections, readFlowRunExecutionBundle, withStageSettlement } from "./runs.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { readAcceptedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
+import { stageLifecycleMatchKey } from "./hooks.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { assertRunMutationAllowed } from "./run-recovery-guard.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const event = "flow_run.descriptor_run_settlement";
+function refuse(reason) {
+    throw new AppError("descriptor_run_settlement_invalid", "Terminal descriptor RUN lacks exact settlement custody", 1, { reason, effect: "no_effect" });
+}
+function selected(context, scope, bundle, matchKeys) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const root = readDescriptorRootWork(context, scope, bundle);
+    const run = context.db.get("SELECT status,index_json FROM runs WHERE project_id=? AND id=?", [scope.projectId, scope.runId]);
+    const index = JSON.parse(run.index_json);
+    const terminal = index.stage_runs.at(-1);
+    if (!bundle.descriptor.descriptor.terminal_stages.includes(scope.stage)
+        || terminal?.stage !== scope.stage || terminal.status !== "done")
+        refuse("terminal_stage_not_accepted");
+    const data = readAcceptedStageData(context, scope);
+    const stageReceipt = readAcceptedDescriptorStageSettlement(context, scope, bundle, matchKeys);
+    if (context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND work_id<>? AND status IN ('created','running','paused') LIMIT 1", [scope.projectId, scope.runId, root.workId])
+        || context.db.get("SELECT 1 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' LIMIT 1", [scope.projectId, scope.runId]))
+        refuse("work_still_active");
+    const prior = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? LIMIT 2", [scope.projectId, event, scope.runId]);
+    if (prior.length > 1 || prior.some(row => Buffer.byteLength(row.payload_json) > 32 * 1024))
+        refuse("ambiguous_receipt");
+    if (root.status !== (prior.length ? "completed" : "running") || run.status !== (prior.length ? "done" : "running"))
+        refuse("terminal_state_changed");
+    return { rootId: root.workId, result: data.bytes.toString("utf8"), binding: { ...scope, work_id: root.workId, bundle_sha256: bundle.sha256, result_sha256: data.result.sha256, input_sha256: data.input_sha256, stage_receipt_sha256: hybridDigest(stageReceipt) }, prior: prior[0] ? JSON.parse(prior[0].payload_json) : null };
+}
+/** Runtime closure only. A terminal handler must first verify semantic/check/
+ * review/Git acceptance, revalidate physical proof, and supply its SQL fence.
+ * Transcript usage collection is deliberately outside this atomic writer.
+ */
+export class PreparedDescriptorRunSettlement {
+    #scope;
+    #bundle;
+    #owner;
+    #git;
+    #generation;
+    #matchKeys;
+    constructor(scope, bundle, owner, git, generation, matchKeys) {
+        this.#scope = scope;
+        this.#bundle = bundle;
+        this.#owner = owner;
+        this.#git = git;
+        this.#generation = generation;
+        this.#matchKeys = matchKeys;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), bundle = readFlowRunExecutionBundle(context, input);
+        if (!bundle)
+            refuse("bundle_required");
+        const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+        const matchKeys = entityReferenceVariants(input.runId).map(reference => stageLifecycleMatchKey("stage_finish", reference, input.stage, input.projectRoot));
+        const snapshot = context.db.readSnapshot(() => ({ owner: selected(context, scope, bundle, matchKeys), generation: assertRunMutationAllowed(context, scope.projectId, scope.runId) }));
+        const git = snapshot.owner.prior?.git ?? gitFacts(bundle.execution.snapshot().scope.workspace);
+        return new PreparedDescriptorRunSettlement(scope, bundle, snapshot.owner, git, snapshot.generation, matchKeys);
+    }
+    apply(context, assertHandlerCustody) {
+        if (typeof assertHandlerCustody !== "function")
+            refuse("handler_fence_required");
+        const bundle = readFlowRunExecutionBundle(context, { projectRoot: this.#bundle.execution.snapshot().scope.projectRoot, runId: this.#scope.runId });
+        if (!bundle || bundle.sha256 !== this.#bundle.sha256)
+            refuse("bundle_changed");
+        const observed = context.db.readSnapshot(() => selected(context, this.#scope, this.#bundle, this.#matchKeys));
+        if (!observed.prior && hybridDigest(gitFacts(this.#bundle.execution.snapshot().scope.workspace)) !== hybridDigest(this.#git))
+            refuse("git_observation_changed");
+        const receipt = { run_id: this.#scope.runId, work_id: this.#owner.rootId, binding: this.#owner.binding, git: this.#git };
+        const changed = withStageSettlement(context, () => {
+            assertRunMutationAllowed(context, this.#scope.projectId, this.#scope.runId, this.#generation);
+            assertHandlerCustody(context);
+            const current = selected(context, this.#scope, this.#bundle, this.#matchKeys);
+            if (hybridDigest(current.binding) !== hybridDigest(this.#owner.binding) || current.result !== this.#owner.result)
+                refuse("terminal_custody_changed");
+            if (current.prior) {
+                if (hybridDigest(current.prior) !== hybridDigest(receipt)
+                    || context.db.get("SELECT result FROM works WHERE work_id=?", [current.rootId])?.result !== current.result)
+                    refuse("settlement_changed");
+                return false;
+            }
+            if (this.#owner.prior)
+                refuse("settlement_receipt_missing");
+            const now = context.now();
+            if (context.db.run("UPDATE works SET status='completed',result=?,completed_at=?,updated_at=? WHERE work_id=? AND project_id=? AND run_id=? AND status='running'", [current.result, now, now, current.rootId, this.#scope.projectId, this.#scope.runId]).changes !== 1)
+                refuse("root_changed");
+            appendFlowRunTimelineEvent(context, this.#scope.projectId, this.#scope.runId, { at: now, type: "work_completed", work_id: current.rootId, descriptor_terminal: true });
+            completeDescriptorRunState(context, this.#scope, this.#bundle, this.#git);
+            appendAudit(context, { projectId: this.#scope.projectId, eventType: event, payload: receipt });
+            return true;
+        });
+        // A committed terminal receipt can outlive an interrupted file publisher.
+        // Replay restores projections from current SQL, without settling again.
+        publishRunProjections(context, this.#scope.projectId, this.#scope.runId);
+        return { changed, run_id: this.#scope.runId, work_id: this.#owner.rootId, status: "done" };
+    }
+}