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

package/dist/services/run-controller.js

@@ -38,12 +38,14 @@ import { assertNoCorrelatedRejection } from "./continuation-outcome.js";
 import { spawnController, recordControllerLauncher, claimControllerProcess, markControllerDispatchReady, assertControllerLeaseAllowed } from "./run-controller-process.js";
 import { controllerAdapter, controllerEnvironment, sessionArguments } from "./run-controller-adapter.js";
 import { retainedChildObserver } from "./controller-child-observer.js";
-import { capacityDelay, continueCodexCapacity, eligibleCodexChildOverload } from "./codex-capacity.js";
+import { capacityDelay, continueProviderCapacity, eligibleProviderChildOverload, providerChildFailure } from "./provider-capacity.js";
 import { resumeControllerSession, failControllerRecovery } from "./run-controller-recovery.js";
 import { captureControllerBoundary } from "./run-controller-capture.js";
 import { requestRunControl } from "./run-control-worker.js";
 import { storageSessionId } from "./session-identity.js";
-import { CAPACITY_POLICY, nativeItemsSettled, overloadBurst, refusalObservation, terminalCodexOverload } from "../harness-runtime/lib/codex-capacity-policy.mjs";
+import { CAPACITY_POLICY, nativeItemsSettled, overloadExhausted, refusalObservation, terminalProviderOverload } from "../harness-runtime/lib/provider-overload-policy.mjs";
+import { renderNativeChildFollowupInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { closeSuccessfulChildCapacity } from "./controller-child-capacity.js";
 import { isObservationLoss } from "../harness-runtime/lib/operation-errors.mjs";
 export { resumeRunController } from "./run-controller-recovery.js";
 const preparedLaunchInputs = new WeakMap();
@@ -247,7 +249,10 @@ export async function serveRunController(context, input) {
         lease.assertNoRenewal();
         if (state.merge_claim)
             mergeLease.assertNoRenewal();
-        assertManagedProcessLease({ ...context, databaseDeadlineAt: Date.now() + 5_000 }, { id: row.process_id, leaseToken: row.process_lease_token, pid: process.pid });
+        // This isolated read already bounds SQLite contention. A wall deadline
+        // before opening the reader mistakes scheduler delay for heartbeat loss;
+        // the observed row's actual expiry/token still fences productive dispatch.
+        assertManagedProcessLease(context, { id: row.process_id, leaseToken: row.process_lease_token, pid: process.pid });
         const current = requireController(context, row.controller_id);
         if (current.owner_pid !== process.pid || current.owner_token !== row.owner_token || !["running", "capturing", "waiting_for_user", "waiting_for_context", "waiting_for_children", "waiting_for_capacity", "waiting_for_merge"].includes(current.status))
             throw new AppError("controller_owner_mismatch", "Controller no longer owns productive dispatch", 1);
@@ -681,14 +686,12 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 }
             }
             catch (error) {
-                if (!["codex-desktop", "opencode-server"].includes(runtimeHarness(session.profile)))
-                    throw error;
                 const resumeCommand = hitl ? text.split("\n\n")[1] : undefined;
                 if (hitl && !resumeCommand?.includes(" stage resume "))
                     throw error;
                 const inspect = (args, id) => runHarnessAdapter({ executable: manifest.adapters[runtimeHarness(session.profile)].executable,
                     args, env: controllerEnvironment(context, manifest, session), runtimeOwner: session.owner, operationId: id, timeoutMs: 30_000, signal: cancellation.signal });
-                const resumed = await continueCodexCapacity({ error, sessionId: session.id, operationId: firstOperationId, signal: cancellation.signal, allowSettledDescendants: true, atomicIntent: true,
+                const resumed = await continueProviderCapacity({ error, sessionId: session.id, operationId: firstOperationId, signal: cancellation.signal, allowSettledDescendants: true, atomicIntent: true,
                     retainedIntents: () => context.db.all("SELECT receipt_json FROM run_controller_operations WHERE controller_id = ? AND generation = ?", [row.controller_id, row.generation])
                         .flatMap(item => { const retained = JSON.parse(item.receipt_json || "null"); return retained?.capacity_intent?.root_operation_id === firstOperationId ? [retained.capacity_intent] : []; }).sort((a, b) => a.ordinal - b.ordinal),
                     retainedFailures: () => context.db.all("SELECT receipt_json FROM run_controller_operations WHERE controller_id = ? AND generation = ?", [row.controller_id, row.generation])
@@ -874,7 +877,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 loadExternalStageContext({ file: stageContext.file, expectedSha256: stageContext.sha256, stage: next.stage });
                 const continuation = JSON.stringify(["start_stage", next.stage, next.attempt ?? null]);
                 retainControllerContinuation(state, continuation, { code: "stage_entry_nonprogressing", message: "The coordinator returned without starting the assigned Stage", details: { stage: next.stage, attempt: next.attempt ?? null, last_receipt: state.last_receipt ?? null } });
-                const transition = routing.transition(next.stage, state.stage ?? undefined);
+                const transition = routing.transition(next.stage, state.stage ?? undefined, run);
                 if (routing.kind === "sdlc" && next.stage === "merge" && routing.mergeMode === "server" && !state.merge_claim) {
                     const request = context.db.get("SELECT merge_request_id, status FROM merge_requests WHERE project_id = ? AND run_id = ? ORDER BY created_at DESC, merge_request_id DESC LIMIT 1", [row.project_id, row.run_id]);
                     if (!request || request.status !== "queued")
@@ -890,7 +893,22 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     appendEvent(context, row.controller_id, "merge_claimed", { request_id: claim.request.merge_request_id });
                     await renewLease();
                 }
-                const stageCwd = routing.cwd(next.stage, state.merge_claim?.target_workspace);
+                const stageCwd = routing.cwd(next.stage, state.merge_claim?.target_workspace, run);
+                const routeBinding = (current) => {
+                    const index = JSON.parse(current.index_json);
+                    return JSON.stringify([current.project_root, current.workspace_root, index.workspace_route ?? null, state.merge_claim ?? null]);
+                };
+                const preparedRoute = routeBinding(run);
+                const assertRoute = async () => {
+                    assertOwner();
+                    if (routeBinding(requireRun(context, row.project_id, row.run_id)) !== preparedRoute) {
+                        const current = state.current_session === null ? null : state.sessions[state.current_session];
+                        if (current && !current.stopped)
+                            await stopSession(current);
+                        throw new AppError("workspace_route_changed", "RUN workspace changed during native Session preparation", 1, { effect: "no_effect", stage: next.stage });
+                    }
+                };
+                await assertRoute();
                 let session = state.current_session === null ? null : state.sessions[state.current_session];
                 if (session && routing.kind === "sdlc" && next.stage === "merge" && routing.mergeMode === "same_session" && path.resolve(session.cwd) !== stageCwd) {
                     throw new AppError("merge_session_workspace_conflict", "Same-session MERGE cannot change the native Session working directory", 1, { session_cwd: session.cwd, target_cwd: stageCwd });
@@ -942,6 +960,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 }
                 const responseFile = path.join(row.state_dir, `${next.stage}-${next.attempt ?? 1}.stage-start-response.json`);
                 const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage start ${run.id} --stage ${next.stage} --project-root ${JSON.stringify(run.project_root)} --context-file ${JSON.stringify(stageContext.file)} --context-sha256 ${stageContext.sha256} --require-session-binding --response-file ${JSON.stringify(responseFile)} --json --progress-jsonl`);
+                await assertRoute();
                 appendEvent(context, row.controller_id, "stage_entered", { stage: next.stage, session_id: session.id, context_sha256: stageContext.sha256 });
                 await prompt(session, controllerStageEntryPrompt(next.stage, command));
                 continue;
@@ -949,11 +968,19 @@ async function executeController(context, row, manifest, state, assertOwnership,
             if (state.current_session === null)
                 throw new AppError("controller_attach_required", "An unfinished Stage has no managed coordinator", 1);
             const session = state.sessions[state.current_session];
+            const childHarness = runtimeHarness(session.profile);
             const baseline = new Set(state.native_baseline ?? []);
             let children = controllerNativeChildren(state.last_receipt ?? {}, session.id).filter(child => !baseline.has(child.session_id));
+            childObserver(session)?.observeSettledChildren(children);
             const retainedFailures = childObserver(session)?.failed() ?? [];
             children = controllerNativeChildren({ descendants: [...children, ...retainedFailures] }, session.id);
-            if (runtimeHarness(session.profile) === "codex-desktop" && children.some(child => child.status === "failed")) {
+            const closedChildEpisodes = closeSuccessfulChildCapacity(state, children, session.id);
+            if (closedChildEpisodes.length)
+                await prepareMutation(() => {
+                    saveState(context, row, state);
+                    appendEvent(context, row.controller_id, "capacity_child_episodes_completed", { child_session_ids: closedChildEpisodes });
+                });
+            if (children.some(child => child.status === "failed" && renderNativeChildFollowupInstruction(childHarness, child.session_id))) {
                 const inspected = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
                 state.last_receipt = inspected;
                 saveState(context, row, state);
@@ -961,32 +988,31 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 const failed = children.filter(child => child.status === "failed");
                 // Freeze each distinct child refusal on its first exact observation,
                 // even while a healthy sibling still owns an active native Turn.
-                for (const failedChild of failed.filter(item => eligibleCodexChildOverload(item, session.id))) {
-                    const linked = context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: "codex-desktop", session_id: failedChild.session_id })]);
+                for (const failedChild of failed.filter(item => eligibleProviderChildOverload(item, session.id))) {
+                    const linked = context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: childHarness, session_id: failedChild.session_id })]);
                     if (linked.length > 1 || linked.some(link => link.status !== "running"))
                         continue;
                     const retained = state.child_capacity?.[failedChild.session_id];
                     const refusals = [...(retained?.refusals ?? [])];
                     if (refusals.some(item => item.turn_id === failedChild.terminal_turn_id))
                         continue;
-                    const nativeFailure = { code: "turn_interrupted", details: { provider_session_id: failedChild.session_id, turn_id: failedChild.terminal_turn_id, native_turn_id: failedChild.terminal_turn_id, terminal_status: "failed", provider_error: failedChild.provider_error, observed_at: failedChild.terminal_observed_at } };
+                    const nativeFailure = providerChildFailure(failedChild);
                     refusals.push(refusalObservation(nativeFailure, retained?.attempts ?? 0, failedChild.terminal_observed_at ?? context.now()));
                     state.child_capacity ??= {};
                     state.child_capacity[failedChild.session_id] = { ...retained, turn_id: retained?.turn_id ?? failedChild.terminal_turn_id, attempts: retained?.attempts ?? 0, policy: CAPACITY_POLICY, refusals };
                     await prepareMutation(() => { saveState(context, row, state); appendEvent(context, row.controller_id, "capacity_child_refusal", { child_session_id: failedChild.session_id, refusal: refusals.at(-1) }); });
-                    const burst = overloadBurst(refusals);
-                    if (burst)
-                        throw new AppError("provider_overload_burst", "Native child had two continuation refusals within two minutes", 1, { ...burst, child_session_id: failedChild.session_id, primary_error: nativeFailure });
+                    const exhausted = overloadExhausted(refusals);
+                    if (exhausted)
+                        throw new AppError("provider_unavailable", "Native child exhausted its overload continuation attempts", 1, { ...exhausted, reason: "overload_retries_exhausted", child_session_id: failedChild.session_id, primary_error: nativeFailure });
                 }
                 // Continue one existing child at a time; another failed child does not
                 // create a second fanout wave or share this child's refusal counter.
-                const child = children.every(item => item.status === "failed" || item.status === "completed") ? failed.find(item => item.parent_session_id === session.id && item.terminal_turn_id && nativeItemsSettled(item.native_turn_items) && terminalCodexOverload({ code: "turn_interrupted", details: { provider_session_id: item.session_id, turn_id: item.terminal_turn_id, native_turn_id: item.terminal_turn_id, terminal_status: "failed", provider_error: item.provider_error } }, item.session_id)) : undefined;
+                const child = children.every(item => item.status === "failed" || item.status === "completed") ? failed.find(item => renderNativeChildFollowupInstruction(childHarness, item.session_id) && eligibleProviderChildOverload(item, session.id)) : undefined;
                 const turnId = child?.terminal_turn_id;
-                const native = child && turnId ? { code: "turn_interrupted", details: { provider_session_id: child.session_id, turn_id: turnId, native_turn_id: turnId,
-                        terminal_status: "failed", provider_error: child.provider_error, observed_at: child.terminal_observed_at } } : null;
+                const native = child && turnId ? providerChildFailure(child) : null;
                 const prior = child && state.child_capacity?.[child.session_id];
-                const links = child ? context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: "codex-desktop", session_id: child.session_id })]) : [];
-                if (child && turnId && native && terminalCodexOverload(native, child.session_id, turnId)
+                const links = child ? context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: childHarness, session_id: child.session_id })]) : [];
+                if (child && turnId && native && terminalProviderOverload(native, child.session_id, turnId)
                     && nativeItemsSettled(child.native_turn_items)
                     && inspected.settled === true && child.parent_session_id === session.id && links.length <= 1
                     && (!links.length || links[0].status === "running")) {
@@ -1004,10 +1030,17 @@ async function executeController(context, row, manifest, state, assertOwnership,
                         state.child_capacity[child.session_id] = { ...prior, turn_id: prior?.turn_id ?? turnId, attempts: prior?.attempts ?? 0, policy: CAPACITY_POLICY, refusals };
                         saveState(context, row, state);
                     }
-                    const burst = overloadBurst(refusals);
-                    if (burst)
-                        throw new AppError("provider_overload_burst", "Native child had two continuation refusals within two minutes", 1, { ...burst, child_session_id: child.session_id, primary_error: native });
-                    const wait = prepared ? Math.max(0, Date.parse(prepared.not_before) - Date.now()) : capacityDelay(native, attempt);
+                    const exhausted = overloadExhausted(refusals);
+                    if (exhausted)
+                        throw new AppError("provider_unavailable", "Native child exhausted its overload continuation attempts", 1, { ...exhausted, reason: "overload_retries_exhausted", child_session_id: child.session_id, primary_error: native });
+                    let wait;
+                    try {
+                        wait = prepared ? Math.max(0, Date.parse(prepared.not_before) - Date.now()) : capacityDelay(native, attempt);
+                    }
+                    catch (error) {
+                        const failure = error;
+                        throw new AppError(failure.code ?? "capacity_retry_metadata_invalid", failure.message ?? "Invalid child retry delay", 1, { ...failure.details, child_session_id: child.session_id, root_operation_id: prior?.root_operation_id ?? null, attempts: refusals.length, primary_error: native });
+                    }
                     if (!Number.isFinite(wait) || Date.now() + wait > 8.64e15)
                         throw new AppError("capacity_retry_metadata_invalid", "Native child retry time is invalid", 1, { child_session_id: child.session_id, delay_ms: wait });
                     const rootOperationId = prior?.root_operation_id ?? `${row.controller_id}:child:${digest([child.session_id, turnId]).slice(0, 16)}`;
@@ -1030,7 +1063,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                         throw new AppError("capacity_child_followup_blocked", "RUN changed during native child capacity wait", 1, { child_session_id: child.session_id });
                     const fresh = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
                     const still = controllerNativeChildren(fresh, session.id).find(item => item.session_id === child.session_id);
-                    const currentLinks = context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: "codex-desktop", session_id: child.session_id })]);
+                    const currentLinks = context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: childHarness, session_id: child.session_id })]);
                     if (currentLinks.length === 1 && ["completed", "cancelled", "paused"].includes(currentLinks[0].status)) {
                         state.last_receipt = fresh;
                         saveState(context, row, state);
@@ -1042,7 +1075,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                         throw new AppError("capacity_child_followup_blocked", "Native child or Work changed during capacity wait", 1, { child_session_id: child.session_id, turn_id: turnId });
                     await renewLease();
                     assertOwner();
-                    const text = `The existing native child ${child.session_id} has a confirmed terminal overloaded Turn. Use the native followup_task tool exactly once for that same child ID with this short message: "Continue your assigned Work from its current durable state. Do not repeat an observed lifecycle command. Finish only the original Work." Do not spawn another child, claim another Work, or perform the child's Work in this parent Turn. End this Turn after the followup_task response.`;
+                    const text = renderNativeChildFollowupInstruction(childHarness, child.session_id);
                     await prompt(session, text, operationId, "child");
                     state.child_capacity[child.session_id].dispatched = true;
                     saveState(context, row, state);

package/dist/services/run-recovery-guard.js

@@ -1,5 +1,5 @@
 import { AppError } from "../shared/errors.js";
-import { CAPACITY_POLICY, overloadBurst } from "../harness-runtime/lib/codex-capacity-policy.mjs";
+import { CAPACITY_POLICY, MAX_OVERLOAD_RETRIES, overloadExhausted } from "../harness-runtime/lib/provider-overload-policy.mjs";
 import { assertRunStartupSettled } from "./run-start-custody.js";
 export function recoveryGuard(context, projectId, runId) { return context.db.get("SELECT recovery_id, project_id, run_id, generation, status, interruption_json, settlement_json, capture_path, created_at, updated_at, sealed_at, resumed_at FROM run_recovery_guards WHERE project_id = ? AND run_id = ? ORDER BY generation DESC LIMIT 1", [projectId, runId]) ?? null; }
 export function assertRunRecoveryAllowed(context, projectId, runId, expectedGeneration) {
@@ -43,7 +43,7 @@ export function recoveryRuntimeAdmission(context, record, input) {
     if (active) {
         const ordinal = dispatch.capacity_intents.length;
         const predecessor = ordinal === 1 ? dispatch.operation_id : dispatch.capacity_intents[ordinal - 2].operation_id;
-        if (active.policy !== CAPACITY_POLICY || active.ordinal !== ordinal || active.root_operation_id !== dispatch.operation_id || active.session_id !== binding.provider_session_id
+        if (ordinal > MAX_OVERLOAD_RETRIES || active.policy !== CAPACITY_POLICY || active.ordinal !== ordinal || active.root_operation_id !== dispatch.operation_id || active.session_id !== binding.provider_session_id
             || active.predecessor !== predecessor || active.operation_id !== `${dispatch.operation_id}:capacity:${ordinal}:session.prompt`
             || active.refusal?.policy !== CAPACITY_POLICY || active.refusal.ordinal !== ordinal - 1 || active.refusal.turn_id !== active.turn_id
             || active.refusal.session_id !== binding.provider_session_id || active.deadline !== null || !Number.isFinite(Date.parse(active.not_before)))
@@ -52,7 +52,7 @@ export function recoveryRuntimeAdmission(context, record, input) {
         if (!failure || JSON.stringify(failure) !== JSON.stringify(active.refusal))
             return false;
         try {
-            if (overloadBurst(dispatch.capacity_failures))
+            if (overloadExhausted(dispatch.capacity_failures))
                 return false;
         }
         catch {

package/dist/services/run-recovery-runtime.js

@@ -8,7 +8,7 @@ import { managedProcessBinding, processIsAlive, resourceHome } from "./managed-p
 import { getResourceDatabase } from "../storage/database.js";
 import { requireManagedDaemonBinding } from "./managed-daemon-binding.js";
 import { lifecycleRetryInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
-import { CAPACITY_POLICY, overloadBurst } from "../harness-runtime/lib/codex-capacity-policy.mjs";
+import { CAPACITY_POLICY, MAX_OVERLOAD_RETRIES, overloadExhausted } from "../harness-runtime/lib/provider-overload-policy.mjs";
 /** Pin retained Session loading and its first acknowledgement Turn, never a general fence bypass. */
 export function prepareRunRecoveryDispatch(context, input) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(input.operationId) || !path.isAbsolute(input.stateDir))
@@ -60,7 +60,7 @@ export function prepareRunRecoveryDispatch(context, input) {
 /** Publish only an exact successor to a failed, effect-free recovery ACK Turn. */
 export function retainRecoveryCapacityIntent(context, input) {
     const { intent } = input;
-    if (!Number.isSafeInteger(intent.ordinal) || intent.ordinal < 1 || !intent.turn_id || !Number.isFinite(Date.parse(intent.not_before)) || intent.policy !== CAPACITY_POLICY
+    if (!Number.isSafeInteger(intent.ordinal) || intent.ordinal < 1 || intent.ordinal > MAX_OVERLOAD_RETRIES || !intent.turn_id || !Number.isFinite(Date.parse(intent.not_before)) || intent.policy !== CAPACITY_POLICY
         || !intent.refusal || intent.refusal.policy !== CAPACITY_POLICY || intent.refusal.ordinal !== intent.ordinal - 1 || intent.refusal.turn_id !== intent.turn_id
         || !Number.isFinite(Date.parse(intent.refusal.first_observed_at)) || intent.deadline !== null)
         throw new AppError("recovery_capacity_intent_invalid", "Recovery capacity successor is invalid", 1);
@@ -91,7 +91,7 @@ export function retainRecoveryCapacityIntent(context, input) {
         }
         const refusals = dispatch.capacity_failures ?? [];
         const observed = refusals.find(item => item.ordinal === intent.refusal.ordinal);
-        if (!observed || JSON.stringify(observed) !== JSON.stringify(intent.refusal) || overloadBurst(refusals))
+        if (!observed || JSON.stringify(observed) !== JSON.stringify(intent.refusal) || overloadExhausted(refusals))
             throw new AppError("recovery_capacity_intent_conflict", "Recovery successor lacks an immutable non-burst refusal binding", 1);
         const predecessor = intent.ordinal === 1 ? dispatch.operation_id : prior[intent.ordinal - 2]?.operation_id;
         if (prior.length !== intent.ordinal - 1 || predecessor !== intent.predecessor || intent.operation_id !== `${dispatch.operation_id}:capacity:${intent.ordinal}:session.prompt`)

package/dist/services/runs.js

@@ -26,6 +26,7 @@ import { flowCommand } from "./stage-pause.js";
 import { RetainedExecutionBundle } from "./execution-bundles.js";
 import { admitBundledFlow, bundledHandlerContext } from "./stage-handlers.js";
 import { hybridDigest } from "./hybrid-contracts.js";
+import { projectPacketLocators, runContextRelocations } from "./stage-context.js";
 const runSchemaId = "dd-flow/flow-run@3";
 const runtimeSchemaId = "dd-flow/flow-run@3";
 const allowedRunFlowKinds = [
@@ -284,20 +285,82 @@ export function importFlowRunExecutionProfile(context, input) {
 export function rebindFlowRunWorkspace(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    assertRunMutationAllowed(context, project.id, run.id);
+    const generation = assertRunMutationAllowed(context, project.id, run.id, input.expectedGeneration);
     const workspaceRoot = resolveWorkspaceRoot(input.workspaceRoot);
     const index = authoritativeIndex(run);
+    const receipt = input.routeReceipt ? { ...input.routeReceipt, policy: { ...input.routeReceipt.policy,
+            worktree_path: input.routeReceipt.policy.worktree_path ? resolveWorkspaceRoot(input.routeReceipt.policy.worktree_path) : null } } : undefined;
+    if (index.execution_bundle && !["vnext_specify", "vnext_protocolize"].includes(run.flow_kind)) {
+        if (workspaceRoot === run.workspace_root)
+            return { ok: true, changed: false };
+        throw new AppError("workspace_route_invalid", "Only SDLC may provision a different RUN workspace", 1, { effect: "no_effect" });
+    }
+    if (workspaceRoot === run.workspace_root) {
+        if (receipt && index.workspace_route && hybridDigest(retainedWorkspaceRoute(context, run).receipt) !== hybridDigest(receipt)) {
+            throw new AppError("workspace_route_conflict", "Committed workspace route differs from the repeated request", 1, { effect: "no_effect" });
+        }
+        publishRunProjections(context, project.id, run.id);
+        return { ok: true, changed: false, workspace_root: workspaceRoot };
+    }
+    if (index.workspace_route)
+        throw new AppError("workspace_route_conflict", "RUN already has a committed workspace route", 1, { effect: "no_effect" });
+    if (input.expectedRevision !== undefined && (index.runtime_revision ?? 0) !== input.expectedRevision)
+        throw new AppError("run_revision_changed", "RUN changed while its workspace was provisioned", 1, { effect: "no_effect", expected_revision: input.expectedRevision, actual_revision: index.runtime_revision ?? 0 });
+    if (index.execution_bundle && !receipt)
+        throw new AppError("workspace_route_missing", "Bundled SDLC rebind requires its prepared route receipt", 1, { effect: "no_effect" });
+    if (receipt && (run.workspace_root !== project.root || receipt.schema_id !== "dd-flow/vnext-workspace-route@1" || receipt.policy.route !== "feature_worktree"
+        || !receipt.policy.provisioned || receipt.policy.worktree_path !== workspaceRoot || !receipt.created || !receipt.bootstrap)) {
+        throw new AppError("workspace_route_invalid", "Prepared workspace route does not match this RUN", 1, { effect: "no_effect" });
+    }
     const now = context.now();
     const facts = gitFacts(workspaceRoot);
+    if (receipt && (facts.branch !== receipt.policy.feature_branch || !receipt.policy.base_ref || !facts.head
+        || spawnSync("git", ["-C", workspaceRoot, "merge-base", "--is-ancestor", receipt.policy.base_ref, facts.head]).status !== 0)) {
+        throw new AppError("workspace_route_invalid", "Prepared checkout differs from the feature branch/base receipt", 1, { effect: "no_effect", run_id: run.id });
+    }
     index.workspace = { ...index.workspace, workspace_path: workspaceRoot, branch: facts.branch ?? "unknown", base: facts.head ?? "unknown", manager: "official-worktrunk" };
     index.execution = { ...index.execution, project_root: project.root, workspace_root: workspaceRoot, git: facts };
     index.updated_at = now;
-    context.db.run("UPDATE runs SET workspace_root = ? WHERE project_id = ? AND id = ?", [workspaceRoot, project.id, run.id]);
-    persistRunState(context, project, { ...run, workspace_root: workspaceRoot }, index);
-    appendAudit(context, { projectId: project.id, eventType: "flow_run.workspace_rebound", payload: { run_id: run.id, workspace_root: workspaceRoot, reason: input.reason } });
-    appendRunTimeline(context, project.id, run.id, { at: now, type: "workspace_rebound", run_id: run.id, workspace_root: workspaceRoot, reason: input.reason, git: facts });
+    const route = receipt ? { schema_id: "dd-flow/run-workspace-route@1", run_id: run.id, project_id: project.id, project_root: project.root,
+        generation, previous_workspace: run.workspace_root, workspace_root: workspaceRoot, revision: (index.runtime_revision ?? 0) + 1,
+        git: facts, receipt, receipt_sha256: hybridDigest(receipt) } : undefined;
+    if (route)
+        index.workspace_route = { revision: route.revision, sha256: hybridDigest(route) };
+    context.db.writeTransaction(() => {
+        assertRunMutationAllowed(context, project.id, run.id, generation);
+        const latest = resolveRun(context, project.id, run.id);
+        if (latest.workspace_root !== run.workspace_root)
+            throw new AppError("workspace_route_changed", "RUN route changed during preparation", 1, { effect: "no_effect" });
+        context.db.run("UPDATE runs SET workspace_root = ? WHERE project_id = ? AND id = ?", [workspaceRoot, project.id, run.id]);
+        persistRunState(context, project, { ...run, workspace_root: workspaceRoot }, index);
+        appendAudit(context, { projectId: project.id, eventType: "flow_run.workspace_rebound", payload: { run_id: run.id, workspace_root: workspaceRoot, reason: input.reason, ...(route ? { route } : {}) } });
+        appendRunTimeline(context, project.id, run.id, { at: now, type: "workspace_rebound", run_id: run.id, workspace_root: workspaceRoot, reason: input.reason, git: facts });
+    }, "runs.rebindWorkspace");
     return { ok: true, run_id: run.id, project_root: project.root, workspace_root: workspaceRoot, git: facts };
 }
+function retainedWorkspaceRoute(context, run) {
+    const index = authoritativeIndex(run), binding = index.workspace_route;
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.workspace_rebound' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.route.revision') = ?", [run.project_id, run.id, binding?.revision ?? -1]);
+    const original = rows.length === 1 ? JSON.parse(rows[0].payload_json).route : undefined;
+    if (!binding || !original || original.schema_id !== "dd-flow/run-workspace-route@1" || hybridDigest(original) !== binding.sha256 || hybridDigest(original.receipt) !== original.receipt_sha256) {
+        throw new AppError("workspace_route_invalid", "RUN committed workspace route evidence changed", 1, { effect: "no_effect", run_id: run.id });
+    }
+    // Relocation receipts are admitted by snapshot import; never rewrite bundle
+    // or source route authority merely because a physical checkout moved.
+    const route = JSON.parse(projectPacketLocators(JSON.stringify(original), runContextRelocations(context, run.project_id, run.id)));
+    if (route.receipt_sha256 !== original.receipt_sha256
+        || route.run_id !== run.id || route.project_id !== run.project_id || route.project_root !== run.project_root || route.workspace_root !== run.workspace_root
+        || index.workspace.workspace_path !== run.workspace_root || index.execution?.workspace_root !== run.workspace_root || index.execution?.project_root !== run.project_root
+        || index.workspace.manager !== "official-worktrunk" || index.workspace.branch !== route.receipt.policy.feature_branch
+        // execution.git is the latest observation (stage completion/refresh updates
+        // it). The immutable review base is workspace.base, not that moving HEAD.
+        || index.workspace.base !== route.git.head
+        || !Number.isInteger(route.generation) || route.generation < 0
+        || route.receipt.policy.worktree_path !== run.workspace_root) {
+        throw new AppError("workspace_route_invalid", "RUN has no exact coherent committed workspace route", 1, { effect: "no_effect", run_id: run.id });
+    }
+    return route;
+}
 function loadUpgradeFlowContract(context, projectRoot) {
     const canon = resolveCanonRoot(context, context.env.DD_MEMORYBANK ? { explicitRoot: context.env.DD_MEMORYBANK } : {});
     if (!canon.ok || !canon.canon) {
@@ -1608,6 +1671,17 @@ export function publishRunProjections(context, projectId, runId) {
         if (!latest)
             throw new AppError("not_found", "RUN is not registered", 1, { run_id: runId });
         const index = authoritativeIndex(latest);
+        if (index.workspace_route) {
+            const route = retainedWorkspaceRoute(context, latest);
+            const file = path.join(runArtifactRoot(latest), "02-protocolize", "workspace-route.json");
+            ensureDir(path.dirname(file));
+            try {
+                writeJsonFile(file, route.receipt);
+            }
+            catch (error) {
+                throw new AppError("workspace_route_publication_failed", "Committed route projection could not be published", 1, { effect: "committed", run_id: runId, route_sha256: index.workspace_route.sha256, cause: String(error) });
+            }
+        }
         const mutations = context.db.get("SELECT 1 FROM sqlite_schema WHERE name = 'flow_run_flag_mutations'") ? context.db.all("SELECT resulting_revision, result_json, created_at, idempotency_key FROM flow_run_flag_mutations WHERE project_id = ? AND run_id = ? ORDER BY resulting_revision DESC LIMIT 32", [projectId, runId]) : [];
         const history = mutations.reverse().map((row) => ({
             revision: row.resulting_revision,
@@ -1661,11 +1735,26 @@ function authoritativeIndex(run) {
         throw new AppError("runtime_state_invalid", "RUN mechanical state in SQLite is missing or invalid", 1, { run_id: run.id, cause: String(error) });
     }
 }
-function assertBundleRunIdentity(run, bundle) {
-    const scope = bundle.execution.snapshot().scope;
+function assertBundleWorkspaceIdentity(context, run, bundle) {
+    const scope = currentBundleScope(context, run, bundle);
+    const route = authoritativeIndex(run).workspace_route ? retainedWorkspaceRoute(context, run) : undefined;
+    if (scope.workspace === run.workspace_root)
+        return true;
+    if (bundle.descriptor.descriptor.id !== "sdlc" || !["vnext_specify", "vnext_protocolize"].includes(run.flow_kind) || scope.workspace !== run.project_root)
+        return false;
+    if (!route)
+        return false;
+    return route.previous_workspace === scope.workspace && route.receipt.policy.route === "feature_worktree"
+        && route.receipt.policy.base_ref !== null && route.receipt.policy.feature_branch !== null;
+}
+function currentBundleScope(context, run, bundle) {
+    return JSON.parse(projectPacketLocators(JSON.stringify(bundle.execution.snapshot().scope), runContextRelocations(context, run.project_id, run.id)));
+}
+function assertBundleRunIdentity(context, run, bundle) {
+    const scope = currentBundleScope(context, run, bundle);
     const flowId = bundle.descriptor.descriptor.id;
     const matchesFlow = flowId === "sdlc" ? ["vnext_specify", "vnext_protocolize"].includes(run.flow_kind) : flowId === run.flow_kind;
-    if (bundle.manifest.run_id !== run.id || scope.projectRoot !== run.project_root || scope.workspace !== run.workspace_root || !matchesFlow) {
+    if (bundle.manifest.run_id !== run.id || scope.projectRoot !== run.project_root || !assertBundleWorkspaceIdentity(context, run, bundle) || !matchesFlow) {
         throw new AppError("run_bundle_identity_invalid", "Execution bundle belongs to another RUN or workspace", 1, { phase: "prepare", effect: "no_effect", run_id: run.id });
     }
     const blobs = new Map(bundle.manifest.inventory.map(ref => [ref.path, bundle.blob(ref.path)]));
@@ -1697,7 +1786,7 @@ export function runBundleAuthorityMetadata(bundle) {
  */
 export function assertPreparedRunBundleAuthority(context, scope, bundle) {
     const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
-    assertBundleRunIdentity(run, bundle);
+    assertBundleRunIdentity(context, run, bundle);
 }
 /** SQL-only fence after the caller has admitted compiled handlers outside the
  * writer. Descriptor schema loading is deliberately excluded from this fence.
@@ -1713,9 +1802,9 @@ export function assertPreparedRunBundleSqlAuthority(context, scope, bundle) {
         || anchor.descriptor_sha256 !== bundle.manifest.descriptor.sha256 || anchor.flow_id !== bundle.manifest.flow_id
         || anchor.admission_sha256 !== hybridDigest(bundleAuthority(bundle.admission())))
         throw new AppError("run_bundle_anchor_invalid", "Prepared bundle differs from authoritative RUN", 1);
-    const execution = bundle.execution.snapshot().scope;
+    const execution = currentBundleScope(context, run, bundle);
     const flow = bundle.descriptor.descriptor.id;
-    if (bundle.manifest.run_id !== run.id || execution.projectRoot !== run.project_root || execution.workspace !== run.workspace_root
+    if (bundle.manifest.run_id !== run.id || execution.projectRoot !== run.project_root || !assertBundleWorkspaceIdentity(context, run, bundle)
         || !(flow === "sdlc" ? ["vnext_specify", "vnext_protocolize"].includes(run.flow_kind) : flow === run.flow_kind)) {
         throw new AppError("run_bundle_identity_invalid", "Execution bundle belongs to another RUN or workspace", 1, { effect: "no_effect", run_id: run.id });
     }
@@ -1755,7 +1844,7 @@ export function readFlowRunExecutionBundle(context, input) {
     }
     const admission = { ...retained, receipts: new Map(retained.receipts), descriptorContext: bundledHandlerContext(new Map()) };
     const bundle = RetainedExecutionBundle.read(path.join(runArtifactRoot(run), "execution-bundle"), anchor.manifest_sha256, admission);
-    assertBundleRunIdentity(run, bundle);
+    assertBundleRunIdentity(context, run, bundle);
     if (bundle.manifest.descriptor.sha256 !== anchor.descriptor_sha256 || bundle.manifest.flow_id !== anchor.flow_id) {
         throw new AppError("run_bundle_anchor_invalid", "RUN bundle descriptor identity changed", 1);
     }
@@ -1766,7 +1855,7 @@ export function bindFlowRunExecutionBundle(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId), index = authoritativeIndex(run);
     const generation = assertRunMutationAllowed(context, project.id, run.id);
-    assertBundleRunIdentity(run, input.bundle);
+    assertBundleRunIdentity(context, run, input.bundle);
     if (input.bundle.manifest.flow_id !== "sdlc") {
         throw new AppError("run_bundle_start_required", "Memory RUN and its bundle authority must be allocated together through the request-bound start", 1, { phase: "prepare", effect: "no_effect", run_id: run.id });
     }

package/dist/services/vnext-code-review.js

@@ -42,7 +42,7 @@ export function prepareVnextCodeReviewStart(context, input) {
     const run = requireRun(context, project.id, input.runId);
     const home = requireHome(run);
     assertRunMutationAllowed(context, project.id, run.id);
-    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage });
+    requireVnextWorkspaceRoute(context, { projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage });
     if (!fs.existsSync(path.join(home, "05-code", "stage-report.json")))
         throw new AppError("runtime_artifact_missing", "CODE-REVIEW requires an accepted CODE report", 1);
     const root = path.join(home, stageDir);

package/dist/services/vnext-code.js

@@ -42,7 +42,7 @@ export async function prepareVnextCodeWorkspace(context, input) {
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     assertRunMutationAllowed(context, project.id, run.id);
-    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, stage: input.stage ?? stage });
+    requireVnextWorkspaceRoute(context, { projectRoot, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, stage: input.stage ?? stage });
     const root = path.join(requireHome(run), stageDir);
     fs.mkdirSync(root, { recursive: true });
     return ensureCodeWorkspaceReady(context, project.id, run, root, [], input.progress, { force: input.stage !== "code-review" });
@@ -53,7 +53,7 @@ export function prepareVnextCodeStart(context, input) {
     const run = requireRun(context, project.id, input.runId);
     assertRunMutationAllowed(context, project.id, run.id);
     const home = requireHome(run);
-    requireVnextWorkspaceRoute({ projectRoot, runId: input.runId, runHome: home, workspaceRoot: run.workspace_root, stage });
+    requireVnextWorkspaceRoute(context, { projectRoot, runId: input.runId, runHome: home, workspaceRoot: run.workspace_root, stage });
     const existingRoot = path.join(home, stageDir);
     const existingPrompt = path.join(existingRoot, "stage-prompt.md");
     const existingStage = stageStatus(run, stage);
@@ -158,7 +158,7 @@ export async function finishVnextCode(context, input) {
     const home = requireHome(run);
     const root = path.join(home, stageDir);
     const generation = assertRunMutationAllowed(context, project.id, run.id);
-    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage });
+    requireVnextWorkspaceRoute(context, { projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage });
     if (stageStatus(run, stage) === "done" && fs.existsSync(path.join(root, "stage-report.json"))) {
         resumeAcceptedCodeStage(context, run, projectRoot, stage, JSON.parse(fs.readFileSync(path.join(root, "stage-report.json"), "utf8")), nextAction(run, changedPathsFromReport(path.join(root, "stage-report.json"))));
         return { ok: true, resumed: true, run_id: run.id, stage, outcome: "accepted", report_path: path.join(root, "stage-report.json"), next_action: nextAction(run, changedPathsFromReport(path.join(root, "stage-report.json"))) };

package/dist/services/vnext-fanout.js

@@ -10,7 +10,8 @@ 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 { eligibleCodexChildOverload } from "./codex-capacity.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";
@@ -262,7 +263,7 @@ export async function reconcileVnextFanout(context, input) {
             continue;
         }
         const link = active[0];
-        if (value.harness_id === "codex-desktop" && eligibleCodexChildOverload(child, value.parent_session_id)) {
+        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;
         }

package/dist/services/vnext-plan-review.js

@@ -50,7 +50,7 @@ export function prepareVnextPlanReviewStart(context, input) {
             return { ...common, state: "terminal", report, outcome };
         throw new AppError("invalid_work_state", "PLAN-REVIEW is already terminal; corrections are applied in the same review Work and are not re-reviewed automatically", 2, { run_id: run.id, outcome });
     }
-    const workspaceRoute = requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan-review" });
+    const workspaceRoute = requireVnextWorkspaceRoute(context, { projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan-review" });
     if (!fs.existsSync(path.join(planRoot, "stage-report.json")) || !fs.existsSync(batch))
         throw new AppError("runtime_artifact_missing", "PLAN-REVIEW requires the accepted PLAN report and proposed CODE batch", 1);
     const requested = requestedMode(run);

package/dist/services/vnext-plan.js

@@ -33,7 +33,7 @@ export function prepareVnextPlanStart(context, input) {
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, projectRoot, input.runId);
     const home = requireHome(run);
-    const workspaceRoute = requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
+    const workspaceRoute = requireVnextWorkspaceRoute(context, { projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
     const protocols = protocolIds(home);
     if (!protocols.length)
         throw new AppError("runtime_artifact_missing", "PLAN requires accepted PROTOCOLIZE protocols", 1);
@@ -136,7 +136,7 @@ export function startVnextPlan(context, input, prepared = prepareVnextPlanStart(
 export function prepareVnextPlanFinish(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const run = requireRun(context, projectRoot, input.runId), home = requireHome(run);
-    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
+    requireVnextWorkspaceRoute(context, { projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
     const protocols = protocolIds(home);
     assertProtocolWorkspace(run.workspace_root, protocols);
     const prepared = prepareVnextPlanArtifacts(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home, protocols });
@@ -153,7 +153,7 @@ function finishVnextPlanOwned(context, input) {
     const run = requireRun(context, projectRoot, input.runId);
     const home = requireHome(run);
     const root = path.join(home, "03-plan");
-    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
+    requireVnextWorkspaceRoute(context, { projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
     const protocols = protocolIds(home);
     if (!protocols.length)
         throw new AppError("runtime_artifact_missing", "PLAN requires accepted PROTOCOLIZE protocols", 1);