@deksden-com/dd-flow-cli 0.9.0-beta.1 → 0.9.0-beta.11

package/dist/services/run-projection.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { reconcileSessionCoverageRows } from "../domain/session-coverage.js";
+import { publicSessionIdentity } from "./session-identity.js";
 export function refreshRunSessionProjection(context, projectId, runId) {
     const run = context.db.get("SELECT id, flow_kind, status, project_root, subject_type, subject_id, runtime_path, run_index_path, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     if (!run)
@@ -9,7 +10,8 @@ export function refreshRunSessionProjection(context, projectId, runId) {
     const sessionRows = context.db.all(`SELECT session_id, harness, provider_session_id, parent_session_id, role, session_kind, worker_id, current_stage, status,
             created_at, updated_at, stopped_at, coverage_units_json
        FROM sessions WHERE project_id = ? AND run_id = ? ORDER BY created_at, session_id`, [projectId, runId]);
-    const sessions = sessionRows.map(sessionProjection);
+    const sessionIdentities = new Map(sessionRows.map((row) => [row.session_id, publicSessionIdentity(row)]));
+    const sessions = sessionRows.map((row) => sessionProjection(row, sessionIdentities));
     const workRows = context.db.all("SELECT work_id, parent_work_id, status, depends_on_json, launch_policy, started_at, completed_at FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id", [projectId, runId]);
     const works = workRows.map((work) => ({ work_id: work.work_id, parent_work_id: work.parent_work_id, status: work.status, depends_on: parseStringArray(work.depends_on_json), launch_policy: work.launch_policy, started_at: work.started_at, completed_at: work.completed_at }));
     const rootWorkId = workRows.find((work) => work.parent_work_id === null)?.work_id ?? null;
@@ -123,10 +125,12 @@ function readPlanId(planPath) {
     return "unknown-plan";
 }
 function workerProjection(context, projectId, runId) {
-    return Object.fromEntries(context.db.all("SELECT job_id, plan_item_id, status, worker_session_id FROM flow_jobs WHERE project_id = ? AND run_id = ? ORDER BY job_id", [projectId, runId]).map((job) => [job.job_id, {
+    return Object.fromEntries(context.db.all(`SELECT j.job_id, j.plan_item_id, j.status, j.worker_session_id, s.harness, s.provider_session_id
+       FROM flow_jobs j LEFT JOIN sessions s ON s.project_id = j.project_id AND s.session_id = j.worker_session_id
+      WHERE j.project_id = ? AND j.run_id = ? ORDER BY j.job_id`, [projectId, runId]).map((job) => [job.job_id, {
             units: [job.plan_item_id],
             status: { pending: "registered", done: "completed" }[job.status] ?? job.status,
-            ...(job.worker_session_id ? { session_id: job.worker_session_id } : {})
+            ...(job.worker_session_id && job.harness ? { session: publicSessionIdentity({ harness: job.harness, provider_session_id: job.provider_session_id, session_id: job.worker_session_id }) } : {})
         }]));
 }
 function parseStringArray(value) {
@@ -138,12 +142,10 @@ function parseStringArray(value) {
         return [];
     }
 }
-function sessionProjection(row) {
+function sessionProjection(row, identities) {
     return {
-        session_id: row.session_id,
-        harness: row.harness,
-        provider_session_id: row.provider_session_id,
-        parent_session_id: row.parent_session_id,
+        session: publicSessionIdentity(row),
+        ...(row.parent_session_id ? { parent_session: identities.get(row.parent_session_id) ?? null } : {}),
         role: row.role,
         session_kind: row.session_kind,
         work_id: row.worker_id,

package/dist/services/runs.js

@@ -15,6 +15,8 @@ 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 { isLegalVnextTransition, vnextStages } from "../domain/stage-catalog.js";
+import { publicSessionIdentity } from "./session-identity.js";
 const runSchemaId = "dd-flow/flow-run@3";
 const runtimeSchemaId = "dd-flow/flow-run@3";
 const runIdType = "RUN";
@@ -124,7 +126,7 @@ export function startFlowRun(context, input) {
     };
     ensureDir(path.dirname(runtimePath));
     ensureDir(runHome);
-    bindCurrentEngineToRun(context, { projectRoot, runId, runHome });
+    bindCurrentEngineToRun(context, { projectRoot, runId, runRoot: runHome });
     const persistedIndex = persistedVnextIndex(index);
     writeJsonFile(runtimePath, runtimeSnapshotForIndex(persistedIndex, 1));
     context.db.run(`INSERT INTO runs
@@ -290,6 +292,22 @@ export function setFlowRunConfig(context, input) {
     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 };
 }
+/** Freeze an automatic review request once from already accepted policy or PLAN facts. */
+export function freezeFlowRunReviewMode(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = authoritativeIndex(run);
+    const settings = runSettings(index);
+    const key = input.review === "plan" ? "plan_review" : "code_review";
+    const current = settings[key];
+    if (current.mode !== "auto")
+        return;
+    const now = context.now();
+    index.settings = { ...settings, [key]: { mode: input.mode, source: input.source, reason: requiredPlain(input.reason, "reason"), updated_at: now } };
+    index.updated_at = now;
+    persistRunState(context, project, run, index);
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.review_mode_frozen", payload: { run_id: run.id, review: input.review, mode: input.mode, source: input.source, reason: input.reason } });
+}
 export function getFlowRunFlagsStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
@@ -450,6 +468,7 @@ export function attachFlowRunStage(context, input) {
     const dir = requiredStageDir(input.dir);
     const status = parseStageStatus(input.status);
     const existing = index.stage_runs.find((item) => item.stage === stage);
+    assertVnextStageStart(run, index, stage, status, existing);
     if (status === "running" && existing) {
         archiveExistingStageAttempt(runArtifactRoot(run), dir);
     }
@@ -674,8 +693,13 @@ export function completeFlowRun(context, input) {
     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 (!['done', 'cancelled', 'failed'].includes(status)) {
+        throw new AppError('validation', 'completeFlowRun accepts only done, cancelled, or failed; use stage block/unblock for a recoverable blocker', 2, { status });
+    }
+    if (!input.manualOverrideReason) {
+        const activeWork = context.db.get("SELECT work_id, status FROM works WHERE project_id = ? AND run_id = ? AND status IN ('created', 'running', 'paused') LIMIT 1", [project.id, run.id]);
+        if (activeWork)
+            throw new AppError("active_work", "RUN cannot complete while Work remains active", 2, { run_id: run.id, work_id: activeWork.work_id, status: activeWork.status });
     }
     if (input.manualOverrideReason && (status === "cancelled" || status === "failed")) {
         closeOpenStagesForOverride(index, status, now);
@@ -685,7 +709,7 @@ export function completeFlowRun(context, input) {
     index.verdict = input.verdict ?? (status === "done" ? "accepted" : status);
     index.next_action = input.nextAction ?? null;
     index.updated_at = now;
-    if (["done", "blocked", "cancelled", "failed"].includes(status)) {
+    if (["done", "cancelled", "failed"].includes(status)) {
         index.completed_at = now;
         index.finished_at = now;
         index.duration_ms = durationMs(index.started_at ?? run.created_at, now);
@@ -733,7 +757,7 @@ export function advanceFlowRun(context, input) {
 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")
+        if (stage.status !== "running" && stage.status !== "pending" && stage.status !== "paused" && stage.status !== "blocked")
             continue;
         stage.status = stageStatus;
         stage.updated_at = now;
@@ -755,7 +779,7 @@ function closeOpenWorksForOverride(context, projectId, runId, status, now) {
     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]);
+       AND status IN ('created', 'running', 'paused')`, [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 = ?)
@@ -881,7 +905,21 @@ export function getFlowRunSessions(context, input) {
                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 };
+    const identities = new Map(sessions.map((row) => [String(row.session_id), publicSessionIdentity({
+            harness: String(row.harness),
+            provider_session_id: typeof row.provider_session_id === "string" ? row.provider_session_id : null,
+            session_id: String(row.session_id)
+        })]));
+    return {
+        ok: true,
+        schema_id: "dd-flow/run-sessions@4",
+        run_id: run.id,
+        sessions: sessions.map(({ session_id, harness: _harness, provider_session_id: _providerSessionId, parent_session_id, ...row }) => ({
+            ...row,
+            session: identities.get(String(session_id)) ?? null,
+            ...(typeof parent_session_id === "string" ? { parent_session: identities.get(parent_session_id) ?? null } : {})
+        }))
+    };
 }
 export function appendFlowRunTimelineEvent(context, projectId, runId, event) {
     const run = requireRunById(context, projectId, runId);
@@ -1133,6 +1171,28 @@ function nextAttempt(existing) {
     const number = Number(existing.attempt.replace("try-", ""));
     return `try-${String(Number.isFinite(number) ? number + 1 : 1).padStart(3, "0")}`;
 }
+function assertVnextStageStart(run, index, stage, status, existing) {
+    if (status !== "running" || (run.flow_kind !== "vnext_specify" && run.flow_kind !== "vnext_protocolize"))
+        return;
+    if (!vnextStages.some((candidate) => candidate.id === stage))
+        return;
+    if (existing) {
+        if (existing.status === "running")
+            throw new AppError("stage_already_running", "The same stage attempt is already running; continue it instead of starting another attempt", 2, { run_id: run.id, stage, attempt: existing.attempt ?? null });
+        throw new AppError("illegal_stage_transition", "A completed or paused vNext stage cannot be started as a new implicit attempt", 2, { run_id: run.id, stage, status: existing.status });
+    }
+    const completed = index.stage_runs.filter((candidate) => candidate.status === "done" || candidate.status === "skipped").sort((left, right) => right.order - left.order)[0];
+    if (!completed) {
+        if (stage === "specify")
+            return;
+        throw new AppError("illegal_stage_transition", "The vNext flow must start with SPECIFY", 2, { run_id: run.id, stage });
+    }
+    if (!isLegalVnextTransition(completed.stage, stage))
+        throw new AppError("illegal_stage_transition", "The requested stage is not a legal successor of the last accepted stage", 2, { run_id: run.id, from: completed.stage, to: stage });
+    const unfinished = index.stage_runs.find((candidate) => !["done", "skipped"].includes(candidate.status));
+    if (unfinished)
+        throw new AppError("illegal_stage_transition", "Another stage is still active", 2, { run_id: run.id, active_stage: unfinished.stage, active_status: unfinished.status, to: stage });
+}
 function upsertStage(index, stageRun) {
     const position = index.stage_runs.findIndex((item) => item.stage === stageRun.stage);
     if (position === -1) {
@@ -1201,7 +1261,7 @@ function flowRunSummary(run) {
         runtime_path: run.runtime_path,
         run_dir: run.run_dir,
         run_index_path: run.run_index_path,
-        run_home_path: run.run_home_path ?? null,
+        run_root: run.run_root,
         layout_version: run.layout_version ?? null,
         artifact_root_kind: run.artifact_root_kind ?? null,
         created_at: run.created_at,
@@ -1296,7 +1356,9 @@ function writeJsonFile(file, value) {
     fs.renameSync(tmpFile, file);
 }
 function runArtifactRoot(run) {
-    return run.run_home_path ?? path.dirname(run.runtime_path);
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1, { run_id: run.id });
+    return run.run_root;
 }
 export function gitFacts(workspaceRoot) {
     const read = (args) => {

package/dist/services/schema-validation.js

@@ -6,7 +6,7 @@ import { Ajv } from "ajv/dist/ajv.js";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import { normalizeFlowContract } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
-import { findRunHome, readRunEngineBinding } from "./run-engine-bindings.js";
+import { readRunEngineBinding } from "./run-engine-bindings.js";
 export function captureMemoryBankBaseline(input) {
     const projectRoot = path.resolve(input.projectRoot);
     const paths = normalizeMemoryBankPaths(projectRoot, input.paths);
@@ -117,8 +117,8 @@ export function validateSchema(options) {
     }
     const valid = validate(data);
     const errors = valid ? [] : (validate.errors ?? []).map(formatAjvError);
-    const semanticErrors = valid ? validateSemanticSchema(options.schemaName, data) : [];
-    const allErrors = [...errors, ...semanticErrors];
+    const contractErrors = valid ? validateContractInvariants(options.schemaName, data) : [];
+    const allErrors = [...errors, ...contractErrors];
     if (allErrors.length > 0) {
         throw new AppError("schema_validation", `${path.basename(filePath)} does not match schema`, 2, {
             schema: schemaResolution,
@@ -181,7 +181,7 @@ const historicalSchemaRegistry = {
         }]
 };
 function resolveRunBoundSchema(options) {
-    if (!options.projectRoot || options.schemaDir)
+    if (!options.runRoot || options.schemaDir)
         return null;
     const data = readJson(path.resolve(options.file), "input file");
     const root = asRecord(data);
@@ -190,13 +190,13 @@ function resolveRunBoundSchema(options) {
     const runId = options.runId ?? inferredRunId;
     if (typeof runId !== "string")
         return null;
-    const projectRoot = path.resolve(options.projectRoot);
-    const located = findRunHome(options.ddFlowHome ?? process.env.DD_FLOW_HOME ?? path.join(path.dirname(projectRoot), ".dd-flow"), projectRoot, runId);
-    if (!located || !isInside(located.run_home, path.resolve(options.file)))
-        return null;
-    const binding = readRunEngineBinding(located.binding_path, { allowMissing: true });
+    const runRoot = path.resolve(options.runRoot);
+    const bindingPath = path.join(runRoot, "engine-binding.json");
+    const binding = readRunEngineBinding(bindingPath);
     if (!binding)
-        return null;
+        throw new AppError("run_engine_binding_missing", "RUN engine binding is missing", 1, { path: bindingPath });
+    if (binding.run_id !== runId)
+        throw new AppError("run_engine_binding_invalid", "RUN engine binding belongs to another RUN", 1, { expected_run_id: runId, actual_run_id: binding.run_id, path: bindingPath });
     const manifestPath = path.join(binding.engine.snapshot_root, "engine.json");
     const manifest = readJson(manifestPath, "bound engine manifest");
     const integrity = asRecord(objectValue(manifest, "integrity"));
@@ -284,7 +284,7 @@ function formatAjvError(error) {
         keyword: error.keyword
     };
 }
-function validateSemanticSchema(schemaName, data) {
+function validateContractInvariants(schemaName, data) {
     const root = asRecord(data);
     if (!root) {
         return [];

package/dist/services/session-identity.js

@@ -0,0 +1,19 @@
+import crypto from "node:crypto";
+import { AppError } from "../shared/errors.js";
+/** Internal SQLite key. Never expose this as a native harness Session ID. */
+export function storageSessionId(identity) {
+    const harness = requirePart(identity.harness_id, "harness_id");
+    const session = requirePart(identity.session_id, "session_id");
+    return `SES-${crypto.createHash("sha256").update(harness).update("\0").update(session).digest("hex").slice(0, 24)}`;
+}
+export function nativeSessionIdentity(harnessId, sessionId) {
+    return { harness_id: requirePart(harnessId, "harness_id"), session_id: requirePart(sessionId, "session_id") };
+}
+export function publicSessionIdentity(input) {
+    return nativeSessionIdentity(input.harness, input.provider_session_id ?? input.session_id);
+}
+function requirePart(value, field) {
+    if (!value || !value.trim())
+        throw new AppError("session_identity_invalid", `${field} must be a non-empty opaque value`, 1, { field });
+    return value;
+}

package/dist/services/sessions.js

@@ -11,6 +11,18 @@ import { checkpointSessionUsage } from "./usage.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
 import { reconcileSessionCoverageRows } from "../domain/session-coverage.js";
 import { appendFlowRunTimelineEvent } from "./runs.js";
+import { publicSessionIdentity, storageSessionId } from "./session-identity.js";
+export function publicFlowSession(context, session) {
+    const identity = publicSessionIdentity(session);
+    const parent = session.parent_session_id
+        ? context.db.get("SELECT harness, provider_session_id, session_id FROM sessions WHERE project_id = ? AND session_id = ?", [session.project_id, session.parent_session_id])
+        : null;
+    const publicFields = { ...session };
+    delete publicFields.session_id;
+    delete publicFields.provider_session_id;
+    delete publicFields.parent_session_id;
+    return { ...publicFields, harness_id: identity.harness_id, session_id: identity.session_id, parent_session: parent ? publicSessionIdentity(parent) : null };
+}
 export function recordFlowSessionObservation(context, input) {
     const duplicate = context.db.get("SELECT id FROM flow_session_segments WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
     if (duplicate)
@@ -86,7 +98,7 @@ export function registerFlowSession(context, input) {
         },
         ...(session.protocol_id ? { protocolId: session.protocol_id } : {})
     });
-    return { ok: true, session };
+    return { ok: true, session: publicFlowSession(context, session) };
 }
 export function getFlowSessionStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -96,7 +108,7 @@ export function getFlowSessionStatus(context, input) {
     });
     return {
         ok: true,
-        sessions,
+        sessions: sessions.map((session) => publicFlowSession(context, session)),
         coverage: reconcileSessionCoverage(sessions)
     };
 }
@@ -111,13 +123,14 @@ export function stopFlowSession(context, input) {
     markSessionStopped(context, project, session, input.reason);
     if (session.run_id)
         refreshRunSessionProjection(context, project.id, session.run_id);
-    return { ok: true, session: flowSessionById(context, project.id, input.sessionId) };
+    const updated = flowSessionById(context, project.id, input.sessionId);
+    return { ok: true, session: updated ? publicFlowSession(context, updated) : null };
 }
 export function syncFlowSessionUsage(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const session = requireFlowSession(context, project.id, input.sessionId);
     if (!session.run_id) {
-        return { ok: true, session_id: session.session_id, extraction_status: "not_observable", diagnostic: "session_not_bound_to_run" };
+        return { ok: true, session: publicSessionIdentity(session), extraction_status: "not_observable", diagnostic: "session_not_bound_to_run" };
     }
     return { ok: true, snapshot: checkpointSessionUsage(context, session, { checkpoint: "manual_sync", stage: session.current_stage }) };
 }
@@ -158,7 +171,7 @@ export function activeFlowSessionsForProject(context, projectId) {
 }
 export function flowSessionsForProject(context, projectId, filter = {}) {
     if (filter.sessionId) {
-        return context.db.all("SELECT * FROM sessions WHERE project_id = ? AND session_id = ? ORDER BY updated_at DESC", [projectId, filter.sessionId]);
+        return context.db.all("SELECT * FROM sessions WHERE project_id = ? AND (session_id = ? OR provider_session_id = ?) ORDER BY updated_at DESC", [projectId, filter.sessionId, filter.sessionId]);
     }
     if (filter.workerId) {
         return context.db.all("SELECT * FROM sessions WHERE project_id = ? AND worker_id = ? ORDER BY updated_at DESC", [projectId, filter.workerId]);
@@ -166,10 +179,7 @@ export function flowSessionsForProject(context, projectId, filter = {}) {
     return context.db.all("SELECT * FROM sessions WHERE project_id = ? ORDER BY updated_at DESC", [projectId]);
 }
 export function flowSessionById(context, projectId, sessionId) {
-    return context.db.get("SELECT * FROM sessions WHERE project_id = ? AND session_id = ?", [
-        projectId,
-        sessionId
-    ]);
+    return context.db.get("SELECT * FROM sessions WHERE project_id = ? AND (session_id = ? OR provider_session_id = ?)", [projectId, sessionId, sessionId]);
 }
 export function updateFlowSessionContinuation(context, projectId, sessionId, actionKey) {
     const session = flowSessionById(context, projectId, sessionId);
@@ -286,7 +296,12 @@ function normalizeFlowSessionPayload(payload) {
 }
 function upsertFlowSession(context, project, payload, forcedSessionId) {
     const now = context.now();
-    const sessionId = forcedSessionId ?? payload.session_id ?? payload.worker_id ?? payload.protocol_id ?? crypto.randomUUID();
+    // `sessions.session_id` is a private storage key.  The native ID is kept
+    // unchanged in provider_session_id and is always paired with its harness in
+    // public contracts.  A caller may pass a forced key only after a trusted
+    // hook has already derived it from that pair.
+    const nativeSessionId = payload.provider_session_id ?? payload.session_id ?? payload.worker_id ?? payload.protocol_id ?? crypto.randomUUID();
+    const sessionId = forcedSessionId ?? storageSessionId({ harness_id: payload.harness ?? "codex-desktop", session_id: nativeSessionId });
     const workspacePath = payload.workspace_path ?? payload.cwd ?? project.root;
     context.db.run(`INSERT INTO sessions
       (session_id, project_id, harness, provider_session_id, agent_id, provider, model, reasoning, mode, agent_type, project_root, flow_kind, status, run_id, parent_session_id, role, aspect_id, plan_item_id, session_kind, protocol_id, worker_id, workspace_path,
@@ -334,7 +349,7 @@ function upsertFlowSession(context, project, payload, forcedSessionId) {
         sessionId,
         project.id,
         payload.harness ?? "codex-desktop",
-        payload.provider_session_id ?? null,
+        nativeSessionId,
         payload.agent_id ?? null,
         payload.provider ?? null,
         payload.model ?? null,

package/dist/services/stage-lifecycle.js

@@ -53,7 +53,9 @@ function bootstrapStageRun(context, projectRoot, input) {
         if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
             throw new AppError("not_found", "--intake-file must point to an existing file", 1, { intake_file: intakeFile });
         }
-        const intakeDir = path.join(started.run.run_home_path ?? path.dirname(started.run.id), "intake");
+        if (!started.run.run_root)
+            throw new AppError("runtime_missing", "New RUN has no artifact root", 1, { run_id: started.run.id });
+        const intakeDir = path.join(started.run.run_root, "intake");
         fs.mkdirSync(intakeDir, { recursive: true });
         fs.copyFileSync(source, path.join(intakeDir, "user-request.md"));
     }
@@ -216,7 +218,7 @@ export function startStage(context, input) {
         })),
         worker_prompt_markdown: prompt
     });
-    validateSchema({ schemaName: "stage-prompt", file: promptDataPath, projectRoot, runId: attached.run.id, ddFlowHome: context.ddFlowHome });
+    validateSchema({ schemaName: "stage-prompt", file: promptDataPath, projectRoot, runId: attached.run.id, runRoot: runHome, ddFlowHome: context.ddFlowHome });
     atomicWrite(path.join(stageRoot, "stage-start.json"), {
         schema_id: "dd-flow/stage-start@2",
         run_id: attached.run.id,
@@ -273,7 +275,7 @@ export function finishStage(context, input) {
     const semanticFile = resolveStageFile(input.semanticFile ?? "@stage/stage-input.json", stageRoot, runHome);
     const receipt = beginFinishReceipt(context, stageRoot, semanticFile, view.run.id, input.stage);
     try {
-        validateSchema({ schemaName: "stage-finish-input", file: semanticFile, projectRoot, runId, ddFlowHome: context.ddFlowHome });
+        validateSchema({ schemaName: "stage-finish-input", file: semanticFile, projectRoot, runId, runRoot: runHome, ddFlowHome: context.ddFlowHome });
         const semantic = readSemanticFile(semanticFile, runHome);
         const status = stringValue(semantic.status) ?? "done";
         if (!["done", "waiting_for_user", "blocked", "failed"].includes(status)) {
@@ -293,7 +295,7 @@ export function finishStage(context, input) {
         const reportPath = path.join(stageRoot, "stage-report.md");
         const htmlPath = path.join(stageRoot, "stage-report.html");
         atomicWrite(dataPath, report);
-        validateSchema({ schemaName: stageReportSchemaName(input.stage, planFinish), file: dataPath, projectRoot, runId, ddFlowHome: context.ddFlowHome });
+        validateSchema({ schemaName: stageReportSchemaName(input.stage, planFinish), file: dataPath, projectRoot, runId, runRoot: runHome, ddFlowHome: context.ddFlowHome });
         atomicWrite(reportPath, renderMarkdown(report));
         atomicWrite(htmlPath, renderHtml(projectRoot, report));
         if (view.run.subject.type === "protocol") {
@@ -410,7 +412,12 @@ function nextActionForProtocolStage(stage) {
     return `continue_${stage}`;
 }
 function runHomePath(run) {
-    return run.run_home_path ?? path.dirname(run.run_index_path);
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN has no artifact root", 1, { run_id: run.id });
+    return run.run_root;
+}
+function runStatePath(run) {
+    return path.join(runHomePath(run), "run.json");
 }
 export function defaultStageDir(stage, flowKind) {
     const normalized = stage === "implementation" ? "code" : stage;
@@ -702,7 +709,7 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
     if (stage === "code" || stage === "implementation") {
         return {
             schema_id: "dd-flow/code-stage-report@2",
-            run: { run_id: view.run.id, run_state: view.run.run_index_path },
+            run: { run_id: view.run.id, run_state: runStatePath(view.run) },
             stage: { name: stage, dir: path.basename(stageRoot), status },
             project: { id: view.run.project_id, title: path.basename(view.run.project_root) },
             subject: { id: view.run.subject.id, title: view.run.subject.id },
@@ -712,7 +719,7 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
                 summary: result,
                 next_action: stringValue(semantic.next_action) ?? "Proceed to readiness."
             },
-            breadcrumbs: [{ label: "RUN", href: view.run.run_index_path, status: "available" }],
+            breadcrumbs: [{ label: "RUN", href: runStatePath(view.run), status: "available" }],
             implemented_goals: [{ title: `Stage ${stage}`, summary: result }],
             acceptance_scenarios: acceptance.map((summary, index) => ({
                 id: `SCN-${stage}-${index + 1}`,
@@ -763,7 +770,7 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
             memory_bank_scope: "changed_files_and_links_only",
             status: "passed"
         },
-        breadcrumbs: [{ label: "RUN", href: view.run.run_index_path, status: "available" }]
+        breadcrumbs: [{ label: "RUN", href: runStatePath(view.run), status: "available" }]
     };
 }
 function preparePlanFinish(context, projectRoot, view, stageRoot) {

package/dist/services/stage-pause.js

@@ -7,7 +7,7 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { findRecentMatchingHookEvent, claimStageResumeHookEvent, stageResumeMatchKey } from "./hooks.js";
 import { requireProjectByRoot } from "./projects.js";
 import { appendFlowRunTimelineEvent, pauseFlowRunStage, resumeFlowRunStage } from "./runs.js";
-import { refreshRunWorkProjection } from "./work-registry.js";
+import { bindSessionForResume, refreshRunWorkProjection } from "./work-registry.js";
 export function pauseStageForUser(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
@@ -25,8 +25,18 @@ export function pauseStageForUser(context, input) {
     fs.mkdirSync(pauseRoot, { recursive: true });
     fs.writeFileSync(questionPath, question);
     const now = context.now();
-    context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
-    pauseFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, pauseId, questionPath });
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        const paused = context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
+        if (paused.changes !== 1)
+            throw new AppError("invalid_work_state", "Work changed before pause could be accepted", 1, { work_id: work.work_id });
+        pauseFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, pauseId, questionPath });
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
     refreshRunWorkProjection(context, project.id, run.id);
     const resume = stageResumeCommand(context, { runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot });
     const resumeTemplate = `${resume} <<'USER_ANSWER'\n<paste the complete user answer exactly>\nUSER_ANSWER`;
@@ -61,26 +71,31 @@ export function resumeStageAfterUser(context, input) {
         errorCode: "trusted_stage_resume_required",
         operation: "stage resume"
     }).eventKey;
-    const identity = claimStageResumeHookEvent(context, {
-        projectId: project.id,
-        runId: run.id,
-        stage: stage.stage,
-        workId: work.work_id,
-        projectRoot,
-        eventKey: hookEventId
-    });
     const answerPath = path.join(path.dirname(stage.pause.question_path), "answer.md");
     fs.writeFileSync(answerPath, input.answer);
     const now = context.now();
     const workSession = context.db.get("SELECT id, session_id, prompt_path, result_path, status FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
     if (!workSession)
         throw new AppError("runtime_missing", "Paused Work has no open Session link", 1, { work_id: work.work_id });
-    if (workSession.session_id !== identity.sessionId) {
-        context.db.run("UPDATE work_sessions SET status = 'completed', updated_at = ?, completed_at = ? WHERE id = ?", [now, now, workSession.id]);
-        context.db.run("INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, NULL)", [`WSES-${crypto.randomUUID()}`, work.work_id, identity.sessionId, identity.hookEventId, workSession.prompt_path, workSession.result_path, now, now]);
+    context.db.exec("BEGIN IMMEDIATE");
+    let identity;
+    try {
+        identity = claimStageResumeHookEvent(context, { projectId: project.id, runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, eventKey: hookEventId });
+        if (workSession.session_id !== identity.sessionId) {
+            bindSessionForResume(context, work.work_id, identity, now);
+            context.db.run("UPDATE work_sessions SET status = 'completed', updated_at = ?, completed_at = ? WHERE id = ?", [now, now, workSession.id]);
+            context.db.run("INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, NULL)", [`WSES-${crypto.randomUUID()}`, work.work_id, identity.sessionId, identity.hookEventId, workSession.prompt_path, workSession.result_path, now, now]);
+        }
+        const resumed = context.db.run("UPDATE works SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'paused'", [now, work.work_id]);
+        if (resumed.changes !== 1)
+            throw new AppError("invalid_work_state", "Work changed before resume could be accepted", 1, { work_id: work.work_id });
+        resumeFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, answerPath });
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
     }
-    context.db.run("UPDATE works SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'paused'", [now, work.work_id]);
-    resumeFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, answerPath });
     refreshRunWorkProjection(context, project.id, run.id);
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_resume_session_bound", stage: stage.stage, work_id: work.work_id, session_id: identity.sessionId });
     const prompt = fs.readFileSync(workSession.prompt_path, "utf8");
@@ -152,7 +167,7 @@ export function flowCommand(context) {
     return context.ddFlowHome === defaultHome ? "dd-flow" : `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow`;
 }
 function requireRun(context, projectId, id) {
-    const rows = context.db.all("SELECT id, short_id, project_id, project_root, run_home_path, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, id, id]);
+    const rows = context.db.all("SELECT id, short_id, project_id, project_root, run_root, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, id, id]);
     if (rows.length !== 1)
         throw new AppError(rows.length ? "ambiguous_alias" : "not_found", rows.length ? "RUN alias is ambiguous" : "RUN is not registered", 1, { run_id: id });
     return rows[0];
@@ -171,9 +186,9 @@ function requireStage(run, stage, status) {
     return found;
 }
 function requireRunHome(run) {
-    if (!run.run_home_path)
-        throw new AppError("runtime_missing", "RUN has no artifact home", 1, { run_id: run.id });
-    return run.run_home_path;
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN has no artifact root", 1, { run_id: run.id });
+    return run.run_root;
 }
 function nextPauseId(runHome) {
     const root = path.join(runHome, "intake", "hitl");