@deksden-com/dd-flow-cli 0.9.0-beta.7 → 0.9.0-beta.75

package/dist/services/workspace-bootstrap.js

@@ -0,0 +1,76 @@
+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, reconcileWorkspaceOwnership, runCheck, workspaceOperationId } 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.
+ * Bootstrap is a project operation, not an alias classified by the engine as a test. */
+export async function runWorkspaceBootstrap(context, input) {
+    reconcileWorkspaceOwnership(context, input.workspaceRoot);
+    const generation = assertRunMutationAllowed(context, input.projectId, input.runId);
+    const operationId = workspaceOperationId(input.workspaceRoot);
+    const identity = crypto.createHash("sha256").update(JSON.stringify([input.projectId, input.runId, generation, path.resolve(input.workspaceRoot), input.command])).digest("hex");
+    const pending = managedProcessStatus(context).find(item => item.operation_id === operationId && ["starting", "running", "stopping"].includes(item.state));
+    if (pending) {
+        if (pending.kind !== "workspace-bootstrap")
+            throw new AppError("bootstrap_in_progress", "A check currently owns this workspace; wait for it before bootstrapping", 2, { process_id: pending.id, stdout_path: pending.stdout_path, stderr_path: pending.stderr_path });
+        if (processTreeIsAlive(pending) || (pending.state === "starting" && managedOwnerIsAlive(pending) !== false)) {
+            throw new AppError("bootstrap_in_progress", "Workspace preparation is still running; inspect its logs and wait for the existing process, do not launch another copy", 2, { process_id: pending.id, stdout_path: pending.stdout_path, stderr_path: pending.stderr_path });
+        }
+        let pendingIdentity = null;
+        try {
+            const metadata = JSON.parse(pending.metadata_json);
+            pendingIdentity = typeof metadata.bootstrap_identity === "string" ? metadata.bootstrap_identity : null;
+        }
+        catch { /* Legacy records have no usable identity. */ }
+        if (pendingIdentity !== identity) {
+            finishManagedProcess(context, { id: pending.id, leaseToken: pending.lease_token, state: "failed", reason: "bootstrap_identity_superseded" });
+        }
+        else {
+            const completionPath = path.join(path.dirname(pending.stdout_path), "completion.json");
+            let completion = null;
+            try {
+                completion = JSON.parse(fs.readFileSync(completionPath, "utf8"));
+            }
+            catch { /* Interrupted shell has no terminal marker. */ }
+            const exitCode = typeof completion?.exit_code === "number" ? completion.exit_code : null;
+            const error = exitCode === null ? "bootstrap ended without a completion marker; inspect retained logs before retrying" : null;
+            finishManagedProcess(context, { id: pending.id, leaseToken: pending.lease_token, state: exitCode === 0 ? "stopped" : "failed", reason: error ?? "bootstrap_completion_reconciled" });
+            assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+            return result(pending.id, pending.stdout_path, pending.stderr_path, completionPath, exitCode, error);
+        }
+    }
+    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}:${identity}`, ownerPid: process.pid, operationId, uniqueActiveOperation: true, projectId: input.projectId, runId: input.runId, stdoutPath, stderrPath, metadata: { command: input.command, workspace_root: input.workspaceRoot, bootstrap_identity: identity } });
+    const stdout = fs.openSync(stdoutPath, "a"), stderr = fs.openSync(stderrPath, "a");
+    try {
+        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))
+            throw new AppError("bootstrap_tree_not_settled", "Bootstrap shell exited but still owns live processes; resources were retained for inspection", 2, { process_id: managed.id, stdout_path: stdoutPath, stderr_path: stderrPath });
+        assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+        finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: completed.exitCode === 0 && !completed.error ? "stopped" : "failed", reason: completed.error });
+        return result(managed.id, stdoutPath, stderrPath, completionPath, completed.exitCode, completed.error);
+    }
+    finally {
+        fs.closeSync(stdout);
+        fs.closeSync(stderr);
+    }
+}
+function result(id, stdout, stderr, completion, exitCode, error) {
+    // Full logs remain on disk; keep the returned prompt bounded.
+    const excerpt = (file) => fs.existsSync(file) ? fs.readFileSync(file, "utf8").slice(-64_000) : "";
+    return { exit_code: exitCode, stdout: excerpt(stdout), stderr: excerpt(stderr), error, process_id: id, stdout_path: stdout, stderr_path: stderr, completion_path: completion };
+}

package/dist/shared/errors.js

@@ -9,6 +9,18 @@ export class AppError extends Error {
         this.details = details;
     }
 }
+/** Error fields must cross JSON boundaries as data: Error.message is not enumerable. */
+export function errorRecord(error, depth = 0) {
+    const value = error;
+    const details = value?.details && typeof value.details === "object" && !Array.isArray(value.details) ? value.details : {};
+    return {
+        code: typeof value?.code === "string" ? value.code : "unexpected",
+        message: typeof value?.message === "string" ? value.message : String(error),
+        exitCode: typeof value?.exitCode === "number" ? value.exitCode : 1,
+        details,
+        ...(value?.cause && depth < 3 ? { cause: errorRecord(value.cause, depth + 1) } : {})
+    };
+}
 export function isAppError(error) {
     return error instanceof AppError;
 }

package/dist/storage/database.js

@@ -4,9 +4,110 @@ 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(`
+    CREATE TABLE IF NOT EXISTS run_recovery_guards (
+      recovery_id TEXT PRIMARY KEY, project_id TEXT NOT NULL, run_id TEXT NOT NULL, generation INTEGER NOT NULL, status TEXT NOT NULL, interruption_json TEXT NOT NULL, settlement_json TEXT, capture_path TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, sealed_at TEXT, resumed_at TEXT, UNIQUE(project_id, run_id, generation), FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_run_recovery_guards_run ON run_recovery_guards(project_id, run_id, generation DESC);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_run_recovery_guards_active ON run_recovery_guards(project_id, run_id) WHERE status IN ('draining', 'sealed', 'resuming');
+    CREATE TABLE IF NOT EXISTS work_recovery_segments (
+      recovery_id TEXT NOT NULL, work_id TEXT NOT NULL, generation INTEGER NOT NULL, prior_started_at TEXT, evidence_path TEXT NOT NULL, status TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY(recovery_id, work_id), FOREIGN KEY(recovery_id) REFERENCES run_recovery_guards(recovery_id), FOREIGN KEY(work_id) REFERENCES works(work_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_work_recovery_segments_work ON work_recovery_segments(work_id, generation DESC);
+    CREATE TABLE IF NOT EXISTS run_recovery_bindings (
+      recovery_id TEXT PRIMARY KEY REFERENCES run_recovery_guards(recovery_id),
+      work_id TEXT NOT NULL REFERENCES works(work_id), prior_work_session_id TEXT NOT NULL,
+      session_id TEXT NOT NULL, harness TEXT NOT NULL, provider_session_id TEXT NOT NULL,
+      daemon_id TEXT NOT NULL, status TEXT NOT NULL, hook_event_key TEXT,
+      created_at TEXT NOT NULL, accepted_at TEXT
+    );
+  `);
+    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) {
     const legacy = db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('vnext_works', 'vnext_agent_turns', 'flow_agent_turns') LIMIT 1");
@@ -16,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,
@@ -46,6 +147,7 @@ export function ensureVnextWorkStorage(db) {
       status TEXT NOT NULL,
       prompt_path TEXT NOT NULL,
       result_path TEXT,
+      start_receipt_json TEXT,
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL,
       completed_at TEXT,
@@ -53,6 +155,16 @@ export function ensureVnextWorkStorage(db) {
     );
     CREATE INDEX IF NOT EXISTS idx_work_sessions_work ON work_sessions(work_id, created_at DESC);
     CREATE UNIQUE INDEX IF NOT EXISTS idx_work_sessions_open ON work_sessions(work_id) WHERE status = 'running';
+
+    CREATE TABLE IF NOT EXISTS run_recovery_guards (
+      recovery_id TEXT PRIMARY KEY, project_id TEXT NOT NULL, run_id TEXT NOT NULL, generation INTEGER NOT NULL, status TEXT NOT NULL, interruption_json TEXT NOT NULL, settlement_json TEXT, capture_path TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, sealed_at TEXT, resumed_at TEXT, UNIQUE(project_id, run_id, generation), FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_run_recovery_guards_run ON run_recovery_guards(project_id, run_id, generation DESC);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_run_recovery_guards_active ON run_recovery_guards(project_id, run_id) WHERE status IN ('draining', 'sealed', 'resuming');
+    CREATE TABLE IF NOT EXISTS work_recovery_segments (
+      recovery_id TEXT NOT NULL, work_id TEXT NOT NULL, generation INTEGER NOT NULL, prior_started_at TEXT, evidence_path TEXT NOT NULL, status TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY(recovery_id, work_id), FOREIGN KEY(recovery_id) REFERENCES run_recovery_guards(recovery_id), FOREIGN KEY(work_id) REFERENCES works(work_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_work_recovery_segments_work ON work_recovery_segments(work_id, generation DESC);
     CREATE TABLE IF NOT EXISTS check_receipts (
       id TEXT PRIMARY KEY,
       project_id TEXT NOT NULL,
@@ -65,6 +177,9 @@ export function ensureVnextWorkStorage(db) {
       command TEXT NOT NULL,
       input_hash TEXT NOT NULL DEFAULT '',
       verification_epoch TEXT NOT NULL DEFAULT '',
+      reservation_sequence INTEGER NOT NULL DEFAULT 0,
+      retry_of_receipt_id TEXT,
+      retry_reason TEXT,
       status TEXT NOT NULL,
       exit_code INTEGER,
       stdout_path TEXT NOT NULL,
@@ -82,6 +197,34 @@ export function ensureVnextWorkStorage(db) {
     );
     CREATE INDEX IF NOT EXISTS idx_check_receipts_run ON check_receipts(project_id, run_id, started_at);
   `);
+    // A committed Work start is authoritative even if publishing its prompt
+    // files is interrupted after commit.  Keep the exact bytes for repair.
+    db.writeTransaction(() => {
+        const columns = db.all("PRAGMA table_info(work_sessions)");
+        if (!columns.some((column) => column.name === "start_receipt_json"))
+            db.execSchema("ALTER TABLE work_sessions ADD COLUMN start_receipt_json TEXT");
+    });
+}
+/** 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.execSchema(`
+    CREATE TABLE IF NOT EXISTS work_launches (
+      operation_id TEXT PRIMARY KEY,
+      work_id TEXT NOT NULL UNIQUE,
+      profile_json TEXT NOT NULL,
+      profile_hash TEXT NOT NULL,
+      status TEXT NOT NULL,
+      state_dir TEXT NOT NULL,
+      journal_path TEXT NOT NULL,
+      provider_session_id TEXT,
+      adapter_receipt_json TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      FOREIGN KEY(work_id) REFERENCES works(work_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_work_launches_status ON work_launches(status, updated_at DESC);
+  `);
 }
 export function getDatabase(ddFlowHome, mode = "initialize") {
     const dbPath = path.join(ddFlowHome, "db.sqlite");
@@ -92,23 +235,45 @@ 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);
+    if (mode !== "read_existing") {
+        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");
     db.exec("PRAGMA foreign_keys = ON");
-    return {
-        path: dbPath,
-        writable: mode !== "read_existing",
-        close: () => db.close?.(),
-        exec: (sql) => db.exec(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)
-    };
+    return databaseFacade(dbPath, mode !== "read_existing", db);
 }
 /**
  * Opens the small host-wide resource registry.  It is intentionally separate
@@ -122,9 +287,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,
@@ -163,16 +344,16 @@ export function getResourceDatabase(resourceHome) {
     );
     CREATE INDEX IF NOT EXISTS idx_managed_resources_lease
       ON managed_resources(lease_expires_at, updated_at);
-  `);
-    const database = {
-        path: dbPath,
-        writable: true,
-        close: () => { resourceDatabases.delete(dbPath); db.close?.(); },
-        exec: (sql) => db.exec(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)
-    };
+  `, fresh);
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+    const database = databaseFacade(dbPath, true, db, () => {
+        resourceDatabases.delete(dbPath);
+        db.close?.();
+    });
     resourceDatabases.set(dbPath, database);
     return database;
 }
@@ -181,19 +362,131 @@ 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 }); },
+        beginWriteTransaction: () => { throw new AppError("read_only_storage", "Read-only access cannot start a write transaction", 1, { path: dbPath }); },
+        writeTransaction: () => { throw new AppError("read_only_storage", "Read-only access cannot start a write transaction", 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 databaseFacade(dbPath, writable, db, close = () => db.close?.()) {
+    let reserved = false;
+    let poisoned = false;
+    let savepoint = 0;
+    const assertUsable = () => { if (poisoned)
+        throw new AppError("write_transaction_unresolved", "Transaction cleanup failed; reopen the connection before continuing", 1); };
+    const beginWriteTransaction = () => {
+        assertUsable();
+        if (!writable)
+            throw new AppError("read_only_storage", "Read-only access cannot start a write transaction", 1, { path: dbPath });
+        db.exec("BEGIN IMMEDIATE");
+        reserved = true;
+    };
+    const rollback = (sql, original) => {
+        try {
+            db.exec(sql);
+        }
+        catch (cleanup) {
+            poisoned = true;
+            if (original instanceof AppError)
+                throw new AppError(original.code, original.message, original.exitCode, { ...original.details, transaction_cleanup_error: errorDetails(cleanup) });
+            throw new AppError("write_transaction_failed", "Write transaction failed and SQLite cleanup also failed", 1, { cause: errorDetails(original), transaction_cleanup_error: errorDetails(cleanup) });
+        }
+        throw original;
+    };
+    const writeTransaction = (operation) => {
+        assertUsable();
+        if (!writable)
+            throw new AppError("read_only_storage", "Read-only access cannot start a write transaction", 1, { path: dbPath });
+        if (db.isTransaction && !reserved)
+            throw new AppError("write_transaction_unowned", "Cannot write inside an unowned transaction or read snapshot", 1);
+        const nested = db.isTransaction;
+        const marker = `dd_flow_write_${++savepoint}`;
+        try {
+            if (nested)
+                db.exec(`SAVEPOINT ${marker}`);
+            else
+                beginWriteTransaction();
+        }
+        catch (error) {
+            throw new AppError("storage_write_failed", "Cannot reserve SQLite writer", 1, { cause: errorDetails(error), transaction_phase: "begin", transaction_rolled_back: true });
+        }
+        let phase = "body";
+        try {
+            const value = operation();
+            if (value && typeof value.then === "function") {
+                void Promise.resolve(value).catch(() => { });
+                throw new AppError("write_transaction_async", "Write transaction callback must be synchronous", 1);
+            }
+            phase = "commit";
+            if (nested)
+                db.exec(`RELEASE ${marker}`);
+            else
+                db.exec("COMMIT");
+            return value;
+        }
+        catch (error) {
+            try {
+                return rollback(nested ? `ROLLBACK TO ${marker}; RELEASE ${marker}` : "ROLLBACK", error);
+            }
+            catch (failure) {
+                if (failure === error && !(error instanceof AppError) && typeof error === "object" && error !== null && "code" in error && String(error.code).startsWith("ERR_SQLITE"))
+                    throw new AppError("storage_write_failed", "SQLite write failed", 1, { cause: errorDetails(error), transaction_phase: phase, transaction_rolled_back: true });
+                throw failure;
+            }
+        }
+        finally {
+            if (!db.isTransaction)
+                reserved = false;
+        }
+    };
+    return {
+        path: dbPath,
+        writable,
+        close,
+        exec: (sql) => { assertUsable(); try {
+            db.exec(sql);
+        }
+        finally {
+            if (!db.isTransaction)
+                reserved = false;
+        } },
+        execSchema: (sql) => { assertUsable(); if (db.isTransaction && !reserved)
+            throw new AppError("write_transaction_unowned", "Cannot change schema inside an unowned transaction", 1); executeStoreSchema(db, sql); },
+        beginWriteTransaction,
+        writeTransaction,
+        run: (sql, params = []) => { assertUsable(); return db.prepare(sql).run(...params); },
+        get: (sql, params = []) => db.prepare(sql).get(...params),
+        all: (sql, params = []) => db.prepare(sql).all(...params)
+    };
+}
+function errorDetails(error) {
+    const value = error;
+    return { message: String(value?.message ?? error), ...(typeof value?.code === "string" ? { code: value.code } : {}), ...(typeof value?.errcode === "number" ? { sqlite_extended_code: value.errcode } : {}) };
+}
 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,
@@ -564,6 +857,7 @@ function migrate(db, dbPath) {
       target_branch TEXT NOT NULL,
       enqueue_target_head TEXT,
       execution_target_head TEXT,
+      accepted_tree TEXT,
       integration_commit TEXT,
       execution_route TEXT NOT NULL,
       status TEXT NOT NULL,
@@ -573,6 +867,7 @@ function migrate(db, dbPath) {
       lock_acquired_at TEXT,
       checkpoint TEXT NOT NULL DEFAULT 'queued',
       profile_hash TEXT,
+      replacement_of_merge_request_id TEXT,
       adapter_receipt_json TEXT,
       result_json TEXT,
       last_error_json TEXT,
@@ -584,8 +879,8 @@ function migrate(db, dbPath) {
     );
     CREATE INDEX IF NOT EXISTS idx_merge_requests_fifo
       ON merge_requests(project_id, status, created_at, merge_request_id);
-    CREATE UNIQUE INDEX IF NOT EXISTS idx_merge_requests_run
-      ON merge_requests(project_id, run_id);
+    CREATE INDEX IF NOT EXISTS idx_merge_requests_run
+      ON merge_requests(project_id, run_id, created_at);
     CREATE UNIQUE INDEX IF NOT EXISTS idx_merge_requests_active_project
       ON merge_requests(project_id)
       WHERE status IN ('active', 'waiting_user', 'action_required', 'recovery_required');
@@ -797,7 +1092,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");
@@ -808,9 +1102,21 @@ function migrate(db, dbPath) {
     db.prepare("UPDATE usage SET cache_read_input_tokens = cached_input_tokens WHERE cache_read_input_tokens IS NULL AND cached_input_tokens IS NOT NULL").run();
     ensureColumn(db, "runs", "run_home_path", "ALTER TABLE runs ADD COLUMN run_home_path TEXT");
     ensureColumn(db, "runs", "run_root", "ALTER TABLE runs ADD COLUMN run_root TEXT");
+    db.prepare("UPDATE runs SET run_root = COALESCE(run_root, run_home_path, run_dir) WHERE run_root IS NULL OR run_root = ''").run();
+    ensureColumn(db, "merge_requests", "accepted_tree", "ALTER TABLE merge_requests ADD COLUMN accepted_tree TEXT");
+    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.
+    // 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");
     ensureColumn(db, "works", "payload_json", "ALTER TABLE works ADD COLUMN payload_json TEXT");
+    ensureColumn(db, "work_sessions", "start_receipt_json", "ALTER TABLE work_sessions ADD COLUMN start_receipt_json TEXT");
     ensureColumn(db, "check_receipts", "declaration_id", "ALTER TABLE check_receipts ADD COLUMN declaration_id TEXT NOT NULL DEFAULT 'CHK-LEGACY'");
     ensureColumn(db, "check_receipts", "workspace_fingerprint", "ALTER TABLE check_receipts ADD COLUMN workspace_fingerprint TEXT NOT NULL DEFAULT ''");
     ensureColumn(db, "check_receipts", "artifacts_json", "ALTER TABLE check_receipts ADD COLUMN artifacts_json TEXT NOT NULL DEFAULT '[]'");
@@ -818,6 +1124,9 @@ function migrate(db, dbPath) {
     ensureColumn(db, "check_receipts", "gate", "ALTER TABLE check_receipts ADD COLUMN gate TEXT NOT NULL DEFAULT 'work'");
     ensureColumn(db, "check_receipts", "input_hash", "ALTER TABLE check_receipts ADD COLUMN input_hash TEXT NOT NULL DEFAULT ''");
     ensureColumn(db, "check_receipts", "verification_epoch", "ALTER TABLE check_receipts ADD COLUMN verification_epoch TEXT NOT NULL DEFAULT ''");
+    ensureColumn(db, "check_receipts", "reservation_sequence", "ALTER TABLE check_receipts ADD COLUMN reservation_sequence INTEGER NOT NULL DEFAULT 0");
+    ensureColumn(db, "check_receipts", "retry_of_receipt_id", "ALTER TABLE check_receipts ADD COLUMN retry_of_receipt_id TEXT");
+    ensureColumn(db, "check_receipts", "retry_reason", "ALTER TABLE check_receipts ADD COLUMN retry_reason TEXT");
     ensureColumn(db, "check_receipts", "before_fingerprint", "ALTER TABLE check_receipts ADD COLUMN before_fingerprint TEXT NOT NULL DEFAULT ''");
     ensureColumn(db, "check_receipts", "after_fingerprint", "ALTER TABLE check_receipts ADD COLUMN after_fingerprint TEXT NOT NULL DEFAULT ''");
     ensureColumn(db, "check_receipts", "profile_hash", "ALTER TABLE check_receipts ADD COLUMN profile_hash TEXT");
@@ -837,6 +1146,7 @@ function migrate(db, dbPath) {
     ensureColumn(db, "hook_events", "parent_session_id", "ALTER TABLE hook_events ADD COLUMN parent_session_id TEXT");
     ensureColumn(db, "hook_events", "daemon_id", "ALTER TABLE hook_events ADD COLUMN daemon_id TEXT");
     ensureColumn(db, "hook_events", "cwd", "ALTER TABLE hook_events ADD COLUMN cwd TEXT");
+    ensureColumn(db, "hook_events", "outcome_json", "ALTER TABLE hook_events ADD COLUMN outcome_json TEXT");
     ensureColumn(db, "harness_usage_snapshots", "tool_calls", "ALTER TABLE harness_usage_snapshots ADD COLUMN tool_calls INTEGER");
     ensureColumn(db, "harness_usage_snapshots", "tool_failures", "ALTER TABLE harness_usage_snapshots ADD COLUMN tool_failures INTEGER");
     ensureColumn(db, "harness_usage_snapshots", "tool_by_name_json", "ALTER TABLE harness_usage_snapshots ADD COLUMN tool_by_name_json TEXT");