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

package/CHANGELOG.md

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

package/dist/build-info.json

@@ -1,11 +1,11 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.15",
-  "cli_commit": "e11a611fe87370d6203792e5c6a54d7205235a26",
-  "built_at": "2026-09-05T09:50:59.828Z",
+  "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

@@ -878,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)) {
@@ -917,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);

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/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,
@@ -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/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 });
@@ -496,7 +499,7 @@ function renderWorkerPrompt(context, work, run, dependencies) {
         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");
+    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;
@@ -658,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);
@@ -667,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/package.json

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