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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.15
+
+### Patch Changes
+
+- Add owned temporary HTTP service supervision with allocated ports and readiness receipts. Prevent duplicate workspace bootstrap processes, retain resources when process ownership is uncertain, and share safe stop behavior between explicit stops and orphan reconciliation.
+
+## 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/README.md

@@ -1,5 +1,18 @@
 # dd-flow-cli
 
+## Managed temporary HTTP services
+
+For an interactive scenario, `runtime process start --run <RUN-ID>
+--project-root <absolute-project> --command '<project command>' --ports api
+--ready-port api --ready-path /health --json --progress-jsonl` runs a foreground
+supervisor. The command receives `DD_FLOW_PORT_API`; use it instead of a fixed
+port. Additional comma-separated names receive equivalent environment variables.
+The ready event points to a receipt and logs under the RUN's `runtime/` folder.
+Keep the tool invocation alive, run the scenario using the allocated ports,
+then execute the exact `stop_command` in that receipt and await the supervisor.
+Readiness is not a scenario pass. Keep semantic/scenario evidence separately.
+Never use a broad `pkill`/`killall`. A failed owned stop retains resources.
+
 `dd-flow-cli` is the mechanical control layer for `dd-flow` workflows.
 
 It does not replace Memory Bank prompts and does not make product, design, merge, or verification judgments. Prompts own intent, route selection, planning depth, evidence meaning, and semantic readiness. The CLI owns explicit local state: projects, protocols, Codex session bindings, transitions, worktree records, lanes, locks, merge queue jobs, hook records, and audit events.

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.15",
+  "cli_commit": "e11a611fe87370d6203792e5c6a54d7205235a26",
+  "built_at": "2026-09-05T09:50:59.828Z",
   "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

@@ -50,7 +50,8 @@ import { finishStage, startStage } from "../services/stage-lifecycle.js";
 import { addWorkBatch, cancelWork, deleteWork, failWork, finishWork, listWorks, mutateWorkDeps, retryWork, showWork, startWork } from "../services/work-registry.js";
 import { createEvalBootstrapSnapshot, createEvalRunSnapshot, prepareVnextSpecifyRun, restoreEvalBootstrapSnapshot, restoreEvalRunSnapshot } from "../services/eval-snapshots.js";
 import { loadExternalStageContext } from "../services/stage-context.js";
-import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, reconcileExpiredManagedProcesses, registerManagedProcess } from "../services/managed-processes.js";
+import { stopManagedProcess, confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, reconcileExpiredManagedProcesses, registerManagedProcess } from "../services/managed-processes.js";
+import { startRuntimeService } from "../services/runtime-service.js";
 const defaultIo = {
     stdout: process.stdout,
     stderr: process.stderr,
@@ -517,7 +518,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return getCliVersionReport();
     }
     if (family === "runtime") {
-        return await dispatchRuntime(context, command, parsed);
+        return await dispatchRuntime(context, command, parsed, commandProgress(io, output));
     }
     if (family === "canon") {
         return dispatchCanon(context, command, parsed);
@@ -1583,14 +1584,19 @@ function dispatchRun(context, command, parsed) {
     }
     throw new AppError("usage", `Unknown run command: ${command ?? "<empty>"}`, 2);
 }
-async function dispatchRuntime(context, command, parsed) {
+async function dispatchRuntime(context, command, parsed, progress) {
     if (command !== "process")
-        throw new AppError("usage", "Usage: dd-flow runtime process <register|confirm|heartbeat|finish|status|reconcile>", 2);
+        throw new AppError("usage", "Usage: dd-flow runtime process <start|stop|register|confirm|heartbeat|finish|status|reconcile>", 2);
     const action = requiredPosition(parsed, 0, "runtime process action");
+    if (action === "start")
+        return await startRuntimeService(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredOption(parsed, "run"), command: requiredOption(parsed, "command"), ports: requiredOption(parsed, "ports").split(","), readyPort: requiredOption(parsed, "ready-port"), readyPath: optionalOption(parsed, "ready-path") ?? "/", timeoutMs: optionalPositiveNumber(parsed, "ready-timeout-ms", true) ?? 30_000, progress });
+    if (action === "stop")
+        return { ok: true, process: await stopManagedProcess(context, { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ...(optionalPositiveNumber(parsed, "grace-ms", true) ? { graceMs: optionalPositiveNumber(parsed, "grace-ms", true) } : {}) }) };
     if (action === "register") {
         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 +1607,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);
@@ -1617,7 +1623,7 @@ async function dispatchRuntime(context, command, parsed) {
         return { ok: true, processes: managedProcessStatus(context) };
     if (action === "reconcile")
         return { ok: true, processes: await reconcileExpiredManagedProcesses(context, requiredOption(parsed, "owner"), optionalPositiveNumber(parsed, "grace-ms", true)) };
-    throw new AppError("usage", "Usage: dd-flow runtime process <register|confirm|heartbeat|finish|status|reconcile>", 2);
+    throw new AppError("usage", "Usage: dd-flow runtime process <start|stop|register|confirm|heartbeat|finish|status|reconcile>", 2);
 }
 function dispatchStat(context, command, parsed) {
     if (command === "usage") {

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

@@ -7,13 +7,33 @@ export function resourceHome(context) {
     return context.env?.DD_FLOW_RESOURCE_HOME ?? context.ddFlowHome ?? "/tmp/dd-flow-runtime";
 }
 export function registerManagedProcess(context, input) {
+    if (!input.uniqueActiveOperation)
+        return insertManagedProcess(context, input);
+    if (!input.operationId)
+        throw new Error("Unique managed operation requires operationId");
+    const db = registry(context);
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const existing = db.get("SELECT * FROM managed_processes WHERE operation_id = ? AND state IN ('starting','running','stopping','orphaned')", [input.operationId]);
+        if (existing)
+            throw Object.assign(new Error("The operation already owns a managed process; observe it instead of spawning a duplicate"), { code: "managed_operation_in_progress", details: { process_id: existing.id, operation_id: input.operationId } });
+        const result = insertManagedProcess(context, input);
+        db.exec("COMMIT");
+        return result;
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+function insertManagedProcess(context, input) {
     const db = registry(context);
     const now = context.now();
     const id = input.id ?? `PROC-${crypto.randomUUID()}`;
     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 +43,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]);
@@ -36,6 +60,9 @@ export function heartbeatManagedProcess(context, input) {
 }
 export function finishManagedProcess(context, input) {
     const db = registry(context);
+    const existing = requireProcess(db, input.id);
+    if (existing.lease_token === input.leaseToken && existing.state === input.state)
+        return true;
     const now = context.now();
     const updated = db.run("UPDATE managed_processes SET state = ?, termination_reason = ?, finished_at = ?, updated_at = ?, lease_expires_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','stopping','orphaned')", [input.state, input.reason ?? null, now, now, now, input.id, input.leaseToken]).changes === 1;
     if (updated)
@@ -48,12 +75,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;
@@ -62,12 +90,18 @@ function processTreeIsAlive(record) {
             process.kill(-group, 0);
             return true;
         }
-        catch {
-            return false;
+        catch (error) {
+            return error.code !== "ESRCH";
         }
     }
     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 +115,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]);
@@ -99,6 +134,26 @@ export function claimExpiredManagedProcesses(context, ownerId) {
 export function managedProcessStatus(context) {
     return registry(context).all("SELECT * FROM managed_processes ORDER BY updated_at DESC, id");
 }
+export async function stopManagedProcess(context, input) {
+    const db = registry(context), record = requireProcess(db, input.id);
+    if (record.lease_token !== input.leaseToken)
+        throw new Error("Managed process lease does not match");
+    if (["stopped", "failed"].includes(record.state) && !processTreeIsAlive(record))
+        return record;
+    db.run("UPDATE managed_processes SET state = 'stopping', updated_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','orphaned')", [context.now(), record.id, record.lease_token]);
+    if (processTreeIsAlive(record)) {
+        terminateOwnedProcess(record, "SIGTERM");
+        await delay(input.graceMs ?? 1_000);
+        if (processTreeIsAlive(record)) {
+            terminateOwnedProcess(record, "SIGKILL");
+            await delay(250);
+        }
+        if (processTreeIsAlive(record))
+            throw Object.assign(new Error("Owned process tree could not be safely stopped; resources retained"), { code: "process_tree_not_settled", details: { process_id: record.id } });
+    }
+    finishManagedProcess(context, { id: record.id, leaseToken: record.lease_token, state: "stopped", reason: input.reason ?? "requested_stop" });
+    return requireProcess(db, record.id);
+}
 /** Reconcile only records the system owns and has atomically claimed. */
 export async function reconcileExpiredManagedProcesses(context, ownerId, graceMs = 1_000) {
     const claimed = claimExpiredManagedProcesses(context, ownerId);
@@ -109,18 +164,15 @@ export async function reconcileExpiredManagedProcesses(context, ownerId, graceMs
             outcomes.push({ id: processRecord.id, outcome: "already_stopped" });
             continue;
         }
-        terminateOwnedProcess(processRecord, "SIGTERM");
-        await delay(graceMs);
-        if (processTreeIsAlive(processRecord)) {
-            terminateOwnedProcess(processRecord, "SIGKILL");
-            await delay(Math.min(graceMs, 250));
+        try {
+            await stopManagedProcess(context, { id: processRecord.id, leaseToken: processRecord.lease_token, graceMs, reason: "orphan_reconciled" });
+            outcomes.push({ id: processRecord.id, outcome: "stopped" });
         }
-        if (processTreeIsAlive(processRecord)) {
+        catch (error) {
+            if (error.code !== "process_tree_not_settled")
+                throw error;
             outcomes.push({ id: processRecord.id, outcome: "kill_failed" });
-            continue;
         }
-        finishManagedProcess(context, { id: processRecord.id, leaseToken: processRecord.lease_token, state: "stopped", reason: "orphan_reconciled" });
-        outcomes.push({ id: processRecord.id, outcome: "stopped" });
     }
     return outcomes;
 }
@@ -160,7 +212,7 @@ function releasePortClaims(db, claims) { for (const claim of claims)
 function terminateOwnedProcess(record, signal) {
     // Never signal a group merely because its former leader PID was once ours.
     // PID reuse or a departed leader makes group ownership unprovable.
-    if (!record.pid || !record.pid_started_at || !processIsAlive(record))
+    if (!record.pid || !record.pid_started_at || processStartedAt(record.pid) !== record.pid_started_at)
         return;
     const group = parseMetadata(record.metadata_json).process_group_id;
     try {

package/dist/services/runs.js

@@ -1263,7 +1263,7 @@ function upsertStage(index, stageRun) {
     }
     index.stage_runs.sort((a, b) => a.order - b.order);
 }
-function resolveRun(context, projectId, idOrAlias) {
+export function resolveRun(context, projectId, idOrAlias) {
     if (isFullEntityId(idOrAlias)) {
         return requireRunById(context, projectId, idOrAlias);
     }

package/dist/services/runtime-service.js

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveRun } from "./runs.js";
+import { codeExecutionEnvironment, runCheck } from "./code-checks.js";
+import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, processTreeIsAlive, registerManagedProcess, reservePorts, resourceHome, stopManagedProcess } from "./managed-processes.js";
+/** Foreground supervisor: the tool may yield while this command owns the service.
+ * Its ready receipt is emitted immediately; a separate stop ends this command.
+ * Readiness is infrastructure evidence, never a successful scenario verdict. */
+export async function startRuntimeService(context, input) {
+    if (!Number.isFinite(input.timeoutMs) || input.timeoutMs <= 0)
+        throw new AppError("validation", "Readiness timeout must be positive and finite", 2);
+    if (!input.command.trim() || !input.ports.length || input.ports.some(name => !/^[a-z][a-z0-9_]*$/.test(name)) || new Set(input.ports).size !== input.ports.length || !input.ports.includes(input.readyPort) || !input.readyPath.startsWith("/") || input.readyPath.startsWith("//"))
+        throw new AppError("validation", "Declare unique lowercase port names, a ready-port from that list and a local /ready-path", 2);
+    const project = requireProjectByRoot(context, path.resolve(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    if (!run?.run_root || !run.workspace_root)
+        throw new AppError("not_found", "Registered RUN with a materialized workspace is required", 2);
+    input = { ...input, runId: run.id };
+    const id = `PROC-${crypto.randomUUID()}`;
+    const directory = path.join(run.run_root, "runtime", id);
+    fs.mkdirSync(directory, { recursive: true });
+    const record = registerManagedProcess(context, { id, kind: "runtime-service", ownerId: `run:${input.runId}`, ownerPid: process.pid, runId: input.runId, projectId: project.id, stdoutPath: path.join(directory, "stdout.log"), stderrPath: path.join(directory, "stderr.log"), metadata: { command: input.command } });
+    const receiptPath = path.join(directory, "service.json");
+    let stdout, stderr;
+    let settled = false, ready = false;
+    const receipt = { schema_id: "dd-flow/runtime-service@1", process_id: record.id, run_id: input.runId, status: "starting", started_at: context.now(), receipt_path: receiptPath, stdout_path: path.join(directory, "stdout.log"), stderr_path: path.join(directory, "stderr.log") };
+    const save = () => { const temporary = `${receiptPath}.${process.pid}.tmp`; fs.writeFileSync(temporary, JSON.stringify(receipt, null, 2)); fs.renameSync(temporary, receiptPath); };
+    try {
+        const allocation = await reservePorts(context, { ownerId: record.owner_id, processId: record.id, names: input.ports });
+        const environment = { ...codeExecutionEnvironment(run.workspace_root), ...Object.fromEntries(Object.entries(allocation.ports).map(([name, port]) => [`DD_FLOW_PORT_${name.toUpperCase()}`, String(port)])), DD_FLOW_EVIDENCE_DIR: directory, DD_FLOW_CHECK_COMPLETION_FILE: path.join(directory, "completion.json") };
+        const quoted = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+        Object.assign(receipt, { ports: allocation.ports, environment: Object.fromEntries(Object.entries(environment).filter(([key]) => key.startsWith("DD_FLOW_PORT_"))), stop_command: `DD_FLOW_HOME=${quoted(context.ddFlowHome)} DD_FLOW_RESOURCE_HOME=${quoted(resourceHome(context))} dd-flow runtime process stop --id ${record.id} --lease-token ${record.lease_token} --json` });
+        save();
+        stdout = fs.openSync(String(receipt.stdout_path), "a");
+        stderr = fs.openSync(String(receipt.stderr_path), "a");
+        const running = runCheck(input.command, run.workspace_root, environment, stdout, stderr, elapsed => input.progress?.(`service ${record.id} alive (${elapsed}s); receipt: ${receiptPath}`), pid => confirmManagedProcess(context, { id: record.id, leaseToken: record.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid }), () => heartbeatManagedProcess(context, { id: record.id, leaseToken: record.lease_token }));
+        void running.then(() => { settled = true; });
+        const deadline = performance.now() + input.timeoutMs;
+        while (!settled && performance.now() < deadline) {
+            try {
+                const response = await fetch(`http://127.0.0.1:${allocation.ports[input.readyPort]}${input.readyPath}`, { signal: AbortSignal.timeout(1_000), redirect: "error" });
+                await response.body?.cancel();
+                ready = response.ok;
+            }
+            catch { /* Startup is observed until the declared deadline. */ }
+            if (ready)
+                break;
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        if (!ready) {
+            await stopManagedProcess(context, { id: record.id, leaseToken: record.lease_token });
+            await running;
+            throw new AppError("service_not_ready", "Service did not pass its declared HTTP readiness check; inspect retained logs", 2, { receipt_path: receiptPath });
+        }
+        Object.assign(receipt, { status: "ready", ready_at: context.now() });
+        save();
+        input.progress?.(`service ready: ${JSON.stringify(receipt)}; keep this supervisor running, use its exact stop command when finished`);
+        const outcome = await running;
+        const current = managedProcessStatus(context).find(item => item.id === record.id);
+        if (current.state === "stopping") {
+            const settleBy = performance.now() + 5_000;
+            while (processTreeIsAlive(current) && performance.now() < settleBy)
+                await new Promise(resolve => setTimeout(resolve, 25));
+        }
+        if (processTreeIsAlive(current))
+            throw new AppError("process_tree_not_settled", "Service still owns live children; retain resources", 2, { process_id: record.id });
+        if (!["stopped", "failed"].includes(current.state))
+            finishManagedProcess(context, { id: record.id, leaseToken: record.lease_token, state: current.state === "stopping" || outcome.exitCode === 0 ? "stopped" : "failed", reason: current.state === "stopping" ? "requested_stop" : outcome.error });
+        Object.assign(receipt, { status: managedProcessStatus(context).find(item => item.id === record.id).state, finished_at: context.now(), exit_code: outcome.exitCode });
+        save();
+        if (receipt.status === "failed")
+            throw new AppError("service_failed", "Service exited unsuccessfully; inspect retained logs", 2, receipt);
+        return receipt;
+    }
+    catch (error) {
+        const current = managedProcessStatus(context).find(item => item.id === record.id);
+        if (!processTreeIsAlive(current))
+            finishManagedProcess(context, { id: record.id, leaseToken: record.lease_token, state: "failed", reason: error instanceof Error ? error.message : String(error) });
+        Object.assign(receipt, { status: "failed", error: error instanceof Error ? error.message : String(error), cleanup_pending: processTreeIsAlive(current) });
+        save();
+        throw error;
+    }
+    finally {
+        if (stdout !== undefined)
+            fs.closeSync(stdout);
+        if (stderr !== undefined)
+            fs.closeSync(stderr);
+    }
+}

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,36 @@ 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");
+    if (packet)
+        codeContext.push("<temporary_services>", "Prefer the declared check launcher: it already owns check resources. If the planned scenario genuinely requires an interactive HTTP service, use the managed supervisor below. This is a template: replace the project service command, port names and readiness path from the plan/project instructions; do not invent a fixed port.", `${command} runtime process start --run ${run.id} --project-root ${JSON.stringify(run.project_root)} --command '<project-service-command>' --ports api --ready-port api --ready-path /health --json --progress-jsonl`, "The service receives DD_FLOW_PORT_API (and equivalent variables for all declared names). The command stays running as its supervisor. Retain its tool handle; wait for the service ready event and read its service.json receipt. Pass those exact ports and the same project environment to reset/seed, API and browser operations.", "A ready receipt proves service readiness only. Record the scenario outcome and real evidence separately. After the scenario, execute the exact stop_command from that receipt, then wait for the supervisor to exit. Never use pkill/killall or stop a sibling's process. If cleanup fails, retain the process id and report the failure; do not claim the resource is free.", "</temporary_services>", "");
+    return ["<work>", `- work_id: ${work.work_id}`, `- run_id: ${work.run_id}`, `- project_root: ${run.project_root}`, `- workspace_root: ${run.workspace_root}`, `- run_home: ${requireRunHome(run)}`, "</work>", "", "<hard_write_boundary>", ...writeBoundary, "</hard_write_boundary>", "", ...codeContext, "<dependency_results>", JSON.stringify(dependencies.filter(Boolean), null, 2), "</dependency_results>", "", "<task>", resolveRunReferences(work.task, work.run_id, requireRunHome(run)), "</task>", "", ...(work.result_schema ? ["<result_contract>", `Return JSON matching \`${work.result_schema}\`.`, ...resultSchemaGuidance(work, run.id), "Do not create result.json yourself. Send the JSON to dd-flow on stdin; it atomically validates and stores the canonical receipt.", "</result_contract>", ""] : []), "<completion>", "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, uniqueActiveOperation: true, 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.15",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {