@deksden-com/dd-flow-cli 0.9.0-beta.74 → 0.9.0-beta.79

package/dist/services/merge-queue.js

@@ -4,7 +4,7 @@ import { appendAudit } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
 import { persistProtocolState, protocolRunDiagnostics, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { resolveProjectRoot } from "../storage/paths.js";
-import { ensureLaneWorkspace, heartbeatLaneLock, releaseLaneLock, requireLaneLockOwner, waitAcquireLaneLock } from "./lanes.js";
+import { ensureLaneWorkspace, heartbeatLaneLock, laneRecord, prepareLaneLock, prepareLaneWaitTiming, prepareLaneWorkspace, releaseLaneLock, requireLaneLockOwner, waitAcquireLaneLock } from "./lanes.js";
 import { stopMergeWorker, stoppedMergeWorkerState } from "./sessions.js";
 import { getProtocolBranchContext, requireClaimableBranchBundle } from "./branch-context.js";
 const mergeLockTtlSeconds = 300;
@@ -18,7 +18,10 @@ export function getMergeQueueStatus(context, input) {
 export function getMergeBundleStatus(context, input) {
     return getProtocolBranchContext(context, { projectRoot: input.projectRoot, workspacePath: input.workspacePath });
 }
-export function claimNextMergeJob(context, input) {
+export function prepareMergeClaim(context, input) {
+    requireMergeText(input.workerId, "worker-id");
+    if (input.protocolId !== undefined)
+        requireMergeText(input.protocolId, "protocol-id");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const stopState = stoppedMergeWorkerState(context, project.id, input.workerId);
     if (stopState.stopped) {
@@ -34,14 +37,22 @@ export function claimNextMergeJob(context, input) {
         workerId: input.workerId,
         workspacePath: input.workspacePath
     });
+    const job = input.protocolId !== undefined
+        ? queueJobByProtocol(context, project.id, input.protocolId)
+        : context.db.get("SELECT * FROM merge_queue WHERE project_id = ? AND status IN ('ready', 'requeued') ORDER BY created_at ASC, id ASC LIMIT 1", [project.id]);
+    if (input.protocolId !== undefined && (!job || !["ready", "requeued"].includes(job.status))) {
+        throw new AppError("merge_job_not_claimable", "Requested merge job is not ready to claim", 1, { protocol_id: input.protocolId, status: job?.status ?? "missing", allowed: ["ready", "requeued"] });
+    }
+    const transition = job ? prepareClaimedProtocolTransition(context, project.id, job.protocol_id) : null;
+    return { project, job, transition };
+}
+export function claimNextMergeJob(context, input) {
+    const { project } = prepareMergeClaim(context, input);
     const now = context.now();
     let claimedProtocolId = null;
     context.db.beginWriteTransaction();
     try {
-        const job = context.db.get(`SELECT * FROM merge_queue
-       WHERE project_id = ? AND status IN ('ready', 'requeued')
-       ORDER BY created_at ASC, id ASC
-       LIMIT 1`, [project.id]);
+        const { job, transition } = prepareMergeClaim(context, input);
         if (!job) {
             context.db.exec("COMMIT");
             return mergeQueueResult(null, { ok: true, outcome: "empty", claimed: false });
@@ -59,7 +70,7 @@ export function claimNextMergeJob(context, input) {
             eventType: "merge_queue.claimed",
             payload: { protocol_id: job.protocol_id, worker_id: input.workerId }
         });
-        transitionClaimedProtocolToIntegration(context, project.id, job.protocol_id, input.workerId, now);
+        transitionClaimedProtocolToIntegration(context, transition, input.workerId, now);
         claimedProtocolId = job.protocol_id;
         context.db.exec("COMMIT");
     }
@@ -74,32 +85,14 @@ export function claimNextMergeJob(context, input) {
     });
 }
 export function claimMergeJob(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const stopState = stoppedMergeWorkerState(context, project.id, input.workerId);
-    if (stopState.stopped) {
-        throw new AppError("merge_worker_stopped", "Stopped or stopping merge worker cannot claim another merge job", 1, {
-            worker_id: input.workerId,
-            status: stopState.status,
-            reason: stopState.reason
-        });
-    }
-    requireLaneLockOwner(context, {
-        projectRoot: project.root,
-        lane: "merge",
-        workerId: input.workerId,
-        workspacePath: input.workspacePath
-    });
+    requireMergeText(input.protocolId, "protocol-id");
+    const { project } = prepareMergeClaim(context, input);
     const now = context.now();
     context.db.beginWriteTransaction();
     try {
-        const job = queueJobByProtocol(context, project.id, input.protocolId);
-        if (!job || !["ready", "requeued"].includes(job.status)) {
-            throw new AppError("merge_job_not_claimable", "Requested merge job is not ready to claim", 1, {
-                protocol_id: input.protocolId,
-                status: job?.status ?? "missing",
-                allowed: ["ready", "requeued"]
-            });
-        }
+        const prepared = prepareMergeClaim(context, input);
+        const job = prepared.job;
+        const transition = prepared.transition;
         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]);
@@ -112,7 +105,7 @@ export function claimMergeJob(context, input) {
             eventType: "merge_queue.claimed",
             payload: { protocol_id: job.protocol_id, worker_id: input.workerId, targeted: true }
         });
-        transitionClaimedProtocolToIntegration(context, project.id, job.protocol_id, input.workerId, now);
+        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 });
     }
@@ -121,7 +114,8 @@ export function claimMergeJob(context, input) {
         throw error;
     }
 }
-export function claimMergeBundle(context, input) {
+export function prepareMergeBundleClaim(context, input) {
+    requireMergeText(input.workerId, "worker-id");
     const { project, protocolIds } = requireClaimableBranchBundle(context, {
         projectRoot: input.projectRoot,
         workspacePath: input.workspacePath
@@ -140,9 +134,16 @@ export function claimMergeBundle(context, input) {
         workerId: input.workerId,
         workspacePath: input.workspacePath
     });
+    const transitions = protocolIds.map((protocolId) => prepareClaimedProtocolTransition(context, project.id, protocolId));
+    return { project, protocolIds, transitions };
+}
+export function claimMergeBundle(context, input) {
+    const { project, protocolIds } = prepareMergeBundleClaim(context, input);
     const now = context.now();
     context.db.beginWriteTransaction();
     try {
+        const transitions = protocolIds.map((protocolId) => prepareClaimedProtocolTransition(context, project.id, protocolId));
+        // Claim every queue row before publishing any filesystem state.
         for (const protocolId of protocolIds) {
             const update = context.db.run(`UPDATE merge_queue
          SET status = 'claimed', claimed_by_session_id = ?, claimed_at = ?, updated_at = ?
@@ -153,7 +154,10 @@ export function claimMergeBundle(context, input) {
                     protocol_ids: protocolIds
                 });
             }
-            transitionClaimedProtocolToIntegration(context, project.id, protocolId, input.workerId, now);
+        }
+        for (const transition of transitions) {
+            const protocolId = transition.protocol.id;
+            transitionClaimedProtocolToIntegration(context, transition, input.workerId, now);
             appendAudit(context, {
                 protocolId,
                 projectId: project.id,
@@ -182,22 +186,38 @@ export function claimMergeBundle(context, input) {
         protocolIds
     });
 }
-export async function waitNextMergeJob(context, input) {
+export function prepareMergeQueueWait(context, input) {
+    requireMergeText(input.workerId, "worker-id");
+    if (typeof input.acquireLock !== "boolean")
+        throw new AppError("validation", "acquire-lock must be boolean", 2);
+    const { timeoutSeconds, pollIntervalSeconds } = prepareLaneWaitTiming(input);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const timeoutSeconds = input.timeoutSeconds ?? 0;
-    const pollIntervalSeconds = input.pollIntervalSeconds ?? 10;
-    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 0) {
-        throw new AppError("validation", "--timeout must be zero or a positive number", 2);
-    }
-    if (!Number.isFinite(pollIntervalSeconds) || pollIntervalSeconds <= 0) {
-        throw new AppError("validation", "--poll-interval must be a positive number", 2);
-    }
     if (input.acquireLock && pollIntervalSeconds >= mergeLockTtlSeconds) {
         throw new AppError("validation", "--poll-interval must be lower than the merge lock TTL when --acquire-lock true", 2, {
             lock_ttl_seconds: mergeLockTtlSeconds
         });
     }
     const initialStopState = stoppedMergeWorkerState(context, project.id, input.workerId);
+    if (!initialStopState.stopped) {
+        const next = context.db.get("SELECT * FROM merge_queue WHERE project_id = ? AND status IN ('ready', 'requeued') ORDER BY created_at ASC, id ASC LIMIT 1", [project.id]);
+        if (next)
+            prepareClaimedProtocolTransition(context, project.id, next.protocol_id);
+        if (input.acquireLock) {
+            if (laneRecord(context, project.id, "merge")) {
+                prepareLaneLock(context, { ...input, lane: "merge", reason: "merge queue wait-next", ttlSeconds: mergeLockTtlSeconds }, "wait-acquire");
+            }
+            else {
+                prepareLaneWorkspace(context, { ...input, lane: "merge" });
+            }
+        }
+        else {
+            requireLaneLockOwner(context, { ...input, lane: "merge" });
+        }
+    }
+    return { project, timeoutSeconds, pollIntervalSeconds, initialStopState };
+}
+export async function waitNextMergeJob(context, input) {
+    const { project, timeoutSeconds, pollIntervalSeconds, initialStopState } = prepareMergeQueueWait(context, input);
     if (initialStopState.stopped) {
         return mergeQueueResult(null, {
             ok: true,
@@ -325,7 +345,9 @@ export async function waitNextMergeJob(context, input) {
         await delay(pollIntervalSeconds * 1000);
     }
 }
-export function completeMergeJob(context, input) {
+export function prepareMergeJobCompletion(context, input) {
+    requireMergeText(input.summary, "summary");
+    requireMergeText(input.workerId, "worker-id");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const protocol = requireProtocol(context, input.protocolId, project.id);
     const job = requireClaimedJob(context, protocol.project_id, input.protocolId, input.workerId);
@@ -335,14 +357,18 @@ export function completeMergeJob(context, input) {
         workerId: input.workerId,
         workspacePath: input.workspacePath
     });
-    const now = context.now();
-    context.db.run(`UPDATE merge_queue
-     SET status = 'merged', last_reason = ?, completed_at = ?, updated_at = ?
-     WHERE id = ?`, [input.summary, now, now, job.id]);
     const state = readProtocolRuntimeState(context, protocol).state;
     const flowContract = flowContractForState(state);
     const targetStage = flowContract.merge_queue.complete.target_stage;
     const targetStatus = flowContract.stages[targetStage]?.terminal ? targetStage : "running";
+    return { protocol, job, state, flowContract, targetStage, targetStatus };
+}
+export function completeMergeJob(context, input) {
+    const { protocol, job, state, flowContract, targetStage, targetStatus } = prepareMergeJobCompletion(context, input);
+    const now = context.now();
+    context.db.run(`UPDATE merge_queue
+     SET status = 'merged', last_reason = ?, completed_at = ?, updated_at = ?
+     WHERE id = ?`, [input.summary, now, now, job.id]);
     persistProtocolState(context, protocol, {
         ...state,
         stage: targetStage,
@@ -365,7 +391,9 @@ export function completeMergeJob(context, input) {
         stop_after_current
     });
 }
-export function completeMergeBundle(context, input) {
+export function prepareMergeBundleCompletion(context, input) {
+    requireMergeText(input.summary, "summary");
+    requireMergeText(input.workerId, "worker-id");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     requireLaneLockOwner(context, {
         projectRoot: project.root,
@@ -380,19 +408,22 @@ export function completeMergeBundle(context, input) {
             workspace_path: input.workspacePath
         });
     }
+    const jobs = protocolIds.map((protocolId) => prepareMergeJobCompletion(context, { ...input, protocolId }));
+    return { project, protocolIds, jobs };
+}
+export function completeMergeBundle(context, input) {
+    prepareMergeBundleCompletion(context, input);
     const now = context.now();
+    let prepared;
     context.db.beginWriteTransaction();
     try {
-        for (const protocolId of protocolIds) {
-            const protocol = requireProtocol(context, protocolId, project.id);
-            const job = requireClaimedJob(context, project.id, protocolId, input.workerId);
+        prepared = prepareMergeBundleCompletion(context, input);
+        const { project, protocolIds, jobs } = prepared;
+        for (const { protocol, job, state, flowContract, targetStage, targetStatus } of jobs) {
+            const protocolId = protocol.id;
             context.db.run(`UPDATE merge_queue
          SET status = 'merged', last_reason = ?, completed_at = ?, updated_at = ?
          WHERE id = ?`, [input.summary, now, now, job.id]);
-            const state = readProtocolRuntimeState(context, protocol).state;
-            const flowContract = flowContractForState(state);
-            const targetStage = flowContract.merge_queue.complete.target_stage;
-            const targetStatus = flowContract.stages[targetStage]?.terminal ? targetStage : "running";
             persistProtocolState(context, protocol, {
                 ...state,
                 stage: targetStage,
@@ -418,6 +449,7 @@ export function completeMergeBundle(context, input) {
         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, {
         ok: true,
@@ -430,7 +462,9 @@ export function completeMergeBundle(context, input) {
         stop_after_current
     });
 }
-export function noteMergeJob(context, input) {
+export function prepareMergeJobNote(context, input) {
+    requireMergeText(input.summary, "summary");
+    requireMergeText(input.workerId, "worker-id");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const protocol = requireProtocol(context, input.protocolId, project.id);
     const job = queueJobByProtocol(context, protocol.project_id, protocol.id);
@@ -449,6 +483,10 @@ export function noteMergeJob(context, input) {
             claimed_by_session_id: job.claimed_by_session_id
         });
     }
+    return { protocol, job };
+}
+export function noteMergeJob(context, input) {
+    const { protocol, job } = prepareMergeJobNote(context, input);
     const now = context.now();
     context.db.run(`UPDATE merge_queue
      SET last_reason = ?, updated_at = ?
@@ -461,7 +499,11 @@ export function noteMergeJob(context, input) {
     });
     return mergeQueueResult(queueJobByProtocol(context, protocol.project_id, protocol.id), { ok: true, outcome: "noted" });
 }
-export function failMergeJob(context, input) {
+export function prepareMergeJobFailure(context, input) {
+    requireMergeText(input.reason, "reason");
+    requireMergeText(input.workerId, "worker-id");
+    if (typeof input.requeue !== "boolean")
+        throw new AppError("validation", "requeue must be boolean", 2);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const protocol = requireProtocol(context, input.protocolId, project.id);
     const job = requireClaimedJob(context, protocol.project_id, input.protocolId, input.workerId);
@@ -471,13 +513,17 @@ export function failMergeJob(context, input) {
         workerId: input.workerId,
         workspacePath: input.workspacePath
     });
+    const state = input.requeue ? readProtocolRuntimeState(context, protocol).state : null;
+    return { protocol, job, state };
+}
+export function failMergeJob(context, input) {
+    const { protocol, job, state } = prepareMergeJobFailure(context, input);
     const now = context.now();
     const status = input.requeue ? "requeued" : "failed";
     context.db.run(`UPDATE merge_queue
      SET status = ?, attempts_count = attempts_count + 1, last_reason = ?, updated_at = ?
      WHERE id = ?`, [status, input.reason, now, job.id]);
-    if (input.requeue) {
-        const state = readProtocolRuntimeState(context, protocol).state;
+    if (state) {
         persistProtocolState(context, protocol, {
             ...state,
             stage: "ready_for_merge",
@@ -500,7 +546,11 @@ export function failMergeJob(context, input) {
         stop_after_current
     });
 }
-export function failMergeBundle(context, input) {
+export function prepareMergeBundleFailure(context, input) {
+    requireMergeText(input.reason, "reason");
+    requireMergeText(input.workerId, "worker-id");
+    if (typeof input.requeue !== "boolean")
+        throw new AppError("validation", "requeue must be boolean", 2);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     requireLaneLockOwner(context, {
         projectRoot: project.root,
@@ -515,18 +565,24 @@ export function failMergeBundle(context, input) {
             workspace_path: input.workspacePath
         });
     }
+    const jobs = protocolIds.map((protocolId) => prepareMergeJobFailure(context, { ...input, protocolId }));
+    return { project, protocolIds, jobs };
+}
+export function failMergeBundle(context, input) {
+    prepareMergeBundleFailure(context, input);
     const now = context.now();
     const status = input.requeue ? "requeued" : "failed";
+    let prepared;
     context.db.beginWriteTransaction();
     try {
-        for (const protocolId of protocolIds) {
-            const protocol = requireProtocol(context, protocolId, project.id);
-            const job = requireClaimedJob(context, project.id, protocolId, input.workerId);
+        prepared = prepareMergeBundleFailure(context, input);
+        const { project, protocolIds, jobs } = prepared;
+        for (const { protocol, job, state } of jobs) {
+            const protocolId = protocol.id;
             context.db.run(`UPDATE merge_queue
          SET status = ?, attempts_count = attempts_count + 1, last_reason = ?, updated_at = ?
          WHERE id = ?`, [status, input.reason, now, job.id]);
-            if (input.requeue) {
-                const state = readProtocolRuntimeState(context, protocol).state;
+            if (state) {
                 persistProtocolState(context, protocol, {
                     ...state,
                     stage: "ready_for_merge",
@@ -555,6 +611,7 @@ export function failMergeBundle(context, input) {
         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, {
         ok: true,
@@ -566,47 +623,57 @@ export function failMergeBundle(context, input) {
         stop_after_current
     });
 }
-export function cancelMergeQueueJob(context, input) {
+export function prepareMergeQueueCancellation(context, input) {
+    requireMergeText(input.reason, "reason");
+    if (input.workerId !== undefined)
+        requireMergeText(input.workerId, "worker-id");
+    if (typeof input.force !== "boolean")
+        throw new AppError("validation", "force must be boolean", 2);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const protocol = requireProtocol(context, input.protocolId, project.id);
     const reason = input.reason.trim();
-    if (!reason) {
-        throw new AppError("validation", "merge-queue cancel requires --reason", 2);
+    const job = queueJobByProtocol(context, protocol.project_id, protocol.id);
+    if (!job) {
+        throw new AppError("not_found", "Merge queue job is not found", 1, { protocol_id: protocol.id });
+    }
+    if (job.status === "cancelled") {
+        return { protocol, job, reason };
+    }
+    if (job.status === "claimed" && !input.force) {
+        if (!input.workerId) {
+            throw new AppError("merge_job_claimed", "Claimed jobs require --worker-id or --force", 1, { protocol_id: protocol.id });
+        }
+        if (job.claimed_by_session_id !== input.workerId) {
+            throw new AppError("merge_job_claimed_by_other_session", "Merge job is claimed by another worker", 1, {
+                protocol_id: protocol.id,
+                claimed_by_session_id: job.claimed_by_session_id
+            });
+        }
+        requireLaneLockOwner(context, {
+            projectRoot: protocol.project_root,
+            lane: "merge",
+            workerId: input.workerId,
+            workspacePath: input.workspacePath
+        });
+    }
+    if (["merged", "failed"].includes(job.status) && !input.force) {
+        throw new AppError("merge_job_terminal", `Merge job is ${job.status}; cancellation requires --force --reason`, 1, {
+            protocol_id: protocol.id,
+            status: job.status
+        });
     }
+    return { protocol, job, reason };
+}
+export function cancelMergeQueueJob(context, input) {
+    const { protocol } = prepareMergeQueueCancellation(context, input);
     const now = context.now();
     context.db.beginWriteTransaction();
     try {
-        const job = queueJobByProtocol(context, protocol.project_id, protocol.id);
-        if (!job) {
-            throw new AppError("not_found", "Merge queue job is not found", 1, { protocol_id: protocol.id });
-        }
+        const { job, reason } = prepareMergeQueueCancellation(context, input);
         if (job.status === "cancelled") {
             context.db.exec("COMMIT");
             return mergeQueueResult(job, { ok: true, outcome: "cancelled", cancelled: false, reason: "already_cancelled" });
         }
-        if (job.status === "claimed" && !input.force) {
-            if (!input.workerId) {
-                throw new AppError("merge_job_claimed", "Claimed jobs require --worker-id or --force", 1, { protocol_id: protocol.id });
-            }
-            if (job.claimed_by_session_id !== input.workerId) {
-                throw new AppError("merge_job_claimed_by_other_session", "Merge job is claimed by another worker", 1, {
-                    protocol_id: protocol.id,
-                    claimed_by_session_id: job.claimed_by_session_id
-                });
-            }
-            requireLaneLockOwner(context, {
-                projectRoot: protocol.project_root,
-                lane: "merge",
-                workerId: input.workerId,
-                workspacePath: input.workspacePath
-            });
-        }
-        if (["merged", "failed"].includes(job.status) && !input.force) {
-            throw new AppError("merge_job_terminal", `Merge job is ${job.status}; cancellation requires --force --reason`, 1, {
-                protocol_id: protocol.id,
-                status: job.status
-            });
-        }
         context.db.run(`UPDATE merge_queue
        SET status = 'cancelled', last_reason = ?, updated_at = ?
        WHERE id = ?`, [reason, now, job.id]);
@@ -629,6 +696,10 @@ export function cancelMergeQueueJob(context, input) {
 export function queueForProject(context, projectId) {
     return context.db.all(`SELECT * FROM merge_queue WHERE project_id = ? ORDER BY created_at ASC, id ASC`, [projectId]);
 }
+function requireMergeText(value, parameter) {
+    if (typeof value !== "string" || !value.trim())
+        throw new AppError("validation", `--${parameter} must be nonempty text`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter });
+}
 function queueJobByProtocol(context, projectId, protocolId) {
     return context.db.get("SELECT * FROM merge_queue WHERE project_id = ? AND protocol_id = ?", [projectId, protocolId]);
 }
@@ -688,7 +759,7 @@ function requireClaimedJob(context, projectId, protocolId, sessionId) {
     }
     return job;
 }
-function transitionClaimedProtocolToIntegration(context, projectId, protocolId, workerId, now) {
+function prepareClaimedProtocolTransition(context, projectId, protocolId) {
     const protocol = requireProtocol(context, protocolId, projectId);
     const state = readProtocolRuntimeState(context, protocol).state;
     const flowContract = flowContractForState(state);
@@ -707,6 +778,10 @@ function transitionClaimedProtocolToIntegration(context, projectId, protocolId,
             diagnostics: blockingDiagnostics
         });
     }
+    return { protocol, state, flowContract };
+}
+function transitionClaimedProtocolToIntegration(context, prepared, workerId, now) {
+    const { protocol, state, flowContract } = prepared;
     persistProtocolState(context, protocol, {
         ...state,
         stage: "integration",
@@ -715,10 +790,10 @@ function transitionClaimedProtocolToIntegration(context, projectId, protocolId,
         updated_at: now
     });
     appendAudit(context, {
-        protocolId,
+        protocolId: protocol.id,
         projectId: protocol.project_id,
         eventType: "protocol.integration_claimed",
-        payload: { protocol_id: protocolId, worker_id: workerId, flow_contract_id: flowContract.id }
+        payload: { protocol_id: protocol.id, worker_id: workerId, flow_contract_id: flowContract.id }
     });
 }
 function releaseLaneLockIfOwned(context, input) {

package/dist/services/migrations.js

@@ -10,6 +10,7 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { classifyCliOperation } from "./cli-operation-classifier.js";
 import { compatibilityContexts, selectEngine } from "./engines.js";
 import { getCliBuildInfo } from "./build-info.js";
+import { prepareJsonFile } from "../cli/input-preparation.js";
 export function assessMigrationImpact(context, input) {
     const root = resolveStatusProjectRoot({ requestedRoot: input.projectRoot, cwd: process.cwd() });
     if (!root.root)
@@ -147,7 +148,7 @@ export function planMigration(context, input) {
         }
     };
 }
-export function applyMigration(context, input) {
+export function prepareMigrationApply(context, input) {
     const classification = input.classification ?? classifyCliOperation(["migration", "apply"], context.env);
     if (classification.mode !== "mb_upgrade") {
         throw new AppError("upgrade_authorization_required", "Migration apply requires explicit mb-upgrade authorization", 1, {
@@ -197,6 +198,13 @@ export function applyMigration(context, input) {
         });
     }
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const current = activeStateSummary(context, project.id);
+    if (activeStateBlockers(current).length)
+        throw new AppError("migration_active_state", "Migration apply requires a quiescent shared home", 1, { active_state: current });
+    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");
     const already = writeDb.get("SELECT value_json FROM runtime_config WHERE key = ?", [applyKey(project.id, sourceVersion, targetVersion)]);
     if (already) {
@@ -218,6 +226,9 @@ export function applyMigration(context, input) {
     };
     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");
     }
@@ -513,13 +524,7 @@ function activeStateBlockers(active) {
     return blockers;
 }
 function readJsonObject(filePath) {
-    let parsed;
-    try {
-        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
-    }
-    catch (error) {
-        throw new AppError("invalid_json", `Cannot read migration report: ${filePath}`, 2, { cause: String(error) });
-    }
+    const { value: parsed } = prepareJsonFile(filePath, "Migration report");
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new AppError("validation", "Migration report must be a JSON object", 2, { file: filePath });
     }

package/dist/services/plan-runtime.js

@@ -6,17 +6,23 @@ import { parseJsonObject } from "../shared/json.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
 export function readCanonicalPlan(planPath, protocolId) {
     if (!fs.existsSync(planPath) || !fs.statSync(planPath).isFile()) {
-        throw new AppError("not_found", `Canonical protocol plan is missing: ${planPath}`, 1, { plan_path: planPath });
+        throw new AppError("runtime_artifact_missing", `Canonical protocol plan is missing: ${planPath}`, 1, { plan_path: planPath });
     }
     const raw = fs.readFileSync(planPath, "utf8");
-    const value = parseJsonObject(raw, planPath);
-    const plan = validatePlan(value, protocolId);
-    const revisionValue = value.revision;
-    const revision = typeof revisionValue === "number" && Number.isInteger(revisionValue) && revisionValue > 0 ? revisionValue : 1;
-    return { plan, raw, sha256: crypto.createHash("sha256").update(raw).digest("hex"), revision };
+    try {
+        const value = parseJsonObject(raw, planPath);
+        const plan = validatePlan(value, protocolId);
+        const revisionValue = value.revision;
+        const revision = typeof revisionValue === "number" && Number.isInteger(revisionValue) && revisionValue > 0 ? revisionValue : 1;
+        return { plan, raw, sha256: crypto.createHash("sha256").update(raw).digest("hex"), revision };
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "validation")
+            throw error;
+        throw new AppError("runtime_artifact_invalid", "Canonical protocol plan is invalid", 1, { plan_path: planPath, cause_code: error.code });
+    }
 }
-export function boundCanonicalPlan(context, input) {
-    const canonical = readCanonicalPlan(input.planPath, input.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]);
     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, {
@@ -28,6 +34,11 @@ export function boundCanonicalPlan(context, input) {
             plan_path: input.planPath
         });
     }
+    return canonical;
+}
+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 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)