@deksden-com/dd-flow-cli 0.3.0 → 0.3.1

package/dist/services/protocols.js

@@ -14,6 +14,7 @@ import { requireProjectByRoot } from "./projects.js";
 import { ensureRuntimeProtocolFiles, readPlanFile, readStateFile, writeState } from "../protocol/local-files.js";
 import { activeCodexSessionBindingsForProject, activeFlowSessionBindingsForProject, codexHomeProfilesForProject, codexHookEventsForProject, hookStatusForProject } from "./hooks.js";
 import { buildProtocolFlowGuidance } from "./flow-guidance.js";
+import { lifecycleIsTerminalFailure, lifecycleIsTerminalSuccess, normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
 export function registerProtocol(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
@@ -88,10 +89,12 @@ export function getProtocolStatus(context, input) {
     const plan = readPlanFile(protocol.plan_path);
     const runDiagnostics = protocolRunDiagnostics(context, protocol, state);
     const queue = context.db.get("SELECT * FROM merge_queue WHERE protocol_id = ?", [protocol.id]);
+    const lifecycle = normalizeProtocolLifecycle({ state, queueStatus: queue?.status ?? null });
     return {
         ok: true,
-        protocol: protocolStatusPayload(protocol),
-        diagnostics: [...runtime.diagnostics, ...runDiagnostics.diagnostics],
+        protocol: { ...protocolStatusPayload(protocol), lifecycle },
+        lifecycle,
+        diagnostics: [...runtime.diagnostics, ...runDiagnostics.diagnostics, ...lifecycle.diagnostics],
         latest_run: runDiagnostics.latest_run,
         state,
         plan: plan ? summarizePlan(plan) : state.plan,
@@ -173,6 +176,9 @@ export function implementProtocol(context, input) {
     if (input.force && (!input.reason || input.reason.trim().length === 0)) {
         throw new AppError("validation", "Forced protocol implement preflight requires --reason", 2);
     }
+    const lifecycle = protocol
+        ? normalizeProtocolLifecycle({ state, queueStatus: queue?.status ?? null })
+        : normalizeProtocolLifecycle({ rawStage: "unregistered", rawStatus: "missing" });
     const currentStage = state?.stage ?? "unregistered";
     const recommendedPrompt = promptForImplementationStage(currentStage);
     return {
@@ -197,6 +203,7 @@ export function implementProtocol(context, input) {
         blockers,
         active_sessions: activeSessions,
         merge_queue: queue ?? null,
+        lifecycle,
         terminal,
         related_context: document.related_context,
         coding_standards_sources: document.coding_standards_sources,
@@ -274,6 +281,7 @@ export function transitionProtocol(context, input) {
         to,
         forced: input.force,
         state: nextState,
+        lifecycle: normalizeProtocolLifecycle({ state: nextState, queueStatus: queue?.status ?? null }),
         flow_guidance: buildProtocolFlowGuidance({ state: nextState, latestRun: runDiagnostics.latest_run, queueStatus: queue?.status ?? null })
     };
 }
@@ -298,6 +306,7 @@ export function readyForMerge(context, input) {
             protocol_id: protocol.id,
             queue_status: existingQueueJob.status,
             state,
+            lifecycle: normalizeProtocolLifecycle({ state, queueStatus: existingQueueJob.status }),
             flow_guidance: buildProtocolFlowGuidance({ state, latestRun: runDiagnostics.latest_run, queueStatus: existingQueueJob.status })
         };
     }
@@ -349,6 +358,7 @@ export function readyForMerge(context, input) {
         protocol_id: protocol.id,
         queue_status: "ready",
         state: nextState,
+        lifecycle: normalizeProtocolLifecycle({ state: nextState, queueStatus: "ready" }),
         flow_guidance: buildProtocolFlowGuidance({ state: nextState, latestRun: runDiagnostics.latest_run, queueStatus: "ready" })
     };
 }
@@ -909,11 +919,17 @@ function protocolSetMemberStatus(context, projectId, document) {
     const projectRoot = projectRootFromProtocolFile(document.path);
     const blockers = document.blocked_by_protocols.map((id) => blockerStatus(context, projectId, projectRoot, id));
     const terminal = protocolTerminalStatus(context, projectId, projectRoot, document.id, state);
+    const lifecycle = normalizeProtocolLifecycle({
+        state,
+        rawStage: runtime?.stage ?? "unregistered",
+        rawStatus: runtime?.status ?? "missing",
+        queueStatus: queue?.status ?? null
+    });
     const setStatus = terminal.success
         ? "done"
         : queue?.status === "claimed" || activeSessions.length > 0
             ? "claimed"
-            : state && ["implementation", "readiness", "plan", "specify", "integration", "queued_for_merge", "ready_for_merge"].includes(state.stage)
+            : state && ["specify", "plan", "code", "merge"].includes(lifecycle.stage)
                 ? "running"
                 : blockers.some((blocker) => !blocker.resolved)
                     ? "blocked"
@@ -926,8 +942,9 @@ function protocolSetMemberStatus(context, projectId, document) {
         blocked_by_protocols: document.blocked_by_protocols,
         blockers,
         runtime: runtime
-            ? { registered: true, status: runtime.status, stage: runtime.stage, next_action: runtime.next_action, updated_at: runtime.updated_at }
+            ? { registered: true, status: runtime.status, stage: runtime.stage, lifecycle, next_action: runtime.next_action, updated_at: runtime.updated_at }
             : { registered: false, status: "missing", stage: "unregistered", next_action: "register_protocol" },
+        lifecycle,
         active_sessions: activeSessions,
         merge_queue: queue ?? null,
         terminal
@@ -964,22 +981,25 @@ function blockerStatus(context, projectId, projectRoot, blockerId) {
     const runtime = findProtocol(context, blockerId);
     const state = runtime ? readProtocolRuntimeState(context, runtime).state : null;
     const terminal = protocolTerminalStatus(context, projectId, projectRoot, blockerId, state);
+    const lifecycle = normalizeProtocolLifecycle({ state, rawStage: runtime?.stage, rawStatus: runtime?.status });
     return {
         id: blockerId,
         resolved: terminal.success,
         source: terminal.source,
         status: runtime?.status ?? terminal.status ?? "unknown",
         stage: runtime?.stage ?? terminal.stage ?? "unknown",
-        lifecycle: terminal.lifecycle,
+        lifecycle,
+        document_lifecycle: terminal.lifecycle,
         reason: terminal.reason
     };
 }
 function protocolTerminalStatus(context, projectId, projectRoot, protocolId, state) {
     if (state) {
-        if (state.stage === "closed" || state.status === "closed") {
+        const lifecycle = normalizeProtocolLifecycle({ state });
+        if (lifecycleIsTerminalSuccess(lifecycle)) {
             return { terminal: true, success: true, source: "runtime_state", status: state.status, stage: state.stage, reason: "runtime protocol is closed" };
         }
-        if (state.stage === "cancelled" || state.status === "cancelled") {
+        if (lifecycleIsTerminalFailure(lifecycle)) {
             return { terminal: true, success: false, source: "runtime_state", status: state.status, stage: state.stage, reason: "runtime protocol is cancelled" };
         }
     }
@@ -1089,6 +1109,7 @@ function objectOrExisting(value, existing) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : existing;
 }
 function protocolStatusPayload(protocol) {
+    const lifecycle = normalizeProtocolLifecycle({ rawStage: protocol.stage, rawStatus: protocol.status });
     return {
         id: protocol.id,
         handshake_id: protocol.handshake_id,
@@ -1096,6 +1117,7 @@ function protocolStatusPayload(protocol) {
         project_root: protocol.project_root,
         status: protocol.status,
         stage: protocol.stage,
+        lifecycle,
         next_action: protocol.next_action,
         route: JSON.parse(protocol.route_json),
         workspace: JSON.parse(protocol.workspace_json),

package/dist/services/sessions.js

@@ -5,6 +5,7 @@ import { AppError } from "../shared/errors.js";
 import { parseJsonObject } from "../shared/json.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
+import { cancelLaneWaitersForWorker } from "./lanes.js";
 export function registerFlowSession(context, input) {
     const payload = decodeFlowSessionPayload(input);
     const project = requireProjectByRoot(context, resolveProjectRoot(payload.project_root));
@@ -44,16 +45,21 @@ export function stopMergeWorker(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const sessions = flowSessionsForProject(context, project.id, { workerId: input.workerId }).filter((session) => session.flow_kind === "merge_worker" && ["active", "pending", "stopping"].includes(session.status));
     let lock_release = { ok: true, released: false, reason: "no_active_session" };
+    let waiter_cancellation = { ok: true, cancelled: 0 };
     for (const session of sessions) {
-        lock_release = markSessionStopped(context, project, session, input.reason) ?? lock_release;
+        const stopped = markSessionStopped(context, project, session, input.reason);
+        if (isStopResult(stopped)) {
+            lock_release = stopped.lock_release ?? lock_release;
+            waiter_cancellation = stopped.waiter_cancellation ?? waiter_cancellation;
+        }
     }
     appendAudit(context, {
         projectId: project.id,
         eventType: "flow_session.merge_worker_stopped",
         reason: input.reason,
-        payload: { project_id: project.id, worker_id: input.workerId, stopped_sessions: sessions.length, lock_release }
+        payload: { project_id: project.id, worker_id: input.workerId, stopped_sessions: sessions.length, lock_release, waiter_cancellation }
     });
-    return { ok: true, stopped_sessions: sessions.length, lock_release };
+    return { ok: true, stopped_sessions: sessions.length, lock_release, waiter_cancellation };
 }
 export function stoppedMergeWorkerState(context, projectId, workerId) {
     const latest = context.db.get(`SELECT status, stop_reason FROM flow_sessions
@@ -268,6 +274,14 @@ function markSessionStopped(context, project, session, reason) {
      SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
      WHERE project_id = ? AND session_id = ?`, [reason, now, now, project.id, session.session_id]);
     let lockRelease = undefined;
+    let waiterCancellation = undefined;
+    if (session.worker_id) {
+        waiterCancellation = cancelLaneWaitersForWorker(context, {
+            projectRoot: project.root,
+            workerId: session.worker_id,
+            reason
+        });
+    }
     if ((session.flow_kind === "merge_worker" || session.flow_kind === "merge_job") && session.worker_id) {
         lockRelease = releaseMergeLockIfOwned(context, project.root, session.worker_id, reason);
     }
@@ -278,7 +292,10 @@ function markSessionStopped(context, project, session, reason) {
         payload: { project_id: project.id, session_id: session.session_id, flow_kind: session.flow_kind },
         ...(session.protocol_id ? { protocolId: session.protocol_id } : {})
     });
-    return lockRelease;
+    return { lock_release: lockRelease, waiter_cancellation: waiterCancellation };
+}
+function isStopResult(value) {
+    return Boolean(value && typeof value === "object" && ("lock_release" in value || "waiter_cancellation" in value));
 }
 function releaseMergeLockIfOwned(context, projectRoot, workerId, reason) {
     const project = requireProjectByRoot(context, resolveProjectRoot(projectRoot));

package/dist/services/status.js

@@ -5,6 +5,9 @@ import { getCanonStatus } from "./canon.js";
 import { getCliBuildInfo } from "./build-info.js";
 import { getProjectVersionStatus, resolveStatusProjectRoot } from "./version-status.js";
 import { findProjectByRoot } from "./projects.js";
+import { classifyCliOperation } from "./cli-operation-classifier.js";
+import { compatibilityReport } from "./compatibility-preflight.js";
+import { selectEngine } from "./engines.js";
 export function getRuntimeStatus(context, input = {}) {
     const cwd = process.cwd();
     const projectRootResolution = resolveStatusProjectRoot({ requestedRoot: input.projectRoot, cwd });
@@ -21,6 +24,7 @@ export function getRuntimeStatus(context, input = {}) {
     const cli = getCliBuildInfo();
     const compatibilityManifest = resolvedCanonForProject ? readCompatibilityManifest(canon) : null;
     const cliCompatibility = cliCompatibilityVerdict(cli, compatibilityManifest);
+    const engineSelection = projectRoot ? selectEngine(context, { projectRoot }) : null;
     const registry = input.checkRegistry ? checkNpmRegistry(context, cli.package_name) : undefined;
     return {
         ok: true,
@@ -43,6 +47,12 @@ export function getRuntimeStatus(context, input = {}) {
             flow_pack: projectVersionStatus?.flow_pack ?? null,
             drift: projectVersionStatus?.drift ?? null
         },
+        engine: engineSelection
+            ? {
+                selection: engineSelection,
+                compatibility: compatibilityReport(engineSelection, classifyCliOperation(["status"]))
+            }
+            : null,
         canon: {
             ...(asRecord(canonStatus) ?? {}),
             resolved: canon ?? null,

package/dist/services/version-status.js

@@ -22,7 +22,8 @@ export function getProjectVersionStatus(input) {
     const flowPack = readFlowPackMetadata(input.projectRoot, memoryBank.root);
     const memoryBankDrift = compareMemoryBankVersion(memoryBank.version, input.canon?.metadata.version ?? null, memoryBank.status);
     const flowPackDrift = compareFlowPackCommit(flowPack.source_commit, input.canon?.metadata.commit ?? null, input.canon?.root ?? null, flowPack.status);
-    const overall = overallDrift(memoryBankDrift, flowPackDrift, memoryBank.status, flowPack.status);
+    const flowContractDrift = compareFlowContract(flowPack.flow_contract, input.canon?.metadata.flow_contract ?? null, flowPack.status);
+    const overall = overallDrift(memoryBankDrift, flowPackDrift, flowContractDrift, memoryBank.status, flowPack.status);
     return {
         root: input.projectRoot,
         root_source: input.rootSource,
@@ -31,8 +32,9 @@ export function getProjectVersionStatus(input) {
         drift: {
             memory_bank_version: memoryBankDrift,
             flow_pack_commit: flowPackDrift,
+            flow_contract: flowContractDrift,
             overall,
-            next_action: nextAction(overall, memoryBank.status, flowPack.status)
+            next_action: nextAction(overall, memoryBank.status, flowPack.status, flowContractDrift.status)
         }
     };
 }
@@ -67,6 +69,7 @@ function readFlowPackMetadata(projectRoot, memoryBankRoot) {
             canon_flow_root: null,
             source_commit: null,
             canon_version_at_source_commit: null,
+            flow_contract: null,
             status: "missing",
             reason: "no_memory_bank",
             canonical_only_files: []
@@ -85,6 +88,7 @@ function readFlowPackMetadata(projectRoot, memoryBankRoot) {
             canon_flow_root: null,
             source_commit: null,
             canon_version_at_source_commit: null,
+            flow_contract: null,
             status: "missing",
             reason: "flow_pack_manifest_missing",
             canonical_only_files: canonicalOnlyFiles
@@ -107,6 +111,7 @@ function readFlowPackMetadata(projectRoot, memoryBankRoot) {
             canon_flow_root: null,
             source_commit: null,
             canon_version_at_source_commit: null,
+            flow_contract: null,
             status: "invalid",
             reason: "flow_pack_manifest_invalid_json",
             canonical_only_files: canonicalOnlyFiles
@@ -118,19 +123,22 @@ function readFlowPackMetadata(projectRoot, memoryBankRoot) {
     const canonRoot = stringOrNull(manifest.canon_root);
     const canonMemoryBankRoot = stringOrNull(manifest.canon_memory_bank_root);
     const canonFlowRoot = stringOrNull(manifest.canon_flow_root);
-    const status = schemaId === "dd-flow/project-flow-pack-manifest@2" && canonVersion && canonMemoryBankRoot && canonFlowRoot
+    const flowContract = stringOrNull(manifest.flow_contract);
+    const status = schemaId === "dd-flow/project-flow-pack-manifest@2" && canonVersion && canonMemoryBankRoot && canonFlowRoot && flowContract
         ? "present"
         : schemaId === "dd-flow/project-flow-pack-manifest@1" ||
-            (schemaId === "dd-flow/project-flow-pack-manifest@2" && canonVersion && (!canonMemoryBankRoot || !canonFlowRoot))
+            (schemaId === "dd-flow/project-flow-pack-manifest@2" && canonVersion && (!canonMemoryBankRoot || !canonFlowRoot || !flowContract))
             ? "degraded"
             : "invalid";
-    const reason = status === "degraded" && schemaId === "dd-flow/project-flow-pack-manifest@2"
+    const reason = status === "degraded" && schemaId === "dd-flow/project-flow-pack-manifest@2" && (!canonMemoryBankRoot || !canonFlowRoot)
         ? "flow_pack_manifest_missing_explicit_canon_roots"
-        : status === "degraded"
-            ? "legacy_flow_pack_manifest"
-            : status === "invalid"
-                ? "flow_pack_manifest_schema_unknown"
-                : undefined;
+        : status === "degraded" && schemaId === "dd-flow/project-flow-pack-manifest@2" && !flowContract
+            ? "flow_pack_manifest_missing_flow_contract"
+            : status === "degraded"
+                ? "legacy_flow_pack_manifest"
+                : status === "invalid"
+                    ? "flow_pack_manifest_schema_unknown"
+                    : undefined;
     return {
         manifest_path: path.relative(projectRoot, manifestPath),
         schema_id: schemaId,
@@ -140,6 +148,7 @@ function readFlowPackMetadata(projectRoot, memoryBankRoot) {
         canon_flow_root: canonFlowRoot,
         source_commit: sourceCommit,
         canon_version_at_source_commit: canonVersion,
+        flow_contract: flowContract,
         status,
         ...(reason ? { reason } : {}),
         canonical_only_files: canonicalOnlyFiles
@@ -216,28 +225,43 @@ function compareFlowPackCommit(current, target, canonRoot, artifactStatus) {
         target
     };
 }
-function overallDrift(memoryBank, flowPack, memoryStatus, flowStatus) {
+function compareFlowContract(current, target, artifactStatus) {
+    if (artifactStatus === "missing")
+        return { status: "missing", confidence: "none", reason: "flow_pack_manifest_missing", current, target };
+    if (artifactStatus === "invalid")
+        return { status: "invalid", confidence: "none", reason: "flow_pack_manifest_invalid", current, target };
+    if (!current)
+        return { status: "unknown", confidence: "none", reason: "flow_pack_flow_contract_missing", current, target };
+    if (!target)
+        return { status: "unknown", confidence: "none", reason: "canon_flow_contract_unknown", current, target };
+    if (current === target)
+        return { status: "same", confidence: "exact", reason: "flow_contract_equal", current, target };
+    return { status: "diverged", confidence: "declared", reason: "flow_contract_mismatch", current, target };
+}
+function overallDrift(memoryBank, flowPack, flowContract, memoryStatus, flowStatus) {
     if (memoryStatus === "missing")
         return "not_applicable";
-    if (memoryBank.status === "invalid" || flowPack.status === "invalid")
+    if (memoryBank.status === "invalid" || flowPack.status === "invalid" || flowContract.status === "invalid")
         return "invalid";
-    if (memoryBank.status === "missing" || flowPack.status === "missing")
+    if (memoryBank.status === "missing" || flowPack.status === "missing" || flowContract.status === "missing")
         return "missing";
     if (memoryBank.status === "ahead" || flowPack.status === "ahead")
         return "ahead";
     if (memoryBank.status === "behind" || flowPack.status === "behind")
         return "behind";
-    if (memoryBank.status === "diverged" || flowPack.status === "diverged")
+    if (memoryBank.status === "diverged" || flowPack.status === "diverged" || flowContract.status === "diverged")
         return "diverged";
     if (memoryBank.status === "same" && (flowPack.status === "same" || flowStatus === "degraded"))
         return flowStatus === "degraded" ? "unknown" : "same";
     return "unknown";
 }
-function nextAction(overall, memoryStatus, flowStatus) {
+function nextAction(overall, memoryStatus, flowStatus, flowContractStatus) {
     if (overall === "same")
         return "no_action";
     if (overall === "not_applicable" && memoryStatus === "missing")
         return "run_mb_init_if_project_needs_memory_bank";
+    if (flowContractStatus === "diverged" || flowContractStatus === "unknown")
+        return "run_canonical_mb_upgrade_before_lifecycle_mutations";
     if (overall === "behind" || flowStatus === "degraded")
         return "run_canonical_mb_upgrade";
     if (overall === "missing")

package/dist/storage/database.js

@@ -134,10 +134,34 @@ function migrate(db) {
       FOREIGN KEY(project_id) REFERENCES projects(id)
     );
 
+    CREATE TABLE IF NOT EXISTS lane_waiters (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id TEXT NOT NULL,
+      lane TEXT NOT NULL,
+      worker_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      queued_at TEXT NOT NULL,
+      acquired_at TEXT,
+      cancelled_at TEXT,
+      expires_at TEXT,
+      reason TEXT,
+      metadata_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      FOREIGN KEY(project_id) REFERENCES projects(id)
+    );
+
     CREATE UNIQUE INDEX IF NOT EXISTS idx_lane_locks_one_active
       ON lane_locks(project_id, lane)
       WHERE status = 'active';
 
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_lane_waiters_one_queued_worker
+      ON lane_waiters(project_id, lane, worker_id)
+      WHERE status = 'queued';
+
+    CREATE INDEX IF NOT EXISTS idx_lane_waiters_fifo
+      ON lane_waiters(project_id, lane, status, queued_at, id);
+
     CREATE TABLE IF NOT EXISTS hook_installations (
       project_id TEXT NOT NULL,
       scope TEXT NOT NULL,
@@ -324,6 +348,7 @@ function migrate(db) {
     ensureColumn(db, "flow_runs", "run_home_path", "ALTER TABLE flow_runs ADD COLUMN run_home_path TEXT");
     ensureColumn(db, "flow_runs", "layout_version", "ALTER TABLE flow_runs ADD COLUMN layout_version TEXT");
     ensureColumn(db, "flow_runs", "artifact_root_kind", "ALTER TABLE flow_runs ADD COLUMN artifact_root_kind TEXT");
+    ensureColumn(db, "lane_waiters", "expires_at", "ALTER TABLE lane_waiters ADD COLUMN expires_at TEXT");
 }
 function ensureColumn(db, table, column, sql) {
     const columns = db.prepare(`PRAGMA table_info(${table})`).all();

package/dist/storage/paths.js

@@ -75,3 +75,15 @@ export function projectCheckoutRoot(ddFlowHome, projectId) {
 export function projectFeatureWorktreePath(ddFlowHome, projectId, runOrProtocolId, repoName) {
     return path.join(projectCheckoutRoot(ddFlowHome, projectId), "worktrees", runOrProtocolId, repoName);
 }
+export function engineStoreRoot(ddFlowHome) {
+    return path.join(ddFlowHome, "engines");
+}
+export function packageEngineRoot(ddFlowHome, packageName) {
+    return path.join(engineStoreRoot(ddFlowHome), safePathSegment(packageName));
+}
+export function engineVersionRoot(ddFlowHome, packageName, version) {
+    return path.join(packageEngineRoot(ddFlowHome, packageName), safePathSegment(version));
+}
+function safePathSegment(value) {
+    return value.replace(/[^a-zA-Z0-9_.@-]+/g, "_");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=26.0.0",