@deksden-com/dd-flow-cli 0.9.0-beta.103 → 0.9.0-beta.105

package/dist/services/managed-processes.js

@@ -86,24 +86,23 @@ export function registerManagedProcess(context, rawInput) {
     if (!input.uniqueActiveOperation)
         return insertManagedProcess(context, input, metadataJson);
     const db = registry(context);
-    db.beginWriteTransaction();
-    try {
+    if (observer && !processIsAlive({ pid: input.pid, pid_started_at: observerBirth }))
+        throw new AppError("process_ownership_unknown", "EVAL observer changed before registration", 1);
+    return db.writeTransaction(() => {
         const existing = db.get("SELECT * FROM managed_processes WHERE operation_id = ? AND state IN ('starting','running','stopping','orphaned')", [input.operationId]);
         if (existing)
             throw new AppError("managed_operation_in_progress", "The operation already owns a managed process; observe it instead of spawning a duplicate", 1, { process_id: existing.id, operation_id: input.operationId });
         let result = insertManagedProcess(context, input, metadataJson);
         if (observer) {
-            result = confirmManagedProcess(context, { id: result.id, leaseToken: result.lease_token, pid: input.pid, ...(input.processGroupId ? { processGroupId: input.processGroupId } : {}) });
-            if (result.pid_started_at !== observerBirth || !processIsAlive(result))
-                throw new AppError("process_ownership_unknown", "EVAL observer changed before registration committed", 1);
+            const metadata = JSON.parse(metadataJson);
+            if (input.processGroupId)
+                metadata.process_group_id = input.processGroupId;
+            const now = context.now();
+            db.run("UPDATE managed_processes SET pid = ?, pid_started_at = ?, state = 'running', lease_expires_at = ?, updated_at = ?, metadata_json = ? WHERE id = ? AND lease_token = ? AND state = 'starting'", [input.pid, observerBirth, leaseExpiry(now, input.leaseMs), now, JSON.stringify(metadata), result.id, result.lease_token]);
+            result = requireProcess(db, result.id);
         }
-        db.exec("COMMIT");
         return result;
-    }
-    catch (error) {
-        db.exec("ROLLBACK");
-        throw error;
-    }
+    });
 }
 function insertManagedProcess(context, input, metadataJson) {
     const db = registry(context);
@@ -167,6 +166,21 @@ export function heartbeatManagedProcess(context, input) {
     const db = registry(context);
     return db.run("UPDATE managed_processes SET lease_expires_at = ?, updated_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','stopping')", [leaseExpiry(context.now(), input.leaseMs), context.now(), input.id, input.leaseToken]).changes === 1;
 }
+/** Read-only lease check for a caller already holding a RUN writer. Renewal
+ * must happen before entering that writer, never from this assertion. */
+export function assertManagedProcessLease(context, input) {
+    const reader = getResourceDatabase(resourceHome(context), "read_isolated");
+    try {
+        const current = reader.get("SELECT pid, lease_expires_at, state FROM managed_processes WHERE id = ? AND lease_token = ?", [input.id, input.leaseToken]);
+        if (!current || current.pid !== input.pid || !["starting", "running"].includes(current.state)
+            || Date.parse(current.lease_expires_at) <= Date.now()) {
+            throw new AppError("controller_lease_lost", "Managed owner lease changed or expired before productive dispatch", 1, { process_id: input.id });
+        }
+    }
+    finally {
+        reader.close?.();
+    }
+}
 export function prepareManagedProcessFinish(context, input) {
     requireProcessText(input.id, "id");
     requireProcessText(input.leaseToken, "lease-token");
@@ -234,26 +248,24 @@ export function managedOwnerIsAlive(record) {
 export function claimExpiredManagedProcesses(context, ownerId) {
     const db = registry(context);
     const now = context.now();
-    db.beginWriteTransaction();
-    try {
-        const candidates = db.all("SELECT * FROM managed_processes WHERE state IN ('starting','running','stopping','orphaned') AND lease_expires_at < ? ORDER BY lease_expires_at, id", [now]);
+    const candidates = db.all("SELECT * FROM managed_processes WHERE state IN ('starting','running','stopping','orphaned') AND lease_expires_at < ? ORDER BY lease_expires_at, id", [now]).filter(candidate => {
+        const ownerAlive = managedOwnerIsAlive(candidate);
+        return ownerAlive !== true && !(ownerAlive === null && processTreeIsAlive(candidate));
+    });
+    return db.writeTransaction(() => {
         const claimed = [];
         for (const candidate of candidates) {
-            const ownerAlive = managedOwnerIsAlive(candidate);
-            if (ownerAlive === true || (ownerAlive === null && processTreeIsAlive(candidate)))
+            // A heartbeat or replacement registration invalidates the pre-writer
+            // death proof; expiry alone never authorizes claiming that new owner.
+            if (JSON.stringify(db.get("SELECT * FROM managed_processes WHERE id = ?", [candidate.id])) !== JSON.stringify(candidate))
                 continue;
             const token = crypto.randomUUID();
             const result = db.run("UPDATE managed_processes SET owner_id = ?, lease_token = ?, state = 'orphaned', lease_expires_at = ?, updated_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','stopping','orphaned') AND lease_expires_at < ?", [ownerId, token, leaseExpiry(now), now, candidate.id, candidate.lease_token, now]);
             if (result.changes === 1)
                 claimed.push({ ...candidate, owner_id: ownerId, lease_token: token, state: "orphaned", updated_at: now });
         }
-        db.exec("COMMIT");
         return claimed;
-    }
-    catch (error) {
-        db.exec("ROLLBACK");
-        throw error;
-    }
+    });
 }
 /** Workspace gates are leases, not spawned processes. Children retain their own registrations. */
 export function managedLeaseReleased(record) {
@@ -400,7 +412,7 @@ function leaseExpiry(now, leaseMs = defaultLeaseMs) {
         throw new AppError("validation", "--lease-ms must be a positive integer within the supported date range", 2);
     return new Date(Date.parse(now) + leaseMs).toISOString();
 }
-export function processStartedAt(pid) { const result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" }); const value = result.status === 0 ? result.stdout.trim() : ""; return value || null; }
+export function processStartedAt(pid) { const result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", timeout: 1_000 }); const value = result.status === 0 ? result.stdout.trim() : ""; return value || null; }
 function releasePortClaims(db, claims) { for (const claim of claims)
     db.run("DELETE FROM managed_resources WHERE resource_kind = 'port' AND resource_key = ? AND lease_token = ?", [claim.key, claim.token]); }
 function terminateOwnedProcess(record, signal) {

package/dist/services/merge-queue.js

@@ -8,6 +8,38 @@ import { ensureLaneWorkspace, heartbeatLaneLock, laneRecord, prepareLaneLock, pr
 import { stopMergeWorker, stoppedMergeWorkerState } from "./sessions.js";
 import { getProtocolBranchContext, requireClaimableBranchBundle } from "./branch-context.js";
 const mergeLockTtlSeconds = 300;
+/** SQL evidence comes from the same read snapshot as filesystem preparation.
+ * Bundle membership scans only branch metadata; unrelated RUN writes do not
+ * invalidate an individual job's accepted inputs. */
+function prepareMergePublication(context, root, workerId, prepare, protocolIds, mode, requireLock = true) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(root));
+    return context.db.readSnapshot(() => {
+        const value = prepare(), ids = JSON.stringify(protocolIds(value));
+        const observe = () => ({
+            root: context.db.get("SELECT root FROM projects WHERE id = ?", [project.id]),
+            lane: context.db.get("SELECT workspace_path, expected_branch, status FROM lanes WHERE project_id = ? AND name = 'merge'", [project.id]),
+            lock: context.db.get("SELECT id, worker_id, lease_token FROM lane_locks WHERE project_id = ? AND lane = 'merge' AND status = 'active'", [project.id]),
+            worker: workerId ? stoppedMergeWorkerState(context, project.id, workerId) : null,
+            queue: mode === "head" ? context.db.all("SELECT * FROM merge_queue WHERE project_id = ? AND status IN ('ready','requeued') ORDER BY created_at, id LIMIT 1", [project.id])
+                : context.db.all(`SELECT * FROM merge_queue WHERE project_id = ? ${mode === "bundle" ? "" : "AND protocol_id IN (SELECT value FROM json_each(?))"} ORDER BY id`, mode === "bundle" ? [project.id] : [project.id, ids]),
+            protocols: context.db.all("SELECT * FROM protocols WHERE project_id = ? AND id IN (SELECT value FROM json_each(?)) ORDER BY id", [project.id, ids]),
+            states: context.db.all("SELECT protocol_id, payload_json FROM audit_events WHERE id IN (SELECT MAX(id) FROM audit_events WHERE project_id = ? AND event_type = 'protocol.state_projection' AND protocol_id IN (SELECT value FROM json_each(?)) GROUP BY protocol_id) ORDER BY protocol_id", [project.id, ids]),
+            runs: context.db.all("SELECT id, subject_id, status, verdict, next_action, index_json, created_at, updated_at, completed_at FROM runs WHERE project_id = ? AND subject_type = 'protocol' AND subject_id IN (SELECT value FROM json_each(?)) ORDER BY id", [project.id, ids]),
+            ...(mode === "bundle" ? {
+                membership: context.db.all("SELECT id, status, stage, next_action, workspace_json, route_json, active_def_json FROM protocols WHERE project_id = ? ORDER BY id", [project.id]),
+                worktrees: context.db.all("SELECT protocol_id, integration_branch, feature_branch, base_ref, worktree_path, status FROM worktree_records WHERE project_id = ? ORDER BY protocol_id", [project.id]),
+                sessions: context.db.all("SELECT session_id, protocol_id, worker_id, flow_kind, status, current_stage, next_action FROM sessions WHERE project_id = ? AND status IN ('pending','active','waiting_user','blocked','stopping') ORDER BY session_id", [project.id])
+            } : {})
+        });
+        const expected = JSON.stringify(observe());
+        return { value, assertCurrent: () => {
+                if (JSON.stringify(observe()) !== expected)
+                    throw new AppError("merge_preparation_changed", "Merge ownership or input authority changed during preparation", 1, { effect: "no_effect" });
+                if (requireLock && !context.db.get("SELECT 1 FROM lane_locks WHERE project_id = ? AND lane = 'merge' AND status = 'active' AND worker_id = ? AND expires_at > ?", [project.id, workerId, context.now()]))
+                    throw new AppError("lane_lock_not_active", "Prepared merge lost its live lane lease", 1, { effect: "no_effect" });
+            } };
+    });
+}
 export function getMergeQueueStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     return {
@@ -47,21 +79,19 @@ export function prepareMergeClaim(context, input) {
     return { project, job, transition };
 }
 export function claimNextMergeJob(context, input) {
-    const { project } = prepareMergeClaim(context, input);
+    const prepared = prepareMergePublication(context, input.projectRoot, input.workerId, () => prepareMergeClaim(context, input), value => value.job ? [value.job.protocol_id] : [], "head");
+    const { project, job, transition } = prepared.value;
     const now = context.now();
     let claimedProtocolId = null;
-    context.db.beginWriteTransaction();
-    try {
-        const { job, transition } = prepareMergeClaim(context, input);
+    const early = context.db.writeTransaction(() => {
+        prepared.assertCurrent();
         if (!job) {
-            context.db.exec("COMMIT");
             return mergeQueueResult(null, { ok: true, outcome: "empty", claimed: false });
         }
         const update = context.db.run(`UPDATE merge_queue
        SET status = 'claimed', claimed_by_session_id = ?, claimed_at = ?, updated_at = ?
        WHERE id = ? AND status IN ('ready', 'requeued')`, [input.workerId, now, now, job.id]);
         if (update.changes !== 1) {
-            context.db.exec("COMMIT");
             return mergeQueueResult(null, { ok: true, outcome: "empty", claimed: false });
         }
         appendAudit(context, {
@@ -72,12 +102,10 @@ export function claimNextMergeJob(context, input) {
         });
         transitionClaimedProtocolToIntegration(context, transition, input.workerId, now);
         claimedProtocolId = job.protocol_id;
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+        return null;
+    });
+    if (early)
+        return early;
     return mergeQueueResult(claimedProtocolId ? queueJobByProtocol(context, project.id, claimedProtocolId) : null, {
         ok: true,
         outcome: claimedProtocolId ? "claimed" : "empty",
@@ -86,13 +114,12 @@ export function claimNextMergeJob(context, input) {
 }
 export function claimMergeJob(context, input) {
     requireMergeText(input.protocolId, "protocol-id");
-    const { project } = prepareMergeClaim(context, input);
+    const prepared = prepareMergePublication(context, input.projectRoot, input.workerId, () => prepareMergeClaim(context, input), () => [input.protocolId], "target");
+    const { project, job: selectedJob, transition: selectedTransition } = prepared.value;
     const now = context.now();
-    context.db.beginWriteTransaction();
-    try {
-        const prepared = prepareMergeClaim(context, input);
-        const job = prepared.job;
-        const transition = prepared.transition;
+    return context.db.writeTransaction(() => {
+        prepared.assertCurrent();
+        const job = selectedJob, transition = selectedTransition;
         const update = context.db.run(`UPDATE merge_queue
        SET status = 'claimed', claimed_by_session_id = ?, claimed_at = ?, updated_at = ?
        WHERE id = ? AND status IN ('ready', 'requeued')`, [input.workerId, now, now, job.id]);
@@ -106,13 +133,8 @@ export function claimMergeJob(context, input) {
             payload: { protocol_id: job.protocol_id, worker_id: input.workerId, targeted: true }
         });
         transitionClaimedProtocolToIntegration(context, transition, input.workerId, now);
-        context.db.exec("COMMIT");
         return mergeQueueResult(queueJobByProtocol(context, project.id, job.protocol_id), { ok: true, outcome: "claimed", claimed: true, targeted: true });
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+    });
 }
 export function prepareMergeBundleClaim(context, input) {
     requireMergeText(input.workerId, "worker-id");
@@ -138,11 +160,11 @@ export function prepareMergeBundleClaim(context, input) {
     return { project, protocolIds, transitions };
 }
 export function claimMergeBundle(context, input) {
-    const { project, protocolIds } = prepareMergeBundleClaim(context, input);
+    const prepared = prepareMergePublication(context, input.projectRoot, input.workerId, () => prepareMergeBundleClaim(context, input), value => value.protocolIds, "bundle");
+    const { project, protocolIds, transitions } = prepared.value;
     const now = context.now();
-    context.db.beginWriteTransaction();
-    try {
-        const transitions = protocolIds.map((protocolId) => prepareClaimedProtocolTransition(context, project.id, protocolId));
+    context.db.writeTransaction(() => {
+        prepared.assertCurrent();
         // Claim every queue row before publishing any filesystem state.
         for (const protocolId of protocolIds) {
             const update = context.db.run(`UPDATE merge_queue
@@ -170,12 +192,7 @@ export function claimMergeBundle(context, input) {
             eventType: "merge_bundle.claimed",
             payload: { project_id: project.id, worker_id: input.workerId, protocol_ids: protocolIds, workspace_path: input.workspacePath }
         });
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+    });
     return mergeBundleResult(context, {
         ok: true,
         outcome: "claimed",
@@ -412,12 +429,11 @@ export function prepareMergeBundleCompletion(context, input) {
     return { project, protocolIds, jobs };
 }
 export function completeMergeBundle(context, input) {
-    prepareMergeBundleCompletion(context, input);
+    const publication = prepareMergePublication(context, input.projectRoot, input.workerId, () => prepareMergeBundleCompletion(context, input), value => value.protocolIds, "bundle");
+    const prepared = publication.value;
     const now = context.now();
-    let prepared;
-    context.db.beginWriteTransaction();
-    try {
-        prepared = prepareMergeBundleCompletion(context, input);
+    context.db.writeTransaction(() => {
+        publication.assertCurrent();
         const { project, protocolIds, jobs } = prepared;
         for (const { protocol, job, state, flowContract, targetStage, targetStatus } of jobs) {
             const protocolId = protocol.id;
@@ -443,12 +459,7 @@ export function completeMergeBundle(context, input) {
             eventType: "merge_bundle.completed",
             payload: { project_id: project.id, worker_id: input.workerId, summary: input.summary, protocol_ids: protocolIds }
         });
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+    });
     const { project, protocolIds } = prepared;
     const stop_after_current = stopAfterCurrentIfRequested(context, project.id, project.root, input.workerId, "merge bundle complete after stop request");
     return mergeBundleResult(context, {
@@ -569,13 +580,12 @@ export function prepareMergeBundleFailure(context, input) {
     return { project, protocolIds, jobs };
 }
 export function failMergeBundle(context, input) {
-    prepareMergeBundleFailure(context, input);
+    const publication = prepareMergePublication(context, input.projectRoot, input.workerId, () => prepareMergeBundleFailure(context, input), value => value.protocolIds, "bundle");
+    const prepared = publication.value;
     const now = context.now();
     const status = input.requeue ? "requeued" : "failed";
-    let prepared;
-    context.db.beginWriteTransaction();
-    try {
-        prepared = prepareMergeBundleFailure(context, input);
+    context.db.writeTransaction(() => {
+        publication.assertCurrent();
         const { project, protocolIds, jobs } = prepared;
         for (const { protocol, job, state } of jobs) {
             const protocolId = protocol.id;
@@ -605,12 +615,7 @@ export function failMergeBundle(context, input) {
             reason: input.reason,
             payload: { project_id: project.id, worker_id: input.workerId, requeue: input.requeue, protocol_ids: protocolIds }
         });
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+    });
     const { project, protocolIds } = prepared;
     const stop_after_current = stopAfterCurrentIfRequested(context, project.id, project.root, input.workerId, "merge bundle fail after stop request");
     return mergeBundleResult(context, {
@@ -665,13 +670,14 @@ export function prepareMergeQueueCancellation(context, input) {
     return { protocol, job, reason };
 }
 export function cancelMergeQueueJob(context, input) {
-    const { protocol } = prepareMergeQueueCancellation(context, input);
+    const prepared = prepareMergePublication(context, input.projectRoot, input.workerId, () => prepareMergeQueueCancellation(context, input), value => [value.protocol.id], "target", false);
+    const { protocol, job, reason } = prepared.value;
     const now = context.now();
-    context.db.beginWriteTransaction();
-    try {
-        const { job, reason } = prepareMergeQueueCancellation(context, input);
+    const early = context.db.writeTransaction(() => {
+        prepared.assertCurrent();
+        if (job.status === "claimed" && !input.force && !context.db.get("SELECT 1 FROM lane_locks WHERE project_id = ? AND lane = 'merge' AND status = 'active' AND worker_id = ? AND expires_at > ?", [protocol.project_id, input.workerId, context.now()]))
+            throw new AppError("lane_lock_not_active", "Prepared cancellation lost its live lane lease", 1);
         if (job.status === "cancelled") {
-            context.db.exec("COMMIT");
             return mergeQueueResult(job, { ok: true, outcome: "cancelled", cancelled: false, reason: "already_cancelled" });
         }
         context.db.run(`UPDATE merge_queue
@@ -685,12 +691,10 @@ export function cancelMergeQueueJob(context, input) {
             forced: input.force,
             payload: { protocol_id: protocol.id, from: job.status, worker_id: input.workerId ?? null }
         });
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+        return null;
+    });
+    if (early)
+        return early;
     return mergeQueueResult(queueJobByProtocol(context, protocol.project_id, protocol.id), { ok: true, outcome: "cancelled", cancelled: true });
 }
 export function queueForProject(context, projectId) {

package/dist/services/merge-server.js

@@ -63,26 +63,18 @@ export function stopMergeServer(context, input) { const changed = context.db.run
     throw new AppError("not_found", "Running merge-server was not found", 1, { server_id: input.serverId }); return { ok: true, server_id: input.serverId, status: "stopping" }; }
 /** Both dispatchers enter the same project FIFO before creating any provider Session. */
 export function claimQueuedMergeRequest(context, input) {
-    context.db.beginWriteTransaction();
-    try {
+    return context.db.writeTransaction(() => {
         const request = context.db.get("SELECT merge_request_id, project_id, run_id, executor_work_id, target_workspace, execution_route, status, created_at FROM merge_requests WHERE merge_request_id = ?", [input.requestId]);
         if (!request)
             throw new AppError("not_found", "MERGE request was not found", 1);
         const generation = assertRunMutationAllowed(context, request.project_id, request.run_id, input.expectedGeneration);
         const earlier = context.db.get("SELECT 1 FROM merge_requests WHERE project_id = ? AND status NOT IN ('completed','failed','cancelled','superseded') AND (created_at < ? OR (created_at = ? AND merge_request_id < ?)) LIMIT 1", [request.project_id, request.created_at, request.created_at, request.merge_request_id]);
-        if (request.status !== "queued" || request.execution_route !== "server" || earlier) {
-            context.db.exec("COMMIT");
+        if (request.status !== "queued" || request.execution_route !== "server" || earlier)
             return null;
-        }
         const token = crypto.randomUUID();
         context.db.run("UPDATE merge_requests SET status = 'dispatching', dispatch_owner = ?, dispatch_lease_token = ?, dispatch_lease_expires_at = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'queued'", [input.ownerId, token, new Date(Date.now() + 120_000).toISOString(), context.now(), request.merge_request_id]);
-        context.db.exec("COMMIT");
         return { request, token, generation };
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+    });
 }
 async function dispatch(context, input) {
     const run = context.db.get("SELECT index_json, project_root FROM runs WHERE project_id = ? AND id = ?", [input.request.project_id, input.request.run_id]);

package/dist/services/migrations.js

@@ -6,6 +6,7 @@ import { requireProjectByRoot } from "./projects.js";
 import { getProjectVersionStatus, resolveStatusProjectRoot } from "./version-status.js";
 import { resolveCanonRoot } from "./canon.js";
 import { getDatabase } from "../storage/database.js";
+import { cleanupScopeWriters } from "./scope-writer-cleanup.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { classifyCliOperation } from "./cli-operation-classifier.js";
 import { compatibilityContexts, selectEngine } from "./engines.js";
@@ -204,8 +205,27 @@ export function prepareMigrationApply(context, input) {
     return { project, sourceVersion, targetVersion, verifiedBackup, reportEngine, chain };
 }
 export function applyMigration(context, input, prepared = prepareMigrationApply(context, input)) {
-    const { project, sourceVersion, targetVersion, verifiedBackup, reportEngine, chain } = prepared;
     const writeDb = getDatabase(context.ddFlowHome, "migrate");
+    let result, primary, failed = false;
+    try {
+        result = applyPreparedMigration(context, prepared, writeDb);
+    }
+    catch (error) {
+        primary = error;
+        failed = true;
+    }
+    const cleanup = cleanupScopeWriters([{ name: writeDb.path, db: writeDb, rollback: false, close: "always" }]);
+    if (failed) {
+        if (primary instanceof AppError && cleanup.length)
+            primary.details.migration_cleanup_errors = cleanup;
+        throw primary;
+    }
+    if (cleanup.length)
+        throw new AppError("migration_cleanup_failed", "Migration receipt is available but its connection could not be closed", 1, { effect: result?.changed ? "committed" : "no_effect", migration_cleanup_errors: cleanup });
+    return result;
+}
+function applyPreparedMigration(context, prepared, writeDb) {
+    const { project, sourceVersion, targetVersion, verifiedBackup, reportEngine, chain } = prepared;
     const already = writeDb.get("SELECT value_json FROM runtime_config WHERE key = ?", [applyKey(project.id, sourceVersion, targetVersion)]);
     if (already) {
         return { ok: true, schema_id: "dd-flow/mb-upgrade-migration-apply@1", status: "verified_noop", changed: false, backup: verifiedBackup, recovery: JSON.parse(already.value_json) };
@@ -225,18 +245,14 @@ export function applyMigration(context, input, prepared = prepareMigrationApply(
         chain: chain.steps.map((step) => ({ ...step, status: "applied" }))
     };
     try {
-        writeDb.beginWriteTransaction();
-        const current = activeStateSummary({ ...context, db: writeDb }, project.id);
-        if (activeStateBlockers(current).length)
-            throw new AppError("migration_active_state", "Migration apply requires a quiescent shared home", 1, { active_state: current });
-        writeDb.run(`INSERT INTO runtime_config (key, value_json, created_at, updated_at) VALUES (?, ?, ?, ?)`, [applyKey(project.id, sourceVersion, targetVersion), JSON.stringify(result), context.now(), context.now()]);
-        writeDb.exec("COMMIT");
+        writeDb.writeTransaction(() => {
+            const current = activeStateSummary({ ...context, db: writeDb }, project.id);
+            if (activeStateBlockers(current).length)
+                throw new AppError("migration_active_state", "Migration apply requires a quiescent shared home", 1, { active_state: current });
+            writeDb.run(`INSERT INTO runtime_config (key, value_json, created_at, updated_at) VALUES (?, ?, ?, ?)`, [applyKey(project.id, sourceVersion, targetVersion), JSON.stringify(result), context.now(), context.now()]);
+        });
     }
     catch (error) {
-        try {
-            writeDb.exec("ROLLBACK");
-        }
-        catch { /* preserve the original failure */ }
         throw new AppError("migration_apply_failed", "Migration apply failed before upgrade RUN creation or canon sync", 1, {
             recovery: {
                 status: "required",
@@ -246,7 +262,7 @@ export function applyMigration(context, input, prepared = prepareMigrationApply(
                 rollback_route: "restore the verified backup before retrying mb-upgrade apply",
                 next_action: "inspect the failed apply and retry only with the same pinned target contract"
             },
-            cause: String(error)
+            cause: error instanceof AppError ? { code: error.code, message: error.message, details: error.details } : String(error)
         });
     }
     return { ok: true, schema_id: "dd-flow/mb-upgrade-migration-apply@1", status: "applied", changed: true, backup: verifiedBackup, recovery: result };

package/dist/services/plan-runtime.js

@@ -23,7 +23,7 @@ export function readCanonicalPlan(planPath, protocolId) {
     }
 }
 export function prepareCanonicalPlan(context, input, canonical = readCanonicalPlan(input.planPath, input.protocolId)) {
-    const binding = context.db.get("SELECT plan_revision, plan_sha256, plan_path FROM plan_bindings WHERE project_id = ? AND protocol_id = ?", [input.projectId, input.protocolId]);
+    const binding = context.db.get("SELECT plan_id, plan_revision, plan_sha256, plan_path FROM plan_bindings WHERE project_id = ? AND protocol_id = ?", [input.projectId, input.protocolId]);
     if (binding && (binding.plan_revision !== canonical.revision || binding.plan_sha256 !== canonical.sha256)) {
         throw new AppError("plan_stale", "Canonical plan changed after the runtime binding was created", 1, {
             protocol_id: input.protocolId,
@@ -38,11 +38,15 @@ export function prepareCanonicalPlan(context, input, canonical = readCanonicalPl
 }
 export function boundCanonicalPlan(context, input, prepared) {
     const canonical = prepareCanonicalPlan(context, input, prepared);
-    const binding = context.db.get("SELECT plan_revision, plan_sha256, plan_path FROM plan_bindings WHERE project_id = ? AND protocol_id = ?", [input.projectId, input.protocolId]);
+    const binding = context.db.get("SELECT plan_id, plan_revision, plan_sha256, plan_path FROM plan_bindings WHERE project_id = ? AND protocol_id = ?", [input.projectId, input.protocolId]);
     const now = context.now();
     if (!binding) {
-        context.db.run(`INSERT INTO plan_bindings (project_id, protocol_id, plan_revision, plan_sha256, plan_path, bound_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`, [input.projectId, input.protocolId, canonical.revision, canonical.sha256, input.planPath, now, now]);
+        context.db.run(`INSERT INTO plan_bindings (project_id, protocol_id, plan_id, plan_revision, plan_sha256, plan_path, bound_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [input.projectId, input.protocolId, canonical.plan.plan_id, canonical.revision, canonical.sha256, input.planPath, now, now]);
+    }
+    else if (binding.plan_id === null) {
+        // Older bindings are upgraded when their canonical source is validated.
+        context.db.run("UPDATE plan_bindings SET plan_id = ?, updated_at = ? WHERE project_id = ? AND protocol_id = ? AND plan_id IS NULL", [canonical.plan.plan_id, now, input.projectId, input.protocolId]);
     }
     for (const item of canonical.plan.items) {
         context.db.run(`INSERT INTO plan_progress

package/dist/services/projects.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { foreignKeyTransaction } from "../storage/foreign-key-transaction.js";
 import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId, slugFromRoot } from "../domain/entity-ids.js";
 import { AppError } from "../shared/errors.js";
 import { projectRuntimeRoot, resolveProjectRoot } from "../storage/paths.js";
@@ -148,9 +149,7 @@ export function migrateProjectIds(context, input) {
     if (conflictingProject) {
         throw new AppError("conflict", `Target project id already exists: ${target.id}`, 1, plan);
     }
-    context.db.exec("PRAGMA foreign_keys = OFF");
-    context.db.beginWriteTransaction();
-    try {
+    foreignKeyTransaction(context.db, () => {
         context.db.run("UPDATE projects SET id = ?, short_id = ?, slug = ?, state_root = ?, updated_at = ? WHERE id = ?", [target.id, target.short_id, target.slug, target.state_root, now, oldId]);
         for (const table of projectReferenceTables()) {
             context.db.run(`UPDATE ${table} SET project_id = ? WHERE project_id = ?`, [target.id, oldId]);
@@ -162,14 +161,7 @@ export function migrateProjectIds(context, input) {
                 foreign_key_errors: foreignKeyErrors
             });
         }
-        context.db.exec("COMMIT");
-        context.db.exec("PRAGMA foreign_keys = ON");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        context.db.exec("PRAGMA foreign_keys = ON");
-        throw error;
-    }
+    });
     appendAudit(context, {
         projectId: target.id,
         eventType: "project.id_migrated",