@deksden-com/dd-flow-cli 0.9.0-beta.8 → 0.9.0-beta.81

package/dist/storage/database.js

@@ -4,9 +4,124 @@ 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();
+/** Invocation authority is prepared once with the runtime schema. Native
+ * hooks must only verify this table; they never create it on the hot path. */
+export function ensureLifecycleInvocationStorage(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS lifecycle_invocations (
+      id TEXT PRIMARY KEY, scope_json TEXT NOT NULL, command TEXT NOT NULL,
+      fingerprint TEXT NOT NULL, status TEXT NOT NULL,
+      event_key TEXT UNIQUE, identity_json TEXT, deadline INTEGER, outcome_json TEXT,
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_lifecycle_invocations_scope
+      ON lifecycle_invocations(scope_json, fingerprint, created_at);
+  `);
+}
+/** 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 +131,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 +161,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 +169,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 +191,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 +211,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");
@@ -89,42 +246,171 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
     if (mode === "read_existing" && !exists) {
         return emptyReadOnlyDatabase(dbPath);
     }
+    if (mode === "hook" && !exists)
+        throw new AppError("hook_storage_unprepared", "Prepare the runtime store before starting native hooks", 1);
     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); ensureLifecycleInvocationStorage(db); };
+            if (mode !== "hook") {
+                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);
+            }
+            else {
+                assertHookStoreReady(db);
+            }
+        }
+        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);
+}
+/**
+ * Hook ingress is a hot, synchronous path.  It may write receipts, but it
+ * must never perform schema migration or VACUUM while the native host waits.
+ * Startup/migration owns this contract; a missing table is an explicit
+ * preparation error instead of an implicit migration race.
+ */
+function assertHookStoreReady(db) {
+    const required = ["projects", "hook_events", "codex_session_bindings", "sessions", "flow_session_segments", "lifecycle_invocations"];
+    const missing = required.filter((table) => !db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table));
+    if (missing.length)
+        throw new AppError("hook_storage_unprepared", "Managed store is not prepared for synchronous hook admission", 1, { missing_tables: missing, next_action: "Open the runtime with a normal dd-flow command and complete migration before starting the native Session." });
+    // Table presence alone does not establish compatibility with an older home.
+    const receiptColumns = {
+        hook_events: "id, project_id, harness, provider_session_id, parent_session_id, daemon_id, session_id, agent_id, turn_id, event_name, tool_name, event_key, cwd, match_key, transcript_path, status, sanitized_summary, outcome_json, created_at",
+        lifecycle_invocations: "id, scope_json, command, fingerprint, status, event_key, identity_json, deadline, outcome_json, created_at, updated_at",
+        codex_session_bindings: "session_id, project_id, protocol_id, handshake_id, cwd, transcript_path, status, created_at, updated_at"
     };
+    for (const [table, columns] of Object.entries(receiptColumns)) {
+        try {
+            db.prepare(`SELECT ${columns} FROM ${table} LIMIT 0`);
+        }
+        catch {
+            throw new AppError("hook_storage_unprepared", "Managed receipt schema needs preparation before native hooks start", 1, { table });
+        }
+    }
 }
 /**
  * Opens the small host-wide resource registry.  It is intentionally separate
  * from a RUN database: a process or a port can outlive the CLI client that
  * created it, while a RUN database belongs to one flow home.
  */
-export function getResourceDatabase(resourceHome) {
-    ensureDir(resourceHome);
+export function withResourceReadSnapshot(resourceHome, read) {
     const dbPath = path.join(resourceHome, "runtime.sqlite");
     const cached = resourceDatabases.get(dbPath);
+    if (!cached && !fs.existsSync(dbPath))
+        return read(emptyReadOnlyDatabase(dbPath));
+    const db = cached ?? new DatabaseSync(dbPath, { readOnly: true });
+    try {
+        if (!cached)
+            db.exec("PRAGMA busy_timeout = 4000; PRAGMA query_only = ON");
+        // A second process can observe SQLite's file before the initializing
+        // transaction publishes its schema. Treat that pre-commit view exactly
+        // like an absent registry; the writer path remains the serialization
+        // boundary and will reopen the committed schema.
+        if (!cached && !db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get()) {
+            return read(emptyReadOnlyDatabase(dbPath));
+        }
+        const reader = cached
+            ? { ...emptyReadOnlyDatabase(dbPath), get: cached.get, all: cached.all }
+            : databaseFacade(dbPath, false, db);
+        // SAVEPOINT also composes with an existing owner's transaction. The
+        // callback sees its uncommitted state but never receives write capability.
+        db.exec("SAVEPOINT resource_read_snapshot");
+        try {
+            const result = read(reader);
+            db.exec("RELEASE resource_read_snapshot");
+            return result;
+        }
+        catch (error) {
+            db.exec("ROLLBACK TO resource_read_snapshot");
+            db.exec("RELEASE resource_read_snapshot");
+            throw error;
+        }
+    }
+    finally {
+        if (!cached)
+            db.close?.();
+    }
+}
+export function getResourceDatabase(resourceHome, mode = "initialize") {
+    const dbPath = path.join(resourceHome, "runtime.sqlite");
+    const cached = resourceDatabases.get(dbPath);
+    if (mode === "read_existing") {
+        // Reuse a current transaction's view without exposing its write capability.
+        if (cached)
+            return { ...emptyReadOnlyDatabase(dbPath), get: cached.get, all: cached.all };
+        if (!fs.existsSync(dbPath))
+            return emptyReadOnlyDatabase(dbPath);
+        const db = new DatabaseSync(dbPath, { readOnly: true });
+        try {
+            db.exec("PRAGMA busy_timeout = 4000; PRAGMA query_only = ON");
+            if (!db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get()) {
+                db.close();
+                return emptyReadOnlyDatabase(dbPath);
+            }
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+        return databaseFacade(dbPath, false, db);
+    }
+    ensureDir(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 +449,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 +467,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,
@@ -574,6 +972,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,
@@ -585,8 +984,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');
@@ -798,7 +1197,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");
@@ -811,9 +1209,19 @@ function migrate(db, dbPath) {
     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 '[]'");
@@ -821,6 +1229,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");
@@ -840,6 +1251,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");

package/dist/storage/paths.js

@@ -15,6 +15,8 @@ export function resolveProjectRoot(root) {
     if (!fs.existsSync(absolute)) {
         throw new AppError("not_found", `Project root does not exist: ${absolute}`, 1);
     }
+    if (!fs.statSync(absolute).isDirectory())
+        throw new AppError("validation", "Project root must be a directory", 2, { project_root: absolute });
     return fs.realpathSync(absolute);
 }
 /** Resolve an existing path to its filesystem identity, or normalize a future path. */
@@ -24,10 +26,16 @@ export function canonicalPath(value, mustExist = true) {
         return fs.realpathSync(absolute);
     if (mustExist)
         throw new AppError("not_found", `Path does not exist: ${absolute}`, 1, { path: absolute });
-    const parent = path.dirname(absolute);
-    if (!fs.existsSync(parent))
-        return absolute;
-    return path.join(fs.realpathSync(parent), path.basename(absolute));
+    const missing = [];
+    let parent = absolute;
+    while (!fs.existsSync(parent)) {
+        missing.unshift(path.basename(parent));
+        const next = path.dirname(parent);
+        if (next === parent)
+            return absolute;
+        parent = next;
+    }
+    return path.join(fs.realpathSync(parent), ...missing);
 }
 export function assertPathWithin(root, candidate, label = "path") {
     const canonicalRoot = canonicalPath(root);
@@ -100,6 +108,11 @@ export function stateJsonPath(projectRoot, protocolId) {
 export function planJsonPath(projectRoot, protocolId) {
     return path.join(protocolDir(projectRoot, protocolId), "plan.json");
 }
+/** Project canonical plan takes precedence over a retained workspace location. */
+export function resolveProtocolPlanPath(projectRoot, protocolId, recordedPath) {
+    const canonical = planJsonPath(projectRoot, protocolId);
+    return fs.existsSync(canonical) ? canonical : recordedPath;
+}
 export function projectHome(ddFlowHome, projectId) {
     return path.join(ddFlowHome, "projects", projectId);
 }