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

package/dist/services/work-registry.js

@@ -2,20 +2,87 @@ 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, assertRecoveryHookCurrent, assertRunMutationAllowed, recoveryGuard, 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"); }
+function ownsPhysicalWorkSession(context, projectId, owner, identity) {
+    if (identity.sessionId !== owner.session_id)
+        return false;
+    const binding = owner.hook_event_id ? context.db.get("SELECT daemon_id FROM hook_events WHERE project_id = ? AND event_key = ?", [projectId, owner.hook_event_id]) : undefined;
+    // Legacy non-daemon sessions remain usable. Once a physical daemon was
+    // captured, another process cannot inherit authority merely by resuming
+    // the same provider Session ID.
+    return !binding?.daemon_id || binding.daemon_id === identity.daemonId;
+}
+/**
+ * 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, ws.hook_event_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 (ownsPhysicalWorkSession(context, project.id, owner, identity))
+        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 (ownsPhysicalWorkSession(context, work.project_id, owner, identity))
+        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 +113,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 +186,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 +208,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; }
 /**
@@ -148,10 +217,11 @@ export function shortWorkId(id) { return /^WRK-\d{3,}(?:-|$)/.exec(id)?.[0]?.rep
  * PATH is not inherited; using the shared lifecycle command keeps them on the
  * same captured runtime as their parent stage.
  */
-export function workStartCommand(context, work) { const run = requireRun(context, work.project_id, work.run_id); return `${flowCommand(context)} work start ${work.work_id} --project-root ${JSON.stringify(run.project_root)} --json`; }
+export function workStartCommand(context, work) { const run = requireRun(context, work.project_id, work.run_id); const recovery = recoveryGuard(context, work.project_id, work.run_id); return `${flowCommand(context)} work start ${work.work_id} --project-root ${JSON.stringify(run.project_root)}${recovery ? ` --recovery-id ${JSON.stringify(recovery.recovery_id)}` : ""} --json`; }
 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)) {
@@ -162,16 +232,19 @@ export function startWork(context, id, input) {
     const run = requireRun(context, work.project_id, work.run_id);
     if (input.projectRoot && resolveProjectRoot(input.projectRoot) !== resolveProjectRoot(run.project_root))
         throw new AppError("project_mismatch", "work start project root does not match its RUN", 1, { work_id: id });
+    const recoveryId = recoveryGuard(context, work.project_id, work.run_id)?.recovery_id;
+    if (input.recoveryId !== recoveryId)
+        throw new AppError("run_recovery_generation_stale", "Work launch must use the exact current recovery packet", 1, { work_id: id, recovery_id: recoveryId ?? null });
     let hookEventId = input.hookEventId;
     if (!hookEventId) {
         try {
-            hookEventId = findRecentMatchingHookEvent(context, { projectId: work.project_id, matchKey: workStartMatchKey(shortWorkId(work.work_id), run.project_root), errorCode: "trusted_session_binding_required", operation: "work start" }).eventKey;
+            hookEventId = findRecentMatchingHookEvent(context, { projectId: work.project_id, matchKey: workStartMatchKey(shortWorkId(work.work_id), run.project_root, recoveryId), errorCode: "trusted_session_binding_required", operation: "work start" }).eventKey;
         }
         catch {
-            hookEventId = findRecentMatchingHookEvent(context, { projectId: work.project_id, matchKey: workStartMatchKey(work.work_id, run.project_root), errorCode: "trusted_session_binding_required", operation: "work start" }).eventKey;
+            hookEventId = findRecentMatchingHookEvent(context, { projectId: work.project_id, matchKey: workStartMatchKey(work.work_id, run.project_root, recoveryId), errorCode: "trusted_session_binding_required", operation: "work start" }).eventKey;
         }
     }
-    const identity = claimWorkStartHookEvent(context, { projectId: work.project_id, eventKey: hookEventId, workId: work.work_id, projectRoot: run.project_root });
+    const identity = claimWorkStartHookEvent(context, { projectId: work.project_id, eventKey: hookEventId, workId: work.work_id, projectRoot: run.project_root, ...(recoveryId ? { recoveryId } : {}) });
     const started = startBoundWork(context, work, run, identity, hookEventId);
     appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: "work_started", work_id: work.work_id, session_id: identity.sessionId, agent_id: identity.agentId });
     return started;
@@ -179,12 +252,16 @@ 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);
     const identity = hookSessionIdentity(context, work.project_id, input.hookEventId);
+    assertRecoveryHookCurrent(context, work.project_id, work.run_id, identity);
     const active = 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 (active) {
+        if (active.session_id === identity.sessionId && !ownsPhysicalWorkSession(context, work.project_id, active, identity))
+            throw new AppError("handoff_session_mismatch", "The active Work belongs to another physical daemon", 1, { work_id: work.work_id });
         if (active.session_id !== identity.sessionId) {
             // A frozen `new_session` policy may transfer the same coordinator Work
             // only to its next stage. Repeating the same stage from another Session
@@ -231,6 +308,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 +320,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 +335,8 @@ 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) {
+    assertRecoveryHookCurrent(context, work.project_id, work.run_id, identity);
+    const generation = 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 +347,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`;
@@ -277,15 +361,18 @@ export function startBoundWork(context, work, run, identity, hookEventId) {
     fs.writeFileSync(contextCandidate, `${JSON.stringify(workContext, null, 2)}\n`);
     context.db.exec("BEGIN IMMEDIATE");
     try {
+        assertRunMutationAllowed(context, work.project_id, work.run_id, generation);
         bindSession(context, work, run, identity, now);
         if (work.parent_work_id && work.launch_policy === "reuse_allowed")
             context.db.run("UPDATE work_sessions SET status = 'completed', completed_at = ?, updated_at = ? WHERE session_id = ? AND status = 'running' AND work_id <> ?", [now, now, identity.sessionId, work.work_id]);
-        const claimed = context.db.run("UPDATE works SET status = 'running', started_at = ?, updated_at = ? WHERE work_id = ? AND status = 'created'", [now, now, work.work_id]);
+        const claimed = context.db.run("UPDATE works SET status = 'running', started_at = COALESCE(started_at, ?), updated_at = ? WHERE work_id = ? AND status = 'created'", [now, now, work.work_id]);
         if (claimed.changes !== 1)
             throw new AppError("conflict", "Work was claimed concurrently", 1, { work_id: work.work_id });
         context.db.run(`INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, NULL)`, [linkId, work.work_id, identity.sessionId, hookEventId, promptPath, resultPath, now, now]);
         fs.renameSync(promptCandidate, promptPath);
         fs.renameSync(contextCandidate, contextPath);
+        if (recovery)
+            activateRecoveryWork(context, work.work_id);
         context.db.exec("COMMIT");
     }
     catch (error) {
@@ -295,16 +382,16 @@ export function startBoundWork(context, work, run, identity, hookEventId) {
         throw error;
     }
     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 +399,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 });
@@ -352,6 +440,9 @@ async function settle(context, id, status, result, progress) {
     const now = context.now();
     context.db.exec("BEGIN IMMEDIATE");
     try {
+        assertRunMutationAllowed(context, work.project_id, work.run_id);
+        if (link && !context.db.get("SELECT 1 FROM work_sessions WHERE id = ? AND status = 'running'", [link.id]))
+            throw new AppError("work_generation_stale", "Work Session was interrupted or superseded while checks ran", 1, { work_id: id });
         context.db.run("UPDATE works SET status = ?, result = ?, completed_at = ?, updated_at = ? WHERE work_id = ?", [status, result, now, now, id]);
         if (link) {
             if (link.result_path && work.parent_work_id !== null)
@@ -367,6 +458,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 +466,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,29 @@ 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);
+    CREATE TABLE IF NOT EXISTS run_recovery_bindings (
+      recovery_id TEXT PRIMARY KEY REFERENCES run_recovery_guards(recovery_id),
+      work_id TEXT NOT NULL REFERENCES works(work_id), prior_work_session_id TEXT NOT NULL,
+      session_id TEXT NOT NULL, harness TEXT NOT NULL, provider_session_id TEXT NOT NULL,
+      daemon_id TEXT NOT NULL, status TEXT NOT NULL, hook_event_key TEXT,
+      created_at TEXT NOT NULL, accepted_at TEXT
+    );
+  `);
+    ensureColumn(db, "run_recovery_bindings", "packet_json", "ALTER TABLE run_recovery_bindings ADD COLUMN packet_json TEXT");
+    ensureColumn(db, "run_recovery_bindings", "packet_sha256", "ALTER TABLE run_recovery_bindings ADD COLUMN packet_sha256 TEXT");
+}
 /** 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 +76,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 +128,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.21",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {
@@ -16,6 +16,16 @@
     "node": ">=26.0.0",
     "pnpm": ">=10.0.0"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/generate-build-info.mjs && node scripts/copy-assets.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --max-warnings=0",
+    "test": "vitest run",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm run build && changeset publish",
+    "prepublishOnly": "node scripts/verify-release-build.mjs"
+  },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
     "@eslint/js": "^9.39.1",
@@ -34,14 +44,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT",
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json && node scripts/generate-build-info.mjs && node scripts/copy-assets.mjs",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint . --max-warnings=0",
-    "test": "vitest run",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "pnpm run build && changeset publish"
-  }
-}
+  "license": "MIT"
+}