@deksden-com/dd-flow-cli 0.9.0-beta.74 → 0.9.0-beta.79

package/dist/services/work-registry.js

@@ -17,6 +17,7 @@ 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) {
@@ -105,8 +106,12 @@ export function createChildWork(context, input) {
 }
 /** 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));
@@ -122,29 +127,46 @@ 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 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)
+        for (const dependency of item.depends_on ?? [])
+            if (!keys.has(dependency) && !existingIds.has(dependency))
+                throw new AppError("validation", "work dependency is unknown", 2, { key: item.key, dependency });
+    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 });
+    return parent;
+}
+export function addWorkBatch(context, input) {
+    const items = input.prepared ?? prepareWorkBatch(context, input);
     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", "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)
-            for (const dependency of item.depends_on ?? [])
-                if (!keys.has(dependency) && !existingIds.has(dependency))
-                    throw new AppError("validation", "work dependency is unknown", 2, { key: item.key, dependency });
-        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 });
+        // 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]]));
@@ -295,36 +317,60 @@ export function materializePendingWorkResults(context, projectId, runId) {
 }
 export function mutateWorkDeps(context, input) {
     if (input.action === "list") {
-        const work = requireWork(context, input.workId);
-        return { work_id: work.work_id, depends_on: parseDependencies(work) };
+        const { work, dependencies } = prepareWorkDeps(context, input);
+        return { work_id: work.work_id, depends_on: dependencies };
     }
+    prepareWorkDeps(context, input);
     return context.db.writeTransaction(() => {
-        const work = requireWork(context, input.workId);
-        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));
-        if (input.action === "clear")
-            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 (input.action === "add")
-                dependencies.add(dependency.work_id);
-            else
-                dependencies.delete(dependency.work_id);
-        }
-        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]);
+        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] };
+        return { work_id: work.work_id, depends_on: dependencies };
     });
 }
-export function deleteWork(context, id) { return context.db.writeTransaction(() => { const work = requireWork(context, id); assertRunMutationAllowed(context, work.project_id, work.run_id); const canonical = work.work_id; if (work.status !== "created" || work.started_at || context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? LIMIT 1", [canonical]) || context.db.get("SELECT 1 FROM works WHERE depends_on_json LIKE ? LIMIT 1", [`%${canonical}%`]))
-    throw new AppError("invalid_work_state", "Only an unstarted unreferenced Work may be deleted", 2); context.db.run("DELETE FROM works WHERE work_id = ?", [canonical]); refreshRunWorkProjection(context, work.project_id, work.run_id); return { ok: true, deleted: canonical }; }); }
+export function 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);
+    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));
+    if (input.action === "clear")
+        dependencies.clear();
+    for (const id of input.on ?? []) {
+        const dependency = requireWork(context, id);
+        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
+            dependencies.delete(dependency.work_id);
+    }
+    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) })));
+    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) {
+    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 /^WRK-\d{3,}(?:-|$)/.exec(id)?.[0]?.replace(/-$/, "") ?? id; }
 /**
  * Return the engine-bound command, never a PATH-dependent `dd-flow` token.
@@ -588,27 +634,76 @@ export function finishFanInWork(context, id, result) { const work = requireWork(
     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) {
+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);
+    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", [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", [work.work_id]);
+    if (work.status === "running" && !link)
+        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 {
-        assertRunMutationAllowed(context, work.project_id, work.run_id);
-        const current = requireWork(context, work.work_id);
-        const pending = fs.existsSync(journal) ? JSON.parse(fs.readFileSync(journal, "utf8")) : null;
-        if (pending && (pending.work_id !== work.work_id || !/^ATT-\d{3,}$/.test(pending.archive) || pending.entries.some(file => !["prompt.md", "result.json", "context.json"].includes(file))))
-            throw new AppError("work_retry_invalid", "Retry journal does not identify this Work", 1);
-        if (current.status !== "failed" && !(pending && current.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: current.result === null ? null : crypto.createHash("sha256").update(current.result).digest("hex") };
-        archive = path.join(attempts, prepared.archive);
+        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);
@@ -678,17 +773,8 @@ function sharedReviewInput(work, run, initialize = false) {
     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 = requireWork(context, id);
-    assertWorkSettlementAllowed(context, work.project_id, work.run_id, work.work_id);
+    const { work, run, link } = prepareWorkSettlement(context, id, status, result);
     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 });
-    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]);
-    if (work.status === "running" && !link)
-        throw new AppError("runtime_missing", "Running Work has no open Work/Session link", 1, { work_id: id });
     let receipts = [];
     let coordinationDrift = [];
     const assertReadOnlyInput = () => {
@@ -776,16 +862,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);
 }
@@ -799,6 +897,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;
@@ -811,14 +918,7 @@ 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 });
-    }
+    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")
@@ -887,13 +987,13 @@ function renderWorkerPrompt(context, work, run, dependencies) {
         : [`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. If the command has no invocation-id, repeat the original Finish. Do not invent a cause that does not appear in the retained output."];
+        : ["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>", "");
     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>", "", "<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), "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>", 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.", `Finish as one standalone command with a quoted heredoc (replace the example JSON with your result):\n${finishWorkCommand} <<'DD_FLOW_RESULT'\n{}\nDD_FLOW_RESULT`, `Fail only for an evidenced external or semantic-contract blocker: ${failWorkCommand}`, "</completion>", ""].join("\n");
+    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. 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), "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>", 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.", `Finish as one standalone command with a quoted heredoc (replace the example JSON with your result):\n${finishWorkCommand} <<'DD_FLOW_RESULT'\n{}\nDD_FLOW_RESULT`, `Fail only for an evidenced external or semantic-contract blocker: ${failWorkCommand}`, "</completion>", ""].join("\n");
 }
 export function resultSchemaGuidance(work, runId) {
     const schema = work.result_schema;
@@ -913,11 +1013,17 @@ export function resultSchemaGuidance(work, runId) {
             "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.", "This is a shape template: replace labels with assigned ids and observed verdicts, fill evidence_refs using existing files from the task packet, and remove findings when none exist. 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/evidence"] }], 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.", required_outcome: "Smallest observable result that closes the defect.", 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, "This is a shape template: replace labels with assigned ids and observed verdicts, fill evidence_refs using existing files from the task packet, and remove findings when none exist. 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/evidence"], 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);
@@ -1006,10 +1112,23 @@ 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) {
+    ensureWorkRegistry(context);
+    const configured = context.env.DD_FLOW_INVOCATION_SCOPE;
+    const scope = configured ? JSON.parse(configured) : undefined;
+    const projectId = scope?.projectRoot ? context.db.get("SELECT id FROM projects WHERE root = ?", [scope.projectRoot])?.id : undefined;
+    const scoped = projectId && scope?.runId ? " AND project_id = ? AND run_id = ?" : "";
+    const params = projectId && scope?.runId ? [projectId, scope.runId] : [];
+    const exact = context.db.get(`SELECT ${workColumns} FROM works WHERE work_id = ?${scoped}`, [id, ...params]);
+    if (exact)
+        return exact;
+    if (!/^WRK-\d{3,}$/.test(id))
+        throw new AppError("not_found", "Work is not registered in the current RUN", 1, { work_id: id });
+    const matches = context.db.all(`SELECT ${workColumns} FROM works WHERE work_id LIKE ?${scoped} ORDER BY work_id`, [`${id}-%`, ...params]);
+    if (matches.length !== 1)
+        throw new AppError(matches.length ? "ambiguous_work_alias" : "not_found", matches.length ? "Short Work alias is ambiguous in the current RUN" : "Work is not registered in the current RUN", 1, { work_id: id, matches: matches.map((work) => work.work_id) });
+    return matches[0];
+}
 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)
@@ -1051,12 +1170,6 @@ function validateItem(value, requireExecutionContext = false) { if (!value || ty
     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_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")); }
-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 });
-} }
 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))