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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.16
+
+### Patch Changes
+
+- Make repair verification causal and retryable, preserve attempt-qualified
+  evidence, expose RUN continuation from persisted lifecycle state, and keep
+  native child ownership bound to the physical harness session.
+
+## 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,11 +1,11 @@
 {
   "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.16",
+  "cli_commit": "8de503c90a952a8b56300a0c0367dd89be5c2436",
+  "built_at": "2026-09-05T22:05:40.605Z",
   "built_with_canon": {
     "version": "4.0.4",
-    "commit": "c8cae271f844fd3b3c7492f164e13a60eaba4839",
+    "commit": "8e572d151c7f9d22c2b60122c87d9febcbfbde69",
     "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",

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);
@@ -877,6 +878,10 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         const semanticFile = optionalOption(parsed, "semantic-file") ?? optionalOption(parsed, "data");
         const resultFile = optionalOption(parsed, "result-file") ?? semanticFile;
         const resultStdin = hasOption(parsed, "result-stdin");
+        const retryCheckId = optionalOption(parsed, "retry-check");
+        const retryReason = optionalOption(parsed, "reason");
+        if (retryCheckId && !retryReason?.trim())
+            throw new AppError("usage", "--retry-check requires --reason explaining the recovered environment", 2);
         if (stage === "specify" && isVnextSpecifyRun(context, { projectRoot, runId })) {
             const outcome = optionalOption(parsed, "outcome");
             if (!outcome || !["specified", "failed", "cancelled"].includes(outcome)) {
@@ -916,17 +921,17 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             if (semanticFile || resultFile || resultStdin || hasOption(parsed, "outcome")) {
                 throw new AppError("usage", "vNext CODE finish accepts only --verification-file", 2);
             }
-            return await finishVnextCode(context, { projectRoot, runId, verificationFile: optionalOption(parsed, "verification-file") ?? path.join("<missing>", "code-verification.json"), progress: commandProgress(io, output) });
+            return await finishVnextCode(context, { projectRoot, runId, verificationFile: optionalOption(parsed, "verification-file") ?? path.join("<missing>", "code-verification.json"), ...(retryCheckId ? { retryCheckId, retryReason: retryReason } : {}), progress: commandProgress(io, output) });
         }
         if (stage === "code-review" && isVnextCodeReviewRun(context, { projectRoot, runId })) {
             if (resultStdin || semanticFile || resultFile || hasOption(parsed, "outcome"))
                 throw new AppError("usage", "vNext CODE-REVIEW uses --decision-file", 2);
-            return await finishVnextCodeReview(context, { projectRoot, runId, ...(optionalOption(parsed, "decision-file") ? { decisionFile: optionalOption(parsed, "decision-file") } : {}), progress: commandProgress(io, output) });
+            return await finishVnextCodeReview(context, { projectRoot, runId, ...(optionalOption(parsed, "decision-file") ? { decisionFile: optionalOption(parsed, "decision-file") } : {}), ...(retryCheckId ? { retryCheckId, retryReason: retryReason } : {}), progress: commandProgress(io, output) });
         }
         if (stage === "merge" && isVnextMergeRun(context, { projectRoot, runId })) {
             if (resultStdin || semanticFile || resultFile || hasOption(parsed, "outcome"))
                 throw new AppError("usage", "vNext MERGE uses the Work result path returned by stage start", 2);
-            return await finishVnextMerge(context, { projectRoot, runId, requestId: requiredOption(parsed, "request"), workId: requiredOption(parsed, "work"), progress: commandProgress(io, output) });
+            return await finishVnextMerge(context, { projectRoot, runId, requestId: requiredOption(parsed, "request"), workId: requiredOption(parsed, "work"), ...(retryCheckId ? { retryCheckId, retryReason: retryReason } : {}), progress: commandProgress(io, output) });
         }
         if (hasOption(parsed, "outcome") || hasOption(parsed, "result-file") || resultStdin) {
             throw new AppError("usage", "--outcome, --result-file and --result-stdin are only available for vNext SPECIFY", 2);
@@ -1583,10 +1588,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 +1627,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/schemas/code-work-batch.schema.json

@@ -19,7 +19,7 @@
     "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release", "external"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "minLength": 1}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "ports": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"}}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}]},
     "documentUpdate": {"type": "object", "additionalProperties": false, "required": ["path", "action", "owner", "reason", "baseline_sha256"], "properties": {"path": {"type": "string", "minLength": 1}, "action": {"enum": ["create", "update"]}, "owner": {"type": "string", "minLength": 1}, "reason": {"type": "string", "minLength": 1}, "baseline_sha256": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"}}},
     "reviewFinding": {"type": "object", "additionalProperties": false, "required": ["finding_ref", "priority", "problem", "impact", "required_outcome", "evidence_refs", "obligation_refs", "decision_reason", "check_refs"], "properties": {"finding_ref": {"type": "string", "minLength": 1}, "priority": {"enum": ["p0", "p1", "p2", "p3"]}, "problem": {"type": "string", "minLength": 1}, "impact": {"type": "string", "minLength": 1}, "required_outcome": {"type": "string", "minLength": 1}, "evidence_refs": {"$ref": "#/$defs/strings"}, "obligation_refs": {"$ref": "#/$defs/strings"}, "decision_reason": {"type": "string", "minLength": 1}, "check_refs": {"$ref": "#/$defs/strings"}}},
-    "repair": {"type": "object", "additionalProperties": false, "required": ["origin_work_ids"], "anyOf": [{"required": ["check_receipt_id", "failure_receipt_path"]}, {"required": ["review_findings"]}, {"required": ["semantic_unresolved", "verification_path"]}], "properties": {"origin_work_ids": {"$ref": "#/$defs/strings"}, "check_receipt_id": {"type": "string", "minLength": 1}, "failure_receipt_path": {"type": "string", "minLength": 1}, "review_findings": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/reviewFinding"}}, "semantic_unresolved": {"$ref": "#/$defs/strings"}, "verification_path": {"type": "string", "minLength": 1}}},
+    "repair": {"type": "object", "additionalProperties": false, "required": ["origin_work_ids", "verification_check_refs"], "anyOf": [{"required": ["check_receipt_id", "failure_receipt_path"]}, {"required": ["review_findings"]}, {"required": ["semantic_unresolved", "verification_path"]}], "properties": {"origin_work_ids": {"$ref": "#/$defs/strings"}, "check_receipt_id": {"type": "string", "minLength": 1}, "failure_receipt_path": {"type": "string", "minLength": 1}, "review_findings": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/reviewFinding"}}, "semantic_unresolved": {"$ref": "#/$defs/strings"}, "verification_path": {"type": "string", "minLength": 1}, "verification_check_refs": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/check"}}}},
     "work": {"type": "object", "additionalProperties": false, "required": ["schema_id", "key", "launch_policy", "source", "task", "semantic_spine", "requirements", "acceptance", "document_updates", "required_read", "discovery_boundary", "planned_write_areas", "checks", "provides_checks", "stop_conditions", "depends_on", "result_schema"], "properties": {"schema_id": {"const": "dd-flow/code-work-packet@5"}, "key": {"type": "string", "minLength": 1}, "launch_policy": {"const": "fresh_agent_required"}, "source": {"$ref": "#/$defs/source"}, "repair": {"$ref": "#/$defs/repair"}, "task": {"type": "string", "minLength": 1}, "semantic_spine": {"$ref": "#/$defs/spine"}, "requirements": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/obligation"}}, "acceptance": {"type": "array", "items": {"$ref": "#/$defs/acceptance"}}, "document_updates": {"type": "array", "items": {"$ref": "#/$defs/documentUpdate"}}, "required_read": {"$ref": "#/$defs/strings", "description": "Mandatory starting sources, not a read allowlist."}, "discovery_boundary": {"$ref": "#/$defs/strings", "description": "Likely discovery areas; additional project-local reads are allowed."}, "planned_write_areas": {"type": "array", "items": {"type": "string", "minLength": 1}, "description": "Soft coordination hints only. A worker may change any necessary project file inside the RUN workspace."}, "checks": {"type": "array", "items": {"$ref": "#/$defs/check"}}, "provides_checks": {"type": "array", "items": {"$ref": "#/$defs/check"}}, "stop_conditions": {"$ref": "#/$defs/strings", "description": "Hard semantic or external stop conditions; path prediction drift is not a stop condition."}, "depends_on": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "result_schema": {"const": "dd-flow/code-work-result@3"}}}
   }
 }

package/dist/services/code-checks.js

@@ -222,7 +222,17 @@ catch {
 } }
 export function unchangedFinalGateFailures(context, input) { const wanted = new Set(input.declarations.flatMap((check) => [check.id, checkRef(check)])); const current = workspaceFingerprint(input.workspaceRoot); const latest = new Map(); for (const receipt of checkReceipts(context, { projectId: input.projectId, runId: input.runId }).filter((item) => item.scope === "aggregate" && item.check_refs.some((ref) => wanted.has(ref))))
     for (const ref of receipt.check_refs)
-        latest.set(ref, receipt); return [...new Set(latest.values())].filter((receipt) => receipt.status === "failed" && receipt.before_fingerprint === current); }
+        latest.set(ref, receipt); return [...new Set(latest.values())].filter((receipt) => receipt.status === "failed" && receipt.before_fingerprint === current && receipt.id !== input.retryReceiptId); }
+/** Validate an explicit retry; the caller still executes a fresh real gate and retains a new receipt. */
+export function validateFailedCheckRetry(context, input) {
+    const receipt = checkReceipts(context, { projectId: input.projectId, runId: input.runId }).find((item) => item.id === input.receiptId);
+    if (!receipt || receipt.scope !== "aggregate" || !["failed", "aborted"].includes(receipt.status))
+        throw new AppError("retry_check_invalid", "--retry-check must name a failed or aborted aggregate receipt in this RUN", 2, { check_receipt_id: input.receiptId });
+    const declared = new Set(input.declarations.flatMap((check) => [check.id, checkRef(check)]));
+    if (!receipt.check_refs.some((ref) => declared.has(ref)))
+        throw new AppError("retry_check_invalid", "--retry-check does not belong to this stage gate", 2, { check_receipt_id: input.receiptId, check_refs: receipt.check_refs });
+    return receipt;
+}
 export function checkReceipts(context, input) {
     const where = input.workId ? "project_id = ? AND run_id = ? AND work_id = ?" : "project_id = ? AND run_id = ?";
     const params = input.workId ? [input.projectId, input.runId, input.workId] : [input.projectId, input.runId];

package/dist/services/hooks.js

@@ -309,7 +309,11 @@ export function handleCodexHook(context, input) {
     const project = projectForHook(context, input.projectRoot ?? commandProjectRoot, stringValue(payload.cwd));
     if (!project)
         return { ok: true, observed: false, reason: "unrelated_cwd" };
-    const binding = rootProviderSessionId ? upsertSessionBindingFromPayload(context, project, rootProviderSessionId, payload) : undefined;
+    // Codex retains the root session_id for a thread-spawned child, while the
+    // payload transcript belongs to the current agent_id. Keep lineage separate
+    // from ownership: otherwise a child overwrites the root transcript binding.
+    const bindingOwnerId = providerSessionId ?? rootProviderSessionId;
+    const binding = bindingOwnerId ? upsertSessionBindingFromPayload(context, project, bindingOwnerId, payload) : undefined;
     const storageId = providerSessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", providerSessionId)) : null;
     const parentSessionId = parentProviderSessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", parentProviderSessionId)) : null;
     const observedSession = flowPayload

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

@@ -229,7 +229,33 @@ export function getFlowRunStatus(context, input) {
     const run = resolveRun(context, project.id, input.runId);
     const index = authoritativeIndex(run);
     const runtime = readRuntimeSnapshot(run.runtime_path);
-    return { ok: true, run: flowRunSummary(run), index, ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, run, index) };
+    return { ok: true, run: flowRunSummary(run), index, continuation: runContinuation(context, run, index), ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, run, index) };
+}
+/** A read-only projection of the next legal lifecycle action.
+ * It is derived from the persisted RUN/Work facts so controllers never infer a
+ * transition from a model's prose or a hard-coded stage array. */
+function runContinuation(context, run, index) {
+    if (["done", "failed", "cancelled"].includes(run.status))
+        return { kind: "terminal", stage: null, attempt: null, work_id: null, reason: run.status, command: null };
+    const active = index.stage_runs.find((stage) => !["done", "skipped"].includes(stage.status));
+    if (active) {
+        const runningWork = context.db.get("SELECT work_id FROM works WHERE project_id = ? AND run_id = ? AND status = 'running' ORDER BY updated_at DESC LIMIT 1", [run.project_id, run.id]);
+        const kind = active.status === "running" ? "continue_stage" : active.status === "paused" || active.status === "waiting_for_user" ? "paused" : "blocked";
+        return { kind, stage: active.stage, attempt: active.attempt ?? null, work_id: active.pause?.work_id ?? runningWork?.work_id ?? null, reason: active.status, command: null };
+    }
+    if (run.status === "waiting_for_user" || run.status === "paused")
+        return { kind: "paused", stage: index.current_stage ?? null, attempt: null, work_id: null, reason: run.status, command: null };
+    if (run.status === "blocked")
+        return { kind: "blocked", stage: index.current_stage ?? null, attempt: null, work_id: null, reason: run.status, command: null };
+    if (run.flow_kind === "vnext_specify" || run.flow_kind === "vnext_protocolize") {
+        const completed = index.stage_runs.filter((stage) => stage.status === "done" || stage.status === "skipped").sort((left, right) => right.order - left.order)[0];
+        const next = completed ? vnextStages.find((stage) => stage.id === completed.stage)?.next.find((candidate) => candidate !== "plan-review" || index.settings?.plan_review?.mode !== "off") : "specify";
+        if (!next)
+            return { kind: "terminal", stage: null, attempt: null, work_id: null, reason: "flow_complete", command: null };
+        const command = `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow stage start ${run.id} --stage ${next} --project-root ${JSON.stringify(run.project_root)} --json`;
+        return { kind: "start_stage", stage: next, attempt: null, work_id: null, reason: "legal_successor", command };
+    }
+    return { kind: "wait", stage: index.current_stage ?? null, attempt: null, work_id: null, reason: "no_vnext_continuation", command: null };
 }
 export function getFlowRunConfig(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -470,7 +496,7 @@ export function attachFlowRunStage(context, input) {
     const existing = index.stage_runs.find((item) => item.stage === stage);
     assertVnextStageStart(run, index, stage, status, existing);
     if (status === "running" && existing) {
-        archiveExistingStageAttempt(runArtifactRoot(run), dir);
+        archiveExistingStageAttempt(context, project.id, run.id, runArtifactRoot(run), dir);
     }
     const stageRun = {
         ...(existing ?? { order: index.stage_runs.length + 1 }),
@@ -776,7 +802,7 @@ export function prepareVnextMergeSourceRepairAttempt(context, input) {
     }
     const root = runArtifactRoot(run);
     for (const stage of ["code", "code-review", "merge"])
-        archiveExistingStageAttempt(root, vnextStageDirectory(stage));
+        archiveExistingStageAttempt(context, project.id, run.id, root, vnextStageDirectory(stage));
     const now = context.now();
     const restarted = {
         ...code,
@@ -1263,7 +1289,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);
     }
@@ -1391,7 +1417,9 @@ function resolveWorkspaceRoot(workspaceRoot) {
     }
     return fs.realpathSync(absolute);
 }
-function archiveExistingStageAttempt(runRoot, stageDir) {
+/** Move one completed stage attempt and update only known durable path columns.
+ * Receipt bytes remain immutable; readers resolve their new location through the DB. */
+function archiveExistingStageAttempt(context, projectId, runId, runRoot, stageDir) {
     const currentStageDir = path.join(runRoot, stageDir);
     if (!fs.existsSync(currentStageDir) || !fs.statSync(currentStageDir).isDirectory()) {
         return;
@@ -1409,6 +1437,17 @@ function archiveExistingStageAttempt(runRoot, stageDir) {
     for (const entry of entries) {
         fs.renameSync(path.join(currentStageDir, entry), path.join(archiveDir, entry));
     }
+    const oldPrefix = `${currentStageDir}${path.sep}`;
+    const newPrefix = `${archiveDir}${path.sep}`;
+    const rewrite = (table, column, where, values) => {
+        context.db.run(`UPDATE ${table} SET ${column} = ? || substr(${column}, ?) WHERE ${column} LIKE ? AND ${where}`, [newPrefix, oldPrefix.length + 1, `${oldPrefix}%`, ...values]);
+    };
+    const workScope = "work_id IN (SELECT work_id FROM works WHERE project_id = ? AND run_id = ?)";
+    rewrite("work_sessions", "prompt_path", workScope, [projectId, runId]);
+    rewrite("work_sessions", "result_path", workScope, [projectId, runId]);
+    const receiptScope = "project_id = ? AND run_id = ?";
+    for (const column of ["stdout_path", "stderr_path", "receipt_path"])
+        rewrite("check_receipts", column, receiptScope, [projectId, runId]);
 }
 function writeJsonFile(file, value) {
     const tmpFile = `${file}.tmp-${process.pid}-${Date.now()}`;

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-review.js

@@ -11,7 +11,7 @@ import { flowCommand } from "./stage-pause.js";
 import { assertStageStartHookEvent } from "./hooks.js";
 import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
 import { addVnextCodeRepair } from "./vnext-code.js";
-import { finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceFingerprint } from "./code-checks.js";
+import { finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, validateFailedCheckRetry, workspaceFingerprint } from "./code-checks.js";
 import { addWorkBatch, bindStageCoordinatorWork, finishWork, refreshRunWorkProjection } from "./work-registry.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { writeStageReport } from "./stage-report-renderer.js";
@@ -172,9 +172,13 @@ export async function finishVnextCodeReview(context, input) {
     const outcome = decision.findings.some((item) => item.disposition === "defer") ? "accepted_with_DEF" : "accepted";
     const repairs = reviewRepairWorks(context, project.id, run.id, root, cycle);
     const finalChecks = finalCodeCheckDeclarations(run.workspace_root, codeWorks(context, project.id, run.id).flatMap((work) => { const payload = readJsonString(work.payload_json); return Array.isArray(payload.checks) ? payload.checks : []; }));
-    const unchangedFailures = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: finalChecks });
+    if (input.retryCheckId) {
+        validateFailedCheckRetry(context, { projectId: project.id, runId: run.id, receiptId: input.retryCheckId, declarations: finalChecks });
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "check_retry_requested", check_receipt_id: input.retryCheckId, stage, reason: input.retryReason ?? "operator retry" });
+    }
+    const unchangedFailures = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: finalChecks, ...(input.retryCheckId ? { retryReceiptId: input.retryCheckId } : {}) });
     if (unchangedFailures.length)
-        throw new AppError("code_review_gate_repair_required", "CODE-REVIEW final gate already failed for the unchanged workspace; repair the evidenced failure before retrying", 2, { outcome: "repair_required", retry_after_workspace_change: true, workspace_fingerprint: unchangedFailures[0].workspace_fingerprint, failures: unchangedFailures });
+        throw new AppError("code_review_gate_repair_required", "CODE-REVIEW final gate already failed for the unchanged workspace; choose source repair or restore the environment and retry that receipt", 2, { outcome: "repair_required", retry_after_workspace_change: true, workspace_fingerprint: unchangedFailures[0].workspace_fingerprint, failures: unchangedFailures, retry_command: `${finishCommand(context, run.id, projectRoot, decisionFile)} --retry-check ${unchangedFailures[0].id} --reason "<environment recovery evidence>"` });
     const receipts = await runCodeChecks(context, { projectId: project.id, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, artifactDir: stageDir, scope: "aggregate", checks: finalChecks, ...(input.progress ? { progress: input.progress } : {}) });
     const failed = receipts.filter((receipt) => receipt.status !== "passed");
     if (failed.length)
@@ -183,7 +187,8 @@ export async function finishVnextCodeReview(context, input) {
             outcome: "repair_required",
             retry_after_workspace_change: true,
             workspace_fingerprint: failed[0].workspace_fingerprint,
-            repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-stdin --project-root ${JSON.stringify(projectRoot)} --json`
+            repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-stdin --project-root ${JSON.stringify(projectRoot)} --json`,
+            retry_command: `${finishCommand(context, run.id, projectRoot, decisionFile)} --retry-check ${failed[0].id} --reason "<environment recovery evidence>"`
         });
     const stopTarget = executionStopTarget(run);
     const nextAction = stopTarget === "merge_completed" ? "start_merge" : "code_review_completed";

package/dist/services/vnext-code.js

@@ -4,7 +4,7 @@ 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, finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceChangedPaths, workspaceFingerprint } from "./code-checks.js";
+import { aggregateCheckDeclarations, checkReceipts, finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, validateFailedCheckRetry, 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";
@@ -157,9 +157,13 @@ export async function finishVnextCode(context, input) {
         return { ok: true, run_id: run.id, stage, outcome: "repair_required", verification, repair, instruction: "The semantic verification is not accepted. Run the returned repair Work, then update code-verification.json and invoke this same stage finish command again." };
     }
     const checks = finalCodeCheckDeclarations(run.workspace_root, works.flatMap((work) => packet(work)?.checks ?? []));
-    const unchangedFailures = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: checks });
+    if (input.retryCheckId) {
+        validateFailedCheckRetry(context, { projectId: project.id, runId: run.id, receiptId: input.retryCheckId, declarations: checks });
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "check_retry_requested", check_receipt_id: input.retryCheckId, stage, reason: input.retryReason ?? "operator retry" });
+    }
+    const unchangedFailures = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: checks, ...(input.retryCheckId ? { retryReceiptId: input.retryCheckId } : {}) });
     if (unchangedFailures.length)
-        throw new AppError("code_gate_repair_required", "CODE final gate already failed for the unchanged workspace; repair the evidenced failure before retrying", 2, { outcome: "repair_required", retry_after_workspace_change: true, workspace_fingerprint: unchangedFailures[0].workspace_fingerprint, failures: unchangedFailures });
+        throw new AppError("code_gate_repair_required", "CODE final gate already failed for the unchanged workspace; choose source repair or restore the environment and retry that receipt", 2, { outcome: "repair_required", retry_after_workspace_change: true, workspace_fingerprint: unchangedFailures[0].workspace_fingerprint, failures: unchangedFailures, retry_command: `${finishCommand(context, run.id, projectRoot, input.verificationFile)} --retry-check ${unchangedFailures[0].id} --reason "<environment recovery evidence>"` });
     let receipts = reusableAggregateGateReceipts(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, checks });
     if (!receipts) {
         const release = acquireAggregateGateLock(root);
@@ -187,7 +191,8 @@ export async function finishVnextCode(context, input) {
             outcome: "repair_required",
             retry_after_workspace_change: true,
             workspace_fingerprint: failed[0].workspace_fingerprint,
-            repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-stdin --project-root ${JSON.stringify(projectRoot)} --json`
+            repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-stdin --project-root ${JSON.stringify(projectRoot)} --json`,
+            retry_command: `${finishCommand(context, run.id, projectRoot, input.verificationFile)} --retry-check ${failed[0].id} --reason "<environment recovery evidence>"`
         });
     }
     const allReceipts = checkReceipts(context, { projectId: project.id, runId: run.id });
@@ -330,7 +335,11 @@ export function addVnextCodeRepair(context, input) {
             origin_work_ids: origins.map((work) => work.work_id),
             ...(receipt ? { check_receipt_id: receipt.id, failure_receipt_path: receipt.receipt_path } : {}),
             ...(input.reviewFindings?.length ? { review_findings: input.reviewFindings } : {}),
-            ...(semanticRepair ? { semantic_unresolved: unique(input.semanticUnresolved ?? []), verification_path: input.verificationPath } : {})
+            ...(semanticRepair ? { semantic_unresolved: unique(input.semanticUnresolved ?? []), verification_path: input.verificationPath } : {}),
+            // `run_at` remains the accepted aggregate placement. This separate
+            // repair obligation is deliberately executed before this repair Work is
+            // accepted, so a local fix cannot close without re-proving its cause.
+            verification_check_refs: selectRepairChecks({ ...(failedCheck ? { failedCheck } : {}), ...(input.reviewChecks ? { reviewChecks: input.reviewChecks } : {}), ...(semanticRepair ? { semanticChecks: declaredChecks } : {}) })
         },
         task: input.objective,
         semantic_spine: {
@@ -384,11 +393,8 @@ export function addVnextCodeRepair(context, input) {
     refreshRunWorkProjection(context, project.id, run.id);
     return { ok: true, run_id: run.id, repair_work_id: id, start_command: workStartCommand(context, work) };
 }
-/** Retain the causal declaration for worker context; run_at keeps aggregate gates at stage scope. */
+/** Retain the causal declaration for worker context; run_at still records its original gate. */
 export function selectRepairChecks(input) {
-    // Gate placement belongs to the accepted PLAN. `runCodeChecks` executes only
-    // work-scoped entries, while retaining the aggregate declaration tells the
-    // worker exactly what will be rerun by the coordinator.
     const candidates = input.failedCheck ? [input.failedCheck] : input.reviewChecks ?? input.semanticChecks ?? [];
     const checks = candidates.map((check) => ({ ...check, purpose: `${input.semanticChecks ? "Prove the CODE verification repair" : "Prove the CODE-REVIEW repair"}: ${check.purpose}` }));
     return uniqueBy(checks, (check) => check.id);

package/dist/services/vnext-fanout.js

@@ -66,7 +66,7 @@ export function getVnextFanoutStatus(context, input) {
                 run_key: subagentCapacityKey,
                 available_slots: capacityKnown ? available : null
             },
-            works: { ...counts, ready: ready.works.map((work) => ({ work_id: work.work_id, task: work.task, start_command: work.start_command })) }
+            works: { ...counts, ready: ready.works.map((work) => ({ work_id: work.work_id, task: work.task, launch_policy: work.launch_policy, start_command: work.start_command })) }
         }
     };
 }

package/dist/services/vnext-merge.js

@@ -15,7 +15,7 @@ import { validateSchema } from "./schema-validation.js";
 import { writeStageReport } from "./stage-report-renderer.js";
 import { bindStageCoordinatorWork, createChildWork, failWork, finishFanInWork, finishWork, refreshRunWorkProjection, startStageCoordinatorWork } from "./work-registry.js";
 import { addVnextCodeRepair } from "./vnext-code.js";
-import { checkReceipts, effectiveCheckDeclarations, readCodeCheckProfile, runCodeChecks, unchangedFinalGateFailures, workspaceFingerprint } from "./code-checks.js";
+import { checkReceipts, effectiveCheckDeclarations, readCodeCheckProfile, runCodeChecks, unchangedFinalGateFailures, validateFailedCheckRetry, workspaceFingerprint } from "./code-checks.js";
 import { applyExternalStageContext } from "./stage-context.js";
 import { ensureLaneWorkspace, heartbeatLaneLock, releaseLaneLock, waitAcquireLaneLock } from "./lanes.js";
 const stage = "merge";
@@ -226,14 +226,18 @@ export async function finishVnextMerge(context, input) {
         request = requireRequest(context, request.merge_request_id);
     }
     const checks = effectiveMergeChecks(run, request);
-    const unchanged = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: request.target_workspace, declarations: checks });
+    if (input.retryCheckId) {
+        validateFailedCheckRetry(context, { projectId: project.id, runId: run.id, receiptId: input.retryCheckId, declarations: checks });
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "check_retry_requested", check_receipt_id: input.retryCheckId, stage, reason: input.retryReason ?? "operator retry" });
+    }
+    const unchanged = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: request.target_workspace, declarations: checks, ...(input.retryCheckId ? { retryReceiptId: input.retryCheckId } : {}) });
     if (unchanged.length)
-        throw new AppError("merge_check_repair_required", "MERGE checks already failed for the unchanged integrated tree", 2, { failures: unchanged });
+        throw new AppError("merge_check_repair_required", "MERGE checks already failed for the unchanged integrated tree; choose source repair or restore the environment and retry that receipt", 2, { failures: unchanged, retry_command: `${finishCommand(context, run.id, request, projectRoot)} --retry-check ${unchanged[0].id} --reason "<environment recovery evidence>"` });
     const receipts = request.checkpoint === "checks_passed" || request.checkpoint === "delivered" || request.checkpoint === "finalized" ? checkReceipts(context, { projectId: project.id, runId: run.id, workId: request.executor_work_id }).filter((receipt) => receipt.status === "passed" && receipt.before_fingerprint === workspaceFingerprint(request.target_workspace)) : await runCodeChecks(context, { projectId: project.id, runId: run.id, runHome: requireHome(run), workspaceRoot: request.target_workspace, workId: request.executor_work_id, artifactDir: path.join(stageDir, "works", request.executor_work_id), scope: "aggregate", checks, ...(input.progress ? { progress: input.progress } : {}) });
     const failed = receipts.filter((receipt) => receipt.status !== "passed");
     if (failed.length) {
         context.db.run("UPDATE merge_requests SET status = 'action_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "merge_gate_failed", failures: failed }), context.now(), request.merge_request_id]);
-        throw new AppError("merge_source_repair_required", "Integrated target checks failed. Do not edit the integration workspace: run the returned source-repair command.", 2, { failures: failed, repair_command: `${flowCommand(context)} merge repair ${request.merge_request_id} --project-root ${JSON.stringify(projectRoot)} --json` });
+        throw new AppError("merge_gate_failed", "Integrated target checks failed. Classify retained evidence: source defects use source repair; restored environment uses retry.", 2, { failures: failed, repair_command: `${flowCommand(context)} merge repair ${request.merge_request_id} --project-root ${JSON.stringify(projectRoot)} --json`, retry_command: `${finishCommand(context, run.id, request, projectRoot)} --retry-check ${failed[0].id} --reason "<environment recovery evidence>"` });
     }
     const requiredRefs = mergeAcceptanceRefs(run.workspace_root, JSON.parse(request.protocol_ids_json));
     const passedRefs = new Set(receipts.flatMap((receipt) => receipt.check_refs));

package/dist/services/work-registry.js

@@ -340,7 +340,10 @@ async function settle(context, id, status, result, progress) {
             readCodeCheckProfile(run.workspace_root);
             coordinationDrift = plannedAreaDrift(packet, result);
             const artifactDir = path.relative(requireRunHome(run), path.dirname(link.result_path));
-            receipts = await runCodeChecks(context, { projectId: work.project_id, runId: work.run_id, runHome: requireRunHome(run), workspaceRoot: run.workspace_root, workId: work.work_id, artifactDir, scope: "work", checks: packet.checks.filter((check) => check.run_at === "work"), ...(progress ? { progress } : {}) });
+            const requiredChecks = packet.repair?.verification_check_refs?.length
+                ? uniqueChecks([...packet.checks.filter((check) => check.run_at === "work"), ...packet.repair.verification_check_refs])
+                : packet.checks.filter((check) => check.run_at === "work");
+            receipts = await runCodeChecks(context, { projectId: work.project_id, runId: work.run_id, runHome: requireRunHome(run), workspaceRoot: run.workspace_root, workId: work.work_id, artifactDir, scope: "work", checks: requiredChecks, ...(progress ? { progress } : {}) });
             const failed = receipts.filter((receipt) => receipt.status !== "passed");
             if (failed.length)
                 throw new AppError("work_checks_failed", "Work remains running because required checks failed", 2, { work_id: id, failures: failed, all_receipts: receipts });
@@ -365,7 +368,7 @@ async function settle(context, id, status, result, progress) {
         throw error;
     }
     refreshRunWorkProjection(context, work.project_id, work.run_id);
-    const newlyReady = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? AND status = 'created' ORDER BY created_at, work_id`, [work.project_id, work.run_id]).filter((candidate) => isReady(context, candidate)).map((candidate) => ({ work_id: candidate.work_id, start_command: workStartCommand(context, candidate) }));
+    const newlyReady = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? AND status = 'created' ORDER BY created_at, work_id`, [work.project_id, work.run_id]).filter((candidate) => isReady(context, candidate)).map((candidate) => ({ work_id: candidate.work_id, launch_policy: candidate.launch_policy, start_command: workStartCommand(context, candidate) }));
     appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: `work_${status}`, work_id: work.work_id, session_id: link?.session_id ?? null, ...(coordinationDrift.length ? { coordination_drift: coordinationDrift } : {}) });
     for (const ready of newlyReady)
         appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: "work_dependency_unblocked", work_id: ready.work_id, completed_dependency: work.work_id });
@@ -494,7 +497,9 @@ 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>", "");
-    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");
+    if (packet)
+        codeContext.push("<temporary_services>", "Prefer the declared check launcher: it already owns check resources. If the planned scenario genuinely requires an interactive HTTP service, use the managed supervisor below. This is a template: replace the project service command, port names and readiness path from the plan/project instructions; do not invent a fixed port.", `${command} runtime process start --run ${run.id} --project-root ${JSON.stringify(run.project_root)} --command '<project-service-command>' --ports api --ready-port api --ready-path /health --json --progress-jsonl`, "The service receives DD_FLOW_PORT_API (and equivalent variables for all declared names). The command stays running as its supervisor. Retain its tool handle; wait for the service ready event and read its service.json receipt. Pass those exact ports and the same project environment to reset/seed, API and browser operations.", "A ready receipt proves service readiness only. Record the scenario outcome and real evidence separately. After the scenario, execute the exact stop_command from that receipt, then wait for the supervisor to exit. Never use pkill/killall or stop a sibling's process. If cleanup fails, retain the process id and report the failure; do not claim the resource is free.", "</temporary_services>", "");
+    return ["<work>", `- work_id: ${work.work_id}`, `- run_id: ${work.run_id}`, `- project_root: ${run.project_root}`, `- workspace_root: ${run.workspace_root}`, `- run_home: ${requireRunHome(run)}`, "</work>", "", "<hard_write_boundary>", ...writeBoundary, "</hard_write_boundary>", "", ...codeContext, "<dependency_results>", JSON.stringify(dependencies.filter(Boolean), null, 2), "</dependency_results>", "", "<task>", resolveRunReferences(work.task, work.run_id, requireRunHome(run)), "</task>", "", ...(work.result_schema ? ["<result_contract>", `Return JSON matching \`${work.result_schema}\`.`, ...resultSchemaGuidance(work, run.id), "Do not create result.json yourself. Send the JSON to dd-flow on stdin; it atomically validates and stores the canonical receipt.", "</result_contract>", ""] : []), "<completion>", packet?.repair?.verification_check_refs?.length ? "Work finish runs its normal work-scoped checks plus the listed causal repair checks. Their original run_at remains an aggregate obligation; this is the additional proof required before accepting this repair." : "Work finish runs only declared run_at=work checks. Stage finish owns readiness/code/merge gates; successful Work completion does not mean those gates have passed.", "A failed receipt means only that the check failed; it is not proof of an engine, harness, dependency, or environment blocker.", ...completionRepair, "Use Fail only for a concrete external blocker after deterministic bootstrap or a contradiction with an accepted requirement/non-goal. Never fail merely because a necessary project path was absent from planned_write_areas.", "Finish may run for several minutes. Preserve the shell tool's process/session handle and poll that same invocation until it exits; progress arrives as JSONL on stderr. Never reissue Finish merely because final stdout has not arrived.", `Finish as one standalone command, 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) {
     const schema = work.result_schema;
@@ -656,7 +661,7 @@ export function refreshRunWorkProjection(context, projectId, runId) { refreshRun
     if (fs.existsSync(obsolete))
         fs.rmSync(obsolete);
 } }
-export function codeWorkGraph(context, projectId, runId) { const works = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id`, [projectId, runId]).filter((work) => Boolean(codePacket(work))); const ready = works.filter((work) => isReady(context, work)); return { total: works.length, created: works.filter((work) => work.status === "created").length, running: works.filter((work) => work.status === "running").length, completed: works.filter((work) => work.status === "completed").length, failed: works.filter((work) => work.status === "failed").length, ready: ready.map((work) => ({ work_id: work.work_id, task: work.task, start_command: workStartCommand(context, work) })), blocked: works.filter((work) => work.status === "created" && !ready.includes(work)).map((work) => ({ work_id: work.work_id, depends_on: parseDependencies(work) })) }; }
+export function codeWorkGraph(context, projectId, runId) { const works = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id`, [projectId, runId]).filter((work) => Boolean(codePacket(work))); const ready = works.filter((work) => isReady(context, work)); return { total: works.length, created: works.filter((work) => work.status === "created").length, running: works.filter((work) => work.status === "running").length, completed: works.filter((work) => work.status === "completed").length, failed: works.filter((work) => work.status === "failed").length, ready: ready.map((work) => ({ work_id: work.work_id, task: work.task, launch_policy: work.launch_policy, start_command: workStartCommand(context, work) })), blocked: works.filter((work) => work.status === "created" && !ready.includes(work)).map((work) => ({ work_id: work.work_id, depends_on: parseDependencies(work) })) }; }
 function parsePayload(work) { if (!work.payload_json)
     return null; try {
     const value = JSON.parse(work.payload_json);
@@ -665,6 +670,7 @@ function parsePayload(work) { if (!work.payload_json)
 catch {
     return null;
 } }
+function uniqueChecks(checks) { return checks.filter((check, index) => checks.findIndex((candidate) => candidate.id === check.id) === index); }
 function codePacket(work) { const value = parsePayload(work); if (value?.schema_id !== "dd-flow/code-work-packet@5")
     return null; return value; }
 function assertNoCycles(nodes) { const local = new Map(nodes.map((node) => [node.id, node.dependencies.filter((dependency) => nodes.some((candidate) => candidate.id === dependency))])); const active = new Set(); const done = new Set(); const visit = (id) => { if (active.has(id))

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.16",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {