@deksden-com/dd-flow-cli 0.9.0-beta.38 → 0.9.0-beta.40

package/dist/services/vnext-specify.js

@@ -9,6 +9,7 @@ import { resolveProjectRoot, writeJsonAtomic } from "../storage/paths.js";
 import { preflightMemoryPermissions } from "./memory-permissions.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunStatus, startFlowRun } from "./runs.js";
+import { resolveStageTransition } from "./execution-policy.js";
 import { validateSchema } from "./schema-validation.js";
 import { bindRunningWorkSession, refreshRunWorkProjection } from "./work-registry.js";
 import { nextWorkId } from "./ids.js";
@@ -65,7 +66,7 @@ export function launchVnextSpecify(context, input) {
     if (preflight.ok !== true)
         throw new AppError("permission_preflight_failed", "SPECIFY workspace is not writable", 1, { preflight });
     const grounding = projectGrounding(projectRoot);
-    const handoff = executionSnapshot(context, run.id);
+    const handoff = executionSnapshot(context, run.project_id, run.id);
     const workContext = {
         schema_id: "dd-flow/work-context@1",
         system: { run_id: run.id, work_id: workId, stage: stageId },
@@ -187,7 +188,7 @@ export function submitVnextSpecify(context, input) {
             appendFlowRunTimelineEvent(context, run.project_id, run.id, { type: "work_completed", work_id: work.work_id, outcome, stage: stageId });
         if (continuesToProtocolize) {
             const nextWork = requireWork(context, work.work_id);
-            advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "specified", nextAction: "start_protocolize" });
+            advanceFlowRun(context, { settlementStage: "specify", projectRoot, runId: run.id, status: "running", verdict: "specified", nextAction: "start_protocolize" });
             refreshRunWorkProjection(context, run.project_id, run.id);
             const nextCommand = `${flowCommand(context)} stage start ${run.id} --stage protocolize --project-root ${JSON.stringify(projectRoot)} --json`;
             return {
@@ -562,12 +563,18 @@ export function readVnextFlowDefinition(projectRoot) {
     }
     return null;
 }
-function executionSnapshot(context, runId) {
-    const row = context.db.get("SELECT index_json FROM runs WHERE id = ?", [runId]);
+function executionSnapshot(context, projectId, runId) {
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     const snapshot = row ? JSON.parse(row.index_json) : null;
-    const handoff = snapshot?.execution_profile?.settings?.stage_session_mode;
+    const profile = snapshot?.execution_profile;
+    let handoff = profile?.settings.stage_session_mode;
     if (handoff !== "same_session" && handoff !== "new_session")
         throw new AppError("execution_profile_invalid", "RUN has no frozen stage session mode", 1, { run_id: runId });
+    if (profile?.settings.execution) {
+        if (!profile.agent_profiles)
+            throw new AppError("execution_profile_not_frozen", "Stage handoff requires frozen RUN profiles", 1);
+        handoff = resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy: profile.settings.execution, profiles: profile.agent_profiles, fromStage: "specify", stage: "protocolize", stageSessionMode: handoff, mergeMode: profile.settings.merge_mode }).session_mode;
+    }
     return { stage_handoff: { effective: handoff, source: "run_override" } };
 }
 function executionSnapshotFromPath(contextPath, workId) {

package/dist/services/work-registry.js

@@ -9,11 +9,13 @@ import { refreshRunSessionProjection } from "./run-projection.js";
 import { readCodeCheckProfile, runCodeChecks, workspaceFingerprint } from "./code-checks.js";
 import { nextWorkId, nextWorkIds } from "./ids.js";
 import { appendFlowRunTimelineEvent } from "./runs.js";
+import { resolveStageTransition } from "./execution-policy.js";
 import { appendAudit } from "./audit.js";
 import { flowCommand } from "./stage-pause.js";
 import { assertPortableArtifactRef } from "./portable-refs.js";
 import { publicSessionIdentity } from "./session-identity.js";
-import { activateRecoveryWork, assertRecoveryHookCurrent, assertRunMutationAllowed, recoveryGuard, recoveryPromptForWork, settleRecoveryWork } from "./run-recovery.js";
+import { activateRecoveryWork, assertRecoveryHookCurrent, assertRunMutationAllowed, assertWorkSettlementAllowed, recoveryGuard, recoveryPromptForWork, settleRecoveryWork } from "./run-recovery.js";
+import { runControlDirective } from "./run-control.js";
 const workColumns = "work_id, project_id, run_id, parent_work_id, task, launch_policy, result_schema, payload_json, depends_on_json, status, result, created_at, started_at, updated_at, completed_at";
 export function ensureWorkRegistry(context) { context.db.exec("SELECT 1 FROM works LIMIT 1"); context.db.exec("SELECT 1 FROM work_sessions LIMIT 1"); }
 function ownsPhysicalWorkSession(context, projectId, owner, identity) {
@@ -304,7 +306,7 @@ export function shortWorkId(id) { return /^WRK-\d{3,}(?:-|$)/.exec(id)?.[0]?.rep
  * same captured runtime as their parent stage.
  */
 export function workStartCommand(context, work) { const run = requireRun(context, work.project_id, work.run_id); const recovery = recoveryGuard(context, work.project_id, work.run_id); return `${flowCommand(context)} work start ${work.work_id} --project-root ${JSON.stringify(run.project_root)}${recovery ? ` --recovery-id ${JSON.stringify(recovery.recovery_id)}` : ""} --json`; }
-export function startWork(context, id, input) {
+export function assertWorkLaunchReady(context, id) {
     ensureWorkRegistry(context);
     const work = requireWork(context, id);
     assertRunMutationAllowed(context, work.project_id, work.run_id);
@@ -315,6 +317,10 @@ export function startWork(context, id, input) {
         const ready = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? AND status = 'created' ORDER BY created_at, work_id`, [work.project_id, work.run_id]).filter((candidate) => isReady(context, candidate)).map((candidate) => ({ work_id: candidate.work_id, start_command: workStartCommand(context, candidate) }));
         throw new AppError("work_not_ready", "Work cannot start until dependencies complete and overlapping planned coordination areas are free", 2, { work_id: id, blockers, ready });
     }
+    return work;
+}
+export function startWork(context, id, input) {
+    const work = assertWorkLaunchReady(context, id);
     const run = requireRun(context, work.project_id, work.run_id);
     if (input.projectRoot && resolveProjectRoot(input.projectRoot) !== resolveProjectRoot(run.project_root))
         throw new AppError("project_mismatch", "work start project root does not match its RUN", 1, { work_id: id });
@@ -403,9 +409,20 @@ export function bindStageCoordinatorWork(context, input) {
     const work = requireWork(context, input.workId);
     assertRunMutationAllowed(context, work.project_id, work.run_id);
     const run = requireRun(context, work.project_id, work.run_id);
-    claimStageStartHookEvent(context, { projectId: work.project_id, eventKey: input.hookEventId, runId: work.run_id, stage: input.stage, projectRoot: run.project_root, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     const snapshot = JSON.parse((context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [work.project_id, work.run_id])?.index_json) ?? "{}");
-    const binding = bindRunningWorkSession(context, { ...input, allowStageHandoff: snapshot.execution_profile?.settings?.stage_session_mode === "new_session" });
+    const profile = snapshot.execution_profile;
+    const previous = context.db.get("SELECT ws.session_id, s.current_stage FROM work_sessions ws JOIN sessions s ON s.project_id = ? AND s.session_id = ws.session_id WHERE ws.work_id = ? AND ws.status = 'running' ORDER BY ws.created_at DESC LIMIT 1", [work.project_id, work.work_id]);
+    let sessionMode = profile?.settings.stage_session_mode ?? "same_session";
+    if (profile?.settings.execution) {
+        if (!profile.agent_profiles)
+            throw new AppError("execution_profile_not_frozen", "Stage handoff requires frozen RUN profiles", 1);
+        sessionMode = resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy: profile.settings.execution, profiles: profile.agent_profiles, ...(previous?.current_stage ? { fromStage: previous.current_stage } : {}), stage: input.stage, stageSessionMode: sessionMode, mergeMode: profile.settings.merge_mode }).session_mode;
+    }
+    const identity = hookSessionIdentity(context, work.project_id, input.hookEventId);
+    if (previous?.current_stage && previous.current_stage !== input.stage && sessionMode === "new_session" && previous.session_id === identity.sessionId)
+        throw new AppError("stage_handoff_required", "This stage requires a fresh coordinator Session under its frozen execution policy", 1, { from_stage: previous.current_stage, stage: input.stage });
+    claimStageStartHookEvent(context, { projectId: work.project_id, eventKey: input.hookEventId, runId: work.run_id, stage: input.stage, projectRoot: run.project_root, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    const binding = bindRunningWorkSession(context, { ...input, allowStageHandoff: sessionMode === "new_session" });
     context.db.run("UPDATE sessions SET current_stage = ?, updated_at = ? WHERE project_id = ? AND session_id = ?", [input.stage, context.now(), work.project_id, binding.session_id]);
     refreshRunSessionProjection(context, work.project_id, work.run_id);
     return binding;
@@ -556,7 +573,7 @@ export function retryWork(context, id, reason) {
 }
 async function settle(context, id, status, result, progress) {
     const work = requireWork(context, id);
-    assertRunMutationAllowed(context, work.project_id, work.run_id);
+    assertWorkSettlementAllowed(context, work.project_id, work.run_id, work.work_id);
     id = work.work_id;
     if (work.status !== "running" && !(status === "cancelled" && work.status === "created"))
         throw new AppError("invalid_work_state", "Work is not running", 2, { status: work.status });
@@ -597,7 +614,7 @@ async function settle(context, id, status, result, progress) {
     const now = context.now();
     context.db.exec("BEGIN IMMEDIATE");
     try {
-        assertRunMutationAllowed(context, work.project_id, work.run_id);
+        assertWorkSettlementAllowed(context, work.project_id, work.run_id, work.work_id);
         if (link && !context.db.get("SELECT 1 FROM work_sessions WHERE id = ? AND status = 'running'", [link.id]))
             throw new AppError("work_generation_stale", "Work Session was interrupted or superseded while checks ran", 1, { work_id: id });
         if (link?.result_path && work.parent_work_id !== null)
@@ -618,11 +635,12 @@ async function settle(context, id, status, result, progress) {
     materializePendingWorkResults(context, work.project_id, work.run_id);
     settleRecoveryWork(context, work.work_id, status);
     refreshRunWorkProjection(context, work.project_id, work.run_id);
-    const newlyReady = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? AND status = 'created' ORDER BY created_at, work_id`, [work.project_id, work.run_id]).filter((candidate) => isReady(context, candidate)).map((candidate) => ({ work_id: candidate.work_id, launch_policy: candidate.launch_policy, start_command: workStartCommand(context, candidate) }));
+    const control = runControlDirective(context, work.project_id, work.run_id);
+    const newlyReady = control ? [] : context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? AND status = 'created' ORDER BY created_at, work_id`, [work.project_id, work.run_id]).filter((candidate) => isReady(context, candidate)).map((candidate) => ({ work_id: candidate.work_id, launch_policy: candidate.launch_policy, start_command: workStartCommand(context, candidate) }));
     appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: `work_${status}`, work_id: work.work_id, session_id: link?.session_id ?? null, ...(coordinationDrift.length ? { coordination_drift: coordinationDrift } : {}) });
     for (const ready of newlyReady)
         appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: "work_dependency_unblocked", work_id: ready.work_id, completed_dependency: work.work_id });
-    return { ok: true, work_id: id, status, checks: receipts, coordination: { planned_write_areas: codePacket(work)?.planned_write_areas ?? [], drift: coordinationDrift }, newly_ready: newlyReady, graph: codeWorkGraph(context, work.project_id, work.run_id), usage: { status: "provisional", reason: "final usage is controller-owned" } };
+    return { ok: true, ...(control ? { control } : {}), work_id: id, status, checks: receipts, coordination: { planned_write_areas: codePacket(work)?.planned_write_areas ?? [], drift: coordinationDrift }, newly_ready: newlyReady, graph: codeWorkGraph(context, work.project_id, work.run_id), usage: { status: "provisional", reason: "final usage is controller-owned" } };
 }
 function recoveryPrompt(recovery) { return ["<recovery_identity>", `- recovery_id: ${recovery.recoveryId}`, `- execution_generation: ${recovery.generation}`, "This Work was interrupted and is now an authorized recovery segment of the same assignment.", "</recovery_identity>", "", "<recovery_instructions>", `Read the retained pre-interruption evidence at ${recovery.evidencePath}.`, "Before changing files or rerunning a command, inspect the workspace, receipts, logs, and partial artifacts. Do not assume the last command succeeded or failed merely because its reply was lost.", "Preserve accepted work. Do not repeat completed Work, create undeclared Work, alter the original requirements, or edit dd-flow runtime state/evidence.", "Observe an existing check or finish instead of duplicating it. Retry only through an exact runtime retry command after establishing that its prior outcome permits it.", "Record the concrete unresolved operation rather than guessing if an external effect cannot be reconciled.", "</recovery_instructions>"].join("\n"); }
 function plannedAreaDrift(packet, result) {

package/dist/services/workspace-bootstrap.js

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
 import { codeExecutionEnvironment, runCheck } from "./code-checks.js";
 import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedOwnerIsAlive, managedProcessStatus, processTreeIsAlive, registerManagedProcess } from "./managed-processes.js";
 /** CODE and MERGE prepare their own checkout through the same managed executor.
@@ -24,13 +25,21 @@ export async function runWorkspaceBootstrap(context, input) {
         finishManagedProcess(context, { id: pending.id, leaseToken: pending.lease_token, state: exitCode === 0 ? "stopped" : "failed", reason: error ?? "bootstrap_completion_reconciled" });
         return result(pending.id, pending.stdout_path, pending.stderr_path, completionPath, exitCode, error);
     }
+    const generation = assertRunMutationAllowed(context, input.projectId, input.runId);
     const directory = path.join(input.runHome, input.artifactDir, `bootstrap-${crypto.randomUUID()}`);
     fs.mkdirSync(directory, { recursive: true });
     const stdoutPath = path.join(directory, "stdout.log"), stderrPath = path.join(directory, "stderr.log"), completionPath = path.join(directory, "completion.json");
     const managed = registerManagedProcess(context, { kind: "workspace-bootstrap", ownerId: operationId, ownerPid: process.pid, operationId, uniqueActiveOperation: true, projectId: input.projectId, runId: input.runId, stdoutPath, stderrPath, metadata: { command: input.command, workspace_root: input.workspaceRoot } });
     const stdout = fs.openSync(stdoutPath, "a"), stderr = fs.openSync(stderrPath, "a");
     try {
-        input.progress?.(`workspace bootstrap started: ${input.command}; logs: ${directory}`);
+        try {
+            input.progress?.(`workspace bootstrap preparing: ${input.command}; logs: ${directory}`);
+            assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+        }
+        catch (error) {
+            finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: "failed", reason: "dispatch_fenced_before_spawn" });
+            throw error;
+        }
         const completed = await runCheck(input.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_CHECK_COMPLETION_FILE: completionPath }, stdout, stderr, elapsed => input.progress?.(`workspace bootstrap still running (${elapsed}s); logs: ${directory}; next report in 15s`), pid => confirmManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid }), () => heartbeatManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token }));
         const current = managedProcessStatus(context).find(item => item.id === managed.id);
         if (processTreeIsAlive(current))

package/dist/storage/database.js

@@ -4,9 +4,86 @@ import crypto from "node:crypto";
 import { createRequire } from "node:module";
 import { ensureDir } from "./paths.js";
 import { AppError } from "../shared/errors.js";
+import { executeStoreSchema, readStoreWriterContract, registerStoreWriter } from "./writer-contract.js";
 const require = createRequire(import.meta.url);
 const { DatabaseSync } = require("node:sqlite");
 const resourceDatabases = new Map();
+/** RUN authority stays in its existing store; process leases stay in runtime.sqlite. */
+export function ensureRunControlStorage(db) {
+    db.execSchema(`
+    CREATE TABLE IF NOT EXISTS run_controls (
+      control_id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL, run_id TEXT NOT NULL,
+      request_id TEXT NOT NULL, request_hash TEXT NOT NULL, request_json TEXT NOT NULL,
+      recovery_id TEXT NOT NULL REFERENCES run_recovery_guards(recovery_id),
+      action TEXT NOT NULL, status TEXT NOT NULL,
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+      UNIQUE(project_id, run_id, request_id),
+      FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id)
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_run_control_active
+      ON run_controls(project_id, run_id) WHERE status IN ('requested','settled','resuming');
+    CREATE TABLE IF NOT EXISTS run_control_admissions (
+      control_id TEXT NOT NULL REFERENCES run_controls(control_id),
+      work_session_id TEXT NOT NULL REFERENCES work_sessions(id),
+      work_id TEXT NOT NULL REFERENCES works(work_id),
+      session_id TEXT NOT NULL, admitted_at TEXT NOT NULL,
+      PRIMARY KEY(control_id, work_session_id)
+    );
+    CREATE TABLE IF NOT EXISTS run_control_stage_admissions (
+      control_id TEXT NOT NULL REFERENCES run_controls(control_id),
+      stage TEXT NOT NULL, attempt TEXT NOT NULL,
+      work_session_id TEXT NOT NULL REFERENCES work_sessions(id),
+      PRIMARY KEY(control_id, stage)
+    );
+    CREATE TABLE IF NOT EXISTS run_control_operations (
+      operation_id TEXT PRIMARY KEY, control_id TEXT NOT NULL REFERENCES run_controls(control_id),
+      target_json TEXT NOT NULL, status TEXT NOT NULL, receipt_json TEXT, error_json TEXT,
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS run_control_workers (
+      control_id TEXT PRIMARY KEY REFERENCES run_controls(control_id),
+      owner_token TEXT NOT NULL, owner_pid INTEGER,
+      status TEXT NOT NULL, process_id TEXT, process_lease_token TEXT,
+      resource_home TEXT NOT NULL, state_dir TEXT NOT NULL,
+      snapshot_json TEXT, error_json TEXT,
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+    );
+  `);
+}
+export function ensureRunControllerStorage(db) {
+    db.execSchema(`
+    CREATE TABLE IF NOT EXISTS run_controllers (
+      controller_id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL, run_id TEXT NOT NULL,
+      request_id TEXT NOT NULL, request_hash TEXT NOT NULL,
+      generation INTEGER NOT NULL, status TEXT NOT NULL,
+      owner_token TEXT NOT NULL, process_id TEXT, process_lease_token TEXT,
+      owner_pid INTEGER, manifest_json TEXT NOT NULL, state_json TEXT NOT NULL,
+      state_dir TEXT NOT NULL, last_error_json TEXT,
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+      FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id),
+      UNIQUE(project_id, run_id, request_id)
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_run_controller_owner
+      ON run_controllers(project_id, run_id)
+      WHERE status NOT IN ('completed', 'cancelled', 'superseded');
+    CREATE TABLE IF NOT EXISTS run_controller_events (
+      sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+      controller_id TEXT NOT NULL REFERENCES run_controllers(controller_id),
+      event_type TEXT NOT NULL, data_json TEXT NOT NULL, created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_run_controller_events
+      ON run_controller_events(controller_id, sequence);
+    CREATE TABLE IF NOT EXISTS run_controller_operations (
+      operation_id TEXT PRIMARY KEY,
+      controller_id TEXT NOT NULL REFERENCES run_controllers(controller_id),
+      generation INTEGER NOT NULL, input_hash TEXT NOT NULL,
+      input_json TEXT NOT NULL, status TEXT NOT NULL,
+      receipt_json TEXT, error_json TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+    );
+  `);
+}
 /** Recovery guards apply to every RUN kind, including custom eval fixtures. */
 export function ensureRecoveryStorage(db) {
     db.exec(`
@@ -29,6 +106,7 @@ export function ensureRecoveryStorage(db) {
   `);
     ensureColumn(db, "run_recovery_bindings", "packet_json", "ALTER TABLE run_recovery_bindings ADD COLUMN packet_json TEXT");
     ensureColumn(db, "run_recovery_bindings", "packet_sha256", "ALTER TABLE run_recovery_bindings ADD COLUMN packet_sha256 TEXT");
+    ensureColumn(db, "run_recovery_bindings", "runtime_dispatch_json", "ALTER TABLE run_recovery_bindings ADD COLUMN runtime_dispatch_json TEXT");
 }
 /** Creates the single Work/Session authority used by a fresh vNext beta runtime. */
 export function ensureVnextWorkStorage(db) {
@@ -39,7 +117,7 @@ export function ensureVnextWorkStorage(db) {
     if (existing && (!/task TEXT NOT NULL/.test(existing.sql) || /launch_token|adapter_session_id/.test(existing.sql))) {
         throw new AppError("beta_storage_recreate_required", "This beta requires a fresh DD_FLOW_HOME; the existing works schema is not compatible", 1);
     }
-    db.exec(`
+    db.execSchema(`
     CREATE TABLE IF NOT EXISTS works (
       work_id TEXT PRIMARY KEY,
       project_id TEXT NOT NULL,
@@ -119,7 +197,7 @@ export function ensureVnextWorkStorage(db) {
 /** Durable intent for a provider-root external Work.  It is deliberately
  * separate from `work_sessions`: only a trusted hook may bind that Session. */
 export function ensureWorkLaunchStorage(db) {
-    db.exec(`
+    db.execSchema(`
     CREATE TABLE IF NOT EXISTS work_launches (
       operation_id TEXT PRIMARY KEY,
       work_id TEXT NOT NULL UNIQUE,
@@ -146,12 +224,40 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
     if (!exists || mode === "migrate")
         ensureDir(ddFlowHome);
     const db = mode === "read_existing" ? new DatabaseSync(dbPath, { readOnly: true }) : new DatabaseSync(dbPath);
-    configureDatabase(db, mode);
+    db.exec("PRAGMA busy_timeout = 4000");
+    if (mode !== "read_existing") {
+        try {
+            registerStoreWriter(db);
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+    try {
+        configureDatabase(db, mode);
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
     // Internal additive schema changes must be available to every write command.
     // Higher-level Memory Bank migrations remain explicit in services/migrations.
     if (mode !== "read_existing") {
-        migrate(db, dbPath);
-        ensureRecoveryStorage(db);
+        try {
+            const initialize = () => { migrate(db); ensureRecoveryStorage(db); };
+            const fresh = !db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get();
+            if (fresh || readStoreWriterContract(db) !== null)
+                executeStoreSchema(db, initialize, fresh);
+            else
+                initialize();
+            // This migration owns a VACUUM backup and a separate data transaction.
+            migrateSessionStorageKeys(db, dbPath);
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
     }
     if (mode === "read_existing")
         db.exec("PRAGMA query_only = ON");
@@ -161,6 +267,7 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
         writable: mode !== "read_existing",
         close: () => db.close?.(),
         exec: (sql) => db.exec(sql),
+        execSchema: (sql) => executeStoreSchema(db, sql),
         run: (sql, params = []) => db.prepare(sql).run(...params),
         get: (sql, params = []) => db.prepare(sql).get(...params),
         all: (sql, params = []) => db.prepare(sql).all(...params)
@@ -178,9 +285,25 @@ export function getResourceDatabase(resourceHome) {
     if (cached)
         return cached;
     const db = new DatabaseSync(dbPath);
-    configureDatabase(db, "initialize");
+    db.exec("PRAGMA busy_timeout = 4000");
+    try {
+        registerStoreWriter(db);
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+    try {
+        configureDatabase(db, "initialize");
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
     db.exec("PRAGMA foreign_keys = ON");
-    db.exec(`
+    const fresh = !db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get();
+    try {
+        executeStoreSchema(db, `
     CREATE TABLE IF NOT EXISTS managed_processes (
       id TEXT PRIMARY KEY,
       kind TEXT NOT NULL,
@@ -219,12 +342,18 @@ export function getResourceDatabase(resourceHome) {
     );
     CREATE INDEX IF NOT EXISTS idx_managed_resources_lease
       ON managed_resources(lease_expires_at, updated_at);
-  `);
+  `, fresh);
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
     const database = {
         path: dbPath,
         writable: true,
         close: () => { resourceDatabases.delete(dbPath); db.close?.(); },
         exec: (sql) => db.exec(sql),
+        execSchema: (sql) => executeStoreSchema(db, sql),
         run: (sql, params = []) => db.prepare(sql).run(...params),
         get: (sql, params = []) => db.prepare(sql).get(...params),
         all: (sql, params = []) => db.prepare(sql).all(...params)
@@ -237,19 +366,34 @@ function emptyReadOnlyDatabase(dbPath) {
         path: dbPath,
         writable: false,
         exec: () => { throw new AppError("read_only_storage", "Read-only access cannot write absent dd-flow storage", 1, { path: dbPath }); },
+        execSchema: () => { throw new AppError("read_only_storage", "Read-only access cannot write absent dd-flow storage", 1, { path: dbPath }); },
         run: () => { throw new AppError("read_only_storage", "Read-only access cannot write absent dd-flow storage", 1, { path: dbPath }); },
         get: () => undefined,
         all: () => []
     };
 }
 function configureDatabase(db, mode) {
-    db.exec("PRAGMA busy_timeout = 4000");
     if (mode !== "read_existing") {
-        db.exec("PRAGMA journal_mode = WAL");
+        // Concurrent first openers can collide while changing journal mode, even
+        // with busy_timeout set. Retrying this configuration does not replay writes.
+        const deadline = performance.now() + 4000, pause = new Int32Array(new SharedArrayBuffer(4));
+        for (;;) {
+            try {
+                const current = db.prepare("PRAGMA journal_mode").get();
+                if (current.journal_mode !== "wal")
+                    db.exec("PRAGMA journal_mode = WAL");
+                break;
+            }
+            catch (error) {
+                if ((error.errcode ?? 0) % 256 !== 5 || performance.now() >= deadline)
+                    throw error;
+                Atomics.wait(pause, 0, 0, Math.min(25, Math.max(1, deadline - performance.now())));
+            }
+        }
         db.exec("PRAGMA synchronous = NORMAL");
     }
 }
-function migrate(db, dbPath) {
+function migrate(db) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS projects (
       id TEXT PRIMARY KEY,
@@ -855,7 +999,6 @@ function migrate(db, dbPath) {
     ensureColumn(db, "sessions", "plan_item_id", "ALTER TABLE sessions ADD COLUMN plan_item_id TEXT");
     ensureColumn(db, "sessions", "session_kind", "ALTER TABLE sessions ADD COLUMN session_kind TEXT");
     ensureColumn(db, "sessions", "coverage_units_json", "ALTER TABLE sessions ADD COLUMN coverage_units_json TEXT NOT NULL DEFAULT '[]'");
-    migrateSessionStorageKeys(db, dbPath);
     ensureColumn(db, "usage", "cache_read_input_tokens", "ALTER TABLE usage ADD COLUMN cache_read_input_tokens INTEGER");
     ensureColumn(db, "usage", "cache_write_input_tokens", "ALTER TABLE usage ADD COLUMN cache_write_input_tokens INTEGER");
     ensureColumn(db, "usage", "uncached_input_tokens", "ALTER TABLE usage ADD COLUMN uncached_input_tokens INTEGER");
@@ -871,7 +1014,11 @@ function migrate(db, dbPath) {
     ensureColumn(db, "merge_requests", "replacement_of_merge_request_id", "ALTER TABLE merge_requests ADD COLUMN replacement_of_merge_request_id TEXT");
     // A failed integration gate may create a new immutable source candidate in
     // the same RUN. The historical unique index made that repair path impossible.
-    db.exec("DROP INDEX IF EXISTS idx_merge_requests_run");
+    // Rebuilding an already-current index changes schema/data_version on every
+    // CLI observation and prevents a controller's writer barrier from settling.
+    const mergeRunIndex = db.prepare("PRAGMA index_list(merge_requests)").all().find(index => index.name === "idx_merge_requests_run");
+    if (mergeRunIndex?.unique)
+        db.exec("DROP INDEX idx_merge_requests_run");
     db.exec("CREATE INDEX IF NOT EXISTS idx_merge_requests_run ON merge_requests(project_id, run_id, created_at)");
     ensureColumn(db, "runs", "layout_version", "ALTER TABLE runs ADD COLUMN layout_version TEXT");
     ensureColumn(db, "runs", "artifact_root_kind", "ALTER TABLE runs ADD COLUMN artifact_root_kind TEXT");

package/dist/storage/writer-contract.js

@@ -0,0 +1,76 @@
+import crypto from "node:crypto";
+import { AppError } from "../shared/errors.js";
+const version = 1;
+const table = "dd_flow_writer_contract";
+const quote = (name) => `"${name.replaceAll('"', '""')}"`;
+/** Publish additive schema and its writer fences in the same transaction. */
+export function executeStoreSchema(db, sql, initialize = false) {
+    const ownsTransaction = !db.isTransaction;
+    db.exec(ownsTransaction ? "BEGIN IMMEDIATE" : "SAVEPOINT dd_flow_schema_change");
+    try {
+        const protectedStore = readStoreWriterContract(db) !== null;
+        if (initialize && !protectedStore && db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get()) {
+            throw new AppError("store_initialization_conflict", "Another writer initialized this store; explicit migration is required", 1);
+        }
+        const before = db.prepare("PRAGMA schema_version").get();
+        if (typeof sql === "string")
+            db.exec(sql);
+        else
+            sql();
+        const after = db.prepare("PRAGMA schema_version").get();
+        if (initialize || (protectedStore && before.schema_version !== after.schema_version))
+            installStoreWriterContract(db);
+        db.exec(ownsTransaction ? "COMMIT" : "RELEASE dd_flow_schema_change");
+    }
+    catch (error) {
+        db.exec(ownsTransaction ? "ROLLBACK" : "ROLLBACK TO dd_flow_schema_change; RELEASE dd_flow_schema_change");
+        throw error;
+    }
+}
+/** Registration is connection-local and never changes historical input bytes. */
+export function registerStoreWriter(db) {
+    const current = readStoreWriterContract(db);
+    if (current !== null && current !== version)
+        throw new AppError("store_writer_incompatible", "This CLI cannot write the store's required contract", 1, { required: current, supported: version });
+    db.function("dd_flow_writer_version", () => version);
+}
+export function readStoreWriterContract(db) {
+    if (!db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table))
+        return null;
+    const rows = db.prepare(`SELECT id, version FROM ${table}`).all();
+    if (rows.length !== 1 || rows[0]?.id !== 1 || !Number.isSafeInteger(rows[0].version) || rows[0].version < 1)
+        throw new AppError("store_writer_contract_invalid", "Store writer contract is malformed", 1);
+    return rows[0].version;
+}
+/** Install only at an explicit migration boundary; ordinary reads never call it. */
+export function installStoreWriterContract(db) {
+    registerStoreWriter(db);
+    const ownsTransaction = !db.isTransaction;
+    if (ownsTransaction)
+        db.exec("BEGIN IMMEDIATE");
+    try {
+        db.exec(`CREATE TABLE IF NOT EXISTS ${table} (id INTEGER PRIMARY KEY CHECK (id = 1), version INTEGER NOT NULL);
+      INSERT OR IGNORE INTO ${table} (id, version) VALUES (1, ${version});`);
+        if (readStoreWriterContract(db) !== version)
+            throw new AppError("store_writer_incompatible", "Store writer contract changed before migration", 1);
+        const tables = db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all();
+        for (const target of tables) {
+            const key = crypto.createHash("sha256").update(target.name).digest("hex").slice(0, 24);
+            for (const action of ["INSERT", "UPDATE", "DELETE"]) {
+                const trigger = quote(`dd_flow_writer_${key}_${action.toLowerCase()}`);
+                db.exec(`DROP TRIGGER IF EXISTS ${trigger};
+          CREATE TRIGGER ${trigger} BEFORE ${action} ON ${quote(target.name)} BEGIN
+          SELECT CASE WHEN dd_flow_writer_version() <> (SELECT version FROM ${table} WHERE id = 1)
+            OR (SELECT COUNT(*) FROM ${table}) <> 1 THEN RAISE(ABORT, 'store_writer_incompatible') END;
+        END;`);
+            }
+        }
+        if (ownsTransaction)
+            db.exec("COMMIT");
+    }
+    catch (error) {
+        if (ownsTransaction)
+            db.exec("ROLLBACK");
+        throw error;
+    }
+}

package/dist/storage/writer-migration.js

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { AppError } from "../shared/errors.js";
+import { installStoreWriterContract, readStoreWriterContract, registerStoreWriter } from "./writer-contract.js";
+/** Explicit one-store cutover. The caller must separately drain external owners. */
+export function migrateStoreWriter(file, backup) {
+    if (!path.isAbsolute(file) || !path.isAbsolute(backup) || file === backup || !fs.existsSync(file) || !fs.statSync(file).isFile())
+        throw new AppError("store_migration_path_invalid", "Migration requires an existing database and a new absolute backup path", 1);
+    const source = fs.realpathSync(file);
+    const destination = path.join(fs.realpathSync(path.dirname(backup)), path.basename(backup));
+    if (fs.lstatSync(file).isSymbolicLink() || [source, `${source}-wal`, `${source}-shm`, `${source}-journal`].includes(destination))
+        throw new AppError("store_migration_path_invalid", "Backup cannot alias the source database or its SQLite sidecars", 1);
+    try {
+        const existing = fs.lstatSync(backup);
+        if (!existing.isFile() || existing.isSymbolicLink())
+            throw new AppError("store_migration_path_invalid", "Backup path already exists", 1);
+        const reader = new DatabaseSync(file, { readOnly: true });
+        try {
+            const recorded = reader.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'dd_flow_writer_migrations'").get()
+                ? reader.prepare("SELECT receipt_json FROM dd_flow_writer_migrations WHERE backup_path = ?").get(destination) : null;
+            const receipt = recorded ? JSON.parse(String(recorded.receipt_json)) : null;
+            if (!receipt || receipt.database !== file || receipt.backup !== backup || receipt.writer_version !== readStoreWriterContract(reader) || receipt.backup_sha256 !== crypto.createHash("sha256").update(fs.readFileSync(backup)).digest("hex")) {
+                throw new AppError("store_migration_path_invalid", "Existing backup has no matching committed migration receipt", 1);
+            }
+            return receipt;
+        }
+        finally {
+            reader.close();
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const db = new DatabaseSync(file);
+    try {
+        db.exec("PRAGMA busy_timeout = 1000");
+        registerStoreWriter(db);
+        db.exec("BEGIN IMMEDIATE");
+        try {
+            const previous = readStoreWriterContract(db);
+            const tables = new Set(db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table'").all().map(row => row.name));
+            const gates = [
+                ["managed_processes", "state IS NULL OR state NOT IN ('stopped','failed')"],
+                ["run_controllers", "status IS NULL OR status NOT IN ('completed','stop_target_reached','cancelled','superseded')"],
+                ["run_control_workers", "status IS NULL OR status NOT IN ('completed','failed','superseded')"],
+                ["work_sessions", "status IS NULL OR status NOT IN ('completed','failed','cancelled')"]
+            ];
+            for (const [table, predicate] of gates) {
+                if (tables.has(table) && db.prepare(`SELECT 1 FROM ${table} WHERE ${predicate} LIMIT 1`).get())
+                    throw new AppError("store_migration_not_drained", "Store still contains unresolved writer ownership", 1, { table });
+            }
+            // A separate reader sees committed WAL while this connection prevents new writes.
+            const reader = new DatabaseSync(file, { readOnly: true });
+            try {
+                reader.exec(`VACUUM INTO '${backup.replaceAll("'", "''")}'`);
+            }
+            finally {
+                reader.close();
+            }
+            const descriptor = fs.openSync(backup, "r");
+            try {
+                fs.fsyncSync(descriptor);
+            }
+            finally {
+                fs.closeSync(descriptor);
+            }
+            const directory = fs.openSync(path.dirname(backup), "r");
+            try {
+                fs.fsyncSync(directory);
+            }
+            finally {
+                fs.closeSync(directory);
+            }
+            const verification = new DatabaseSync(backup, { readOnly: true });
+            try {
+                const check = verification.prepare("PRAGMA integrity_check").get();
+                if (Object.values(check)[0] !== "ok" || readStoreWriterContract(verification) !== previous)
+                    throw new AppError("store_migration_backup_invalid", "Backup failed integrity or contract verification", 1);
+            }
+            finally {
+                verification.close();
+            }
+            const receipt = { database: file, backup, backup_sha256: crypto.createHash("sha256").update(fs.readFileSync(backup)).digest("hex"), previous_version: previous, writer_version: 1 };
+            db.exec("CREATE TABLE IF NOT EXISTS dd_flow_writer_migrations (backup_path TEXT PRIMARY KEY, receipt_json TEXT NOT NULL)");
+            db.prepare("INSERT INTO dd_flow_writer_migrations VALUES (?, ?)").run(destination, JSON.stringify(receipt));
+            installStoreWriterContract(db);
+            db.exec("COMMIT");
+            return receipt;
+        }
+        catch (error) {
+            if (db.isTransaction)
+                db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    finally {
+        db.close();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.38",
+  "version": "0.9.0-beta.40",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {