@deksden-com/dd-flow-cli 0.9.0-beta.156 → 0.9.0-beta.158

package/dist/services/run-controller.js

@@ -56,6 +56,7 @@ import { RECOVERY_POLICY as CAPACITY_POLICY, nativeItemsSettled, recoveryExhaust
 import { renderNativeChildFollowupInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 import { childCapacityDispatchAllowed, childCapacityRecoveryDecision, closeSuccessfulChildCapacity, reconcileChildCapacity } from "./controller-child-capacity.js";
 import { completedChildRepair, reserveChildRepair } from "./controller-child-repair.js";
+import { prepareWorkFailureResolution, readFailureDecision, failureDecisionReady, acceptFailureDecision, applyWorkFailureDecision, reconcilePendingWorkFailure, workFailureResolutionPrompt, workFailureDiagnostic, workFailureBlockActive } from "./controller-work-failure.js";
 import { getVnextFanoutStatus } from "./vnext-fanout.js";
 import { isObservationLoss } from "../harness-runtime/lib/operation-errors.mjs";
 import { recordTechnicalNote } from "./technical-notes.js";
@@ -610,14 +611,18 @@ async function executeController(context, row, manifest, state, assertOwnership,
     };
     const capacityUncertain = (error) => error instanceof AppError && ["capacity_continuation_blocked", "operation_observation_lost"].includes(error.code) && error.details.capacity_uncertainty === true || Boolean(state.pending_capacity) && (String(error?.code) === "capacity_continuation_blocked" || isObservationLoss(error));
     const stopAfterFailure = (error) => {
+        // The published pause already fences this owner. A later observer failure
+        // must not supersede that same control with a second pause or fatal stop.
+        if (technicalPauseRequested)
+            return Promise.resolve();
         // A retained successor may already be running. Fencing/recovery records
         // uncertainty; cancellation is not evidence of its missing outcome.
         if (capacityUncertain(error))
             return Promise.resolve();
         if (retainControllerLeaseUncertainty(context, row, error))
             return Promise.resolve();
-        if (error instanceof AppError && (error.details.reconciliation_required === true || ["invocation_assignment_unproven", "invocation_outcome_pending", "invocation_receipt_timeout"].includes(error.code)) && state.current_session !== null)
-            return pauseDependency(state.sessions[state.current_session]).catch(cause => {
+        if (error instanceof AppError && error.code !== "child_work_repair_blocked" && (error.details.reconciliation_required === true || ["invocation_assignment_unproven", "invocation_outcome_pending", "invocation_receipt_timeout"].includes(error.code)) && state.current_session !== null)
+            return pauseDependency(state.sessions[state.current_session], undefined, error, "productive_continuation").catch(cause => {
                 if (!(cause instanceof AppError && cause.code === "controller_technical_dependency_paused"))
                     return stopAfterFailure(new AppError("controller_dependency_control_unavailable", "The dependency pause could not be published safely", 1, { primary: errorRecord(error), control_error: errorRecord(cause) }));
             });
@@ -674,11 +679,24 @@ async function executeController(context, row, manifest, state, assertOwnership,
         note(session, "accepted_work_native_child_failed", "native_completion", "cleanup_pending", child.terminal_turn_id);
         return false;
     });
-    const pauseDependency = async (session, sourceOperationId) => {
+    const pauseDependency = async (session, sourceOperationId, cause, protectedAction = "stage_transition") => {
         // The control intent contains the retained productive failure; it must not
         // require that same failure to disappear before the owner can pause it.
         assertPhysicalOwner();
-        note(session, "native_writer_dependency_blocked", "stage_transition", "dependency_blocked");
+        const recorded = cause ? errorRecord(cause) : { code: "native_writer_dependency_blocked", message: "Conflicting native execution has not settled" };
+        const primary = { code: String(recorded.code), message: String(recorded.message) };
+        const details = cause instanceof AppError ? cause.details : {};
+        const dependency = { primary, protected_action: protectedAction,
+            ...(typeof details.reason === "string" ? { reason: details.reason } : {}),
+            ...Object.fromEntries(["work_id", "operation_id", "refusal_invocation_id", "successor_invocation_id"].filter(key => typeof details[key] === "string").map(key => [key, details[key]])) };
+        recordTechnicalNote(context, row.project_id, row.run_id, { code: primary.code, message: primary.message,
+            phase: protectedAction, generation: row.generation, ...(state.stage ? { stage: state.stage } : {}),
+            ...(typeof details.work_id === "string" ? { work_id: details.work_id } : {}),
+            harness: runtimeHarness(session.profile), resource_identity: session.state_dir,
+            consequence: "dependency_blocked", ...(sourceOperationId ? { source_operation_id: sourceOperationId } : {}),
+            diagnostic_reference: JSON.stringify(dependency) });
+        // Diagnostic observations can race (adapter read vs lifecycle monitor), but
+        // they own one pause of this execution, not one control per error message.
         const requestId = `technical:${row.controller_id}:${row.generation}:${digest([state.stage, session.state_dir]).slice(0, 20)}`;
         const input = { projectRoot: manifest.request.project_root, runId: row.run_id, requestId, action: "pause" };
         // Publish source binding in the same SQL transaction as the control
@@ -692,13 +710,13 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 return;
             const prior = context.db.get("SELECT 1 FROM run_controller_events WHERE controller_id=? AND event_type='technical_dependency_paused' AND json_extract(data_json,'$.control_id')=? AND COALESCE(json_extract(data_json,'$.source_operation_id'),'')=?", [row.controller_id, controlId, sourceOperationId ?? ""]);
             if (!prior)
-                appendEvent(context, row.controller_id, "technical_dependency_paused", { schema_id: "dd-flow/controller-dependency@1", request_id: requestId, control_id: controlId, generation: row.generation, control: receipt, state_dir: session.state_dir, ...(sourceOperationId ? { source_operation_id: sourceOperationId } : {}) });
+                appendEvent(context, row.controller_id, "technical_dependency_paused", { schema_id: "dd-flow/controller-dependency@1", request_id: requestId, control_id: controlId, generation: row.generation, control: receipt, state_dir: session.state_dir, ...dependency, ...(sourceOperationId ? { source_operation_id: sourceOperationId } : {}) });
         });
         if (typeof intent.control_id !== "string")
             throw new AppError("controller_dependency_control_unavailable", "Technical control was not created", 1, { intent });
         technicalPauseRequested = true;
         const control = await requestRunControl(executionContext, { ...input, waitMs: 0 });
-        throw new AppError("controller_technical_dependency_paused", "Conflicting native execution requires control reconciliation before continuation", 1, { control, effect: "no_effect" });
+        throw new AppError("controller_technical_dependency_paused", "A retained dependency requires control reconciliation before continuation", 1, { control, ...dependency, effect: "no_effect" });
     };
     const confirmStopped = async (stateDir, receipt) => {
         const fail = () => new AppError("controller_native_shutdown_unproven", "The managed daemon is not proven clean and closed", 1, { state_dir: stateDir, receipt });
@@ -765,7 +783,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
             // A missing report is not a failed Stage. A real unstable source still
             // fences its dependent successor until the existing control can seal it.
             if (nextStage && ["recovery_observation_budget_exhausted", "controller_boundary_changed", "snapshot_source_changed", "owned_inventory_changed"].includes(code) && state.current_session !== null)
-                await pauseDependency(state.sessions[state.current_session]);
+                await pauseDependency(state.sessions[state.current_session], undefined, error, "boundary_capture");
         }
     };
     const reconcilePromptPredecessor = async (session) => {
@@ -775,7 +793,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
             return;
         const receipt = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false).catch(async (error) => {
             if (accepted && controllerObligationAccepted(context, row, accepted) && lateNativeFailure(error, session.id))
-                await pauseDependency(session);
+                await pauseDependency(session, undefined, error, "predecessor_settlement");
             throw error;
         });
         state.last_receipt = receipt;
@@ -786,12 +804,12 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 note(session, "accepted_boundary_settlement_pending", "native_observation", "cleanup_pending");
                 if (receipt.native_settled === true && receipt.settled === true)
                     return;
-                await pauseDependency(session);
+                await pauseDependency(session, undefined, new AppError("accepted_boundary_settlement_pending", "Accepted boundary still has an unsettled native predecessor", 1), "predecessor_settlement");
             }
             throw new AppError("settlement_reconciliation_required", "The managed Session still has an unsettled productive predecessor", 1, { session_id: session.id, settlement: current });
         }
     };
-    const prompt = async (session, text, operationId, kind, boundary = "finish", assignedWorkIds) => {
+    const prompt = async (session, text, operationId, kind, boundary = "finish", assignedWorkIds, failureResolution) => {
         const hitl = kind === "hitl";
         const pending = state.pending_capacity;
         if (pending && (pending.session_id !== session.id || pending.generation !== row.generation || pending.kind !== (kind ?? "stage") || operationId && operationId !== pending.root_operation_id))
@@ -800,6 +818,8 @@ async function executeController(context, row, manifest, state, assertOwnership,
             await reconcilePromptPredecessor(session);
         const firstOperationId = pending?.root_operation_id ?? operationId ?? `${row.controller_id}:prompt:${crypto.randomUUID()}`;
         const expectedBoundary = state.stage ? controllerObligation(context, row, state.stage, hitl ? "resume" : boundary, assignedWorkIds) : undefined;
+        if (expectedBoundary && failureResolution)
+            expectedBoundary.failure_resolution = failureResolution;
         const hitlText = async () => {
             const answerId = firstOperationId.slice(0, -`:prompt:${row.generation}`.length);
             const answer = context.db.get("SELECT input_json,receipt_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND status IN ('accepted','completed')", [answerId, row.controller_id]);
@@ -959,8 +979,11 @@ async function executeController(context, row, manifest, state, assertOwnership,
         catch (error) {
             if (!fatal && error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale", "controller_owner_mismatch"].includes(error.code))
                 throw error;
-            if (!fatal && lateNativeFailure(error, session.id))
-                await pauseDependency(session, firstOperationId);
+            if (!fatal && lateNativeFailure(error, session.id)) {
+                if (failureResolution && failureDecisionReady(failureResolution))
+                    acceptFailureDecision(executionContext, row, failureResolution, assertOwner);
+                await pauseDependency(session, firstOperationId, error, "productive_continuation");
+            }
             await stopAfterFailure(error);
             if (!capacityUncertain(error) && !(error instanceof AppError && error.code === "controller_lease_unconfirmed"))
                 cancellation.abort();
@@ -972,7 +995,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
         return receipt;
     };
     const monitor = setInterval(() => {
-        if (fatal)
+        if (fatal || technicalPauseRequested)
             return;
         try {
             checkOutcomes();
@@ -984,6 +1007,12 @@ async function executeController(context, row, manifest, state, assertOwnership,
         }
     }, 1000);
     monitor.unref();
+    const resolutionWriterSettled = async (session) => {
+        const inspected = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
+        state.last_receipt = inspected;
+        saveState(context, row, state);
+        return inspected.settled === true && !controllerNativeChildren(inspected, session.id).some(child => ["running", "unknown"].includes(child.status));
+    };
     try {
         for (;;) {
             if (technicalPauseRequested)
@@ -1007,7 +1036,17 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 const file = args?.includes("--prompt-file") ? args[args.indexOf("--prompt-file") + 1] : undefined;
                 if (!session || pending.generation !== row.generation || !file || digestBytes(fs.readFileSync(file)) !== dispatch?.prompt_sha256)
                     throw new AppError("capacity_continuation_conflict", "Retained capacity resume reference has no exact owned prompt", 1);
-                await prompt(session, fs.readFileSync(file, "utf8"), pending.root_operation_id, pending.kind === "stage" ? undefined : pending.kind);
+                await prompt(session, fs.readFileSync(file, "utf8"), pending.root_operation_id, pending.kind === "stage" ? undefined : pending.kind, dispatch?.obligation?.action ?? "finish", dispatch?.obligation?.work_ids, dispatch?.obligation?.failure_resolution);
+                continue;
+            }
+            const failureRecovery = await reconcilePendingWorkFailure(executionContext, row, state, next.kind, run.project_root, assertOwner, resolutionWriterSettled);
+            if (failureRecovery === "waiting") {
+                setStatus("waiting_for_children");
+                await delay(1000);
+                continue;
+            }
+            if (failureRecovery === "applied") {
+                saveState(context, row, state);
                 continue;
             }
             if (next.kind !== "paused" && state.current_session !== null) {
@@ -1055,6 +1094,11 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 appendEvent(context, row.controller_id, "terminal", { reason: next.reason });
                 return;
             }
+            if ((next.kind === "paused" || next.kind === "blocked") && workFailureBlockActive(executionContext, row, view.index)) {
+                setStatus("waiting_for_dependency");
+                await delay(1000, undefined, { signal: cancellation.signal });
+                continue;
+            }
             if (next.kind === "paused") {
                 setStatus("waiting_for_user");
                 const pause = view.index.stage_runs.find(stage => stage.stage === next.stage)?.pause;
@@ -1156,7 +1200,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 }
                 if (!session || transition.session_mode === "new_session" || !sameSessionProfile(session.profile, transition.coordinator) || path.resolve(session.cwd) !== stageCwd) {
                     if (session && !await retireSession(session))
-                        await pauseDependency(session);
+                        await pauseDependency(session, undefined, new AppError("native_session_cleanup_pending", "Retired Session still prevents conflicting workspace reuse", 1), "stage_transition");
                     await renewLease();
                     assertOwner();
                     const directory = path.join(row.state_dir, `session-${state.sessions.length + 1}`);
@@ -1437,12 +1481,16 @@ async function executeController(context, row, manifest, state, assertOwnership,
                         repairBlockedWorks.push(workId);
                         recordTechnicalNote(context, row.project_id, row.run_id, { code: "child_work_repair_blocked", message: blocker.message,
                             phase: "work_repair", generation: row.generation, stage: next.stage, work_id: workId, harness: childHarness,
-                            resource_identity: workId, consequence: "dependency_blocked", diagnostic_reference: String(blocker.details.reason) });
+                            resource_identity: workId, consequence: "dependency_blocked", diagnostic_reference: JSON.stringify({
+                                protected_action: "work_finish", reason: blocker.details.reason, primary: blocker.details.primary_error,
+                                refusal_invocation_id: blocker.details.refusal_invocation_id, successor_invocation_id: blocker.details.successor_invocation_id,
+                                operation_id: blocker.details.operation_id
+                            }) });
                     }
                 }
             }
             const memoryFlow = ["mb-init", "mb-upgrade", "mb-fix", "interactive"].includes(run.flow_kind) || isSourceSnapshotFlow(run.flow_kind) || routing.kind === "descriptor" && isDeliveryFlow(run.flow_kind);
-            const fanoutInput = { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles, dispatchFence: retainedFailures.length > 0, repairBlockedWorks };
+            const fanoutInput = { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles, dispatchFence: retainedFailures.length > 0, repairBlockedWorks, ...(state.work_failure?.deferred ? { deferredFailure: state.work_failure.work_id } : {}) };
             const fanout = memoryFlow ? await runControllerMemoryTask(executionContext, { operation: "fanout", input: fanoutInput }, cancellation.signal)
                 : await nextControllerFanout(executionContext, fanoutInput);
             if (memoryFlow)
@@ -1474,6 +1522,43 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     throw new AppError(cause.code, cause.message, 1, { ...cause.details, ...(cause.invocation_id ? { invocation_id: cause.invocation_id } : {}), ...(cause.hook_event_id ? { hook_event_id: cause.hook_event_id } : {}), controller_wrapper: "incomplete_subject_turn", stage: next.stage });
                 throw new AppError("incomplete_subject_turn", "Managed Turn ended without a completed Stage or declared continuation", 1, { stage: next.stage });
             }
+            if (fanout.kind === "failure") {
+                const resolution = state.work_failure ?? prepareWorkFailureResolution(executionContext, row, next.stage, fanout.failure);
+                if (resolution.work_id !== fanout.failure.work_id || resolution.work_session_id !== fanout.failure.work_session_id)
+                    throw new AppError("work_failure_scope_changed", "Pending resolution belongs to another failed attempt", 1);
+                state.work_failure = resolution;
+                saveState(context, row, state);
+                while (!failureDecisionReady(resolution)) {
+                    const attempt = state.work_failure.submission_attempt ?? 0;
+                    if (attempt >= 2)
+                        await pauseDependency(session, undefined, new AppError("work_failure_decision_invalid", "Coordinator did not submit a valid bound failure decision", 1, workFailureDiagnostic(resolution)), "work_failure_resolution");
+                    await prompt(session, workFailureResolutionPrompt(resolution, state.work_failure.submission_diagnostic), `${row.controller_id}:failure-resolution:${digest([resolution.accepted_file, attempt, row.generation])}`, undefined, "failure_resolution", undefined, resolution);
+                    try {
+                        readFailureDecision(resolution);
+                    }
+                    catch (error) {
+                        state.work_failure.submission_diagnostic = error instanceof Error ? error.message : String(error);
+                    }
+                    state.work_failure.submission_attempt = attempt + 1;
+                    saveState(context, row, state);
+                }
+                const decision = acceptFailureDecision(executionContext, row, resolution, assertOwner);
+                if (decision.action === "block" && fanout.ready) {
+                    state.work_failure.deferred = true;
+                    saveState(context, row, state);
+                    continue;
+                }
+                if (!await resolutionWriterSettled(session)) {
+                    setStatus("waiting_for_children");
+                    await delay(1000);
+                    continue;
+                }
+                applyWorkFailureDecision(executionContext, row, resolution, decision, run.project_root, assertOwner);
+                delete state.work_failure;
+                state.last_continuation = null;
+                saveState(context, row, state);
+                continue;
+            }
             if (fanout.kind === "wait") {
                 if (fanout.reason === "accepted_work_native_cleanup") {
                     const pending = children.filter(child => ["running", "unknown"].includes(child.status) && acceptedChildWork(context, row, childHarness, session.id, child.session_id));
@@ -1482,20 +1567,20 @@ async function executeController(context, row, manifest, state, assertOwnership,
                         try {
                             await call(session, ["session", "cancel", "--session-id", child.session_id, ...sessionArguments(context, manifest, session)], false);
                         }
-                        catch {
-                            await pauseDependency(session);
+                        catch (error) {
+                            await pauseDependency(session, undefined, error, "accepted_child_retirement");
                         }
                     }
                     const operationId = `${row.controller_id}:child-retirement:${crypto.randomUUID()}`;
                     const observed = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false, operationId).catch(async (error) => {
                         if (lateNativeFailure(error, session.id))
-                            await pauseDependency(session);
+                            await pauseDependency(session, operationId, error, "accepted_child_retirement");
                         throw error;
                     });
                     state.last_receipt = observed;
                     saveState(context, row, state);
                     if (!acceptedChildrenRetired(pending.map(child => child.session_id), observed, session.id, operationId))
-                        await pauseDependency(session);
+                        await pauseDependency(session, operationId, new AppError("accepted_child_retirement_unconfirmed", "Accepted child results are retained but native retirement remains unconfirmed", 1), "accepted_child_retirement");
                     continue;
                 }
                 setStatus(fanout.reason === "qualified_capacity_required" ? "waiting_for_capacity" : "waiting_for_children");
@@ -1551,7 +1636,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 if (rejected)
                     throw fatal ?? rejected.reason;
                 if (cleanupConflict)
-                    await pauseDependency(session);
+                    await pauseDependency(session, undefined, new AppError("external_work_cleanup_pending", "Accepted external Work still has an unretired workspace writer", 1), "workspace_reuse");
                 state.last_continuation = null;
                 saveState(context, row, state);
                 continue;

package/dist/services/vnext-code.js

@@ -1,5 +1,5 @@
 import { managedLifecycleCommand } from "./lifecycle-invocations.js";
-import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { stageLifecycleInstruction, workStopConditionInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 import { ensureAggregateRepair, ensureRepairIntent } from "./repair-intents.js";
 import { runWorkspaceBootstrap } from "./workspace-bootstrap.js";
 import crypto from "node:crypto";
@@ -546,6 +546,8 @@ export function coordinatorPrompt(context, input) {
         "</code_graph>",
         "",
         "<execution_commands>",
+        workStopConditionInstruction,
+        "An explicit child work fail ends that attempt, not automatically the Stage. The controller supplies a bound failure-resolution packet; submit its requested decision without inventing a retry, mutating runtime state or replaying accepted predecessors.",
         "Do not choose a provider delegation tool from this stage prompt. At each work_fanout boundary, stop at the Work-graph boundary; the shared controller supplies the selected adapter's native tool, exact parameters, child task, and wait contract. It launches only entries listed in graph.ready and uses at most the qualified capacity. Every registered CODE Work runs in a fresh child Session, including a serial dependency chain. The coordinator launches those children only through the controller-supplied native delegation instruction; it must never invoke a Work start_command itself. Each child receives its complete packet from dd-flow and runs its own exact start_command. After a Work finishes, the controller uses the graph returned by work finish to launch newly ready Work. To refresh the parent graph yourself use the exact command: " + runtimeCommand(context, ["work", "ls", "--run", input.run.id, "--ready", "--project-root", input.projectRoot, "--json"]),
         "A quiet child is still running until the harness reports its turn completed, failed, cancelled or explicitly needs attention. An elapsed nominal wait, silence, or no new artifact is not an unresponsive-worker failure. Never interrupt, replace, relaunch, or stage-block a still-running child for that reason, even if an external controller asks. Long work finish and stage finish commands emit check progress on stderr. After you issue the exact CODE stage finish command, wait for that same command to return once: a completed command with a non-zero exit and structured `code_gate_failed` output is its terminal result, not a reason to keep waiting. A repair_required continuation already registered the repair: end this Turn. Do not invoke that Work's start_command from the coordinator Session, inspect its PID, start a second finish command, or infer failure from quiet output. Close a disposable child only after its Work is accepted or explicitly failed/cancelled and the harness reports the turn settled.",
         `A repairable engine, harness, or environment failure is not a user question. Write the evidence summary to ${path.join(requireHome(input.run), "works", input.rootWork.work_id, "block-summary.md")}, then record it with a separate command: ${runtimeCommand(context, ["stage", "block", input.run.id, "--stage", "code", "--work", input.rootWork.work_id, "--kind", "<engine|harness|environment>", "--code", "<stable-code>", "--summary-file", `@run/works/${input.rootWork.work_id}/block-summary.md`, "--retryable", "--project-root", input.projectRoot, "--json"])}. Choose kind and stable-code from evidence; this example is not an executable continuation. Repair it externally, then run the exact unblock_command returned by dd-flow and continue this same stage.`,

package/dist/services/vnext-plan-review.js

@@ -21,7 +21,7 @@ import { currentStagePrompt, applyExternalStageContext, prepareExternalStageCont
 import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
 import { getStageFanoutCapacity, readFanoutDescriptor, subagentCapacityKey, writeFanoutDescriptor } from "./vnext-fanout.js";
 import { stageGraphScope } from "./stage-work-graph.js";
-import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { stageLifecycleInstruction, workStopConditionInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, latestRunVerificationMatrix } from "./verification-matrix.js";
 import { reviewerSourceInputs, reviewerSourceInstruction } from "./review-copy.js";
 import { reviewDefEvidence } from "./review-deferral.js";
@@ -366,7 +366,7 @@ function orchestratorPrompt(context, input) {
     const decision = path.join(input.root, "decision.json");
     const workspaceContract = ["<workspace_contract>", `- route: ${input.workspaceRoute.route}`, `- feature branch: ${input.workspaceRoute.feature_branch ?? "not applicable"}`, `- base commit: ${input.workspaceRoute.base_ref ?? "not applicable"}`, `- read/write workspace: ${input.run.workspace_root}`, "The CLI verified this frozen route. All plan and correction writes belong in the named workspace; project root remains only the stable lifecycle identity. Do not create, switch, merge or delete branches/worktrees.", "</workspace_contract>"].join("\n");
     const acceptanceOwnership = "For every deferred acceptance or document update, identify the named CODE Work owner, its causal checks, and when it can truthfully close the obligation. Aggregate checks run only after implementation Work completes: assign a CODE owner to pending documents and use CODE needs_checks → verification_required → repair after those receipts. A promise that MERGE or an unnamed readiness owner will finish acceptance is a material PLAN finding; bootstrap workspace readiness is not proof of the new feature.";
-    const template = [acceptanceOwnership, planCheckInstruction,
+    const template = [acceptanceOwnership, planCheckInstruction, workStopConditionInstruction, "Review stop_conditions semantically: reject conditions that veto the requested change merely because the baseline differs, turn planned paths into ownership, or expand one unsupported evidence operation into a prohibition on all implementation. Preserve real safety, accepted-decision and required-evidence boundaries.",
         `The accepted check profile is ${path.join(input.run.workspace_root, ".memory-bank", "spec", "engineering", "code-check-profile.json")}. A new check required by a correction is planned, not available: name its provider Work and order consumers after that Work.`,
         input.template].join("\n\n");
     const reviewerLaunch = capacity.source === "external_policy"

package/dist/services/vnext-plan.js

@@ -21,7 +21,7 @@ import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { acceptStageReport, prepareStageReport } from "./stage-report-renderer.js";
 import { currentStagePrompt, applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { subagentCapacityKey } from "./vnext-fanout.js";
-import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { stageLifecycleInstruction, workStopConditionInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, verificationMatrixInstruction } from "./verification-matrix.js";
 import { stageSuccessor } from "./vnext-contracts.js";
 export function isVnextPlanRun(context, input) {
@@ -109,7 +109,7 @@ export function startVnextPlan(context, input, prepared = prepareVnextPlanStart(
                 ? [`This RUN must reach MERGE. Project policy already supplies the mandatory merge gate${policyMergeAliases.length === 1 ? "" : "s"}: ${policyMergeAliases.join(", ")}. Do not duplicate them in semantic checks[]. Add another merge check only when the task genuinely needs additional evidence.`]
                 : ["This RUN must reach MERGE and project policy supplies no merge gate. Select at least one real top-level checks[] entry with run_at: merge. It may use an existing project alias or a planned alias materialised by a named P* provider Work. This is a planning obligation: do not defer it to CODE-REVIEW or MERGE."]), "The CLI validates the effective merge gate but never invents one or migrates an incompatible project policy.", "</merge_gate_contract>", ""]
         : [];
-    const prompt = ["<stage_identity>", `- RUN: ${run.id}`, `- Work: ${planWorkId}`, "- stage: plan", "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility or permission discovery.", `- Project root: ${projectRoot}`, `- Workspace: ${run.workspace_root}`, `- Stage workspace: ${root}`, `- Git: ${JSON.stringify(git)}`, capacityContext, "</trusted_runtime_context>", "", "<workspace_contract>", `- route: ${workspaceRoute.route}`, `- feature branch: ${workspaceRoute.feature_branch ?? "not applicable"}`, `- base commit: ${workspaceRoute.base_ref ?? "not applicable"}`, `- write workspace: ${run.workspace_root}`, "The CLI has verified this frozen route. All project reads and writes for PLAN and later CODE happen in the write workspace; project root is only the stable runtime identity for lifecycle commands. Do not create, switch, merge or delete branches/worktrees.", "Keep the task runner's current cwd. Use the absolute paths in this packet instead of trying to set the provisioned workspace as a tool workdir.", "</workspace_contract>", "", "<accepted_inputs>", `- ${path.join(home, "01-specify", "specify.json")}`, `- ${path.join(home, "02-protocolize", "protocolize-result.json")}`, ...protocols.map((id) => `- ${path.join(run.workspace_root, ".memory-bank", "protocol", id, "summary.md")}`), "</accepted_inputs>", "", ...(codeCheckProfile ? ["<code_check_policy>", "You, not the CLI, select evidence for every accepted requirement and acceptance criterion. The profile only lists reusable aliases, mandatory project policy gates and guarded raw command prefixes. Inspect relevant package/test manifests before choosing a check. Do not classify checks by weight and do not omit a needed check because it looks expensive.", JSON.stringify(codeCheckProfile, null, 2), "</code_check_policy>", ""] : []), ...mergeContract, "<artifacts>", "The CLI has already materialized every artifact below as a partially filled draft. Edit these files in place; do not create replacements elsewhere.", "Prefilled and CLI-owned plan fields: schema_id, plan_id, protocol_id, initial revision and source_refs.", "Prefilled and CLI-owned aspect-map fields: schema_id, protocol_id, plan_id, plan revision, catalog_ref and every catalog aspect_id.", "You own the remaining semantic fields. Empty or missing semantic values are intentional draft markers and must be completed before validation.", ...planPaths.map((value) => `- partially filled plan: ${value}`), ...mapPaths.map((value) => `- partially filled aspect map: ${value}`), "</artifacts>", "", "<output_contract>", "Complete every named plan and aspect map in place. Do not create or edit code-work-batch.json: dd-flow derives it after validation.", "The CLI owns schema_id, plan_id, protocol_id, revision and source_refs. Preserve them exactly.", planCheckInstruction, "For each R-* and AC-*, choose an actually relevant proof: an existing focused test, a new planned alias plus its provider Work, a project policy gate, or an autonomous executable check. Every plan item needs at least one check_ref. The CLI validates ids, provider ordering, materialization and guarded command policy; it never chooses a check for you. A provider Work may verify itself with the alias it has just created. A consumer must depend on that provider.", "Each check must terminate and return an exit status. Never declare a bare dev/start/serve/watch service command as a check; use a finite test that manages its own service lifecycle (for example, a browser test with a webServer fixture).", "Each plan item must name concrete existing source/test paths in required_read. planned_write_areas is optional: use stable component directories or files only when they help coordinate parallel Work; it is never a write allowlist. Reference every owned R-* and AC-* in one or more items; every AC-* needs an observable acceptance proof.", "For every selected check, inspect its command's launch path and the runtime entrypoints it starts. The fixture/reset process, service process and client process must observe one intended environment and data world. If a required runtime entrypoint needs a code change, make that change explicit in the Work task and its verification. Use planned_write_areas only to advertise likely concurrent overlap; do not treat it as ownership or assume another Work will repair an omitted change. If an independent infrastructure Work is clearer, plan that Work explicitly and order consumers after it.", reviewGroupingRule, "Complete compact contract and schema paths:", `- protocol plan schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "vnext-protocol-plan.schema.json")}`, `- aspect map schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "plan-aspect-map.schema.json")}`, "Minimal valid protocol-plan shape:", "```json", JSON.stringify(planExample(protocols[0]), null, 2), "```", "Minimal valid aspect-map shape:", "```json", JSON.stringify(aspectMapExample(protocols[0]), null, 2), "```", "</output_contract>", "", "<execution_commands>", "PLAN never launches independent reviewers or registers CODE Work.", "If PLAN needs a material user decision with no reasonable default, write the question packet to the named text file, then run the separate standalone lifecycle command below. Do not combine file creation and dd-flow in one shell command:", "```sh", pauseCommandTemplate, "```", "Ask the returned user_message, stop, and resume this same PLAN Work with the exact returned command.", "Validate both partially filled drafts after completing their semantic fields:", ...validationCommands.map((command) => `- ${command}`), "Finish PLAN only after all questions are resolved and both validation commands pass:", finishCommand, "The response returns the only PLAN-REVIEW start command. Follow it; do not start CODE directly.", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
+    const prompt = ["<stage_identity>", `- RUN: ${run.id}`, `- Work: ${planWorkId}`, "- stage: plan", "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility or permission discovery.", `- Project root: ${projectRoot}`, `- Workspace: ${run.workspace_root}`, `- Stage workspace: ${root}`, `- Git: ${JSON.stringify(git)}`, capacityContext, "</trusted_runtime_context>", "", "<workspace_contract>", `- route: ${workspaceRoute.route}`, `- feature branch: ${workspaceRoute.feature_branch ?? "not applicable"}`, `- base commit: ${workspaceRoute.base_ref ?? "not applicable"}`, `- write workspace: ${run.workspace_root}`, "The CLI has verified this frozen route. All project reads and writes for PLAN and later CODE happen in the write workspace; project root is only the stable runtime identity for lifecycle commands. Do not create, switch, merge or delete branches/worktrees.", "Keep the task runner's current cwd. Use the absolute paths in this packet instead of trying to set the provisioned workspace as a tool workdir.", "</workspace_contract>", "", "<accepted_inputs>", `- ${path.join(home, "01-specify", "specify.json")}`, `- ${path.join(home, "02-protocolize", "protocolize-result.json")}`, ...protocols.map((id) => `- ${path.join(run.workspace_root, ".memory-bank", "protocol", id, "summary.md")}`), "</accepted_inputs>", "", ...(codeCheckProfile ? ["<code_check_policy>", "You, not the CLI, select evidence for every accepted requirement and acceptance criterion. The profile only lists reusable aliases, mandatory project policy gates and guarded raw command prefixes. Inspect relevant package/test manifests before choosing a check. Do not classify checks by weight and do not omit a needed check because it looks expensive.", JSON.stringify(codeCheckProfile, null, 2), "</code_check_policy>", ""] : []), ...mergeContract, "<artifacts>", "The CLI has already materialized every artifact below as a partially filled draft. Edit these files in place; do not create replacements elsewhere.", "Prefilled and CLI-owned plan fields: schema_id, plan_id, protocol_id, initial revision and source_refs.", "Prefilled and CLI-owned aspect-map fields: schema_id, protocol_id, plan_id, plan revision, catalog_ref and every catalog aspect_id.", "You own the remaining semantic fields. Empty or missing semantic values are intentional draft markers and must be completed before validation.", ...planPaths.map((value) => `- partially filled plan: ${value}`), ...mapPaths.map((value) => `- partially filled aspect map: ${value}`), "</artifacts>", "", "<output_contract>", "Complete every named plan and aspect map in place. Do not create or edit code-work-batch.json: dd-flow derives it after validation.", "The CLI owns schema_id, plan_id, protocol_id, revision and source_refs. Preserve them exactly.", planCheckInstruction, workStopConditionInstruction, "For each R-* and AC-*, choose an actually relevant proof: an existing focused test, a new planned alias plus its provider Work, a project policy gate, or an autonomous executable check. Every plan item needs at least one check_ref. The CLI validates ids, provider ordering, materialization and guarded command policy; it never chooses a check for you. A provider Work may verify itself with the alias it has just created. A consumer must depend on that provider.", "Each check must terminate and return an exit status. Never declare a bare dev/start/serve/watch service command as a check; use a finite test that manages its own service lifecycle (for example, a browser test with a webServer fixture).", "Each plan item must name concrete existing source/test paths in required_read. planned_write_areas is optional: use stable component directories or files only when they help coordinate parallel Work; it is never a write allowlist. Reference every owned R-* and AC-* in one or more items; every AC-* needs an observable acceptance proof.", "For every selected check, inspect its command's launch path and the runtime entrypoints it starts. The fixture/reset process, service process and client process must observe one intended environment and data world. If a required runtime entrypoint needs a code change, make that change explicit in the Work task and its verification. Use planned_write_areas only to advertise likely concurrent overlap; do not treat it as ownership or assume another Work will repair an omitted change. If an independent infrastructure Work is clearer, plan that Work explicitly and order consumers after it.", reviewGroupingRule, "Complete compact contract and schema paths:", `- protocol plan schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "vnext-protocol-plan.schema.json")}`, `- aspect map schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "plan-aspect-map.schema.json")}`, "Minimal valid protocol-plan shape:", "```json", JSON.stringify(planExample(protocols[0]), null, 2), "```", "Minimal valid aspect-map shape:", "```json", JSON.stringify(aspectMapExample(protocols[0]), null, 2), "```", "</output_contract>", "", "<execution_commands>", "PLAN never launches independent reviewers or registers CODE Work.", "If PLAN needs a material user decision with no reasonable default, write the question packet to the named text file, then run the separate standalone lifecycle command below. Do not combine file creation and dd-flow in one shell command:", "```sh", pauseCommandTemplate, "```", "Ask the returned user_message, stop, and resume this same PLAN Work with the exact returned command.", "Validate both partially filled drafts after completing their semantic fields:", ...validationCommands.map((command) => `- ${command}`), "Finish PLAN only after all questions are resolved and both validation commands pass:", finishCommand, "The response returns the only PLAN-REVIEW start command. Follow it; do not start CODE directly.", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
     const artifactMaterialization = { status: "materialized", completeness: "partially_filled", plan_paths: planPaths, aspect_map_paths: mapPaths, cli_owned_plan_fields: ["schema_id", "plan_id", "protocol_id", "revision", "source_refs"], cli_owned_aspect_map_fields: ["schema_id", "protocol_id", "plan_id", "plan_revision", "catalog_ref", "aspects[].aspect_id"], validation_commands: validationCommands };
     const promptPath = path.join(root, "stage-prompt.md");
     // This explicit final rule supersedes historical pack wording: a flow gate
@@ -326,7 +326,7 @@ export function validateVnextCodeHandoff(context, input) {
     });
 }
 const planTask = "Produce accepted plan.json and aspect-map.json artifacts.";
-function planExample(protocolId) { return { schema_id: "dd-flow/protocol-plan@6", plan_id: "PLAN-001", protocol_id: protocolId, revision: 1, title: "Example", summary: "A compact executable plan.", source_refs: [{ kind: "specify", id: "SPECIFY", path: "run://RUN-000/01-specify/specify.json", requirement_ids: ["R-001", "AC-001"] }], goal: { outcome: "Deliver the accepted behavior.", constraints: ["Keep the accepted scope."], non_goals: [] }, assessment: { scope_breadth: { level: "narrow", surfaces: ["one surface"], reason: "One vertical slice." }, solution_novelty: { level: "established", surfaces: ["existing pattern"], reason: "Reuse project practice." }, solution_uncertainty: { level: "low", surfaces: ["known behavior"], reason: "No open technical question." }, failure_impact: { level: "low", surfaces: ["local feature"], reason: "Reversible local change." }, selected_depth: "compact_plan", depth_trigger: "none" }, decisions: [], document_updates: [], checks: [{ id: "CHK-P1-TEST", command: "pnpm test", purpose: "Proves the changed behavior.", run_at: "work", availability: "available" }], items: [{ id: "P1", title: "Implement behavior", summary: "Change the owning surface.", details: "Follow the accepted requirement and project conventions.", depends_on: [], requirement_refs: ["R-001", "AC-001"], semantic_spine: { user_outcome: "The requested behavior is available.", component_responsibility: "Own the behavior.", must_preserve: ["Existing behavior."], non_goals: [], acceptance_contribution: "Makes AC-001 observable." }, execution_context: { required_read: ["apps/api/src/example.ts"], discovery_boundary: ["Related tests only."], planned_write_areas: ["apps/api/src/"], stop_conditions: ["Stop if accepted scope conflicts with current truth."] }, verification: { check_refs: ["CHK-P1-TEST"] } }], acceptance: [{ criterion_id: "AC-001", plan_item_ids: ["P1"], changed_surfaces: ["apps/api/src/example.ts"], path: "Exercise the accepted user path.", environment: "Local test environment.", fixtures: [], cleanup: "No persistent fixture.", check_refs: ["CHK-P1-TEST"], expected_evidence: ["Focused check passes."], proof_limits: ["Manual production evidence is not claimed."], gate: "work" }] }; }
+function planExample(protocolId) { return { schema_id: "dd-flow/protocol-plan@6", plan_id: "PLAN-001", protocol_id: protocolId, revision: 1, title: "Example", summary: "A compact executable plan.", source_refs: [{ kind: "specify", id: "SPECIFY", path: "run://RUN-000/01-specify/specify.json", requirement_ids: ["R-001", "AC-001"] }], goal: { outcome: "Deliver the accepted behavior.", constraints: ["Keep the accepted scope."], non_goals: [] }, assessment: { scope_breadth: { level: "narrow", surfaces: ["one surface"], reason: "One vertical slice." }, solution_novelty: { level: "established", surfaces: ["existing pattern"], reason: "Reuse project practice." }, solution_uncertainty: { level: "low", surfaces: ["known behavior"], reason: "No open technical question." }, failure_impact: { level: "low", surfaces: ["local feature"], reason: "Reversible local change." }, selected_depth: "compact_plan", depth_trigger: "none" }, decisions: [], document_updates: [], checks: [{ id: "CHK-P1-TEST", command: "pnpm test", purpose: "Proves the changed behavior.", run_at: "work", availability: "available" }], items: [{ id: "P1", title: "Implement behavior", summary: "Change the owning surface.", details: "Follow the accepted requirement and project conventions.", depends_on: [], requirement_refs: ["R-001", "AC-001"], semantic_spine: { user_outcome: "The requested behavior is available.", component_responsibility: "Own the behavior.", must_preserve: ["Existing behavior."], non_goals: [], acceptance_contribution: "Makes AC-001 observable." }, execution_context: { required_read: ["apps/api/src/example.ts"], discovery_boundary: ["Related tests only."], planned_write_areas: ["apps/api/src/"], stop_conditions: [] }, verification: { check_refs: ["CHK-P1-TEST"] } }], acceptance: [{ criterion_id: "AC-001", plan_item_ids: ["P1"], changed_surfaces: ["apps/api/src/example.ts"], path: "Exercise the accepted user path.", environment: "Local test environment.", fixtures: [], cleanup: "No persistent fixture.", check_refs: ["CHK-P1-TEST"], expected_evidence: ["Focused check passes."], proof_limits: ["Manual production evidence is not claimed."], gate: "work" }] }; }
 function aspectMapExample(protocolId) { return { $schema: "plan-aspect-map.schema.json", schema_id: "dd-flow/plan-aspect-map@3", protocol_id: protocolId, plan_id: "PLAN-001", plan_revision: 1, catalog_ref: { path: ".memory-bank/dd-flow/mb-sdlc/plan-aspects/aspects" }, routing: { initial_state: "orchestrator_local", selected_route: "local_compact", reason: "One genuinely small semantic unit.", groups: [] }, review_groups: [], aspects: [{ aspect_id: "example_aspect", applicability: "not_applicable", reason: "Only an example; use the supplied real catalog.", planned_artifact_refs: [] }] }; }
 function requireRun(context, root, id) { const project = requireProjectByRoot(context, root); const run = context.db.get("SELECT id, project_id, workspace_root, run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, id]); if (!run)
     throw new AppError("not_found", "RUN is not registered", 1); return run; }

package/dist/services/work-registry.js

@@ -37,7 +37,8 @@ import { publicSessionIdentity } from "./session-identity.js";
 import { activateRecoveryWork, assertRecoveryHookCurrent, assertRunMutationAllowed, assertWorkSettlementAllowed, recoveryGuard, recoveryPromptForWork, settleRecoveryWork } from "./run-recovery.js";
 import { runControlDirective } from "./run-control.js";
 import { prepareError, prepareJsonFile } from "../cli/input-preparation.js";
-import { lifecycleRetryInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { lifecycleRetryInstruction, workStopConditionInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { prepareRetryCorrection, prepareExternalRetry, renderRetryCorrection, retryCorrectionFile, retryReceiptFile } from "./work-retry-context.js";
 import { acceptedDecisionPrecedence, loadExternalStageContext, renderRetainedStageContext, renderRunOperationalContext, runContextRelocations } from "./stage-context.js";
 import { reviewEnvironmentAllowed, reviewExecutionCopyHash, reviewSourceHash, reviewSourcePaths } from "./review-copy.js";
 import { latestRunVerificationMatrix, verificationMatrixInstruction, verificationMatrixContract } from "./verification-matrix.js";
@@ -948,7 +949,7 @@ export function startBoundWork(context, work, run, claimIdentity, hookEventId, s
     const finishMarker = `DD_FLOW_FINISH_${crypto.randomUUID()}`;
     const failMarker = `DD_FLOW_FAIL_${crypto.randomUUID()}`;
     const workspaceView = preparedCopy ? { work_id: work.work_id, from: run.workspace_root, to: reviewInputPath(requireRunHome(run), preparedCopy.copy.root), source_sha256: preparedCopy.copy.source_sha256, copy_sha256: preparedCopy.copy.sha256 } : undefined;
-    let promptTemplate = renderWorkerPrompt(context, work, workerRun, preparedDependencies, { finish: finishMarker, fail: failMarker }, workspaceView, preparedReviewInput ?? undefined);
+    let promptTemplate = `${renderRetryCorrection(context, work, requireRunHome(run))}${renderWorkerPrompt(context, work, workerRun, preparedDependencies, { finish: finishMarker, fail: failMarker }, workspaceView, preparedReviewInput ?? undefined)}`;
     if (preparedRecovery)
         promptTemplate = `${recoveryPrompt(preparedRecovery)}\n\n${promptTemplate}`;
     let binding;
@@ -1249,7 +1250,7 @@ export function prepareWorkSettlement(context, id, status, result) {
         throw new AppError("work_start_publication_pending", "Finish publishing this Work's committed start packet before settlement", 1, { work_id: work.work_id, effect: "no_effect" });
     return { work, run, link };
 }
-export function prepareWorkRetry(context, id, reason) {
+export function prepareWorkRetry(context, id, reason, correction) {
     if (typeof reason !== "string" || !reason.trim())
         throw new AppError("usage", "Work retry requires a nonempty --reason", 2);
     const work = requireWork(context, id);
@@ -1269,17 +1270,24 @@ export function prepareWorkRetry(context, id, reason) {
             throw new AppError("work_retry_invalid", "Retry journal is not valid JSON", 1);
         }
         const item = value;
-        if (!item || typeof item !== "object" || item.work_id !== work.work_id || typeof item.archive !== "string" || !/^ATT-\d{3,}$/.test(item.archive) || !Array.isArray(item.entries) || item.entries.some(file => !["prompt.md", "result.json", "context.json", "result-input.json"].includes(file)) || new Set(item.entries).size !== item.entries.length || !(item.result_sha256 === null || typeof item.result_sha256 === "string" && /^[a-f0-9]{64}$/.test(item.result_sha256)))
+        if (!item || typeof item !== "object" || item.work_id !== work.work_id || typeof item.archive !== "string" || !/^ATT-\d{3,}$/.test(item.archive) || !Array.isArray(item.entries) || item.entries.some(file => !["prompt.md", "result.json", "context.json", "result-input.json", retryCorrectionFile, retryReceiptFile].includes(file)) || new Set(item.entries).size !== item.entries.length || !(item.result_sha256 === null || typeof item.result_sha256 === "string" && /^[a-f0-9]{64}$/.test(item.result_sha256))
+            || item.correction && (item.correction.work_id !== work.work_id || item.correction.project_id !== work.project_id || item.correction.run_id !== work.run_id || item.correction.failed_result_sha256 !== item.result_sha256)
+            || item.external_launch && (item.external_launch.work_id !== work.work_id || typeof item.external_launch.operation_id !== "string" || typeof item.external_launch.state_dir !== "string" || !path.isAbsolute(item.external_launch.state_dir)))
             throw new AppError("work_retry_invalid", "Retry journal does not identify this Work", 1);
         pending = item;
     }
+    if (pending?.correction && correction && (pending.correction.episode_id !== correction.episode_id || pending.correction.correction !== correction.correction || pending.correction.failed_result_sha256 !== correction.failed_result_sha256 || pending.correction.decision_ref !== fs.realpathSync(correction.decision_ref)))
+        throw new AppError("work_retry_conflict", "Pending retry belongs to another retained correction", 1);
+    if (pending && !pending.correction && correction)
+        throw new AppError("work_retry_conflict", "Cannot add a correction to an already prepared retry", 1);
     if (work.status !== "failed" && !(pending && work.status === "created"))
         throw new AppError("invalid_work_state", "Only failed Work may be retried", 2);
     const attempts = path.join(directory, "attempts");
     let number = 1;
     while (fs.existsSync(path.join(attempts, `ATT-${String(number).padStart(3, "0")}`)))
         number += 1;
-    const prepared = pending ?? { work_id: work.work_id, archive: `ATT-${String(number).padStart(3, "0")}`, entries: ["prompt.md", "result.json", "context.json", "result-input.json"].filter(file => fs.existsSync(path.join(directory, file))), result_sha256: work.result === null ? null : crypto.createHash("sha256").update(work.result).digest("hex") };
+    const prepared = pending ?? { work_id: work.work_id, archive: `ATT-${String(number).padStart(3, "0")}`, entries: ["prompt.md", "result.json", "context.json", "result-input.json", retryCorrectionFile, retryReceiptFile].filter(file => fs.existsSync(path.join(directory, file))), result_sha256: work.result === null ? null : crypto.createHash("sha256").update(work.result).digest("hex"),
+        ...(correction ? { correction: prepareRetryCorrection(correction, work, requireRunHome(run)) } : {}), external_launch: prepareExternalRetry(context, work) };
     const archive = path.join(attempts, prepared.archive);
     if (work.status === "failed") {
         if (prepared.result_sha256 !== (work.result === null ? null : crypto.createHash("sha256").update(work.result).digest("hex")))
@@ -1294,16 +1302,36 @@ export function prepareWorkRetry(context, id, reason) {
             if (!fs.existsSync(source) && !fs.existsSync(target))
                 throw new AppError("archive_artifact_missing", "Work artifact is absent from both retry locations", 1, { source, target });
         }
+        if (prepared.external_launch) {
+            const external = prepareExternalRetry(context, work);
+            if (JSON.stringify(external) !== JSON.stringify(prepared.external_launch))
+                throw new AppError("work_retry_conflict", "Previous external launch changed while retry was prepared", 1);
+            const file = path.join(archive, "external-launch.json");
+            if (fs.existsSync(file) && fs.readFileSync(file, "utf8") !== JSON.stringify(prepared.external_launch))
+                throw new AppError("work_retry_conflict", "Archived external launch differs from the failed attempt", 1);
+        }
     }
     return { work, run, directory, journal, pending, prepared, archive };
 }
-export function retryWork(context, id, reason) {
+export function retryWork(context, id, reason, correction) {
     const pending = requireWork(context, id);
+    const priorReceipt = path.join(requireRunHome(requireRun(context, pending.project_id, pending.run_id)), "works", pending.work_id, retryReceiptFile);
+    if (correction && pending.status !== "failed" && fs.existsSync(priorReceipt) && !fs.existsSync(path.join(path.dirname(priorReceipt), ".retry.json"))) {
+        const retained = JSON.parse(fs.readFileSync(priorReceipt, "utf8"));
+        const current = context.db.get("SELECT current_start_invocation_id FROM works WHERE work_id=?", [pending.work_id]);
+        if (retained.episode_id === correction.episode_id && retained.failed_result_sha256 === correction.failed_result_sha256 && retained.current_start_invocation_id === current?.current_start_invocation_id) {
+            const source = JSON.parse(fs.readFileSync(path.join(path.dirname(priorReceipt), retryCorrectionFile), "utf8"));
+            if (source.correction !== correction.correction || source.decision_ref !== fs.realpathSync(correction.decision_ref))
+                throw new AppError("work_retry_conflict", "Applied retry belongs to a different retained correction", 1);
+            renderRetryCorrection(context, pending, requireRunHome(requireRun(context, pending.project_id, pending.run_id)));
+            return { ok: true, ...retained, reason, idempotent: true };
+        }
+    }
     // A committed failed result must be published (or diagnosed) before its
     // live path can be archived for the next attempt.
     materializePendingWorkResults(context, pending.project_id, pending.run_id, pending.work_id);
-    const { work, run, directory, journal, pending: retainedJournal, prepared, archive } = prepareWorkRetry(context, id, reason);
-    const previousStart = context.db.get("SELECT current_start_invocation_id FROM works WHERE work_id = ?", [id])?.current_start_invocation_id;
+    const { work, run, directory, journal, pending: retainedJournal, prepared, archive } = prepareWorkRetry(context, id, reason, correction);
+    const previousStart = context.db.get("SELECT current_start_invocation_id FROM works WHERE work_id = ?", [work.work_id])?.current_start_invocation_id;
     const startAuthority = work.status === "failed" ? prepareWorkStartAuthority(context, rawWorkStartCommand(context, work), previousStart) : null;
     if (work.status === "failed") {
         // The durable journal and archive are projections of the failed SQL
@@ -1315,6 +1343,10 @@ export function retryWork(context, id, reason) {
         const receipt = path.join(archive, "accepted-receipt.json");
         const receiptBytes = JSON.stringify({ work_id: work.work_id, status: work.status, result: work.result, result_sha256: prepared.result_sha256 });
         publishStartReceiptFile(receipt, receiptBytes, sha256(receiptBytes));
+        if (prepared.external_launch) {
+            const bytes = JSON.stringify(prepared.external_launch);
+            publishStartReceiptFile(path.join(archive, "external-launch.json"), bytes, sha256(bytes));
+        }
         for (const file of prepared.entries) {
             const source = path.join(directory, file), target = path.join(archive, file);
             if (fs.existsSync(source)) {
@@ -1339,6 +1371,12 @@ export function retryWork(context, id, reason) {
             assertRunMutationAllowed(context, current.project_id, current.run_id, startAuthority?.scope.generation);
             if (current.status !== "failed" || current.result !== work.result || current.updated_at !== work.updated_at)
                 throw new AppError("work_retry_conflict", "Failed Work receipt changed during retry", 1);
+            if (prepared.external_launch) {
+                const launch = context.db.get("SELECT * FROM work_launches WHERE work_id=?", [work.work_id]);
+                if (JSON.stringify(launch) !== JSON.stringify(prepared.external_launch))
+                    throw new AppError("work_retry_conflict", "External launch changed before retry commit", 1);
+                context.db.run("DELETE FROM work_launches WHERE work_id=? AND operation_id=?", [work.work_id, prepared.external_launch.operation_id]);
+            }
             retireWorkPacketAuthorities(context, work.work_id);
             for (const column of ["prompt_path", "result_path"]) {
                 const file = column === "prompt_path" ? "prompt.md" : "result.json";
@@ -1350,9 +1388,18 @@ export function retryWork(context, id, reason) {
             context.db.run("UPDATE works SET current_start_invocation_id = ? WHERE work_id = ?", [startId, work.work_id]);
         });
     }
+    if (prepared.correction) {
+        const bytes = JSON.stringify(prepared.correction);
+        publishStartReceiptFile(path.join(directory, retryCorrectionFile), bytes, sha256(bytes));
+    }
+    const currentStart = context.db.get("SELECT current_start_invocation_id FROM works WHERE work_id=?", [work.work_id])?.current_start_invocation_id ?? null;
+    const retryReceipt = { work_id: work.work_id, archived_attempt: path.relative(requireRunHome(run), archive).split(path.sep).join("/"), failed_result_sha256: prepared.result_sha256, current_start_invocation_id: currentStart,
+        ...(prepared.correction ? { episode_id: prepared.correction.episode_id } : {}), ...(prepared.external_launch ? { archived_launch_ref: path.join(archive, "external-launch.json") } : {}) };
+    const retryBytes = JSON.stringify(retryReceipt);
+    publishStartReceiptFile(path.join(directory, retryReceiptFile), retryBytes, sha256(retryBytes));
     fs.rmSync(journal, { force: true });
     refreshRunWorkProjection(context, work.project_id, work.run_id);
-    return { ok: true, work_id: work.work_id, archived_attempt: path.relative(requireRunHome(run), archive).split(path.sep).join("/"), reason };
+    return { ok: true, ...(prepared.correction ? retryReceipt : { work_id: work.work_id, archived_attempt: retryReceipt.archived_attempt }), reason };
 }
 export function reviewSourceInputs(context, workId) {
     const work = requireWork(context, workId);
@@ -2114,7 +2161,7 @@ function renderWorkerPromptBody(context, work, run, dependencies, commands) {
                 "Workspace evidence resolves inside this private copy. RUN evidence is read-only. Write only this Work's result-input.json and assigned Work-owned evidence under run_home; neither a result JSON nor a private edit proves accepted publication or finding closure."]
             : mergeWork
                 ? ["MERGE does not own product-code repair. Use only the stage packet's merge apply command; resolve only paths that Git reports as unmerged. Do not edit integration code, tests, documentation or configuration to make a gate pass.", "RUN artifacts are read-only evidence: refer to them with run:// URIs and let dd-flow persist your submitted result."]
-                : [`HARD RULE: project source reads and writes must remain under ${run.workspace_root}.`, "Do not write through project_root, outside workspace_root, into another RUN, or into Git/worktree control data. Do not create, switch, merge or delete branches/worktrees.", "RUN artifacts are read-only evidence: refer to them with run:// URIs and let dd-flow persist your submitted result. Accepted requirements, non-goals and stop_conditions are semantic hard boundaries. planned_write_areas is not."];
+                : [`HARD RULE: project source reads and writes must remain under ${run.workspace_root}.`, "Do not write through project_root, outside workspace_root, into another RUN, or into Git/worktree control data. Do not create, switch, merge or delete branches/worktrees.", "RUN artifacts are read-only evidence: refer to them with run:// URIs and let dd-flow persist your submitted result. Accepted requirements and non-goals are semantic boundaries. planned_write_areas is not.", workStopConditionInstruction];
     const completionRepair = readOnly
         ? ["If Finish reports input drift or an infrastructure failure, report the exact receipt and stop. Do not change the reviewed files to make the check pass."]
         : repairPacket
@@ -2328,8 +2375,8 @@ function validateItem(value, requireExecutionContext = false) { if (!value || ty
     throw new AppError("validation", "work item must be an object", 2); const item = value; if (typeof item.key !== "string" || !item.key || typeof item.task !== "string" || !item.task.trim())
     throw new AppError("validation", "work item requires key and task", 2); const code = item.schema_id === "dd-flow/code-work-packet@5"; if (requireExecutionContext && !code)
     throw new AppError("validation", "CODE batch requires code-work-packet@5 items", 2, { key: item.key }); for (const key of code ? ["required_read", "discovery_boundary", "planned_write_areas", "checks", "provides_checks", "stop_conditions"] : [])
-    if (!Array.isArray(item[key]) || (!['provides_checks', 'planned_write_areas', 'checks'].includes(key) && item[key].length === 0) || (key === "checks" && item[key].length === 0 && !allowsEmptyRepairChecks(item)))
-        throw new AppError("validation", `CODE work item requires ${['provides_checks', 'planned_write_areas'].includes(key) ? "an array" : `non-empty ${key}`}`, 2, { key: item.key }); if (item.depends_on !== undefined && (!Array.isArray(item.depends_on) || !item.depends_on.every((entry) => typeof entry === "string")))
+    if (!Array.isArray(item[key]) || (!['provides_checks', 'planned_write_areas', 'checks', 'stop_conditions'].includes(key) && item[key].length === 0) || (key === "checks" && item[key].length === 0 && !allowsEmptyRepairChecks(item)))
+        throw new AppError("validation", `CODE work item requires ${['provides_checks', 'planned_write_areas', 'stop_conditions'].includes(key) ? "an array" : `non-empty ${key}`}`, 2, { key: item.key }); if (item.depends_on !== undefined && (!Array.isArray(item.depends_on) || !item.depends_on.every((entry) => typeof entry === "string")))
     throw new AppError("validation", "depends_on must be a string array", 2); if (item.parent !== undefined && typeof item.parent !== "string")
     throw new AppError("validation", "parent must be a string", 2); if (item.launch_policy !== undefined && item.launch_policy !== "reuse_allowed" && item.launch_policy !== "fresh_agent_required")
     throw new AppError("validation", "launch_policy must be reuse_allowed or fresh_agent_required", 2); if (item.result_schema !== undefined && (typeof item.result_schema !== "string" || !item.result_schema))