@deksden-com/dd-flow-cli 0.9.0-beta.13 → 0.9.0-beta.14

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.14
+
+### Patch Changes
+
+- Audit runtime recovery: distinguish process owners from children, retain live check resources, await failed check startup cleanup, share managed workspace bootstrap between CODE/MERGE, correct assigned repair examples, and reject publication without canonical build provenance.
+
 ## 0.9.0-beta.13
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,15 +1,15 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.13",
-  "cli_commit": "020ada108a59291f4462f7d52d3ea64bccd77b56",
-  "built_at": "2026-09-05T08:17:23.882Z",
+  "cli_version": "0.9.0-beta.14",
+  "cli_commit": "29b30887789f9ee686d5903a4ddcea40a24dc8ce",
+  "built_at": "2026-09-05T08:57:36.734Z",
   "built_with_canon": {
-    "version": null,
-    "commit": null,
-    "flow_contract": null,
-    "repo_root": null,
-    "memorybank_root": null,
-    "flow_root": null,
-    "layout": null
+    "version": "4.0.4",
+    "commit": "c8cae271f844fd3b3c7492f164e13a60eaba4839",
+    "flow_contract": "dd-flow-canonical-2026-08",
+    "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
+    "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",
+    "flow_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank/dd-flow",
+    "layout": "dot_memory_bank"
   }
 }

package/dist/cli/run-cli.js

@@ -1591,6 +1591,7 @@ async function dispatchRuntime(context, command, parsed) {
         const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true);
         const process = registerManagedProcess(context, {
             kind: requiredOption(parsed, "kind"), ownerId: requiredOption(parsed, "owner"),
+            ownerPid: optionalPositiveNumber(parsed, "owner-pid", true),
             projectId: optionalOption(parsed, "project-id") ?? null, runId: optionalOption(parsed, "run") ?? null,
             workId: optionalOption(parsed, "work") ?? null, checkId: optionalOption(parsed, "check") ?? null,
             operationId: optionalOption(parsed, "operation") ?? null, stdoutPath: optionalOption(parsed, "stdout") ?? null,
@@ -1601,7 +1602,7 @@ async function dispatchRuntime(context, command, parsed) {
     if (action === "confirm") {
         const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true);
         const processGroupId = optionalPositiveNumber(parsed, "process-group-id", true);
-        return { ok: true, process: confirmManagedProcess(context, { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), pid: optionalPositiveNumber(parsed, "pid", true) ?? 0, ...(processGroupId ? { processGroupId } : {}), ...(leaseMs ? { leaseMs } : {}) }) };
+        return { ok: true, process: confirmManagedProcess(context, { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ownerPid: optionalPositiveNumber(parsed, "owner-pid", true), pid: optionalPositiveNumber(parsed, "pid", true) ?? 0, ...(processGroupId ? { processGroupId } : {}), ...(leaseMs ? { leaseMs } : {}) }) };
     }
     if (action === "heartbeat") {
         const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true);

package/dist/services/code-checks.js

@@ -3,7 +3,7 @@ import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, processIsAlive, registerManagedProcess, reservePorts } from "./managed-processes.js";
+import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, managedOwnerIsAlive, processTreeIsAlive, registerManagedProcess, reservePorts } from "./managed-processes.js";
 const profileRelativePath = path.join(".memory-bank", "spec", "engineering", "code-check-profile.json");
 // Receipt reservation precedes child spawn so an interrupted CLI leaves an
 // auditable attempt. A second caller must not mistake that small handoff window
@@ -99,7 +99,7 @@ export async function runCodeChecks(context, input) {
         try {
             fs.mkdirSync(evidenceDir, { recursive: true });
             writeReceipt(receiptPath, receiptFor({ ...reserved, resources, result, status: "running", after: before, mutationPaths: [], artifacts: [] }));
-            const managed = registerManagedProcess(context, { kind: "check", ownerId: `check:${id}`, projectId: input.projectId, runId: input.runId, workId: input.workId ?? null, checkId: id, stdoutPath, stderrPath, metadata: { command: group.command } });
+            const managed = registerManagedProcess(context, { kind: "check", ownerPid: process.pid, ownerId: `check:${id}`, projectId: input.projectId, runId: input.runId, workId: input.workId ?? null, checkId: id, stdoutPath, stderrPath, metadata: { command: group.command } });
             const allocation = await reservePorts(context, { ownerId: managed.owner_id, processId: managed.id, names: group.ports });
             resources = allocation.ports;
             input.progress?.(`check ${index + 1}/${groups.length} started: ${group.command}`);
@@ -109,13 +109,18 @@ export async function runCodeChecks(context, input) {
                 result = await runCheck(group.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_EVIDENCE_DIR: evidenceDir, DD_FLOW_CHECK_COMPLETION_FILE: completionPath, ...portEnvironment(resources) }, stdout, stderr, (elapsed) => input.progress?.(`check ${index + 1}/${groups.length} still running (${elapsed}s): ${group.command}`), (pid) => confirmManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid }), () => heartbeatManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token }));
             }
             finally {
-                allocation.release();
                 fs.closeSync(stdout);
                 fs.closeSync(stderr);
-                finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: result.aborted || result.exitCode !== 0 || Boolean(result.error) ? "failed" : "stopped", reason: result.error });
             }
+            const current = managedProcessStatus(context).find(item => item.id === managed.id);
+            if (processTreeIsAlive(current))
+                throw new AppError("check_in_progress", "The check shell exited but its process tree is still live; retain this receipt and its resources until settlement", 2, { process_id: managed.id, check_receipt_id: id });
+            allocation.release();
+            finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: result.aborted || result.exitCode !== 0 || Boolean(result.error) ? "failed" : "stopped", reason: result.error });
         }
         catch (error) {
+            if (error instanceof AppError && error.code === "check_in_progress")
+                throw error;
             result = { exitCode: null, error: error instanceof Error ? error.message : String(error), aborted: true };
         }
         const after = workspaceState(input.workspaceRoot, [input.runHome]);
@@ -158,7 +163,7 @@ export function reconcileUnfinishedChecks(context, input) {
         // A stale lease after host sleep is not permission to duplicate a living
         // check.  Its durable completion marker or explicit reconciliation decides
         // the outcome before another invocation may start.
-        if (process && ["starting", "running", "stopping"].includes(process.state) && (process.state === "starting" || processIsAlive(process))) {
+        if (process && ["starting", "running", "stopping"].includes(process.state) && (processTreeIsAlive(process) || (process.state === "starting" && (managedOwnerIsAlive(process) !== false || Date.parse(process.lease_expires_at) > Date.parse(context.now()))))) {
             throw new AppError("check_in_progress", "A previous check invocation is still running", 1, { check_receipt_id: pendingReceipt.id, process_id: process.id, pid: process.pid });
         }
         if (!process && !completion && Date.now() - Date.parse(pendingReceipt.started_at) < receiptStartingGraceMs) {
@@ -269,24 +274,65 @@ function collectRequiredArtifacts(root, required) { const missing = []; const it
 } return { complete: missing.length === 0, missing, items }; }
 function listFiles(root, current = root) { return fs.readdirSync(current, { withFileTypes: true }).flatMap((entry) => { if ([".git", "node_modules"].includes(entry.name))
     return []; const absolute = path.join(current, entry.name); return entry.isDirectory() ? listFiles(root, absolute) : [path.relative(root, absolute)]; }).sort(); }
-function runCheck(command, cwd, environment, stdout, stderr, heartbeat, onSpawn, renewLease) { return new Promise((resolve) => { const started = Date.now(); const child = spawn("/bin/sh", ["-lc", checkShellScript()], { cwd, env: { ...environment, DD_FLOW_CHECK_COMMAND: command }, stdio: ["ignore", stdout, stderr], detached: process.platform !== "win32" }); if (!child.pid) {
-    resolve({ exitCode: null, error: "check process did not provide a PID", aborted: true });
-    return;
-} try {
-    onSpawn(child.pid);
+export function runCheck(command, cwd, environment, stdout, stderr, heartbeat, onSpawn, renewLease) {
+    return new Promise((resolve) => {
+        const started = Date.now();
+        const child = spawn("/bin/sh", ["-lc", checkShellScript()], { cwd, env: { ...environment, DD_FLOW_CHECK_COMMAND: command }, stdio: ["ignore", stdout, stderr], detached: process.platform !== "win32" });
+        let error = null;
+        let stopping = false;
+        let progress;
+        let escalation;
+        const stop = (cause) => {
+            if (stopping)
+                return;
+            stopping = true;
+            error = cause instanceof Error ? cause.message : String(cause);
+            if (progress) {
+                clearInterval(progress);
+                progress = undefined;
+            }
+            if (child.pid) {
+                terminateProcessGroup(child.pid, "SIGTERM");
+                escalation = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 5_000);
+            }
+        };
+        // Register handlers before checking pid or calling persistence callbacks.
+        // Failure is not completion until the spawned process has actually closed.
+        child.once("error", (value) => { error = value.message; });
+        child.once("close", (exitCode, signal) => {
+            if (progress)
+                clearInterval(progress);
+            if (escalation)
+                clearTimeout(escalation);
+            if (stopping)
+                terminateProcessGroup(child.pid, "SIGKILL");
+            resolve({ exitCode, error: error ?? (signal ? `terminated by ${signal}` : null), aborted: stopping || Boolean(signal) || Boolean(error) });
+        });
+        if (!child.pid) {
+            error = "check process did not provide a PID";
+            return;
+        }
+        try {
+            onSpawn(child.pid);
+        }
+        catch (cause) {
+            stop(cause);
+            return;
+        }
+        progress = setInterval(() => {
+            try {
+                if (!renewLease()) {
+                    stop("managed process lease lost");
+                    return;
+                }
+                heartbeat(Math.floor((Date.now() - started) / 1000));
+            }
+            catch (cause) {
+                stop(cause);
+            }
+        }, 15_000);
+    });
 }
-catch (error) {
-    terminateProcessGroup(child.pid, "SIGTERM");
-    resolve({ exitCode: null, error: error instanceof Error ? error.message : String(error), aborted: true });
-    return;
-} let leaseLost = false; let error = null; let escalation; const progress = setInterval(() => { const elapsed = Math.floor((Date.now() - started) / 1000); if (!renewLease()) {
-    error = "managed process lease lost";
-    leaseLost = true;
-    terminateProcessGroup(child.pid, "SIGTERM");
-    escalation = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 5_000);
-    return;
-} heartbeat(elapsed); }, 15_000); child.once("error", (value) => { error = value.message; }); child.once("close", (exitCode, signal) => { clearInterval(progress); if (escalation)
-    clearTimeout(escalation); resolve({ exitCode, error: error ?? (signal ? `terminated by ${signal}` : null), aborted: leaseLost || Boolean(signal) || Boolean(error) }); }); }); }
 function checkShellScript() {
     return [
         'completion="${DD_FLOW_CHECK_COMPLETION_FILE:-}"',

package/dist/services/managed-processes.js

@@ -13,7 +13,7 @@ export function registerManagedProcess(context, input) {
     const token = crypto.randomUUID();
     db.run(`INSERT INTO managed_processes
       (id, kind, pid, pid_started_at, owner_id, lease_token, lease_expires_at, project_id, run_id, work_id, check_id, operation_id, stdout_path, stderr_path, state, started_at, updated_at, finished_at, termination_reason, metadata_json)
-     VALUES (?, ?, NULL, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'starting', ?, ?, NULL, NULL, ?)`, [id, input.kind, input.ownerId, token, leaseExpiry(now, input.leaseMs), input.projectId ?? null, input.runId ?? null, input.workId ?? null, input.checkId ?? null, input.operationId ?? null, input.stdoutPath ?? null, input.stderrPath ?? null, now, now, JSON.stringify(input.metadata ?? {})]);
+     VALUES (?, ?, NULL, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'starting', ?, ?, NULL, NULL, ?)`, [id, input.kind, input.ownerId, token, leaseExpiry(now, input.leaseMs), input.projectId ?? null, input.runId ?? null, input.workId ?? null, input.checkId ?? null, input.operationId ?? null, input.stdoutPath ?? null, input.stderrPath ?? null, now, now, JSON.stringify({ ...input.metadata, ...(input.ownerPid ? { owner_pid: input.ownerPid, owner_pid_started_at: processStartedAt(input.ownerPid) } : {}) })]);
     return requireProcess(db, id);
 }
 export function confirmManagedProcess(context, input) {
@@ -23,6 +23,10 @@ export function confirmManagedProcess(context, input) {
     const metadata = parseMetadata(current.metadata_json);
     if (input.processGroupId)
         metadata.process_group_id = input.processGroupId;
+    if (input.ownerPid) {
+        metadata.owner_pid = input.ownerPid;
+        metadata.owner_pid_started_at = processStartedAt(input.ownerPid);
+    }
     const result = db.run(`UPDATE managed_processes
      SET pid = ?, pid_started_at = ?, state = 'running', lease_expires_at = ?, updated_at = ?, metadata_json = ?
      WHERE id = ? AND lease_token = ? AND state = 'starting'`, [input.pid, processStartedAt(input.pid), leaseExpiry(now, input.leaseMs), now, JSON.stringify(metadata), input.id, input.leaseToken]);
@@ -48,12 +52,13 @@ export function processIsAlive(record) {
     try {
         process.kill(record.pid, 0);
     }
-    catch {
-        return false;
+    catch (error) {
+        return error.code !== "ESRCH";
     }
-    return !record.pid_started_at || record.pid_started_at === processStartedAt(record.pid);
+    const started = processStartedAt(record.pid);
+    return !record.pid_started_at || !started || record.pid_started_at === started;
 }
-function processTreeIsAlive(record) {
+export function processTreeIsAlive(record) {
     if (processIsAlive(record))
         return true;
     const group = parseMetadata(record.metadata_json).process_group_id;
@@ -68,6 +73,12 @@ function processTreeIsAlive(record) {
     }
     return false;
 }
+export function managedOwnerIsAlive(record) {
+    const metadata = parseMetadata(record.metadata_json);
+    if (typeof metadata.owner_pid !== "number")
+        return null;
+    return processIsAlive({ pid: metadata.owner_pid, pid_started_at: typeof metadata.owner_pid_started_at === "string" ? metadata.owner_pid_started_at : null });
+}
 /**
  * Expiry proves that observation stopped, not that the owner died.  A live PID
  * remains owned until its result is reconciled; only a dead process can be
@@ -81,7 +92,8 @@ export function claimExpiredManagedProcesses(context, ownerId) {
         const candidates = db.all("SELECT * FROM managed_processes WHERE state IN ('starting','running','stopping','orphaned') AND lease_expires_at < ? ORDER BY lease_expires_at, id", [now]);
         const claimed = [];
         for (const candidate of candidates) {
-            if (processTreeIsAlive(candidate))
+            const ownerAlive = managedOwnerIsAlive(candidate);
+            if (ownerAlive === true || (ownerAlive === null && processTreeIsAlive(candidate)))
                 continue;
             const token = crypto.randomUUID();
             const result = db.run("UPDATE managed_processes SET owner_id = ?, lease_token = ?, state = 'orphaned', lease_expires_at = ?, updated_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','stopping','orphaned') AND lease_expires_at < ?", [ownerId, token, leaseExpiry(now), now, candidate.id, candidate.lease_token, now]);

package/dist/services/vnext-code.js

@@ -1,10 +1,10 @@
 import crypto from "node:crypto";
-import { spawn } from "node:child_process";
+import { runWorkspaceBootstrap } from "./workspace-bootstrap.js";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
-import { aggregateCheckDeclarations, checkReceipts, codeExecutionEnvironment, finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceChangedPaths, workspaceFingerprint } from "./code-checks.js";
+import { aggregateCheckDeclarations, checkReceipts, finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceChangedPaths, workspaceFingerprint } from "./code-checks.js";
 import { requireProjectByRoot } from "./projects.js";
 import { appendFlowRunTimelineEvent, advanceFlowRun, attachFlowRunStage, completeFlowRunStage, completeFlowRun, getFlowRunVariables, gitFacts } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
@@ -653,50 +653,22 @@ async function ensureCodeWorkspaceReady(context, projectId, run, root, readiness
         throw new AppError("execution_profile_invalid", "CODE requires a frozen bootstrap command in the RUN execution profile", 1, { run_id: run.id });
     }
     const receiptPath = path.join(root, "workspace-readiness.json");
-    const prior = readReadiness(receiptPath);
-    if (prior?.workspace_root === run.workspace_root && prior.command === bootstrap.command && prior.status === "passed" && JSON.stringify(prior.check_declarations ?? []) === JSON.stringify(readinessChecks))
-        return { ...prior, reused: true };
+    // Re-run the project bootstrap on stage entry: a prior receipt cannot prove
+    // that ignored dependencies or local services still exist.
     const startedAt = new Date().toISOString();
     progress?.(`workspace bootstrap started: ${bootstrap.command}`);
-    const result = await runBootstrap(bootstrap.command, run.workspace_root, codeExecutionEnvironment(run.workspace_root), progress);
+    const result = await runWorkspaceBootstrap(context, { projectId, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, command: bootstrap.command, artifactDir: "05-code/readiness", progress });
     const bootstrapPassed = result.exit_code === 0 && !result.error;
     const checks = bootstrapPassed && readinessChecks.length
         ? await runCodeChecks(context, { projectId, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, scope: "aggregate", artifactDir: "05-code/readiness", checks: readinessChecks, ...(progress ? { progress } : {}) })
         : [];
-    const receipt = { schema_id: "dd-flow/workspace-readiness@2", workspace_root: run.workspace_root, command: bootstrap.command, policy_ref: bootstrap.policy_ref, started_at: startedAt, finished_at: new Date().toISOString(), status: bootstrapPassed && checks.every((check) => check.status === "passed") ? "passed" : "failed", exit_code: result.exit_code, stdout: result.stdout, stderr: result.stderr, check_declarations: readinessChecks, checks: checks.map((check) => ({ id: check.id, status: check.status, receipt_path: check.receipt_path })), ...(result.error ? { error: result.error } : {}), receipt_path: receiptPath };
+    const receipt = { schema_id: "dd-flow/workspace-readiness@2", workspace_root: run.workspace_root, command: bootstrap.command, policy_ref: bootstrap.policy_ref, started_at: startedAt, finished_at: new Date().toISOString(), status: bootstrapPassed && checks.every((check) => check.status === "passed") ? "passed" : "failed", process_id: result.process_id, stdout_path: result.stdout_path, stderr_path: result.stderr_path, completion_path: result.completion_path, exit_code: result.exit_code, stdout: result.stdout, stderr: result.stderr, check_declarations: readinessChecks, checks: checks.map((check) => ({ id: check.id, status: check.status, receipt_path: check.receipt_path })), ...(result.error ? { error: result.error } : {}), receipt_path: receiptPath };
     fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
     if (receipt.status !== "passed")
         throw new AppError("workspace_readiness_failed", "CODE workspace bootstrap failed", 1, receipt);
     progress?.("workspace bootstrap passed");
     return receipt;
 }
-function runBootstrap(command, cwd, environment, progress) {
-    return new Promise((resolve) => {
-        const started = Date.now();
-        const child = spawn("/bin/sh", ["-lc", command], { cwd, env: environment, stdio: ["ignore", "pipe", "pipe"] });
-        let stdout = "";
-        let stderr = "";
-        let error = null;
-        child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout += chunk; });
-        child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk; });
-        const heartbeat = setInterval(() => progress?.(`workspace bootstrap still running (${Math.floor((Date.now() - started) / 1000)}s)`), 15_000);
-        const timeout = setTimeout(() => child.kill("SIGTERM"), 15 * 60 * 1000);
-        child.once("error", (value) => { error = value.message; });
-        child.once("close", (exitCode, signal) => {
-            clearInterval(heartbeat);
-            clearTimeout(timeout);
-            resolve({ exit_code: exitCode, stdout, stderr, error: error ?? (signal ? `terminated by ${signal}` : null) });
-        });
-    });
-}
-function readReadiness(file) {
-    try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
-    }
-    catch {
-        return null;
-    }
-}
 function requireHome(run) {
     if (!run.run_root)
         throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1);

package/dist/services/vnext-merge.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { runWorkspaceBootstrap } from "./workspace-bootstrap.js";
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync, spawnSync } from "node:child_process";
@@ -220,7 +221,7 @@ export async function finishVnextMerge(context, input) {
         throw new AppError("merge_semantic_blocked", "A blocked semantic result cannot complete MERGE", 2, { result_path: resultPath });
     if (request.checkpoint === "apply_recorded") {
         input.progress?.("bootstrapping integrated target");
-        runBootstrap(run, request.target_workspace);
+        await runBootstrap(context, run, request.target_workspace, request.merge_request_id, input.progress);
         context.db.run("UPDATE merge_requests SET checkpoint = 'bootstrap_ready', updated_at = ? WHERE merge_request_id = ?", [context.now(), request.merge_request_id]);
         request = requireRequest(context, request.merge_request_id);
     }
@@ -360,9 +361,14 @@ function protocolIds(home) { const root = path.join(home, "03-plan"); if (!fs.ex
 function workspaceRoute(home) { const file = path.join(home, "02-protocolize", "workspace-route.json"); const value = JSON.parse(fs.readFileSync(file, "utf8")); if (!value.policy?.integration_branch)
     throw new AppError("workspace_route_missing", "MERGE requires the frozen integration branch", 1, { file }); return { integration_branch: value.policy.integration_branch }; }
 function executionSettings(run) { return JSON.parse(run.index_json).execution_profile?.settings ?? {}; }
-function runBootstrap(run, cwd) { const command = executionSettings(run).code_bootstrap?.command; if (!command)
-    return; const result = spawnSync("/bin/sh", ["-lc", command], { cwd, encoding: "utf8" }); if (result.status !== 0)
-    throw new AppError("merge_bootstrap_failed", "Integrated target bootstrap failed", 2, { command, stdout: result.stdout, stderr: result.stderr, status: result.status }); }
+async function runBootstrap(context, run, cwd, mergeId, progress) {
+    const command = executionSettings(run).code_bootstrap?.command;
+    if (!command)
+        throw new AppError("execution_profile_invalid", "MERGE requires a frozen workspace bootstrap command", 2);
+    const result = await runWorkspaceBootstrap(context, { projectId: run.project_id, runId: run.id, runHome: requireHome(run), workspaceRoot: cwd, command, artifactDir: `${stageDir}/${mergeId}/readiness`, progress });
+    if (result.exit_code !== 0 || result.error)
+        throw new AppError("merge_bootstrap_failed", "Integrated target bootstrap failed; inspect its retained logs", 2, { command, ...result });
+}
 function verifyLocalDelivery(request) { const head = gitValue(request.target_workspace, ["rev-parse", request.target_branch]); if (!request.integration_commit || head !== request.integration_commit)
     throw new AppError("merge_delivery_unproven", "Local integration branch does not resolve to the accepted integration commit", 1, { target_branch: request.target_branch, expected: request.integration_commit, actual: head }); }
 function cleanupReceiptPath(run) { return path.join(requireHome(run), stageDir, "cleanup-receipt.json"); }

package/dist/services/work-registry.js

@@ -464,10 +464,10 @@ function validateCodeWorkResult(work, value, projectRoot, runHome, runId) {
     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_findings?.map((finding) => finding.finding_ref) ?? [];
+    validateReviewResolutions(work.work_id, assigned, result.resolutions ?? []);
     if (assigned.length) {
         if ((result.changed_paths?.length ?? 0) === 0)
             throw new AppError("review_repair_no_change", "Review repair must materialize a project change; a no-op cannot resolve a finding", 2, { work_id: work.work_id, findings: assigned });
-        validateReviewResolutions(work.work_id, assigned, result.resolutions ?? []);
         for (const resolution of result.resolutions ?? [])
             for (const ref of resolution.evidence_refs ?? [])
                 assertPortableArtifactRef(ref, { workspaceRoot: projectRoot, runHome, runId });
@@ -491,28 +491,34 @@ function renderWorkerPrompt(context, work, run, dependencies) {
     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 call Finish again. 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 the materialization and then executes the check.", "</provided_checks>", ""] : []), "<verification>", ...packet.checks.map((item) => `- ${item.id} at ${item.run_at}: ${item.command} — ${item.purpose}`), "The CLI executes work-scoped checks and retains their receipts. Report semantic evidence only; do not rerun declared checks manually.", "</verification>", "", "<stop_conditions>", ...packet.stop_conditions.map((item) => `- ${item}`), "</stop_conditions>", ""] : [];
+    const codeContext = packet ? ["<semantic_spine>", JSON.stringify(packet.semantic_spine, null, 2), "</semantic_spine>", "", ...(packet.repair ? ["<repair_context>", JSON.stringify(packet.repair, null, 2), "Read the failed receipt and its linked stdout/stderr before editing. Preserve the accepted origin context and fix only the evidenced failure.", "</repair_context>", ""] : []), "<accepted_requirements>", JSON.stringify(packet.requirements, null, 2), "</accepted_requirements>", "", "<write_boundary_invariant>", "For a mutation guarded by membership, ownership, authorization or parent lifecycle state, preserve that predicate in the write statement or make guard and write one explicit transaction with the needed lock. A prior read may diagnose an error but never proves a later write remains allowed. Apply this to create, update, delete and parent-state mutations.", "</write_boundary_invariant>", "", "<acceptance_context>", "The criteria below are end-to-end context. Complete this Work's semantic contribution and declared checks; another ordered Work may own a different acceptance surface.", JSON.stringify(packet.acceptance, null, 2), "</acceptance_context>", "", "<required_read>", "These are mandatory starting sources, not a read allowlist. Read any additional project files needed to implement the Work correctly.", ...packet.required_read.map((item) => `- ${resolveRunReferences(item, work.run_id, requireRunHome(run))}`), "</required_read>", "", "<discovery_boundary>", "These are likely discovery areas, not a hard boundary. Expand project-local investigation when required and report material additions.", ...packet.discovery_boundary.map((item) => `- ${item}`), "</discovery_boundary>", "", "<planned_write_areas>", "SOFT COORDINATION HINT ONLY. These paths help the coordinator avoid concurrent collisions. They do not grant or deny write permission and do not limit the files needed for this Work. You may create or change any project file under workspace_root that is necessary and in semantic scope; report every actual changed path.", ...(packet.planned_write_areas.length ? packet.planned_write_areas.map((item) => `- ${item}`) : ["- none predicted; derive the necessary files from the task"]), "</planned_write_areas>", "", ...(packet.provides_checks.length ? ["<provided_checks>", ...packet.provides_checks.map((item) => `- ${item.id}: materialize ${item.command}${item.definition ? ` as ${item.definition}` : ""}; it is not usable until this Work finishes.`), "Update the declared project command or alias before Work finish. The CLI verifies materialization at Work finish. Execution occurs at its declared run_at gate, not necessarily in this Work.", "</provided_checks>", ""] : []), "<verification>", ...packet.checks.map((item) => `- ${item.id} at ${item.run_at}: ${item.command} — ${item.purpose}`), "The CLI executes work-scoped checks and retains their receipts. Report semantic evidence only; do not rerun declared checks manually.", "</verification>", "", "<stop_conditions>", ...packet.stop_conditions.map((item) => `- ${item}`), "</stop_conditions>", ""] : [];
     if (packet)
         codeContext.push("<document_updates>", JSON.stringify(packet.document_updates, null, 2), "Materialize every listed update. dd-flow verifies the resulting file against its PLAN-time baseline.", "</document_updates>", "", "<completion_contract>", "Successful completion requires empty deviations and blockers and every assigned document update in changed_paths. A necessary path outside planned_write_areas is normal coordination drift, not a blocker; include it in changed_paths and continue.", "</completion_contract>", "");
-    return ["<work>", `- work_id: ${work.work_id}`, `- run_id: ${work.run_id}`, `- project_root: ${run.project_root}`, `- workspace_root: ${run.workspace_root}`, `- run_home: ${requireRunHome(run)}`, "</work>", "", "<hard_write_boundary>", ...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>", "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.", ...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, piping your JSON object to stdin: ${command} work finish ${work.work_id} --result-stdin --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`, `Fail only for an evidenced external or semantic-contract blocker: ${command} work fail ${work.work_id} --reason "receipt path + exact external or semantic blocker" --project-root ${JSON.stringify(run.project_root)} --json`, "</completion>", ""].join("\n");
+    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>", "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, piping your JSON object to stdin: ${command} work finish ${work.work_id} --result-stdin --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`, `Fail only for an evidenced external or semantic-contract blocker: ${command} work fail ${work.work_id} --reason "receipt path + exact external or semantic blocker" --project-root ${JSON.stringify(run.project_root)} --json`, "</completion>", ""].join("\n");
 }
-function resultSchemaGuidance(work, runId) {
+export function resultSchemaGuidance(work, runId) {
     const schema = work.result_schema;
     const refs = `Evidence refs for project source are relative to workspace_root; RUN evidence uses run://${runId}/path/to/artifact.`;
     if (schema === "dd-flow/code-work-result@3") {
         const packet = codePacket(work);
-        const obligationRef = packet?.repair?.check_receipt_id ? packet.checks[0]?.id ?? "CHK-assigned-check" : "AC-001";
-        const obligationNote = packet?.repair?.check_receipt_id
-            ? `This is a gate-repair Work: cite its assigned check id (${obligationRef}) in evidence. Do not substitute an unrelated acceptance criterion.`
-            : "Cite an acceptance criterion or check explicitly assigned to this Work in evidence.";
-        return [refs, obligationNote, "For a review repair, include exactly one resolution per assigned finding; explain what changed and cite evidence that demonstrates the required outcome:", "```json", JSON.stringify({ schema_id: schema, summary: "What was implemented.", changed_paths: ["project-relative/path"], evidence: [{ obligation_ref: obligationRef, refs: ["project-relative/evidence"] }], deviations: [], blockers: [], resolutions: [{ finding_ref: "WRK-000/FIND-001", summary: "How the required outcome was achieved.", evidence_refs: ["project-relative/evidence"] }] }, null, 2), "```"];
+        const obligations = [...new Set([
+                ...(packet?.acceptance ?? []).map((item) => item.criterion_id).filter((id) => Boolean(id)),
+                ...(packet?.checks ?? []).map((item) => item.id),
+                ...(packet?.repair?.review_findings ?? []).flatMap((finding) => finding.obligation_refs ?? [])
+            ])];
+        const findings = packet?.repair?.review_findings ?? [];
+        return [refs, `Assigned obligation refs: ${JSON.stringify(obligations)}. Cite only these in evidence.obligation_ref.`,
+            "This is a shape template, not a completed result. Populate changed_paths and evidence from the actual work and existing files; empty arrays below do not establish completion.",
+            "For a gate repair, cite the assigned check id. For a review repair, replace each resolution summary and fill evidence_refs with existing evidence proving its required outcome. Ordinary Work has resolutions: [].",
+            "```json", JSON.stringify({ schema_id: schema, summary: "Describe the actual implementation.", changed_paths: [], evidence: [], deviations: [], blockers: [], resolutions: findings.map((finding) => ({ finding_ref: finding.finding_ref, summary: "Describe how the assigned required outcome was achieved.", evidence_refs: [] })) }, null, 2), "```",
+            "Each evidence entry has exactly obligation_ref (one assigned ref) and refs (nonempty list of existing evidence paths). Each resolution has finding_ref, summary and nonempty evidence_refs. Do not invent file names or finding ids."];
     }
     if (schema === "dd-flow/code-review-result@1") {
-        return [refs, "Assess every assigned aspect exactly once. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id to form the canonical reference.", "Use this complete minimal shape. Report only material, direct-evidence findings; taste and cosmetics are not findings:", "```json", JSON.stringify({ schema_id: schema, verdict: "pass | findings | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | findings | blocked", summary: "Conclusion.", evidence_refs: ["path/to/file", `run://${runId}/05-code/checks/receipt.json`] }], findings: [{ finding_id: "FIND-001", aspect_id: "assigned_aspect_id", priority: "p0 | p1 | p2 | p3", problem: "Violated obligation or rule.", impact: "Concrete risk or failure.", required_outcome: "Smallest observable result that closes the defect.", evidence_refs: ["path/to/file"], obligation_refs: ["R-001 | AC-001 | policy ref"] }] }, null, 2), "```"];
+        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: [] }], 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), "```"];
     }
     if (schema !== "dd-flow/plan-review-result@1")
         return [];
-    return [refs, "Use this complete minimal shape; do not add fields. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id when the coordinator classifies them:", "```json", JSON.stringify({ schema_id: schema, plan_revision: 1, overall_verdict: "pass | watch | needs_changes | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | watch | needs_changes | blocked", summary: "Conclusion for this aspect.", evidence_refs: ["path/to/file", `run://${runId}/03-plan/plan.json`], findings: [{ finding_id: "FIND-001", severity: "high | medium | low | info", summary: "Problem, if any.", evidence_refs: ["path/to/file"] }] }] }, null, 2), "```"];
+    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: [], 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);

package/dist/services/workspace-bootstrap.js

@@ -0,0 +1,50 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { codeExecutionEnvironment, runCheck } from "./code-checks.js";
+import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedOwnerIsAlive, managedProcessStatus, processTreeIsAlive, registerManagedProcess } from "./managed-processes.js";
+/** CODE and MERGE prepare their own checkout through the same managed executor.
+ * Bootstrap is a project operation, not an alias classified by the engine as a test. */
+export async function runWorkspaceBootstrap(context, input) {
+    const operationId = `bootstrap:${crypto.createHash("sha256").update(JSON.stringify([input.runId, input.workspaceRoot, input.artifactDir, input.command])).digest("hex")}`;
+    const pending = managedProcessStatus(context).find(item => item.operation_id === operationId && ["starting", "running", "stopping"].includes(item.state));
+    if (pending) {
+        if (processTreeIsAlive(pending) || (pending.state === "starting" && managedOwnerIsAlive(pending) !== false)) {
+            throw new AppError("bootstrap_in_progress", "Workspace preparation is still running; inspect its logs and wait for the existing process, do not launch another copy", 2, { process_id: pending.id, stdout_path: pending.stdout_path, stderr_path: pending.stderr_path });
+        }
+        const completionPath = path.join(path.dirname(pending.stdout_path), "completion.json");
+        let completion = null;
+        try {
+            completion = JSON.parse(fs.readFileSync(completionPath, "utf8"));
+        }
+        catch { /* Interrupted shell has no terminal marker. */ }
+        const exitCode = typeof completion?.exit_code === "number" ? completion.exit_code : null;
+        const error = exitCode === null ? "bootstrap ended without a completion marker; inspect retained logs before retrying" : null;
+        finishManagedProcess(context, { id: pending.id, leaseToken: pending.lease_token, state: exitCode === 0 ? "stopped" : "failed", reason: error ?? "bootstrap_completion_reconciled" });
+        return result(pending.id, pending.stdout_path, pending.stderr_path, completionPath, exitCode, error);
+    }
+    const directory = path.join(input.runHome, input.artifactDir, `bootstrap-${crypto.randomUUID()}`);
+    fs.mkdirSync(directory, { recursive: true });
+    const stdoutPath = path.join(directory, "stdout.log"), stderrPath = path.join(directory, "stderr.log"), completionPath = path.join(directory, "completion.json");
+    const managed = registerManagedProcess(context, { kind: "workspace-bootstrap", ownerId: operationId, ownerPid: process.pid, operationId, projectId: input.projectId, runId: input.runId, stdoutPath, stderrPath, metadata: { command: input.command, workspace_root: input.workspaceRoot } });
+    const stdout = fs.openSync(stdoutPath, "a"), stderr = fs.openSync(stderrPath, "a");
+    try {
+        input.progress?.(`workspace bootstrap started: ${input.command}; logs: ${directory}`);
+        const completed = await runCheck(input.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_CHECK_COMPLETION_FILE: completionPath }, stdout, stderr, elapsed => input.progress?.(`workspace bootstrap still running (${elapsed}s); logs: ${directory}; next report in 15s`), pid => confirmManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid }), () => heartbeatManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token }));
+        const current = managedProcessStatus(context).find(item => item.id === managed.id);
+        if (processTreeIsAlive(current))
+            throw new AppError("bootstrap_tree_not_settled", "Bootstrap shell exited but still owns live processes; resources were retained for inspection", 2, { process_id: managed.id, stdout_path: stdoutPath, stderr_path: stderrPath });
+        finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: completed.exitCode === 0 && !completed.error ? "stopped" : "failed", reason: completed.error });
+        return result(managed.id, stdoutPath, stderrPath, completionPath, completed.exitCode, completed.error);
+    }
+    finally {
+        fs.closeSync(stdout);
+        fs.closeSync(stderr);
+    }
+}
+function result(id, stdout, stderr, completion, exitCode, error) {
+    // Full logs remain on disk; keep the returned prompt bounded.
+    const excerpt = (file) => fs.existsSync(file) ? fs.readFileSync(file, "utf8").slice(-64_000) : "";
+    return { exit_code: exitCode, stdout: excerpt(stdout), stderr: excerpt(stderr), error, process_id: id, stdout_path: stdout, stderr_path: stderr, completion_path: completion };
+}

package/package.json

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