@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.141

package/dist/services/vnext-contracts.js

@@ -1 +1,10 @@
-export {};
+import { isControllerManagedInvocation, managedLifecycleCommand } from "./lifecycle-invocations.js";
+/** Successor authority belongs to the controller, not the finishing Session.
+ * Manual flows still need an executable next step. Current-stage finish and
+ * paused/child Work commands do not pass through this boundary. */
+export function stageSuccessor(context, input) {
+    const next = { ...input.metadata, kind: "start_stage", stage: input.stage };
+    return isControllerManagedInvocation(context, input.projectRoot, input.runId)
+        ? { ...next, controller_owned: true, stop_turn: true, instruction: "This Stage is complete. End this Turn now and await the controller's next Stage assignment. Do not start the successor Stage or prepare its command." }
+        : { ...next, command: managedLifecycleCommand(context, input.command) };
+}

package/dist/services/vnext-execution-profile.js

@@ -1,19 +1,91 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import { AppError } from "../shared/errors.js";
+import { canonicalPath } from "../storage/paths.js";
+import { isExecutionRouting } from "./execution-policy.js";
+export const RUN_OPERATIONAL_DECISION_CONTRACT = "run-operational-decision@1";
+const object = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const text = (value) => typeof value === "string" && Boolean(value.trim());
+const keys = (value, allowed) => object(value) && Object.keys(value).every(key => allowed.includes(key));
+/** Structural validation only: acceptance is supplied by the caller, never inferred from settings. */
+export function validateRunOperationalDecision(value, settings) {
+    if (!object(value) || value.schema_id !== RUN_OPERATIONAL_DECISION_CONTRACT || !text(value.id)
+        || !object(value.scope) || !text(value.scope.project_root) || !path.isAbsolute(value.scope.project_root)
+        || [value.scope.eval_id, value.scope.execution_id].some(item => item !== undefined && !text(item))
+        || !object(value.settings) || !object(value.settings.merge_delivery) || value.settings.merge_delivery.strategy !== settings.merge_delivery.strategy
+        || !object(value.settings.merge_cleanup) || value.settings.merge_cleanup.source !== settings.merge_cleanup.source
+        || !object(value.policy) || !text(value.policy.path) || !text(value.policy.sha256) || !/^[a-f0-9]{64}$/.test(value.policy.sha256)
+        || !Array.isArray(value.policy.clauses) || !value.policy.clauses.length || !value.policy.clauses.every(text)
+        || !object(value.acceptance) || !text(value.acceptance.source) || !text(value.acceptance.reference)
+        || value.exception !== undefined && (!object(value.exception) || !text(value.exception.reason) || !text(value.exception.owner)
+            || !text(value.exception.review_at) || !Number.isFinite(Date.parse(value.exception.review_at))
+            || value.exception.expires_at !== undefined && (!text(value.exception.expires_at) || !Number.isFinite(Date.parse(value.exception.expires_at))))) {
+        throw new AppError("operational_decision_invalid", "Operational decision requires explicit acceptance, scoped authority and matching settings", 2);
+    }
+    if (!keys(value, ["schema_id", "id", "scope", "settings", "policy", "acceptance", "exception", "declaration"])
+        || !keys(value.scope, ["project_root", "eval_id", "execution_id"])
+        || !keys(value.settings, ["merge_delivery", "merge_cleanup"])
+        || !keys(value.settings.merge_delivery, ["strategy"]) || !keys(value.settings.merge_cleanup, ["source"])
+        || !keys(value.policy, ["path", "sha256", "clauses"]) || !keys(value.acceptance, ["source", "reference"])
+        || value.exception !== undefined && !keys(value.exception, ["reason", "owner", "review_at", "expires_at"])
+        || value.declaration !== undefined && !keys(value.declaration, ["bytes", "sha256"]))
+        throw new AppError("operational_decision_invalid", "Operational decision contains unsupported authority fields", 2);
+    if (value.declaration !== undefined) {
+        if (!object(value.declaration) || !text(value.declaration.bytes) || !text(value.declaration.sha256)
+            || crypto.createHash("sha256").update(value.declaration.bytes).digest("hex") !== value.declaration.sha256)
+            throw new AppError("operational_decision_invalid", "Original operational declaration checksum does not match", 2);
+        let declaration;
+        try {
+            declaration = JSON.parse(value.declaration.bytes);
+        }
+        catch {
+            throw new AppError("operational_decision_invalid", "Original operational declaration must be JSON", 2);
+        }
+        if (!object(declaration) || !keys(declaration, ["schema_id", "id", "scope", "settings", "policy", "acceptance", "exception"])
+            || declaration.scope !== undefined && !keys(declaration.scope, ["project_root", "eval_id", "execution_id"])
+            || ["schema_id", "id", "settings", "policy", "acceptance", "exception"].some(key => !isDeepStrictEqual(declaration[key], value[key])))
+            throw new AppError("operational_decision_invalid", "Materialized decision changed the accepted declaration", 2);
+    }
+    return value;
+}
+/** Machine validation of declared policy bytes, not an NLP interpretation of Markdown. */
+export function assertOperationalDecisionSource(decision, projectRoot, now) {
+    if (canonicalPath(decision.scope.project_root, false) !== canonicalPath(projectRoot, false))
+        throw new AppError("operational_decision_scope_mismatch", "Operational decision belongs to another project", 2);
+    const file = path.resolve(projectRoot, decision.policy.path);
+    const relative = path.relative(fs.realpathSync(projectRoot), fs.existsSync(file) ? fs.realpathSync(file) : file);
+    if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) || relative === ".." || !fs.existsSync(file) || crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") !== decision.policy.sha256)
+        throw new AppError("operational_decision_policy_changed", "Operational decision policy source checksum does not match an owned file", 2, { file });
+    if (decision.exception?.expires_at && Date.parse(decision.exception.expires_at) <= Date.parse(now))
+        throw new AppError("operational_decision_expired", "Explicit operational decision expiration has passed", 2);
+}
 const relativePath = path.join(".memory-bank", "dd-flow", "project-execution.json");
 /** The project owns defaults; a RUN snapshots them once and never re-infers them. */
 export function loadVnextExecutionProfile(projectRoot) {
+    return loadVnextExecutionProfileSnapshot(projectRoot).profile;
+}
+/** Parse and identify the same source bytes; a second read cannot bind another declaration. */
+export function loadVnextExecutionProfileSnapshot(projectRoot) {
     const file = path.join(projectRoot, relativePath);
+    let bytes;
     let value;
     try {
-        value = JSON.parse(fs.readFileSync(file, "utf8"));
+        bytes = fs.readFileSync(file);
+        value = JSON.parse(bytes.toString("utf8"));
     }
     catch (error) {
         throw new AppError("execution_profile_missing", "vNext flow requires .memory-bank/dd-flow/project-execution.json", 1, { file, cause: String(error) });
     }
+    return { profile: validateVnextExecutionProfile(value), bytes };
+}
+/** Pure shared admission contract for project-execution@2 and @3. */
+export function validateVnextExecutionProfile(value) {
+    if (!object(value))
+        throw new AppError("execution_profile_invalid", "Project execution profile must be an object", 1);
     const profile = value;
-    if (profile.schema_id !== "dd-flow/project-execution@2"
+    if ((profile.schema_id !== "dd-flow/project-execution@2" && profile.schema_id !== "dd-flow/project-execution@3")
         || (profile.stage_session_mode !== undefined && profile.stage_session_mode !== "same_session" && profile.stage_session_mode !== "new_session")
         || !["auto", "off", "standard", "deep"].includes(String(profile.plan_review_mode))
         || (profile.code_review_mode !== undefined && !["auto", "off", "standard", "deep"].includes(String(profile.code_review_mode)))
@@ -21,10 +93,13 @@ export function loadVnextExecutionProfile(projectRoot) {
         || profile.merge_delivery?.strategy !== "local"
         || !["retain", "delete_after_success"].includes(String(profile.merge_cleanup?.source))
         || !["code_completed", "code_review_completed", "merge_completed"].includes(String(profile.stop_target))
-        || !profile.code_bootstrap || typeof profile.code_bootstrap.command !== "string" || !profile.code_bootstrap.command.trim()
-        || typeof profile.code_bootstrap.policy_ref !== "string" || !profile.code_bootstrap.policy_ref.trim()) {
-        throw new AppError("execution_profile_invalid", "Project execution profile does not match dd-flow/project-execution@2", 1, { file });
+        || (profile.code_bootstrap !== undefined && (!profile.code_bootstrap || typeof profile.code_bootstrap.command !== "string" || !profile.code_bootstrap.command.trim()
+            || typeof profile.code_bootstrap.policy_ref !== "string" || !profile.code_bootstrap.policy_ref.trim()))
+        || (profile.execution === undefined ? profile.schema_id === "dd-flow/project-execution@3" : !isExecutionRouting(profile.execution))) {
+        throw new AppError("execution_profile_invalid", "Project execution profile does not match its supported dd-flow schema", 1);
     }
+    if (profile.operational_decision !== undefined)
+        validateRunOperationalDecision(profile.operational_decision, profile);
     return { ...profile, stage_session_mode: profile.stage_session_mode ?? "same_session", code_review_mode: profile.code_review_mode ?? "off" };
 }
 export function executionProfilePath(projectRoot) { return path.join(projectRoot, relativePath); }

package/dist/services/vnext-fanout.js

@@ -3,10 +3,106 @@ import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
-import { getFlowRunVariables } from "./runs.js";
-import { listWorks } from "./work-registry.js";
+import { getFlowRunVariables, appendFlowRunTimelineEvent, readFlowRunExecutionBundle } from "./runs.js";
+import { resolveExecutionPolicy } from "./execution-policy.js";
+import { listWorks, failWork, cancelWork, readWorkBatchCustody } from "./work-registry.js";
+import { storageSessionId } from "./session-identity.js";
+import { reconcileUnfinishedChecks } from "./code-checks.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
+import { stageWorkIds, stageGraphScope } from "./stage-work-graph.js";
+import { eligibleProviderChildOverload } from "./provider-capacity.js";
+import { renderNativeChildFollowupInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { selectMemoryCompositionRegistration } from "./memory-composition-registration.js";
+import { safeNativeFailure } from "../harness-runtime/lib/native-children.mjs";
 export const subagentCapacityKey = "runtime.subagent.available_slots";
+/** External concurrency is policy, never evidence of native child qualification. */
+export function getStageFanoutCapacity(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
+    if (!run)
+        throw new AppError("not_found", "RUN is unavailable", 1);
+    const index = JSON.parse(run.index_json);
+    const bundle = index.execution_bundle ? readFlowRunExecutionBundle(context, { projectRoot, runId: input.runId }) : null;
+    const generic = bundle?.execution.work(input.stage).delegation;
+    if (generic?.mode === "external")
+        return input.nativeOnly
+            ? { run_key: null, available_slots: null, source: "harness_qualification" }
+            : { run_key: null, available_slots: generic.max_parallel, source: "external_policy" };
+    // Generic native admission already requires a scoped capacity receipt whose
+    // observed count covers this frozen limit. Mutable legacy variables cannot
+    // replace that receipt or silently prevent its productive dispatch.
+    if (generic?.mode === "native")
+        return { run_key: null, available_slots: generic.max_parallel, source: "harness_qualification" };
+    const frozen = index.execution_profile;
+    if (!bundle && frozen?.settings.execution) {
+        if (!frozen.agent_profiles)
+            throw new AppError("execution_profile_not_frozen", "Fan-out needs the RUN's frozen profiles", 1);
+        const resolved = resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy: frozen.settings.execution, profiles: frozen.agent_profiles, stage: input.stage });
+        if (resolved.delegation.mode === "external" && !input.nativeOnly)
+            return { run_key: null, available_slots: resolved.delegation.max_parallel, source: "external_policy" };
+    }
+    const variables = getFlowRunVariables(context, { projectRoot, runId: input.runId });
+    const available = variables.variables[subagentCapacityKey];
+    return { run_key: subagentCapacityKey, available_slots: typeof available === "number" && Number.isInteger(available) && available >= 0 ? Math.min(available, generic?.max_parallel ?? available) : null, source: "harness_qualification" };
+}
+function nativeFailureController(context, projectId, runId, stage, parent) {
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type='table' AND name='run_controllers'"))
+        return null;
+    const rows = context.db.all("SELECT controller_id,generation,state_json FROM run_controllers WHERE project_id=? AND run_id=? AND status NOT IN ('completed','cancelled','superseded')", [projectId, runId]);
+    const matching = rows.filter(row => {
+        try {
+            const state = JSON.parse(row.state_json);
+            return state.stage === stage && state.sessions?.[state.current_session]?.id === parent;
+        }
+        catch {
+            return false;
+        }
+    });
+    return matching.length === 1 ? matching[0] : null;
+}
+/** Failure metadata authored by a Work is not native evidence. Require the
+ * independently recorded reconciliation and its exact current registry links. */
+export function verifiedNativeWorkFailure(context, input) {
+    const b = input.receipt.native_binding;
+    if (!b || b.schema_id !== "dd-flow/native-work-failure@1")
+        return;
+    const project = requireProjectByRoot(context, input.projectRoot);
+    const scope = stageGraphScope(context, project.id, input.runId, input.stage);
+    const controller = nativeFailureController(context, project.id, input.runId, input.stage, input.parentSessionId);
+    if (!controller || b.controller_id !== controller.controller_id || b.generation !== controller.generation
+        || b.project_id !== project.id || b.run_id !== input.runId || b.stage !== input.stage
+        || b.stage_attempt_id !== scope.attempt || b.stage_cycle !== scope.cycle
+        || b.work_id !== input.workId || b.parent_work_id !== input.parentWorkId
+        || b.parent_provider_session_id !== input.parentSessionId || b.terminal_turn_id !== input.receipt.terminal_turn_id
+        || input.receipt.source !== "native_child_observation" || input.receipt.outcome !== "failed")
+        return;
+    const link = context.db.get(`SELECT ws.id 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 ws.id=? AND w.project_id=? AND w.run_id=? AND w.work_id=? AND w.parent_work_id=? AND ws.status='failed' AND w.status='failed' AND s.parent_session_id=? AND s.provider_session_id=? AND s.harness=?`, [b.work_session_id, project.id, input.runId, input.workId, input.parentWorkId, storageSessionId({ harness_id: b.harness_id, session_id: input.parentSessionId }), b.provider_session_id, b.harness_id]);
+    if (!link)
+        return;
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_id=? AND id=?", [project.id, input.runId]);
+    try {
+        const events = fs.readFileSync(path.join(run.run_root, "timeline.jsonl"), "utf8").trim().split("\n");
+        const proof = events.some(line => {
+            const event = JSON.parse(line);
+            if (event.type !== "native_child_reconciliation" || event.stage !== input.stage)
+                return false;
+            const terminal = event.observations?.children?.find((child) => child.session_id === b.provider_session_id && child.terminal_turn_id === b.terminal_turn_id);
+            if (event.observations?.parent_session_id !== b.parent_provider_session_id || event.observations?.harness_id !== b.harness_id
+                || terminal?.status !== "failed" || terminal.terminal_observed_at !== input.receipt.terminal_observed_at
+                || JSON.stringify(safeNativeFailure(terminal.provider_error)) !== JSON.stringify(safeNativeFailure(input.receipt.provider_error)))
+                return false;
+            return event.reconciled?.some((entry) => entry.outcome === "failed"
+                && entry.native_binding && Object.keys(b).every(key => b[key] === entry.native_binding[key]));
+        });
+        return proof ? b : undefined;
+    }
+    catch {
+        return;
+    }
+}
 export function fanoutState(input) {
     if (!input.hasWork)
         return input.dispatch === "none" ? "coordinator_required" : "dispatch_required";
@@ -18,7 +114,7 @@ export function fanoutState(input) {
 }
 export function fanoutFile(stageRoot) { return path.join(stageRoot, "fanout.json"); }
 export function writeFanoutDescriptor(stageRoot, descriptor) {
-    const value = { schema_id: "dd-flow/work-fanout@1", kind: "work_fanout", ...descriptor };
+    const value = { schema_id: descriptor.scope ? "dd-flow/work-fanout@2" : "dd-flow/work-fanout@1", kind: "work_fanout", ...descriptor };
     fs.writeFileSync(fanoutFile(stageRoot), `${JSON.stringify(value, null, 2)}\n`);
     return value;
 }
@@ -27,31 +123,95 @@ export function readFanoutDescriptor(stageRoot) {
     if (!fs.existsSync(file))
         return null;
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (value.schema_id !== "dd-flow/work-fanout@1" || value.kind !== "work_fanout" || typeof value.stage !== "string" || typeof value.parent_work_id !== "string" || !["none", "plan-review"].includes(String(value.dispatch)) || typeof value.capacity_required !== "boolean") {
+    if (!["dd-flow/work-fanout@1", "dd-flow/work-fanout@2"].includes(String(value.schema_id)) || value.kind !== "work_fanout" || typeof value.stage !== "string" || typeof value.parent_work_id !== "string" || !["none", "plan-review"].includes(String(value.dispatch)) || typeof value.capacity_required !== "boolean" || value.schema_id === "dd-flow/work-fanout@2" && (!value.scope || [value.scope.project_id, value.scope.run_id, value.scope.attempt, value.scope.cycle].some(item => typeof item !== "string"))) {
         throw new AppError("runtime_missing", "Stage fan-out descriptor is invalid", 1, { file });
     }
     return value;
 }
+/** Memory graphs are SQL-owned; a mutable/missing fanout.json is not their
+ * dispatch authority. Domain registrations and Work launch owners still fence
+ * productive assignments, including reviewer/correction waves.
+ */
+export function memoryStageFanoutDescriptor(context, input) {
+    if (!["compose", "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?.flow_kind !== "mb-init")
+        return null;
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init")
+        throw new AppError("stage_graph_compatibility_required", "Memory graph requires its admitted RUN bundle", 1);
+    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 root = readDescriptorRootWork(context, { projectId: project.id, runId: input.runId }, bundle);
+    const scope = stageGraphScope(context, project.id, input.runId, input.stage), members = stageWorkIds(context, project.id, input.runId, input.stage);
+    if (root.status !== "running" || !members.has(root.workId))
+        throw new AppError("stage_graph_conflict", "Memory graph lost its active coordinator", 1);
+    for (const id of members) {
+        if (id === root.workId)
+            continue;
+        const work = context.db.get("SELECT parent_work_id,result_schema FROM works WHERE project_id=? AND run_id=? AND work_id=?", [project.id, input.runId, id]);
+        const schemas = input.stage === "compose" ? ["dd-flow/memory-composition-work-result@1"] : ["dd-flow/memory-review-work-result@1", "dd-flow/memory-repair-work-result@1"];
+        if (!work || work.parent_work_id !== root.workId || !schemas.includes(work.result_schema ?? ""))
+            throw new AppError("stage_graph_conflict", "Memory graph contains an unassigned Work", 1);
+        const custody = readWorkBatchCustody(context, id);
+        if (custody.scope.project_id !== scope.project_id || custody.scope.run_id !== scope.run_id || custody.scope.attempt !== scope.attempt
+            || custody.scope.cycle !== scope.cycle || custody.scope.stage !== input.stage || custody.scope.parent_work_id !== root.workId)
+            throw new AppError("stage_graph_conflict", "Memory graph contains foreign allocation custody", 1);
+    }
+    if (input.stage === "compose") {
+        const children = context.db.all("SELECT work_id FROM works WHERE project_id=? AND run_id=? AND parent_work_id=?", [project.id, input.runId, root.workId]).filter(work => members.has(work.work_id));
+        const registered = 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.attempt')=? AND json_extract(payload_json,'$.scope.cycle')=? LIMIT 1", [project.id, input.runId, scope.attempt, scope.cycle]);
+        if (children.length || registered) {
+            const registration = selectMemoryCompositionRegistration(context, { ...scope, stage: "compose", parent_work_id: root.workId });
+            const ids = new Set(Object.values(registration.work_ids));
+            if (ids.size !== children.length || children.some(work => !ids.has(work.work_id)))
+                throw new AppError("stage_graph_conflict", "Memory composition differs from its registered graph", 1);
+        }
+    }
+    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 };
+}
 /** Read-only projection for an external orchestrator.  dd-flow keeps the graph authority. */
 export function getVnextFanoutStatus(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
-    const run = context.db.get("SELECT run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
-    if (!run?.run_root)
-        throw new AppError("not_found", "RUN artifact root is unavailable", 1, { run_id: input.runId });
-    const stageRoot = path.join(run.run_root, vnextStageDirectory(input.stage));
-    const descriptor = readFanoutDescriptor(stageRoot);
+    const run = context.db.get("SELECT run_root, index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
+    if (!run)
+        throw new AppError("not_found", "RUN is not registered", 1, { run_id: input.runId });
+    if (!run.run_root)
+        throw new AppError("runtime_artifact_missing", "RUN artifact root is unavailable", 1, { run_id: input.runId });
+    const index = JSON.parse(run.index_json);
+    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));
+    let descriptor = memoryStageFanoutDescriptor(context, input) ?? 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'")) {
+        const members = stageWorkIds(context, project.id, input.runId, input.stage);
+        const parents = context.db.all("SELECT w.work_id, w.parent_work_id FROM repair_intents i JOIN works w ON w.work_id = i.work_id WHERE i.project_id = ? AND i.run_id = ? AND i.stage = ?", [project.id, input.runId, input.stage]).filter(work => members.has(work.work_id));
+        const roots = [...new Set(parents.map(work => work.parent_work_id))];
+        if (roots.length > 1)
+            throw new AppError("stage_graph_conflict", "Registered repairs disagree on their stage coordinator", 1);
+        if (roots.length === 1)
+            descriptor = { schema_id: "dd-flow/work-fanout@2", scope: stageGraphScope(context, project.id, input.runId, input.stage), kind: "work_fanout", stage: input.stage, parent_work_id: roots[0], dispatch: "none", capacity_required: true };
+    }
     if (!descriptor)
         return { ok: true, run_id: input.runId, stage: input.stage, orchestration: null };
     if (descriptor.stage !== input.stage)
         throw new AppError("runtime_missing", "Stage fan-out descriptor belongs to another stage", 1, { requested_stage: input.stage, descriptor_stage: descriptor.stage });
-    const variables = getFlowRunVariables(context, { projectRoot, runId: input.runId });
-    const available = variables.variables[subagentCapacityKey];
-    const all = listWorks(context, { parentWorkId: descriptor.parent_work_id, includeResults: false });
-    const ready = listWorks(context, { parentWorkId: descriptor.parent_work_id, ready: true, includeResults: false });
+    const capacity = getStageFanoutCapacity(context, { projectRoot, runId: input.runId, stage: input.stage });
+    const members = stageWorkIds(context, project.id, input.runId, input.stage);
+    const currentScope = stageGraphScope(context, project.id, input.runId, input.stage);
+    const compatible = descriptor.scope ? Object.entries(currentScope).every(([key, value]) => descriptor.scope[key] === value) : members.size > 0;
+    if (!compatible)
+        return { ok: true, run_id: input.runId, stage: input.stage, orchestration: { ...descriptor, state: "compatibility_required", compatibility: { code: "stage_graph_compatibility_required", message: "Legacy or stale stage graph has no authoritative current membership; use the pinned engine", expected_scope: currentScope } } };
+    const all = listWorks(context, { parentWorkId: descriptor.parent_work_id, includeResults: false, workIds: members });
+    const ready = { works: all.works.filter(work => work.ready) };
     const counts = Object.fromEntries(["created", "running", "completed", "failed", "cancelled"].map((status) => [status, all.works.filter((work) => work.status === status).length]));
     const hasWork = all.works.length > 0;
-    const capacityKnown = typeof available === "number" && Number.isInteger(available) && available >= 0;
+    const capacityKnown = capacity.available_slots !== null;
     return {
         ok: true,
         run_id: input.runId,
@@ -62,11 +222,143 @@ export function getVnextFanoutStatus(context, input) {
             // not: their coordinator first materializes the Work graph from its
             // authoritative prompt. An empty graph is therefore not a success.
             state: fanoutState({ dispatch: descriptor.dispatch, hasWork, capacityRequired: descriptor.capacity_required, capacityKnown, created: counts.created ?? 0, running: counts.running ?? 0 }),
-            capacity: {
-                run_key: subagentCapacityKey,
-                available_slots: capacityKnown ? available : null
-            },
-            works: { ...counts, ready: ready.works.map((work) => ({ work_id: work.work_id, task: work.task, start_command: work.start_command })) }
+            capacity,
+            graph_revision: all.works.map(work => ({ work_id: work.work_id, status: work.status, depends_on: work.depends_on })),
+            works: { ...counts, ready: ready.works.map((work) => ({ work_id: work.work_id, task: work.task, launch_policy: work.launch_policy, start_command: work.start_command })) }
         }
     };
 }
+/** Explicit controller mutation, separate from read-only fanout status.
+ * A native child may be mapped only by its registered identity. Reused native
+ * Sessions need a provider execution identity: without one we report ambiguity
+ * instead of applying a late event to the newest Work attempt. */
+export async function reconcileVnextFanout(context, input) {
+    const value = prepareNativeObservations(input.observations);
+    const status = getVnextFanoutStatus(context, input);
+    if (!status.orchestration)
+        return { ok: true, issues: [], reconciled: [] };
+    if (status.orchestration.state === "compatibility_required")
+        throw new AppError("stage_graph_compatibility_required", "Cannot reconcile a legacy or stale graph", 1);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const members = stageWorkIds(context, project.id, input.runId, input.stage);
+    const parent = storageSessionId({ harness_id: value.harness_id, session_id: value.parent_session_id });
+    const issues = [], reconciled = [];
+    for (const child of value.children) {
+        if (child.provenance === "parent_mismatch" || child.parent_session_id !== undefined && child.parent_session_id !== value.parent_session_id) {
+            issues.push({ code: "native_child_parent_mismatch", session_id: child.session_id, observed_parent_session_id: child.parent_session_id ?? null, expected_parent_session_id: value.parent_session_id, outcome: child.status });
+            continue;
+        }
+        if (child.status === "running" || child.status === "unknown")
+            continue;
+        const sessionId = storageSessionId({ harness_id: value.harness_id, session_id: String(child.session_id) });
+        const links = context.db.all(`SELECT ws.id, ws.work_id, ws.status, w.status AS work_status, w.parent_work_id 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`, [project.id, input.runId, sessionId, parent]);
+        const active = links.filter(link => link.status === "running" && link.work_status === "running" && link.parent_work_id === status.orchestration.parent_work_id && members.has(link.work_id));
+        if (!active.length) {
+            if (!links.length)
+                issues.push({ code: "child_launch_association_missing", session_id: child.session_id, outcome: child.status });
+            continue;
+        }
+        if (links.length !== 1 || active.length !== 1) {
+            issues.push({ code: "child_execution_ambiguous", session_id: child.session_id, work_ids: active.map(link => link.work_id) });
+            continue;
+        }
+        const link = active[0];
+        if (renderNativeChildFollowupInstruction(String(value.harness_id), String(child.session_id)) && eligibleProviderChildOverload(child, value.parent_session_id)) {
+            issues.push({ code: "child_capacity_pending", work_id: link.work_id, session_id: child.session_id });
+            continue;
+        }
+        const pendingCheck = () => context.db.get("SELECT 1 FROM check_receipts WHERE project_id = ? AND run_id = ? AND work_id = ? AND status = 'running' LIMIT 1", [project.id, input.runId, link.work_id]);
+        if (pendingCheck()) {
+            const run = context.db.get("SELECT workspace_root, run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
+            try {
+                reconcileUnfinishedChecks(context, { projectId: project.id, runId: input.runId, workspaceRoot: run.workspace_root, runHome: run.run_root, workId: link.work_id });
+            }
+            catch (error) {
+                if (!(error instanceof AppError) || error.code !== "check_in_progress")
+                    throw error;
+            }
+            if (pendingCheck()) {
+                issues.push({ code: "child_check_in_progress", work_id: link.work_id });
+                continue;
+            }
+        }
+        if (context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created','running','paused') LIMIT 1", [link.work_id])) {
+            issues.push({ code: "child_descendants_unsettled", work_id: link.work_id });
+            continue;
+        }
+        if (child.status === "settled_by_root") {
+            issues.push({ code: "child_execution_outcome_unconfirmed", work_id: link.work_id, session_id: child.session_id });
+            continue;
+        }
+        if (child.status === "completed") {
+            issues.push({ code: "execution_ended_without_work_result", work_id: link.work_id, session_id: child.session_id });
+            continue;
+        }
+        const providerError = safeNativeFailure(child.provider_error);
+        const controller = nativeFailureController(context, project.id, input.runId, input.stage, value.parent_session_id);
+        const scope = stageGraphScope(context, project.id, input.runId, input.stage);
+        const terminalTime = typeof child.terminal_observed_at === "string" ? Date.parse(child.terminal_observed_at) : NaN;
+        const nativeBinding = child.status === "failed" && controller && typeof child.terminal_turn_id === "string" && child.terminal_turn_id.length > 0 && child.terminal_turn_id.length <= 256 && Number.isFinite(terminalTime)
+            ? { schema_id: "dd-flow/native-work-failure@1", project_id: project.id, run_id: input.runId, stage: input.stage, stage_attempt_id: scope.attempt, stage_cycle: scope.cycle,
+                parent_work_id: status.orchestration.parent_work_id, work_id: link.work_id, work_session_id: link.id, harness_id: value.harness_id,
+                parent_provider_session_id: value.parent_session_id, provider_session_id: String(child.session_id), terminal_turn_id: child.terminal_turn_id,
+                controller_id: controller.controller_id, generation: controller.generation } : undefined;
+        const reason = JSON.stringify({ source: "native_child_observation", harness_id: value.harness_id, session_id: child.session_id, work_session_id: link.id, outcome: child.status,
+            ...(nativeBinding ? { native_binding: nativeBinding } : {}),
+            ...(typeof child.terminal_turn_id === "string" ? { terminal_turn_id: child.terminal_turn_id } : {}),
+            ...(typeof child.terminal_observed_at === "string" ? { terminal_observed_at: child.terminal_observed_at } : {}),
+            ...(providerError ? { provider_error: providerError } : {}) });
+        const result = await (child.status === "failed" ? failWork : cancelWork)(context, link.work_id, reason);
+        reconciled.push({ work_id: link.work_id, work_session_id: link.id, outcome: child.status, ...(nativeBinding ? { native_binding: nativeBinding } : {}), result });
+    }
+    appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "native_child_reconciliation", stage: input.stage, observations: value, issues, reconciled });
+    return { ok: true, issues, reconciled };
+}
+/**
+ * Records every terminal native child at the Stage where it is first observed.
+ * This is separate from fan-out settlement: a historical child can be valid
+ * evidence for an earlier Work, while an unbound terminal child is retained
+ * as an inconsistency instead of being rediscovered in a later review wave.
+ */
+export function prepareNativeObservations(observations) {
+    const value = observations;
+    if (!value || typeof value.harness_id !== "string" || !value.harness_id.trim() || typeof value.parent_session_id !== "string" || !value.parent_session_id.trim() || !Array.isArray(value.children)
+        || value.children.some(child => !child || typeof child.session_id !== "string" || !child.session_id.trim() || typeof child.status !== "string" || !["running", "unknown", "completed", "failed", "cancelled", "settled_by_root"].includes(child.status) || child.parent_session_id !== undefined && typeof child.parent_session_id !== "string" || child.provenance !== undefined && !["root_child", "parent_mismatch"].includes(String(child.provenance))))
+        throw new AppError("usage", "Expected native observations: harness_id, parent_session_id and children[{session_id,status}]", 2);
+    if (new Set(value.children.map(child => child.session_id)).size !== value.children.length)
+        throw new AppError("usage", "Native observations must contain each child Session exactly once", 2);
+    return { harness_id: value.harness_id, parent_session_id: value.parent_session_id, children: value.children };
+}
+export function observeVnextNativeChildren(context, input) {
+    const value = prepareNativeObservations(input.observations);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const parent = storageSessionId({ harness_id: value.harness_id, session_id: value.parent_session_id });
+    const issues = [], history = [], pending = [];
+    for (const child of value.children) {
+        if (child.provenance === "parent_mismatch" || child.parent_session_id !== undefined && child.parent_session_id !== value.parent_session_id) {
+            issues.push({ code: "native_child_parent_mismatch", session_id: child.session_id, observed_parent_session_id: child.parent_session_id ?? null, expected_parent_session_id: value.parent_session_id, outcome: child.status, detected_at_stage: input.stage });
+            continue;
+        }
+        const sessionId = storageSessionId({ harness_id: value.harness_id, session_id: String(child.session_id) });
+        const links = context.db.all(`SELECT ws.id, ws.work_id, ws.status, w.status AS work_status, w.parent_work_id, s.current_stage
+         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`, [project.id, input.runId, sessionId, parent]);
+        if (child.status === "running" || child.status === "unknown") {
+            pending.push({ session_id: child.session_id, outcome: child.status, links: links.map(link => ({ work_id: link.work_id, work_session_id: link.id })) });
+            continue;
+        }
+        if (!links.length) {
+            issues.push({ code: "unbound_native_delegation_detected", session_id: child.session_id, outcome: child.status, detected_at_stage: input.stage, origin_stage: "unknown" });
+            continue;
+        }
+        if (links.length !== 1) {
+            issues.push({ code: "child_execution_ambiguous", session_id: child.session_id, outcome: child.status, detected_at_stage: input.stage, work_ids: links.map(link => link.work_id) });
+            continue;
+        }
+        const link = links[0];
+        history.push({ session_id: child.session_id, outcome: child.status, work_id: link.work_id, work_session_id: link.id, work_status: link.work_status, origin_stage: link.current_stage ?? "unknown", detected_at_stage: input.stage });
+    }
+    appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "native_child_observation", stage: input.stage, observations: value, issues, history, pending });
+    return { ok: true, issues, history, pending };
+}