@deksden-com/dd-flow-cli 0.9.0-beta.18 → 0.9.0-beta.21

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.21
+
+### Patch Changes
+
+- Validate every selected engine artifact and execute its pinned snapshot even when its version matches the router. Retain a new recovery interruption before root acknowledgement.
+
+## 0.9.0-beta.20
+
+### Patch Changes
+
+- Verify recovery payloads and workspace drift before resuming, preserve staged Git changes, publish snapshots through a temporary directory, and allow explicit recovery restoration into fresh targets. Fence RUN mutations and late asynchronous Work completion while recovery is active.
+
+## 0.9.0-beta.19
+
+### Patch Changes
+
+- Require a fresh trusted hook receipt from the physical Work owner before terminal stage or Work lifecycle commands can mutate a vNext RUN. Record terminal native-child observations at their originating Stage so unbound delegation is retained as a diagnostic instead of contaminating a later fan-out wave.
+
 ## 0.9.0-beta.18
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,11 +1,11 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.18",
-  "cli_commit": "5624d92e8e96732db6a81f1cf86fb5342f38401f",
-  "built_at": "2026-09-06T03:05:30.379Z",
+  "cli_version": "0.9.0-beta.21",
+  "cli_commit": "2350e9cbeddba31e283d27384163b2bb44690d46",
+  "built_at": "2026-09-06T23:59:54.226Z",
   "built_with_canon": {
-    "version": "4.0.5",
-    "commit": "272579e9035b88772a0f017c9bec09f877c17552",
+    "version": "4.0.6",
+    "commit": "2aafb30d23e3f646b736b7ead25438cab97b16bf",
     "flow_contract": "dd-flow-canonical-2026-08",
     "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
     "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",

package/dist/cli/help.js

@@ -155,8 +155,9 @@ Usage:
   dd-flow run status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run list --project-root <root> --json
   dd-flow run prepare-vnext-specify --project-root <root> --slug <slug> --json
-  dd-flow run snapshot create <RUN-ID|RUN-short-id> (--stage-entry <stage>|--candidate|--incomplete) --project-root <root> --output <directory> --json
-  dd-flow run snapshot restore --snapshot <directory> --project-root <prepared-root> --json
+  dd-flow run recovery inspect|begin|seal|capture|resume <RUN-ID|RUN-short-id> --project-root <root> --json
+  dd-flow run snapshot create <RUN-ID|RUN-short-id> (--stage-entry <stage>|--candidate|--incomplete|--recovery-id <RCV-ID>) --project-root <root> --output <directory> --json
+  dd-flow run snapshot restore --snapshot <directory> --project-root <prepared-root> [--recovery-id <RCV-ID>] --json
   dd-flow run snapshot bootstrap create --project-root <root> --output <directory> --json
   dd-flow run snapshot bootstrap restore --snapshot <directory> --project-root <prepared-root> --json
   dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> --json
@@ -170,7 +171,7 @@ Usage:
 
 RUN-* is the execution envelope for one concrete flow launch. Semantic truth remains in protocol, experiment, DEF, scenario, evidence, and Memory Bank documents. New run artifacts are stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runs/<RUN-ID-slug>/ with one run.json projection and an append-only timeline.jsonl. Timeline is the compact full run report: summary is always present, while --hide may suppress bulky sections. Use \`dd-flow stat usage --run …\` to reread registered local Codex transcript counters and tool-call facts and refresh the current usage projection; unavailable data is explicit rather than zero.
 
-run prepare-vnext-specify allocates an otherwise unstarted vNext RUN for the canonical SPECIFY entry checkpoint. run snapshot is the eval-only checkpoint boundary: it snapshots one quiescent RUN, its dedicated DD_FLOW_HOME, and the exact project tree including its Git repository, then restores them into a fresh dedicated runtime. It is not a general runtime backup command and fails closed for a shared runtime.
+run prepare-vnext-specify allocates an otherwise unstarted vNext RUN for the canonical SPECIFY entry checkpoint. run recovery makes an interrupted RUN read-only, requires an explicit settled-tree receipt, captures immutable recovery evidence, then explicitly returns delegated Work to the ready graph. run snapshot is the eval-only checkpoint boundary: it snapshots one quiescent RUN, its dedicated DD_FLOW_HOME, and the exact project tree including its Git repository, then restores them into a fresh dedicated runtime. It is not a general runtime backup command and fails closed for a shared runtime.
 
 Examples:
   dd-flow run start --project-root "$PWD" --flow-kind mb_sdlc --subject-type protocol --subject-id PRT-001-demo --slug demo --json
@@ -192,6 +193,7 @@ Usage:
   dd-flow stage fanout status <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --json
   dd-flow stage fanout dispatch <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --json
   dd-flow stage fanout reconcile <RUN-ID> --project-root <root> --stage <name> --observations-file <native-observations.json> --json
+  dd-flow stage native observe <RUN-ID> --project-root <root> --stage <name> --observations-file <native-observations.json> --json
   dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--semantic-file <RUN-local-json>] --json
   dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage specify (--result-file <RUN-local-specify.json>|--result-stdin) --outcome <specified|failed|cancelled> --json
 

package/dist/cli/run-cli.js

@@ -41,14 +41,15 @@ import { addVnextCodeRepair, finishVnextCode, startVnextCode } from "../services
 import { addVnextCodeReviewRepair, finishVnextCodeReview, isVnextCodeReviewRun, startVnextCodeReview } from "../services/vnext-code-review.js";
 import { applyVnextMerge, finishVnextMerge, getVnextMergeRequest, isVnextMergeRun, repairVnextMerge, routeVnextMergeRequest, startVnextMerge } from "../services/vnext-merge.js";
 import { mergeServerStatus, serveMergeRequests, stopMergeServer } from "../services/merge-server.js";
-import { getVnextFanoutStatus, reconcileVnextFanout } from "../services/vnext-fanout.js";
+import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout } from "../services/vnext-fanout.js";
 import { pauseStageForUser, resumeStageAfterUser } from "../services/stage-pause.js";
 import { blockStageForRuntime, unblockStageAfterRuntimeRepair } from "../services/stage-blocker.js";
 import { classifyCliOperation, requiresExplicitUpgradeAuthorization } from "../services/cli-operation-classifier.js";
 import { renderWorkerPrompt } from "../services/prompts.js";
 import { finishStage, startStage } from "../services/stage-lifecycle.js";
-import { addWorkBatch, cancelWork, deleteWork, failWork, finishWork, listWorks, mutateWorkDeps, retryWork, showWork, startWork } from "../services/work-registry.js";
+import { addWorkBatch, assertStageLifecycleOwner, assertWorkLifecycleOwner, cancelWork, deleteWork, failWork, finishWork, listWorks, mutateWorkDeps, retryWork, showWork, startWork } from "../services/work-registry.js";
 import { createEvalBootstrapSnapshot, createEvalRunSnapshot, prepareVnextSpecifyRun, restoreEvalBootstrapSnapshot, restoreEvalRunSnapshot } from "../services/eval-snapshots.js";
+import { acceptRunRecovery, beginRunRecovery, inspectRunRecovery, recordRecoveryCapture, resumeRunRecovery, sealRunRecovery } from "../services/run-recovery.js";
 import { loadExternalStageContext } from "../services/stage-context.js";
 import { stopManagedProcess, confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, reconcileExpiredManagedProcesses, registerManagedProcess } from "../services/managed-processes.js";
 import { startRuntimeService } from "../services/runtime-service.js";
@@ -670,6 +671,11 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         }
         throw new AppError("usage", "Use: dd-flow stage fanout <status|dispatch|reconcile> <RUN> --stage <stage> --project-root <path>; reconcile requires --observations-file <native-observations.json>", 2);
     }
+    if (family === "stage" && command === "native") {
+        if (requiredPosition(parsed, 0, "native action") !== "observe")
+            throw new AppError("usage", "Use: dd-flow stage native observe <RUN> --stage <stage> --observations-file <native-observations.json> --project-root <path>", 2);
+        return observeVnextNativeChildren(context, { projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "stage native observe"), runId: requiredPosition(parsed, 1, "run-id"), stage: requiredOption(parsed, "stage"), observations: JSON.parse(fs.readFileSync(requiredOption(parsed, "observations-file"), "utf8")) });
+    }
     if (family === "run" && command === "capacity") {
         if (requiredPosition(parsed, 0, "capacity action") !== "record")
             throw new AppError("usage", "Use: dd-flow run capacity record <RUN> --available-slots <0..15> --project-root <path>", 2);
@@ -757,19 +763,27 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return deleteWork(context, requiredPosition(parsed, 0, "work-id"));
     if (family === "work" && command === "start") {
         const hookEventId = optionalOption(parsed, "hook-event-id");
+        const recoveryId = optionalOption(parsed, "recovery-id");
         const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "work start");
-        return startWork(context, requiredPosition(parsed, 0, "work-id"), { ...(hookEventId ? { hookEventId } : {}), projectRoot });
+        return startWork(context, requiredPosition(parsed, 0, "work-id"), { ...(hookEventId ? { hookEventId } : {}), ...(recoveryId ? { recoveryId } : {}), projectRoot });
     }
     if (family === "work" && command === "finish") {
         const resultFile = optionalOption(parsed, "result-file");
         const resultStdin = hasOption(parsed, "result-stdin");
         if (Boolean(resultFile) === resultStdin)
             throw new AppError("usage", "work finish requires exactly one of --result-file or --result-stdin", 2);
+        const workId = requiredPosition(parsed, 0, "work-id");
+        const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "work finish");
+        assertWorkLifecycleOwner(context, { workId, projectRoot, operation: "work_finish", ...(optionalOption(parsed, "hook-event-id") ? { hookEventId: optionalOption(parsed, "hook-event-id") } : {}) });
         const result = resultFile ? fs.readFileSync(path.resolve(resultFile), "utf8") : await readStdin(io.stdin);
-        return await finishWork(context, requiredPosition(parsed, 0, "work-id"), result, commandProgress(io, output));
+        return await finishWork(context, workId, result, commandProgress(io, output));
+    }
+    if (family === "work" && command === "fail") {
+        const workId = requiredPosition(parsed, 0, "work-id");
+        const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "work fail");
+        assertWorkLifecycleOwner(context, { workId, projectRoot, operation: "work_fail", ...(optionalOption(parsed, "hook-event-id") ? { hookEventId: optionalOption(parsed, "hook-event-id") } : {}) });
+        return failWork(context, workId, requiredOption(parsed, "reason"));
     }
-    if (family === "work" && command === "fail")
-        return failWork(context, requiredPosition(parsed, 0, "work-id"), requiredOption(parsed, "reason"));
     if (family === "work" && command === "cancel")
         return cancelWork(context, requiredPosition(parsed, 0, "work-id"), requiredOption(parsed, "reason"));
     if (family === "work" && command === "retry")
@@ -882,8 +896,17 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         const resultStdin = hasOption(parsed, "result-stdin");
         const retryCheckId = optionalOption(parsed, "retry-check");
         const retryReason = optionalOption(parsed, "reason");
+        const hookEventId = optionalOption(parsed, "hook-event-id");
         if (retryCheckId && !retryReason?.trim())
             throw new AppError("usage", "--retry-check requires --reason explaining the recovered environment", 2);
+        const protectedLifecycle = (stage === "specify" && isVnextSpecifyRun(context, { projectRoot, runId }))
+            || (stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot, runId }))
+            || (stage === "plan" && isVnextPlanRun(context, { projectRoot, runId }))
+            || (stage === "plan-review" && isVnextPlanReviewRun(context, { projectRoot, runId }))
+            || (stage === "code" && isVnextPlanRun(context, { projectRoot, runId }))
+            || (stage === "code-review" && isVnextCodeReviewRun(context, { projectRoot, runId }));
+        if (protectedLifecycle)
+            assertStageLifecycleOwner(context, { projectRoot, runId, stage, operation: "stage_finish", ...(hookEventId ? { hookEventId } : {}) });
         if (stage === "specify" && isVnextSpecifyRun(context, { projectRoot, runId })) {
             const outcome = optionalOption(parsed, "outcome");
             if (!outcome || !["specified", "failed", "cancelled"].includes(outcome)) {
@@ -949,11 +972,23 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
     if (family === "stage" && command === "pause") {
         if (!hasOption(parsed, "question-stdin"))
             throw new AppError("usage", "stage pause requires --question-stdin", 2);
+        const projectRoot = requiredOption(parsed, "project-root");
+        const runId = requiredPosition(parsed, 0, "run-id");
+        const stage = requiredOption(parsed, "stage");
+        const workId = requiredOption(parsed, "work");
+        const protectedLifecycle = (stage === "specify" && isVnextSpecifyRun(context, { projectRoot, runId }))
+            || (stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot, runId }))
+            || (stage === "plan" && isVnextPlanRun(context, { projectRoot, runId }))
+            || (stage === "plan-review" && isVnextPlanReviewRun(context, { projectRoot, runId }))
+            || (stage === "code" && isVnextPlanRun(context, { projectRoot, runId }))
+            || (stage === "code-review" && isVnextCodeReviewRun(context, { projectRoot, runId }));
+        if (protectedLifecycle)
+            assertStageLifecycleOwner(context, { projectRoot, runId, stage, workId, operation: "stage_pause", ...(optionalOption(parsed, "hook-event-id") ? { hookEventId: optionalOption(parsed, "hook-event-id") } : {}) });
         return pauseStageForUser(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            runId: requiredPosition(parsed, 0, "run-id"),
-            stage: requiredOption(parsed, "stage"),
-            workId: requiredOption(parsed, "work"),
+            projectRoot,
+            runId,
+            stage,
+            workId,
             question: await readStdin(io.stdin)
         });
     }
@@ -1429,6 +1464,24 @@ function dispatchSession(context, command, parsed) {
     throw new AppError("usage", `Unknown session command: ${command ?? "<empty>"}`, 2);
 }
 function dispatchRun(context, command, parsed) {
+    if (command === "recovery") {
+        const action = requiredPosition(parsed, 0, "recovery action");
+        const projectRoot = requiredOption(parsed, "project-root");
+        const runId = requiredPosition(parsed, 1, "run-id");
+        if (action === "inspect")
+            return inspectRunRecovery(context, { projectRoot, runId });
+        if (action === "begin")
+            return beginRunRecovery(context, { projectRoot, runId, interruption: requiredOption(parsed, "interruption-json") });
+        if (action === "seal")
+            return sealRunRecovery(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), settlement: requiredOption(parsed, "settlement-json") });
+        if (action === "capture")
+            return recordRecoveryCapture(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), capturePath: requiredOption(parsed, "capture-path") });
+        if (action === "resume")
+            return resumeRunRecovery(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), daemonId: requiredOption(parsed, "daemon-id"), harness: requiredOption(parsed, "harness"), nativeSessionId: requiredOption(parsed, "native-session-id") });
+        if (action === "accept")
+            return acceptRunRecovery(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), ...(optionalOption(parsed, "hook-event-id") ? { hookEventId: optionalOption(parsed, "hook-event-id") } : {}) });
+        throw new AppError("usage", "Use: dd-flow run recovery inspect|begin|seal|capture|resume|accept", 2);
+    }
     if (command === "snapshot") {
         const action = requiredPosition(parsed, 0, "snapshot action");
         if (action === "bootstrap") {
@@ -1448,9 +1501,10 @@ function dispatchRun(context, command, parsed) {
         if (action === "create") {
             const candidate = parsed.options.has("candidate");
             const incomplete = parsed.options.has("incomplete");
+            const recoveryId = optionalOption(parsed, "recovery-id");
             const stageEntry = optionalOption(parsed, "stage-entry");
-            if (Number(candidate) + Number(incomplete) + Number(stageEntry !== undefined) !== 1)
-                throw new AppError("usage", "Use exactly one of --candidate, --incomplete or --stage-entry", 2);
+            if (Number(candidate) + Number(incomplete) + Number(stageEntry !== undefined) + Number(recoveryId !== undefined) !== 1)
+                throw new AppError("usage", "Use exactly one of --candidate, --incomplete, --recovery-id or --stage-entry", 2);
             const input = {
                 projectRoot: requiredOption(parsed, "project-root"),
                 runId: requiredPosition(parsed, 1, "run-id"),
@@ -1458,6 +1512,8 @@ function dispatchRun(context, command, parsed) {
             };
             if (incomplete)
                 return createEvalRunSnapshot(context, { ...input, incomplete: true });
+            if (recoveryId)
+                return createEvalRunSnapshot(context, { ...input, recoveryId });
             return candidate
                 ? createEvalRunSnapshot(context, { ...input, candidate: true })
                 : createEvalRunSnapshot(context, { ...input, stageEntry: stageEntry });
@@ -1465,6 +1521,7 @@ function dispatchRun(context, command, parsed) {
         if (action === "restore")
             return restoreEvalRunSnapshot(context, {
                 snapshot: requiredOption(parsed, "snapshot"),
+                ...(optionalOption(parsed, "recovery-id") ? { recoveryId: requiredOption(parsed, "recovery-id") } : {}),
                 projectRoot: requiredOption(parsed, "project-root")
             });
         throw new AppError("usage", "Use: dd-flow run snapshot bootstrap create|restore | dd-flow run snapshot create <RUN> (--stage-entry <stage>|--candidate) --project-root <path> --output <directory> | dd-flow run snapshot restore --snapshot <directory> --project-root <path>", 2);

package/dist/services/dashboard.js

@@ -19,6 +19,8 @@ export function getCmuxStatus(context, input) {
 }
 export function renderDashboard(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    if (projectRecoveryGuarded(context, project.id))
+        throw new AppError("run_recovery_guarded", "Project dashboard is frozen while its RUN is retained for recovery", 1);
     const format = parseDashboardFormat(input.format);
     if (format === "html") {
         if (input.protocol) {
@@ -170,6 +172,10 @@ export function refreshAllDashboards(context, input = {}) {
 }
 export function autoRefreshDashboards(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    // Hooks and usage ingestion continue to record receipts after capture.
+    // Their derived timestamp must not mutate the captured workspace.
+    if (projectRecoveryGuarded(context, project.id))
+        return { ok: true, skipped: true, reason: "run_recovery_guarded" };
     const config = readProjectConfig(context, project.id);
     if (!config.dashboard.auto_refresh) {
         return { ok: true, skipped: true, reason: "dashboard_auto_refresh_disabled" };
@@ -196,6 +202,9 @@ export function autoRefreshDashboards(context, input) {
     }
     return result;
 }
+function projectRecoveryGuarded(context, projectId) {
+    return Boolean(context.db.get("SELECT 1 FROM run_recovery_guards WHERE project_id = ? AND status IN ('draining', 'sealed', 'resuming') LIMIT 1", [projectId]));
+}
 export function dashboardSummary(context, projectId, projectRoot) {
     const config = readProjectConfig(context, projectId);
     return {

package/dist/services/engines.js

@@ -174,7 +174,9 @@ export function routeArgsThroughEngine(context, args, io, stdin, env, resolvedPr
     if (!selection.selected)
         return Promise.resolve(null);
     const current = getCliBuildInfo();
-    if (selection.selected.package_name === current.package_name && selection.selected.package_version === current.version) {
+    const currentRoot = findPackageRoot(path.dirname(sourceFile));
+    if (selection.selected.package_name === current.package_name && selection.selected.package_version === current.version
+        && currentRoot !== null && fs.realpathSync(selection.selected.snapshot_root) === fs.realpathSync(currentRoot)) {
         return Promise.resolve({ routed: true, exitCode: 0, inProcess: true });
     }
     const entrypoint = resolveManifestEntrypoint(selection.selected);
@@ -383,11 +385,7 @@ export function selectEngine(context, input, options = {}, classification = inpu
     const manifests = readInstalledManifests(engineStoreRoot(context.ddFlowHome))
         .filter((manifest) => manifest.package_name === packageName)
         .filter((manifest) => requiredRange !== null && satisfiesRange(manifest.package_version, requiredRange))
-        .filter((manifest) => options.allowCurrentInProcess
-        && manifest.package_name === build.package_name
-        && manifest.package_version === build.version
-        ? true
-        : manifestHealthy(manifest))
+        .filter((manifest) => manifestHealthy(manifest))
         .sort((a, b) => {
         const versionOrder = compareSemverStrings(b.package_version, a.package_version);
         if (versionOrder !== 0)