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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

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,8 +1,8 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.14",
-  "cli_commit": "29b30887789f9ee686d5903a4ddcea40a24dc8ce",
-  "built_at": "2026-09-05T08:57:36.734Z",
+  "cli_version": "0.9.0-beta.15",
+  "cli_commit": "e11a611fe87370d6203792e5c6a54d7205235a26",
+  "built_at": "2026-09-05T09:50:59.828Z",
   "built_with_canon": {
     "version": "4.0.4",
     "commit": "c8cae271f844fd3b3c7492f164e13a60eaba4839",

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,10 +1584,14 @@ 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, {
@@ -1618,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/managed-processes.js

@@ -7,6 +7,26 @@ 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()}`;
@@ -40,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)
@@ -67,8 +90,8 @@ export function processTreeIsAlive(record) {
             process.kill(-group, 0);
             return true;
         }
-        catch {
-            return false;
+        catch (error) {
+            return error.code !== "ESRCH";
         }
     }
     return false;
@@ -111,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);
@@ -121,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;
 }
@@ -172,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/work-registry.js

@@ -494,6 +494,8 @@ function renderWorkerPrompt(context, work, run, dependencies) {
     const codeContext = packet ? ["<semantic_spine>", JSON.stringify(packet.semantic_spine, null, 2), "</semantic_spine>", "", ...(packet.repair ? ["<repair_context>", JSON.stringify(packet.repair, null, 2), "Read the failed receipt and its linked stdout/stderr before editing. Preserve the accepted origin context and fix only the evidenced failure.", "</repair_context>", ""] : []), "<accepted_requirements>", JSON.stringify(packet.requirements, null, 2), "</accepted_requirements>", "", "<write_boundary_invariant>", "For a mutation guarded by membership, ownership, authorization or parent lifecycle state, preserve that predicate in the write statement or make guard and write one explicit transaction with the needed lock. A prior read may diagnose an error but never proves a later write remains allowed. Apply this to create, update, delete and parent-state mutations.", "</write_boundary_invariant>", "", "<acceptance_context>", "The criteria below are end-to-end context. Complete this Work's semantic contribution and declared checks; another ordered Work may own a different acceptance surface.", JSON.stringify(packet.acceptance, null, 2), "</acceptance_context>", "", "<required_read>", "These are mandatory starting sources, not a read allowlist. Read any additional project files needed to implement the Work correctly.", ...packet.required_read.map((item) => `- ${resolveRunReferences(item, work.run_id, requireRunHome(run))}`), "</required_read>", "", "<discovery_boundary>", "These are likely discovery areas, not a hard boundary. Expand project-local investigation when required and report material additions.", ...packet.discovery_boundary.map((item) => `- ${item}`), "</discovery_boundary>", "", "<planned_write_areas>", "SOFT COORDINATION HINT ONLY. These paths help the coordinator avoid concurrent collisions. They do not grant or deny write permission and do not limit the files needed for this Work. You may create or change any project file under workspace_root that is necessary and in semantic scope; report every actual changed path.", ...(packet.planned_write_areas.length ? packet.planned_write_areas.map((item) => `- ${item}`) : ["- none predicted; derive the necessary files from the task"]), "</planned_write_areas>", "", ...(packet.provides_checks.length ? ["<provided_checks>", ...packet.provides_checks.map((item) => `- ${item.id}: materialize ${item.command}${item.definition ? ` as ${item.definition}` : ""}; it is not usable until this Work finishes.`), "Update the declared project command or alias before Work finish. The CLI verifies materialization at Work finish. Execution occurs at its declared run_at gate, not necessarily in this Work.", "</provided_checks>", ""] : []), "<verification>", ...packet.checks.map((item) => `- ${item.id} at ${item.run_at}: ${item.command} — ${item.purpose}`), "The CLI executes work-scoped checks and retains their receipts. Report semantic evidence only; do not rerun declared checks manually.", "</verification>", "", "<stop_conditions>", ...packet.stop_conditions.map((item) => `- ${item}`), "</stop_conditions>", ""] : [];
     if (packet)
         codeContext.push("<document_updates>", JSON.stringify(packet.document_updates, null, 2), "Materialize every listed update. dd-flow verifies the resulting file against its PLAN-time baseline.", "</document_updates>", "", "<completion_contract>", "Successful completion requires empty deviations and blockers and every assigned document update in changed_paths. A necessary path outside planned_write_areas is normal coordination drift, not a blocker; include it in changed_paths and continue.", "</completion_contract>", "");
+    if (packet)
+        codeContext.push("<temporary_services>", "Prefer the declared check launcher: it already owns check resources. If the planned scenario genuinely requires an interactive HTTP service, use the managed supervisor below. This is a template: replace the project service command, port names and readiness path from the plan/project instructions; do not invent a fixed port.", `${command} runtime process start --run ${run.id} --project-root ${JSON.stringify(run.project_root)} --command '<project-service-command>' --ports api --ready-port api --ready-path /health --json --progress-jsonl`, "The service receives DD_FLOW_PORT_API (and equivalent variables for all declared names). The command stays running as its supervisor. Retain its tool handle; wait for the service ready event and read its service.json receipt. Pass those exact ports and the same project environment to reset/seed, API and browser operations.", "A ready receipt proves service readiness only. Record the scenario outcome and real evidence separately. After the scenario, execute the exact stop_command from that receipt, then wait for the supervisor to exit. Never use pkill/killall or stop a sibling's process. If cleanup fails, retain the process id and report the failure; do not claim the resource is free.", "</temporary_services>", "");
     return ["<work>", `- work_id: ${work.work_id}`, `- run_id: ${work.run_id}`, `- project_root: ${run.project_root}`, `- workspace_root: ${run.workspace_root}`, `- run_home: ${requireRunHome(run)}`, "</work>", "", "<hard_write_boundary>", ...writeBoundary, "</hard_write_boundary>", "", ...codeContext, "<dependency_results>", JSON.stringify(dependencies.filter(Boolean), null, 2), "</dependency_results>", "", "<task>", resolveRunReferences(work.task, work.run_id, requireRunHome(run)), "</task>", "", ...(work.result_schema ? ["<result_contract>", `Return JSON matching \`${work.result_schema}\`.`, ...resultSchemaGuidance(work, run.id), "Do not create result.json yourself. Send the JSON to dd-flow on stdin; it atomically validates and stores the canonical receipt.", "</result_contract>", ""] : []), "<completion>", "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");
 }
 export function resultSchemaGuidance(work, runId) {

package/dist/services/workspace-bootstrap.js

@@ -27,7 +27,7 @@ export async function runWorkspaceBootstrap(context, input) {
     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 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}`);

package/package.json

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