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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/dd-flow-cli
 
+## 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.19",
+  "cli_commit": "02648aa2db37e9332089ca941b06f5735b563496",
+  "built_at": "2026-09-06T13:33:22.164Z",
   "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,7 +155,8 @@ 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 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> --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
@@ -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 { 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);
@@ -765,11 +771,18 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         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 +895,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 +971,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 +1463,22 @@ 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") });
+        throw new AppError("usage", "Use: dd-flow run recovery inspect|begin|seal|capture|resume", 2);
+    }
     if (command === "snapshot") {
         const action = requiredPosition(parsed, 0, "snapshot action");
         if (action === "bootstrap") {
@@ -1448,9 +1498,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 +1509,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 });

package/dist/services/eval-snapshots.js

@@ -55,7 +55,13 @@ export function createEvalRunSnapshot(context, input) {
     const project = requireProjectByRoot(context, projectRoot);
     const status = getFlowRunStatus(context, { projectRoot, runId: input.runId });
     assertDedicatedHome(context, project.id, input.runId);
-    if (input.incomplete) { /* Forensic evidence is not an accepted or restorable boundary. */ }
+    const recovery = typeof input.recoveryId === "string";
+    if (recovery) {
+        const guard = context.db.get("SELECT status, recovery_id FROM run_recovery_guards WHERE project_id = ? AND run_id = ? AND recovery_id = ?", [project.id, input.runId, input.recoveryId]);
+        if (!guard || guard.status !== "sealed")
+            throw new AppError("recovery_invalid_state", "Recovery snapshots require the matching sealed recovery guard", 1, { run_id: input.runId, recovery_id: input.recoveryId ?? null, status: guard?.status ?? null });
+    }
+    if (input.incomplete || recovery) { /* Recovery captures only after the runner seals all writers. */ }
     else if (input.candidate)
         assertTerminalCandidate(status.index.stage_runs ?? []);
     else if (input.stageEntry)
@@ -66,7 +72,7 @@ export function createEvalRunSnapshot(context, input) {
     const activeChildren = input.candidate
         ? context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND status IN ('created', 'running', 'paused')", [project.id, input.runId])?.count ?? 0
         : context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND (status IN ('running', 'paused') OR (status = 'created' AND (? IS NULL OR COALESCE(result_schema, '') NOT LIKE ?)))", [project.id, input.runId, allowedCreatedResultSchema, allowedCreatedResultSchema ? `${allowedCreatedResultSchema}@%` : ""])?.count ?? 0;
-    if (!input.incomplete && activeChildren > 0)
+    if (!input.incomplete && !recovery && activeChildren > 0)
         throw new AppError("snapshot_not_quiescent", `${input.candidate ? "Candidate" : "Stage-entry"} snapshot requires no active child Work`, 1, { run_id: input.runId, active_children: activeChildren });
     const output = path.resolve(input.output);
     if (fs.existsSync(output))
@@ -103,9 +109,9 @@ export function createEvalRunSnapshot(context, input) {
         project_id: project.id,
         project_root: projectRoot,
         dd_flow_home: context.ddFlowHome,
-        purpose: input.incomplete ? "incomplete" : input.candidate ? "candidate" : "stage_entry",
-        stage_entry: input.incomplete || input.candidate ? null : input.stageEntry,
-        ...(input.incomplete ? { consistency: "sqlite_read_snapshot_files_copied_nonatomically", active_child_work_count: activeChildren, restorable: false } : {}),
+        purpose: input.incomplete ? "incomplete" : recovery ? "recovery" : input.candidate ? "candidate" : "stage_entry",
+        stage_entry: input.incomplete || recovery || input.candidate ? null : input.stageEntry,
+        ...(input.incomplete ? { consistency: "sqlite_read_snapshot_files_copied_nonatomically", active_child_work_count: activeChildren, restorable: false } : recovery ? { recovery_id: input.recoveryId, consistency: "sealed_writer_barrier_required", active_child_work_count: activeChildren, restorable: "same-runtime-or-explicit-restore" } : {}),
         created_at: context.now(),
         runtime_sha256: treeHash(path.join(output, "runtime")),
         project_sha256: treeHash(path.join(output, "project")),
@@ -129,6 +135,8 @@ export function restoreEvalRunSnapshot(context, input) {
     const manifest = readManifest(snapshot);
     if (manifest.purpose === "incomplete")
         throw new AppError("snapshot_incomplete_not_restorable", "Incomplete snapshot is forensic evidence, not a stage-entry fixture", 1, { snapshot });
+    if (manifest.purpose === "recovery")
+        throw new AppError("snapshot_recovery_requires_explicit_restore", "Recovery snapshots require the recovery runner; they are not a generic stage-entry fixture", 1, { snapshot });
     if (manifest.purpose === "candidate")
         throw new AppError("snapshot_candidate_not_restorable", "A terminal candidate snapshot is evidence, not a stage-entry fixture", 1, { snapshot });
     if (!manifest.stage_entry)
@@ -383,7 +391,7 @@ function readManifest(snapshot) {
     if (!fs.existsSync(file))
         throw new AppError("snapshot_missing", "Snapshot manifest is missing", 1, { snapshot });
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (value.schema_id !== "dd-flow/eval-run-snapshot@5" || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate", "incomplete"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose !== "stage_entry" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
+    if (value.schema_id !== "dd-flow/eval-run-snapshot@5" || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate", "incomplete", "recovery"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose !== "stage_entry" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
         throw new AppError("snapshot_invalid", "Snapshot manifest is invalid", 1, { snapshot });
     if (!value.project_git.branch || !value.project_git.head || !value.project_git.bundle_sha256)
         throw new AppError("snapshot_invalid", "Snapshot project Git metadata is incomplete", 1, { snapshot });

package/dist/services/hooks.js

@@ -285,7 +285,7 @@ export function handleCodexHook(context, input) {
         return { ok: true, observed: false, reason: "event_not_participating", event: eventName };
     // Resume legitimately receives an answer through stdin. It is matched by
     // immutable lifecycle arguments below; never reject or rewrite that pipe.
-    if (lifecycle.analysis.kind === "compound") {
+    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
         return {
             ok: false,
             observed: false,
@@ -299,14 +299,25 @@ export function handleCodexHook(context, input) {
             }
         };
     }
-    const { flowPayload, stageStart, stageResume, workStart, bootstrapStageStart, commandProjectRoot } = lifecycle;
+    const { flowPayload, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, bootstrapStageStart, commandProjectRoot } = lifecycle;
     const matchKey = commandProjectRoot ? lifecycleMatchKey(lifecycle, commandProjectRoot) : null;
     // A bootstrap stage is the first stateful command for a new materialized project.
     // Its PreToolUse event arrives before stage start can register that project.
     if (bootstrapStageStart && commandProjectRoot) {
         registerProject(context, { root: commandProjectRoot });
     }
-    const project = projectForHook(context, input.projectRoot ?? commandProjectRoot, stringValue(payload.cwd));
+    let project;
+    try {
+        project = projectForHook(context, input.projectRoot ?? commandProjectRoot, stringValue(payload.cwd));
+    }
+    catch (error) {
+        // A terminal command outside a registered flow gets no trusted receipt;
+        // the CLI will fail closed if it is actually executed. This keeps hooks
+        // inert for unrelated shell-parser probes and stale project directories.
+        if (stageFinish || stagePause || workFinish || workFail)
+            return { ok: true, observed: false, reason: "project_not_registered" };
+        throw error;
+    }
     if (!project)
         return { ok: true, observed: false, reason: "unrelated_cwd" };
     // Codex retains the root session_id for a thread-spawned child, while the
@@ -364,7 +375,7 @@ export function handleCodexHook(context, input) {
         session: providerSessionId ? nativeSessionIdentity("codex-desktop", providerSessionId) : null,
         ...(parentProviderSessionId ? { parent_session: nativeSessionIdentity("codex-desktop", parentProviderSessionId) } : {}),
         protocol_id: protocolId,
-        ...(providerSessionId && (flowPayload || stageStart || stageResume || workStart)
+        ...(providerSessionId && (flowPayload || stageStart || stageFinish || stagePause || stageResume || workStart || workFinish || workFail)
             ? {
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
@@ -414,7 +425,7 @@ export function handleZcodeEvent(context, input) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound") {
+    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
         throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone ZCode Bash tool call", 1, {
             standalone_command: lifecycle.invocation.command
         });
@@ -521,12 +532,12 @@ export function handleGrokEvent(context, input) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound") {
+    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
         throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone Grok Build tool call", 1, {
             standalone_command: lifecycle.invocation.command
         });
     }
-    const { flowPayload, stageStart, stageResume, workStart, bootstrapStageStart, commandProjectRoot } = lifecycle;
+    const { flowPayload, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, bootstrapStageStart, commandProjectRoot } = lifecycle;
     const expectedRoot = resolveProjectRoot(input.projectRoot);
     if (commandProjectRoot && resolveProjectRoot(commandProjectRoot) !== expectedRoot) {
         throw new AppError("project_mismatch", "Grok Build lifecycle command project root does not match the controlled workspace", 1, {
@@ -570,7 +581,7 @@ export function handleGrokEvent(context, input) {
     });
     const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: eventKey, session: nativeSessionIdentity("grok-acp", providerSessionId),
         ...(isChild ? { parent_session: nativeSessionIdentity("grok-acp", stringValue(ddGrok.parentProviderSessionId) ?? rootProviderSessionId) } : {}), daemon_id: daemonId ?? null };
-    return (flowPayload || stageStart || stageResume || workStart)
+    return (flowPayload || stageStart || stageFinish || stagePause || stageResume || workStart || workFinish || workFail)
         ? { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...(rawInput ?? {}), command: commandWithHookEvent(command, eventKey) } } }
         : result;
 }
@@ -635,7 +646,7 @@ function handleControlledToolEvent(context, input, event, harness) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound") {
+    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
         throw new AppError("compound_lifecycle_command", `dd-flow lifecycle commands must be a standalone ${label} shell tool call`, 1, { standalone_command: lifecycle.invocation.command });
     }
     const { flowPayload, bootstrapStageStart, commandProjectRoot } = lifecycle;
@@ -747,25 +758,39 @@ function lifecycleFacts(command) {
         return null;
     const invocation = analysis.invocation;
     const stageStart = invocation.operation === "stage_start";
+    const stageFinish = invocation.operation === "stage_finish";
+    const stagePause = invocation.operation === "stage_pause";
     const stageResume = invocation.operation === "stage_resume";
     const workStart = invocation.operation === "work_start";
+    const workFinish = invocation.operation === "work_finish";
+    const workFail = invocation.operation === "work_fail";
     return {
         analysis,
         invocation,
         flowPayload: flowSessionPayloadFromRegisterCommand(invocation),
         stageStart,
+        stageFinish,
+        stagePause,
         stageResume,
-        workStart,
+        workStart, workFinish, workFail,
         bootstrapStageStart: stageStart && commandHasOption(invocation, "bootstrap"),
         commandProjectRoot: commandOption(invocation, "project-root"),
-        stageName: stageStart || stageResume ? commandOption(invocation, "stage") : undefined,
-        runId: stageStart || stageResume ? commandPosition(invocation, 0) : undefined,
-        workId: stageResume ? commandOption(invocation, "work") : workStart ? commandPosition(invocation, 0) : undefined,
+        stageName: stageStart || stageFinish || stagePause || stageResume ? commandOption(invocation, "stage") : undefined,
+        runId: stageStart || stageFinish || stagePause || stageResume ? commandPosition(invocation, 0) : undefined,
+        workId: stagePause || stageResume ? commandOption(invocation, "work") : workStart || workFinish || workFail ? commandPosition(invocation, 0) : undefined,
         contextSha256: commandOption(invocation, "context-sha256")
     };
 }
+// Worker completion and the two HITL commands intentionally take their
+// payload from stdin. Their generated pipe/heredoc is one lifecycle command,
+// not a second authority. Everything else remains standalone-only.
+function allowsStdinLifecycleCompound(facts) {
+    const operation = facts.invocation.operation;
+    return (operation === "work_finish" && commandHasOption(facts.invocation, "result-stdin"))
+        || ((operation === "stage_pause" || operation === "stage_resume") && facts.invocation.heredoc);
+}
 function lifecycleMatchKey(facts, projectRoot) {
-    const { invocation, bootstrapStageStart, stageStart, stageResume, workStart, stageName, runId, workId, contextSha256 } = facts;
+    const { invocation, bootstrapStageStart, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, stageName, runId, workId, contextSha256 } = facts;
     if (bootstrapStageStart)
         return bootstrapMatchKey({
             projectRoot,
@@ -775,12 +800,58 @@ function lifecycleMatchKey(facts, projectRoot) {
         });
     if (stageStart && runId && stageName)
         return stageStartMatchKey(runId, stageName, projectRoot, contextSha256);
+    if (stageFinish && runId && stageName)
+        return stageLifecycleMatchKey("stage_finish", runId, stageName, projectRoot);
+    if (stagePause && runId && stageName && workId)
+        return stageLifecycleMatchKey("stage_pause", runId, stageName, projectRoot, workId);
     if (stageResume && runId && stageName && workId)
         return stageResumeMatchKey(runId, stageName, workId, projectRoot);
     if (workStart && workId)
         return workStartMatchKey(workId, projectRoot);
+    if (workFinish && workId)
+        return workLifecycleMatchKey("work_finish", workId, projectRoot);
+    if (workFail && workId)
+        return workLifecycleMatchKey("work_fail", workId, projectRoot);
     return null;
 }
+export function stageLifecycleMatchKey(operation, runId, stage, projectRoot, workId) {
+    return crypto.createHash("sha256").update(JSON.stringify({ operation, run_id: runId, stage, project_root: resolveProjectRoot(projectRoot), ...(workId ? { work_id: workId } : {}) })).digest("hex");
+}
+export function workLifecycleMatchKey(operation, workId, projectRoot) {
+    return crypto.createHash("sha256").update(JSON.stringify({ operation, work_id: workId, project_root: resolveProjectRoot(projectRoot) })).digest("hex");
+}
+/** Claims a Work terminal command only after its exact hook receipt has proved
+ * the physical Session that issued it. Work code performs the owner check. */
+export function claimWorkLifecycleHookEvent(context, input) {
+    const matchKey = workLifecycleMatchKey(input.operation, input.workId, input.projectRoot);
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, {
+        projectId: input.projectId, matchKey, errorCode: "trusted_session_binding_required", operation: input.operation.replace("_", " ")
+    }).eventKey;
+    const event = context.db.get("SELECT id, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, eventKey]);
+    if (!event?.session_id || event.status !== "observed" || event.match_key !== matchKey) {
+        throw new AppError("trusted_session_binding_required", `${input.operation.replace("_", " ")} requires one fresh matching PreToolUse hook event`, 1, { work_id: input.workId, event_key: eventKey });
+    }
+    const claimed = context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [context.now(), event.id]);
+    if (claimed.changes !== 1)
+        throw new AppError("trusted_session_binding_required", "matching Work lifecycle hook event was already claimed", 1, { work_id: input.workId });
+    return hookSessionIdentity(context, input.projectId, eventKey);
+}
+/** Claims a lifecycle command only after its exact hook receipt has proved the
+ * physical Session that issued it. Stage code performs the Work-owner check. */
+export function claimStageLifecycleHookEvent(context, input) {
+    const matchKey = stageLifecycleMatchKey(input.operation, input.runId, input.stage, input.projectRoot, input.workId);
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, {
+        projectId: input.projectId, matchKey, errorCode: "trusted_session_binding_required", operation: input.operation.replace("_", " ")
+    }).eventKey;
+    const event = context.db.get("SELECT id, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, eventKey]);
+    if (!event?.session_id || event.status !== "observed" || event.match_key !== matchKey) {
+        throw new AppError("trusted_session_binding_required", `${input.operation.replace("_", " ")} requires one fresh matching PreToolUse hook event`, 1, { run_id: input.runId, stage: input.stage, event_key: eventKey });
+    }
+    const claimed = context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [context.now(), event.id]);
+    if (claimed.changes !== 1)
+        throw new AppError("trusted_session_binding_required", "matching lifecycle hook event was already claimed", 1, { run_id: input.runId, stage: input.stage });
+    return hookSessionIdentity(context, input.projectId, eventKey);
+}
 /** Trusted session identity is created by PreToolUse, never supplied by an agent. */
 export function sessionIdForHookEvent(context, projectId, eventKey) {
     const event = context.db.get("SELECT session_id FROM hook_events WHERE project_id = ? AND event_key = ?", [projectId, eventKey]);

package/dist/services/lifecycle-command.js

@@ -175,10 +175,18 @@ function lifecycleOperation(argv) {
         return "session_register";
     if (key === "stage start")
         return "stage_start";
+    if (key === "stage finish")
+        return "stage_finish";
+    if (key === "stage pause")
+        return "stage_pause";
     if (key === "stage resume")
         return "stage_resume";
     if (key === "work start")
         return "work_start";
+    if (key === "work finish")
+        return "work_finish";
+    if (key === "work fail")
+        return "work_fail";
     return null;
 }
 export function parseCommandArgs(argv) {

package/dist/services/run-recovery.js

@@ -0,0 +1,104 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { requireProjectByRoot } from "./projects.js";
+import { appendFlowRunTimelineEvent } from "./runs.js";
+function requireRun(context, projectId, runId) {
+    const run = context.db.get("SELECT r.id, r.run_root, r.workspace_root, p.root AS project_root FROM runs r JOIN projects p ON p.id = r.project_id WHERE r.project_id = ? AND r.id = ?", [projectId, runId]);
+    if (!run?.run_root)
+        throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1, { run_id: runId });
+    return run;
+}
+function parseObject(value, label) { try {
+    const parsed = JSON.parse(value);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+        return parsed;
+}
+catch { /* validated below */ } throw new AppError("validation", `${label} must be a JSON object`, 2); }
+export function recoveryGuard(context, projectId, runId) { return context.db.get("SELECT recovery_id, project_id, run_id, generation, status, interruption_json, settlement_json, capture_path, created_at, updated_at, sealed_at, resumed_at FROM run_recovery_guards WHERE project_id = ? AND run_id = ? ORDER BY generation DESC LIMIT 1", [projectId, runId]) ?? null; }
+export function assertRunMutationAllowed(context, projectId, runId) { const guard = recoveryGuard(context, projectId, runId); if (guard && ["draining", "sealed", "resuming"].includes(guard.status))
+    throw new AppError("run_recovery_guarded", "RUN is retained for recovery; reconcile or resume its recovery operation before accepting a new lifecycle mutation", 1, { run_id: runId, recovery_id: guard.recovery_id, generation: guard.generation, status: guard.status }); }
+export function beginRunRecovery(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const interruption = parseObject(input.interruption, "interruption");
+    const prior = recoveryGuard(context, project.id, run.id);
+    if (prior && ["draining", "sealed", "resuming"].includes(prior.status))
+        return { ok: true, recovery: { ...prior, interruption: JSON.parse(prior.interruption_json) }, reused: true };
+    const recoveryId = `RCV-${crypto.randomUUID()}`, generation = (prior?.generation ?? 0) + 1, now = context.now();
+    context.db.run("INSERT INTO run_recovery_guards (recovery_id, project_id, run_id, generation, status, interruption_json, settlement_json, capture_path, created_at, updated_at, sealed_at, resumed_at) VALUES (?, ?, ?, ?, 'draining', ?, NULL, NULL, ?, ?, NULL, NULL)", [recoveryId, project.id, run.id, generation, JSON.stringify(interruption), now, now]);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_draining", recovery_id: recoveryId, generation, interruption });
+    return { ok: true, recovery: { recovery_id: recoveryId, run_id: run.id, generation, status: "draining", interruption } };
+}
+export function sealRunRecovery(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const guard = recoveryGuard(context, project.id, run.id);
+    if (!guard || guard.recovery_id !== input.recoveryId)
+        throw new AppError("recovery_not_found", "Recovery operation is not registered for this RUN", 1, { recovery_id: input.recoveryId, run_id: run.id });
+    const settlement = parseObject(input.settlement, "settlement");
+    if (settlement.settled !== true)
+        throw new AppError("recovery_not_settled", "Recovery capture requires an explicit settled tree receipt", 1, { recovery_id: guard.recovery_id });
+    if (guard.status === "sealed")
+        return { ok: true, recovery: { ...guard, settlement: JSON.parse(guard.settlement_json ?? "{}") }, reused: true };
+    if (guard.status !== "draining")
+        throw new AppError("recovery_invalid_state", "Recovery is not draining", 1, { recovery_id: guard.recovery_id, status: guard.status });
+    const now = context.now();
+    context.db.run("UPDATE run_recovery_guards SET status = 'sealed', settlement_json = ?, sealed_at = ?, updated_at = ? WHERE recovery_id = ? AND status = 'draining'", [JSON.stringify(settlement), now, now, guard.recovery_id]);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_sealed", recovery_id: guard.recovery_id, generation: guard.generation, settlement });
+    return { ok: true, recovery: { recovery_id: guard.recovery_id, run_id: run.id, generation: guard.generation, status: "sealed", settlement } };
+}
+export function recordRecoveryCapture(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const guard = recoveryGuard(context, project.id, run.id);
+    if (!guard || guard.recovery_id !== input.recoveryId || guard.status !== "sealed")
+        throw new AppError("recovery_invalid_state", "Recovery capture requires a sealed recovery operation", 1, { recovery_id: input.recoveryId, run_id: run.id });
+    const capture = path.resolve(input.capturePath);
+    if (!fs.existsSync(capture))
+        throw new AppError("recovery_capture_missing", "Recovery capture path is unavailable", 1, { capture });
+    context.db.run("UPDATE run_recovery_guards SET capture_path = ?, updated_at = ? WHERE recovery_id = ?", [capture, context.now(), guard.recovery_id]);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_capture_ready", recovery_id: guard.recovery_id, capture_path: capture });
+    return { ok: true, recovery_id: guard.recovery_id, capture_path: capture };
+}
+export function resumeRunRecovery(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const guard = recoveryGuard(context, project.id, run.id);
+    if (!guard || guard.recovery_id !== input.recoveryId)
+        throw new AppError("recovery_not_found", "Recovery operation is not registered for this RUN", 1, { recovery_id: input.recoveryId, run_id: run.id });
+    if (guard.status === "recovered")
+        return { ok: true, recovery_id: guard.recovery_id, generation: guard.generation, resumed: true, reused: true };
+    if (guard.status !== "sealed" || !guard.capture_path)
+        throw new AppError("recovery_capture_required", "Recovery must be sealed and captured before it can resume", 1, { recovery_id: guard.recovery_id, status: guard.status });
+    // The root coordinator keeps its same native Session and receives a recovery
+    // prompt from the eval runner. Only delegated Work is returned to the ready
+    // graph and therefore gets a fresh, addressable recovery packet.
+    const now = context.now(), running = context.db.all("SELECT work_id, started_at, status FROM works WHERE project_id = ? AND run_id = ? AND status = 'running' AND parent_work_id IS NOT NULL ORDER BY work_id", [project.id, run.id]);
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        for (const work of running) {
+            const evidence = path.join(run.run_root, "recoveries", guard.recovery_id, "works", work.work_id), source = path.join(run.run_root, "works", work.work_id);
+            fs.mkdirSync(path.dirname(evidence), { recursive: true });
+            if (fs.existsSync(source) && !fs.existsSync(evidence))
+                fs.cpSync(source, evidence, { recursive: true, verbatimSymlinks: true });
+            context.db.run("INSERT INTO work_recovery_segments (recovery_id, work_id, generation, prior_started_at, evidence_path, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'prepared', ?, ?)", [guard.recovery_id, work.work_id, guard.generation, work.started_at, evidence, now, now]);
+            context.db.run("UPDATE work_sessions SET status = 'interrupted', completed_at = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [now, now, work.work_id]);
+            context.db.run("UPDATE works SET status = 'created', result = NULL, started_at = NULL, completed_at = NULL, updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
+        }
+        context.db.run("UPDATE run_recovery_guards SET status = 'recovered', resumed_at = ?, updated_at = ? WHERE recovery_id = ? AND status = 'sealed'", [now, now, guard.recovery_id]);
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_resumed", recovery_id: guard.recovery_id, generation: guard.generation, interrupted_works: running.map((work) => work.work_id) });
+    return { ok: true, recovery_id: guard.recovery_id, generation: guard.generation, resumed: true, interrupted_works: running.map((work) => work.work_id) };
+}
+export function recoveryPromptForWork(context, workId) { const row = context.db.get("SELECT recovery_id, generation, evidence_path FROM work_recovery_segments WHERE work_id = ? AND status = 'prepared' ORDER BY generation DESC LIMIT 1", [workId]); return row ? { recoveryId: row.recovery_id, generation: row.generation, evidencePath: row.evidence_path } : null; }
+export function activateRecoveryWork(context, workId) { context.db.run("UPDATE work_recovery_segments SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'prepared'", [context.now(), workId]); }
+export function settleRecoveryWork(context, workId, status) { context.db.run("UPDATE work_recovery_segments SET status = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [status, context.now(), workId]); }
+export function inspectRunRecovery(context, input) { const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)); const run = requireRun(context, project.id, input.runId); const guard = recoveryGuard(context, project.id, run.id); const works = context.db.all("SELECT w.work_id, w.status, s.recovery_id, s.status AS segment_status FROM works w LEFT JOIN work_recovery_segments s ON s.work_id = w.work_id AND s.generation = (SELECT MAX(generation) FROM work_recovery_segments latest WHERE latest.work_id = w.work_id) WHERE w.project_id = ? AND w.run_id = ? ORDER BY w.work_id", [project.id, run.id]); return { ok: true, run_id: run.id, recovery: guard ? { ...guard, interruption: JSON.parse(guard.interruption_json), settlement: guard.settlement_json ? JSON.parse(guard.settlement_json) : null } : null, works }; }

package/dist/services/stage-lifecycle.js

@@ -18,6 +18,7 @@ import { registerProject } from "./projects.js";
 import { registerProtocol } from "./protocols.js";
 import { previewNextEntityId } from "./ids.js";
 import { hookSessionIdentity, sessionIdForHookEvent } from "./hooks.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
 const stagePromptSections = [
     "stage_identity",
     "authoritative_runtime_facts",
@@ -119,6 +120,7 @@ export function startStage(context, input) {
     if (!runId)
         throw new AppError("usage", "stage start requires a RUN id or --bootstrap", 2);
     const before = runView(getFlowRunStatus(context, { projectRoot, runId }));
+    assertRunMutationAllowed(context, before.run.project_id, before.run.id);
     const dir = input.dir ?? defaultStageDir(input.stage, before.run.flow_kind);
     const attached = runView(attachFlowRunStage(context, {
         projectRoot,
@@ -263,6 +265,7 @@ export function finishStage(context, input) {
         throw new AppError("usage", "stage finish requires a RUN id", 2);
     const runId = input.runId;
     const view = runView(getFlowRunStatus(context, { projectRoot, runId }));
+    assertRunMutationAllowed(context, view.run.project_id, view.run.id);
     const existing = view.index.stage_runs?.find((stage) => stage.stage === input.stage);
     if (!existing) {
         throw new AppError("not_found", `Run stage is not attached: ${input.stage}`, 1, { run_id: view.run.id, stage: input.stage });

package/dist/services/vnext-fanout.js

@@ -135,3 +135,43 @@ export async function reconcileVnextFanout(context, input) {
     appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "native_child_reconciliation", stage: input.stage, observations: value, issues, reconciled });
     return { ok: true, issues, reconciled };
 }
+/**
+ * Records every terminal native child at the Stage where it is first observed.
+ * This is separate from fan-out settlement: a historical child can be valid
+ * evidence for an earlier Work, while an unbound terminal child is retained
+ * as an inconsistency instead of being rediscovered in a later review wave.
+ */
+export function observeVnextNativeChildren(context, input) {
+    const value = input.observations;
+    if (!value || typeof value.harness_id !== "string" || !value.harness_id || typeof value.parent_session_id !== "string" || !Array.isArray(value.children)
+        || value.children.some(child => !child || typeof child.session_id !== "string" || !["running", "unknown", "completed", "failed", "cancelled"].includes(String(child.status))))
+        throw new AppError("usage", "Expected native observations: harness_id, parent_session_id and children[{session_id,status}]", 2);
+    if (new Set(value.children.map(child => child.session_id)).size !== value.children.length)
+        throw new AppError("usage", "Native observations must contain each child Session exactly once", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const parent = storageSessionId({ harness_id: value.harness_id, session_id: value.parent_session_id });
+    const issues = [], history = [], pending = [];
+    for (const child of value.children) {
+        const sessionId = storageSessionId({ harness_id: value.harness_id, session_id: String(child.session_id) });
+        const links = context.db.all(`SELECT ws.id, ws.work_id, ws.status, w.status AS work_status, w.parent_work_id, s.current_stage
+         FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id
+         JOIN sessions s ON s.project_id = w.project_id AND s.session_id = ws.session_id
+        WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ? AND s.parent_session_id = ? ORDER BY ws.created_at`, [project.id, input.runId, sessionId, parent]);
+        if (child.status === "running" || child.status === "unknown") {
+            pending.push({ session_id: child.session_id, outcome: child.status, links: links.map(link => ({ work_id: link.work_id, work_session_id: link.id })) });
+            continue;
+        }
+        if (!links.length) {
+            issues.push({ code: "unbound_native_delegation_detected", session_id: child.session_id, outcome: child.status, detected_at_stage: input.stage, origin_stage: "unknown" });
+            continue;
+        }
+        if (links.length !== 1) {
+            issues.push({ code: "child_execution_ambiguous", session_id: child.session_id, outcome: child.status, detected_at_stage: input.stage, work_ids: links.map(link => link.work_id) });
+            continue;
+        }
+        const link = links[0];
+        history.push({ session_id: child.session_id, outcome: child.status, work_id: link.work_id, work_session_id: link.id, work_status: link.work_status, origin_stage: link.current_stage ?? "unknown", detected_at_stage: input.stage });
+    }
+    appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "native_child_observation", stage: input.stage, observations: value, issues, history, pending });
+    return { ok: true, issues, history, pending };
+}

package/dist/services/work-registry.js

@@ -2,20 +2,78 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { findRecentMatchingHookEvent, claimStageStartHookEvent, claimWorkStartHookEvent, hookSessionIdentity, workStartMatchKey } from "./hooks.js";
+import { findRecentMatchingHookEvent, claimStageLifecycleHookEvent, claimStageStartHookEvent, claimWorkLifecycleHookEvent, claimWorkStartHookEvent, hookSessionIdentity, workStartMatchKey } from "./hooks.js";
 import { validateSchema } from "./schema-validation.js";
 import { resolveProjectRoot, resolveRunReferences } from "../storage/paths.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
 import { readCodeCheckProfile, runCodeChecks, workspaceFingerprint } from "./code-checks.js";
 import { nextWorkId, nextWorkIds } from "./ids.js";
 import { appendFlowRunTimelineEvent } from "./runs.js";
+import { appendAudit } from "./audit.js";
 import { flowCommand } from "./stage-pause.js";
 import { assertPortableArtifactRef } from "./portable-refs.js";
 import { publicSessionIdentity } from "./session-identity.js";
+import { activateRecoveryWork, assertRunMutationAllowed, recoveryPromptForWork, settleRecoveryWork } from "./run-recovery.js";
 const workColumns = "work_id, project_id, run_id, parent_work_id, task, launch_policy, result_schema, payload_json, depends_on_json, status, result, created_at, started_at, updated_at, completed_at";
 export function ensureWorkRegistry(context) { context.db.exec("SELECT 1 FROM works LIMIT 1"); context.db.exec("SELECT 1 FROM work_sessions LIMIT 1"); }
+/**
+ * A Stage terminal command is allowed only from the Session that owns its
+ * running coordinator Work.  A hook receipt proves the caller; a WorkSession
+ * proves the owner.  Either fact alone is insufficient.
+ */
+export function assertStageLifecycleOwner(context, input) {
+    ensureWorkRegistry(context);
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = context.db.get("SELECT id FROM projects WHERE root = ?", [projectRoot]);
+    if (!project)
+        throw new AppError("not_found", "Project is not registered", 1, { project_root: projectRoot });
+    requireRun(context, project.id, input.runId);
+    const owner = context.db.get(`SELECT ws.id, ws.work_id, ws.session_id
+       FROM work_sessions ws
+       JOIN works w ON w.work_id = ws.work_id
+       JOIN sessions s ON s.project_id = w.project_id AND s.session_id = ws.session_id
+      WHERE w.project_id = ? AND w.run_id = ? AND ws.status = 'running'
+        AND w.status IN ('running', 'paused') AND (w.parent_work_id IS NULL OR s.current_stage = ?)
+        ${input.workId ? "AND w.work_id = ?" : ""}
+      ORDER BY ws.created_at DESC LIMIT 1`, input.workId ? [project.id, input.runId, input.stage, input.workId] : [project.id, input.runId, input.stage]);
+    if (!owner)
+        throw new AppError("trusted_session_binding_required", "Stage lifecycle command has no running coordinator Work/Session binding", 1, { run_id: input.runId, stage: input.stage, ...(input.workId ? { work_id: input.workId } : {}) });
+    const identity = claimStageLifecycleHookEvent(context, {
+        projectId: project.id, ...(input.hookEventId ? { eventKey: input.hookEventId } : {}), operation: input.operation,
+        runId: input.runId, stage: input.stage, projectRoot, ...(input.operation === "stage_pause" ? { workId: owner.work_id } : {})
+    });
+    if (identity.sessionId === owner.session_id)
+        return identity;
+    context.db.run("UPDATE hook_events SET status = 'rejected', claimed_at = ? WHERE id = ?", [context.now(), identity.hookEventId]);
+    const payload = { run_id: input.runId, stage: input.stage, work_id: owner.work_id, operation: input.operation, expected_session_id: owner.session_id, observed_session_id: identity.sessionId, hook_event_id: identity.hookEventId };
+    appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "lifecycle_caller_mismatch", ...payload });
+    appendAudit(context, { projectId: project.id, eventType: "stage.lifecycle_caller_rejected", payload });
+    throw new AppError("lifecycle_caller_mismatch", "Stage lifecycle command was issued by a Session that does not own the running Work", 1, payload);
+}
+/** A Work terminal command belongs to the Session that started that Work.
+ * Controllers can still use their explicit non-agent operations; they cannot
+ * borrow a native worker's authority by naming its Work id. */
+export function assertWorkLifecycleOwner(context, input) {
+    ensureWorkRegistry(context);
+    const work = requireWork(context, input.workId);
+    const run = requireRun(context, work.project_id, work.run_id);
+    if (resolveProjectRoot(input.projectRoot) !== resolveProjectRoot(run.project_root))
+        throw new AppError("project_mismatch", "Work lifecycle project root does not match its RUN", 1, { work_id: work.work_id });
+    const owner = context.db.get("SELECT id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, completed_at FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
+    if (!owner)
+        throw new AppError("trusted_session_binding_required", "Work lifecycle command has no running Work/Session binding", 1, { work_id: work.work_id });
+    const identity = claimWorkLifecycleHookEvent(context, { projectId: work.project_id, ...(input.hookEventId ? { eventKey: input.hookEventId } : {}), operation: input.operation, workId: work.work_id, projectRoot: run.project_root });
+    if (identity.sessionId === owner.session_id)
+        return identity;
+    context.db.run("UPDATE hook_events SET status = 'rejected', claimed_at = ? WHERE id = ?", [context.now(), identity.hookEventId]);
+    const payload = { run_id: work.run_id, work_id: work.work_id, operation: input.operation, expected_session_id: owner.session_id, observed_session_id: identity.sessionId, hook_event_id: identity.hookEventId };
+    appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: "work_lifecycle_caller_mismatch", ...payload });
+    appendAudit(context, { projectId: work.project_id, eventType: "work.lifecycle_caller_rejected", payload });
+    throw new AppError("lifecycle_caller_mismatch", "Work lifecycle command was issued by a Session that does not own the running Work", 1, payload);
+}
 export function createChildWork(context, input) {
     const parent = requireWork(context, input.parentWorkId);
+    assertRunMutationAllowed(context, parent.project_id, parent.run_id);
     if (parent.status !== "running")
         throw new AppError("invalid_work_state", "Child Work requires a running parent", 2, { parent_work_id: parent.work_id, status: parent.status });
     const id = nextWorkId(context, parent.project_id, input.slug);
@@ -46,6 +104,7 @@ export function validateWorkBatchFile(file) {
 export function addWorkBatch(context, input) {
     ensureWorkRegistry(context);
     const parent = requireWork(context, input.parentWorkId);
+    assertRunMutationAllowed(context, parent.project_id, parent.run_id);
     if (parent.status !== "running")
         throw new AppError("invalid_work_state", "Batch parent must be running", 2, { work_id: parent.work_id, status: parent.status });
     const parsed = readJson(input.file);
@@ -118,6 +177,7 @@ export function mutateWorkDeps(context, input) {
     const work = requireWork(context, input.workId);
     if (input.action === "list")
         return { work_id: work.work_id, depends_on: parseDependencies(work) };
+    assertRunMutationAllowed(context, work.project_id, work.run_id);
     if (work.status !== "created")
         throw new AppError("invalid_work_state", "Dependencies change only while Work is created", 2);
     const dependencies = new Set(parseDependencies(work));
@@ -139,7 +199,7 @@ export function mutateWorkDeps(context, input) {
     refreshRunWorkProjection(context, work.project_id, work.run_id);
     return { work_id: work.work_id, depends_on: [...dependencies] };
 }
-export function deleteWork(context, id) { const work = requireWork(context, id); const canonical = work.work_id; if (work.status !== "created" || work.started_at || context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? LIMIT 1", [canonical]) || context.db.get("SELECT 1 FROM works WHERE depends_on_json LIKE ? LIMIT 1", [`%${canonical}%`]))
+export function deleteWork(context, id) { const work = requireWork(context, id); assertRunMutationAllowed(context, work.project_id, work.run_id); const canonical = work.work_id; if (work.status !== "created" || work.started_at || context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? LIMIT 1", [canonical]) || context.db.get("SELECT 1 FROM works WHERE depends_on_json LIKE ? LIMIT 1", [`%${canonical}%`]))
     throw new AppError("invalid_work_state", "Only an unstarted unreferenced Work may be deleted", 2); context.db.run("DELETE FROM works WHERE work_id = ?", [canonical]); refreshRunWorkProjection(context, work.project_id, work.run_id); return { ok: true, deleted: canonical }; }
 export function shortWorkId(id) { return /^WRK-\d{3,}(?:-|$)/.exec(id)?.[0]?.replace(/-$/, "") ?? id; }
 /**
@@ -152,6 +212,7 @@ export function workStartCommand(context, work) { const run = requireRun(context
 export function startWork(context, id, input) {
     ensureWorkRegistry(context);
     const work = requireWork(context, id);
+    assertRunMutationAllowed(context, work.project_id, work.run_id);
     if (work.status !== "created")
         throw new AppError("invalid_work_state", "Work is not created", 2, { work_id: id, status: work.status });
     if (!isReady(context, work)) {
@@ -179,6 +240,7 @@ export function startWork(context, id, input) {
 /** Binds the already-running coordinator of a stage to its trusted hook Session. */
 export function bindRunningWorkSession(context, input) {
     const work = requireWork(context, input.workId);
+    assertRunMutationAllowed(context, work.project_id, work.run_id);
     if (work.status !== "running")
         throw new AppError("invalid_work_state", "Stage coordinator Work must be running", 1, { work_id: work.work_id, status: work.status });
     const run = requireRun(context, work.project_id, work.run_id);
@@ -231,6 +293,7 @@ export function bindRunningWorkSession(context, input) {
 /** A stage coordinator is launched by `stage start`, not by an invented nested `work start`. */
 export function bindStageCoordinatorWork(context, input) {
     const work = requireWork(context, input.workId);
+    assertRunMutationAllowed(context, work.project_id, work.run_id);
     const run = requireRun(context, work.project_id, work.run_id);
     claimStageStartHookEvent(context, { projectId: work.project_id, eventKey: input.hookEventId, runId: work.run_id, stage: input.stage, projectRoot: run.project_root, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     const snapshot = JSON.parse((context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [work.project_id, work.run_id])?.index_json) ?? "{}");
@@ -242,6 +305,7 @@ export function bindStageCoordinatorWork(context, input) {
 /** Starts a created coordinator Work from its trusted `stage start` event. */
 export function startStageCoordinatorWork(context, input) {
     const work = requireWork(context, input.workId);
+    assertRunMutationAllowed(context, work.project_id, work.run_id);
     if (work.status !== "created")
         throw new AppError("invalid_work_state", "Stage coordinator Work is not created", 2, { work_id: work.work_id, status: work.status });
     const run = requireRun(context, work.project_id, work.run_id);
@@ -256,6 +320,7 @@ export function startStageCoordinatorWork(context, input) {
 }
 /** Stage entry points call this only after their own trusted hook claim. */
 export function startBoundWork(context, work, run, identity, hookEventId) {
+    assertRunMutationAllowed(context, work.project_id, work.run_id);
     if (work.status !== "created")
         throw new AppError("invalid_work_state", "Work is not created", 2, { work_id: work.work_id, status: work.status });
     const now = context.now();
@@ -266,10 +331,13 @@ export function startBoundWork(context, work, run, identity, hookEventId) {
     const resultPath = path.join(directory, "result.json");
     const contextPath = path.join(directory, "context.json");
     const dependencyResults = parseDependencies(work).map((dependency) => context.db.get("SELECT work_id, result FROM works WHERE work_id = ?", [dependency])).filter(Boolean);
-    const prompt = renderWorkerPrompt(context, work, run, dependencyResults);
+    const recovery = recoveryPromptForWork(context, work.work_id);
+    let prompt = renderWorkerPrompt(context, work, run, dependencyResults);
+    if (recovery)
+        prompt = `${recoveryPrompt(recovery)}\n\n${prompt}`;
     const payload = parsePayload(work);
     const readOnly = payload?.read_only === true;
-    const workContext = { schema_id: "dd-flow/work-context@1", run_id: work.run_id, work_id: work.work_id, parent_work_id: work.parent_work_id, project_root: run.project_root, workspace_root: run.workspace_root, run_root: requireRunHome(run), depends_on: parseDependencies(work), launch_policy: work.launch_policy, result_schema: work.result_schema, read_only: readOnly, ...(readOnly ? { workspace_fingerprint: workspaceFingerprint(run.workspace_root) } : {}) };
+    const workContext = { schema_id: "dd-flow/work-context@1", run_id: work.run_id, work_id: work.work_id, parent_work_id: work.parent_work_id, project_root: run.project_root, workspace_root: run.workspace_root, run_root: requireRunHome(run), depends_on: parseDependencies(work), launch_policy: work.launch_policy, result_schema: work.result_schema, read_only: readOnly, ...(recovery ? { recovery } : {}), ...(readOnly ? { workspace_fingerprint: workspaceFingerprint(run.workspace_root) } : {}) };
     const token = crypto.randomUUID();
     const promptCandidate = `${promptPath}.${token}.tmp`;
     const contextCandidate = `${contextPath}.${token}.tmp`;
@@ -294,17 +362,19 @@ export function startBoundWork(context, work, run, identity, hookEventId) {
         fs.rmSync(contextCandidate, { force: true });
         throw error;
     }
+    if (recovery)
+        activateRecoveryWork(context, work.work_id);
     refreshRunWorkProjection(context, work.project_id, work.run_id);
-    return { ok: true, work_id: work.work_id, work_session_id: linkId, worker_prompt_markdown: prompt, prompt_path: promptPath, session_binding: { source: "PreToolUse", session: { harness_id: identity.harness, session_id: identity.nativeSessionId } } };
+    return { ok: true, work_id: work.work_id, work_session_id: linkId, worker_prompt_markdown: prompt, prompt_path: promptPath, ...(recovery ? { recovery } : {}), session_binding: { source: "PreToolUse", session: { harness_id: identity.harness, session_id: identity.nativeSessionId } } };
 }
 export function finishWork(context, id, result, progress) { return settle(context, id, "completed", result, progress); }
 /** Structured fan-in closes a parent after its Session was handed to a child. */
-export function finishFanInWork(context, id, result) { const work = requireWork(context, id); if (work.status !== "running")
+export function finishFanInWork(context, id, result) { const work = requireWork(context, id); assertRunMutationAllowed(context, work.project_id, work.run_id); if (work.status !== "running")
     throw new AppError("invalid_work_state", "Fan-in Work is not running", 2, { work_id: work.work_id, status: work.status }); if (context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created','running','paused') LIMIT 1", [work.work_id]))
     throw new AppError("active_child_work", "Fan-in Work still has active children", 2, { work_id: work.work_id }); const now = context.now(); context.db.run("UPDATE works SET status = 'completed', result = ?, completed_at = ?, updated_at = ? WHERE work_id = ?", [result, now, now, work.work_id]); context.db.run("UPDATE work_sessions SET status = 'completed', completed_at = COALESCE(completed_at, ?), updated_at = ? WHERE work_id = ? AND status = 'running'", [now, now, work.work_id]); refreshRunWorkProjection(context, work.project_id, work.run_id); appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: "work_completed", work_id: work.work_id, fan_in: true }); return { ok: true, work_id: work.work_id, status: "completed", fan_in: true }; }
 export function failWork(context, id, reason) { return settle(context, id, "failed", reason); }
 export function cancelWork(context, id, reason) { return settle(context, id, "cancelled", reason); }
-export function retryWork(context, id, reason) { const work = requireWork(context, id); id = work.work_id; if (work.status !== "failed")
+export function retryWork(context, id, reason) { const work = requireWork(context, id); assertRunMutationAllowed(context, work.project_id, work.run_id); id = work.work_id; if (work.status !== "failed")
     throw new AppError("invalid_work_state", "Only failed Work may be retried", 2); const run = requireRun(context, work.project_id, work.run_id); const directory = path.join(requireRunHome(run), "works", id); const attempts = path.join(directory, "attempts"); const number = fs.existsSync(attempts) ? fs.readdirSync(attempts).filter((entry) => /^ATT-\d{3}$/.test(entry)).length + 1 : 1; const archive = path.join(attempts, `ATT-${String(number).padStart(3, "0")}`); fs.mkdirSync(archive, { recursive: true }); for (const file of ["prompt.md", "result.json", "context.json"]) {
     const source = path.join(directory, file);
     if (fs.existsSync(source))
@@ -312,6 +382,7 @@ export function retryWork(context, id, reason) { const work = requireWork(contex
 } context.db.run("UPDATE works SET status = 'created', result = NULL, started_at = NULL, completed_at = NULL, updated_at = ? WHERE work_id = ?", [context.now(), id]); refreshRunWorkProjection(context, work.project_id, work.run_id); return { ok: true, work_id: id, archived_attempt: path.relative(requireRunHome(run), archive).split(path.sep).join("/"), reason }; }
 async function settle(context, id, status, result, progress) {
     const work = requireWork(context, id);
+    assertRunMutationAllowed(context, work.project_id, work.run_id);
     id = work.work_id;
     if (work.status !== "running" && !(status === "cancelled" && work.status === "created"))
         throw new AppError("invalid_work_state", "Work is not running", 2, { status: work.status });
@@ -367,6 +438,7 @@ async function settle(context, id, status, result, progress) {
         context.db.exec("ROLLBACK");
         throw error;
     }
+    settleRecoveryWork(context, work.work_id, status);
     refreshRunWorkProjection(context, work.project_id, work.run_id);
     const newlyReady = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? AND status = 'created' ORDER BY created_at, work_id`, [work.project_id, work.run_id]).filter((candidate) => isReady(context, candidate)).map((candidate) => ({ work_id: candidate.work_id, launch_policy: candidate.launch_policy, start_command: workStartCommand(context, candidate) }));
     appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: `work_${status}`, work_id: work.work_id, session_id: link?.session_id ?? null, ...(coordinationDrift.length ? { coordination_drift: coordinationDrift } : {}) });
@@ -374,6 +446,7 @@ async function settle(context, id, status, result, progress) {
         appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: "work_dependency_unblocked", work_id: ready.work_id, completed_dependency: work.work_id });
     return { ok: true, work_id: id, status, checks: receipts, coordination: { planned_write_areas: codePacket(work)?.planned_write_areas ?? [], drift: coordinationDrift }, newly_ready: newlyReady, graph: codeWorkGraph(context, work.project_id, work.run_id), usage: { status: "provisional", reason: "final usage is controller-owned" } };
 }
+function recoveryPrompt(recovery) { return ["<recovery_identity>", `- recovery_id: ${recovery.recoveryId}`, `- execution_generation: ${recovery.generation}`, "This Work was interrupted and is now an authorized recovery segment of the same assignment.", "</recovery_identity>", "", "<recovery_instructions>", `Read the retained pre-interruption evidence at ${recovery.evidencePath}.`, "Before changing files or rerunning a command, inspect the workspace, receipts, logs, and partial artifacts. Do not assume the last command succeeded or failed merely because its reply was lost.", "Preserve accepted work. Do not repeat completed Work, create undeclared Work, alter the original requirements, or edit dd-flow runtime state/evidence.", "Observe an existing check or finish instead of duplicating it. Retry only through an exact runtime retry command after establishing that its prior outcome permits it.", "Record the concrete unresolved operation rather than guessing if an external effect cannot be reconciled.", "</recovery_instructions>"].join("\n"); }
 function plannedAreaDrift(packet, result) {
     const changed = JSON.parse(result).changed_paths;
     if (!Array.isArray(changed) || packet.planned_write_areas.length === 0)

package/dist/storage/database.js

@@ -7,6 +7,20 @@ import { AppError } from "../shared/errors.js";
 const require = createRequire(import.meta.url);
 const { DatabaseSync } = require("node:sqlite");
 const resourceDatabases = new Map();
+/** Recovery guards apply to every RUN kind, including custom eval fixtures. */
+export function ensureRecoveryStorage(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS run_recovery_guards (
+      recovery_id TEXT PRIMARY KEY, project_id TEXT NOT NULL, run_id TEXT NOT NULL, generation INTEGER NOT NULL, status TEXT NOT NULL, interruption_json TEXT NOT NULL, settlement_json TEXT, capture_path TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, sealed_at TEXT, resumed_at TEXT, UNIQUE(project_id, run_id, generation), FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_run_recovery_guards_run ON run_recovery_guards(project_id, run_id, generation DESC);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_run_recovery_guards_active ON run_recovery_guards(project_id, run_id) WHERE status IN ('draining', 'sealed', 'resuming');
+    CREATE TABLE IF NOT EXISTS work_recovery_segments (
+      recovery_id TEXT NOT NULL, work_id TEXT NOT NULL, generation INTEGER NOT NULL, prior_started_at TEXT, evidence_path TEXT NOT NULL, status TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY(recovery_id, work_id), FOREIGN KEY(recovery_id) REFERENCES run_recovery_guards(recovery_id), FOREIGN KEY(work_id) REFERENCES works(work_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_work_recovery_segments_work ON work_recovery_segments(work_id, generation DESC);
+  `);
+}
 /** Creates the single Work/Session authority used by a fresh vNext beta runtime. */
 export function ensureVnextWorkStorage(db) {
     const legacy = db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('vnext_works', 'vnext_agent_turns', 'flow_agent_turns') LIMIT 1");
@@ -53,6 +67,16 @@ export function ensureVnextWorkStorage(db) {
     );
     CREATE INDEX IF NOT EXISTS idx_work_sessions_work ON work_sessions(work_id, created_at DESC);
     CREATE UNIQUE INDEX IF NOT EXISTS idx_work_sessions_open ON work_sessions(work_id) WHERE status = 'running';
+
+    CREATE TABLE IF NOT EXISTS run_recovery_guards (
+      recovery_id TEXT PRIMARY KEY, project_id TEXT NOT NULL, run_id TEXT NOT NULL, generation INTEGER NOT NULL, status TEXT NOT NULL, interruption_json TEXT NOT NULL, settlement_json TEXT, capture_path TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, sealed_at TEXT, resumed_at TEXT, UNIQUE(project_id, run_id, generation), FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_run_recovery_guards_run ON run_recovery_guards(project_id, run_id, generation DESC);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_run_recovery_guards_active ON run_recovery_guards(project_id, run_id) WHERE status IN ('draining', 'sealed', 'resuming');
+    CREATE TABLE IF NOT EXISTS work_recovery_segments (
+      recovery_id TEXT NOT NULL, work_id TEXT NOT NULL, generation INTEGER NOT NULL, prior_started_at TEXT, evidence_path TEXT NOT NULL, status TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY(recovery_id, work_id), FOREIGN KEY(recovery_id) REFERENCES run_recovery_guards(recovery_id), FOREIGN KEY(work_id) REFERENCES works(work_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_work_recovery_segments_work ON work_recovery_segments(work_id, generation DESC);
     CREATE TABLE IF NOT EXISTS check_receipts (
       id TEXT PRIMARY KEY,
       project_id TEXT NOT NULL,
@@ -95,8 +119,10 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
     configureDatabase(db, mode);
     // Internal additive schema changes must be available to every write command.
     // Higher-level Memory Bank migrations remain explicit in services/migrations.
-    if (mode !== "read_existing")
+    if (mode !== "read_existing") {
         migrate(db, dbPath);
+        ensureRecoveryStorage(db);
+    }
     if (mode === "read_existing")
         db.exec("PRAGMA query_only = ON");
     db.exec("PRAGMA foreign_keys = ON");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.18",
+  "version": "0.9.0-beta.19",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {