@deksden-com/dd-flow-cli 0.9.0-beta.104 → 0.9.0-beta.106

package/dist/services/runs.js

@@ -2,6 +2,8 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { withProjectionLock } from "../storage/projection-lock.js";
+import { reconcileRunStageReports } from "./stage-report-renderer.js";
 import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
 import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadCanonicalFlowContract, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
@@ -15,6 +17,7 @@ import { refreshRunSessionProjection } from "./run-projection.js";
 import { resolveCanonRoot } from "./canon.js";
 import { bindCurrentEngineToRun } from "./engines.js";
 import { executionProfilePath, loadVnextExecutionProfile } from "./vnext-execution-profile.js";
+import { loadVnextWorkspacePolicy } from "./vnext-workspace-policy.js";
 import { assertSameSessionMerge, loadExecutionRoutingInput, resolveStageTransition, snapshotAgentProfiles } from "./execution-policy.js";
 import { isLegalVnextTransition, vnextStageDirectory, vnextStages } from "../domain/stage-catalog.js";
 import { publicSessionIdentity } from "./session-identity.js";
@@ -144,7 +147,6 @@ export function startFlowRun(context, input, prepared = prepareFlowRunStart(cont
         fs.writeFileSync(path.join(runHome, "execution-routing.input.json"), routingInput.bytes, { flag: "wx", mode: 0o600 });
     bindCurrentEngineToRun(context, { projectRoot, runId, runRoot: 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, run_root, layout_version, artifact_root_kind,
@@ -178,8 +180,9 @@ export function startFlowRun(context, input, prepared = prepareFlowRunStart(cont
         eventType: "flow_run.started",
         payload: { run_id: runId, flow_kind: flowKind, subject: index.subject, workspace_root: workspaceRoot, run_home: runHome }
     });
-    appendRunTimeline(runHome, { at: now, type: "run_started", run_id: runId });
-    appendRunTimeline(runHome, {
+    context.db.afterCommit(() => publishRunProjections(context, project.id, runId));
+    appendRunTimeline(context, project.id, runId, { at: now, type: "run_started", run_id: runId });
+    appendRunTimeline(context, project.id, runId, {
         at: now,
         type: "flow_flags_resolved",
         run_id: runId,
@@ -192,7 +195,7 @@ export function startFlowRun(context, input, prepared = prepareFlowRunStart(cont
 function snapshotVnextExecutionProfile(projectRoot, ddFlowHome, routingInput) {
     const profile = loadVnextExecutionProfile(projectRoot);
     const sourcePath = executionProfilePath(projectRoot);
-    return freezeRunExecutionRouting(ddFlowHome, {
+    const frozen = freezeRunExecutionRouting(ddFlowHome, {
         schema_id: "dd-flow/run-execution-profile@1",
         source_path: sourcePath,
         source_checksum: crypto.createHash("sha256").update(fs.readFileSync(sourcePath)).digest("hex"),
@@ -208,6 +211,12 @@ function snapshotVnextExecutionProfile(projectRoot, ddFlowHome, routingInput) {
             ...(profile.execution ? { execution: profile.execution } : {})
         }
     }, routingInput);
+    if (frozen.settings.merge_mode === "same_session" && frozen.settings.stop_target === "merge_completed"
+        && fs.existsSync(path.join(projectRoot, ".memory-bank", "dd-flow", "project-workspace.json"))
+        && loadVnextWorkspacePolicy(projectRoot).workspace.route === "feature_worktree") {
+        throw new AppError("merge_session_workspace_conflict", "Feature-worktree MERGE targets the integration checkout; use server MERGE or a qualified new Session", 2, { project_root: projectRoot });
+    }
+    return frozen;
 }
 /** Fresh RUN and fresh stage-entry experiments freeze through the same resolver. */
 export function freezeRunExecutionRouting(ddFlowHome, base, input) {
@@ -238,7 +247,7 @@ export function importFlowRunExecutionProfile(context, input) {
     index.execution_profile = { ...input.profile, stage_entry_import: { stage: input.stage, lineage_file: input.lineageFile } };
     index.updated_at = context.now();
     persistRunState(context, project, run, index);
-    appendRunTimeline(run.run_root, { at: index.updated_at, type: "execution_policy_imported", stage: input.stage, lineage_file: input.lineageFile, source_checksum: input.profile.routing_input?.source_checksum });
+    appendRunTimeline(context, project.id, run.id, { at: index.updated_at, type: "execution_policy_imported", stage: input.stage, lineage_file: input.lineageFile, source_checksum: input.profile.routing_input?.source_checksum });
 }
 /**
  * A vNext route may materialize a feature checkout after its semantic
@@ -259,7 +268,7 @@ export function rebindFlowRunWorkspace(context, input) {
     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 });
+    appendRunTimeline(context, project.id, run.id, { 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) {
@@ -307,7 +316,7 @@ function runContinuation(context, run, index) {
         const command = `${flowCommand(context)} stage start ${run.id} --stage ${next} --project-root ${JSON.stringify(run.project_root)} --json`;
         const profile = index.execution_profile;
         const execution = profile?.settings.execution ? profile.agent_profiles
-            ? { status: "resolved", ...resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy: profile.settings.execution, profiles: profile.agent_profiles, ...(completed ? { fromStage: completed.stage } : {}), stage: next, stageSessionMode: profile.settings.stage_session_mode, mergeMode: profile.settings.merge_mode }) }
+            ? { status: "resolved", ...resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy: profile.settings.execution, profiles: profile.agent_profiles, projectRoot: run.project_root, workspaceRoot: run.workspace_root, ...(completed ? { fromStage: completed.stage } : {}), stage: next, stageSessionMode: profile.settings.stage_session_mode, mergeMode: profile.settings.merge_mode }) }
             : { status: "unfrozen", reason: "execution_profile_not_frozen" }
             : undefined;
         return { kind: "start_stage", stage: next, attempt: null, work_id: null, reason: "legal_successor", command, ...(execution ? { execution } : {}) };
@@ -362,7 +371,7 @@ export function setFlowRunConfig(context, input) {
     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 });
+    appendRunTimeline(context, project.id, run.id, { 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 prepareFlowRunConfig(context, input) {
@@ -404,8 +413,8 @@ export function getFlowRunFlagsStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     const index = authoritativeIndex(run);
-    const runtime = readRuntimeSnapshot(run.runtime_path);
-    const flags = runtime?.flow_flags ?? index.flow_flags;
+    const legacyRuntime = index.flow_flags ? null : readRuntimeSnapshot(run.runtime_path);
+    const flags = index.flow_flags ?? legacyRuntime?.flow_flags;
     if (!flags) {
         return {
             ok: true,
@@ -423,7 +432,7 @@ export function getFlowRunFlagsStatus(context, input) {
         snapshot_revision: flags.snapshot_revision,
         snapshot_checksum: flags.snapshot_checksum,
         flow_flags: flags,
-        runtime_revision: runtime?.runtime_revision ?? index.runtime_revision ?? null
+        runtime_revision: index.runtime_revision ?? legacyRuntime?.runtime_revision ?? null
     };
 }
 export function reviseFlowRunFlags(context, input) {
@@ -431,22 +440,23 @@ export function reviseFlowRunFlags(context, input) {
     const run = resolveRun(context, project.id, input.runId);
     assertRunMutationAllowed(context, project.id, run.id);
     const idempotencyKey = requiredPlain(input.idempotencyKey, "idempotency-key");
-    context.db.beginWriteTransaction();
-    let committed = false;
-    try {
+    const priorMutation = context.db.get("SELECT result_json FROM flow_run_flag_mutations WHERE project_id = ? AND run_id = ? AND idempotency_key = ?", [project.id, run.id, idempotencyKey]);
+    if (priorMutation)
+        return { ...JSON.parse(priorMutation.result_json), idempotent: true };
+    // Canonical contract bytes are prepared before taking the writer. Revision
+    // and idempotency are compared again against SQL authority under the lock.
+    const contract = loadProjectFlowContract(run.project_root);
+    return context.db.writeTransaction(() => {
         const existingMutation = context.db.get("SELECT result_json FROM flow_run_flag_mutations WHERE project_id = ? AND run_id = ? AND idempotency_key = ?", [project.id, run.id, idempotencyKey]);
         if (existingMutation) {
             const result = { ...JSON.parse(existingMutation.result_json), idempotent: true };
-            context.db.exec("COMMIT");
-            committed = true;
             return result;
         }
         // Read the authority only after the write lock: two callers with the same
         // expected revision must not both pass the compare-and-set check.
         const lockedRun = requireRunById(context, project.id, run.id);
         const index = authoritativeIndex(lockedRun);
-        const runtime = readRuntimeSnapshot(lockedRun.runtime_path);
-        const current = runtime?.flow_flags ?? index.flow_flags;
+        const current = index.flow_flags;
         if (!current) {
             throw new AppError("validation", "Legacy RUN has no flow-flag snapshot; revise is unavailable", 2, { run_id: run.id });
         }
@@ -463,7 +473,6 @@ export function reviseFlowRunFlags(context, input) {
             });
         }
         const now = context.now();
-        const contract = loadProjectFlowContract(lockedRun.project_root);
         const next = resolveFlowFlags(contract, {
             flowKind: index.flow_kind,
             preset: input.preset ?? current.preset.applied,
@@ -519,14 +528,12 @@ export function reviseFlowRunFlags(context, input) {
         context.db.run(`INSERT INTO flow_run_flag_mutations
         (project_id, run_id, idempotency_key, expected_revision, resulting_revision, result_json, created_at)
        VALUES (?, ?, ?, ?, ?, ?, ?)`, [project.id, run.id, idempotencyKey, input.expectedRevision, next.snapshot_revision, JSON.stringify(result), now]);
-        context.db.exec("COMMIT");
-        committed = true;
         appendAudit(context, {
             projectId: project.id,
             eventType: "flow_run.flags_revised",
             payload: { run_id: run.id, snapshot_revision: next.snapshot_revision, snapshot_checksum: next.snapshot_checksum, ...(reason ? { reason } : {}) }
         });
-        appendRunTimeline(runArtifactRoot(run), {
+        appendRunTimeline(context, project.id, run.id, {
             at: now,
             type: "flow_flags_revised",
             run_id: run.id,
@@ -536,12 +543,7 @@ export function reviseFlowRunFlags(context, input) {
             ...(reason ? { reason } : {})
         });
         return result;
-    }
-    catch (error) {
-        if (!committed)
-            context.db.exec("ROLLBACK");
-        throw error;
-    }
+    }, "runs.reviseFlowFlags");
 }
 export function listFlowRuns(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -556,9 +558,9 @@ export function prepareFlowRunStageAttachment(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     assertRunMutationAllowed(context, project.id, run.id);
-    const index = authoritativeIndex(run);
     const stage = requiredPlain(input.stage, "stage");
     const dir = prepareStageDirectory(input.dir);
+    const index = authoritativeIndex(run);
     const status = parseStageStatus(input.status);
     const existing = index.stage_runs.find((item) => item.stage === stage);
     assertVnextStageStart(run, index, stage, status, existing);
@@ -567,9 +569,12 @@ export function prepareFlowRunStageAttachment(context, input) {
 export function attachFlowRunStage(context, input) {
     // Mutable stage state is re-read immediately before archiving/persisting.
     const { project, run, index, stage, dir, status, existing } = prepareFlowRunStageAttachment(context, input);
+    const runRoot = runArtifactRoot(run);
+    if (fs.existsSync(path.join(runRoot, `.archive-${dir}.json`)))
+        archiveExistingStageAttempt(context, project.id, run.id, runRoot, dir);
     const now = context.now();
     if (status === "running" && existing) {
-        archiveExistingStageAttempt(context, project.id, run.id, runArtifactRoot(run), dir);
+        archiveExistingStageAttempt(context, project.id, run.id, runRoot, dir);
     }
     const stageRun = {
         ...(existing ?? { order: index.stage_runs.length + 1 }),
@@ -597,7 +602,8 @@ export function attachFlowRunStage(context, input) {
         eventType: "flow_run.stage_attached",
         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 });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "stage_attached", run_id: run.id, stage, status, attempt: stageRun.attempt ?? null });
+    context.db.afterCommit(() => reconcileRunStageReports(context, project.id, run.id, stage));
     // 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.
@@ -608,7 +614,7 @@ export function attachFlowRunStage(context, input) {
 }
 /** Keep synchronous stage settlement atomic; files are projections, SQLite is authoritative. */
 export function withStageSettlement(context, operation) {
-    return context.db.writeTransaction(operation);
+    return context.db.writeTransaction(operation, "stage.settle");
 }
 export function prepareFlowRunStageCompletion(context, input) {
     for (const [name, value] of Object.entries({ stageReport: input.stageReport, data: input.data, dataSchemaId: input.dataSchemaId, report: input.report })) {
@@ -634,58 +640,74 @@ export function prepareFlowRunStageCompletion(context, input) {
     if (!existing) {
         throw new AppError("not_found", `Run stage is not attached: ${stage}`, 1, { run_id: run.id, stage });
     }
-    return { project, run, index, stage, status, existing };
-}
-export function completeFlowRunStage(context, input) {
-    const { project, run, index, stage, status, existing } = prepareFlowRunStageCompletion(context, input);
-    const now = context.now();
     const dataPath = input.data ? path.join(runArtifactRoot(run), existing.dir, input.data) : null;
-    const stageRun = {
-        ...existing,
-        status,
-        ...(input.stageReport ? { stage_report: input.stageReport } : {}),
-        ...(input.data ? { data: input.data } : {}),
-        ...(dataPath && fs.existsSync(dataPath) ? { data_sha256: crypto.createHash("sha256").update(fs.readFileSync(dataPath)).digest("hex") } : {}),
-        ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : {}),
-        ...(input.report ? { report: input.report } : {}),
-        ...(input.usage ? { usage: input.usage } : {}),
-        ...(input.aliases && input.aliases.length > 0 ? { artifact_aliases: input.aliases } : {}),
-        updated_at: now,
-        ...(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;
-    index.execution = {
-        project_root: index.execution?.project_root ?? run.project_root,
-        workspace_root: index.execution?.workspace_root ?? run.workspace_root,
-        git: gitFacts(run.workspace_root)
-    };
-    persistRunState(context, project, run, index);
-    refreshRunSessionProjection(context, project.id, run.id);
-    appendAudit(context, {
-        projectId: project.id,
-        eventType: "flow_run.stage_completed",
-        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 });
+    const dataSha256 = input.dataSha256 ?? (dataPath && fs.existsSync(dataPath) ? crypto.createHash("sha256").update(fs.readFileSync(dataPath)).digest("hex") : null);
+    if (dataSha256 && !/^[a-f0-9]{64}$/.test(dataSha256))
+        throw new AppError("validation", "Stage data SHA-256 is invalid", 2);
+    return { project, run, index, stage, status, existing, dataSha256, git: input.git ?? gitFacts(run.workspace_root), generation: ["done", "failed", "skipped"].includes(status) ? assertStageSettlementAllowed(context, project.id, run.id, stage) : assertRunMutationAllowed(context, project.id, run.id) };
+}
+export function completeFlowRunStage(context, input, prepared = prepareFlowRunStageCompletion(context, input)) {
+    const { project, run, stage, status, dataSha256, git, generation } = prepared;
+    const completed = context.db.writeTransaction(() => {
+        if (["done", "failed", "skipped"].includes(status))
+            assertStageSettlementAllowed(context, project.id, run.id, stage, generation);
+        else
+            assertRunMutationAllowed(context, project.id, run.id, generation);
+        const latest = requireRunById(context, project.id, run.id);
+        const index = authoritativeIndex(latest);
+        const existing = index.stage_runs.find((item) => item.stage === stage);
+        if (!existing || existing.attempt !== prepared.existing.attempt || index.runtime_revision !== prepared.index.runtime_revision) {
+            throw new AppError("stage_revision_changed", "Stage attempt changed during finish preparation", 1, { run_id: run.id, stage, expected_attempt: prepared.existing.attempt, actual_attempt: existing?.attempt ?? null });
+        }
+        const now = context.now();
+        const stageRun = {
+            ...existing,
+            status,
+            ...(input.stageReport ? { stage_report: input.stageReport } : {}),
+            ...(input.data ? { data: input.data } : {}),
+            ...(dataSha256 ? { data_sha256: dataSha256 } : {}),
+            ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : {}),
+            ...(input.report ? { report: input.report } : {}),
+            ...(input.usage ? { usage: input.usage } : {}),
+            ...(input.aliases && input.aliases.length > 0 ? { artifact_aliases: input.aliases } : {}),
+            updated_at: now,
+            ...(status === "done" || status === "waiting_for_user" || status === "blocked" || status === "failed" || status === "skipped"
+                ? { completed_at: now, duration_ms: durationMs(existing.started_at ?? null, now), git }
+                : {})
+        };
+        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;
+        index.execution = {
+            project_root: index.execution?.project_root ?? run.project_root,
+            workspace_root: index.execution?.workspace_root ?? run.workspace_root,
+            git
+        };
+        persistRunState(context, project, latest, index);
+        context.db.afterCommit(() => refreshRunSessionProjection(context, project.id, run.id));
+        appendAudit(context, {
+            projectId: project.id,
+            eventType: "flow_run.stage_completed",
+            payload: { run_id: run.id, stage, status, stage_report: input.stageReport ?? null, data: input.data ?? null }
+        });
+        appendRunTimeline(context, project.id, run.id, { at: now, type: "stage_completed", run_id: run.id, stage, status, attempt: stageRun.attempt ?? null });
+        return { index, stageRun };
+    }, "runs.completeFlowRunStage");
     const updatedRun = requireRunById(context, project.id, run.id);
-    return { ok: true, run: flowRunSummary(updatedRun), stage_run: stageRun, index, flow_guidance: guidanceForRun(context, updatedRun, index) };
+    return { ok: true, run: flowRunSummary(updatedRun), stage_run: completed.stageRun, index: completed.index, flow_guidance: guidanceForRun(context, updatedRun, completed.index) };
 }
 /** Pause one live stage without completing it or creating a new attempt. */
 export function pauseFlowRunStage(context, input) {
@@ -720,7 +742,7 @@ export function pauseFlowRunStage(context, input) {
     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 });
+    appendRunTimeline(context, project.id, run.id, { 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. */
@@ -751,8 +773,8 @@ export function resumeFlowRunStage(context, input) {
     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 });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "user_answer_received", run_id: run.id, stage, work_id: input.workId, pause_id: pause.id, answer_path: input.answerPath });
+    appendRunTimeline(context, project.id, run.id, { 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. */
@@ -786,7 +808,7 @@ export function blockFlowRunStage(context, input, prepared = prepareFlowRunStage
     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 });
+    appendRunTimeline(context, project.id, run.id, { 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. */
@@ -818,7 +840,7 @@ export function unblockFlowRunStage(context, input, prepared = prepareFlowRunSta
     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 });
+    appendRunTimeline(context, project.id, run.id, { 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) {
@@ -904,7 +926,7 @@ export function completeFlowRun(context, input) {
         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: input.manualOverrideReason ? "run_manual_override" : "run_completed", run_id: run.id, status, ...(input.manualOverrideReason ? { reason: input.manualOverrideReason } : {}) });
+    appendRunTimeline(context, project.id, run.id, { 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) };
 }
@@ -925,7 +947,7 @@ export function advanceFlowRun(context, input) {
     index.updated_at = now;
     persistRunState(context, project, run, index);
     appendAudit(context, { projectId: project.id, eventType: "flow_run.progressed", payload: { run_id: run.id, status: index.status, verdict: input.verdict, next_action: index.next_action } });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "run_progressed", run_id: run.id, status: index.status, next_action: index.next_action });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "run_progressed", run_id: run.id, status: index.status, next_action: index.next_action });
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, ...(control ? { control } : {}), run: flowRunSummary(updatedRun), index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
@@ -990,7 +1012,7 @@ export function prepareVnextMergeSourceRepairAttempt(context, input) {
     }));
     persistRunState(context, project, run, index);
     appendAudit(context, { projectId: project.id, eventType: "flow_run.merge_source_repair_prepared", payload: { run_id: run.id, merge_request_id: input.mergeRequestId, cycle } });
-    appendRunTimeline(root, { at: now, type: "merge_source_repair_prepared", run_id: run.id, merge_request_id: input.mergeRequestId, cycle });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "merge_source_repair_prepared", run_id: run.id, merge_request_id: input.mergeRequestId, cycle });
     return { run_id: run.id, cycle };
 }
 function closeOpenStagesForOverride(index, status, now) {
@@ -1039,7 +1061,7 @@ function closeRunOrchestrators(context, projectId, run, status, now) {
     context.db.run(`UPDATE flow_session_segments SET ended_at = ?
      WHERE project_id = ? AND run_id = ? AND session_id IN (${active.map(() => "?").join(", ")}) AND ended_at IS NULL`, [now, projectId, run.id, ...active.map((session) => session.session_id)]);
     for (const session of active) {
-        appendRunTimeline(runArtifactRoot(run), {
+        appendRunTimeline(context, projectId, run.id, {
             at: now,
             type: "session_stopped",
             run_id: run.id,
@@ -1162,7 +1184,7 @@ export function getFlowRunSessions(context, input) {
 }
 export function appendFlowRunTimelineEvent(context, projectId, runId, event) {
     const run = requireRunById(context, projectId, runId);
-    appendRunTimeline(runArtifactRoot(run), { run_id: run.id, ...event });
+    appendRunTimeline(context, projectId, run.id, { run_id: run.id, ...event });
 }
 function guidanceForRun(context, run, index) {
     if (run.flow_kind === "vnext_specify")
@@ -1262,39 +1284,26 @@ function persistRunState(context, project, run, index, options = {}) {
     if (index.status === "running" && ["draining", "sealed", "resuming"].includes(recoveryGuard(context, project.id, run.id)?.status ?? ""))
         index.status = "paused";
     const runtimePath = run.runtime_path || projectRunJsonPath(context.ddFlowHome, project.id, run.id);
-    const previousRuntime = readRuntimeSnapshot(runtimePath);
-    const runtimeRevision = Math.max(index.runtime_revision ?? 0, previousRuntime?.runtime_revision ?? 0) + 1;
-    index.runtime_revision = runtimeRevision;
-    const history = [...(previousRuntime?.flag_revision_history ?? [])];
-    if (options.flagRevision) {
-        history.push(options.flagRevision);
-    }
-    const persistedIndex = persistedVnextIndex(index);
-    ensureDir(path.dirname(runtimePath));
-    context.db.exec("SAVEPOINT persist_run_state");
-    try {
-        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(persistedIndex),
-            runtimePath,
-            runtimePath,
-            index.updated_at,
-            index.completed_at ?? null,
-            project.id,
-            run.id
-        ]);
-        writeJsonFile(runtimePath, runtimeSnapshotForIndex(persistedIndex, runtimeRevision, history));
-        context.db.exec("RELEASE persist_run_state");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK TO persist_run_state; RELEASE persist_run_state");
-        throw error;
-    }
+    context.db.writeTransaction(() => {
+        const stored = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, run.id]);
+        if (!stored)
+            throw new AppError("not_found", "RUN is not registered", 1, { run_id: run.id });
+        const previous = JSON.parse(stored.index_json);
+        const actualRevision = previous.runtime_revision ?? 0;
+        const expectedRevision = index.runtime_revision ?? 0;
+        if (actualRevision !== expectedRevision)
+            throw new AppError("run_revision_changed", "RUN changed during preparation", 1, { run_id: run.id, expected_revision: expectedRevision, actual_revision: actualRevision });
+        index.runtime_revision = actualRevision + 1;
+        const history = [...(previous.flag_revision_history ?? [])];
+        if (options.flagRevision)
+            history.push(options.flagRevision);
+        index.flag_revision_history = history.slice(-32);
+        const updated = 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 = ? AND index_json = ?`, [index.status, index.verdict, index.next_action, JSON.stringify(persistedVnextIndex(index)), runtimePath, runtimePath, index.updated_at, index.completed_at ?? null, project.id, run.id, stored.index_json]);
+        if (updated.changes !== 1)
+            throw new AppError("run_revision_changed", "RUN changed during preparation", 1, { run_id: run.id });
+        context.db.afterCommit(() => publishRunProjections(context, project.id, run.id));
+    }, "runs.persistRunState");
 }
 /** vNext stores derived stage/work state only once: stage_runs, Works and Sessions. */
 function persistedVnextIndex(index) {
@@ -1350,26 +1359,50 @@ function setRunVariable(context, input, value, prepared = prepareRunVariable(con
     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 });
+    appendRunTimeline(context, project.id, run.id, { 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");
-    let sequence = 0;
-    if (fs.existsSync(timelinePath)) {
-        const lines = fs.readFileSync(timelinePath, "utf8").trim().split(/\r?\n/).filter(Boolean);
-        const last = lines.length > 0 ? JSON.parse(lines[lines.length - 1]) : undefined;
-        sequence = typeof last?.sequence === "number" ? last.sequence : lines.length;
-    }
-    const safeEvent = sanitizeTimelineValue(event);
-    const enriched = {
-        event_id: crypto.randomUUID(),
-        sequence: sequence + 1,
-        at: typeof safeEvent.at === "string" ? safeEvent.at : new Date().toISOString(),
-        ...safeEvent
-    };
-    fs.appendFileSync(timelinePath, `${JSON.stringify(enriched)}\n`);
+function appendRunTimeline(context, projectId, runId, event) {
+    context.db.writeTransaction(() => {
+        const last = context.db.get("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.timeline' AND json_extract(payload_json, '$.run_id') = ? ORDER BY id DESC LIMIT 1", [projectId, runId]);
+        const sequence = last ? Number(JSON.parse(last.payload_json).sequence) + 1 : 1;
+        const safeEvent = sanitizeTimelineValue(event);
+        const enriched = { event_id: crypto.randomUUID(), sequence, at: typeof safeEvent.at === "string" ? safeEvent.at : context.now(), ...safeEvent };
+        appendAudit(context, { projectId, eventType: "flow_run.timeline", payload: { run_id: runId, sequence, event: enriched } });
+        context.db.afterCommit(() => publishRunProjections(context, projectId, runId));
+    }, "runs.appendRunTimeline");
+}
+/** Rebuild projections from committed SQL after taking a per-RUN filesystem lock. */
+export function publishRunProjections(context, 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", 1, { run_id: runId });
+    const runtimePath = run.runtime_path || projectRunJsonPath(context.ddFlowHome, projectId, runId);
+    ensureDir(path.dirname(runtimePath));
+    withProjectionLock(`${runtimePath}.publish-lock`, () => {
+        // A delayed publisher must observe the latest commit after acquiring its lock.
+        const latest = context.db.get("SELECT * FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+        if (!latest)
+            throw new AppError("not_found", "RUN is not registered", 1, { run_id: runId });
+        const index = authoritativeIndex(latest);
+        const mutations = context.db.all("SELECT resulting_revision, result_json, created_at, idempotency_key FROM flow_run_flag_mutations WHERE project_id = ? AND run_id = ? ORDER BY resulting_revision DESC LIMIT 32", [projectId, runId]);
+        const history = mutations.reverse().map((row) => ({
+            revision: row.resulting_revision,
+            checksum: String(JSON.parse(row.result_json).snapshot_checksum ?? ""),
+            at: row.created_at,
+            idempotency_key: row.idempotency_key
+        }));
+        writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, index.runtime_revision ?? 1, history.length ? history : index.flag_revision_history ?? []));
+        const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.timeline' AND json_extract(payload_json, '$.run_id') = ? ORDER BY id", [projectId, runId]);
+        if (latest.run_root) {
+            const timelinePath = path.join(latest.run_root, "timeline.jsonl");
+            ensureDir(path.dirname(timelinePath));
+            const bytes = rows.map((row) => JSON.stringify(JSON.parse(row.payload_json).event)).join("\n");
+            const temporary = `${timelinePath}.tmp-${process.pid}-${crypto.randomUUID()}`;
+            fs.writeFileSync(temporary, bytes ? `${bytes}\n` : "");
+            fs.renameSync(temporary, timelinePath);
+        }
+    });
 }
 function runtimeSnapshotForIndex(index, runtimeRevision, flagRevisionHistory = []) {
     const rest = { ...index };
@@ -1604,6 +1637,16 @@ export function archiveExistingStageAttempt(context, projectId, runId, runRoot,
     }
     const journal = path.join(runRoot, `.archive-${stageDir}.json`);
     const pending = fs.existsSync(journal) ? JSON.parse(fs.readFileSync(journal, "utf8")) : null;
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const prior = row ? JSON.parse(row.index_json) : null;
+    const live = prior?.stage_runs.find((stage) => stage.dir === stageDir);
+    const generation = row ? assertRunMutationAllowed(context, projectId, runId) : 0;
+    if (pending && (pending.project_id && pending.project_id !== projectId || pending.run_id && pending.run_id !== runId))
+        throw new AppError("archive_owner_changed", "Archive journal belongs to another RUN", 1, { journal });
+    if (pending?.generation !== undefined && pending.generation !== generation)
+        throw new AppError("archive_owner_changed", "RUN generation changed while an archive was pending", 1, { journal, expected_generation: pending.generation, generation });
+    if (pending?.prior_attempt && live?.attempt !== pending.prior_attempt && live?.attempt !== pending.next_attempt)
+        throw new AppError("archive_owner_changed", "Stage attempt changed while an archive was pending", 1, { journal, prior_attempt: pending.prior_attempt, actual_attempt: live?.attempt ?? null });
     const entries = pending?.entries ?? fs.readdirSync(currentStageDir).filter((entry) => !/^try-\d{3}$/.test(entry));
     if (entries.length === 0 && !pending) {
         return;
@@ -1613,10 +1656,9 @@ export function archiveExistingStageAttempt(context, projectId, runId, runRoot,
         attempt += 1;
     }
     const archiveDir = pending?.archiveDir ?? path.join(currentStageDir, `try-${String(attempt).padStart(3, "0")}`);
+    const intent = pending ?? { archiveDir, entries, stage_run: live ?? null, project_id: projectId, run_id: runId, prior_attempt: live?.attempt ?? null, next_attempt: nextAttempt(live), runtime_revision: prior?.runtime_revision ?? 0, generation };
     if (!pending) {
-        const stored = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
-        const prior = stored ? JSON.parse(stored.index_json) : null;
-        writeJsonFile(journal, { archiveDir, entries, stage_run: prior?.stage_runs.find((stage) => stage.dir === stageDir) ?? null });
+        writeJsonFile(journal, intent);
     }
     ensureDir(archiveDir);
     for (const entry of entries) {
@@ -1630,20 +1672,36 @@ export function archiveExistingStageAttempt(context, projectId, runId, runRoot,
         else if (!fs.existsSync(target))
             throw new AppError("archive_artifact_missing", "Artifact is absent from both archive locations", 2, { source, target });
     }
-    const oldPrefix = `${currentStageDir}${path.sep}`;
-    const newPrefix = `${archiveDir}${path.sep}`;
-    const rewrite = (table, column, where, values) => {
-        context.db.run(`UPDATE ${table} SET ${column} = ? || substr(${column}, ?) WHERE ${column} LIKE ? AND substr(${column}, ?, 4) != 'try-' AND ${where}`, [newPrefix, oldPrefix.length + 1, `${oldPrefix}%`, oldPrefix.length + 1, ...values]);
-    };
-    const workScope = "work_id IN (SELECT work_id FROM works WHERE project_id = ? AND run_id = ?)";
-    rewrite("work_sessions", "prompt_path", workScope, [projectId, runId]);
-    rewrite("work_sessions", "result_path", workScope, [projectId, runId]);
-    const receiptScope = "project_id = ? AND run_id = ?";
-    for (const column of ["stdout_path", "stderr_path", "receipt_path"])
-        rewrite("check_receipts", column, receiptScope, [projectId, runId]);
-    // Retain the original stage facts with its immutable artifacts; current
-    // stage_runs stays a projection of the current attempt, not a second ledger.
-    fs.renameSync(journal, path.join(archiveDir, "archive.json"));
+    context.db.writeTransaction(() => {
+        const current = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+        const currentIndex = current ? JSON.parse(current.index_json) : null;
+        const currentAttempt = currentIndex?.stage_runs.find((stage) => stage.dir === stageDir)?.attempt;
+        if (currentIndex && intent.runtime_revision !== undefined && (currentIndex.runtime_revision ?? 0) !== intent.runtime_revision && currentAttempt !== intent.next_attempt)
+            throw new AppError("archive_owner_changed", "RUN revision changed while an archive was pending", 1, { journal });
+        if (intent.prior_attempt && currentAttempt !== intent.prior_attempt && currentAttempt !== intent.next_attempt)
+            throw new AppError("archive_owner_changed", "Stage attempt changed while an archive was pending", 1, { journal });
+        if (row && generation !== assertRunMutationAllowed(context, projectId, runId))
+            throw new AppError("archive_owner_changed", "RUN generation changed while an archive was pending", 1, { journal });
+        if (intent.next_attempt === undefined || currentAttempt !== intent.next_attempt) {
+            const oldPrefix = `${currentStageDir}${path.sep}`;
+            const newPrefix = `${archiveDir}${path.sep}`;
+            const rewrite = (table, column, where, values) => {
+                context.db.run(`UPDATE ${table} SET ${column} = ? || substr(${column}, ?) WHERE ${column} LIKE ? AND substr(${column}, ?, 4) != 'try-' AND ${where}`, [newPrefix, oldPrefix.length + 1, `${oldPrefix}%`, oldPrefix.length + 1, ...values]);
+            };
+            const workScope = "work_id IN (SELECT work_id FROM works WHERE project_id = ? AND run_id = ?)";
+            rewrite("work_sessions", "prompt_path", workScope, [projectId, runId]);
+            rewrite("work_sessions", "result_path", workScope, [projectId, runId]);
+            const receiptScope = "project_id = ? AND run_id = ?";
+            for (const column of ["stdout_path", "stderr_path", "receipt_path"])
+                rewrite("check_receipts", column, receiptScope, [projectId, runId]);
+        }
+        context.db.afterCommit(() => {
+            if (!fs.existsSync(journal))
+                return;
+            // Retain original Stage facts with the immutable attempt after SQL paths commit.
+            fs.renameSync(journal, path.join(archiveDir, "archive.json"));
+        });
+    });
 }
 function writeJsonFile(file, value) {
     const tmpFile = `${file}.tmp-${process.pid}-${Date.now()}`;