@deksden-com/dd-flow-cli 0.6.0 → 0.8.0-beta.135

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 = 'running' 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 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 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) {

package/dist/services/plan-runtime.js

@@ -54,8 +54,8 @@ export function boundCanonicalPlan(context, input) {
     refreshProtocolRuns(context, input.projectId, input.protocolId);
     return canonical;
 }
-export function planWithProgress(context, input) {
-    const canonical = boundCanonicalPlan(context, input);
+export function planWithProgress(context, input, options = {}) {
+    const canonical = options.bind === false ? readCanonicalPlan(input.planPath, input.protocolId) : boundCanonicalPlan(context, input);
     const rows = context.db.all(`SELECT item_id, plan_revision, plan_sha256, status, summary, evidence_json, block_reason, user_required
      FROM plan_progress WHERE project_id = ? AND protocol_id = ?`, [input.projectId, input.protocolId]);
     const progress = new Map(rows.map((row) => [row.item_id, row]));
@@ -67,8 +67,8 @@ export function planWithProgress(context, input) {
         }
     };
 }
-export function planSummary(context, input) {
-    const { canonical, plan } = planWithProgress(context, input);
+export function planSummary(context, input, options = {}) {
+    const { canonical, plan } = planWithProgress(context, input, options);
     return {
         plan_id: plan.plan_id,
         revision: canonical.revision,
@@ -98,7 +98,7 @@ export function updatePlanProgress(context, input) {
     refreshProtocolRuns(context, input.projectId, input.protocolId);
 }
 function refreshProtocolRuns(context, projectId, protocolId) {
-    for (const run of context.db.all("SELECT id FROM flow_runs WHERE project_id = ? AND subject_type = 'protocol' AND subject_id = ?", [projectId, protocolId]))
+    for (const run of context.db.all("SELECT id FROM runs WHERE project_id = ? AND subject_type = 'protocol' AND subject_id = ?", [projectId, protocolId]))
         refreshRunSessionProjection(context, projectId, run.id);
 }
 function mergeProgress(item, row, canonical) {

package/dist/services/plans.js

@@ -7,11 +7,11 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { planSummary, planWithProgress, updatePlanProgress } from "./plan-runtime.js";
 export function getPlanStatus(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
-    const current = planWithProgress(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path });
+    const current = planWithProgress(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }, { bind: false });
     return {
         ok: true,
         protocol_id: protocol.id,
-        plan: planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }),
+        plan: planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }, { bind: false }),
         binding: { revision: current.canonical.revision, sha256: current.canonical.sha256, path: protocol.plan_path },
         blocked_items: current.plan.items
             .filter((item) => item.status === "blocked")
@@ -69,7 +69,9 @@ function updatePlanItem(context, projectRoot, protocolId, itemId, transform) {
 }
 function scopedProtocol(context, projectRoot, protocolId) {
     const project = requireProjectByRoot(context, resolveProjectRoot(projectRoot));
-    return requireProtocol(context, protocolId, project.id);
+    const protocol = requireProtocol(context, protocolId, project.id);
+    readProtocolRuntimeState(context, protocol);
+    return protocol;
 }
 function assertDependenciesClosed(plan, item) {
     const openDependencies = item.depends_on

package/dist/services/projects.js

@@ -218,9 +218,9 @@ export function getProjectStatus(context, input) {
         merge_queue: mergeQueue,
         hook_status: hookStatusForProject(context, project.id),
         codex_home_profiles: codexHomeProfilesForProject(context, project.id),
-        flow_sessions: activeFlowSessionBindingsForProject(context, project.id),
+        sessions: activeFlowSessionBindingsForProject(context, project.id),
         codex_session_bindings: activeCodexSessionBindingsForProject(context, project.id),
-        codex_hook_events: codexHookEventsForProject(context, project.id),
+        hook_events: codexHookEventsForProject(context, project.id),
         worktrees,
         lane_status: {
             lanes: context.db.all("SELECT * FROM lanes WHERE project_id = ? ORDER BY name ASC", [project.id]),
@@ -319,10 +319,10 @@ function projectReferenceTables() {
         "codex_home_profiles",
         "codex_session_bindings",
         "project_config",
-        "flow_sessions",
+        "sessions",
         "flow_session_segments",
         "flow_jobs",
-        "codex_hook_events",
+        "hook_events",
         "worktree_records"
     ];
 }

package/dist/services/prompts.js

@@ -204,7 +204,7 @@ function protocolIdForRun(context, projectId, runId) {
     return run.subject_id;
 }
 function requireRun(context, projectId, runId) {
-    const row = context.db.get("SELECT id, project_id, subject_type, subject_id, workspace_root, run_index_path, run_home_path, index_json FROM flow_runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, runId, runId]);
+    const row = context.db.get("SELECT id, project_id, subject_type, subject_id, workspace_root, run_index_path, run_home_path, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, runId, runId]);
     if (!row)
         throw new AppError("not_found", `Run is not found: ${runId}`, 1);
     return row;

package/dist/services/protocols.js

@@ -47,7 +47,7 @@ export function registerProtocol(context, input) {
         JSON.stringify(state.blockers),
         JSON.stringify(state.active_def),
         runtimeStateJsonPath(context.ddFlowHome, project.id, protocolId),
-        planJsonPath(projectRoot, protocolId),
+        planJsonPath(workspacePath ?? projectRoot, protocolId),
         existing?.created_at ?? now,
         now
     ];
@@ -100,16 +100,16 @@ export function getProtocolStatus(context, input) {
         diagnostics: [...runtime.diagnostics, ...runDiagnostics.diagnostics, ...lifecycle.diagnostics],
         latest_run: runDiagnostics.latest_run,
         state,
-        plan: plan ? planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }) : state.plan,
+        plan: plan ? planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }, { bind: false }) : state.plan,
         merge_queue: queue,
         branch_context: getProtocolBranchContext(context, { protocolId: protocol.id, projectRoot: project.root }).branch_context,
         flow_guidance: buildProtocolFlowGuidance({ state, latestRun: runDiagnostics.latest_run, queueStatus: queue?.status ?? null }),
         worktree: context.db.get("SELECT * FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [protocol.project_id, protocol.id]),
         hook_status: hookStatusForProject(context, protocol.project_id),
         codex_home_profiles: codexHomeProfilesForProject(context, protocol.project_id),
-        flow_sessions: activeFlowSessionBindingsForProject(context, protocol.project_id).filter((session) => session.protocol_id === protocol.id),
+        sessions: activeFlowSessionBindingsForProject(context, protocol.project_id).filter((session) => session.protocol_id === protocol.id),
         codex_session_bindings: activeCodexSessionBindingsForProject(context, protocol.project_id).filter((binding) => binding.protocol_id === protocol.id),
-        codex_hook_events: codexHookEventsForProject(context, protocol.project_id).filter((event) => event.protocol_id === protocol.id),
+        hook_events: codexHookEventsForProject(context, protocol.project_id).filter((event) => event.protocol_id === protocol.id),
         audit: getAuditEvents(context, protocol.project_id, protocol.id)
     };
 }
@@ -502,7 +502,7 @@ export function cancelProtocol(context, input) {
         }
         let closedSessions = 0;
         if (input.closeSessions) {
-            const result = context.db.run(`UPDATE flow_sessions
+            const result = context.db.run(`UPDATE sessions
          SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
          WHERE project_id = ?
            AND protocol_id = ?
@@ -705,7 +705,7 @@ function removeLocalFeatureBranch(projectRoot, branch, force) {
     return { ok: true, skipped: false, reason: force ? "branch_force_deleted" : "branch_deleted", branch };
 }
 function releaseRelatedMergeLocks(context, protocol, reason) {
-    const workers = context.db.all(`SELECT DISTINCT worker_id FROM flow_sessions
+    const workers = context.db.all(`SELECT DISTINCT worker_id FROM sessions
      WHERE project_id = ? AND protocol_id = ? AND worker_id IS NOT NULL`, [protocol.project_id, protocol.id]).map((row) => row.worker_id).filter((workerId) => Boolean(workerId));
     const job = context.db.get("SELECT claimed_by_session_id FROM merge_queue WHERE project_id = ? AND protocol_id = ?", [protocol.project_id, protocol.id]);
     if (job?.claimed_by_session_id) {
@@ -734,6 +734,7 @@ function releaseRelatedMergeLocks(context, protocol, reason) {
 }
 export function readProtocolRuntimeState(context, protocol) {
     const diagnostics = [];
+    normalizeProtocolPlanPath(context, protocol, diagnostics);
     try {
         return { state: readStateFile(protocol.state_path, protocol.id), diagnostics };
     }
@@ -764,7 +765,7 @@ export function readProtocolRuntimeState(context, protocol) {
     }
     const plan = canonicalPlanIfPresent(context, protocol);
     const summary = plan
-        ? planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path })
+        ? planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }, { bind: false })
         : { plan_id: null, total: 0, done: 0, blocked: 0 };
     const flowContract = loadProjectFlowContract(protocol.project_root);
     const state = {
@@ -782,6 +783,9 @@ export function readProtocolRuntimeState(context, protocol) {
         flow_contract: flowContract,
         updated_at: protocol.updated_at
     };
+    if (!context.db.writable) {
+        return { state, diagnostics };
+    }
     const stableStatePath = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
     const stablePlanPath = planJsonPath(protocol.project_root, protocol.id);
     ensureDir(path.dirname(stableStatePath));
@@ -798,6 +802,23 @@ export function readProtocolRuntimeState(context, protocol) {
     });
     return { state, diagnostics };
 }
+function normalizeProtocolPlanPath(context, protocol, diagnostics) {
+    const canonicalPlanPath = planJsonPath(protocol.project_root, protocol.id);
+    if (protocol.plan_path === canonicalPlanPath || !fs.existsSync(canonicalPlanPath))
+        return;
+    diagnostics.push({
+        code: "protocol_plan_relocated",
+        severity: "warning",
+        old_path: protocol.plan_path,
+        path: canonicalPlanPath,
+        source: "project_canonical_plan",
+        recommended_action: "use the project canonical plan as the sole semantic plan source"
+    });
+    if (context.db.writable) {
+        context.db.run("UPDATE protocols SET plan_path = ?, updated_at = ? WHERE project_id = ? AND id = ?", [canonicalPlanPath, context.now(), protocol.project_id, protocol.id]);
+    }
+    protocol.plan_path = canonicalPlanPath;
+}
 export function protocolRunDiagnostics(context, protocol, state) {
     const runs = linkedRunsForProtocol(context, protocol, 5);
     const latest = runs[0];
@@ -845,7 +866,7 @@ export function persistProtocolState(context, protocol, state) {
     ]);
     if (state.status === "closed" || state.stage === "closed") {
         const now = context.now();
-        context.db.run(`UPDATE flow_sessions
+        context.db.run(`UPDATE sessions
        SET status = 'stopped', stop_reason = 'protocol closed', updated_at = ?, stopped_at = ?
        WHERE project_id = ?
          AND protocol_id = ?
@@ -1195,14 +1216,14 @@ function readinessMissingFields(state) {
 }
 function linkedRunsForProtocol(context, protocol, limit) {
     return context.db.all(`SELECT id, short_id, flow_kind, subject_type, subject_id, status, verdict, next_action, run_index_path, index_json, created_at, updated_at, completed_at
-     FROM flow_runs
+     FROM runs
      WHERE project_id = ? AND subject_type = 'protocol' AND subject_id = ?
      ORDER BY updated_at DESC, id DESC
      LIMIT ?`, [protocol.project_id, protocol.id, limit]);
 }
 function resolveLinkedRun(context, protocol, runIdOrAlias) {
     const matches = context.db.all(`SELECT id, short_id, flow_kind, subject_type, subject_id, status, verdict, next_action, run_index_path, index_json, created_at, updated_at, completed_at
-     FROM flow_runs
+     FROM runs
      WHERE project_id = ? AND (id = ? OR short_id = ?)
      ORDER BY updated_at DESC, id DESC`, [protocol.project_id, runIdOrAlias, runIdOrAlias]);
     if (matches.length === 1)