@deksden-com/dd-flow-cli 0.5.0 → 0.7.0

package/dist/services/hooks.js

@@ -107,15 +107,11 @@ export function getCodexHomeStatus(context, input) {
     const configStatus = managedConfigStatus(record);
     const hooksStatus = hookFileStatus(record.hooks_path, project.root);
     const drift = configStatus.drift_status === "none" && hooksStatus.drift_status === "none" ? "none" : "drifted";
-    const now = context.now();
-    context.db.run(`UPDATE codex_home_profiles
-     SET last_checked_at = ?, last_drift_status = ?, updated_at = ?
-     WHERE project_id = ? AND profile = ?`, [now, drift, now, project.id, profile]);
     return {
         ok: true,
         installed: fs.existsSync(record.target_home),
         profile,
-        home: homeProfile(context, project.id, profile),
+        home: { ...record, last_drift_status: drift },
         config: configStatus,
         hooks: hooksStatus,
         shared_entries: sharedEntryStatus(record.source_home, record.target_home)
@@ -196,7 +192,7 @@ export function getCodexHooksStatus(context, input) {
         };
     }
     const status = hookFileStatus(location.hooksPath, project.root);
-    const recorded = hookInstallation(context, project.id, installationScope(target, location.profile));
+    const recorded = hookInstallation(context, project.id, installationScope(target, location.profile, location.hooksPath));
     const driftStatus = status.installed ? "none" : recorded?.installed === 1 ? "drifted" : status.drift_status;
     return {
         ok: true,
@@ -224,7 +220,7 @@ export function installCodexHooks(context, input) {
     const nextConfig = mergeHooksConfig(existing, project.root);
     ensureDir(path.dirname(location.hooksPath));
     writeJsonFile(location.hooksPath, nextConfig);
-    recordHookInstallation(context, project.id, installationScope(target, location.profile), location.hooksPath, true, "none");
+    recordHookInstallation(context, project.id, installationScope(target, location.profile, location.hooksPath), location.hooksPath, true, "none");
     appendAudit(context, {
         projectId: project.id,
         eventType: "codex_hooks.installed",
@@ -256,7 +252,7 @@ export function removeCodexHooks(context, input) {
     const nextConfig = removeManagedHooks(existing, project.root);
     ensureDir(path.dirname(location.hooksPath));
     writeJsonFile(location.hooksPath, nextConfig);
-    recordHookInstallation(context, project.id, installationScope(target, location.profile), location.hooksPath, false, "not_installed");
+    recordHookInstallation(context, project.id, installationScope(target, location.profile, location.hooksPath), location.hooksPath, false, "not_installed");
     appendAudit(context, {
         projectId: project.id,
         eventType: "codex_hooks.removed",
@@ -277,13 +273,16 @@ export function handleCodexHook(context, input) {
     if (!command)
         return { ok: true, observed: false, reason: "non_bash_tool" };
     const flowPayload = flowSessionPayloadFromRegisterCommand(command);
-    if (!flowPayload)
+    const bootstrapStageStart = /\bdd-flow\s+stage\s+start\b/.test(command) && /(?:^|\s)--bootstrap(?:\s|$)/.test(command);
+    if (!flowPayload && !bootstrapStageStart)
         return { ok: true, observed: false, reason: "event_not_participating", event: eventName };
     const project = projectForHook(context, input.projectRoot, stringValue(payload.cwd));
     if (!project)
         return { ok: true, observed: false, reason: "unrelated_cwd" };
     const binding = sessionId ? upsertSessionBindingFromPayload(context, project, sessionId, payload) : undefined;
-    const observedSession = bindObservedFlowSession(context, project, flowPayload, sessionId ?? flowPayload.session_id ?? undefined);
+    const observedSession = flowPayload
+        ? bindObservedFlowSession(context, project, flowPayload, sessionId ?? flowPayload.session_id ?? undefined)
+        : undefined;
     const effectiveSessionId = observedSession?.session_id ?? sessionId ?? null;
     const protocolId = observedSession?.protocol_id ?? binding?.protocol_id ?? null;
     const eventKey = hookEventKey(payload, eventName, toolName, command);
@@ -315,9 +314,23 @@ export function handleCodexHook(context, input) {
         duplicate: !inserted,
         event_key: eventKey,
         session_id: effectiveSessionId,
-        protocol_id: protocolId
+        protocol_id: protocolId,
+        ...(sessionId
+            ? {
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "allow",
+                    updatedInput: { command: commandWithSessionId(command, sessionId) }
+                }
+            }
+            : {})
     };
 }
+function commandWithSessionId(command, sessionId) {
+    if (/(?:^|\s)--session-id(?:=|\s)/.test(command))
+        return command;
+    return `${command} --session-id ${JSON.stringify(sessionId)}`;
+}
 export function hookStatusForProject(context, projectId) {
     return context.db.all(`SELECT scope, config_path, content_hash, installed, drift_status, updated_at
      FROM hook_installations WHERE project_id = ? ORDER BY updated_at DESC`, [projectId]);
@@ -460,7 +473,7 @@ function commandHook(command, statusMessage) {
     return { type: "command", command, timeout: 5, statusMessage };
 }
 function hookCommand(event) {
-    return `dd-flow codex hook handle --event ${event} --json`;
+    return `PATH="\${HOME}/Library/pnpm:/opt/homebrew/bin:/usr/local/bin:\${PATH}" dd-flow codex hook handle --event ${event} --json`;
 }
 function resolveHookTarget(target) {
     if (!target || target === "isolated") {
@@ -632,8 +645,8 @@ function recordHookInstallation(context, projectId, scope, configPath, installed
        drift_status = excluded.drift_status,
        updated_at = excluded.updated_at`, [projectId, scope, configPath, hashObject(readJsonIfExists(configPath) ?? {}), installed ? 1 : 0, driftStatus, now, now]);
 }
-function installationScope(target, profile) {
-    return target === "isolated" ? `isolated:${profile}` : "default";
+function installationScope(target, profile, hooksPath) {
+    return target === "isolated" ? `isolated:${profile}` : `default:${path.dirname(hooksPath)}`;
 }
 function upsertSessionBindingFromPayload(context, project, sessionId, payload) {
     const existing = sessionBinding(context, project.id, sessionId);
@@ -688,7 +701,7 @@ function projectForHook(context, explicitRoot, cwd) {
         .sort((left, right) => right.root.length - left.root.length)[0];
 }
 function hookEventKey(payload, eventName, toolName, command) {
-    const explicit = stringValue(payload.event_id) ?? stringValue(payload.delivery_id) ?? stringValue(payload.id);
+    const explicit = stringValue(payload.tool_use_id) ?? stringValue(payload.event_id) ?? stringValue(payload.delivery_id) ?? stringValue(payload.id);
     if (explicit)
         return explicit;
     return crypto.createHash("sha256").update(JSON.stringify({

package/dist/services/lanes.js

@@ -10,8 +10,6 @@ const defaultTtlSeconds = 300;
 const defaultPollIntervalSeconds = 10;
 export function getLaneStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    expireStaleLocks(context, project.id);
-    expireStaleWaiters(context, project.id);
     return {
         ok: true,
         lanes: lanesForProject(context, project.id, input.lane),
@@ -179,8 +177,6 @@ export async function waitForLaneLock(context, input) {
 }
 export function getLaneWaiters(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    expireStaleLocks(context, project.id);
-    expireStaleWaiters(context, project.id);
     return {
         ok: true,
         lane: input.lane ? normalizeLane(input.lane) : null,

package/dist/services/merge-queue.js

@@ -73,6 +73,54 @@ export function claimNextMergeJob(context, input) {
         claimed: Boolean(claimedProtocolId)
     });
 }
+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
+    });
+    const now = context.now();
+    context.db.exec("BEGIN IMMEDIATE");
+    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 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) {
+            throw new AppError("merge_job_claim_race", "Requested merge job changed while claiming", 1, { protocol_id: input.protocolId });
+        }
+        appendAudit(context, {
+            protocolId: job.protocol_id,
+            projectId: project.id,
+            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);
+        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 claimMergeBundle(context, input) {
     const { project, protocolIds } = requireClaimableBranchBundle(context, {
         projectRoot: input.projectRoot,

package/dist/services/merge-worker.js

@@ -1,7 +1,7 @@
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
-import { ensureLaneWorkspace, acquireLaneLock, releaseLaneLock, expireProjectLaneLocks } from "./lanes.js";
+import { ensureLaneWorkspace, acquireLaneLock, releaseLaneLock } from "./lanes.js";
 import { claimNextMergeJob, queueForProject } from "./merge-queue.js";
 import { requireProjectByRoot } from "./projects.js";
 import { buildStaticFlowGuidance } from "./flow-guidance.js";
@@ -175,15 +175,14 @@ function withJobGuidance(context, job) {
     }
 }
 function detectMergeWorkerState(context, projectId) {
-    expireProjectLaneLocks(context, projectId);
     const workers = activeMergeWorkerSessions(context, projectId);
     const workerIds = [...new Set(workers.map((worker) => worker.worker_id).filter((value) => Boolean(value)))];
     const claimed = context.db.all(`SELECT protocol_id, claimed_by_session_id, status, updated_at FROM merge_queue
      WHERE project_id = ? AND status = 'claimed'
      ORDER BY updated_at DESC, id DESC`, [projectId]);
     const lock = context.db.get(`SELECT worker_id, status, expires_at, reason FROM lane_locks
-     WHERE project_id = ? AND lane = 'merge' AND status = 'active'
-     ORDER BY updated_at DESC, id DESC LIMIT 1`, [projectId]);
+     WHERE project_id = ? AND lane = 'merge' AND status = 'active' AND expires_at > ?
+     ORDER BY updated_at DESC, id DESC LIMIT 1`, [projectId, context.now()]);
     if (workerIds.length > 1) {
         return { state: "blocked", reason: "multiple_active_merge_workers", workers };
     }

package/dist/services/migrations.js

@@ -1,9 +1,15 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
 import { AppError } from "../shared/errors.js";
 import { requireProjectByRoot } from "./projects.js";
 import { getProjectVersionStatus, resolveStatusProjectRoot } from "./version-status.js";
 import { resolveCanonRoot } from "./canon.js";
+import { getDatabase } from "../storage/database.js";
+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";
 export function assessMigrationImpact(context, input) {
     const root = resolveStatusProjectRoot({ requestedRoot: input.projectRoot, cwd: process.cwd() });
     if (!root.root)
@@ -78,14 +84,19 @@ export function planMigration(context, input) {
         rootSource: rootResolution.root_source
     });
     const sourceVersion = input.sourceVersion ?? versionStatus?.memory_bank.version ?? "unknown";
-    const targetVersion = input.targetVersion ?? versionStatus?.memory_bank.version ?? "unknown";
-    const chain = adjacentMigrationChain(sourceVersion, targetVersion);
+    const targetVersion = input.targetVersion ?? upgradeCanon(context).canon?.version ?? versionStatus?.memory_bank.version ?? "unknown";
+    const canon = upgradeCanon(context);
+    const impacts = canon.canon ? readImpacts(path.join(canon.canon.memorybank_root, "release-impact")) : [];
+    const chain = adjacentMigrationChain(sourceVersion, targetVersion, impacts);
     const activeState = activeStateSummary(context, project.id);
     const backup = backupEvidence(input);
+    const engine = migrationEngineEvidence(context, rootResolution.root, targetVersion, input.classification);
     const blockers = [
         ...(chain.status === "unsupported" ? [`unsupported migration path: ${chain.reason}`] : []),
-        ...(backup.status === "missing" ? ["backup evidence is required before runtime/home migration"] : []),
-        ...(input.allowActive ? [] : activeStateBlockers(activeState))
+        ...(backup.status !== "present" ? ["verified backup evidence is required before runtime/home migration"] : []),
+        ...(engine.target_canon_version !== targetVersion ? ["migration target version does not match the resolved target canon version"] : []),
+        ...(engine.target_engine_available !== "selected" ? ["target upgrade engine is not selected"] : []),
+        ...activeStateBlockers(activeState)
     ];
     const status = blockers.length > 0 ? "blocked" : chain.steps.length === 0 ? "noop" : "ready";
     return {
@@ -110,12 +121,7 @@ export function planMigration(context, input) {
             chain: chain.steps,
             blocked_reasons: blockers
         },
-        engine: {
-            router_version: null,
-            selected_engine_version: null,
-            source_engine_available: "unknown",
-            target_engine_available: "unknown"
-        },
+        engine,
         backup,
         active_state: activeState,
         primary_data: [
@@ -141,35 +147,134 @@ export function planMigration(context, input) {
         }
     };
 }
+export function applyMigration(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, {
+            required_marker: "DD_FLOW_COMPATIBILITY_MODE=mb-upgrade"
+        });
+    }
+    const report = input.reportFile
+        ? readJsonObject(path.resolve(input.reportFile))
+        : planMigration(context, input);
+    const reportFile = input.reportFile ? path.resolve(input.reportFile) : null;
+    const reportValidation = validateMigrationReportObject(report);
+    if (reportValidation.errors.length > 0) {
+        throw new AppError("migration_report_invalid", "Migration report is not acceptable for apply", 2, { errors: reportValidation.errors, file: reportFile });
+    }
+    const migration = recordValue(report.migration);
+    const backup = recordValue(report.backup);
+    const activeState = recordValue(report.active_state);
+    const blockers = Array.isArray(migration?.blocked_reasons) ? migration.blocked_reasons.map(String) : [];
+    if (blockers.length > 0 || stringValue(migration?.status) === "blocked") {
+        throw new AppError("migration_blocked", "Migration apply is blocked by its verified report", 1, { blockers, file: reportFile });
+    }
+    const backupPath = stringValue(backup?.path);
+    const verifiedBackup = backupPath ? verifyBackupFile(backupPath) : null;
+    if (!verifiedBackup) {
+        throw new AppError("backup_invalid", "Migration apply requires a readable, non-empty backup file", 1, { path: backupPath });
+    }
+    if (activeState && hasActiveState(activeState)) {
+        throw new AppError("migration_active_state", "Migration apply requires a quiescent shared home", 1, { active_state: activeState });
+    }
+    const sourceVersion = stringValue(migration?.source_memory_bank_version);
+    const targetVersion = stringValue(migration?.target_memory_bank_version);
+    if (!sourceVersion || !targetVersion)
+        throw new AppError("migration_contract_invalid", "Migration source and target versions are required", 1);
+    const canon = upgradeCanon(context);
+    const impacts = canon.canon ? readImpacts(path.join(canon.canon.memorybank_root, "release-impact")) : [];
+    const chain = adjacentMigrationChain(sourceVersion, targetVersion, impacts);
+    if (chain.status === "unsupported")
+        throw new AppError("migration_chain_invalid", chain.reason ?? "Unsupported migration chain", 1);
+    const expectedEngine = migrationEngineEvidence(context, resolveProjectRoot(input.projectRoot), targetVersion, classification);
+    const reportEngine = recordValue(report.engine);
+    const engineErrors = validateEngineEvidence(reportEngine, expectedEngine, targetVersion);
+    if (engineErrors.length > 0) {
+        throw new AppError("migration_contract_invalid", "Migration report engine contract does not match the pinned upgrade target", 1, {
+            errors: engineErrors,
+            expected: expectedEngine,
+            actual: reportEngine
+        });
+    }
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    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) {
+        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) };
+    }
+    const result = {
+        status: "applied",
+        source_version: sourceVersion,
+        target_version: targetVersion,
+        contract: {
+            flow_kind: "mb-upgrade",
+            mode: "mb-upgrade-only",
+            adjacent_only: true
+        },
+        engine: reportEngine,
+        applied_at: context.now(),
+        backup: verifiedBackup,
+        chain: chain.steps.map((step) => ({ ...step, status: "applied" }))
+    };
+    try {
+        writeDb.exec("BEGIN IMMEDIATE");
+        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");
+    }
+    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",
+                source_version: sourceVersion,
+                target_version: targetVersion,
+                backup: verifiedBackup,
+                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)
+        });
+    }
+    return { ok: true, schema_id: "dd-flow/mb-upgrade-migration-apply@1", status: "applied", changed: true, backup: verifiedBackup, recovery: result };
+}
+export function assertUpgradeRunStorageReady(context, projectRoot) {
+    const project = context.db.get("SELECT id FROM projects WHERE root = ?", [resolveProjectRoot(projectRoot)]);
+    if (!project)
+        throw new AppError("migration_not_applied", "mb-upgrade RUN requires a registered project with explicit migration apply", 1);
+    const status = getProjectVersionStatus({ projectRoot: resolveProjectRoot(projectRoot), rootSource: "explicit" });
+    const target = upgradeCanon(context).canon?.version;
+    const source = status?.memory_bank.version;
+    if (!source || !target)
+        throw new AppError("migration_not_applied", "mb-upgrade RUN requires source and target Memory Bank versions", 1);
+    const applied = context.db.get("SELECT value_json FROM runtime_config WHERE key = ?", [applyKey(project.id, source, target)]);
+    if (!applied)
+        throw new AppError("migration_not_applied", "mb-upgrade RUN requires explicit migration apply before RUN creation", 1, {
+            source_version: source,
+            target_version: target,
+            next_action: "run migration plan, verify and explicit migration apply first"
+        });
+    const value = recordValue(parseJsonValue(applied.value_json));
+    if (!value || !["applied", "verified_noop"].includes(stringValue(value.status) ?? "")) {
+        throw new AppError("migration_not_applied", "mb-upgrade RUN has no successful explicit migration apply evidence", 1, {
+            source_version: source,
+            target_version: target
+        });
+    }
+}
 export function verifyMigrationReport(_context, input) {
     const filePath = path.resolve(input.file);
     const report = readJsonObject(filePath);
+    const validation = validateMigrationReportObject(report);
     const schemaId = stringValue(report.schema_id);
-    if (schemaId !== "dd-flow/mb-upgrade-migration-report@1") {
-        throw new AppError("validation", "Migration report schema_id is not dd-flow/mb-upgrade-migration-report@1", 2, {
-            file: filePath,
-            schema_id: schemaId
-        });
-    }
     const migration = recordValue(report.migration);
     const backup = recordValue(report.backup);
     const chain = Array.isArray(migration?.chain) ? migration.chain : [];
     const backupStatus = stringValue(backup?.status);
     const blockedReasons = Array.isArray(migration?.blocked_reasons) ? migration.blocked_reasons.map(String) : [];
-    const errors = [];
-    if (!migration)
-        errors.push("migration block is required");
-    if (!backup)
-        errors.push("backup block is required");
-    if (backupStatus !== "present" && backupStatus !== "planned")
-        errors.push("backup.status must be present or planned");
-    if (migration?.adjacent_only !== true)
-        errors.push("migration.adjacent_only must be true");
-    if (chain.some((step) => !isAdjacentStep(step)))
-        errors.push("all migration.chain entries must be adjacent steps with from/to/status");
-    if (stringValue(migration?.status) === "ready" && blockedReasons.length > 0) {
-        errors.push("ready migration report must not contain blocked reasons");
-    }
+    const errors = validation.errors;
     if (errors.length > 0) {
         throw new AppError("migration_report_invalid", "Migration report is not acceptable", 2, { file: filePath, errors });
     }
@@ -180,6 +285,7 @@ export function verifyMigrationReport(_context, input) {
         verdict: blockedReasons.length > 0 ? "blocked_report_valid" : "accepted",
         checks: {
             backup: backupStatus,
+            backup_integrity: backupStatus === "present" && stringValue(backup?.path) ? verifyBackupFile(stringValue(backup?.path)) : null,
             adjacent_chain_steps: chain.length,
             blocked_reasons: blockedReasons.length
         }
@@ -191,17 +297,135 @@ function backupEvidence(input) {
             status: "missing",
             path: null,
             created_at: null,
+            size_bytes: null,
+            sha256: null,
             rollback_route: "required before applying runtime/home migration"
         };
     }
+    const file = path.resolve(input.backupPath);
+    const verified = verifyBackupFile(file);
     return {
-        status: fs.existsSync(path.resolve(input.backupPath)) ? "present" : "planned",
-        path: path.resolve(input.backupPath),
-        created_at: input.backupCreatedAt ?? null,
+        status: verified ? "present" : "missing",
+        path: file,
+        created_at: input.backupCreatedAt ?? (verified ? new Date(fs.statSync(file).birthtimeMs).toISOString() : null),
+        size_bytes: verified?.size_bytes ?? null,
+        sha256: verified?.sha256 ?? null,
         rollback_route: "restore backup before retrying migration"
     };
 }
-function adjacentMigrationChain(source, target) {
+function verifyBackupFile(file) {
+    try {
+        const stat = fs.statSync(file);
+        if (!stat.isFile() || stat.size <= 0)
+            return null;
+        return {
+            path: file,
+            size_bytes: stat.size,
+            sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"),
+            created_at: stat.birthtime.toISOString()
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function validateMigrationReportObject(report) {
+    const migration = recordValue(report.migration);
+    const backup = recordValue(report.backup);
+    const chain = Array.isArray(migration?.chain) ? migration.chain : [];
+    const backupStatus = stringValue(backup?.status);
+    const blockedReasons = Array.isArray(migration?.blocked_reasons) ? migration.blocked_reasons.map(String) : [];
+    const errors = [];
+    if (report.schema_id !== "dd-flow/mb-upgrade-migration-report@1")
+        errors.push("schema_id must be dd-flow/mb-upgrade-migration-report@1");
+    if (!migration)
+        errors.push("migration block is required");
+    if (!recordValue(report.engine))
+        errors.push("engine block is required");
+    if (!backup)
+        errors.push("backup block is required");
+    if (backupStatus !== "present")
+        errors.push("backup.status must be present");
+    if (backupStatus === "present") {
+        const backupPath = stringValue(backup?.path);
+        const verified = backupPath ? verifyBackupFile(backupPath) : null;
+        if (!verified)
+            errors.push("backup file must be readable and non-empty");
+        else {
+            if (backup?.size_bytes !== verified.size_bytes)
+                errors.push("backup.size_bytes does not match the verified backup");
+            if (backup?.sha256 !== verified.sha256)
+                errors.push("backup.sha256 does not match the verified backup");
+        }
+    }
+    if (migration?.adjacent_only !== true)
+        errors.push("migration.adjacent_only must be true");
+    if (chain.some((step) => !isAdjacentStep(step)))
+        errors.push("all migration.chain entries must be adjacent steps with from/to/status");
+    const engine = recordValue(report.engine);
+    if (engine && stringValue(migration?.target_memory_bank_version) !== engine.target_canon_version) {
+        errors.push("migration.target_memory_bank_version must match engine.target_canon_version");
+    }
+    if (stringValue(migration?.status) === "ready" && blockedReasons.length > 0)
+        errors.push("ready migration report must not contain blocked reasons");
+    return { errors };
+}
+function migrationEngineEvidence(context, projectRoot, targetVersion, classification) {
+    const env = context.env;
+    const targetClassification = classification ?? classifyCliOperation(["migration", "plan"], env);
+    const current = selectEngine(context, { projectRoot, env }, {}, {
+        mode: "normal_write", operation: "project.current", family: "project", command: "current", action: null
+    });
+    const target = selectEngine(context, { projectRoot, env }, { allowCurrentInProcess: true }, targetClassification);
+    const contexts = compatibilityContexts(context, { projectRoot, env, classification: targetClassification });
+    const targetContext = recordValue(contexts.upgrade_target);
+    const canon = upgradeCanon(context).canon;
+    const targetCanonVersion = canon?.version ?? null;
+    return {
+        router_version: getCliBuildInfo().version,
+        source_engine_version: current.selected?.package_version ?? null,
+        target_engine_version: target.selected?.package_version ?? null,
+        selected_engine_version: target.selected?.package_version ?? null,
+        source_engine_available: current.status,
+        target_engine_available: target.status,
+        target_canon_version: targetCanonVersion,
+        target_canon_commit: canon?.commit ?? null,
+        target_compatibility_sha256: stringValue(targetContext?.canon && recordValue(targetContext.canon)?.compatibility_sha256),
+        effective_engine_version: recordValue(contexts.effective_execution)?.engine_version ?? null
+    };
+}
+function validateEngineEvidence(actual, expected, targetVersion) {
+    const errors = [];
+    if (!actual)
+        return ["engine block is required"];
+    for (const key of ["target_engine_version", "selected_engine_version", "target_canon_version", "target_canon_commit", "target_compatibility_sha256"]) {
+        if (actual[key] !== expected[key])
+            errors.push(`engine.${key} does not match current target assessment`);
+    }
+    if (actual.target_canon_version !== targetVersion)
+        errors.push("engine.target_canon_version must match migration target version");
+    if (actual.target_engine_available !== "selected")
+        errors.push("engine.target_engine_available must be selected");
+    return errors;
+}
+function parseJsonValue(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+function upgradeCanon(context) {
+    return resolveCanonRoot(context, context.env.DD_MEMORYBANK ? { explicitRoot: context.env.DD_MEMORYBANK } : {});
+}
+function hasActiveState(active) {
+    return ["protocols", "runs", "merge_queue", "lane_locks", "lane_waiters", "merge_sessions", "sessions"].some((key) => Array.isArray(active[key]) && active[key].length > 0);
+}
+function applyKey(projectId, source, target) {
+    return `mb-upgrade.apply.${projectId}.${source}.${target}`;
+}
+function adjacentMigrationChain(source, target, impacts = []) {
     if (source === target)
         return { status: "ok", steps: [] };
     const sourceParts = parseSemver(source);
@@ -209,8 +433,38 @@ function adjacentMigrationChain(source, target) {
     if (!sourceParts || !targetParts) {
         return { status: "unsupported", reason: "source or target version is not semver", steps: [] };
     }
+    if (impacts.length > 0) {
+        const steps = [];
+        const visited = new Set();
+        let current = source;
+        while (current !== target) {
+            if (visited.has(current))
+                return { status: "unsupported", reason: "release impact chain contains a cycle", steps: [] };
+            visited.add(current);
+            const impact = impacts.find((item) => item.from_version === current);
+            if (!impact)
+                return { status: "unsupported", reason: `missing adjacent release impact from ${current}`, steps: [] };
+            steps.push({
+                id: `${impact.from_version}-to-${impact.to_version}`,
+                from: impact.from_version,
+                to: impact.to_version,
+                status: "planned",
+                minimum_upgrade_mode: impact.minimum_upgrade_mode,
+                domains: impact.domains,
+                path_migration: impact.path_migration,
+                runtime_migration: impact.runtime_migration,
+                required_checks: impact.required_checks
+            });
+            current = impact.to_version;
+            const next = parseSemver(current);
+            if (!next || compareParts(next, targetParts) > 0) {
+                return { status: "unsupported", reason: `release impact chain overshoots target ${target}`, steps: [] };
+            }
+        }
+        return { status: "ok", steps };
+    }
     if (sourceParts.major !== targetParts.major) {
-        return { status: "unsupported", reason: "major version migration requires explicit future migration units", steps: [] };
+        return { status: "unsupported", reason: "major version migration requires canonical release-impact units", steps: [] };
     }
     if (targetParts.minor < sourceParts.minor || (targetParts.minor === sourceParts.minor && targetParts.patch < sourceParts.patch)) {
         return { status: "unsupported", reason: "downgrade migrations are not supported", steps: [] };
@@ -229,24 +483,33 @@ function adjacentMigrationChain(source, target) {
     }
     return { status: "ok", steps };
 }
-function activeStateSummary(context, projectId) {
+function activeStateSummary(context, _projectId) {
     return {
-        protocols: context.db.all("SELECT id, status, stage FROM protocols WHERE project_id = ? AND status NOT IN ('closed', 'cancelled') ORDER BY updated_at DESC", [projectId]),
-        runs: context.db.all("SELECT id, status, verdict FROM flow_runs WHERE project_id = ? AND status NOT IN ('done', 'cancelled', 'failed') ORDER BY updated_at DESC", [projectId]),
-        merge_queue: context.db.all("SELECT protocol_id, status FROM merge_queue WHERE project_id = ? AND status IN ('ready', 'claimed', 'requeued') ORDER BY updated_at DESC", [projectId]),
-        lane_locks: context.db.all("SELECT lane, worker_id, status FROM lane_locks WHERE project_id = ? AND status = 'active' ORDER BY updated_at DESC", [projectId])
+        protocols: context.db.all("SELECT id, project_id, status, stage FROM protocols WHERE status NOT IN ('closed', 'cancelled') ORDER BY updated_at DESC"),
+        runs: context.db.all("SELECT id, project_id, status, verdict FROM flow_runs WHERE status = 'running' ORDER BY updated_at DESC"),
+        merge_queue: context.db.all("SELECT protocol_id, project_id, status FROM merge_queue WHERE status IN ('ready', 'claimed', 'requeued') ORDER BY updated_at DESC"),
+        lane_locks: context.db.all("SELECT lane, project_id, worker_id, status FROM lane_locks WHERE status = 'active' ORDER BY updated_at DESC"),
+        lane_waiters: context.db.all("SELECT id, lane, project_id, worker_id, status FROM lane_waiters WHERE status = 'queued' ORDER BY queued_at ASC, id ASC"),
+        merge_sessions: context.db.all("SELECT session_id, project_id, status, current_protocol_id FROM merge_sessions WHERE status IN ('starting', 'active', 'stopping') ORDER BY updated_at DESC"),
+        sessions: context.db.all("SELECT session_id, project_id, status FROM flow_sessions WHERE status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping') ORDER BY updated_at DESC")
     };
 }
 function activeStateBlockers(active) {
     const blockers = [];
     if (active.protocols.length > 0)
-        blockers.push(`active protocols: ${active.protocols.map((item) => item.id).join(", ")}`);
+        blockers.push(`active protocols: ${active.protocols.map((item) => `${item.project_id}:${item.id}`).join(", ")}`);
     if (active.runs.length > 0)
-        blockers.push(`active runs: ${active.runs.map((item) => item.id).join(", ")}`);
+        blockers.push(`active runs: ${active.runs.map((item) => `${item.project_id}:${item.id}`).join(", ")}`);
     if (active.merge_queue.length > 0)
-        blockers.push(`active merge queue items: ${active.merge_queue.map((item) => item.protocol_id).join(", ")}`);
+        blockers.push(`active merge queue items: ${active.merge_queue.map((item) => `${item.project_id}:${item.protocol_id}`).join(", ")}`);
     if (active.lane_locks.length > 0)
-        blockers.push(`active lane locks: ${active.lane_locks.map((item) => `${item.lane}:${item.worker_id}`).join(", ")}`);
+        blockers.push(`active lane locks: ${active.lane_locks.map((item) => `${item.project_id}:${item.lane}:${item.worker_id}`).join(", ")}`);
+    if (active.lane_waiters.length > 0)
+        blockers.push(`queued lane waiters: ${active.lane_waiters.map((item) => `${item.project_id}:${item.lane}:${item.worker_id}`).join(", ")}`);
+    if (active.merge_sessions.length > 0)
+        blockers.push(`active merge sessions: ${active.merge_sessions.map((item) => `${item.project_id}:${item.session_id}`).join(", ")}`);
+    if (active.sessions.length > 0)
+        blockers.push(`active sessions: ${active.sessions.map((item) => `${item.project_id}:${item.session_id}`).join(", ")}`);
     return blockers;
 }
 function readJsonObject(filePath) {