@deksden-com/dd-flow-cli 0.6.0 → 0.8.0-beta.135

package/dist/services/runs.js

@@ -3,17 +3,20 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
-import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
+import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadCanonicalFlowContract, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
 import { ensureDir, projectRunHome, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { buildRunFlowGuidance } from "./flow-guidance.js";
 import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
-import { checkpointRunUsage, usageForRun } from "./usage.js";
+import { recalculateRunUsage } from "./usage.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
-const runSchemaId = "dd-flow/flow-run@2";
-const runtimeSchemaId = "dd-flow/flow-run@2";
+import { resolveCanonRoot } from "./canon.js";
+import { bindCurrentEngineToRun } from "./engines.js";
+import { executionProfilePath, loadVnextExecutionProfile } from "./vnext-execution-profile.js";
+const runSchemaId = "dd-flow/flow-run@3";
+const runtimeSchemaId = "dd-flow/flow-run@3";
 const runIdType = "RUN";
 const allowedRunFlowKinds = [
     "mb_sdlc",
@@ -25,12 +28,16 @@ const allowedRunFlowKinds = [
     "mb-distill",
     "mb-upgrade-review",
     "mb-sdlc-review",
+    "vnext_specify",
+    "vnext_protocolize",
     "review",
     "custom"
 ];
 export function startFlowRun(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const flowContract = loadProjectFlowContract(projectRoot);
+    const flowContract = input.flowKind === "mb-upgrade"
+        ? loadUpgradeFlowContract(context, projectRoot)
+        : loadProjectFlowContract(projectRoot);
     registerProject(context, { root: projectRoot });
     const project = requireProjectByRoot(context, projectRoot);
     const workspaceRoot = resolveWorkspaceRoot(input.workspaceRoot ?? projectRoot);
@@ -39,6 +46,9 @@ export function startFlowRun(context, input) {
     const runId = nextRunId(context, project.id, slug);
     const { shortId } = parseFullEntityId(runId);
     const now = context.now();
+    const executionProfile = (flowKind === "vnext_protocolize" || flowKind === "vnext_specify")
+        ? snapshotVnextExecutionProfile(projectRoot)
+        : undefined;
     const flowFlags = resolveFlowFlags(flowContract, {
         flowKind,
         ...(input.preset ? { preset: input.preset } : {}),
@@ -86,7 +96,6 @@ export function startFlowRun(context, input) {
         },
         stage_runs: [],
         sessions: [],
-        artifacts: { stage_prompt: path.join(runHome, "stage-prompt.md"), stage_report_json: path.join(runHome, "stage-report.json"), stage_report_md: path.join(runHome, "stage-report.md"), stage_report_html: path.join(runHome, "stage-report.html"), summary: path.join(runHome, "summary.md") },
         status: "running",
         verdict: "pending",
         next_action: input.nextAction ?? null,
@@ -99,20 +108,30 @@ export function startFlowRun(context, input) {
         snapshot_checksum: flowFlags.snapshot_checksum,
         reconciliation_status: "reconciled",
         flow_flags: flowFlags,
-        current_stage: null,
-        attempts: [],
-        session_coverage: { status: "unavailable", expected: [], observed: [], missing: [] },
-        usage_coverage: { status: "unavailable", expected: [], observed: [], missing: [] },
+        settings: {
+            plan_review: { mode: executionProfile?.settings.plan_review_mode ?? "auto", source: "default", reason: "Project execution profile default.", updated_at: now },
+            code_review: { mode: executionProfile?.settings.code_review_mode ?? "auto", source: "default", reason: "Project execution profile default.", updated_at: now }
+        },
+        ...(executionProfile ? { execution_profile: executionProfile } : {}),
+        artifacts: {
+            stage_prompt: "stage-prompt.md",
+            stage_report_json: "stage-report.json",
+            stage_report_md: "stage-report.md",
+            stage_report_html: "stage-report.html",
+            summary: "summary.md"
+        },
         timeline_path: "timeline.jsonl"
     };
     ensureDir(path.dirname(runtimePath));
     ensureDir(runHome);
-    writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, 1));
-    context.db.run(`INSERT INTO flow_runs
+    bindCurrentEngineToRun(context, { projectRoot, runId, runHome });
+    const persistedIndex = persistedVnextIndex(index);
+    writeJsonFile(runtimePath, runtimeSnapshotForIndex(persistedIndex, 1));
+    context.db.run(`INSERT INTO runs
       (id, short_id, slug, project_id, project_root, workspace_root, flow_kind, subject_type, subject_id,
-       status, verdict, next_action, runtime_path, run_dir, run_index_path, run_home_path, layout_version, artifact_root_kind,
+       status, verdict, next_action, runtime_path, run_dir, run_index_path, run_home_path, run_root, layout_version, artifact_root_kind,
        index_json, created_at, updated_at, completed_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)`, [
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)`, [
         runId,
         shortId,
         slug,
@@ -129,9 +148,10 @@ export function startFlowRun(context, input) {
         runHome,
         runtimePath,
         runHome,
+        runHome,
         "home_run_v2",
         "dd_flow_home",
-        JSON.stringify(index),
+        JSON.stringify(persistedIndex),
         now,
         now
     ]);
@@ -151,14 +171,121 @@ export function startFlowRun(context, input) {
     });
     return { ok: true, run: flowRunSummary(requireRunById(context, project.id, runId)), index };
 }
+function snapshotVnextExecutionProfile(projectRoot) {
+    const profile = loadVnextExecutionProfile(projectRoot);
+    const sourcePath = executionProfilePath(projectRoot);
+    return {
+        schema_id: "dd-flow/run-execution-profile@1",
+        source_path: sourcePath,
+        source_checksum: crypto.createHash("sha256").update(fs.readFileSync(sourcePath)).digest("hex"),
+        settings: {
+            stage_session_mode: profile.stage_session_mode,
+            plan_review_mode: profile.plan_review_mode,
+            code_review_mode: profile.code_review_mode,
+            stop_target: profile.stop_target,
+            code_bootstrap: profile.code_bootstrap
+        }
+    };
+}
+/**
+ * A vNext route may materialize a feature checkout after its semantic
+ * PROTOCOLIZE decision. Keep project identity stable while moving the RUN's
+ * concrete write workspace before PLAN is allowed to start.
+ */
+export function rebindFlowRunWorkspace(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const workspaceRoot = resolveWorkspaceRoot(input.workspaceRoot);
+    const index = authoritativeIndex(run);
+    const now = context.now();
+    const facts = gitFacts(workspaceRoot);
+    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(runArtifactRoot(run), { at: now, type: "workspace_rebound", run_id: run.id, workspace_root: workspaceRoot, reason: input.reason, git: facts });
+    return { ok: true, run_id: run.id, project_root: project.root, workspace_root: workspaceRoot, git: facts };
+}
+function loadUpgradeFlowContract(context, projectRoot) {
+    const canon = resolveCanonRoot(context, context.env.DD_MEMORYBANK ? { explicitRoot: context.env.DD_MEMORYBANK } : {});
+    if (!canon.ok || !canon.canon) {
+        throw new AppError("canon_unavailable", "mb-upgrade RUN requires the pinned canonical Memory Bank", 1, {
+            project_root: projectRoot,
+            blockers: canon.blockers,
+            bootstrap: canon.bootstrap
+        });
+    }
+    return loadCanonicalFlowContract(canon.canon.flow_root);
+}
 export function getFlowRunStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    refreshRunSessionProjection(context, project.id, run.id);
-    const refreshedRun = requireRunById(context, project.id, run.id);
-    const index = authoritativeIndex(refreshedRun);
-    const runtime = readRuntimeSnapshot(refreshedRun.runtime_path);
-    return { ok: true, run: flowRunSummary(refreshedRun), index, ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, refreshedRun, index) };
+    const index = authoritativeIndex(run);
+    const runtime = readRuntimeSnapshot(run.runtime_path);
+    return { ok: true, run: flowRunSummary(run), index, ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, run, index) };
+}
+export function getFlowRunConfig(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = authoritativeIndex(run);
+    return { ok: true, run_id: run.id, settings: runSettings(index) };
+}
+/** RUN variables are one small shared context bag; policy values are projected, not duplicated. */
+export function getFlowRunVariables(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const variables = materializedRunVariables(authoritativeIndex(run));
+    if (input.key) {
+        if (!(input.key in variables))
+            throw new AppError("not_found", "RUN variable is not set", 1, { key: input.key, run_id: run.id });
+        return { ok: true, run_id: run.id, key: input.key, value: variables[input.key] };
+    }
+    return { ok: true, run_id: run.id, variables };
+}
+export function setFlowRunVariable(context, input) {
+    if (!input.key.startsWith("user."))
+        throw new AppError("validation", "Only user.* RUN variables may be set directly", 2, { key: input.key });
+    return setRunVariable(context, input, input.value);
+}
+/** Controllers own policy.* and runtime.* values; agents never call this directly. */
+export function setRuntimeRunVariable(context, input) {
+    if (!input.key.startsWith("runtime."))
+        throw new AppError("validation", "Controller runtime variables must use runtime.*", 2, { key: input.key });
+    return setRunVariable(context, input, input.value);
+}
+export function setFlowRunConfig(context, input) {
+    if (input.key !== "plan_review.mode" && input.key !== "code_review.mode") {
+        throw new AppError("validation", `Unknown RUN config key: ${input.key}`, 2);
+    }
+    if (!["auto", "off", "standard", "deep"].includes(input.value)) {
+        throw new AppError("validation", "--value for review mode must be auto, off, standard, or deep", 2);
+    }
+    const reason = requiredPlain(input.reason, "reason");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = authoritativeIndex(run);
+    const stageName = input.key === "plan_review.mode" ? "plan-review" : "code-review";
+    if (index.stage_runs.some((stage) => stage.stage === stageName)) {
+        throw new AppError("invalid_run_config_state", `${input.key} is frozen after ${stageName} starts`, 2, { run_id: run.id });
+    }
+    const now = context.now();
+    const settings = runSettings(index);
+    const previous = input.key === "plan_review.mode" ? settings.plan_review : settings.code_review;
+    const mode = input.value;
+    const source = input.source ?? "user_instruction";
+    if (previous.mode === mode && previous.reason === reason && previous.source === source) {
+        return { ok: true, run_id: run.id, settings, idempotent: true };
+    }
+    index.settings = input.key === "plan_review.mode"
+        ? { ...settings, plan_review: { mode, source, reason, updated_at: now } }
+        : { ...settings, code_review: { mode, source, reason, updated_at: now } };
+    index.updated_at = now;
+    persistRunState(context, project, run, index);
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.config_set", payload: { run_id: run.id, key: input.key, value: mode, source, reason } });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: "run_config_set", run_id: run.id, key: input.key, value: mode, source, reason });
+    return { ok: true, run_id: run.id, settings: runSettings(index), idempotent: false };
 }
 export function getFlowRunFlagsStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -305,7 +432,7 @@ export function reviseFlowRunFlags(context, input) {
 export function listFlowRuns(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const runs = context.db
-        .all(`SELECT * FROM flow_runs
+        .all(`SELECT * FROM runs
        WHERE project_id = ?
        ORDER BY updated_at DESC, id DESC`, [project.id])
         .map(flowRunSummary);
@@ -349,16 +476,11 @@ export function attachFlowRunStage(context, input) {
         payload: { run_id: run.id, stage, dir, status }
     });
     appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_attached", run_id: run.id, stage, status, attempt: stageRun.attempt ?? null });
-    if (status === "running") {
-        context.db.run("UPDATE flow_sessions SET current_stage = ?, updated_at = ? WHERE project_id = ? AND run_id = ?", [
-            stage,
-            now,
-            project.id,
-            run.id
-        ]);
+    // A stage transition must not rewrite every Session in the RUN.  A RUN may
+    // contain independent reviewer/worker sessions; their stage is set by the
+    // stage/work binding that actually owns that Session.
+    if (status === "running")
         refreshRunSessionProjection(context, project.id, run.id);
-        checkpointRunUsage(context, { projectId: project.id, runId: run.id, checkpoint: "stage_started", stage, stageAttempt: stageRun.attempt ?? null });
-    }
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), stage_run: stageRun, index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
@@ -382,11 +504,23 @@ export function completeFlowRunStage(context, input) {
         ...(input.report ? { report: input.report } : {}),
         ...(input.aliases && input.aliases.length > 0 ? { artifact_aliases: input.aliases } : {}),
         updated_at: now,
-        ...(status === "done" || status === "blocked" || status === "failed" || status === "skipped"
+        ...(status === "done" || status === "waiting_for_user" || status === "blocked" || status === "failed" || status === "skipped"
             ? { completed_at: now, duration_ms: durationMs(existing.started_at ?? null, now), git: gitFacts(run.workspace_root) }
             : {})
     };
     upsertStage(index, stageRun);
+    if (status === "waiting_for_user") {
+        index.status = "waiting_for_user";
+        index.verdict = "waiting_for_user";
+    }
+    else if (status === "blocked" || status === "failed") {
+        index.status = status;
+        index.verdict = status;
+    }
+    else if (status === "done" && index.status === "waiting_for_user") {
+        index.status = "running";
+        index.verdict = "running";
+    }
     index.current_stage = stage;
     index.attempts = index.stage_runs.map((item) => ({ stage: item.stage, attempt_number: Number((item.attempt ?? "try-001").replace("try-", "")) || 1, root: item.dir, archive: null, status: item.status, started_at: item.started_at ?? now, finished_at: item.completed_at ?? null }));
     index.updated_at = now;
@@ -403,16 +537,147 @@ export function completeFlowRunStage(context, input) {
         payload: { run_id: run.id, stage, status, stage_report: input.stageReport ?? null, data: input.data ?? null }
     });
     appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_completed", run_id: run.id, stage, status, attempt: stageRun.attempt ?? null });
-    checkpointRunUsage(context, { projectId: project.id, runId: run.id, checkpoint: "stage_finished", stage, stageAttempt: stageRun.attempt ?? null });
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), stage_run: stageRun, index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
+/** Pause one live stage without completing it or creating a new attempt. */
+export function pauseFlowRunStage(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = authoritativeIndex(run);
+    const stage = requiredPlain(input.stage, "stage");
+    const stageRun = index.stage_runs.find((item) => item.stage === stage);
+    if (!stageRun || stageRun.status !== "running") {
+        throw new AppError("invalid_stage_state", "Only a running stage can pause", 1, { run_id: run.id, stage, status: stageRun?.status ?? "missing" });
+    }
+    const now = context.now();
+    stageRun.status = "paused";
+    stageRun.updated_at = now;
+    stageRun.pause = {
+        id: input.pauseId,
+        reason: "waiting_for_user",
+        work_id: input.workId,
+        question_path: input.questionPath,
+        answer_path: null,
+        paused_at: now,
+        resumed_at: null
+    };
+    index.pause = stageRun.pause;
+    index.status = operationalRunStatus(context, project.id, run.id);
+    index.verdict = index.status === "paused" ? "paused" : "running";
+    index.next_action = "await_user_answer";
+    index.current_stage = stage;
+    index.updated_at = now;
+    index.attempts = index.stage_runs.map((item) => ({ stage: item.stage, attempt_number: Number((item.attempt ?? "try-001").replace("try-", "")) || 1, root: item.dir, archive: null, status: item.status, started_at: item.started_at ?? now, finished_at: item.completed_at ?? null }));
+    persistRunState(context, project, run, index);
+    refreshRunSessionProjection(context, project.id, run.id);
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.stage_paused", payload: { run_id: run.id, stage, work_id: input.workId, pause_id: input.pauseId, reason: "waiting_for_user" } });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_waiting_for_user", run_id: run.id, stage, work_id: input.workId, pause_id: input.pauseId, question_path: input.questionPath });
+    return { run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
+}
+/** Resume the same stage, Work and attempt after a user answer is recorded. */
+export function resumeFlowRunStage(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = authoritativeIndex(run);
+    const stage = requiredPlain(input.stage, "stage");
+    const stageRun = index.stage_runs.find((item) => item.stage === stage);
+    if (!stageRun || stageRun.status !== "paused" || !stageRun.pause || stageRun.pause.work_id !== input.workId) {
+        throw new AppError("invalid_stage_state", "Stage resume requires its matching paused Work", 1, { run_id: run.id, stage, work_id: input.workId, status: stageRun?.status ?? "missing" });
+    }
+    const now = context.now();
+    const pause = stageRun.pause;
+    const pausedMs = durationMs(pause.paused_at, now) ?? 0;
+    stageRun.status = "running";
+    stageRun.updated_at = now;
+    stageRun.paused_ms = (stageRun.paused_ms ?? 0) + pausedMs;
+    delete stageRun.pause;
+    index.pause = undefined;
+    index.status = "running";
+    index.verdict = "running";
+    index.next_action = `continue_${stage}`;
+    index.current_stage = stage;
+    index.updated_at = now;
+    index.attempts = index.stage_runs.map((item) => ({ stage: item.stage, attempt_number: Number((item.attempt ?? "try-001").replace("try-", "")) || 1, root: item.dir, archive: null, status: item.status, started_at: item.started_at ?? now, finished_at: item.completed_at ?? null }));
+    persistRunState(context, project, run, index);
+    refreshRunSessionProjection(context, project.id, run.id);
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.stage_resumed", payload: { run_id: run.id, stage, work_id: input.workId, pause_id: pause.id, answer_path: input.answerPath } });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: "user_answer_received", run_id: run.id, stage, work_id: input.workId, pause_id: pause.id, answer_path: input.answerPath });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_resumed", run_id: run.id, stage, work_id: input.workId, pause_id: pause.id, paused_ms: pausedMs });
+    return { run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
+}
+/** Pause the current stage for a non-user runtime blocker. */
+export function blockFlowRunStage(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = authoritativeIndex(run);
+    const stage = requiredPlain(input.stage, "stage");
+    const stageRun = index.stage_runs.find((item) => item.stage === stage);
+    if (!stageRun || stageRun.status !== "running")
+        throw new AppError("invalid_stage_state", "Only a running stage can be blocked", 1, { run_id: run.id, stage, status: stageRun?.status ?? "missing" });
+    const now = context.now();
+    stageRun.status = "blocked";
+    stageRun.updated_at = now;
+    stageRun.blocker = { kind: input.kind, code: input.code, summary: input.summary, retryable: input.retryable, work_id: input.workId, blocked_at: now, resumed_at: null };
+    index.blocker = stageRun.blocker;
+    index.status = "paused";
+    index.verdict = "paused";
+    index.next_action = "resolve_blocker_then_unblock_same_stage";
+    index.current_stage = stage;
+    index.updated_at = now;
+    persistRunState(context, project, run, index);
+    refreshRunSessionProjection(context, project.id, run.id);
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.stage_blocked", payload: { run_id: run.id, stage, work_id: input.workId, kind: input.kind, code: input.code, retryable: input.retryable } });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_blocked", run_id: run.id, stage, work_id: input.workId, kind: input.kind, code: input.code, summary: input.summary, retryable: input.retryable });
+    return { run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
+}
+/** Continue the same stage after its non-user blocker was repaired externally. */
+export function unblockFlowRunStage(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = authoritativeIndex(run);
+    const stage = requiredPlain(input.stage, "stage");
+    const stageRun = index.stage_runs.find((item) => item.stage === stage);
+    if (!stageRun || stageRun.status !== "blocked" || !stageRun.blocker || stageRun.blocker.work_id !== input.workId)
+        throw new AppError("invalid_stage_state", "Stage unblock requires its matching runtime blocker", 1, { run_id: run.id, stage, work_id: input.workId, status: stageRun?.status ?? "missing" });
+    const now = context.now();
+    const blocker = stageRun.blocker;
+    const blockedMs = durationMs(blocker.blocked_at, now) ?? 0;
+    stageRun.status = "running";
+    stageRun.updated_at = now;
+    stageRun.paused_ms = (stageRun.paused_ms ?? 0) + blockedMs;
+    delete stageRun.blocker;
+    index.blocker = undefined;
+    index.status = "running";
+    index.verdict = "running";
+    index.next_action = `continue_${stage}`;
+    index.current_stage = stage;
+    index.updated_at = now;
+    persistRunState(context, project, run, index);
+    refreshRunSessionProjection(context, project.id, run.id);
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.stage_unblocked", payload: { run_id: run.id, stage, work_id: input.workId, code: blocker.code } });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_unblocked", run_id: run.id, stage, work_id: input.workId, code: blocker.code, blocked_ms: blockedMs });
+    return { run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
+}
+function operationalRunStatus(context, projectId, runId) {
+    const unfinished = context.db.all("SELECT work_id, status, parent_work_id FROM works WHERE project_id = ? AND run_id = ? AND status IN ('created', 'running', 'paused')", [projectId, runId]);
+    const parents = new Set(unfinished.map((work) => work.parent_work_id).filter((id) => Boolean(id)));
+    const leaves = unfinished.filter((work) => !parents.has(work.work_id));
+    return leaves.length > 0 && leaves.every((work) => work.status === "paused") ? "paused" : "running";
+}
 export function completeFlowRun(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     const index = authoritativeIndex(run);
     const now = context.now();
     const status = parseRunStatus(input.status);
+    if (!['done', 'blocked', 'cancelled', 'failed'].includes(status)) {
+        throw new AppError('validation', 'completeFlowRun accepts terminal statuses only; use advanceFlowRun for a live RUN', 2, { status });
+    }
+    if (input.manualOverrideReason && (status === "cancelled" || status === "failed")) {
+        closeOpenStagesForOverride(index, status, now);
+        closeOpenWorksForOverride(context, project.id, run.id, status, now);
+    }
     index.status = status;
     index.verdict = input.verdict ?? (status === "done" ? "accepted" : status);
     index.next_action = input.nextAction ?? null;
@@ -429,27 +694,80 @@ export function completeFlowRun(context, input) {
     }
     persistRunState(context, project, run, index);
     closeRunOrchestrators(context, project.id, run, status, now);
+    const usageProjection = recalculateRunUsage(context, { projectId: project.id, runId: run.id });
+    const usage = {
+        status: usageProjection.status ?? "unavailable",
+        session_count: Array.isArray(usageProjection.sessions) ? usageProjection.sessions.length : 0,
+        coverage: usageProjection.coverage ?? {},
+        session_reconciliation: usageProjection.session_reconciliation ?? {}
+    };
     refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, {
         projectId: project.id,
-        eventType: "flow_run.completed",
-        payload: { run_id: run.id, status, verdict: index.verdict, next_action: index.next_action }
+        eventType: input.manualOverrideReason ? "flow_run.manual_override" : "flow_run.completed",
+        payload: { run_id: run.id, status, verdict: index.verdict, next_action: index.next_action, ...(input.manualOverrideReason ? { reason: input.manualOverrideReason } : {}) }
     });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "run_completed", run_id: run.id, status });
-    checkpointRunUsage(context, { projectId: project.id, runId: run.id, checkpoint: "run_finished" });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: input.manualOverrideReason ? "run_manual_override" : "run_completed", run_id: run.id, status, ...(input.manualOverrideReason ? { reason: input.manualOverrideReason } : {}) });
+    const updatedRun = requireRunById(context, project.id, run.id);
+    return { ok: true, run: flowRunSummary(updatedRun), index, usage, flow_guidance: guidanceForRun(context, updatedRun, index) };
+}
+/** Update a live RUN between stages without manufacturing terminal evidence. */
+export function advanceFlowRun(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = authoritativeIndex(run);
+    const now = context.now();
+    index.status = input.status;
+    index.verdict = input.verdict;
+    index.next_action = input.nextAction ?? null;
+    index.updated_at = now;
+    persistRunState(context, project, run, index);
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.progressed", payload: { run_id: run.id, status: input.status, verdict: input.verdict, next_action: index.next_action } });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: "run_progressed", run_id: run.id, status: input.status, next_action: index.next_action });
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
+function closeOpenStagesForOverride(index, status, now) {
+    const stageStatus = status === "cancelled" ? "skipped" : "failed";
+    for (const stage of index.stage_runs) {
+        if (stage.status !== "running" && stage.status !== "pending")
+            continue;
+        stage.status = stageStatus;
+        stage.updated_at = now;
+        stage.completed_at = now;
+        stage.duration_ms = durationMs(stage.started_at ?? null, now);
+    }
+    index.attempts = index.stage_runs.map((stage) => ({
+        stage: stage.stage,
+        attempt_number: Number((stage.attempt ?? "try-001").replace("try-", "")) || 1,
+        root: stage.dir,
+        archive: null,
+        status: stage.status,
+        started_at: stage.started_at ?? now,
+        finished_at: stage.completed_at ?? null
+    }));
+}
+function closeOpenWorksForOverride(context, projectId, runId, status, now) {
+    const workStatus = status === "cancelled" ? "cancelled" : "failed";
+    context.db.run(`UPDATE works
+       SET status = ?, updated_at = ?, completed_at = ?
+     WHERE project_id = ? AND run_id = ?
+       AND status IN ('created', 'running')`, [workStatus, now, now, projectId, runId]);
+    context.db.run(`UPDATE work_sessions
+       SET status = ?, updated_at = ?, completed_at = ?
+     WHERE work_id IN (SELECT work_id FROM works WHERE project_id = ? AND run_id = ?)
+       AND status <> 'completed'`, [workStatus, now, now, projectId, runId]);
+}
 function closeRunOrchestrators(context, projectId, run, status, now) {
     if (!["done", "blocked", "cancelled", "failed"].includes(status))
         return;
-    const active = context.db.all(`SELECT session_id FROM flow_sessions
+    const active = context.db.all(`SELECT session_id FROM sessions
      WHERE project_id = ? AND run_id = ? AND session_kind = 'orchestrator'
        AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [projectId, run.id]);
     if (active.length === 0)
         return;
     const reason = `run_${status}`;
-    context.db.run(`UPDATE flow_sessions SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
+    context.db.run(`UPDATE sessions SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
      WHERE project_id = ? AND run_id = ? AND session_kind = 'orchestrator'
        AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [reason, now, now, projectId, run.id]);
     context.db.run(`UPDATE flow_session_segments SET ended_at = ?
@@ -514,7 +832,7 @@ export function getFlowRunTimeline(context, input) {
     if (!hidden.has("sessions"))
         report.sessions = sessions;
     if (!hidden.has("usage"))
-        report.usage = usageForRun(context, { projectId: project.id, runId: run.id, groupBy: "session" });
+        report.usage = { status: "available_via_stat_usage", command: `dd-flow stat usage --run ${run.id} --project-root ${JSON.stringify(run.project_root)} --json` };
     if (!hidden.has("artifacts"))
         report.artifacts = index.stage_runs.map((stage) => ({
             stage: stage.stage,
@@ -526,16 +844,51 @@ export function getFlowRunTimeline(context, input) {
         }));
     return report;
 }
-export function getFlowRunUsage(context, input) {
+export function getStoredFlowRunUsage(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = authoritativeIndex(run);
+    const stageNames = input.stage?.split(",").map((value) => value.trim()).filter(Boolean) ?? [];
+    const stageRuns = stageNames.map((name) => index.stage_runs.find((item) => item.stage === name));
+    if (stageNames.length && stageRuns.some((stage) => !stage?.started_at))
+        throw new AppError("not_found", "RUN stage timing is unavailable", 1, { run_id: run.id, stages: stageNames });
+    const starts = stageRuns.map((stage) => stage.started_at).sort();
+    const finishes = stageRuns.map((stage) => stage.completed_at).filter((value) => Boolean(value)).sort();
+    const usage = recalculateRunUsage(context, {
+        projectId: project.id,
+        runId: run.id,
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        ...(starts.length ? { stage: { name: stageNames.join(","), startedAt: starts[0], completedAt: finishes.length === stageRuns.length ? finishes.at(-1) : null } } : {})
+    });
+    refreshRunSessionProjection(context, project.id, run.id);
+    return usage;
+}
+export function getFlowRunSessions(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    return usageForRun(context, { projectId: project.id, runId: run.id, groupBy: input.groupBy ?? "session" });
+    const sessions = context.db.all(`SELECT s.session_id, s.harness, s.provider_session_id, s.parent_session_id,
+            s.agent_id, s.worker_id, s.provider, s.model, s.reasoning, s.mode,
+            s.agent_type, s.transcript_path,
+            COUNT(ws.id) AS work_link_count
+       FROM sessions s
+       JOIN work_sessions ws ON ws.session_id = s.session_id
+       JOIN works w ON w.work_id = ws.work_id
+      WHERE w.project_id = ? AND w.run_id = ?
+      GROUP BY s.session_id, s.harness, s.provider_session_id, s.parent_session_id,
+               s.agent_id, s.worker_id, s.provider, s.model, s.reasoning, s.mode,
+               s.agent_type, s.transcript_path
+      ORDER BY s.created_at, s.session_id`, [project.id, run.id]);
+    return { ok: true, schema_id: "dd-flow/run-sessions@3", run_id: run.id, sessions };
 }
 export function appendFlowRunTimelineEvent(context, projectId, runId, event) {
     const run = requireRunById(context, projectId, runId);
     appendRunTimeline(runArtifactRoot(run), { run_id: run.id, ...event });
 }
 function guidanceForRun(context, run, index) {
+    if (run.flow_kind === "vnext_specify")
+        return vnextSpecifyGuidance(run, index);
+    if (run.flow_kind === "vnext_protocolize")
+        return vnextProtocolizeGuidance(run, index);
     if (run.status === "discarded") {
         return buildRunFlowGuidance({
             stageRuns: index.stage_runs,
@@ -550,7 +903,9 @@ function guidanceForRun(context, run, index) {
             const state = readProtocolRuntimeState(context, protocol).state;
             return buildRunFlowGuidance({
                 stageRuns: index.stage_runs,
-                protocolStage: state.stage,
+                protocolStage: state.status === "waiting_for_user" || state.status === "blocked" || state.status === "failed"
+                    ? state.status
+                    : state.stage,
                 ...(state.flow_contract ? { contract: state.flow_contract } : {}),
                 runId: run.id,
                 runDir: index.run_home?.relative_path ?? path.posix.join("runs", run.id)
@@ -563,6 +918,62 @@ function guidanceForRun(context, run, index) {
     }
     return buildRunFlowGuidance({ stageRuns: index.stage_runs, runId: run.id, runDir: index.run_home?.relative_path ?? path.posix.join("runs", run.id) });
 }
+function vnextProtocolizeGuidance(run, index) {
+    const specifyDone = index.stage_runs.some((stage) => stage.stage === "specify" && stage.status === "done");
+    const protocolizeDone = index.stage_runs.some((stage) => stage.stage === "protocolize" && stage.status === "done");
+    const planDone = index.stage_runs.some((stage) => stage.stage === "plan" && stage.status === "done");
+    const planReviewDone = index.stage_runs.some((stage) => stage.stage === "plan-review" && stage.status === "done");
+    const codeDone = index.stage_runs.some((stage) => stage.stage === "code" && stage.status === "done");
+    const codeReviewDone = index.stage_runs.some((stage) => stage.stage === "code-review" && stage.status === "done");
+    const nextStage = !specifyDone ? "specify" : !protocolizeDone ? "protocolize" : !planDone ? "plan" : !planReviewDone ? "plan-review" : !codeDone ? "code" : !codeReviewDone ? "code-review" : null;
+    const currentStage = index.current_stage ?? [...index.stage_runs].reverse().find((stage) => stage.status === "running" || stage.status === "done")?.stage ?? nextStage;
+    const terminal = run.status === "done" || run.status === "cancelled" || run.status === "failed" || run.status === "discarded";
+    const paused = run.status === "paused";
+    const blocked = paused && Boolean(index.blocker);
+    return {
+        current_stage: currentStage,
+        lifecycle: { flow: "mb_sdlc_vnext_protocolize", stage: currentStage, substage: null, status: run.status, terminal, source: "vnext_run" },
+        allowed_next_stages: terminal || paused || !nextStage ? [] : [nextStage],
+        recommended_next_action: terminal || !nextStage ? "none" : blocked ? "resolve_blocker_then_unblock_same_stage" : paused ? "await_user_answer_then_resume_same_stage" : `start_${nextStage.replace("-", "_")}`,
+        recommended_prompt: terminal || !nextStage ? "none" : blocked ? "unblock_command_from_blocker" : paused ? "resume_command_from_pause" : `.memory-bank/dd-flow/vnext/${nextStage}.md`,
+        required_predecessor_evidence: !specifyDone ? [] : !protocolizeDone ? ["01-specify/specify.json"] : !planDone ? ["01-specify/specify.json", "02-protocolize/protocolize-result.json"] : !planReviewDone ? ["03-plan/stage-report.json"] : !codeDone ? ["04-plan-review/stage-report.json"] : ["05-code/stage-report.json"],
+        guards: [],
+        blocked_if_missing: []
+    };
+}
+function vnextSpecifyGuidance(run, index) {
+    const terminal = ["done", "failed", "cancelled", "discarded"].includes(run.status);
+    const next = run.status === "paused" && index.blocker
+        ? "resolve_blocker_then_unblock_same_stage"
+        : run.status === "paused"
+            ? "await_user_answer_then_resume_same_stage"
+            : run.status === "waiting_for_user"
+                ? "await_user_answer"
+                : run.status === "done"
+                    ? "start_protocolize"
+                    : run.status === "running"
+                        ? "complete_work_session"
+                        : terminal
+                            ? "none"
+                            : "inspect_run_state";
+    return {
+        current_stage: "specify",
+        lifecycle: {
+            flow: "mb_sdlc_vnext_specify",
+            stage: "specify",
+            substage: null,
+            status: run.status,
+            terminal,
+            source: "vnext_run"
+        },
+        allowed_next_stages: terminal ? [] : ["specify"],
+        recommended_next_action: next,
+        recommended_prompt: terminal ? "none" : ".memory-bank/dd-flow/vnext/specify.md",
+        required_predecessor_evidence: [],
+        guards: [],
+        blocked_if_missing: []
+    };
+}
 function persistRunState(context, project, run, index, options = {}) {
     const runtimePath = run.runtime_path || projectRunJsonPath(context.ddFlowHome, project.id, run.id);
     const previousRuntime = readRuntimeSnapshot(runtimePath);
@@ -572,16 +983,17 @@ function persistRunState(context, project, run, index, options = {}) {
     if (options.flagRevision) {
         history.push(options.flagRevision);
     }
+    const persistedIndex = persistedVnextIndex(index);
     ensureDir(path.dirname(runtimePath));
-    writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, runtimeRevision, history));
-    context.db.run(`UPDATE flow_runs
+    writeJsonFile(runtimePath, runtimeSnapshotForIndex(persistedIndex, runtimeRevision, history));
+    context.db.run(`UPDATE runs
      SET status = ?, verdict = ?, next_action = ?, index_json = ?, runtime_path = ?, run_index_path = ?,
        updated_at = ?, completed_at = ?
      WHERE project_id = ? AND id = ?`, [
         index.status,
         index.verdict,
         index.next_action,
-        JSON.stringify(index),
+        JSON.stringify(persistedIndex),
         runtimePath,
         runtimePath,
         index.updated_at,
@@ -590,6 +1002,58 @@ function persistRunState(context, project, run, index, options = {}) {
         run.id
     ]);
 }
+/** vNext stores derived stage/work state only once: stage_runs, Works and Sessions. */
+function persistedVnextIndex(index) {
+    if (index.flow_kind !== "vnext_specify" && index.flow_kind !== "vnext_protocolize")
+        return index;
+    const persisted = structuredClone(index);
+    delete persisted.current_stage;
+    delete persisted.attempts;
+    delete persisted.workers;
+    delete persisted.session_coverage;
+    delete persisted.usage_coverage;
+    return persisted;
+}
+function runSettings(index) {
+    const planReview = index.settings?.plan_review;
+    const codeReview = index.settings?.code_review;
+    if (planReview && codeReview)
+        return { plan_review: planReview, code_review: codeReview };
+    return {
+        plan_review: {
+            mode: "auto",
+            source: "default",
+            reason: "No explicit review preference was recorded.",
+            updated_at: index.created_at
+        },
+        code_review: codeReview ?? {
+            mode: index.execution_profile?.settings.code_review_mode ?? "auto",
+            source: "default",
+            reason: "No explicit review preference was recorded.",
+            updated_at: index.created_at
+        }
+    };
+}
+function materializedRunVariables(index) {
+    const settings = runSettings(index);
+    return {
+        "policy.plan_review.requested_mode": settings.plan_review.mode,
+        "policy.code_review.requested_mode": settings.code_review.mode,
+        ...(index.variables ?? {})
+    };
+}
+function setRunVariable(context, input, value) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = authoritativeIndex(run);
+    if (index.variables?.[input.key] === value)
+        return { ok: true, run_id: run.id, key: input.key, value, idempotent: true };
+    index.variables = { ...(index.variables ?? {}), [input.key]: value };
+    index.updated_at = context.now();
+    persistRunState(context, project, run, index);
+    appendRunTimeline(runArtifactRoot(run), { at: index.updated_at, type: "run_variable_set", run_id: run.id, key: input.key });
+    return { ok: true, run_id: run.id, key: input.key, value, idempotent: false };
+}
 function appendRunTimeline(runHome, event) {
     ensureDir(runHome);
     const timelinePath = path.join(runHome, "timeline.jsonl");
@@ -630,11 +1094,13 @@ function readRuntimeSnapshot(file) {
     }
 }
 function authoritativeIndex(run) {
-    const runtime = readRuntimeSnapshot(run.runtime_path);
-    if (!runtime) {
-        throw new AppError("validation", "RUN authority is missing or invalid", 2, { run_id: run.id, path: run.runtime_path });
+    try {
+        const state = JSON.parse(run.index_json);
+        return { ...state, schema_id: runSchemaId };
+    }
+    catch (error) {
+        throw new AppError("validation", "RUN mechanical state in SQLite is missing or invalid", 2, { run_id: run.id, cause: String(error) });
     }
-    return { ...runtime, schema_id: runSchemaId };
 }
 function sanitizeTimelineValue(value, key) {
     if (key && /(secret|password|authorization|cookie|api[_-]?key|private[_-]?key|access[_-]?token|refresh[_-]?token|transcript|prompt|tool[_-]?output|document[_-]?content)/i.test(key)) {
@@ -677,7 +1143,7 @@ function resolveRun(context, projectId, idOrAlias) {
         return requireRunById(context, projectId, idOrAlias);
     }
     if (isShortEntityId(idOrAlias)) {
-        const matches = context.db.all("SELECT * FROM flow_runs WHERE project_id = ? AND short_id = ? ORDER BY updated_at DESC", [
+        const matches = context.db.all("SELECT * FROM runs WHERE project_id = ? AND short_id = ? ORDER BY updated_at DESC", [
             projectId,
             idOrAlias
         ]);
@@ -692,14 +1158,14 @@ function resolveRun(context, projectId, idOrAlias) {
     throw new AppError("not_found", `Run is not registered: ${idOrAlias}`, 1, { run_id: idOrAlias });
 }
 function requireRunById(context, projectId, runId) {
-    const run = context.db.get("SELECT * FROM flow_runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const run = context.db.get("SELECT * FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     if (!run) {
         throw new AppError("not_found", `Run is not registered: ${runId}`, 1, { run_id: runId });
     }
     return run;
 }
 function nextRunId(context, projectId, slug) {
-    const rows = context.db.all("SELECT id FROM flow_runs WHERE project_id = ? AND id LIKE 'RUN-%'", [projectId]);
+    const rows = context.db.all("SELECT id FROM runs WHERE project_id = ? AND id LIKE 'RUN-%'", [projectId]);
     const max = rows.reduce((value, row) => {
         try {
             const parsed = parseFullEntityId(row.id);
@@ -749,19 +1215,19 @@ function parseRunFlowKind(value) {
     return normalized;
 }
 function parseRunStatus(value) {
-    if (!["running", "done", "blocked", "cancelled", "failed"].includes(value)) {
+    if (!["running", "paused", "waiting_for_user", "done", "blocked", "cancelled", "failed"].includes(value)) {
         throw new AppError("validation", "run status is not supported", 2, {
             status: value,
-            allowed: ["running", "done", "blocked", "cancelled", "failed"]
+            allowed: ["running", "paused", "waiting_for_user", "done", "blocked", "cancelled", "failed"]
         });
     }
     return value;
 }
 function parseStageStatus(value) {
-    if (!["pending", "running", "done", "blocked", "skipped", "failed"].includes(value)) {
+    if (!["pending", "running", "paused", "waiting_for_user", "done", "blocked", "skipped", "failed"].includes(value)) {
         throw new AppError("validation", "stage status is not supported", 2, {
             status: value,
-            allowed: ["pending", "running", "done", "blocked", "skipped", "failed"]
+            allowed: ["pending", "running", "paused", "waiting_for_user", "done", "blocked", "skipped", "failed"]
         });
     }
     return value;
@@ -827,12 +1293,13 @@ function writeJsonFile(file, value) {
 function runArtifactRoot(run) {
     return run.run_home_path ?? path.dirname(run.runtime_path);
 }
-function gitFacts(workspaceRoot) {
+export function gitFacts(workspaceRoot) {
     const read = (args) => {
         const result = spawnSync("git", ["-C", workspaceRoot, ...args.split(" ")], { encoding: "utf8" });
         return result.status === 0 ? result.stdout.trim() || null : null;
     };
-    const status = read("status --porcelain --untracked-files=all");
+    const statusResult = spawnSync("git", ["-C", workspaceRoot, "status", "--porcelain", "--untracked-files=all"], { encoding: "utf8" });
+    const status = statusResult.status === 0 ? statusResult.stdout.trim() : null;
     return {
         branch: read("branch --show-current"),
         head: read("rev-parse HEAD"),