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

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

@@ -0,0 +1,71 @@
+import { nativeContinuationSuccessor, nativeContinuationAdmitted } from "../harness-runtime/lib/native-children.mjs";
+/** The failure fence forbids fanout, not the exact retained child's recovery. */
+export function childCapacityDispatchAllowed(state, failures, parentId, operationId, promptSha256) {
+    return Object.entries(state.child_capacity ?? {}).some(([sessionId, intent]) => intent.operation_id === operationId
+        && intent.dispatched === true && intent.phase === "dispatched" && intent.prompt_sha256 === promptSha256
+        && failures.some(child => child.session_id === sessionId && child.parent_session_id === parentId
+            && child.status === "failed" && child.provenance !== "parent_mismatch" && child.terminal_turn_id === intent.turn_id));
+}
+/** An overloaded parent may have sent the message, but activity is not admission. */
+export function childCapacityRecoveryDecision(state, children, parentId, operationId, parentTurnId) {
+    const target = Object.entries(state.child_capacity ?? {}).find(([, intent]) => intent.operation_id === operationId);
+    if (!target)
+        return "reconciliation_blocked";
+    const child = children.find(item => item.session_id === target[0]);
+    if (child && (child.parent_session_id !== parentId || child.provenance === "parent_mismatch"))
+        return "reconciliation_blocked";
+    if (!child)
+        return "continue";
+    if (parentTurnId && child.continuation_admission?.parent_turn_id === parentTurnId && target[1].phase === "dispatched")
+        target[1].parent_turn_id = parentTurnId;
+    reconcileChildCapacity(state, [child], parentId);
+    if (["native_message_accepted", "successor_observed"].includes(target[1].phase ?? ""))
+        return "completed";
+    return child.status === "running" || child.terminal_turn_id && child.terminal_turn_id !== target[1].turn_id ? "reconciliation_blocked" : "continue";
+}
+/** Bind native admission to a durable managed parent Turn, never to child prose. */
+export function reconcileChildCapacity(state, children, parentId, observedAt = new Date().toISOString()) {
+    let changed = false;
+    for (const child of children) {
+        const intent = state.child_capacity?.[child.session_id], admission = child.continuation_admission;
+        if (!intent?.dispatched || !intent.operation_id || !intent.parent_turn_id || !intent.continuation_ref || !admission
+            || child.parent_session_id !== parentId || child.provenance === "parent_mismatch" || admission.parent_session_id !== parentId
+            || admission.parent_turn_id !== intent.parent_turn_id || admission.agent_id !== intent.continuation_ref.agent_id)
+            continue;
+        const bound = { ...admission, operation_id: intent.operation_id, predecessor_turn_id: intent.turn_id };
+        child.continuation_admission = bound;
+        const successor = nativeContinuationSuccessor(child, intent.turn_id, intent.continuation_ref.ended_at);
+        if (admission.proof_kind === "parent_tool_successor" && !successor)
+            continue;
+        if (admission.proof_kind === "parent_tool_admission" && !nativeContinuationAdmitted(child, intent.turn_id, intent.continuation_ref.ended_at))
+            continue;
+        const phase = successor ? "successor_observed" : "native_message_accepted";
+        if (intent.phase === "successor_observed" && !successor)
+            continue;
+        if (intent.phase !== phase || JSON.stringify(intent.admission) !== JSON.stringify(bound)) {
+            // A refreshed proof digest/status poll is not a new model signal.
+            if (intent.phase !== phase || !intent.last_signal_at)
+                intent.last_signal_at = observedAt;
+            intent.phase = phase;
+            intent.admission = bound;
+            changed = true;
+        }
+    }
+    return changed;
+}
+/** 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;
+        if (retained.continuation_ref && retained.phase !== "successor_observed")
+            continue;
+        retained.phase = "settled";
+        delete state.child_capacity[child.session_id];
+        closed.push(child.session_id);
+    }
+    return closed;
+}

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

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import { normalizeNativeChildren, safeNativeFailure, nativeContinuationSuccessor } from "../harness-runtime/lib/native-children.mjs";
+/** A durable observation is a dispatch fence, not authority to complete Work. */
+export function retainedChildObserver(input) {
+    let active = true, pending;
+    let gap = null;
+    const retained = new Map();
+    const sameScope = (scope) => scope?.controller_id === input.scope.controller_id && scope.generation === input.scope.generation && scope.stage === input.scope.stage && scope.root_session_id === input.scope.root_session_id;
+    const normalized = (child) => {
+        if (!child || child.parent_session_id !== input.scope.root_session_id || child.status !== "failed" || typeof child.terminal_turn_id !== "string" || ![child.session_id, child.terminal_turn_id, child.source].every(value => typeof value === "string" && value.length > 0 && value.length <= 256))
+            throw new Error("native_child_observation_invalid");
+        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.continuation_ref ? { continuation_ref: child.continuation_ref } : {}),
+            ...(child.recovery_unavailable_reason ? { recovery_unavailable_reason: child.recovery_unavailable_reason } : {}),
+            ...(child.continuation_admission ? { continuation_admission: child.continuation_admission } : {}),
+            ...(child.resumed_from_message_id ? { resumed_from_message_id: child.resumed_from_message_id } : {}),
+            ...(child.current_turn_id ? { current_turn_id: child.current_turn_id } : {}),
+            ...(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) => {
+        for (const raw of children) {
+            const child = normalized(raw);
+            retained.set(`${child.session_id}:${child.terminal_turn_id}`, child);
+        }
+    };
+    if (fs.existsSync(input.file))
+        for (const line of fs.readFileSync(input.file, "utf8").split("\n").filter(Boolean)) {
+            const observation = JSON.parse(line);
+            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;
+            }
+        }
+    const complete = (children) => {
+        if (!active)
+            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);
+        // 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
+            && (!old.continuation_ref && ["completed", "failed"].includes(child.status) && child.terminal_turn_id && child.terminal_turn_id !== old.terminal_turn_id
+                || nativeContinuationSuccessor(child, old.terminal_turn_id, old.continuation_ref?.ended_at)))).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, ...(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;
+            if (receipt.provider_session_id !== input.scope.root_session_id || receipt.observation_error || evidence?.observation_error || !evidence?.read?.projection || !evidence.read.session || !tree || tree.observation_error || !Array.isArray(tree.running))
+                return false;
+            if (tree.ended ? !Array.isArray(tree.ended.items) || tree.ended.total !== tree.ended.items.length || tree.ended.nextCursor : !Array.isArray(tree.completed))
+                return false;
+            const children = normalizeNativeChildren(receipt, input.scope.root_session_id);
+            if (children.some(child => child.status === "failed" && !child.terminal_turn_id))
+                return false;
+            complete(children);
+            return true;
+        },
+        tick() {
+            if (!active || pending)
+                return;
+            pending = (async () => {
+                const children = await input.read();
+                if (!active || children === null)
+                    return;
+                complete(children);
+            })().catch(error => {
+                if (!active)
+                    return;
+                try {
+                    input.assertOwner();
+                    const code = String(error?.code ?? "observation_unavailable");
+                    gap = /^[\w-]{1,128}$/.test(code) ? code : "observation_unavailable";
+                    const fd = fs.openSync(input.file, "a", 0o600);
+                    try {
+                        fs.writeSync(fd, `${JSON.stringify({ scope: input.scope, gap })}\n`);
+                        fs.fsyncSync(fd);
+                    }
+                    finally {
+                        fs.closeSync(fd);
+                    }
+                }
+                catch { /* Lost owner cannot publish; the gap remains an explicit caller error. */ }
+                input.gap(error);
+            }).finally(() => { pending = undefined; });
+        },
+        // The caller aborts its request; a late reply cannot publish after closure.
+        close() { active = false; return pending ?? Promise.resolve(); },
+    };
+}

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

@@ -0,0 +1,117 @@
+import { AppError } from "../shared/errors.js";
+import { renderNativeChildFollowupInstruction, renderWaitInstructions } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { nativeItemsSettled } from "../harness-runtime/lib/provider-overload-policy.mjs";
+import { parseLifecycleCommand } from "./lifecycle-command.js";
+import { storageSessionId } from "./session-identity.js";
+import { stageWorkIds } from "./stage-work-graph.js";
+import { appendEvent, digest } from "./run-controller-state.js";
+const blocked = (workId, reason, diagnostic = {}) => new AppError("child_work_repair_blocked", "Completed child has no safe automatic Work correction", 1, { work_id: workId, reason, reconciliation_required: true, effect: "no_effect", ...diagnostic });
+function progressKey(error) {
+    const failures = error.details.failures;
+    if (Array.isArray(failures) && failures.length) {
+        const inputs = failures.map((receipt) => typeof receipt.declaration_id === "string" && typeof receipt.command === "string" && typeof receipt.input_hash === "string"
+            ? [receipt.declaration_id, receipt.command, receipt.input_hash] : null);
+        return inputs.every(Boolean) ? digest([error.code, inputs.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)))]) : null;
+    }
+    return typeof error.details.input_key === "string" && typeof error.details.rejection_signature === "string"
+        ? digest([error.details.input_key, error.details.rejection_signature]) : null;
+}
+/** One durable correction per refusal/successor, not a provider retry or a new worker. */
+export function completedChildRepair(context, row, input) {
+    const members = stageWorkIds(context, row.project_id, row.run_id, input.stage);
+    for (const child of input.children) {
+        if (child.status !== "completed")
+            continue;
+        const links = context.db.all(`SELECT w.work_id,w.status FROM work_sessions ws
+      JOIN works w ON w.work_id=ws.work_id JOIN sessions s ON s.session_id=ws.session_id AND s.project_id=w.project_id
+      WHERE w.project_id=? AND w.run_id=? AND ws.session_id=? AND s.parent_session_id=?`, [row.project_id, row.run_id, storageSessionId({ harness_id: input.harness, session_id: child.session_id }), storageSessionId({ harness_id: input.harness, session_id: input.parentId })])
+            .filter(link => members.has(link.work_id));
+        if (!links.some(link => link.status === "running"))
+            continue;
+        if (links.length !== 1 || child.parent_session_id !== input.parentId || child.provenance === "parent_mismatch"
+            || !child.terminal_turn_id || !nativeItemsSettled(child.native_turn_items))
+            throw blocked(links[0].work_id, "native_identity_unconfirmed");
+        const workId = links[0].work_id;
+        if (context.db.get("SELECT 1 FROM check_receipts WHERE project_id=? AND run_id=? AND work_id=? AND status='running' LIMIT 1", [row.project_id, row.run_id, workId]))
+            continue;
+        if (context.db.get("SELECT 1 FROM works WHERE parent_work_id=? AND status IN ('created','running','paused') LIMIT 1", [workId]))
+            throw blocked(workId, "descendants_unsettled");
+        const reservations = context.db.all(`SELECT e.controller_id,e.data_json FROM run_controller_events e
+      JOIN run_controllers c ON c.controller_id=e.controller_id WHERE c.project_id=? AND c.run_id=?
+      AND e.event_type='work_repair_reserved' AND json_extract(e.data_json,'$.work_id')=? ORDER BY e.sequence DESC`, [row.project_id, row.run_id, workId]);
+        const refusals = context.db.all("SELECT id,command,scope_json,identity_json,outcome_json FROM lifecycle_invocations WHERE status='settled' AND json_extract(outcome_json,'$.error.details.work_id')=? ORDER BY rowid DESC", [workId]);
+        const refusal = refusals.find(attempt => {
+            try {
+                const scope = JSON.parse(attempt.scope_json), identity = JSON.parse(attempt.identity_json ?? "null");
+                const parsed = parseLifecycleCommand(attempt.command);
+                return attempt.scope_json === context.env.DD_FLOW_INVOCATION_SCOPE && parsed.kind === "standalone" && parsed.invocation.operation === "work_finish" && scope.runId === row.run_id
+                    && scope.generation === row.generation && scope.rootSessionId === input.parentId
+                    && Array.isArray(identity) && identity[2] === child.session_id && identity[3] === input.parentId;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!refusal)
+            throw blocked(workId, "repair_refusal_missing");
+        const outcome = JSON.parse(refusal.outcome_json), error = outcome.error, details = error?.details;
+        const diagnostic = { refusal_invocation_id: refusal.id, successor_invocation_id: outcome.successor_invocation_id, primary_error: { code: error?.code, message: error?.message } };
+        // Reattach the exact durable episode before admitting a new one. A new
+        // terminal Turn/UUID alone never authorizes a second delivery.
+        for (const previous of reservations) {
+            const retained = JSON.parse(previous.data_json);
+            const operation = context.db.get("SELECT status FROM run_controller_operations WHERE operation_id=?", [retained.operation_id]);
+            const sameEpisode = retained.refusal_invocation_id === refusal.id && retained.successor_invocation_id === outcome.successor_invocation_id;
+            if (operation?.status !== "completed" && operation?.status !== "failed") {
+                if (previous.controller_id !== row.controller_id || retained.generation !== row.generation || retained.child_session_id !== child.session_id)
+                    throw blocked(workId, "followup_owner_unconfirmed", { ...diagnostic, operation_id: retained.operation_id });
+                return retained;
+            }
+            if (sameEpisode)
+                throw blocked(workId, "followup_admission_unconfirmed", { ...diagnostic, operation_id: retained.operation_id });
+        }
+        if (details?.effect !== "no_effect" || details.recoverable !== true || typeof details.retry_command !== "string"
+            || typeof outcome.successor_invocation_id !== "string")
+            throw blocked(workId, "repair_successor_unproven", diagnostic);
+        const successor = context.db.get("SELECT scope_json,status FROM lifecycle_invocations WHERE id=?", [outcome.successor_invocation_id]);
+        if (successor?.status !== "issued" || successor.scope_json !== refusal.scope_json)
+            throw blocked(workId, "repair_successor_not_issued", diagnostic);
+        const progress = progressKey(error);
+        if (!progress)
+            throw blocked(workId, "repair_progress_unproven", diagnostic);
+        if (reservations.some(previous => {
+            const retained = JSON.parse(previous.data_json);
+            // Legacy episodes without a binding cannot prove a new correction.
+            return !retained.progress_key || retained.progress_key === progress;
+        }))
+            throw blocked(workId, "repeated_without_progress", diagnostic);
+        const instruction = renderNativeChildFollowupInstruction(input.harness, child, { purpose: "work_repair", context: JSON.stringify({ work_id: workId, code: error.code, message: error.message, retry_command: details.retry_command }) });
+        if (!instruction)
+            throw blocked(workId, "same_child_repair_unsupported", diagnostic);
+        return { work_id: workId, generation: row.generation, child_session_id: child.session_id, terminal_turn_id: child.terminal_turn_id, refusal_invocation_id: refusal.id,
+            successor_invocation_id: outcome.successor_invocation_id, progress_key: progress,
+            operation_id: `${row.controller_id}:work-repair:${digest([row.run_id, workId, row.generation, refusal.id, outcome.successor_invocation_id])}`,
+            prompt: `Continue only the existing child for this unfinished Work. This is one bound correction, not a new fanout wave.\n${instruction}\n\nA follow-up submission acknowledgement or the child's previous completed Turn is not completion of this correction. Wait for this same child's follow-up; never resend the message to poll it.\n${renderWaitInstructions({ harness: input.harness, stage: input.stage })}` };
+    }
+    return null;
+}
+export function reserveChildRepair(context, row, repair, assertOwner) {
+    context.db.writeTransaction(() => {
+        assertOwner();
+        if (repair.generation !== row.generation)
+            throw blocked(repair.work_id, "generation_changed_before_followup");
+        const work = context.db.get("SELECT status FROM works WHERE project_id=? AND run_id=? AND work_id=?", [row.project_id, row.run_id, repair.work_id]);
+        if (work?.status !== "running")
+            throw blocked(repair.work_id, "work_changed_before_followup");
+        const reserved = context.db.get(`SELECT e.controller_id,e.data_json FROM run_controller_events e JOIN run_controllers c ON c.controller_id=e.controller_id
+      WHERE c.project_id=? AND c.run_id=? AND e.event_type='work_repair_reserved' AND json_extract(e.data_json,'$.successor_invocation_id')=?`, [row.project_id, row.run_id, repair.successor_invocation_id]);
+        if (reserved && (reserved.controller_id !== row.controller_id || reserved.data_json !== JSON.stringify(repair)))
+            throw blocked(repair.work_id, "episode_reserved_by_another_dispatch");
+        if (!reserved) {
+            const successor = context.db.get("SELECT status FROM lifecycle_invocations WHERE id=?", [repair.successor_invocation_id]);
+            if (successor?.status !== "issued")
+                throw blocked(repair.work_id, "successor_changed_before_followup");
+            appendEvent(context, row.controller_id, "work_repair_reserved", repair);
+        }
+    });
+}

package/dist/services/controller-execution.js

@@ -0,0 +1,97 @@
+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";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.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, workspaceRoot) {
+    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(currentRun?.workspace_root ?? workspaceRoot ?? 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) {
+    const boundDistill = run.flow_kind === "mb-distill" && JSON.parse(run.index_json).execution_bundle?.flow_id === "mb-distill";
+    const boundDelivery = isDeliveryFlow(run.flow_kind) && JSON.parse(run.index_json).execution_bundle?.flow_id === run.flow_kind;
+    if (manifest?.schema_id === "dd-flow/run-controller-manifest@2" || ["mb-init", "mb-upgrade", "mb-fix", "review-fix", "interactive"].includes(run.flow_kind) || isDiagnosticFlow(run.flow_kind) || boundDistill || boundDelivery) {
+        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);
+        }
+        // Bundle admission has already checked the current RUN workspace against
+        // its trusted relocation receipts; frozen scope remains historical input.
+        return { ...genericControllerRouting(bundle.execution, run.workspace_root), 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 } : {}) });
+        }
+    };
+}