@deksden-com/dd-flow-cli 0.9.0-beta.9 → 0.9.0-beta.91

package/dist/services/work-registry.js

@@ -1,33 +1,124 @@
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
+import { bindStageWork, currentStageWorkIds, stageWorkIds } from "./stage-work-graph.js";
+import { runtimeCommand } from "./runtime-command.js";
 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 { entityReferenceVariants, shortEntityReference } from "../shared/entity-references.js";
+import { resolveWorkReference } from "../storage/work-references.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 { ignoredWorkspacePaths, normalizeWorkspacePath, readCodeCheckProfile, runCodeChecks, validateFailedCheckRetry, workspaceFingerprint } from "./code-checks.js";
 import { nextWorkId, nextWorkIds } from "./ids.js";
 import { appendFlowRunTimelineEvent } from "./runs.js";
+import { resolveStageTransition } from "./execution-policy.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, assertWorkSettlementAllowed, recoveryGuard, recoveryPromptForWork, settleRecoveryWork } from "./run-recovery.js";
+import { runControlDirective } from "./run-control.js";
+import { prepareError, prepareJsonFile } from "../cli/input-preparation.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 scopedWork = input.workId ? requireWork(context, input.workId, { projectId: project.id, runId: input.runId }) : undefined;
+    let 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 = ?)
+        ${scopedWork ? "AND w.work_id = ?" : ""}
+      ORDER BY ws.created_at DESC LIMIT 1`, scopedWork ? [project.id, input.runId, input.stage, scopedWork.work_id] : [project.id, input.runId, input.stage]);
+    if (!owner && input.operation === "stage_finish" && ["code", "code-review"].includes(input.stage)) {
+        const row = context.db.get("SELECT run_root, index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
+        const index = row ? JSON.parse(row.index_json) : null;
+        const completed = index?.stage_runs.find(entry => entry.stage === input.stage && entry.status === "done");
+        if (row && completed && (index?.current_stage ?? index?.stage_runs.at(-1)?.stage) === input.stage)
+            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 WHERE w.project_id = ? AND w.run_id = ? AND w.parent_work_id IS NULL AND w.status = 'completed' AND ws.status = 'completed' AND ws.result_path = ? ORDER BY ws.created_at DESC LIMIT 1", [project.id, input.runId, path.join(row.run_root, completed.dir, "stage-report.json")]);
+    }
+    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);
-    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);
-    const now = context.now();
-    context.db.run(`INSERT INTO works (${workColumns}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, '[]', 'created', NULL, ?, NULL, ?, NULL)`, [id, parent.project_id, parent.run_id, parent.work_id, input.task, input.launchPolicy, input.resultSchema ?? null, input.payload ? JSON.stringify(input.payload) : null, now, now]);
-    refreshRunWorkProjection(context, parent.project_id, parent.run_id);
-    return requireWork(context, id);
+    return context.db.writeTransaction(() => {
+        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);
+        const now = context.now();
+        context.db.run(`INSERT INTO works (${workColumns}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, '[]', 'created', NULL, ?, NULL, ?, NULL)`, [id, parent.project_id, parent.run_id, parent.work_id, input.task, input.launchPolicy, input.resultSchema ?? null, input.payload ? JSON.stringify(input.payload) : null, now, now]);
+        if (input.stage)
+            bindStageWork(context, { projectId: parent.project_id, runId: parent.run_id, workId: id, stage: input.stage });
+        refreshRunWorkProjection(context, parent.project_id, parent.run_id);
+        return requireWork(context, id);
+    });
 }
 /** Validate a proposed batch before PLAN accepts it, without registering Work. */
 export function validateWorkBatchFile(file) {
-    const parsed = readJson(file);
-    if (!Array.isArray(parsed.works) || parsed.works.length === 0)
+    validateWorkBatch(prepareJsonFile(file, "work batch").value);
+}
+/** Validate an already prepared batch without reopening its source file. */
+export function validateWorkBatch(value) {
+    const parsed = value;
+    if (!parsed || !Array.isArray(parsed.works) || parsed.works.length === 0)
         throw new AppError("validation", "work batch requires non-empty works", 2);
     const items = parsed.works.map((item) => validateItem(item, true));
     const keys = new Set(items.map((item) => item.key));
@@ -43,18 +134,29 @@ export function validateWorkBatchFile(file) {
     assertNoCycles(items.map((item) => ({ id: item.key, dependencies: item.depends_on ?? [] })));
     assertNoParentCycles(items.filter((item) => Boolean(item.parent)).map((item) => ({ id: item.key, parent: item.parent })));
 }
-export function addWorkBatch(context, input) {
-    ensureWorkRegistry(context);
-    const parent = requireWork(context, input.parentWorkId);
-    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);
-    if (!Array.isArray(parsed.works) || parsed.works.length === 0)
+export function prepareWorkBatch(context, input) {
+    if (input.file !== undefined && input.value !== undefined)
+        throw new AppError("usage", "Work batch accepts either file or value, not both", 2);
+    if (input.file === undefined && input.value === undefined)
+        throw new AppError("usage", "Work batch input is required", 2);
+    const parsed = (input.file !== undefined ? prepareJsonFile(input.file, "work batch").value : input.value);
+    if (!parsed || !Array.isArray(parsed.works) || parsed.works.length === 0)
         throw new AppError("validation", "work batch requires non-empty works", 2);
     const items = parsed.works.map((item) => validateItem(item));
     const keys = new Set(items.map((item) => item.key));
     if (keys.size !== items.length)
         throw new AppError("validation", "work batch keys must be unique", 2);
+    assertNoCycles(items.map(item => ({ id: item.key, dependencies: item.depends_on ?? [] })));
+    assertNoParentCycles(items.filter((item) => Boolean(item.parent)).map(item => ({ id: item.key, parent: item.parent })));
+    prepareBatchParent(context, input.parentWorkId, items);
+    return items;
+}
+function prepareBatchParent(context, parentWorkId, items) {
+    const keys = new Set(items.map(item => item.key));
+    const parent = requireWork(context, 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 existing = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ?`, [parent.project_id, parent.run_id]);
     const existingIds = new Set(existing.map((row) => row.work_id));
     for (const item of items)
@@ -64,9 +166,15 @@ export function addWorkBatch(context, input) {
     for (const item of items)
         if (item.parent && !keys.has(item.parent) && !existingIds.has(item.parent))
             throw new AppError("validation", "work parent is unknown", 2, { key: item.key, parent: item.parent });
-    const now = context.now();
-    context.db.exec("BEGIN IMMEDIATE");
-    try {
+    return parent;
+}
+export function addWorkBatch(context, input) {
+    const items = input.prepared ?? prepareWorkBatch(context, input);
+    return context.db.writeTransaction(() => {
+        // Only mutable authority/references are rechecked under the write lock.
+        // Caller bytes were read once, before admission, and are never reopened.
+        const parent = prepareBatchParent(context, input.parentWorkId, items);
+        const now = context.now();
         const allocated = nextWorkIds(context, parent.project_id, items.map((item) => item.key));
         const ids = new Map(items.map((item, index) => [item.key, allocated[index]]));
         const resolve = (value) => ids.get(value) ?? value;
@@ -76,16 +184,17 @@ export function addWorkBatch(context, input) {
         for (const item of proposed)
             context.db.run(`INSERT INTO works (work_id, project_id, run_id, parent_work_id, task, launch_policy, result_schema, payload_json, depends_on_json, status, result, started_at, created_at, updated_at, completed_at)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'created', NULL, NULL, ?, ?, NULL)`, [item.id, parent.project_id, parent.run_id, item.parentId, item.task, item.launch_policy ?? "reuse_allowed", item.result_schema ?? null, item.payload ? JSON.stringify(item.payload) : null, JSON.stringify(item.dependencies), now, now]);
-        context.db.exec("COMMIT");
-        for (const item of proposed)
+        const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [parent.project_id, parent.run_id]);
+        const stages = run ? (JSON.parse(run.index_json).stage_runs ?? []) : [];
+        const ownerStage = input.stage ?? [...stages].reverse().find(stage => stage.status === "running")?.stage;
+        for (const item of proposed) {
+            if (ownerStage)
+                bindStageWork(context, { projectId: parent.project_id, runId: parent.run_id, workId: item.id, stage: ownerStage, ...(input.cycle ? { cycle: input.cycle } : {}) });
             appendFlowRunTimelineEvent(context, parent.project_id, parent.run_id, { type: "work_materialized", work_id: item.id, parent_work_id: item.parentId, depends_on: item.dependencies, launch_policy: item.launch_policy ?? "reuse_allowed" });
+        }
         refreshRunWorkProjection(context, parent.project_id, parent.run_id);
         return { ok: true, work_ids: Object.fromEntries(ids) };
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+    });
 }
 export function listWorks(context, input) {
     ensureWorkRegistry(context);
@@ -105,8 +214,8 @@ export function listWorks(context, input) {
         where.push("status = ?");
         params.push(input.status);
     }
-    const rows = context.db.all(`SELECT ${workColumns} FROM works WHERE ${where.join(" AND ")} ORDER BY created_at, work_id`, params);
-    const ready = (work) => isReady(context, work);
+    const rows = context.db.all(`SELECT ${workColumns} FROM works WHERE ${where.join(" AND ")} ORDER BY created_at, work_id`, params).filter(work => !input.workIds || input.workIds.has(work.work_id));
+    const ready = (work) => (input.workIds || currentStageWorkIds(context, work.project_id, work.run_id))?.has(work.work_id) !== false && isReady(context, work);
     const filtered = input.ready ? rows.filter(ready) : rows;
     return { works: filtered.slice(0, input.limit ?? filtered.length).map((work) => {
             const isReadyNow = ready(work);
@@ -114,10 +223,137 @@ export function listWorks(context, input) {
         }) };
 }
 export function showWork(context, id) { const work = requireWork(context, id); const sessions = context.db.all("SELECT ws.id, ws.work_id, ws.session_id, ws.hook_event_id, ws.status, ws.prompt_path, ws.result_path, ws.created_at, ws.completed_at, s.harness AS harness_id, COALESCE(s.provider_session_id, s.session_id) AS native_session_id FROM work_sessions ws LEFT JOIN sessions s ON s.project_id = ? AND s.session_id = ws.session_id WHERE ws.work_id = ? ORDER BY ws.created_at", [work.project_id, work.work_id]); return { work: { ...work, short_id: shortWorkId(work.work_id), payload: parsePayload(work), payload_json: undefined, depends_on: parseDependencies(work), sessions: sessions.map(({ session_id, harness_id, native_session_id, ...session }) => ({ ...session, ...(harness_id && native_session_id ? { session: publicSessionIdentity({ harness: harness_id, provider_session_id: native_session_id, session_id }) } : {}) })) } }; }
+function receiptIntentPath(resultPath, sessionId) {
+    return `${resultPath}.pending-${crypto.createHash("sha256").update(sessionId).digest("hex")}`;
+}
+function receiptFileHash(file) {
+    return fs.existsSync(file) ? crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") : null;
+}
+function sha256(contents) { return crypto.createHash("sha256").update(contents).digest("hex"); }
+function publishReceiptFile(file, contents) {
+    const temporary = `${file}.tmp-${crypto.randomUUID()}`;
+    try {
+        fs.writeFileSync(temporary, contents);
+        const descriptor = fs.openSync(temporary, "r");
+        try {
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        fs.renameSync(temporary, file);
+        const directory = fs.openSync(path.dirname(file), "r");
+        try {
+            fs.fsyncSync(directory);
+        }
+        finally {
+            fs.closeSync(directory);
+        }
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+/** Rebuild prompt/context projections from a committed Work-start receipt. */
+export function materializePendingWorkStarts(context, projectId, runId) {
+    const runHome = requireRunHome(requireRun(context, projectId, runId));
+    context.db.writeTransaction(() => {
+        const rows = context.db.all("SELECT ws.id, ws.work_id, ws.prompt_path, ws.start_receipt_json FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.status = 'running' AND ws.start_receipt_json IS NOT NULL", [projectId, runId]);
+        for (const row of rows) {
+            // The same coordinator Session can move on to a different stage packet.
+            // A start receipt is not authority to overwrite that later packet.
+            let receipt;
+            try {
+                receipt = JSON.parse(row.start_receipt_json);
+            }
+            catch {
+                throw new AppError("work_start_receipt_invalid", "Committed Work start receipt is not valid JSON", 1, { work_id: row.work_id });
+            }
+            const originalPromptPath = path.join(runHome, "works", row.work_id, ...(receipt.generation && receipt.generation > 0 ? ["starts", row.id] : []), "prompt.md");
+            if (path.resolve(row.prompt_path) !== path.resolve(originalPromptPath))
+                continue;
+            if (receipt.version !== 1 || typeof receipt.prompt !== "string" || typeof receipt.context !== "string" || receipt.prompt_sha256 !== sha256(receipt.prompt) || receipt.context_sha256 !== sha256(receipt.context))
+                throw new AppError("work_start_receipt_invalid", "Committed Work start receipt does not match its retained bytes", 1, { work_id: row.work_id });
+            publishStartReceiptFile(row.prompt_path, receipt.prompt, String(receipt.prompt_sha256));
+            publishStartReceiptFile(path.join(path.dirname(row.prompt_path), "context.json"), receipt.context, String(receipt.context_sha256));
+        }
+    });
+}
+function publishStartReceiptFile(file, contents, expectedHash) {
+    const actual = receiptFileHash(file);
+    if (actual === expectedHash)
+        return;
+    if (actual !== null) {
+        throw new AppError("work_start_projection_conflict", "Work start packet differs from its committed receipt; preserve it for recovery", 1, { path: file, expected_sha256: expectedHash, actual_sha256: actual });
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    publishReceiptFile(file, contents);
+}
+/** Replay only a prepared publication whose exact receipt was committed in SQLite. */
+export function materializePendingWorkResults(context, projectId, runId) {
+    context.db.beginWriteTransaction();
+    try {
+        const rows = context.db.all(`SELECT w.work_id, w.result, w.status, ws.id, ws.result_path FROM works w JOIN work_sessions ws ON ws.work_id = w.work_id AND ws.status = w.status WHERE w.project_id = ? AND w.run_id = ? AND w.parent_work_id IS NOT NULL AND w.result IS NOT NULL AND w.status IN ('completed', 'failed', 'cancelled') AND ws.result_path IS NOT NULL`, [projectId, runId]);
+        for (const row of rows) {
+            const intentPath = receiptIntentPath(row.result_path, row.id);
+            if (!fs.existsSync(intentPath))
+                continue;
+            const intent = JSON.parse(fs.readFileSync(intentPath, "utf8"));
+            const digest = crypto.createHash("sha256").update(row.result).digest("hex");
+            if (intent.work_id !== row.work_id || intent.work_session_id !== row.id || intent.status !== row.status || intent.result_sha256 !== digest)
+                throw new AppError("work_result_publication_conflict", "Pending result publication does not identify the committed receipt", 1, { work_id: row.work_id, intent_path: intentPath });
+            const actual = receiptFileHash(row.result_path);
+            if (actual !== digest && actual !== intent.previous_sha256)
+                throw new AppError("work_result_artifact_drift", "Result changed after its publication was prepared; preserve it for diagnosis", 1, { work_id: row.work_id, actual_sha256: actual, expected_sha256: digest });
+            if (fs.existsSync(row.result_path)) {
+                const previous = fs.readFileSync(row.result_path);
+                if (!previous.equals(Buffer.from(row.result))) {
+                    const retained = `${row.result_path}.conflict-${crypto.createHash("sha256").update(previous).digest("hex")}`;
+                    try {
+                        fs.writeFileSync(retained, previous, { flag: "wx", flush: true });
+                    }
+                    catch (error) {
+                        if (error.code !== "EEXIST" || !fs.readFileSync(retained).equals(previous))
+                            throw error;
+                    }
+                }
+            }
+            publishReceiptFile(row.result_path, row.result);
+            fs.unlinkSync(intentPath);
+        }
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}
 export function mutateWorkDeps(context, input) {
+    if (input.action === "list") {
+        const { work, dependencies } = prepareWorkDeps(context, input);
+        return { work_id: work.work_id, depends_on: dependencies };
+    }
+    prepareWorkDeps(context, input);
+    return context.db.writeTransaction(() => {
+        const { work, dependencies } = prepareWorkDeps(context, input);
+        context.db.run("UPDATE works SET depends_on_json = ?, updated_at = ? WHERE work_id = ?", [JSON.stringify(dependencies), context.now(), work.work_id]);
+        refreshRunWorkProjection(context, work.project_id, work.run_id);
+        return { work_id: work.work_id, depends_on: dependencies };
+    });
+}
+export function prepareWorkDeps(context, input) {
+    if (!["list", "add", "remove", "clear"].includes(input.action) || (input.on !== undefined && (!Array.isArray(input.on) || input.on.some(id => typeof id !== "string" || !id.trim()))))
+        throw new AppError("usage", "Invalid Work dependency action or --on target", 2);
+    if (["add", "remove"].includes(input.action) && !input.on?.length)
+        throw new AppError("usage", "Dependency add/remove requires at least one --on target", 2);
+    if (["list", "clear"].includes(input.action) && input.on?.length)
+        throw new AppError("usage", "Dependency list/clear does not accept --on targets", 2);
+    if (input.action === "list") {
+        const work = requireWork(context, input.workId);
+        return { work, dependencies: parseDependencies(work) };
+    }
     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));
@@ -125,8 +361,8 @@ export function mutateWorkDeps(context, input) {
         dependencies.clear();
     for (const id of input.on ?? []) {
         const dependency = requireWork(context, id);
-        if (dependency.run_id !== work.run_id)
-            throw new AppError("validation", "Dependencies must stay in one RUN", 2);
+        if (dependency.project_id !== work.project_id || dependency.run_id !== work.run_id)
+            throw new AppError("validation", "Dependencies must stay in one project and RUN", 2);
         if (input.action === "add")
             dependencies.add(dependency.work_id);
         else
@@ -135,56 +371,76 @@ export function mutateWorkDeps(context, input) {
     if (dependencies.has(work.work_id))
         throw new AppError("validation", "Work cannot depend on itself", 2);
     assertNoCycles(context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ?`, [work.project_id, work.run_id]).map((row) => ({ id: row.work_id, dependencies: row.work_id === work.work_id ? [...dependencies] : parseDependencies(row) })));
-    context.db.run("UPDATE works SET depends_on_json = ?, updated_at = ? WHERE work_id = ?", [JSON.stringify([...dependencies]), context.now(), work.work_id]);
-    refreshRunWorkProjection(context, work.project_id, work.run_id);
-    return { work_id: work.work_id, depends_on: [...dependencies] };
+    return { work, dependencies: [...dependencies] };
+}
+export function prepareWorkDelete(context, id) {
+    const work = requireWork(context, id);
+    assertRunMutationAllowed(context, work.project_id, work.run_id);
+    if (work.status !== "created" || work.started_at || context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? LIMIT 1", [work.work_id]) || context.db.get("SELECT 1 FROM works WHERE depends_on_json LIKE ? LIMIT 1", [`%${work.work_id}%`]))
+        throw new AppError("invalid_work_state", "Only an unstarted unreferenced Work may be deleted", 2);
+    return work;
 }
-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}%`]))
-    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; }
+export function deleteWork(context, id) {
+    prepareWorkDelete(context, id);
+    return context.db.writeTransaction(() => { const work = prepareWorkDelete(context, id); context.db.run("DELETE FROM works WHERE work_id = ?", [work.work_id]); refreshRunWorkProjection(context, work.project_id, work.run_id); return { ok: true, deleted: work.work_id }; });
+}
+export function shortWorkId(id) { return shortEntityReference(id); }
 /**
  * Return the engine-bound command, never a PATH-dependent `dd-flow` token.
  * Fan-out workers run in independently spawned harnesses where the adapter's
  * 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 startWork(context, id, input) {
+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 managedLifecycleCommand(context, runtimeCommand(context, ["work", "start", shortWorkId(work.work_id), "--project-root", run.project_root, ...(recovery ? ["--recovery-id", recovery.recovery_id] : []), "--json"])); }
+export function assertWorkLaunchReady(context, id) {
     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)) {
         const blockers = readinessBlockers(context, work);
-        const ready = 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, start_command: workStartCommand(context, candidate) }));
+        const ready = 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) => currentStageWorkIds(context, candidate.project_id, candidate.run_id)?.has(candidate.work_id) !== false && isReady(context, candidate)).map((candidate) => ({ work_id: candidate.work_id, start_command: workStartCommand(context, candidate) }));
         throw new AppError("work_not_ready", "Work cannot start until dependencies complete and overlapping planned coordination areas are free", 2, { work_id: id, blockers, ready });
     }
+    return work;
+}
+export function startWork(context, id, input) {
+    if (input.hookEventId && !context.env.DD_FLOW_CURRENT_INVOCATION) {
+        const retainedWork = requireWork(context, id);
+        const retainedRun = requireRun(context, retainedWork.project_id, retainedWork.run_id);
+        if (input.projectRoot && resolveProjectRoot(input.projectRoot) !== resolveProjectRoot(retainedRun.project_root))
+            throw new AppError("project_mismatch", "Work start belongs to another project", 1);
+        const reply = recoverCommittedWorkStart(context, null, input.hookEventId, recoveryGuard(context, retainedWork.project_id, retainedWork.run_id)?.generation ?? 0, retainedWork.work_id);
+        if (reply)
+            return reply;
+    }
+    const work = assertWorkLaunchReady(context, id);
     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 });
-    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;
-        }
-        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;
-        }
-    }
-    const identity = claimWorkStartHookEvent(context, { projectId: work.project_id, eventKey: hookEventId, workId: work.work_id, projectRoot: run.project_root });
-    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 });
+    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 });
+    const hookEventId = input.hookEventId ?? findRecentMatchingHookEvent(context, { projectId: work.project_id, matchKey: entityReferenceVariants(work.work_id).map((reference) => workStartMatchKey(reference, run.project_root, recoveryId)), errorCode: "trusted_session_binding_required", operation: "work start" }).eventKey;
+    const eventKey = hookEventId;
+    const started = startBoundWork(context, work, run, () => claimWorkStartHookEvent(context, { projectId: work.project_id, eventKey, workId: work.work_id, projectRoot: run.project_root, ...(recoveryId ? { recoveryId } : {}) }), eventKey);
+    appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: "work_started", work_id: work.work_id, work_session_id: started.work_session_id });
     return started;
 }
 /** 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
@@ -193,7 +449,7 @@ export function bindRunningWorkSession(context, input) {
                 throw new AppError("handoff_session_mismatch", "The active Work is already bound to a different Session", 1, { work_id: work.work_id });
             const now = context.now();
             const id = `WS-${crypto.randomUUID()}`;
-            context.db.exec("BEGIN IMMEDIATE");
+            context.db.beginWriteTransaction();
             try {
                 context.db.run("UPDATE work_sessions SET status = 'completed', completed_at = ?, updated_at = ? WHERE id = ?", [now, now, active.id]);
                 const stillRunning = context.db.get("SELECT 1 FROM work_sessions WHERE session_id = ? AND status = 'running' LIMIT 1", [active.session_id]);
@@ -215,7 +471,7 @@ export function bindRunningWorkSession(context, input) {
     }
     const now = context.now();
     const id = `WS-${crypto.randomUUID()}`;
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         bindSession(context, work, run, identity, now);
         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)", [id, work.work_id, identity.sessionId, input.hookEventId, input.promptPath, input.resultPath ?? null, now, now]);
@@ -231,10 +487,22 @@ 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) ?? "{}");
-    const binding = bindRunningWorkSession(context, { ...input, allowStageHandoff: snapshot.execution_profile?.settings?.stage_session_mode === "new_session" });
+    const profile = snapshot.execution_profile;
+    const previous = context.db.get("SELECT ws.session_id, s.current_stage FROM work_sessions ws JOIN sessions s ON s.project_id = ? AND s.session_id = ws.session_id WHERE ws.work_id = ? AND ws.status = 'running' ORDER BY ws.created_at DESC LIMIT 1", [work.project_id, work.work_id]);
+    let sessionMode = profile?.settings.stage_session_mode ?? "same_session";
+    if (profile?.settings.execution) {
+        if (!profile.agent_profiles)
+            throw new AppError("execution_profile_not_frozen", "Stage handoff requires frozen RUN profiles", 1);
+        sessionMode = resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy: profile.settings.execution, profiles: profile.agent_profiles, ...(previous?.current_stage ? { fromStage: previous.current_stage } : {}), stage: input.stage, stageSessionMode: sessionMode, mergeMode: profile.settings.merge_mode }).session_mode;
+    }
+    const identity = hookSessionIdentity(context, work.project_id, input.hookEventId);
+    if (previous?.current_stage && previous.current_stage !== input.stage && sessionMode === "new_session" && previous.session_id === identity.sessionId)
+        throw new AppError("stage_handoff_required", "This stage requires a fresh coordinator Session under its frozen execution policy", 1, { from_stage: previous.current_stage, stage: input.stage });
+    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 binding = bindRunningWorkSession(context, { ...input, allowStageHandoff: sessionMode === "new_session" });
     context.db.run("UPDATE sessions SET current_stage = ?, updated_at = ? WHERE project_id = ? AND session_id = ?", [input.stage, context.now(), work.project_id, binding.session_id]);
     refreshRunSessionProjection(context, work.project_id, work.run_id);
     return binding;
@@ -242,95 +510,293 @@ 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);
     if (input.projectRoot && resolveProjectRoot(input.projectRoot) !== resolveProjectRoot(run.project_root))
         throw new AppError("project_mismatch", "stage coordinator project root does not match its RUN", 1, { work_id: work.work_id });
-    const identity = 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 binding = startBoundWork(context, work, run, identity, input.hookEventId);
-    const sessionId = String(binding.session_binding.session_id ?? "");
-    context.db.run("UPDATE sessions SET current_stage = ?, updated_at = ? WHERE project_id = ? AND session_id = ?", [input.stage, context.now(), work.project_id, sessionId]);
+    const binding = startBoundWork(context, work, run, () => 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 } : {}) }), input.hookEventId, input.stage);
     refreshRunSessionProjection(context, work.project_id, work.run_id);
     return binding;
 }
-/** Stage entry points call this only after their own trusted hook claim. */
-export function startBoundWork(context, work, run, identity, hookEventId) {
-    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();
-    const linkId = `WS-${crypto.randomUUID()}`;
+/** Claim, command authority and binding commit together; only packet projection follows. */
+export function startBoundWork(context, work, run, claimIdentity, hookEventId, stage) {
+    const generation = assertRunMutationAllowed(context, work.project_id, work.run_id);
     const directory = path.join(requireRunHome(run), "works", work.work_id);
-    fs.mkdirSync(directory, { recursive: true });
-    const promptPath = path.join(directory, "prompt.md");
-    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 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 token = crypto.randomUUID();
-    const promptCandidate = `${promptPath}.${token}.tmp`;
-    const contextCandidate = `${contextPath}.${token}.tmp`;
-    fs.writeFileSync(promptCandidate, prompt);
-    fs.writeFileSync(contextCandidate, `${JSON.stringify(workContext, null, 2)}\n`);
-    context.db.exec("BEGIN IMMEDIATE");
+    const linkId = `WS-${crypto.randomUUID()}`;
+    // Recovery can reopen the same Work without retiring its historical packet.
+    // Give each new-generation start its own immutable publication destination.
+    const packetDirectory = generation > 0 ? path.join(directory, "starts", linkId) : directory;
+    const promptPath = path.join(packetDirectory, "prompt.md"), resultPath = path.join(directory, "result.json");
+    // The first reviewer freezes shared inputs in the same transaction as its claim.
+    const readOnly = parsePayload(work)?.read_only === true;
+    let fingerprint;
+    let binding;
     try {
-        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]);
-        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);
-        context.db.exec("COMMIT");
+        binding = context.db.writeTransaction(() => {
+            const current = requireWork(context, work.work_id);
+            assertRunMutationAllowed(context, current.project_id, current.run_id, generation);
+            if (current.status !== "created")
+                throw new AppError("conflict", "Work was claimed concurrently", 1, { work_id: current.work_id, status: current.status });
+            if (Object.keys(current).some(key => current[key] !== work[key]))
+                throw new AppError("work_not_ready", "Work inputs changed while preparing its start packet", 2, { work_id: current.work_id });
+            if (!isReady(context, current))
+                throw new AppError("work_not_ready", "Work dependencies are not ready", 2, { work_id: current.work_id, blockers: readinessBlockers(context, current) });
+            if (fs.existsSync(path.join(directory, ".retry.json")))
+                throw new AppError("work_retry_incomplete", "Complete the interrupted Work retry before starting its next attempt", 1, { work_id: work.work_id });
+            const identity = claimIdentity();
+            assertRecoveryHookCurrent(context, current.project_id, current.run_id, identity);
+            const dependencyResults = parseDependencies(current).map(dependency => context.db.get("SELECT work_id, result FROM works WHERE work_id = ?", [dependency])).filter(Boolean);
+            const recovery = recoveryPromptForWork(context, current.work_id);
+            let prompt = renderWorkerPrompt(context, current, run, dependencyResults);
+            if (recovery)
+                prompt = `${recoveryPrompt(recovery)}\n\n${prompt}`;
+            if (readOnly)
+                fingerprint = sharedReviewInput(work, run, true) ?? workspaceFingerprint(run.workspace_root);
+            const workContext = { schema_id: "dd-flow/work-context@1", run_id: current.run_id, work_id: current.work_id, parent_work_id: current.parent_work_id, project_root: run.project_root, workspace_root: run.workspace_root, run_root: requireRunHome(run), depends_on: parseDependencies(current), launch_policy: current.launch_policy, result_schema: current.result_schema, read_only: readOnly, ...(recovery ? { recovery } : {}), ...(readOnly ? { workspace_fingerprint: fingerprint } : {}) };
+            const contextBytes = `${JSON.stringify(workContext, null, 2)}\n`;
+            const response = { ok: true, work_id: current.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 } } };
+            const receipt = JSON.stringify({ version: 1, prompt, context: contextBytes, prompt_sha256: sha256(prompt), context_sha256: sha256(contextBytes), response, response_sha256: sha256(JSON.stringify(response)), generation, invocation_id: context.env.DD_FLOW_CURRENT_INVOCATION ?? null });
+            const now = context.now();
+            bindSession(context, current, run, identity, now);
+            if (current.parent_work_id && current.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, current.work_id]);
+            if (context.db.run("UPDATE works SET status = 'running', started_at = COALESCE(started_at, ?), updated_at = ? WHERE work_id = ? AND status = 'created'", [now, now, current.work_id]).changes !== 1)
+                throw new AppError("conflict", "Work was claimed concurrently", 1, { work_id: current.work_id });
+            context.db.run("INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, start_receipt_json, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, ?, NULL)", [linkId, current.work_id, identity.sessionId, hookEventId, promptPath, resultPath, receipt, now, now]);
+            if (stage)
+                context.db.run("UPDATE sessions SET current_stage = ?, updated_at = ? WHERE project_id = ? AND session_id = ?", [stage, now, current.project_id, identity.sessionId]);
+            if (recovery)
+                activateRecoveryWork(context, current.work_id);
+            return response;
+        });
     }
     catch (error) {
-        context.db.exec("ROLLBACK");
-        fs.rmSync(promptCandidate, { force: true });
-        fs.rmSync(contextCandidate, { force: true });
+        // This transaction publishes only SQL authority, never files or provider calls.
+        if (error instanceof AppError && error.code === "storage_write_failed" && error.details.transaction_rolled_back === true)
+            error.details.effect = "no_effect";
+        if (error instanceof AppError && error.details.effect === "no_effect" && !context.env.DD_FLOW_CURRENT_INVOCATION) {
+            let retry = false;
+            try {
+                retry = context.db.writeTransaction(() => {
+                    if (context.db.get("SELECT 1 FROM hook_events WHERE project_id = ? AND json_extract(outcome_json, '$.work_id') = ? AND json_extract(outcome_json, '$.generation') = ? AND json_extract(outcome_json, '$.storage_retry') = 1", [work.project_id, work.work_id, generation]))
+                        return false;
+                    return context.db.run("UPDATE hook_events SET outcome_json = ? WHERE project_id = ? AND event_key = ? AND status = 'observed' AND outcome_json IS NULL", [JSON.stringify({ work_id: work.work_id, run_id: work.run_id, generation, effect: "no_effect", disposition: "retrying", storage_retry: 1, deadline: Date.now() + 60000 }), work.project_id, hookEventId]).changes === 1;
+                });
+            }
+            catch (persistence) {
+                error.details.retry_persistence_error = String(persistence);
+            }
+            if (retry)
+                return startBoundWork(context, work, run, claimIdentity, hookEventId, stage);
+        }
         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 } } };
+    try {
+        materializePendingWorkStarts(context, work.project_id, work.run_id);
+        refreshRunWorkProjection(context, work.project_id, work.run_id);
+    }
+    catch (error) {
+        if (error instanceof AppError) {
+            error.details.effect = "committed";
+            throw error;
+        }
+        throw new AppError("work_start_publication_failed", error instanceof Error ? error.message : String(error), 1, { effect: "committed", work_id: work.work_id, hook_event_id: hookEventId, cause: { code: error?.code ?? null } });
+    }
+    return binding;
+}
+/** Read the exact committed reply, never bind another Session or regenerate a packet. */
+export function recoverCommittedWorkStart(context, invocationId, eventKey, generation, workId) {
+    const row = context.db.get("SELECT ws.start_receipt_json, w.project_id, w.run_id FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE ws.start_receipt_json IS NOT NULL AND ws.hook_event_id = ? AND json_extract(ws.start_receipt_json, '$.invocation_id') IS ? AND (? IS NULL OR w.work_id = ?)", [eventKey, invocationId, workId ?? null, workId ?? null]);
+    if (!row)
+        return undefined;
+    const receipt = JSON.parse(row.start_receipt_json);
+    if (receipt.generation !== generation || !receipt.response || receipt.response_sha256 !== sha256(JSON.stringify(receipt.response)))
+        throw new AppError("work_start_receipt_invalid", "Committed reply identity or checksum differs", 1, { invocation_id: invocationId });
+    assertRunMutationAllowed(context, row.project_id, row.run_id, generation);
+    materializePendingWorkStarts(context, row.project_id, row.run_id);
+    return receipt.response;
+}
+/** Root coordinators have no worker checks: settle them inside the stage transaction. */
+export function finishStageCoordinatorWork(context, id, result) {
+    const work = requireWork(context, id);
+    if (work.parent_work_id !== null || codePacket(work) || parsePayload(work)?.read_only)
+        throw new AppError("invalid_work_state", "Stage settlement requires a root coordinator", 2);
+    const run = requireRun(context, work.project_id, work.run_id);
+    const link = context.db.get("SELECT * FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [id]);
+    if (!link)
+        throw new AppError("runtime_missing", "Coordinator has no open Work/Session link", 1);
+    validateWorkResult(work, result, run.project_root, run.workspace_root, requireRunHome(run), run.id, link.result_path);
+    finishFanInWork(context, id, result);
+    context.db.run("UPDATE sessions SET status = 'idle', updated_at = ? WHERE project_id = ? AND session_id = ? AND NOT EXISTS (SELECT 1 FROM work_sessions WHERE session_id = ? AND status = 'running')", [context.now(), work.project_id, link.session_id, link.session_id]);
+    settleRecoveryWork(context, id, "completed");
 }
-export function finishWork(context, id, result, progress) { return settle(context, id, "completed", result, progress); }
+export function finishWork(context, id, result, progress, retry) { return settle(context, id, "completed", result, progress, retry); }
 /** 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")
-    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))
-        fs.renameSync(source, path.join(archive, file));
-} 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) {
+export function prepareWorkSettlement(context, id, status, result) {
+    if (status !== "completed" && (typeof result !== "string" || !result.trim()))
+        throw new AppError("usage", "Work settlement requires a nonempty --reason", 2);
     const work = requireWork(context, id);
-    id = work.work_id;
+    assertWorkSettlementAllowed(context, work.project_id, work.run_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 });
-    if (status === "completed" && context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created', 'running', 'paused') LIMIT 1", [id]))
-        throw new AppError("active_child_work", "Work cannot complete while a child Work is active", 2, { work_id: id });
+    if (status === "completed" && 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", "Work cannot complete while a child Work is active", 2, { work_id: work.work_id });
     const run = requireRun(context, work.project_id, work.run_id);
-    const link = 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", [id]);
+    const link = 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 (work.status === "running" && !link)
-        throw new AppError("runtime_missing", "Running Work has no open Work/Session link", 1, { work_id: id });
+        throw new AppError("runtime_missing", "Running Work has no open Work/Session link", 1, { work_id: work.work_id });
+    return { work, run, link };
+}
+export function prepareWorkRetry(context, id, reason) {
+    if (typeof reason !== "string" || !reason.trim())
+        throw new AppError("usage", "Work retry requires a nonempty --reason", 2);
+    const work = requireWork(context, id);
+    assertRunMutationAllowed(context, work.project_id, work.run_id);
+    const run = requireRun(context, work.project_id, work.run_id);
+    const directory = path.join(requireRunHome(run), "works", work.work_id);
+    const journal = path.join(directory, ".retry.json");
+    let pending = null;
+    if (fs.existsSync(journal)) {
+        let value;
+        try {
+            value = JSON.parse(fs.readFileSync(journal, "utf8"));
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
+            throw new AppError("work_retry_invalid", "Retry journal is not valid JSON", 1);
+        }
+        const item = value;
+        if (!item || typeof item !== "object" || item.work_id !== work.work_id || typeof item.archive !== "string" || !/^ATT-\d{3,}$/.test(item.archive) || !Array.isArray(item.entries) || item.entries.some(file => !["prompt.md", "result.json", "context.json"].includes(file)) || new Set(item.entries).size !== item.entries.length || !(item.result_sha256 === null || typeof item.result_sha256 === "string" && /^[a-f0-9]{64}$/.test(item.result_sha256)))
+            throw new AppError("work_retry_invalid", "Retry journal does not identify this Work", 1);
+        pending = item;
+    }
+    if (work.status !== "failed" && !(pending && work.status === "created"))
+        throw new AppError("invalid_work_state", "Only failed Work may be retried", 2);
+    const attempts = path.join(directory, "attempts");
+    let number = 1;
+    while (fs.existsSync(path.join(attempts, `ATT-${String(number).padStart(3, "0")}`)))
+        number += 1;
+    const prepared = pending ?? { work_id: work.work_id, archive: `ATT-${String(number).padStart(3, "0")}`, entries: ["prompt.md", "result.json", "context.json"].filter(file => fs.existsSync(path.join(directory, file))), result_sha256: work.result === null ? null : crypto.createHash("sha256").update(work.result).digest("hex") };
+    const archive = path.join(attempts, prepared.archive);
+    if (work.status === "failed") {
+        if (prepared.result_sha256 !== (work.result === null ? null : crypto.createHash("sha256").update(work.result).digest("hex")))
+            throw new AppError("work_retry_conflict", "Failed Work receipt changed during retry", 1);
+        const receipt = path.join(archive, "accepted-receipt.json");
+        if (fs.existsSync(receipt) && fs.readFileSync(receipt, "utf8") !== JSON.stringify({ work_id: work.work_id, status: work.status, result: work.result, result_sha256: prepared.result_sha256 }))
+            throw new AppError("work_retry_conflict", "Archived receipt differs from failed Work", 1);
+        for (const file of prepared.entries) {
+            const source = path.join(directory, file), target = path.join(archive, file);
+            if (fs.existsSync(source) && fs.existsSync(target))
+                throw new AppError("archive_conflict", "Both live and archived Work artifact exist; preserve both", 1, { source, target });
+            if (!fs.existsSync(source) && !fs.existsSync(target))
+                throw new AppError("archive_artifact_missing", "Work artifact is absent from both retry locations", 1, { source, target });
+        }
+    }
+    return { work, run, directory, journal, pending, prepared, archive };
+}
+export function retryWork(context, id, reason) {
+    const { work, run, directory, journal } = prepareWorkRetry(context, id, reason);
+    let archive = "";
+    context.db.beginWriteTransaction();
+    try {
+        const { work: current, pending, prepared, archive: targetArchive } = prepareWorkRetry(context, work.work_id, reason);
+        archive = targetArchive;
+        if (current.status === "failed") {
+            if (prepared.result_sha256 !== (current.result === null ? null : crypto.createHash("sha256").update(current.result).digest("hex")))
+                throw new AppError("work_retry_conflict", "Failed Work receipt changed during retry", 1);
+            fs.mkdirSync(archive, { recursive: true });
+            if (!pending)
+                publishReceiptFile(journal, JSON.stringify(prepared));
+            const receipt = path.join(archive, "accepted-receipt.json");
+            const receiptBytes = JSON.stringify({ work_id: current.work_id, status: current.status, result: current.result, result_sha256: prepared.result_sha256 });
+            if (fs.existsSync(receipt) && fs.readFileSync(receipt, "utf8") !== receiptBytes)
+                throw new AppError("work_retry_conflict", "Archived receipt differs from failed Work", 1);
+            if (!fs.existsSync(receipt))
+                publishReceiptFile(receipt, receiptBytes);
+            for (const file of prepared.entries) {
+                const source = path.join(directory, file), target = path.join(archive, file);
+                if (fs.existsSync(source)) {
+                    if (fs.existsSync(target))
+                        throw new AppError("archive_conflict", "Both live and archived Work artifact exist; preserve both", 1, { source, target });
+                    fs.renameSync(source, target);
+                }
+                else if (!fs.existsSync(target))
+                    throw new AppError("archive_artifact_missing", "Work artifact is absent from both retry locations", 1, { source, target });
+            }
+            for (const folder of [archive, directory]) {
+                const descriptor = fs.openSync(folder, "r");
+                try {
+                    fs.fsyncSync(descriptor);
+                }
+                finally {
+                    fs.closeSync(descriptor);
+                }
+            }
+            for (const column of ["prompt_path", "result_path"]) {
+                const file = column === "prompt_path" ? "prompt.md" : "result.json";
+                context.db.run(`UPDATE work_sessions SET ${column} = ? WHERE work_id = ? AND ${column} = ?`, [path.join(archive, file), work.work_id, path.join(directory, file)]);
+            }
+            context.db.run("UPDATE works SET status = 'created', result = NULL, started_at = NULL, completed_at = NULL, updated_at = ? WHERE work_id = ? AND status = 'failed'", [context.now(), work.work_id]);
+        }
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    fs.rmSync(journal, { force: true });
+    refreshRunWorkProjection(context, work.project_id, work.run_id);
+    return { ok: true, work_id: work.work_id, archived_attempt: path.relative(requireRunHome(run), archive).split(path.sep).join("/"), reason };
+}
+function sharedReviewInput(work, run, initialize = false) {
+    const kind = parsePayload(work)?.kind;
+    const relative = kind === "code-review" ? "06-code-review/review-context.json" : kind === "plan-review" ? "04-plan-review/work-context.json" : null;
+    if (!relative || !work.parent_work_id)
+        return null;
+    const file = path.join(requireRunHome(run), relative);
+    if (!fs.existsSync(file))
+        return null;
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (value.read_only_input?.parent_work_id !== work.parent_work_id)
+        return null;
+    if (!value.read_only_input.fingerprint && initialize) {
+        // Called under the Work-start writer reservation, after stage setup has
+        // finished. The first reviewer accepts the input shared by this group.
+        value.read_only_input.fingerprint = workspaceFingerprint(run.workspace_root);
+        const temporary = `${file}.tmp-${crypto.randomUUID()}`;
+        fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
+        fs.renameSync(temporary, file);
+    }
+    return typeof value.read_only_input.fingerprint === "string" ? value.read_only_input.fingerprint : null;
+}
+async function settle(context, id, status, result, progress, retry) {
+    const { work, run, link } = prepareWorkSettlement(context, id, status, result);
+    id = work.work_id;
     let receipts = [];
     let coordinationDrift = [];
-    if (status === "completed") {
-        if (parsePayload(work)?.read_only === true) {
+    const assertReadOnlyInput = () => {
+        if (status === "completed" && parsePayload(work)?.read_only === true) {
+            const shared = sharedReviewInput(work, run);
+            // The final reviewer commits the shared input boundary under the writer
+            // reservation. Concurrent finishes cannot both skip this verification.
+            if (shared && context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ? AND work_id <> ? AND status IN ('created','running','paused') AND json_extract(payload_json, '$.read_only') = 1 AND json_extract(payload_json, '$.kind') = ? LIMIT 1", [work.project_id, work.run_id, work.parent_work_id, work.work_id, parsePayload(work)?.kind]))
+                return;
             const contextFile = link ? path.join(path.dirname(link.prompt_path), "context.json") : "";
-            const baseline = contextFile && fs.existsSync(contextFile) ? JSON.parse(fs.readFileSync(contextFile, "utf8")).workspace_fingerprint : null;
+            const baseline = shared ?? (contextFile && fs.existsSync(contextFile) ? JSON.parse(fs.readFileSync(contextFile, "utf8")).workspace_fingerprint : null);
             const current = workspaceFingerprint(run.workspace_root);
             if (typeof baseline !== "string" || baseline !== current)
-                throw new AppError("read_only_work_mutated_workspace", "Read-only Work changed the accepted workspace", 2, { work_id: work.work_id, baseline, current });
+                throw new AppError("read_only_input_changed", "The workspace changed during read-only Work; its review input is stale (the writer is unknown)", 2, { work_id: work.work_id, baseline, current });
         }
+    };
+    if (status === "completed") {
         validateWorkResult(work, result, run.project_root, run.workspace_root, requireRunHome(run), run.id, link?.result_path ?? null);
         const packet = codePacket(work);
         if (packet) {
@@ -340,19 +806,28 @@ async function settle(context, id, status, result, progress) {
             readCodeCheckProfile(run.workspace_root);
             coordinationDrift = plannedAreaDrift(packet, result);
             const artifactDir = path.relative(requireRunHome(run), path.dirname(link.result_path));
-            receipts = await runCodeChecks(context, { projectId: work.project_id, runId: work.run_id, runHome: requireRunHome(run), workspaceRoot: run.workspace_root, workId: work.work_id, artifactDir, scope: "work", checks: packet.checks.filter((check) => check.run_at === "work"), ...(progress ? { progress } : {}) });
+            const requiredChecks = packet.repair?.verification_check_refs?.length
+                ? uniqueChecks([...packet.checks.filter((check) => check.run_at === "work"), ...packet.repair.verification_check_refs])
+                : packet.checks.filter((check) => check.run_at === "work");
+            if (retry)
+                validateFailedCheckRetry(context, { projectId: work.project_id, runId: work.run_id, receiptId: retry.receiptId, declarations: requiredChecks, reason: retry.reason });
+            receipts = await runCodeChecks(context, { projectId: work.project_id, runId: work.run_id, runHome: requireRunHome(run), workspaceRoot: run.workspace_root, workId: work.work_id, artifactDir, scope: "work", checks: requiredChecks, ...(retry ? { retryReceiptId: retry.receiptId, retryReason: retry.reason } : {}), ...(progress ? { progress } : {}) });
             const failed = receipts.filter((receipt) => receipt.status !== "passed");
             if (failed.length)
                 throw new AppError("work_checks_failed", "Work remains running because required checks failed", 2, { work_id: id, failures: failed, all_receipts: receipts });
         }
     }
     const now = context.now();
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
+        assertReadOnlyInput();
+        assertWorkSettlementAllowed(context, work.project_id, work.run_id, work.work_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 });
+        if (link?.result_path && work.parent_work_id !== null)
+            publishReceiptFile(receiptIntentPath(link.result_path, link.id), JSON.stringify({ work_id: work.work_id, work_session_id: link.id, status, result_sha256: crypto.createHash("sha256").update(result).digest("hex"), previous_sha256: receiptFileHash(link.result_path) }));
         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)
-                fs.writeFileSync(link.result_path, result);
             context.db.run("UPDATE work_sessions SET status = ?, completed_at = ?, updated_at = ? WHERE id = ?", [status, now, now, link.id]);
             const stillRunning = context.db.get("SELECT 1 FROM work_sessions WHERE session_id = ? AND status = 'running' LIMIT 1", [link.session_id]);
             if (!stillRunning)
@@ -364,18 +839,25 @@ async function settle(context, id, status, result, progress) {
         context.db.exec("ROLLBACK");
         throw error;
     }
+    materializePendingWorkResults(context, work.project_id, work.run_id);
+    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, start_command: workStartCommand(context, candidate) }));
+    const control = runControlDirective(context, work.project_id, work.run_id);
+    const newlyReady = control ? [] : 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 } : {}) });
     for (const ready of newlyReady)
         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" } };
+    return { ok: true, ...(control ? { control } : {}), 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)
         return [];
-    return changed.filter((item) => typeof item === "string" && !packet.planned_write_areas.some((area) => item === area || item.startsWith(`${area}/`)));
+    return changed.filter((item) => typeof item === "string" && !packet.planned_write_areas.some((area) => {
+        const normalized = area.replace(/[\\/]+$/, "");
+        return item === normalized || item.startsWith(`${normalized}/`);
+    }));
 }
 function bindSession(context, work, run, identity, now) {
     const priorWorkSession = context.db.get("SELECT session_id FROM work_sessions WHERE work_id = ? ORDER BY created_at DESC LIMIT 1", [work.work_id])?.session_id ?? null;
@@ -385,16 +867,28 @@ function bindSession(context, work, run, identity, now) {
     // Work ancestry and provider-tree containment are different relations. An
     // isolated worker is logically a child Work but physically a provider root.
     const parentSession = inferredParentSession ?? identity.parentSessionId;
+    // Stored provider ancestry uses internal keys, just like hook_events.
+    // Resolve native IDs only when rendering diagnostics; changing storage here
+    // breaks existing bindings and usage ancestry joins.
     const providerParentSession = identity.parentSessionId;
+    const identityDetails = (sessionKey = identity.sessionId, parentKey = parentSession) => ({
+        internal_session_key: sessionKey,
+        native_session_id: sessionKey === identity.sessionId ? identity.nativeSessionId : context.db.get("SELECT provider_session_id FROM sessions WHERE project_id = ? AND session_id = ?", [work.project_id, sessionKey])?.provider_session_id ?? null,
+        internal_parent_session_key: parentKey,
+        native_parent_session_id: parentKey ? context.db.get("SELECT provider_session_id FROM sessions WHERE project_id = ? AND session_id = ?", [work.project_id, parentKey])?.provider_session_id ?? null : null,
+        harness: identity.harness
+    });
     if (work.parent_work_id && !parentSession)
         throw new AppError("parent_session_required", "Child Work requires a confirmed parent Work/Session link", 1, { work_id: work.work_id, parent_work_id: work.parent_work_id });
     if (work.launch_policy === "fresh_agent_required" && (identity.sessionId === parentSession || context.db.get("SELECT 1 FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ? LIMIT 1", [work.project_id, work.run_id, identity.sessionId])))
-        throw new AppError("fresh_session_required", "This Work requires a fresh Session in this RUN", 1, { work_id: work.work_id, session_id: identity.sessionId });
+        throw new AppError("fresh_session_required", "This Work requires a fresh Session in this RUN", 1, { work_id: work.work_id, effect: "no_effect", recoverable: true, handoff_required: true, ...identityDetails() });
     const existing = context.db.get("SELECT session_id, parent_session_id, provider_parent_session_id FROM sessions WHERE project_id = ? AND session_id = ?", [work.project_id, identity.sessionId]);
-    if (existing && existing.parent_session_id && parentSession && existing.parent_session_id !== parentSession)
-        throw new AppError("session_parent_conflict", "Observed Session already has a different immutable parent", 1, { session_id: identity.sessionId });
+    // A reuse-allowed Work can follow another Work in this same Session. Its
+    // Work predecessor is not a new physical/logical parent of the Session.
+    if (existing && existing.parent_session_id && parentSession && parentSession !== identity.sessionId && existing.parent_session_id !== parentSession)
+        throw new AppError("session_parent_conflict", "Observed Session already has a different immutable parent", 1, { work_id: work.work_id, ...identityDetails(existing.session_id, existing.parent_session_id), conflicting_internal_parent_session_key: parentSession });
     if (existing?.provider_parent_session_id && providerParentSession && existing.provider_parent_session_id !== providerParentSession)
-        throw new AppError("provider_session_parent_conflict", "Observed provider Session already has a different immutable provider parent", 1, { session_id: identity.sessionId });
+        throw new AppError("provider_session_parent_conflict", "Observed provider Session already has a different immutable provider parent", 1, { work_id: work.work_id, ...identityDetails(existing.session_id, existing.parent_session_id), conflicting_internal_provider_parent_session_key: providerParentSession, conflicting_native_parent_session_id: context.db.get("SELECT provider_session_id FROM sessions WHERE project_id = ? AND session_id = ?", [work.project_id, providerParentSession])?.provider_session_id ?? null });
     context.db.run(`INSERT INTO sessions (session_id, project_id, harness, provider_session_id, provider_parent_session_id, agent_id, parent_session_id, provider, model, reasoning, mode, agent_type, project_root, flow_kind, status, run_id, protocol_id, worker_id, workspace_path, continuation_policy, current_stage, next_action, last_action_hash, continuation_count, stop_reason, transcript_path, cwd, metadata_json, coverage_units_json, created_at, updated_at, stopped_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'vnext', 'active', ?, NULL, ?, ?, 'go_router', 'work', NULL, NULL, 0, NULL, ?, ?, '{}', '[]', ?, ?, NULL) ON CONFLICT(session_id, project_id) DO UPDATE SET harness = excluded.harness, provider_session_id = COALESCE(excluded.provider_session_id, provider_session_id), provider_parent_session_id = COALESCE(excluded.provider_parent_session_id, provider_parent_session_id), agent_id = COALESCE(excluded.agent_id, agent_id), parent_session_id = COALESCE(excluded.parent_session_id, parent_session_id), provider = COALESCE(excluded.provider, provider), model = COALESCE(excluded.model, model), reasoning = COALESCE(excluded.reasoning, reasoning), mode = COALESCE(excluded.mode, mode), agent_type = COALESCE(excluded.agent_type, agent_type), flow_kind = excluded.flow_kind, run_id = excluded.run_id, worker_id = excluded.worker_id, workspace_path = excluded.workspace_path, transcript_path = COALESCE(excluded.transcript_path, transcript_path), cwd = excluded.cwd, updated_at = excluded.updated_at`, [identity.sessionId, work.project_id, identity.harness, identity.providerSessionId, providerParentSession, identity.agentId, existing?.parent_session_id ?? (parentSession === identity.sessionId ? null : parentSession), identity.provider, identity.model, identity.reasoning, identity.mode, identity.agentType, run.project_root, work.run_id, work.work_id, run.workspace_root, identity.transcriptPath, run.workspace_root, now, now]);
     reactivateBoundSession(context, work.project_id, identity.sessionId, now);
 }
@@ -408,6 +902,15 @@ export function bindSessionForResume(context, workId, identity, now) {
 function reactivateBoundSession(context, projectId, sessionId, now) {
     context.db.run("UPDATE sessions SET status = 'active', stop_reason = NULL, stopped_at = NULL, updated_at = ? WHERE project_id = ? AND session_id = ?", [now, projectId, sessionId]);
 }
+export function prepareWorkResult(context, id, result) {
+    try {
+        const { work, run, link } = prepareWorkSettlement(context, id, "completed", result);
+        validateWorkResult(work, result, run.project_root, run.workspace_root, requireRunHome(run), run.id, link?.result_path ?? null);
+    }
+    catch (error) {
+        prepareError(error, { work_id: id });
+    }
+}
 function validateWorkResult(work, result, projectRoot, workspaceRoot, runHome, runId, resultPath) {
     if (!work.result_schema)
         return;
@@ -420,15 +923,8 @@ function validateWorkResult(work, result, projectRoot, workspaceRoot, runHome, r
     catch {
         throw new AppError("validation", "Work result must be JSON for its declared result schema", 2, { work_id: work.work_id, result_schema: work.result_schema });
     }
-    const candidate = `${resultPath}.candidate-${process.pid}`;
-    fs.writeFileSync(candidate, result);
-    try {
-        validateSchema({ schemaName: work.result_schema.replace(/^dd-flow\//, "").replace(/@\d+$/, ""), file: candidate, projectRoot, runId, runRoot: runHome });
-    }
-    finally {
-        fs.rmSync(candidate, { force: true });
-    }
-    if (work.result_schema === "dd-flow/code-work-result@2")
+    validateSchema({ schemaName: work.result_schema.replace(/^dd-flow\//, "").replace(/@\d+$/, ""), file: resultPath, data: parsed, projectRoot, runId, runRoot: runHome });
+    if (work.result_schema === "dd-flow/code-work-result@3")
         validateCodeWorkResult(work, parsed, workspaceRoot, runHome, runId);
     if (work.result_schema === "dd-flow/code-review-result@1")
         validateCodeReviewResult(work, parsed, { workspaceRoot, runHome, runId });
@@ -437,20 +933,29 @@ function validateWorkResult(work, result, projectRoot, workspaceRoot, runHome, r
 }
 function validateCodeWorkResult(work, value, projectRoot, runHome, runId) {
     const result = value;
+    const changedPaths = (result.changed_paths ?? []).map((item) => normalizeWorkspacePath(projectRoot, item));
+    const ignored = ignoredWorkspacePaths(projectRoot, changedPaths);
+    if (ignored.length)
+        throw new AppError("environment_repair_not_product_change", "CODE Work must record ignored environment repair separately, not as a product changed_path", 2, { work_id: work.work_id, paths: ignored });
     if ((result.deviations?.length ?? 0) > 0 || (result.blockers?.length ?? 0) > 0)
         throw new AppError("work_contract_incomplete", "CODE Work cannot complete with unresolved deviations or blockers; fail the Work and report the contract mismatch", 2, { work_id: work.work_id, deviations: result.deviations ?? [], blockers: result.blockers ?? [] });
     const packet = codePacket(work);
     if (!packet)
         return;
-    const acceptedCriteria = new Set(packet.acceptance.map((item) => item.criterion_id).filter((item) => typeof item === "string"));
+    const acceptedObligations = new Set(packet.acceptance.map((item) => item.criterion_id).filter((item) => typeof item === "string"));
+    for (const check of packet.checks)
+        acceptedObligations.add(check.id);
+    for (const finding of packet.repair?.review_findings ?? [])
+        for (const ref of finding.obligation_refs ?? [])
+            acceptedObligations.add(ref);
     for (const item of result.evidence ?? []) {
-        if (!item.criterion_id || !acceptedCriteria.has(item.criterion_id))
-            throw new AppError("evidence_criterion_unknown", "CODE Work evidence must reference an acceptance criterion assigned to this Work", 2, { work_id: work.work_id, criterion_id: item.criterion_id ?? null });
+        if (!item.obligation_ref || !acceptedObligations.has(item.obligation_ref))
+            throw new AppError("evidence_obligation_unknown", "CODE Work evidence must reference an obligation assigned to this Work", 2, { work_id: work.work_id, obligation_ref: item.obligation_ref ?? null, accepted_obligation_refs: [...acceptedObligations] });
         for (const ref of item.refs ?? [])
             assertPortableArtifactRef(ref, { workspaceRoot: projectRoot, runHome, runId });
     }
     const documentUpdates = (packet.document_updates ?? []);
-    const changed = new Set(result.changed_paths ?? []);
+    const changed = new Set(changedPaths);
     const missingDocuments = documentUpdates.map((entry) => entry.path).filter((entry) => !changed.has(entry));
     if (missingDocuments.length)
         throw new AppError("document_update_missing", "CODE Work did not materialize every document update assigned by PLAN", 2, { work_id: work.work_id, missing_paths: missingDocuments });
@@ -458,36 +963,73 @@ function validateCodeWorkResult(work, value, projectRoot, runHome, runId) {
         return true; const current = crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); return entry.action === "create" ? entry.baseline_sha256 !== null : current === entry.baseline_sha256; }).map((entry) => entry.path);
     if (unchangedDocuments.length)
         throw new AppError("document_update_not_materialized", "Assigned durable document updates must exist and differ from their PLAN baseline", 2, { work_id: work.work_id, unchanged_paths: unchangedDocuments });
-    const assigned = packet.repair?.review_finding_ids ?? [];
+    const assigned = packet.repair?.review_findings?.map((finding) => finding.finding_ref) ?? [];
+    validateReviewResolutions(work.work_id, assigned, result.resolutions ?? []);
     if (assigned.length) {
-        if ((result.changed_paths?.length ?? 0) === 0)
+        if (changedPaths.length === 0)
             throw new AppError("review_repair_no_change", "Review repair must materialize a project change; a no-op cannot resolve a finding", 2, { work_id: work.work_id, findings: assigned });
-        const resolved = new Set(result.resolved_finding_refs ?? []);
-        const missing = assigned.filter((finding) => !resolved.has(finding));
-        const unexpected = [...resolved].filter((finding) => !assigned.includes(finding));
-        if (missing.length || unexpected.length)
-            throw new AppError("review_repair_incomplete", "Review repair must explicitly resolve exactly its assigned finding references", 2, { work_id: work.work_id, missing, unexpected });
+        for (const resolution of result.resolutions ?? [])
+            for (const ref of resolution.evidence_refs ?? [])
+                assertPortableArtifactRef(ref, { workspaceRoot: projectRoot, runHome, runId });
     }
 }
+export function validateReviewResolutions(workId, assigned, resolutions) {
+    const resolved = new Set(resolutions.map((resolution) => resolution.finding_ref).filter((ref) => Boolean(ref)));
+    const missing = assigned.filter((finding) => !resolved.has(finding));
+    const unexpected = [...resolved].filter((finding) => !assigned.includes(finding));
+    const duplicate = resolutions.length !== resolved.size;
+    if (missing.length || unexpected.length || duplicate)
+        throw new AppError("review_repair_incomplete", "Review repair must include exactly one resolution for each assigned finding reference", 2, { work_id: workId, missing, unexpected, duplicate });
+}
 function renderWorkerPrompt(context, work, run, dependencies) {
     const command = flowCommand(context);
     const packet = codePacket(work);
-    const codeContext = packet ? ["<semantic_spine>", JSON.stringify(packet.semantic_spine, null, 2), "</semantic_spine>", "", ...(packet.repair ? ["<repair_context>", JSON.stringify(packet.repair, null, 2), "Read the failed receipt and its linked stdout/stderr before editing. Preserve the accepted origin context and fix only the evidenced failure.", "</repair_context>", ""] : []), "<accepted_requirements>", JSON.stringify(packet.requirements, null, 2), "</accepted_requirements>", "", "<write_boundary_invariant>", "For a mutation guarded by membership, ownership, authorization or parent lifecycle state, preserve that predicate in the write statement or make guard and write one explicit transaction with the needed lock. A prior read may diagnose an error but never proves a later write remains allowed. Apply this to create, update, delete and parent-state mutations.", "</write_boundary_invariant>", "", "<acceptance_context>", "The criteria below are end-to-end context. Complete this Work's semantic contribution and declared checks; another ordered Work may own a different acceptance surface.", JSON.stringify(packet.acceptance, null, 2), "</acceptance_context>", "", "<required_read>", "These are mandatory starting sources, not a read allowlist. Read any additional project files needed to implement the Work correctly.", ...packet.required_read.map((item) => `- ${resolveRunReferences(item, work.run_id, requireRunHome(run))}`), "</required_read>", "", "<discovery_boundary>", "These are likely discovery areas, not a hard boundary. Expand project-local investigation when required and report material additions.", ...packet.discovery_boundary.map((item) => `- ${item}`), "</discovery_boundary>", "", "<planned_write_areas>", "SOFT COORDINATION HINT ONLY. These paths help the coordinator avoid concurrent collisions. They do not grant or deny write permission and do not limit the files needed for this Work. You may create or change any project file under workspace_root that is necessary and in semantic scope; report every actual changed path.", ...(packet.planned_write_areas.length ? packet.planned_write_areas.map((item) => `- ${item}`) : ["- none predicted; derive the necessary files from the task"]), "</planned_write_areas>", "", ...(packet.provides_checks.length ? ["<provided_checks>", ...packet.provides_checks.map((item) => `- ${item.id}: materialize ${item.command}${item.definition ? ` as ${item.definition}` : ""}; it is not usable until this Work finishes.`), "Update the declared project command or alias before Work finish. The CLI verifies the materialization and then executes the check.", "</provided_checks>", ""] : []), "<verification>", ...packet.checks.map((item) => `- ${item.id} at ${item.run_at}: ${item.command} — ${item.purpose}`), "The CLI executes work-scoped checks and retains their receipts. Report semantic evidence only; do not rerun declared checks manually.", "</verification>", "", "<stop_conditions>", ...packet.stop_conditions.map((item) => `- ${item}`), "</stop_conditions>", ""] : [];
+    const resultInputPath = path.join(requireRunHome(run), "works", work.work_id, "result-input.json");
+    const finishWorkCommand = managedLifecycleCommand(context, runtimeCommand(context, ["work", "finish", work.work_id, "--result-file", resultInputPath, "--project-root", run.project_root, "--json", "--progress-jsonl"]));
+    const failWorkCommand = managedLifecycleCommand(context, runtimeCommand(context, ["work", "fail", shortWorkId(work.work_id), "--reason", "receipt path + exact external or semantic blocker", "--project-root", run.project_root, "--json"]));
+    const mergeWork = parsePayload(work)?.kind === "merge";
+    const writeBoundary = mergeWork
+        ? ["MERGE does not own product-code repair. Use only the stage packet's merge apply command; resolve only paths that Git reports as unmerged. Do not edit integration code, tests, documentation or configuration to make a gate pass.", "RUN artifacts are read-only evidence: refer to them with run:// URIs and let dd-flow persist your submitted result."]
+        : [`HARD RULE: project source reads and writes must remain under ${run.workspace_root}.`, "Do not write through project_root, outside workspace_root, into another RUN, or into Git/worktree control data. Do not create, switch, merge or delete branches/worktrees.", "RUN artifacts are read-only evidence: refer to them with run:// URIs and let dd-flow persist your submitted result. Accepted requirements, non-goals and stop_conditions are semantic hard boundaries. planned_write_areas is not."];
+    const completionRepair = mergeWork
+        ? ["A failed integration check is evidence for a source-repair cycle, not permission to repair the integration workspace. Follow the exact merge repair command returned by dd-flow."]
+        : ["Read the failed receipt and its stdout/stderr. Fix project-owned source, migration, test, formatting, or configuration errors in this same Work, then use the returned retry_command with your result. Internal invocation IDs are runtime-owned; do not copy or invent them. Do not invent a cause that does not appear in the retained output."];
+    const codeContext = packet ? ["<semantic_spine>", JSON.stringify(packet.semantic_spine, null, 2), "</semantic_spine>", "", ...(packet.repair ? ["<repair_context>", JSON.stringify(packet.repair, null, 2), "Read the failed receipt and its linked stdout/stderr before editing. Preserve the accepted origin context and fix only the evidenced failure.", "</repair_context>", ""] : []), "<accepted_requirements>", JSON.stringify(packet.requirements, null, 2), "</accepted_requirements>", "", "<write_boundary_invariant>", "For a mutation guarded by membership, ownership, authorization or parent lifecycle state, preserve that predicate in the write statement or make guard and write one explicit transaction with the needed lock. A prior read may diagnose an error but never proves a later write remains allowed. Apply this to create, update, delete and parent-state mutations.", "</write_boundary_invariant>", "", "<acceptance_context>", "The criteria below are end-to-end context. Complete this Work's semantic contribution and declared checks; another ordered Work may own a different acceptance surface.", JSON.stringify(packet.acceptance, null, 2), "</acceptance_context>", "", "<required_read>", "These are mandatory starting sources, not a read allowlist. Read any additional project files needed to implement the Work correctly.", ...packet.required_read.map((item) => `- ${resolveRunReferences(item, work.run_id, requireRunHome(run))}`), "</required_read>", "", "<discovery_boundary>", "These are likely discovery areas, not a hard boundary. Expand project-local investigation when required and report material additions.", ...packet.discovery_boundary.map((item) => `- ${item}`), "</discovery_boundary>", "", "<planned_write_areas>", "SOFT COORDINATION HINT ONLY. These paths help the coordinator avoid concurrent collisions. They do not grant or deny write permission and do not limit the files needed for this Work. You may create or change any project file under workspace_root that is necessary and in semantic scope; report every actual changed path.", ...(packet.planned_write_areas.length ? packet.planned_write_areas.map((item) => `- ${item}`) : ["- none predicted; derive the necessary files from the task"]), "</planned_write_areas>", "", ...(packet.provides_checks.length ? ["<provided_checks>", ...packet.provides_checks.map((item) => `- ${item.id}: materialize ${item.command}${item.definition ? ` as ${item.definition}` : ""}; it is not usable until this Work finishes.`), "Update the declared project command or alias before Work finish. The CLI verifies materialization at Work finish. Execution occurs at its declared run_at gate, not necessarily in this Work.", "</provided_checks>", ""] : []), "<verification>", ...packet.checks.map((item) => `- ${item.id} at ${item.run_at}: ${item.command} — ${item.purpose}`), "The CLI executes work-scoped checks and retains their receipts. Report semantic evidence only; do not rerun declared checks manually.", "</verification>", "", "<stop_conditions>", ...packet.stop_conditions.map((item) => `- ${item}`), "</stop_conditions>", ""] : [];
     if (packet)
         codeContext.push("<document_updates>", JSON.stringify(packet.document_updates, null, 2), "Materialize every listed update. dd-flow verifies the resulting file against its PLAN-time baseline.", "</document_updates>", "", "<completion_contract>", "Successful completion requires empty deviations and blockers and every assigned document update in changed_paths. A necessary path outside planned_write_areas is normal coordination drift, not a blocker; include it in changed_paths and continue.", "</completion_contract>", "");
-    return ["<work>", `- work_id: ${work.work_id}`, `- run_id: ${work.run_id}`, `- project_root: ${run.project_root}`, `- workspace_root: ${run.workspace_root}`, `- run_home: ${requireRunHome(run)}`, "</work>", "", "<hard_write_boundary>", `HARD RULE: project source reads and writes must remain under ${run.workspace_root}.`, "Do not write through project_root, outside workspace_root, into another RUN, or into Git/worktree control data. Do not create, switch, merge or delete branches/worktrees.", "RUN artifacts are read-only evidence: refer to them with run:// URIs and let dd-flow persist your submitted result. Accepted requirements, non-goals and stop_conditions are semantic hard boundaries. planned_write_areas is not.", "</hard_write_boundary>", "", ...codeContext, "<dependency_results>", JSON.stringify(dependencies.filter(Boolean), null, 2), "</dependency_results>", "", "<task>", resolveRunReferences(work.task, work.run_id, requireRunHome(run)), "</task>", "", ...(work.result_schema ? ["<result_contract>", `Return JSON matching \`${work.result_schema}\`.`, ...resultSchemaGuidance(work, run.id), "Do not create result.json yourself. Send the JSON to dd-flow on stdin; it atomically validates and stores the canonical receipt.", "</result_contract>", ""] : []), "<completion>", "The CLI runs every declared required check before accepting this Work. A failed receipt means only that the check failed; it is not proof of an engine, harness, dependency, or environment blocker.", "Read the failed receipt and its stdout/stderr. Fix project-owned source, migration, test, formatting, or configuration errors in this same Work, then call Finish again. Do not invent a cause that does not appear in the retained output.", "Use Fail only for a concrete external blocker after deterministic bootstrap or a contradiction with an accepted requirement/non-goal. Never fail merely because a necessary project path was absent from planned_write_areas.", "Finish may run for several minutes. Preserve the shell tool's process/session handle and poll that same invocation until it exits; progress arrives as JSONL on stderr. Never reissue Finish merely because final stdout has not arrived.", `Finish as one standalone command, piping your JSON object to stdin: ${command} work finish ${work.work_id} --result-stdin --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`, `Fail only for an evidenced external or semantic-contract blocker: ${command} work fail ${work.work_id} --reason "receipt path + exact external or semantic blocker" --project-root ${JSON.stringify(run.project_root)} --json`, "</completion>", ""].join("\n");
+    if (packet)
+        codeContext.push("<temporary_services>", "Prefer the declared check launcher: it already owns check resources. If the planned scenario genuinely requires an interactive HTTP service, use the managed supervisor below. This is a template: replace the project service command, port names and readiness path from the plan/project instructions; do not invent a fixed port.", `${command} runtime process start --run ${run.id} --project-root ${JSON.stringify(run.project_root)} --command '<project-service-command>' --ports api --ready-port api --ready-path /health --json --progress-jsonl`, "The service receives DD_FLOW_PORT_API (and equivalent variables for all declared names). The command stays running as its supervisor. Retain its tool handle; wait for the service ready event and read its service.json receipt. Pass those exact ports and the same project environment to reset/seed, API and browser operations.", "A ready receipt proves service readiness only. Record the scenario outcome and real evidence separately. After the scenario, execute the exact stop_command from that receipt, then wait for the supervisor to exit. Never use pkill/killall or stop a sibling's process. If cleanup fails, retain the process id and report the failure; do not claim the resource is free.", "</temporary_services>", "");
+    return ["<work>", `- work_id: ${work.work_id}`, `- run_id: ${work.run_id}`, `- project_root: ${run.project_root}`, `- workspace_root: ${run.workspace_root}`, `- run_home: ${requireRunHome(run)}`, "</work>", "", "<cli_context>", `- Work commands use the short ID ${shortWorkId(work.work_id)}; dd-flow binds it to this RUN.`, `- @project = ${run.project_root}`, `- @workspace = ${run.workspace_root}`, `- @run = ${requireRunHome(run)}`, "- @ aliases are accepted only by declared dd-flow path parameters. Copy the quoted alias literally; do not add backslashes. Shell tools such as cat and rg require ordinary paths relative to cwd or absolute paths.", "- Lifecycle invocation IDs are internal runtime authority and are intentionally omitted from commands.", "</cli_context>", "", "<hard_write_boundary>", ...writeBoundary, "</hard_write_boundary>", "", ...codeContext, "<dependency_results>", JSON.stringify(dependencies.filter(Boolean), null, 2), "</dependency_results>", "", "<task>", resolveRunReferences(work.task, work.run_id, requireRunHome(run)), "</task>", "", ...(work.result_schema ? ["<result_contract>", `Return JSON matching \`${work.result_schema}\`.`, ...resultSchemaGuidance(work, run.id), `Write the completed JSON to ${resultInputPath}. This is an attempt input, not the canonical result.json receipt. dd-flow validates the file and atomically stores the canonical receipt.`, "</result_contract>", ""] : []), "<completion>", packet?.repair?.verification_check_refs?.length ? "Work finish runs its normal work-scoped checks plus the listed causal repair checks. Their original run_at remains an aggregate obligation; this is the additional proof required before accepting this repair." : "Work finish runs only declared run_at=work checks. Stage finish owns readiness/code/merge gates; successful Work completion does not mean those gates have passed.", "A failed receipt means only that the check failed; it is not proof of an engine, harness, dependency, or environment blocker.", ...completionRepair, "Use Fail only for a concrete external blocker after deterministic bootstrap or a contradiction with an accepted requirement/non-goal. Never fail merely because a necessary project path was absent from planned_write_areas.", "Finish may run for several minutes. Preserve the shell tool's process/session handle and poll that same invocation until it exits; progress arrives as JSONL on stderr. Never reissue Finish merely because final stdout has not arrived.", `First write only the result JSON to ${resultInputPath}. Then run this standalone command:\n${finishWorkCommand}`, `Fail only for an evidenced external or semantic-contract blocker: ${failWorkCommand}`, "</completion>", ""].join("\n");
 }
-function resultSchemaGuidance(work, runId) {
+export function resultSchemaGuidance(work, runId) {
     const schema = work.result_schema;
     const refs = `Evidence refs for project source are relative to workspace_root; RUN evidence uses run://${runId}/path/to/artifact.`;
-    if (schema === "dd-flow/code-work-result@2")
-        return [refs, "Use this complete minimal shape. For a review repair, also include resolved_finding_refs with exactly the finding references assigned in repair_context:", "```json", JSON.stringify({ schema_id: schema, summary: "What was implemented.", changed_paths: ["project-relative/path"], evidence: [{ criterion_id: "AC-001", refs: ["project-relative/evidence", `run://${runId}/05-code/checks/receipt.json`] }], deviations: [], blockers: [], resolved_finding_refs: [] }, null, 2), "```"];
+    if (schema === "dd-flow/code-work-result@3") {
+        const packet = codePacket(work);
+        const obligations = [...new Set([
+                ...(packet?.acceptance ?? []).map((item) => item.criterion_id).filter((id) => Boolean(id)),
+                ...(packet?.checks ?? []).map((item) => item.id),
+                ...(packet?.repair?.review_findings ?? []).flatMap((finding) => finding.obligation_refs ?? [])
+            ])];
+        const findings = packet?.repair?.review_findings ?? [];
+        return [refs, `Assigned obligation refs: ${JSON.stringify(obligations)}. Cite only these in evidence.obligation_ref.`,
+            "This is a shape template, not a completed result. Populate changed_paths and evidence from the actual work and existing files; empty arrays below do not establish completion.",
+            "For a gate repair, cite the assigned check id. For a review repair, replace each resolution summary and fill evidence_refs with existing evidence proving its required outcome. Ordinary Work has resolutions: [].",
+            "```json", JSON.stringify({ schema_id: schema, summary: "Describe the actual implementation.", changed_paths: [], evidence: [], deviations: [], blockers: [], resolutions: findings.map((finding) => ({ finding_ref: finding.finding_ref, summary: "Describe how the assigned required outcome was achieved.", evidence_refs: [] })) }, null, 2), "```",
+            "Each evidence entry has exactly obligation_ref (one assigned ref) and refs (nonempty list of existing evidence paths). Each resolution has finding_ref, summary and nonempty evidence_refs. Do not invent file names or finding ids."];
+    }
     if (schema === "dd-flow/code-review-result@1") {
-        return [refs, "Assess every assigned aspect exactly once. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id to form the canonical reference.", "Use this complete minimal shape. Report only material, direct-evidence findings; taste and cosmetics are not findings:", "```json", JSON.stringify({ schema_id: schema, verdict: "pass | findings | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | findings | blocked", summary: "Conclusion.", evidence_refs: ["path/to/file", `run://${runId}/05-code/checks/receipt.json`] }], findings: [{ finding_id: "FIND-001", aspect_id: "assigned_aspect_id", priority: "p0 | p1 | p2 | p3", problem: "Violated obligation or rule.", impact: "Concrete risk or failure.", evidence_refs: ["path/to/file"], obligation_refs: ["R-001 | AC-001 | policy ref"] }] }, null, 2), "```"];
+        const aspect = { aspect_id: "assigned_aspect_id", verdict: "pass", summary: "Conclusion.", evidence_refs: ["path/to/evidence"] };
+        const clean = { schema_id: schema, verdict: "pass", summary: "Concise evidence-backed conclusion.", aspects: [aspect], findings: [] };
+        const mixed = { ...clean, verdict: "findings", aspects: [aspect, { ...aspect, aspect_id: "another_assigned_aspect_id", verdict: "findings" }], findings: [{ finding_id: "FIND-001", aspect_id: "another_assigned_aspect_id", priority: "p1", problem: "Describe the evidenced defect.", impact: "Describe its material impact.", required_outcome: "Describe the required correction.", evidence_refs: ["path/to/evidence"], obligation_refs: ["assigned_obligation_ref"] }] };
+        return [refs, "Assess every assigned aspect exactly once. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id to form the canonical reference.", "Examples below show no findings and mixed aspect outcomes, not completed results. Replace placeholder ids and paths with assigned aspects, obligations and existing evidence. Choose verdict pass, findings or blocked. Keep findings: [] when none exist. Report only material, direct-evidence defects, not taste or cosmetics.", "```json", JSON.stringify(clean, null, 2), "```", "```json", JSON.stringify(mixed, null, 2), "```"];
     }
     if (schema !== "dd-flow/plan-review-result@1")
         return [];
-    return [refs, "Use this complete minimal shape; do not add fields. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id when the coordinator classifies them:", "```json", JSON.stringify({ schema_id: schema, plan_revision: 1, overall_verdict: "pass | watch | needs_changes | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | watch | needs_changes | blocked", summary: "Conclusion for this aspect.", evidence_refs: ["path/to/file", `run://${runId}/03-plan/plan.json`], findings: [{ finding_id: "FIND-001", severity: "high | medium | low | info", summary: "Problem, if any.", evidence_refs: ["path/to/file"] }] }] }, null, 2), "```"];
+    const aspect = { aspect_id: "assigned_aspect_id", verdict: "pass", summary: "Conclusion for this aspect.", evidence_refs: ["path/to/evidence"], findings: [] };
+    const clean = { schema_id: schema, plan_revision: 1, overall_verdict: "pass", summary: "Concise evidence-backed conclusion.", aspects: [aspect] };
+    const mixed = { ...clean, overall_verdict: "needs_changes", aspects: [aspect, { ...aspect, aspect_id: "another_assigned_aspect_id", verdict: "needs_changes", findings: [{ finding_id: "FIND-001", severity: "high", summary: "Describe the evidenced defect.", evidence_refs: ["path/to/evidence"] }] }] };
+    return [refs, "Examples below show no findings and mixed aspect outcomes, not completed results. Assess each assigned aspect once, replace placeholder ids, plan_revision and paths with packet values and existing evidence. Choose verdict pass, watch, needs_changes or blocked. Keep findings: [] when an aspect has no findings. Do not add fields. Number findings locally as FIND-001, FIND-002, ...; dd-flow adds the Work id when the coordinator classifies them.", "```json", JSON.stringify(clean, null, 2), "```", "```json", JSON.stringify(mixed, null, 2), "```"];
 }
 export function validateCodeReviewResultIdentity(work, value) {
     const group = codeReviewGroup(work);
@@ -516,6 +1058,7 @@ export function validateCodeReviewResultIdentity(work, value) {
 function validateCodeReviewResult(work, value, input) {
     validateCodeReviewResultIdentity(work, value);
     const result = value;
+    assertReviewAspectEvidence(work, result.aspects ?? [], "CODE");
     const findings = result.findings ?? [];
     // A reviewer is a child Work and cannot pause its coordinator-owned Stage.
     // Its structured blocked result is evidence for the coordinator, which then
@@ -545,6 +1088,7 @@ export function validatePlanReviewResult(work, value, input) {
     const unexpected = ids.filter((id) => !expected.has(id));
     if (new Set(ids).size !== ids.length || missing.length || unexpected.length)
         throw new AppError("review_evidence_invalid", "PLAN reviewer result must assess every assigned aspect exactly once", 2, { work_id: work.work_id, group: group.key, missing, unexpected });
+    assertReviewAspectEvidence(work, aspects, "PLAN");
     const findingIds = aspects.flatMap((aspect) => aspect.findings ?? []).map((finding) => finding.finding_id ?? "");
     const invalid = findingIds.filter((id) => !/^FIND-\d{3}$/.test(id));
     if (new Set(findingIds).size !== findingIds.length || invalid.length)
@@ -559,6 +1103,11 @@ export function validatePlanReviewResult(work, value, input) {
         assertPortableArtifactRef(ref, input);
     }
 }
+function assertReviewAspectEvidence(work, aspects, stage) {
+    const missing = aspects.filter((aspect) => !Array.isArray(aspect.evidence_refs) || aspect.evidence_refs.length === 0).map((aspect) => aspect.aspect_id ?? "");
+    if (missing.length)
+        throw new AppError("review_evidence_invalid", `${stage} reviewer result requires non-empty evidence_refs for every assigned aspect`, 2, { work_id: work.work_id, missing_aspects: missing });
+}
 function codeReviewGroup(work) {
     const payload = parsePayload(work);
     const group = payload?.group;
@@ -569,10 +1118,14 @@ function codeReviewGroup(work) {
         ? { key: value.key, aspect_ids: value.aspect_ids }
         : null;
 }
-function requireWork(context, id) { ensureWorkRegistry(context); const exact = context.db.get(`SELECT ${workColumns} FROM works WHERE work_id = ?`, [id]); if (exact)
-    return exact; if (!/^WRK-\d{3,}$/.test(id))
-    throw new AppError("not_found", "Work is not registered", 1, { work_id: id }); const matches = context.db.all(`SELECT ${workColumns} FROM works WHERE work_id LIKE ? ORDER BY work_id`, [`${id}-%`]); if (matches.length !== 1)
-    throw new AppError(matches.length ? "ambiguous_work_alias" : "not_found", matches.length ? "Short Work alias is ambiguous" : "Work is not registered", 1, { work_id: id, matches: matches.map((work) => work.work_id) }); return matches[0]; }
+function requireWork(context, id, explicitScope) {
+    ensureWorkRegistry(context);
+    const configured = context.env.DD_FLOW_INVOCATION_SCOPE;
+    const scope = configured ? JSON.parse(configured) : undefined;
+    const projectId = explicitScope?.projectId ?? (scope?.projectRoot ? context.db.get("SELECT id FROM projects WHERE root = ?", [scope.projectRoot])?.id : undefined);
+    const runId = explicitScope?.runId ?? scope?.runId;
+    return resolveWorkReference(context, id, { projectId, runId });
+}
 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 requireRunHome(run) { if (!run.run_root)
@@ -613,19 +1166,13 @@ function validateItem(value, requireExecutionContext = false) { if (!value || ty
     throw new AppError("validation", "launch_policy must be reuse_allowed or fresh_agent_required", 2); if (item.result_schema !== undefined && (typeof item.result_schema !== "string" || !item.result_schema))
     throw new AppError("validation", "result_schema must be a non-empty schema id", 2); const payload = code ? item : (item.payload && typeof item.payload === "object" && !Array.isArray(item.payload) ? item.payload : undefined); return { key: item.key, task: item.task, ...(Array.isArray(item.depends_on) ? { depends_on: item.depends_on } : {}), ...(typeof item.parent === "string" ? { parent: item.parent } : {}), ...(typeof item.launch_policy === "string" ? { launch_policy: item.launch_policy } : {}), ...(typeof item.result_schema === "string" ? { result_schema: item.result_schema } : {}), ...(payload ? { payload } : {}) }; }
 function allowsEmptyRepairChecks(item) { const repair = item.repair; if (!repair || typeof repair !== "object" || Array.isArray(repair))
-    return false; const value = repair; return typeof value.check_receipt_id === "string" || (Array.isArray(value.review_check_refs) && value.review_check_refs.some((ref) => typeof ref === "string")) || (Array.isArray(value.semantic_unresolved) && value.semantic_unresolved.some((item) => typeof item === "string")); }
-function readJson(file) { try {
-    return JSON.parse(fs.readFileSync(path.resolve(file), "utf8"));
-}
-catch (error) {
-    throw new AppError("validation", `Invalid JSON file: ${String(error)}`, 2, { file });
-} }
+    return false; const value = repair; return typeof value.check_receipt_id === "string" || (Array.isArray(value.review_findings) && value.review_findings.some((finding) => typeof finding === "object" && finding !== null && Array.isArray(finding.check_refs) && finding.check_refs.some((ref) => typeof ref === "string"))) || (Array.isArray(value.semantic_unresolved) && value.semantic_unresolved.some((item) => typeof item === "string")); }
 export function refreshRunWorkProjection(context, projectId, runId) { refreshRunSessionProjection(context, projectId, runId); const run = context.db.get("SELECT run_root FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]); if (run?.run_root) {
     const obsolete = path.join(run.run_root, "work.json");
     if (fs.existsSync(obsolete))
         fs.rmSync(obsolete);
 } }
-export function codeWorkGraph(context, projectId, runId) { const works = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id`, [projectId, runId]).filter((work) => Boolean(codePacket(work))); const ready = works.filter((work) => isReady(context, work)); return { total: works.length, created: works.filter((work) => work.status === "created").length, running: works.filter((work) => work.status === "running").length, completed: works.filter((work) => work.status === "completed").length, failed: works.filter((work) => work.status === "failed").length, ready: ready.map((work) => ({ work_id: work.work_id, task: work.task, start_command: workStartCommand(context, work) })), blocked: works.filter((work) => work.status === "created" && !ready.includes(work)).map((work) => ({ work_id: work.work_id, depends_on: parseDependencies(work) })) }; }
+export function codeWorkGraph(context, projectId, runId) { const index = JSON.parse(context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId])?.index_json ?? "{}"); const active = index.stage_runs?.some(item => item.stage === "code-review" && item.status === "running") ? "code-review" : "code"; const members = index.stage_runs?.length ? stageWorkIds(context, projectId, runId, active) : null; const works = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id`, [projectId, runId]).filter((work) => Boolean(codePacket(work)) && (!members || members.has(work.work_id))); const ready = works.filter((work) => isReady(context, work)); return { total: works.length, created: works.filter((work) => work.status === "created").length, running: works.filter((work) => work.status === "running").length, completed: works.filter((work) => work.status === "completed").length, failed: works.filter((work) => work.status === "failed").length, ready: ready.map((work) => ({ work_id: work.work_id, task: work.task, launch_policy: work.launch_policy, start_command: workStartCommand(context, work) })), blocked: works.filter((work) => work.status === "created" && !ready.includes(work)).map((work) => ({ work_id: work.work_id, depends_on: parseDependencies(work) })) }; }
 function parsePayload(work) { if (!work.payload_json)
     return null; try {
     const value = JSON.parse(work.payload_json);
@@ -634,6 +1181,7 @@ function parsePayload(work) { if (!work.payload_json)
 catch {
     return null;
 } }
+function uniqueChecks(checks) { return checks.filter((check, index) => checks.findIndex((candidate) => candidate.id === check.id) === index); }
 function codePacket(work) { const value = parsePayload(work); if (value?.schema_id !== "dd-flow/code-work-packet@5")
     return null; return value; }
 function assertNoCycles(nodes) { const local = new Map(nodes.map((node) => [node.id, node.dependencies.filter((dependency) => nodes.some((candidate) => candidate.id === dependency))])); const active = new Set(); const done = new Set(); const visit = (id) => { if (active.has(id))