@deksden-com/dd-flow-cli 0.9.0-beta.37 → 0.9.0-beta.39

package/dist/services/runtime-scope-stop.js

@@ -0,0 +1,95 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { runHarnessAdapter } from "./harness-adapter.js";
+import { managedProcessBinding, managedProcessStatus, processIsAlive, processTreeIsAlive, resourceHome, stopManagedProcess } from "./managed-processes.js";
+import { fenceRuntimeBudget, runtimeBudgetStatus, scopeLocalProcessRole } from "./runtime-budget.js";
+import { retainedDaemonOperations } from "./run-control.js";
+import { historicalDaemonSettlement } from "./native-daemon-history.js";
+import { managedProviderBelongsToDaemon } from "./managed-daemon-binding.js";
+/** Native daemons own cancellation after the observing CLI disconnects. */
+export async function stopRuntimeScope(context, scopeId, requestId) {
+    const fence = fenceRuntimeBudget(context, scopeId, requestId);
+    const inventory = runtimeBudgetStatus(context, scopeId).processes;
+    const nodes = await Promise.all(inventory.filter(record => record.kind.endsWith("-daemon")).map(async (record) => {
+        try {
+            const historical = historicalDaemonSettlement(context, scopeId, record);
+            if (historical)
+                return historical;
+            const metadata = JSON.parse(record.metadata_json);
+            if (!metadata.state_dir || !path.isAbsolute(metadata.state_dir) || !metadata.adapter_executable || !path.isAbsolute(metadata.adapter_executable))
+                throw new AppError("runtime_scope_owner_unknown", "Native stop requires its retained directory and executable", 1);
+            const file = path.join(metadata.state_dir, "daemon.json");
+            const read = () => JSON.parse(fs.readFileSync(file, "utf8"));
+            const state = read();
+            const owner = state.config?.runtime_owner;
+            if (!state.daemon_id || !owner || owner.budget?.scope_id !== scopeId || owner.owner_id !== record.owner_id || owner.role !== metadata.role || owner.state_dir !== metadata.state_dir || owner.adapter_executable !== metadata.adapter_executable || owner.resource_home !== resourceHome(context) || (owner.project_id ?? null) !== record.project_id || (owner.run_id ?? null) !== record.run_id || (owner.work_id ?? null) !== record.work_id || !record.operation_id?.startsWith(`${owner.operation_id}:`) || state.resource_process?.id !== record.id || state.resource_process.lease_token !== record.lease_token || state.pid !== record.pid)
+                throw new AppError("runtime_scope_owner_unknown", "Native owner does not match its registration", 1);
+            const closed = state.shutdown_state === "clean" && state.active_tree === false && !processTreeIsAlive(record)
+                ? retainedDaemonOperations(metadata.state_dir).find(operation => operation.daemon_id === state.daemon_id && operation.operation === "daemon.stop" && operation.state === "completed" && operation.result?.stopped === true && operation.result?.clean === true) : undefined;
+            const operationId = closed ? String(closed.operation_id) : `scope-stop:${crypto.createHash("sha256").update(JSON.stringify([scopeId, record.id, state.daemon_id])).digest("hex")}`;
+            const requested = path.join(metadata.state_dir, "operations", crypto.createHash("sha256").update(operationId).digest("hex"), "requested.json");
+            const prior = fs.existsSync(requested);
+            const current = managedProcessStatus(context).find(item => item.id === record.id);
+            if (!current || current.lease_token !== record.lease_token || current.pid !== record.pid || current.pid_started_at !== record.pid_started_at)
+                throw new AppError("runtime_scope_owner_changed", "Native registration changed before control", 1);
+            if (!prior && !processIsAlive(current))
+                throw new AppError("runtime_scope_outcome_unknown", "Dead native owner requires retained shutdown evidence", 1);
+            const env = { ...context.env, DD_FLOW_HOME: owner.dd_flow_home, DD_FLOW_BIN: owner.dd_flow_bin, DD_FLOW_RESOURCE_HOME: owner.resource_home };
+            delete env.DD_FLOW_CONTROL_TOKEN;
+            delete env.DD_FLOW_CONTROLLER_TOKEN;
+            const receipt = await runHarnessAdapter({ executable: metadata.adapter_executable,
+                args: prior ? ["daemon", "operation", "--operation-id", operationId, "--state-dir", metadata.state_dir, "--json"] : ["daemon", "stop", "--cancel-tree", "--state-dir", metadata.state_dir, "--json"],
+                env, operationId: prior ? `${operationId}:observe` : operationId, timeoutMs: 30_000 });
+            if (prior && (receipt.operation_id !== operationId || receipt.daemon_id !== state.daemon_id || receipt.operation !== "daemon.stop" || receipt.state !== "completed"))
+                throw new AppError("runtime_scope_outcome_unknown", "Native close operation has not completed", 1);
+            const result = (prior ? receipt.result : receipt);
+            const after = read();
+            const finalOwner = managedProcessStatus(context).find(item => item.id === record.id);
+            if (!finalOwner || finalOwner.lease_token !== record.lease_token || finalOwner.pid !== record.pid || finalOwner.pid_started_at !== record.pid_started_at || after.resource_process?.id !== record.id || after.resource_process.lease_token !== record.lease_token || JSON.stringify(after.config?.runtime_owner) !== JSON.stringify(owner))
+                throw new AppError("runtime_scope_owner_changed", "Native ownership changed during control", 1);
+            if (result?.stopped !== true || result.clean !== true || after.daemon_id !== state.daemon_id || after.shutdown_state !== "clean" || after.active_tree !== false || processTreeIsAlive(finalOwner))
+                throw new AppError("runtime_scope_not_settled", "Native close has not proved whole-tree settlement", 1);
+            const processes = managedProcessStatus(context).filter(item => managedProviderBelongsToDaemon(item, finalOwner, after) && item.operation_id?.startsWith(`${owner.operation_id}:`) && !processTreeIsAlive(item)).map(item => ({ process_id: item.id, native_settled: true, binding: managedProcessBinding(item, resourceHome(context)) }));
+            return { process_id: record.id, state_dir: metadata.state_dir, settled: true, operation_id: operationId, owner_operation_id: owner.operation_id, processes };
+        }
+        catch (error) {
+            return { process_id: record.id, settled: false, reason: error instanceof AppError ? error.code : "runtime_scope_control_failed", message: String(error) };
+        }
+    }));
+    const covered = new Set(nodes.map(node => node.process_id));
+    for (const record of runtimeBudgetStatus(context, scopeId).processes) {
+        if (covered.has(record.id))
+            continue;
+        const metadata = JSON.parse(record.metadata_json);
+        // RUN control owns active controllers/checks. Adopt only its already-finished
+        // physical registrations here; death alone is not a completed RUN operation.
+        if ((record.kind === "run-controller" && metadata.role === "controller" && record.operation_id
+            || record.kind === "check" && metadata.role === "check" && record.check_id)
+            && record.project_id && record.run_id && ["stopped", "failed"].includes(record.state)
+            && record.pid && record.pid_started_at && !processTreeIsAlive(record)) {
+            const operationId = record.operation_id ?? record.check_id;
+            nodes.push({ process_id: record.id, state_dir: metadata.state_dir ?? "", settled: true, operation_id: operationId, owner_operation_id: operationId });
+            continue;
+        }
+        if (scopeLocalProcessRole(record) && record.operation_id && record.pid && record.pid_started_at) {
+            try {
+                await stopManagedProcess(context, { id: record.id, leaseToken: record.lease_token, force: false, graceMs: 500, reason: `scope-stop:${scopeId}` });
+                nodes.push({ process_id: record.id, state_dir: "", settled: true, operation_id: record.operation_id, owner_operation_id: record.operation_id });
+            }
+            catch (error) {
+                nodes.push({ process_id: record.id, settled: false, reason: "runtime_scope_resource_unsettled", message: String(error) });
+            }
+            continue;
+        }
+        const binding = JSON.stringify(managedProcessBinding(record, resourceHome(context)));
+        const parent = nodes.find(node => node.settled && node.state_dir === metadata.state_dir && "processes" in node && node.processes?.some(item => item.process_id === record.id && item.native_settled && JSON.stringify(item.binding) === binding));
+        if (parent && !processTreeIsAlive(record)) {
+            nodes.push({ process_id: record.id, state_dir: metadata.state_dir, settled: true, operation_id: parent.operation_id, owner_operation_id: parent.owner_operation_id });
+        }
+        else
+            nodes.push({ process_id: record.id, settled: false, reason: "runtime_scope_resource_unsettled", message: "Resource needs its own settlement proof" });
+    }
+    return { scope_id: scopeId, fence, settled: nodes.every(node => node.settled), nodes };
+}

package/dist/services/runtime-scope-worker.js

@@ -0,0 +1,165 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { AppError } from "../shared/errors.js";
+import { getResourceDatabase } from "../storage/database.js";
+import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, processIsAlive, processStartedAt, registerManagedProcess, resourceHome } from "./managed-processes.js";
+import { publicRuntimeScopeWorker, requestRuntimeScopeControl, runtimeBudgetStatus } from "./runtime-budget.js";
+import { controlRuntimeScopeRuns } from "./runtime-scope-control.js";
+import { prepareRuntimeScopeResume, recordRuntimeScopeResume } from "./runtime-scope-resume.js";
+export async function launchRuntimeScopeResume(context, input) {
+    const resume = recordRuntimeScopeResume(context, input);
+    if (!resume.current)
+        return { scope_id: input.scopeId, resume, current: false, settled: false };
+    if (resume.status === "released")
+        return { scope_id: input.scopeId, resume, release: resume.release, current: true, dispatch_blocked: resume.dispatch_blocked, settled: false };
+    const control = runtimeBudgetStatus(context, input.scopeId).control;
+    if (control?.generation !== input.generation)
+        throw new AppError("runtime_scope_control_superseded", "Scope resume source changed before owner launch", 1);
+    const owner = await launchRuntimeScopeControl(context, input.scopeId, control.request_id, control.requested_mode);
+    return { ...owner, resume, dispatch_blocked: true, settled: false };
+}
+const keyFor = (scope, generation) => crypto.createHash("sha256").update(JSON.stringify([scope, generation])).digest("hex");
+function birth() {
+    const started = processStartedAt(process.pid);
+    if (!started)
+        throw new AppError("runtime_scope_owner_unknown", "Scope owner birth identity is unavailable", 1);
+    return { pid: process.pid, pid_started_at: started };
+}
+export async function launchRuntimeScopeControl(context, scopeId, requestId, mode, manifest) {
+    const control = requestRuntimeScopeControl(context, scopeId, requestId, mode, manifest), db = getResourceDatabase(resourceHome(context)), key = keyFor(scopeId, control.generation);
+    let worker;
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const current = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control' AND resource_key = ?", [scopeId]);
+        const prior = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ?", [key]);
+        const existing = prior ? JSON.parse(prior.metadata_json) : null;
+        if (existing) {
+            const identity = existing.owner ?? existing.launcher;
+            if (!identity || !Number.isSafeInteger(identity.pid) || identity.pid < 1 || typeof identity.pid_started_at !== "string" || !identity.pid_started_at || !["starting", "running", "completed", "failed", "superseded"].includes(existing.status))
+                throw new AppError("runtime_scope_owner_unknown", "Retained scope owner has no verifiable birth identity", 1);
+        }
+        if (!current || JSON.parse(current.metadata_json).generation !== control.generation || db.get("SELECT 1 FROM managed_resources WHERE resource_kind = 'provider-fence' AND resource_key = ?", [scopeId])) {
+            db.exec("COMMIT");
+            return { scope_id: scopeId, control, current: false, settled: false, worker: existing ? publicRuntimeScopeWorker(existing) : null };
+        }
+        if (existing && (existing.owner ? processIsAlive(existing.owner) : existing.status !== "failed" && processIsAlive(existing.launcher))) {
+            db.exec("COMMIT");
+            return { scope_id: scopeId, control, current: true, settled: false, worker: publicRuntimeScopeWorker(existing) };
+        }
+        worker = { scope_id: scopeId, generation: control.generation, request_id: requestId, mode, token: crypto.randomUUID(), status: "starting", launcher: birth() };
+        const now = context.now();
+        db.run("INSERT INTO managed_resources (resource_kind,resource_key,owner_id,lease_token,lease_expires_at,process_id,metadata_json,created_at,updated_at) VALUES ('scope-control-worker',?,?,?,?,NULL,?,?,?) ON CONFLICT(resource_kind,resource_key) DO UPDATE SET lease_token = excluded.lease_token, metadata_json = excluded.metadata_json, updated_at = excluded.updated_at", [key, scopeId, worker.token, now, JSON.stringify(worker), now, now]);
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    try {
+        const entry = fileURLToPath(new URL("../cli.js", import.meta.url));
+        if (!fs.existsSync(entry))
+            throw new AppError("harness_runtime_unbuilt", "Build the CLI before launching scope control", 1);
+        const directory = path.join(resourceHome(context), "scope-controls", key);
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const log = fs.openSync(path.join(directory, "control.log"), "a", 0o600);
+        try {
+            const env = { ...context.env, DD_FLOW_HOME: context.ddFlowHome, DD_FLOW_RESOURCE_HOME: resourceHome(context), DD_FLOW_ENGINE_MODE: "1", DD_FLOW_SCOPE_CONTROL_TOKEN: worker.token };
+            delete env.DD_FLOW_CONTROL_TOKEN;
+            delete env.DD_FLOW_CONTROLLER_TOKEN;
+            const child = spawn(process.execPath, [entry, "runtime", "scope", "serve", "--scope-id", scopeId, "--generation", String(control.generation), "--json"], { env, detached: true, stdio: ["ignore", log, log] });
+            await new Promise((resolve, reject) => { child.once("spawn", resolve); child.once("error", reject); });
+            child.unref();
+        }
+        finally {
+            fs.closeSync(log);
+        }
+    }
+    catch (error) {
+        db.run("UPDATE managed_resources SET metadata_json = json_set(metadata_json, '$.status', 'failed', '$.error', ?), updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ? AND json_extract(metadata_json, '$.owner') IS NULL", [String(error), context.now(), key, worker.token]);
+    }
+    const retained = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ?", [key]);
+    return { scope_id: scopeId, control, current: true, settled: false, worker: publicRuntimeScopeWorker(JSON.parse(retained.metadata_json)) };
+}
+export async function serveRuntimeScopeControl(context, scopeId, generation) {
+    if (!Number.isSafeInteger(generation) || generation < 1 || !context.env.DD_FLOW_SCOPE_CONTROL_TOKEN)
+        throw new AppError("runtime_scope_owner_unknown", "Scope worker requires its launch token and generation", 1);
+    const db = getResourceDatabase(resourceHome(context)), key = keyFor(scopeId, generation), token = context.env.DD_FLOW_SCOPE_CONTROL_TOKEN;
+    let worker;
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const row = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [key, token]);
+        if (!row)
+            throw new AppError("runtime_scope_owner_unknown", "Scope worker claim changed", 1);
+        worker = JSON.parse(row.metadata_json);
+        if (worker.owner || worker.status !== "starting")
+            throw new AppError("runtime_scope_already_owned", "Scope control already has a physical owner", 1);
+        worker.owner = birth();
+        worker.status = "running";
+        db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    let heartbeat;
+    try {
+        const record = registerManagedProcess(context, { kind: "scope-control", ownerId: key, operationId: `scope-control:${key}:${token}`, ownerPid: process.pid, metadata: { role: "control", scope_id: scopeId, generation } });
+        worker.process_id = record.id;
+        worker.process_lease_token = record.lease_token;
+        confirmManagedProcess(context, { id: record.id, leaseToken: record.lease_token, pid: process.pid, processGroupId: process.pid, ownerPid: process.pid });
+        db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
+        let leaseLost = false;
+        heartbeat = setInterval(() => { try {
+            if (!heartbeatManagedProcess(context, { id: record.id, leaseToken: record.lease_token }))
+                leaseLost = true;
+        }
+        catch {
+            leaseLost = true;
+        } }, 10_000);
+        heartbeat.unref();
+        for (;;) {
+            if (leaseLost)
+                throw new AppError("runtime_scope_owner_changed", "Scope worker lost its managed lease", 1);
+            const status = runtimeBudgetStatus(context, scopeId);
+            const release = status.release;
+            if (release?.current === true && release.generation === generation) {
+                worker.status = "completed";
+                worker.snapshot = release;
+                break;
+            }
+            if (status.control?.generation !== generation || status.fence) {
+                worker.status = "superseded";
+                break;
+            }
+            const resume = status.resume;
+            worker.snapshot = await prepareRuntimeScopeResume(context, scopeId, generation, resume?.generation === generation ? resume.request_id : undefined) ?? await controlRuntimeScopeRuns(context, scopeId, worker.request_id, worker.mode);
+            db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
+            await delay(1_000);
+        }
+        return { scope_id: scopeId, generation, status: worker.status };
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "runtime_scope_control_superseded") {
+            const release = runtimeBudgetStatus(context, scopeId).release;
+            worker.status = release?.current === true && release.generation === generation ? "completed" : "superseded";
+            if (worker.status === "completed")
+                worker.snapshot = release;
+            return { scope_id: scopeId, generation, status: worker.status };
+        }
+        worker.status = "failed";
+        worker.error = String(error);
+        throw error;
+    }
+    finally {
+        if (heartbeat)
+            clearInterval(heartbeat);
+        db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
+        if (worker.process_id && worker.process_lease_token)
+            finishManagedProcess(context, { id: worker.process_id, leaseToken: worker.process_lease_token, state: worker.status === "failed" ? "failed" : "stopped", reason: "scope_owner_exited" });
+    }
+}

package/dist/services/runtime-service.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import crypto from "node:crypto";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
 import { requireProjectByRoot } from "./projects.js";
 import { resolveRun } from "./runs.js";
 import { codeExecutionEnvironment, runCheck } from "./code-checks.js";
@@ -19,6 +20,7 @@ export async function startRuntimeService(context, input) {
     if (!run?.run_root || !run.workspace_root)
         throw new AppError("not_found", "Registered RUN with a materialized workspace is required", 2);
     input = { ...input, runId: run.id };
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
     const id = `PROC-${crypto.randomUUID()}`;
     const directory = path.join(run.run_root, "runtime", id);
     fs.mkdirSync(directory, { recursive: true });
@@ -34,6 +36,8 @@ export async function startRuntimeService(context, input) {
         const quoted = (value) => `'${value.replaceAll("'", "'\\''")}'`;
         Object.assign(receipt, { ports: allocation.ports, environment: Object.fromEntries(Object.entries(environment).filter(([key]) => key.startsWith("DD_FLOW_PORT_"))), stop_command: `DD_FLOW_HOME=${quoted(context.ddFlowHome)} DD_FLOW_RESOURCE_HOME=${quoted(resourceHome(context))} dd-flow runtime process stop --id ${record.id} --lease-token ${record.lease_token} --json` });
         save();
+        input.progress?.(`service ${record.id} preparing; receipt: ${receiptPath}`);
+        assertRunMutationAllowed(context, project.id, run.id, generation);
         stdout = fs.openSync(String(receipt.stdout_path), "a");
         stderr = fs.openSync(String(receipt.stderr_path), "a");
         const running = runCheck(input.command, run.workspace_root, environment, stdout, stderr, elapsed => input.progress?.(`service ${record.id} alive (${elapsed}s); receipt: ${receiptPath}`), pid => confirmManagedProcess(context, { id: record.id, leaseToken: record.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid }), () => heartbeatManagedProcess(context, { id: record.id, leaseToken: record.lease_token }));

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

@@ -203,7 +203,7 @@ export async function finishVnextCodeReview(context, input) {
     completeFlowRunStage(context, { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html" });
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_completed", work_id: rootWork.work_id, outcome });
     if (nextAction === "start_merge")
-        advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "code_review_completed", nextAction });
+        advanceFlowRun(context, { settlementStage: "code-review", projectRoot, runId: run.id, status: "running", verdict: "code_review_completed", nextAction });
     else {
         await finishWork(context, rootWork.work_id, JSON.stringify(report, null, 2));
         completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "code_review_completed", nextAction: undefined });

package/dist/services/vnext-code.js

@@ -270,7 +270,7 @@ export async function finishVnextCode(context, input) {
         completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "code_completed", nextAction: undefined });
     }
     else {
-        advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "code_completed", nextAction: next });
+        advanceFlowRun(context, { settlementStage: "code", projectRoot, runId: run.id, status: "running", verdict: "code_completed", nextAction: next });
     }
     return {
         ok: true,

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

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
+import { isExecutionRouting } from "./execution-policy.js";
 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) {
@@ -23,43 +24,9 @@ export function loadVnextExecutionProfile(projectRoot) {
         || !["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()
-        || !validRouting(profile.execution, profile.schema_id === "dd-flow/project-execution@3")) {
+        || (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, { file });
     }
     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); }
-function validRouting(value, required) {
-    if (value === undefined)
-        return !required;
-    if (!object(value) || !profileId(value.agent_profile_id) || !override(value, true))
-        return false;
-    if (value.stage_overrides !== undefined) {
-        if (!object(value.stage_overrides))
-            return false;
-        for (const [stage, item] of Object.entries(value.stage_overrides))
-            if (!stage.trim() || !object(item) || !override(item, false))
-                return false;
-    }
-    return true;
-}
-function override(value, root) {
-    const allowed = root ? new Set(["agent_profile_id", "delegation", "stage_overrides"]) : new Set(["agent_profile_id", "delegation"]);
-    if (Object.keys(value).some(key => !allowed.has(key)))
-        return false;
-    if (!root && value.agent_profile_id === undefined && value.delegation === undefined)
-        return false;
-    if (value.agent_profile_id !== undefined && !profileId(value.agent_profile_id))
-        return false;
-    if (value.delegation === undefined)
-        return true;
-    if (!object(value.delegation) || (value.delegation.mode !== "native" && value.delegation.mode !== "external"))
-        return false;
-    if (value.delegation.agent_profile_id !== undefined && !profileId(value.delegation.agent_profile_id))
-        return false;
-    if (value.delegation.max_parallel !== undefined && (!Number.isInteger(value.delegation.max_parallel) || Number(value.delegation.max_parallel) < 1))
-        return false;
-    return value.delegation.mode !== "native" || value.delegation.max_parallel === undefined;
-}
-function profileId(value) { return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value); }
-function object(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value); }

package/dist/services/vnext-fanout.js

@@ -4,11 +4,31 @@ import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
 import { getFlowRunVariables, appendFlowRunTimelineEvent } from "./runs.js";
+import { resolveExecutionPolicy } from "./execution-policy.js";
 import { listWorks, failWork, cancelWork } from "./work-registry.js";
 import { storageSessionId } from "./session-identity.js";
 import { reconcileUnfinishedChecks } from "./code-checks.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 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 frozen = JSON.parse(run.index_json).execution_profile;
+    if (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")
+            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 ? available : null, source: "harness_qualification" };
+}
 export function fanoutState(input) {
     if (!input.hasWork)
         return input.dispatch === "none" ? "coordinator_required" : "dispatch_required";
@@ -47,13 +67,12 @@ export function getVnextFanoutStatus(context, input) {
         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 capacity = getStageFanoutCapacity(context, { projectRoot, runId: input.runId, stage: input.stage });
     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 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,
@@ -64,10 +83,7 @@ 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
-            },
+            capacity,
             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 })) }
         }
     };

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

@@ -16,7 +16,7 @@ import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { writeStageReport } from "./stage-report-renderer.js";
 import { assertPortableArtifactRef } from "./portable-refs.js";
 import { applyExternalStageContext } from "./stage-context.js";
-import { readFanoutDescriptor, subagentCapacityKey, writeFanoutDescriptor } from "./vnext-fanout.js";
+import { getStageFanoutCapacity, readFanoutDescriptor, subagentCapacityKey, writeFanoutDescriptor } from "./vnext-fanout.js";
 const stage = "plan-review";
 const stageDir = vnextStageDirectory(stage);
 const reviewTask = "Independently review the accepted PLAN and decide whether CODE may open.";
@@ -74,7 +74,7 @@ export function startVnextPlanReview(context, input) {
         const report = reportFor({ run, mode: effective, requested, outcome: "off", groups: [], batchChecksum, planChecksum, code: registered, now, projectRoot, flow: flowCommand(context) });
         writeReport(root, report);
         completeFlowRunStage(context, { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html" });
-        advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "plan_review_off", nextAction: "start_code" });
+        advanceFlowRun(context, { settlementStage: "plan-review", projectRoot, runId: run.id, status: "running", verdict: "plan_review_off", nextAction: "start_code" });
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "plan_review_opened", mode: effective, outcome: "off" });
         return { ok: true, run_id: run.id, stage, outcome: "review_off", ...(externalContext ? { external_context: externalContext } : {}), plan_review: { requested_mode: requested, effective_mode: effective, policy_source: policySource(run), reason: "No applicable independent review group." }, next: { kind: "start_stage", stage: "code", command: codeCommand(context, run.id, projectRoot) } };
     }
@@ -143,7 +143,7 @@ export function dispatchVnextPlanReview(context, input) {
     refreshRunWorkProjection(context, project.id, run.id);
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "plan_review_dispatched", work_id: parent.work_id, groups: reviews.map((item) => ({ group: item.group, work_id: item.work_id })) });
     const waves = plannedReviewWaves(groups, capacity.availableSlots);
-    return { ok: true, run_id: run.id, stage, capacity: { available_slots: capacity.availableSlots }, routing: { group_count: groups.length, planned_waves: waves.length, waves, preference: "Use one wave when semantic compatibility permits; hard dependencies create later waves." }, review_works: reviews, next_action: "launch_ready_reviews" };
+    return { ok: true, run_id: run.id, stage, capacity: { available_slots: capacity.availableSlots, source: capacity.source }, routing: { group_count: groups.length, planned_waves: waves.length, waves, preference: "Use one wave when semantic compatibility permits; hard dependencies create later waves." }, review_works: reviews, next_action: "launch_ready_reviews" };
 }
 // Capacity is a RUN fact shared by every fan-out stage.
 const reviewCapacityKey = subagentCapacityKey;
@@ -249,7 +249,7 @@ export function finishVnextPlanReview(context, input) {
     writeReport(root, report);
     refreshRunWorkProjection(context, project.id, run.id);
     completeFlowRunStage(context, { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html" });
-    advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "plan_review_accepted", nextAction: "start_code" });
+    advanceFlowRun(context, { settlementStage: "plan-review", projectRoot, runId: run.id, status: "running", verdict: "plan_review_accepted", nextAction: "start_code" });
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "plan_review_accepted", work_id: parent.work_id, code: registered });
     return { ok: true, run_id: run.id, stage, outcome: "accepted", code: registered, next_action: "start_code", next: { kind: "start_stage", stage: "code", command: codeCommand(context, run.id, projectRoot) } };
 }
@@ -264,7 +264,11 @@ function orchestratorPrompt(context, input) {
     const decision = path.join(input.root, "decision.json");
     const revision = currentPlanRevision(input.home, input.run.workspace_root);
     const workspaceContract = ["<workspace_contract>", `- route: ${input.workspaceRoute.route}`, `- feature branch: ${input.workspaceRoute.feature_branch ?? "not applicable"}`, `- base commit: ${input.workspaceRoute.base_ref ?? "not applicable"}`, `- read/write workspace: ${input.run.workspace_root}`, "The CLI verified this frozen route. All plan and correction writes belong in the named workspace; project root remains only the stable lifecycle identity. Do not create, switch, merge or delete branches/worktrees.", "</workspace_contract>"].join("\n");
-    return ["<stage_identity>", `- RUN: ${input.run.id}`, `- Work: ${input.workId}`, "- Stage: plan-review", `- Mode: ${input.effective}`, "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility, permission or schema discovery.", `- Project root: ${input.projectRoot}`, `- Stage workspace: ${input.root}`, `- PLAN revision: ${revision}`, `- PLAN report checksum: ${input.planChecksum}`, `- Generated CODE batch checksum: ${input.batchChecksum}`, "</trusted_runtime_context>", "", workspaceContract, "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", `Dispatch fresh reviewers: ${dispatchCommand(context, input.run.id, input.projectRoot)}`, `If dispatch reports qualified_capacity_required, stop. The external harness controller qualifies the selected profile outside this RUN and records the resulting integer with ${capacityRecordCommand(context, input.run.id, input.projectRoot, "<qualified-native-child-count>")}. PLAN-REVIEW never launches a capacity probe.`, "After dispatch, launch at most the qualified capacity at once. If more independent reviewer Works remain, wait for the current wave to settle, then start the unchanged queued Works in the next wave. A reviewer launch rejected before it starts is not review evidence: do not create a replacement; wait for a running wave to settle and start that same queued Work. Each reviewer must be a genuinely fresh harness child Session. The lifecycle adapter binds that observed Session; do not bind or supply a Session ID manually. Reviewers are read-only and must not create children. As soon as a reviewer result is accepted, release that reviewer Session when the harness permits; do not let finished disposable workers occupy slots before the next wave.", "Review the execution environment of every selected check as part of its proof: a reset/fixture process, service process and client process must share the intended data and configuration world. A runtime entrypoint that can break that invariant must be explicit in one Work's task and verification and ordered before its consumer. planned_write_areas may advertise likely overlap, but do not treat them as ownership; required_read alone is not a delivery plan.", "If the final decision needs user input with no reasonable default, run this exact one-command heredoc, replacing only its placeholder body. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:", "```sh", input.pauseCommandTemplate, "```", "Ask the returned user_message, stop, then resume this same PLAN-REVIEW Work. Do not write decision.json or finish first.", `When all reviewer results are complete and every user question is resolved, classify every material finding, fix accepted findings in this same PLAN-REVIEW Work, then write ${decision} and finish: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer findings use local FIND-NNN ids. dd-flow exposes each finding to this coordinator as WRK-.../FIND-NNN; use that canonical finding_ref in the decision.", "A completed reviewer result with needs_changes or blocked is evidence, not the stage outcome. Classify its material findings and apply accepted fixes in this one review pass; do not start a second review automatically. Only a missing, malformed or unfinished reviewer result blocks the stage. For an accepted correction, increment PLAN revision and update only plan.json and the relevant aspect map. Do not edit or list code-work-batch.json: the CLI validates final PLAN and regenerates it. If no material correction is needed, set correction.status=not_required. The CLI checks mechanical handoff coherence; it does not prove semantic correctness.", "```json", JSON.stringify({ schema_id: "dd-flow/plan-review-decision@3", outcome: "accepted | failed | cancelled", summary: "Concise evidence-backed final decision.", finding_decisions: [{ finding_ref: "WRK-001-review/FIND-001", decision: "accepted_fix | rejected | deferred_as_DEF | requires_user | duplicate", reason: "Why." }], correction: { status: "not_required | applied", previous_plan_revision: revision, changed_paths: [], summary: "No material correction was needed, or summarize the applied correction." } }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
+    const capacity = getStageFanoutCapacity(context, { projectRoot: input.projectRoot, runId: input.run.id, stage });
+    const reviewerLaunch = capacity.source === "external_policy"
+        ? `After dispatch, return at the Work-graph boundary. The shared runtime launches the queued reviewer Works as separate external Sessions, at most ${capacity.available_slots} in parallel under the RUN's frozen profiles. Do not launch native children, create provider roots, run a capacity probe, or record this external limit as native capacity. Reviewers are read-only leaf workers. Continue the semantic decision only after their Work receipts settle; do not substitute a missing result or relaunch a settled reviewer.`
+        : "After dispatch, launch at most the qualified capacity at once. If more independent reviewer Works remain, wait for the current wave to settle, then start the unchanged queued Works in the next wave. A reviewer launch rejected before it starts is not review evidence: do not create a replacement; wait for a running wave to settle and start that same queued Work. Each reviewer must be a genuinely fresh harness child Session. The lifecycle adapter binds that observed Session; do not bind or supply a Session ID manually. Reviewers are read-only and must not create children. As soon as a reviewer result is accepted, release that reviewer Session when the harness permits; do not let finished disposable workers occupy slots before the next wave.";
+    return ["<stage_identity>", `- RUN: ${input.run.id}`, `- Work: ${input.workId}`, "- Stage: plan-review", `- Mode: ${input.effective}`, "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility, permission or schema discovery.", `- Project root: ${input.projectRoot}`, `- Stage workspace: ${input.root}`, `- PLAN revision: ${revision}`, `- PLAN report checksum: ${input.planChecksum}`, `- Generated CODE batch checksum: ${input.batchChecksum}`, "</trusted_runtime_context>", "", workspaceContract, "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", `Dispatch fresh reviewers: ${dispatchCommand(context, input.run.id, input.projectRoot)}`, `If dispatch reports qualified_capacity_required, stop. The external harness controller qualifies the selected profile outside this RUN and records the resulting integer with ${capacityRecordCommand(context, input.run.id, input.projectRoot, "<qualified-native-child-count>")}. PLAN-REVIEW never launches a capacity probe.`, reviewerLaunch, "Review the execution environment of every selected check as part of its proof: a reset/fixture process, service process and client process must share the intended data and configuration world. A runtime entrypoint that can break that invariant must be explicit in one Work's task and verification and ordered before its consumer. planned_write_areas may advertise likely overlap, but do not treat them as ownership; required_read alone is not a delivery plan.", "If the final decision needs user input with no reasonable default, run this exact one-command heredoc, replacing only its placeholder body. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:", "```sh", input.pauseCommandTemplate, "```", "Ask the returned user_message, stop, then resume this same PLAN-REVIEW Work. Do not write decision.json or finish first.", `When all reviewer results are complete and every user question is resolved, classify every material finding, fix accepted findings in this same PLAN-REVIEW Work, then write ${decision} and finish: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer findings use local FIND-NNN ids. dd-flow exposes each finding to this coordinator as WRK-.../FIND-NNN; use that canonical finding_ref in the decision.", "A completed reviewer result with needs_changes or blocked is evidence, not the stage outcome. Classify its material findings and apply accepted fixes in this one review pass; do not start a second review automatically. Only a missing, malformed or unfinished reviewer result blocks the stage. For an accepted correction, increment PLAN revision and update only plan.json and the relevant aspect map. Do not edit or list code-work-batch.json: the CLI validates final PLAN and regenerates it. If no material correction is needed, set correction.status=not_required. The CLI checks mechanical handoff coherence; it does not prove semantic correctness.", "```json", JSON.stringify({ schema_id: "dd-flow/plan-review-decision@3", outcome: "accepted | failed | cancelled", summary: "Concise evidence-backed final decision.", finding_decisions: [{ finding_ref: "WRK-001-review/FIND-001", decision: "accepted_fix | rejected | deferred_as_DEF | requires_user | duplicate", reason: "Why." }], correction: { status: "not_required | applied", previous_plan_revision: revision, changed_paths: [], summary: "No material correction was needed, or summarize the applied correction." } }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
 }
 function reviewGroups(home, workspaceRoot) {
     const root = path.join(home, "03-plan");
@@ -328,10 +332,9 @@ export function capacityQualificationResponse(context, input) {
     return { ok: true, run_id: input.runId, stage, outcome: "qualified_capacity_required", next_action: "qualify_harness_profile_then_record_capacity", next: { record_command: capacityRecordCommand(context, input.runId, input.projectRoot, "<qualified-native-child-count>"), retry_command: dispatchCommand(context, input.runId, input.projectRoot) } };
 }
 function ensureReviewCapacity(context, input) {
-    const variables = getFlowRunVariables(context, { projectRoot: input.projectRoot, runId: input.runId });
-    const known = variables.variables[reviewCapacityKey];
-    if (typeof known === "number" && Number.isInteger(known) && known >= 0)
-        return { pending: false, availableSlots: known };
+    const capacity = getStageFanoutCapacity(context, { ...input, stage });
+    if (capacity.available_slots !== null)
+        return { pending: false, availableSlots: capacity.available_slots, source: capacity.source };
     return { pending: true, response: capacityQualificationResponse(context, { projectRoot: input.projectRoot, runId: input.runId }) };
 }
 function protocolIdsForReview(home) {

package/dist/services/vnext-plan.js

@@ -138,7 +138,7 @@ export function finishVnextPlan(context, input) {
     const reportJson = writeStageReport(root, report).json;
     validateSchema({ schemaName: "stage-report", file: reportJson, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: home });
     completeFlowRunStage(context, { projectRoot, runId: run.id, stage: "plan", status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html" });
-    advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "planned", nextAction: "start_plan_review" });
+    advanceFlowRun(context, { settlementStage: "plan", projectRoot, runId: run.id, status: "running", verdict: "planned", nextAction: "start_plan_review" });
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "plan_accepted", work_id: work.work_id, protocols, id: workSession.id, next_stage: "plan-review" });
     return { ok: true, run_id: run.id, protocols, next_action: "start_plan_review", next_command: reviewCommand, next: { kind: "start_stage", stage: "plan-review", command: reviewCommand } };
 }

package/dist/services/vnext-protocolize.js

@@ -7,6 +7,7 @@ import { previewNextEntityId } from "./ids.js";
 import { registerProtocol } from "./protocols.js";
 import { requireProjectByRoot } from "./projects.js";
 import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRunStage, gitFacts, rebindFlowRunWorkspace } from "./runs.js";
+import { resolveStageTransition } from "./execution-policy.js";
 import { validateSchema } from "./schema-validation.js";
 import { assertStageStartHookEvent, hookSessionIdentity } from "./hooks.js";
 import { bindStageCoordinatorWork, refreshRunWorkProjection } from "./work-registry.js";
@@ -21,9 +22,15 @@ const stage = "protocolize";
 function stageSessionMode(context, run) {
     const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [run.project_id, run.id]);
     const value = row ? JSON.parse(row.index_json) : null;
-    const mode = value?.execution_profile?.settings?.stage_session_mode;
+    const profile = value?.execution_profile;
+    const mode = profile?.settings.stage_session_mode;
     if (mode !== "same_session" && mode !== "new_session")
         throw new AppError("execution_profile_invalid", "RUN is missing its frozen stage session mode", 1, { run_id: run.id });
+    if (profile?.settings.execution) {
+        if (!profile.agent_profiles)
+            throw new AppError("execution_profile_not_frozen", "Stage handoff requires frozen RUN profiles", 1);
+        return resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy: profile.settings.execution, profiles: profile.agent_profiles, fromStage: "protocolize", stage: "plan", stageSessionMode: mode, mergeMode: profile.settings.merge_mode }).session_mode;
+    }
     return mode;
 }
 export function isVnextProtocolizeRun(context, input) {
@@ -77,7 +84,6 @@ export function startVnextProtocolize(context, input) {
         const handoff = specifyHandoff(path.join(requireRunHome(run), "01-specify", "work-context.json"), work.work_id);
         prepareVnextProtocolize(context, { projectRoot, runId: run.id, workId: work.work_id, handoff });
     }
-    const handoff = JSON.parse(fs.readFileSync(contextPath, "utf8"));
     const frozenContext = JSON.parse(fs.readFileSync(contextPath, "utf8"));
     const previous = context.db.get("SELECT ws.session_id, s.stop_reason FROM work_sessions ws LEFT JOIN sessions s ON s.project_id = ? AND s.session_id = ws.session_id WHERE ws.work_id = ? ORDER BY ws.created_at DESC LIMIT 1", [project.id, work.work_id]);
     const activeWorkSession = context.db.get("SELECT * FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
@@ -91,7 +97,7 @@ export function startVnextProtocolize(context, input) {
             return false;
         }
     })();
-    const mode = handoff.system?.handoff?.stage_handoff.effective;
+    const mode = frozenContext.system?.handoff?.stage_handoff.effective;
     const promptPath = path.join(protocolizeRoot, "prompt.md");
     const externalContext = applyExternalStageContext({ stageRoot: protocolizeRoot, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const sessionId = hookSessionIdentity(context, project.id, input.hookEventId).sessionId;
@@ -165,7 +171,7 @@ export function finishVnextProtocolize(context, input) {
     validateSchema({ schemaName: "stage-report", file: reportJson, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireRunHome(run) });
     completeFlowRunStage(context, { projectRoot, runId: run.id, stage, status: "done", data: "protocolize-result.json", dataSchemaId: "dd-flow/vnext-protocolize-result@3", report: "stage-report.md", stageReport: "stage-report.html" });
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "protocol_documents_materialized", work_id: work.work_id, protocol_ids: protocolIds, stage });
-    advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "protocolized", nextAction: "start_plan" });
+    advanceFlowRun(context, { settlementStage: "protocolize", projectRoot, runId: run.id, status: "running", verdict: "protocolized", nextAction: "start_plan" });
     refreshRunWorkProjection(context, project.id, run.id);
     const nextCommand = `${flowCommand(context)} stage start ${run.id} --stage plan --project-root ${JSON.stringify(projectRoot)} --json`;
     return { ok: true, outcome: "protocolized", run_id: run.id, protocol_ids: protocolIds, workspace_root: workspaceRoot, git_policy: resolvedPolicy, next_action: "await_plan", next_command: nextCommand, next: { kind: "start_stage", stage: "plan", command: nextCommand, cwd: workspaceRoot, session_mode: resolvedPolicy.stage_session_mode }, artifacts: { result: resultFile, report_json: reportJson, report_markdown: reportMarkdown, report_html: reportHtml, protocols: protocolIds.map((id) => path.join(workspaceRoot, ".memory-bank", "protocol", id, "summary.md")) } };