@deksden-com/dd-flow-cli 0.6.0 → 0.8.0-beta.135

package/dist/services/vnext-workspace-policy.js

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { gitFacts } from "./runs.js";
+const configRelativePath = path.join(".memory-bank", "dd-flow", "project-workspace.json");
+/** The runtime reads explicit configuration; it never attempts to infer route from policy prose. */
+export function loadVnextWorkspacePolicy(projectRoot) {
+    const file = path.join(projectRoot, configRelativePath);
+    if (!fs.existsSync(file)) {
+        throw new AppError("workspace_policy_missing", "vNext flow requires .memory-bank/dd-flow/project-workspace.json", 1, { file });
+    }
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new AppError("workspace_policy_invalid", "Project workspace policy is not valid JSON", 1, { file, cause: String(error) });
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AppError("workspace_policy_invalid", "Project workspace policy must be an object", 1, { file });
+    }
+    const raw = value;
+    const workspace = raw.workspace;
+    const route = workspace?.route;
+    const integrationBranch = workspace?.integration_branch;
+    const template = workspace?.feature_branch_template;
+    const provisionStage = workspace?.provision_stage;
+    if (raw.schema_id !== "dd-flow/project-workspace@1" || !workspace || (route !== "feature_worktree" && route !== "integration_branch_direct") || typeof integrationBranch !== "string" || !integrationBranch || provisionStage !== "protocolize_start") {
+        throw new AppError("workspace_policy_invalid", "Project workspace policy does not match dd-flow/project-workspace@1", 1, { file });
+    }
+    if (route === "feature_worktree" && (typeof template !== "string" || !template.includes("<RUN>"))) {
+        throw new AppError("workspace_policy_invalid", "feature_worktree policy needs a branch template containing <RUN>", 1, { file });
+    }
+    return {
+        schema_id: "dd-flow/project-workspace@1",
+        workspace: {
+            route,
+            integration_branch: integrationBranch,
+            feature_branch_template: typeof template === "string" ? template : null,
+            provision_stage: "protocolize_start"
+        }
+    };
+}
+export function vnextRunBranch(policy, run) {
+    if (policy.workspace.route !== "feature_worktree")
+        return null;
+    return policy.workspace.feature_branch_template
+        .replaceAll("<RUN>", run.short_id.toLowerCase())
+        .replaceAll("<slug>", safeSlug(run.slug));
+}
+/**
+ * The route receipt is the single source of truth after PROTOCOLIZE provisions
+ * the workspace. Every later mutating vNext stage calls this before it opens.
+ */
+export function requireVnextWorkspaceRoute(input) {
+    const file = path.join(input.runHome, "02-protocolize", "workspace-route.json");
+    let receipt;
+    try {
+        receipt = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new AppError("workspace_route_missing", `${input.stage} requires the PROTOCOLIZE workspace route receipt`, 1, { file, run_id: input.runId, cause: String(error) });
+    }
+    const policy = receipt.policy;
+    if (receipt.schema_id !== "dd-flow/vnext-workspace-route@1" || !policy?.provisioned || (policy.route !== "feature_worktree" && policy.route !== "integration_branch_direct")) {
+        throw new AppError("workspace_route_missing", `${input.stage} requires a valid provisioned workspace route`, 1, { file, run_id: input.runId });
+    }
+    const workspaceRoot = realPath(input.workspaceRoot);
+    if (policy.worktree_path && realPath(policy.worktree_path) !== workspaceRoot) {
+        throw new AppError("workspace_route_invalid", `${input.stage} RUN workspace differs from its frozen route`, 1, { run_id: input.runId, expected_workspace_root: policy.worktree_path, actual_workspace_root: workspaceRoot });
+    }
+    if (policy.route === "feature_worktree") {
+        if (!receipt.created || !receipt.bootstrap || !policy.worktree_path || !policy.feature_branch || !policy.base_ref || workspaceRoot === realPath(input.projectRoot)) {
+            throw new AppError("workspace_route_missing", `${input.stage} requires a provisioned feature worktree`, 1, { run_id: input.runId, workspace_root: workspaceRoot, policy });
+        }
+        const facts = gitFacts(workspaceRoot);
+        if (facts.status === "unavailable" || facts.branch !== policy.feature_branch || facts.head !== policy.base_ref) {
+            throw new AppError("workspace_route_invalid", `${input.stage} workspace no longer matches its frozen feature branch and base`, 1, { run_id: input.runId, workspace_root: workspaceRoot, expected: policy, actual: facts });
+        }
+    }
+    return policy;
+}
+function realPath(value) { return fs.existsSync(value) ? fs.realpathSync(value) : path.resolve(value); }
+function safeSlug(value) {
+    const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return slug || "work";
+}

package/dist/services/work-registry.js

@@ -0,0 +1,499 @@
+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 { validateSchema } from "./schema-validation.js";
+import { resolveProjectRoot, resolveRunReferences, writeJsonAtomic } from "../storage/paths.js";
+import { refreshRunSessionProjection } from "./run-projection.js";
+import { runCodeChecks } from "./code-checks.js";
+import { nextWorkId } from "./ids.js";
+import { appendFlowRunTimelineEvent } from "./runs.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"); }
+/** 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)
+        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));
+    if (keys.size !== items.length)
+        throw new AppError("validation", "work batch keys must be unique", 2);
+    for (const item of items)
+        for (const dependency of item.depends_on ?? [])
+            if (!keys.has(dependency))
+                throw new AppError("validation", "PLAN batch dependency must name a local key", 2, { key: item.key, dependency });
+    for (const item of items)
+        if (item.parent && !keys.has(item.parent))
+            throw new AppError("validation", "PLAN batch parent must name a local key", 2, { key: item.key, parent: item.parent });
+    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)
+        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);
+    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 });
+    const now = context.now();
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        const ids = new Map(items.map((item) => [item.key, nextWorkId(context, parent.project_id, item.key)]));
+        const resolve = (value) => ids.get(value) ?? value;
+        const proposed = items.map((item) => ({ ...item, id: ids.get(item.key), parentId: item.parent ? resolve(item.parent) : parent.work_id, dependencies: (item.depends_on ?? []).map(resolve) }));
+        assertNoCycles(proposed.map((item) => ({ id: item.id, dependencies: item.dependencies })));
+        assertNoParentCycles(proposed.map((item) => ({ id: item.id, parent: item.parentId })));
+        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)
+            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);
+    if (!input.runId && !input.parentWorkId)
+        throw new AppError("usage", "work ls requires --run or --parent", 2);
+    const where = ["task IS NOT NULL"];
+    const params = [];
+    if (input.runId) {
+        where.push("run_id = ?");
+        params.push(input.runId);
+    }
+    if (input.parentWorkId) {
+        where.push("parent_work_id = ?");
+        params.push(input.parentWorkId);
+    }
+    if (input.status) {
+        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 filtered = input.ready ? rows.filter(ready) : rows;
+    return { works: filtered.slice(0, input.limit ?? filtered.length).map((work) => {
+            const isReadyNow = ready(work);
+            return { ...work, payload: parsePayload(work), payload_json: undefined, depends_on: parseDependencies(work), ready: isReadyNow, ...(isReadyNow ? { start_command: workStartCommand(context, work) } : {}), ...(input.includeResults ? {} : { result: undefined }) };
+        }) };
+}
+export function showWork(context, id) { const work = requireWork(context, id); const sessions = context.db.all("SELECT id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, completed_at FROM work_sessions WHERE work_id = ? ORDER BY created_at", [work.work_id]); return { work: { ...work, short_id: shortWorkId(work.work_id), payload: parsePayload(work), payload_json: undefined, depends_on: parseDependencies(work), sessions } }; }
+export function mutateWorkDeps(context, input) {
+    const work = requireWork(context, input.workId);
+    if (input.action === "list")
+        return { work_id: work.work_id, depends_on: parseDependencies(work) };
+    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]);
+    refreshRunWorkProjection(context, work.project_id, work.run_id);
+    return { work_id: work.work_id, depends_on: [...dependencies] };
+}
+export function deleteWork(context, id) { const work = requireWork(context, id); const canonical = work.work_id; if (work.status !== "created" || work.started_at || context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? LIMIT 1", [canonical]) || context.db.get("SELECT 1 FROM works WHERE depends_on_json LIKE ? LIMIT 1", [`%${canonical}%`]))
+    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 workStartCommand(context, work) { const run = requireRun(context, work.project_id, work.run_id); return `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow work start ${work.work_id} --project-root ${JSON.stringify(run.project_root)} --json`; }
+export function startWork(context, id, input) {
+    ensureWorkRegistry(context);
+    const work = requireWork(context, 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) }));
+        throw new AppError("work_not_ready", "Work cannot start until dependencies complete and overlapping write scopes are free", 2, { work_id: id, blockers, ready });
+    }
+    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 });
+    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);
+    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);
+    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)
+            throw new AppError("handoff_session_mismatch", "The active Work is already bound to a different Session", 1, { work_id: work.work_id });
+        context.db.run("UPDATE work_sessions SET prompt_path = ?, result_path = COALESCE(?, result_path), updated_at = ? WHERE id = ?", [input.promptPath, input.resultPath ?? null, context.now(), active.id]);
+        return { work_session_id: active.id, session_id: identity.sessionId, reused: true };
+    }
+    const now = context.now();
+    const id = `WS-${crypto.randomUUID()}`;
+    context.db.exec("BEGIN IMMEDIATE");
+    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]);
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    refreshRunWorkProjection(context, work.project_id, work.run_id);
+    return { work_session_id: id, session_id: identity.sessionId };
+}
+/** 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);
+    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 binding = bindRunningWorkSession(context, input);
+    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;
+}
+/** Starts a created coordinator Work from its trusted `stage start` event. */
+export function startStageCoordinatorWork(context, input) {
+    const work = requireWork(context, input.workId);
+    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 });
+    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]);
+    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()}`;
+    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");
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        bindSession(context, work, run, identity, now);
+        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]);
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    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, resultPath);
+    writeJsonAtomic(path.join(directory, "context.json"), { 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 });
+    fs.writeFileSync(promptPath, prompt);
+    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_id: identity.sessionId } };
+}
+export function finishWork(context, id, result, progress) { return settle(context, id, "completed", result, progress); }
+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) {
+    const work = requireWork(context, id);
+    id = work.work_id;
+    if (work.status !== "running" && !(status === "cancelled" && work.status === "created"))
+        throw new AppError("invalid_work_state", "Work is not running", 2, { status: work.status });
+    if (status === "completed" && context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created', 'running') 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 = [];
+    if (status === "completed") {
+        validateWorkResult(work, result, run.project_root, run.workspace_root, run.id, link?.result_path ?? null);
+        const packet = codePacket(work);
+        if (packet) {
+            validateChangedPaths(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 failed = receipts.filter((receipt) => receipt.status === "failed");
+            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");
+    try {
+        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)
+                context.db.run("UPDATE sessions SET status = 'idle', updated_at = ? WHERE project_id = ? AND session_id = ?", [now, work.project_id, link.session_id]);
+        }
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    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) }));
+    appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: `work_${status}`, work_id: work.work_id, session_id: link?.session_id ?? null });
+    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, newly_ready: newlyReady, graph: codeWorkGraph(context, work.project_id, work.run_id), usage: { status: "provisional", reason: "final usage is controller-owned" } };
+}
+function validateChangedPaths(packet, result) {
+    const changed = JSON.parse(result).changed_paths;
+    if (!Array.isArray(changed))
+        return;
+    const outside = changed.filter((item) => typeof item === "string" && !packet.write_scope.some((scope) => item === scope || item.startsWith(`${scope}/`)));
+    if (outside.length)
+        throw new AppError("write_scope_violation", "CODE Work result declares paths outside its accepted write scope", 2, { outside, write_scope: packet.write_scope });
+}
+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;
+    const inferredParentSession = work.parent_work_id
+        ? context.db.get("SELECT session_id FROM work_sessions WHERE work_id = ? ORDER BY created_at DESC LIMIT 1", [work.parent_work_id])?.session_id ?? null
+        : priorWorkSession && priorWorkSession !== identity.sessionId ? priorWorkSession : null;
+    const parentSession = identity.parentSessionId ?? inferredParentSession;
+    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 });
+    const existing = context.db.get("SELECT session_id, 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 });
+    context.db.run(`INSERT INTO sessions (session_id, project_id, harness, provider_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), 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, 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);
+}
+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]);
+}
+function validateWorkResult(work, result, projectRoot, workspaceRoot, runId, resultPath) {
+    if (!work.result_schema)
+        return;
+    if (!resultPath)
+        throw new AppError("runtime_missing", "Work result path is unavailable", 1, { work_id: work.work_id });
+    let parsed;
+    try {
+        parsed = JSON.parse(result);
+    }
+    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 });
+    }
+    fs.writeFileSync(resultPath, result);
+    validateSchema({ schemaName: work.result_schema.replace(/^dd-flow\//, "").replace(/@\d+$/, ""), file: resultPath, projectRoot, runId });
+    if (work.result_schema === "dd-flow/code-work-result@2")
+        validateCodeWorkResult(work, parsed, workspaceRoot);
+    if (work.result_schema === "dd-flow/code-review-result@1")
+        validateCodeReviewResultIdentity(work, parsed);
+}
+function validateCodeWorkResult(work, value, projectRoot) {
+    const result = value;
+    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 documentUpdates = (packet.document_updates ?? []);
+    const changed = new Set(result.changed_paths ?? []);
+    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 });
+    const unchangedDocuments = documentUpdates.filter((entry) => { const file = path.join(projectRoot, entry.path); if (!fs.existsSync(file) || !fs.statSync(file).isFile())
+        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 ?? [];
+    if (assigned.length) {
+        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 });
+    }
+}
+function renderWorkerPrompt(context, work, run, dependencies, resultPath) {
+    const command = `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow`;
+    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>", "", "<acceptance_context>", "The criteria below are end-to-end context. Complete only this Work's semantic_spine.acceptance_contribution, task, write_scope, and declared checks. A criterion may name another ordered Work's UI, documentation, or evidence surface; do not fail merely because that surface is outside this Work's write_scope.", JSON.stringify(packet.acceptance, null, 2), "</acceptance_context>", "", "<required_read>", ...packet.required_read.map((item) => `- ${resolveRunReferences(item, work.run_id, requireRunHome(run))}`), "</required_read>", "", "<discovery_boundary>", ...packet.discovery_boundary.map((item) => `- ${item}`), "</discovery_boundary>", "", "<write_scope>", ...packet.write_scope.map((item) => `- ${item}`), "</write_scope>", "", ...(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>", ""] : [];
+    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>", "", "<contract_failure>", "Successful completion requires empty deviations and blockers and every assigned document update in changed_paths. If a required path is missing from write_scope, do not report success: fail this Work with that exact path and the retained receipt so the coordinator can correct the packet.", "</contract_failure>", "");
+    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>", "", "<workspace_contract>", `All project reads and writes belong under ${run.workspace_root}. Project root is only the stable lifecycle identity for dd-flow commands. Do not create, switch, merge or delete branches/worktrees.`, "</workspace_contract>", "", ...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), `Write it to ${resultPath}.`, "</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 for a contractual scope conflict where a required repair path lies outside this Work's write_scope. Quote the exact receipt plus the error or missing path. A project check failure inside this Work's scope must be fixed before Finish.", "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: ${command} work finish ${work.work_id} --result-file ${JSON.stringify(resultPath)} --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`, `Fail only for an evidenced external or scope-contract case: ${command} work fail ${work.work_id} --reason "receipt path + exact error or missing write_scope path" --project-root ${JSON.stringify(run.project_root)} --json`, "</completion>", ""].join("\n");
+}
+function resultSchemaGuidance(work) {
+    const schema = work.result_schema;
+    if (schema === "dd-flow/code-work-result@2")
+        return ["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"] }], deviations: [], blockers: [], resolved_finding_refs: [] }, null, 2), "```"];
+    if (schema === "dd-flow/code-review-result@1") {
+        return ["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"] }], 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), "```"];
+    }
+    if (schema !== "dd-flow/plan-review-result@1")
+        return [];
+    return ["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"], findings: [{ finding_id: "FIND-001", severity: "high | medium | low | info", summary: "Problem, if any.", evidence_refs: ["path/to/file"] }] }] }, null, 2), "```"];
+}
+export function validateCodeReviewResultIdentity(work, value) {
+    const group = codeReviewGroup(work);
+    if (!group)
+        throw new AppError("review_evidence_invalid", "CODE reviewer Work has no assigned review group", 2, { work_id: work.work_id });
+    const result = value;
+    const aspectIds = (result.aspects ?? []).map((item) => item.aspect_id ?? "");
+    const expected = new Set(group.aspect_ids);
+    const missing = group.aspect_ids.filter((id) => !aspectIds.includes(id));
+    const unexpected = aspectIds.filter((id) => !expected.has(id));
+    if (new Set(aspectIds).size !== aspectIds.length || missing.length || unexpected.length) {
+        throw new AppError("review_evidence_invalid", "CODE reviewer result must assess every assigned aspect exactly once", 2, { work_id: work.work_id, group: group.key, missing, unexpected });
+    }
+    const findingIds = (result.findings ?? []).map((item) => item.finding_id ?? "");
+    const invalid = findingIds.filter((id) => !/^FIND-\d{3}$/.test(id));
+    const wrongAspect = (result.findings ?? []).filter((item) => !item.aspect_id || !expected.has(item.aspect_id)).map((item) => item.finding_id ?? "");
+    if (new Set(findingIds).size !== findingIds.length || invalid.length || wrongAspect.length) {
+        throw new AppError("review_evidence_invalid", "CODE reviewer finding ids must be local FIND-NNN ids and aspect refs must stay inside the assigned review group", 2, { work_id: work.work_id, group: group.key, required_format: "FIND-NNN", invalid, wrong_aspect: wrongAspect });
+    }
+}
+function codeReviewGroup(work) {
+    const payload = parsePayload(work);
+    const group = payload?.group;
+    if (!group || typeof group !== "object" || Array.isArray(group))
+        return null;
+    const value = group;
+    return typeof value.key === "string" && Array.isArray(value.aspect_ids) && value.aspect_ids.every((item) => typeof item === "string")
+        ? { 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 requireRun(context, projectId, runId) { const run = context.db.get("SELECT r.id, r.run_home_path, 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_home_path)
+    throw new AppError("runtime_missing", "RUN workspace is unavailable", 1, { run_id: runId }); return run; }
+function requireRunHome(run) { if (!run.run_home_path)
+    throw new AppError("runtime_missing", "RUN workspace is unavailable", 1, { run_id: run.id }); return run.run_home_path; }
+function parseDependencies(work) { try {
+    const value = JSON.parse(work.depends_on_json);
+    return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : [];
+}
+catch {
+    return [];
+} }
+function isReady(context, work) { return work.status === "created" && readinessBlockers(context, work).length === 0; }
+function readinessBlockers(context, work) {
+    const blockers = parseDependencies(work).flatMap((id) => { const dependency = context.db.get("SELECT status FROM works WHERE work_id = ?", [id]); return dependency?.status === "completed" ? [] : [{ kind: "dependency", work_id: id, status: dependency?.status ?? "missing" }]; });
+    const scope = workWriteScope(work);
+    if (scope.length === 0)
+        return blockers;
+    for (const running of context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? AND status = 'running' AND work_id != ?`, [work.project_id, work.run_id, work.work_id])) {
+        const overlap = overlappingScopes(scope, workWriteScope(running));
+        if (overlap.length)
+            blockers.push({ kind: "write_scope", work_id: running.work_id, paths: overlap });
+    }
+    return blockers;
+}
+function workWriteScope(work) { const payload = parsePayload(work); return Array.isArray(payload?.write_scope) ? payload.write_scope.filter((item) => typeof item === "string").map((item) => item.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "")) : []; }
+function overlappingScopes(left, right) { const overlap = new Set(); for (const a of left)
+    for (const b of right)
+        if (a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`))
+            overlap.add(a.length <= b.length ? a : b); return [...overlap]; }
+function validateItem(value, requireExecutionContext = false) { if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new AppError("validation", "work item must be an object", 2); const item = value; if (typeof item.key !== "string" || !item.key || typeof item.task !== "string" || !item.task.trim())
+    throw new AppError("validation", "work item requires key and task", 2); const code = item.schema_id === "dd-flow/code-work-packet@4"; if (requireExecutionContext && !code)
+    throw new AppError("validation", "CODE batch requires code-work-packet@4 items", 2, { key: item.key }); for (const key of code ? ["required_read", "discovery_boundary", "write_scope", "checks", "provides_checks", "stop_conditions"] : [])
+    if (!Array.isArray(item[key]) || (key !== "provides_checks" && item[key].length === 0))
+        throw new AppError("validation", `CODE work item requires ${key === "provides_checks" ? "an array" : `non-empty ${key}`}`, 2, { key: item.key }); if (item.depends_on !== undefined && (!Array.isArray(item.depends_on) || !item.depends_on.every((entry) => typeof entry === "string")))
+    throw new AppError("validation", "depends_on must be a string array", 2); if (item.parent !== undefined && typeof item.parent !== "string")
+    throw new AppError("validation", "parent must be a string", 2); if (item.launch_policy !== undefined && item.launch_policy !== "reuse_allowed" && item.launch_policy !== "fresh_agent_required")
+    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 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_home_path FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]); if (run?.run_home_path) {
+    const obsolete = path.join(run.run_home_path, "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) })) }; }
+function parsePayload(work) { if (!work.payload_json)
+    return null; try {
+    const value = JSON.parse(work.payload_json);
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+catch {
+    return null;
+} }
+function codePacket(work) { const value = parsePayload(work); if (value?.schema_id !== "dd-flow/code-work-packet@4")
+    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))
+    throw new AppError("validation", "Work dependencies contain a cycle", 2); if (done.has(id))
+    return; active.add(id); for (const dependency of local.get(id) ?? [])
+    visit(dependency); active.delete(id); done.add(id); }; for (const id of local.keys())
+    visit(id); }
+function assertNoParentCycles(nodes) { const parents = new Map(nodes.map((node) => [node.id, node.parent])); for (const node of nodes) {
+    const seen = new Set([node.id]);
+    let parent = node.parent;
+    while (parents.has(parent)) {
+        if (seen.has(parent))
+            throw new AppError("validation", "Work parents contain a cycle", 2);
+        seen.add(parent);
+        parent = parents.get(parent);
+    }
+} }