@deksden-com/dd-flow-cli 0.9.0-beta.83 → 0.9.0-beta.87

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.87
+
+### Patch Changes
+
+- a49655a: Use separate files for model-authored lifecycle payloads and preserve native
+  shell-composition diagnostics instead of reporting a missing hook receipt.
+
+## 0.9.0-beta.86
+
+### Patch Changes
+
+- 8abe471: Settle invalid managed lifecycle arguments atomically before dispatch and return one safe corrected command.
+
+## 0.9.0-beta.85
+
+### Patch Changes
+
+- fe8f493: Restore runtime-owned response publication options before dispatching a managed lifecycle command, and update the controller fixture to validate the public command contract.
+
+## 0.9.0-beta.84
+
+### Patch Changes
+
+- 644d181: Keep RUN identity, project paths, context files, response destinations and
+  integrity hashes inside retained lifecycle authority instead of asking agents
+  to copy them. Restore those inputs deterministically when the observed command
+  executes, including MERGE apply and repair commands.
+
 ## 0.9.0-beta.83
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,11 +1,11 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.83",
-  "cli_commit": "7ede03ea5da48b77ab59b46bed8028b2a885da61",
-  "built_at": "2026-09-20T14:09:35.175Z",
+  "cli_version": "0.9.0-beta.87",
+  "cli_commit": "68245785d197ab491e80db40faf2e57a18a6a055",
+  "built_at": "2026-09-20T22:46:39.592Z",
   "built_with_canon": {
     "version": "4.1.1",
-    "commit": "97f811d33c212ae3497020178b1ed825c7c3ebac",
+    "commit": "acaae844a871ddfbc49fd66355373f166dc3e683",
     "flow_contract": "dd-flow-canonical-2026-08",
     "repo_root": "/home/runner/work/dd-flow-cli/dd-flow-cli/dd-memorybank",
     "memorybank_root": "/home/runner/work/dd-flow-cli/dd-flow-cli/dd-memorybank/.memory-bank",

package/dist/cli/command-inputs.js

@@ -43,9 +43,9 @@ export const commandInputs = {
     "prompt render": route(0, `${project} run stage profile`, "workspace-root task-file plan-item"),
     "stage start": { ...route([0, 1], `${project} stage`, `${lifecycle} dir subject intake-file context-file context-sha256`, "bootstrap intake-stdin require-session-binding"), contextualPaths: words("project-root intake-file context-file") },
     "stage finish": { ...route(1, `${project} stage`, `${lifecycle} dir semantic-file data result-file outcome decision-file verification-file retry-check reason request work`, "result-stdin"), contextualPaths: words("project-root semantic-file result-file decision-file verification-file") },
-    "stage pause": { ...route(1, `${project} stage work`, lifecycle, "question-stdin"), contextualPaths: ["project-root"] },
-    "stage resume": { ...route(1, `${project} stage work`, lifecycle, "answer-stdin"), contextualPaths: ["project-root"] },
-    "stage block": route(1, `${project} stage work kind code`, "", "summary-stdin retryable", "", { kind: ["engine", "harness", "environment"] }),
+    "stage pause": { ...route(1, `${project} stage work`, `${lifecycle} question-file`, "question-stdin"), contextualPaths: words("project-root question-file") },
+    "stage resume": { ...route(1, `${project} stage work`, `${lifecycle} answer-file`, "answer-stdin"), contextualPaths: words("project-root answer-file") },
+    "stage block": { ...route(1, `${project} stage work kind code`, "summary-file", "summary-stdin retryable", "", { kind: ["engine", "harness", "environment"] }), contextualPaths: words("project-root summary-file") },
     "stage unblock": route(1, `${project} stage work`),
     "stage fanout status": route(1, "stage", scoped),
     "stage fanout dispatch": route(1, "stage", scoped),
@@ -55,7 +55,7 @@ export const commandInputs = {
     "work add-batch": route(0, "parent file", scoped),
     "work ls": route(0, "", `${scoped} run parent status limit`, "ready include-results", "", { status: ["created", "running", "paused", "completed", "failed", "cancelled"] }),
     "work show": route(1, "", scoped),
-    "work repair add": route(0, "run", `${scoped} origin-work from-check from-finding from-unresolved check-ref verification-file`, "task-stdin", "origin-work from-finding from-unresolved check-ref"),
+    "work repair add": { ...route(0, "run", `${scoped} origin-work from-check from-finding from-unresolved check-ref verification-file task-file`, "task-stdin", "origin-work from-finding from-unresolved check-ref"), contextualPaths: words("project-root verification-file task-file") },
     "work deps add": route(1, "on", scoped, "", "on"),
     "work deps remove": route(1, "on", scoped, "", "on"),
     "work deps list": route(1, "", scoped),
@@ -285,7 +285,8 @@ export function prepareCommandRoute(args) {
         ["root", "project-root"], ["payload-file", "json-file"],
         ["payload-file", "payload-json", "payload-base64"], ["semantic-file", "data", "result-file", "result-stdin"],
         ["stage-report", "dashboard"], ["task-file", "plan-item"], ["project", "project-root"],
-        ["intake-file", "intake-stdin", "context-file"]
+        ["intake-file", "intake-stdin", "context-file"], ["question-file", "question-stdin"], ["answer-file", "answer-stdin"],
+        ["summary-file", "summary-stdin"], ["task-file", "task-stdin"]
     ]) {
         const present = aliases.filter(name => parsed.options.has(name));
         if (present.length > 1)

package/dist/cli/help.js

@@ -231,9 +231,9 @@ Examples:
 Usage:
   dd-flow stage start <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--dir <NN-stage-slug>] [--require-session-binding] --json
   dd-flow stage start --bootstrap --project-root <root> --stage specify --subject <safe-subject> (--intake-file <path>|--intake-stdin) [--require-session-binding] --json
-  dd-flow stage pause <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --question-stdin --json
-  dd-flow stage resume <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --answer-stdin --json
-  dd-flow stage block <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --kind engine|harness|environment --code <code> --summary-stdin [--retryable] --json
+  dd-flow stage pause <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> (--question-file <path>|--question-stdin) --json
+  dd-flow stage resume <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> (--answer-file <path>|--answer-stdin) --json
+  dd-flow stage block <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --kind engine|harness|environment --code <code> (--summary-file <path>|--summary-stdin) [--retryable] --json
   dd-flow stage unblock <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --json
   dd-flow stage fanout status <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --json
   dd-flow stage fanout dispatch <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --json
@@ -254,7 +254,7 @@ Usage:
   dd-flow work start <WORK-ID> --project-root <root> --json
   dd-flow work launch <WORK-ID> [--stage <name>] --json
   dd-flow work finish <WORK-ID> (--result-file <path>|--result-stdin) --project-root <root> --json
-  dd-flow work repair add --run <RUN-ID> (--from-check <CHECK-ID>|--from-unresolved <gap> --verification-file <file>) --origin-work <WORK-ID>... --task-stdin --project-root <root> --json
+  dd-flow work repair add --run <RUN-ID> (--from-check <CHECK-ID>|--from-unresolved <gap> --verification-file <file>) --origin-work <WORK-ID>... (--task-file <path>|--task-stdin) --project-root <root> --json
 
 CODE workers receive their full accepted packet from work start. work finish validates the result and executes the packet's focused checks before completion. A failed aggregate CODE gate or unresolved semantic verification creates a repair Work from the selected completed origin context and retained evidence. Its planned write areas are coordination hints only; the repair may change any necessary project file inside its RUN workspace.`
     ],

package/dist/cli/run-cli.js

@@ -4,7 +4,7 @@ import { randomUUID } from "node:crypto";
 import { quote } from "shell-quote";
 import { observeLifecycleCommand } from "../services/lifecycle-invocations.js";
 import { verifyCodexHookDelivery } from "../services/codex-hook-delivery.js";
-import { assertLifecycleInvocationCurrent, awaitLifecycleInvocation, expandLifecycleInvocationArgs, issueLifecycleInvocation, prepareLifecycleIssuance, lifecycleInvocationScope, observedLifecycleInvocation, settleLifecycleInvocation, settleLifecycleRejection, validateLifecyclePathAliases } from "../services/lifecycle-invocations.js";
+import { assertLifecycleInvocationCurrent, awaitLifecycleInvocation, expandLifecycleInvocationArgs, issueLifecycleInvocation, prepareLifecycleIssuance, lifecycleInvocationScope, observedLifecycleDiagnostic, observedLifecycleInvocation, resolveObservedLifecycleArgs, settleLifecycleInvocation, settleLifecyclePreparationRejection, settleLifecycleRejection, validateLifecyclePathAliases } from "../services/lifecycle-invocations.js";
 import { createContext, createRouterContext } from "../runtime/context.js";
 import { migrateStoreWriter } from "../storage/writer-migration.js";
 import { helpForArgs } from "./help.js";
@@ -134,19 +134,43 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             validateLifecyclePathAliases(output.args, lifecycleCommand.invocation.operation);
         const observedInvocation = observedLifecycleInvocation(routerContext, publicCommand);
         if (!observedInvocation && !suppliedInvocationId && env.DD_FLOW_DAEMON_ID && lifecycleCommand.kind === "standalone") {
+            const diagnostic = observedLifecycleDiagnostic(routerContext, publicCommand, env.DD_FLOW_DAEMON_ID);
+            if (diagnostic)
+                throw new AppError("lifecycle_shell_syntax_invalid", `Native observer rejected the shell form: ${String(diagnostic.reason ?? "unsupported shell composition")}. Write structured input to a file and run the returned dd-flow command separately.`, 2, { ...diagnostic, phase: "prepare", effect: "no_effect", recoverable: true });
             throw new AppError("invocation_receipt_missing", "Managed lifecycle command has no committed native receipt", 1, { effect: "no_effect", recoverable: false });
         }
         const invocationId = observedInvocation?.id ?? suppliedInvocationId;
-        const boundInvocationArgs = invocationId && invocationId !== suppliedInvocationId
-            ? [...output.args.filter((_, index, values) => values[index - 1] !== "--invocation-id" && values[index] !== "--invocation-id"), "--invocation-id", invocationId]
-            : output.args;
+        let boundInvocationArgs;
+        try {
+            boundInvocationArgs = observedInvocation
+                ? resolveObservedLifecycleArgs(routerContext, observedInvocation.id, output.args)
+                : invocationId && invocationId !== suppliedInvocationId
+                    ? [...output.args.filter((_, index, values) => values[index - 1] !== "--invocation-id" && values[index] !== "--invocation-id"), "--invocation-id", invocationId]
+                    : output.args;
+        }
+        catch (error) {
+            if (!(observedInvocation && error instanceof AppError))
+                throw error;
+            const rejectionContext = createContext({ ...env }, "hook");
+            try {
+                Object.assign(error.details, settleLifecyclePreparationRejection(rejectionContext, observedInvocation.id, error));
+            }
+            finally {
+                rejectionContext.db.close?.();
+            }
+            throw error;
+        }
         const observedOperation = lifecycleCommand.kind === "standalone" ? lifecycleCommand.invocation.operation : null;
         if (observedInvocation && !observedOperation)
             throw new AppError("invocation_command_invalid", "Observed lifecycle command could not be parsed", 1);
         const invocationScope = invocationId ? lifecycleInvocationScope({ ...routerContext, env }, invocationId) : undefined;
-        const invocationArgs = invocationScope && observedOperation
+        const expandedInvocationArgs = invocationScope && observedOperation
             ? expandLifecycleInvocationArgs(routerContext, boundInvocationArgs, invocationScope, observedOperation)
             : boundInvocationArgs;
+        const retainedOutput = observedInvocation ? parseOutputOptions(expandedInvocationArgs) : null;
+        if (retainedOutput?.responseFile)
+            output.responseFile = retainedOutput.responseFile;
+        const invocationArgs = retainedOutput?.args ?? expandedInvocationArgs;
         emitHumanProgress(io, output, progress, "start");
         if (output.progressJsonl) {
             writeProgressJsonl(io, "start", `Starting ${output.args.slice(0, 3).join(" ")}`);
@@ -957,9 +981,10 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
         const input = { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), stage: requiredOption(parsed, "stage"), workId: requiredOption(parsed, "work") };
         try {
             if (route.key === "stage block") {
-                if (!hasOption(parsed, "summary-stdin"))
-                    throw new AppError("usage", "stage block requires --summary-stdin", 2);
-                prepared.interactionText = await readStdin(io.stdin);
+                const summaryFile = optionalOption(parsed, "summary-file"), summaryStdin = hasOption(parsed, "summary-stdin");
+                if (Boolean(summaryFile) === summaryStdin)
+                    throw new AppError("usage", "stage block requires exactly one of --summary-file or --summary-stdin", 2);
+                prepared.interactionText = summaryFile ? prepareTextFile(summaryFile, "Runtime block summary").text : await readStdin(io.stdin);
                 prepareStageRuntimeBlock(context, { ...input, kind: requiredOption(parsed, "kind"), code: requiredOption(parsed, "code"), summary: prepared.interactionText, retryable: hasOption(parsed, "retryable") });
             }
             else
@@ -992,11 +1017,13 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
         }
     }
     if (route.key === "work repair add") {
-        if (!hasOption(parsed, "task-stdin"))
-            throw new AppError("usage", "work repair add requires --task-stdin", 2);
-        if (io.stdin?.isTTY)
+        const taskFile = optionalOption(parsed, "task-file"), taskStdin = hasOption(parsed, "task-stdin");
+        if (Boolean(taskFile) === taskStdin)
+            throw new AppError("usage", "work repair add requires exactly one of --task-file or --task-stdin", 2);
+        if (taskStdin && io.stdin?.isTTY)
             throw new AppError("usage", "--task-stdin requires piped or redirected input", 2);
-        prepared.workRepair = prepareCliWorkRepair(context, parsed, await readStdin(io.stdin), scopeProjectRoot);
+        const task = taskFile ? prepareTextFile(taskFile, "Repair task").text : await readStdin(io.stdin);
+        prepared.workRepair = prepareCliWorkRepair(context, parsed, task, scopeProjectRoot);
     }
     if (route.key === "run config set" || route.key === "run vars set") {
         const input = { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 1, "run-id"), key: requiredOption(parsed, "key"), value: requiredOption(parsed, "value") };
@@ -1132,14 +1159,17 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
         requiredOption(parsed, "project-root");
         requiredOption(parsed, "stage");
         requiredOption(parsed, "work");
-        const parameter = command === "pause" ? "question-stdin" : "answer-stdin";
-        if (!hasOption(parsed, parameter))
-            throw new AppError("usage", `stage ${command} requires --${parameter}`, 2);
-        if (io.stdin?.isTTY)
-            throw new AppError("usage", `--${parameter} requires piped or redirected input`, 2);
-        prepared.interactionText = await readStdin(io.stdin);
+        const fileParameter = command === "pause" ? "question-file" : "answer-file";
+        const stdinParameter = command === "pause" ? "question-stdin" : "answer-stdin";
+        const inputFile = optionalOption(parsed, fileParameter);
+        const fromStdin = hasOption(parsed, stdinParameter);
+        if (Boolean(inputFile) === fromStdin)
+            throw new AppError("usage", `stage ${command} requires exactly one of --${fileParameter} or --${stdinParameter}`, 2);
+        if (fromStdin && io.stdin?.isTTY)
+            throw new AppError("usage", `--${stdinParameter} requires piped or redirected input`, 2);
+        prepared.interactionText = inputFile ? prepareTextFile(inputFile, command === "pause" ? "User question" : "User answer").text : await readStdin(io.stdin);
         if (!prepared.interactionText.trim())
-            return prepareError(new AppError("validation", `stage ${command} requires non-empty --${parameter}`, 2), { parameter });
+            return prepareError(new AppError("validation", `stage ${command} requires non-empty input`, 2), { parameter: inputFile ? fileParameter : stdinParameter });
         const input = { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id"), stage: requiredOption(parsed, "stage"), workId: requiredOption(parsed, "work") };
         try {
             if (command === "pause")
@@ -1726,8 +1756,6 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         }, prepared.legacyStageFinish));
     }
     if (family === "stage" && command === "pause") {
-        if (!hasOption(parsed, "question-stdin"))
-            throw new AppError("usage", "stage pause requires --question-stdin", 2);
         const projectRoot = requiredOption(parsed, "project-root");
         const runId = requiredPosition(parsed, 0, "run-id");
         const stage = requiredOption(parsed, "stage");
@@ -1749,8 +1777,6 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         });
     }
     if (family === "stage" && command === "resume") {
-        if (!hasOption(parsed, "answer-stdin"))
-            throw new AppError("usage", "stage resume requires --answer-stdin", 2);
         const hookEventId = optionalOption(parsed, "hook-event-id");
         return resumeStageAfterUser(context, {
             projectRoot: requiredOption(parsed, "project-root"),
@@ -1763,8 +1789,6 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         });
     }
     if (family === "stage" && command === "block") {
-        if (!hasOption(parsed, "summary-stdin"))
-            throw new AppError("usage", "stage block requires --summary-stdin", 2);
         const kind = requiredOption(parsed, "kind");
         if (kind !== "engine" && kind !== "harness" && kind !== "environment")
             throw new AppError("usage", "--kind must be engine, harness or environment", 2);

package/dist/services/controller-fanout.js

@@ -5,11 +5,11 @@ import { dispatchVnextPlanReview } from "./vnext-plan-review.js";
 import { resolveExecutionPolicy } from "./execution-policy.js";
 import { renderDelegationInstructions } from "../harness-runtime/lib/delegation-instructions.mjs";
 /** Stage entry acknowledges the packet before the controller issues child commands. */
-export function controllerStageEntryPrompt(stage, command, responseFile) {
+export function controllerStageEntryPrompt(stage, command) {
     return [
         `Start the assigned ${stage} Stage now. Your first tool call must be this exact standalone command:`,
         command,
-        `Read the complete authoritative packet saved to ${JSON.stringify(responseFile)}, including worker_prompt_markdown. If a read is truncated, continue until the entire packet has been read.`,
+        "Read the complete authoritative packet from the command's response_file result, including worker_prompt_markdown. If a read is truncated, continue until the entire packet has been read.",
         "If the returned packet has orchestration.kind = work_fanout, this Turn is only Stage entry: acknowledge the packet and end your Turn immediately. The packet describes the whole Stage, but its graph/dispatch/finish instructions belong to later controller continuations. Do not list, start, launch or finish Work, create children, change files, run checks, or finish the Stage in this entry Turn. The controller will inspect the graph and send the next assignment with exact issued commands (or dispatch external workers itself).",
         "Otherwise perform this Stage's semantic work and stop at its boundary or a declared HITL boundary. Do not start a successor Stage.",
         "Execute each runtime-issued lifecycle operation and target as one standalone call. Internal invocation IDs are intentionally absent; never add, copy or invent one. For a no-effect input rejection, correct the input and use its returned retry_command. If a required command is missing or no safe retry is returned, report the exact error and end the Turn so the controller can handle it."

package/dist/services/hooks.js

@@ -352,7 +352,7 @@ export function handleCodexHook(context, input) {
         ?? (bindingOwnerId ? sessionBinding(context, project.id, bindingOwnerId)?.transcript_path ?? locateCodexTranscript(bindingOwnerId, context.env.CODEX_HOME) : null);
     const persist = (scope) => {
         if (scope)
-            matchKey = lifecycleMatchKey(lifecycle, project.root, scope);
+            matchKey = lifecycleMatchKey(lifecycleFacts(scope.command), project.root, scope);
         const binding = bindingOwnerId ? upsertSessionBindingFromPayload(context, project, bindingOwnerId, payload, transcriptPath) : undefined;
         const effectiveSessionId = storageId;
         const protocolId = binding?.protocol_id ?? null;
@@ -549,7 +549,7 @@ function recordZcodeLifecycle(context, input, invocationId) {
     const eventNameForReceipt = invocationId ? "ToolCallObserved" : "PreToolUse";
     const persist = (scope) => {
         if (scope)
-            matchKey = lifecycleMatchKey(lifecycle, expectedRoot, scope);
+            matchKey = lifecycleMatchKey(lifecycleFacts(scope.command), expectedRoot, scope);
         assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "zcode-acp", providerSessionId, parentSessionId, daemonId, sessionId, turnId: null, eventName: eventNameForReceipt, toolName: toolName ?? "Bash", matchKey, cwd: expectedRoot });
         const payload = { ...hook, session_id: providerSessionId, cwd: expectedRoot, tool_name: toolName ?? "Bash", tool_input: rawInput,
             command, provider: stringValue(observedProfile.provider), model: stringValue(observedProfile.model), reasoning: stringValue(observedProfile.reasoning), mode: stringValue(observedProfile.mode) };

package/dist/services/lifecycle-command.js

@@ -198,6 +198,10 @@ function lifecycleOperation(argv) {
         return "work_finish";
     if (key === "work fail")
         return "work_fail";
+    if (key === "merge apply")
+        return "merge_apply";
+    if (key === "merge repair")
+        return "merge_repair";
     return null;
 }
 export function parseCommandArgs(argv) {

package/dist/services/lifecycle-invocations.js

@@ -58,10 +58,50 @@ function invocation(command) {
 // Input data may be supplied later (stdin/file contents); authority is bound to
 // the exact operation and literal argv. Existing lifecycle validation owns data.
 function fingerprint(parsed) {
-    const options = [...parsed.args.options].filter(([key]) => !["invocation-id", "hook-event-id", "json", "progress-jsonl", "response-file"].includes(key))
+    const projected = publicInvocationArgs(parsed);
+    const publicParsed = invocation(`${quote([parsed.executable])} ${quoteModelFacingArgs(projected)}`);
+    const options = [...publicParsed.args.options].filter(([key]) => !["invocation-id", "hook-event-id", "json", "progress-jsonl"].includes(key))
         .map(([key, values]) => [key, key === "reason" ? ["<semantic-reason>"] : values.map(value => normalizedInvocationValue(key, value))])
         .sort(([a], [b]) => a.localeCompare(b));
-    return crypto.createHash("sha256").update(JSON.stringify([parsed.operation, parsed.args.positional.map(value => normalizedInvocationValue("positional", value)), options])).digest("hex");
+    return crypto.createHash("sha256").update(JSON.stringify([parsed.operation, publicParsed.args.positional.map(value => normalizedInvocationValue("positional", value)), options])).digest("hex");
+}
+const runtimeOwnedOptions = {
+    stage_start: new Set(["project-root", "context-file", "context-sha256", "response-file", "require-session-binding"]),
+    stage_finish: new Set(["project-root", "result-file", "decision-file", "verification-file"]),
+    stage_pause: new Set(["project-root"]), stage_resume: new Set(["project-root"]),
+    work_start: new Set(["project-root", "recovery-id"]),
+    work_finish: new Set(["project-root"]), work_fail: new Set(["project-root"]),
+    merge_apply: new Set(["project-root"]), merge_repair: new Set(["project-root"]),
+    recovery_accept: new Set(["project-root"])
+};
+function publicInvocationArgs(parsed) {
+    const hidden = runtimeOwnedOptions[parsed.operation] ?? new Set();
+    const args = [];
+    for (let index = 0; index < parsed.argv.length; index += 1) {
+        const value = parsed.argv[index];
+        if (!value.startsWith("--")) {
+            args.push(value);
+            continue;
+        }
+        const key = value.slice(2).split("=", 1)[0];
+        const inline = value.includes("=");
+        const next = parsed.argv[index + 1];
+        if (hidden.has(key) || key === "invocation-id" || key === "hook-event-id") {
+            if (!inline && next && !next.startsWith("--"))
+                index += 1;
+            continue;
+        }
+        args.push(value);
+        if (!inline && next && !next.startsWith("--"))
+            args.push(parsed.argv[++index]);
+    }
+    // A managed coordinator Session is already bound to its RUN. Work IDs stay
+    // public because sibling Work assignments can coexist under one native root.
+    const operationOffset = parsed.operation === "recovery_accept" ? 3 : 2;
+    if (["stage_start", "stage_finish", "recovery_accept"].includes(parsed.operation)
+        && !parsed.args.options.has("bootstrap") && args[operationOffset] && !args[operationOffset].startsWith("--"))
+        args.splice(operationOffset, 1);
+    return args;
 }
 function normalizedInvocationValue(key, value) {
     value = normalizedPathAlias(value);
@@ -92,10 +132,7 @@ function quoteModelFacingArgs(argv) {
 }
 function withoutInvocationId(command, aliases) {
     const parsed = invocation(command);
-    const argv = [...parsed.argv];
-    const at = argv.indexOf("--invocation-id");
-    if (at >= 0)
-        argv.splice(at, 2);
+    const argv = publicInvocationArgs(parsed);
     for (let index = 0; index < argv.length; index += 1) {
         const option = argv[index - 1]?.replace(/^--/, "");
         if (option === "project-root")
@@ -123,11 +160,20 @@ function withoutInvocationId(command, aliases) {
     return `${prefix ? `${prefix} ` : ""}${executable}${argv.length ? ` ${quoteModelFacingArgs(argv)}` : ""}${suffix ? ` ${suffix}` : ""}`.trim();
 }
 function publicInvocationCommand(context, row, command) {
+    if (!commandOption(invocation(command), "project-root"))
+        command = retainedCommandWithoutInvocationId(row);
     const rendered = renderInvocationCommand(row, command);
     const scope = JSON.parse(row.scope_json);
     const run = scope.runId ? context.db.get("SELECT workspace_root, run_root FROM runs WHERE id = ?", [scope.runId]) : undefined;
     return withoutInvocationId(rendered, { project: scope.projectRoot, ...(run?.workspace_root ? { workspace: run.workspace_root } : {}), ...(run?.run_root ? { run: run.run_root } : {}) });
 }
+function retainedCommandWithoutInvocationId(row) {
+    const marker = ` --invocation-id ${row.id}`;
+    const at = row.command.indexOf(marker);
+    if (at < 0 || row.command.indexOf(marker, at + marker.length) >= 0)
+        throw new AppError("invocation_command_invalid", "Retained issued command has an ambiguous invocation marker", 1);
+    return `${row.command.slice(0, at)}${row.command.slice(at + marker.length)}`;
+}
 /** Resolve the small, declared alias vocabulary used by model-facing lifecycle commands.
  * Both native-hook admission and CLI execution call this function so they cannot
  * disagree about the command that an alias denotes. */
@@ -454,11 +500,7 @@ function successorLifecycleInvocationCommand(context, prior) {
     // The parser proves the marker belongs to argv. Remove that one rendered
     // token from the retained text so response-file/stdin/heredoc presentation
     // remains byte-for-byte stable across a retry.
-    const marker = ` --invocation-id ${prior.id}`;
-    const markerAt = prior.command.indexOf(marker);
-    if (markerAt < 0 || prior.command.indexOf(marker, markerAt + marker.length) >= 0)
-        throw new AppError("invocation_command_invalid", "Retained issued command has an ambiguous invocation marker", 1);
-    const command = `${prior.command.slice(0, markerAt)}${prior.command.slice(markerAt + marker.length)}`;
+    const command = retainedCommandWithoutInvocationId(prior);
     return managedLifecycleCommand({ ...context, env: { ...context.env, DD_FLOW_INVOCATION_SCOPE: prior.scope_json, DD_FLOW_CURRENT_INVOCATION: prior.id } }, command);
 }
 // Caller holds the write transaction and has checked authority. Issued (or
@@ -568,6 +610,11 @@ export function assertLifecycleInvocationCurrent(context, scope, command) {
             throw new AppError("invocation_scope_mismatch", "Work does not belong unambiguously to the issued RUN scope", 1);
         }
     }
+    else if (parsed.operation.startsWith("merge_")) {
+        const request = context.db.get("SELECT project_id, run_id FROM merge_requests WHERE merge_request_id = ?", [parsed.args.positional[0] ?? ""]);
+        if (!request || request.project_id !== project.id || request.run_id !== scope.runId)
+            throw new AppError("invocation_scope_mismatch", "MERGE request does not belong to the issued RUN scope", 1);
+    }
     else if (parsed.operation !== "session_register" && !parsed.args.options.has("bootstrap")) {
         const target = parsed.args.positional[0];
         const run = context.db.get("SELECT id FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [project.id, target ?? null, target ?? null]);
@@ -661,8 +708,30 @@ export function observeLifecycleInvocation(context, input) {
     storage(context);
     const supplied = input.id ? context.db.get("SELECT * FROM lifecycle_invocations WHERE id = ?", [input.id]) : undefined;
     const analysis = parseLifecycleCommand(input.command);
-    if (analysis.kind !== "standalone" || analysis.invocation.wrapped)
-        return { eventKey: input.recordReceipt(), duplicate: false, invocationId: null };
+    if (analysis.kind !== "standalone" || analysis.invocation.wrapped) {
+        const eventKey = input.recordReceipt();
+        if (analysis.kind !== "none") {
+            const retained = context.db.get("SELECT outcome_json FROM hook_events WHERE event_key = ?", [eventKey]);
+            let outcome = {};
+            try {
+                outcome = retained?.outcome_json ? JSON.parse(retained.outcome_json) : {};
+            }
+            catch {
+                outcome = {};
+            }
+            context.db.run("UPDATE hook_events SET outcome_json = ? WHERE event_key = ?", [JSON.stringify({
+                    ...outcome,
+                    lifecycle_observation: {
+                        code: "lifecycle_shell_syntax_invalid",
+                        reason: analysis.kind === "compound" ? analysis.reason : "wrapped_lifecycle_command",
+                        command_fingerprint: fingerprint(analysis.invocation),
+                        effect: "no_effect",
+                        recoverable: true
+                    }
+                }), eventKey]);
+        }
+        return { eventKey, duplicate: false, invocationId: null };
+    }
     const candidates = context.db.all("SELECT * FROM lifecycle_invocations WHERE status IN ('issued','observed') ORDER BY rowid DESC")
         .filter(row => {
         const scope = JSON.parse(row.scope_json);
@@ -713,7 +782,7 @@ export function observeLifecycleInvocation(context, input) {
             context.db.exec("COMMIT");
             return { eventKey: row.event_key, duplicate: true, ...resolved };
         }
-        const eventKey = input.recordReceipt(scope);
+        const eventKey = input.recordReceipt({ projectRoot: scope.projectRoot, runId: scope.runId, command: initial.command });
         // A native hook may execute from a provider worktree while the issued
         // lifecycle scope is anchored to the stable project root. Project
         // identity is the canonical boundary; comparing raw cwd would reject a
@@ -738,6 +807,29 @@ export function observeLifecycleInvocation(context, input) {
         throw error;
     }
 }
+/** Return a precise native-observer rejection for the same argv. This keeps
+ * shell diagnostics distinct from a genuinely absent hook receipt. */
+export function observedLifecycleDiagnostic(context, command, daemonId) {
+    const analysis = parseLifecycleCommand(command);
+    if (analysis.kind !== "standalone")
+        return null;
+    const commandFingerprint = fingerprint(analysis.invocation);
+    const rows = context.db.all("SELECT event_key, outcome_json FROM hook_events WHERE daemon_id = ? AND status = 'observed' AND outcome_json IS NOT NULL ORDER BY id DESC LIMIT 20", [daemonId]).flatMap(row => {
+        try {
+            const outcome = JSON.parse(row.outcome_json);
+            return outcome.lifecycle_observation?.command_fingerprint === commandFingerprint ? [{ ...outcome.lifecycle_observation, event_key: row.event_key }] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    if (!rows.length)
+        return null;
+    const reasons = new Set(rows.map(row => `${String(row.code)}\0${String(row.reason)}`));
+    if (reasons.size !== 1)
+        return null;
+    return { ...rows[0], matching_events: rows.map(row => row.event_key) };
+}
 /** Resolve only a command that a native hook has already bound to an issued
  * attempt. This is the CLI-side half of admission for model-facing commands
  * that intentionally omit the internal UUID. */
@@ -763,6 +855,43 @@ export function observedLifecycleInvocation(context, command) {
         throw new AppError("invocation_ambiguous", "More than one observed lifecycle attempt matches this command", 1, { effect: "no_effect", matches: matches.map(row => row.id) });
     return { id: matches[0].id, scope: JSON.parse(matches[0].scope_json) };
 }
+/** Replace presentation argv with the exact retained machine assignment.
+ * Public semantic arguments are already covered by the projected fingerprint;
+ * any explicitly repeated private value must agree instead of being ignored. */
+export function resolveObservedLifecycleArgs(context, id, actualArgs) {
+    const row = context.db.get("SELECT * FROM lifecycle_invocations WHERE id = ?", [id]);
+    if (!row)
+        throw new AppError("invocation_unknown", "Lifecycle invocation is not registered", 1, { invocation_id: id });
+    const retained = invocation(row.command), actual = invocation(`${quote([retained.executable])} ${quoteModelFacingArgs(actualArgs)}`);
+    if (fingerprint(actual) !== row.fingerprint)
+        throw new AppError("invocation_command_mismatch", "Lifecycle command does not match its issued assignment", 2, { phase: "prepare", effect: "no_effect", recoverable: true });
+    for (const key of runtimeOwnedOptions[retained.operation] ?? []) {
+        const supplied = commandOption(actual, key), expected = commandOption(retained, key);
+        if (supplied !== undefined && normalizedInvocationValue(key, supplied) !== normalizedInvocationValue(key, expected ?? "")) {
+            throw new AppError("invocation_argument_mismatch", `--${key} is owned by the managed assignment and does not match it`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: key });
+        }
+    }
+    return [...retained.argv];
+}
+export function settleLifecyclePreparationRejection(context, id, error) {
+    return context.db.writeTransaction(() => {
+        const row = load(context, id);
+        if (row.status === "settled") {
+            const details = row.outcome_json ? JSON.parse(row.outcome_json)?.error?.details : undefined;
+            return details?.effect === "no_effect" && details.retry_command ? details : { effect: "unknown", recoverable: false };
+        }
+        if (!["issued", "observed"].includes(row.status))
+            return { effect: "unknown", recoverable: false };
+        const scope = JSON.parse(row.scope_json);
+        if (scope.runId)
+            assertLifecycleInvocationCurrent(context, scope, row.command);
+        const details = { ...error.details, effect: "no_effect", recoverable: true,
+            retry_command: successorLifecycleInvocationCommand(context, row),
+            retry_instruction: "Execute retry_command verbatim in this same Session. The rejected call changed no lifecycle state." };
+        context.db.run("UPDATE lifecycle_invocations SET status = 'settled', outcome_json = ?, updated_at = ? WHERE id = ?", [JSON.stringify({ error: { ...errorRecord(error), details } }), context.now(), row.id]);
+        return details;
+    });
+}
 /** One caller owns execution; a lost process leaves an explicit unknown
  * outcome, never an automatic replay. Existing recovery decides the next step. */
 export async function awaitLifecycleInvocation(context, input) {
@@ -782,27 +911,7 @@ export async function awaitLifecycleInvocation(context, input) {
     catch (error) {
         if (!(error instanceof AppError) || !(["usage", "invocation_command_mismatch", "invocation_command_invalid"].includes(error.code) || error.details.phase === "prepare"))
             throw error;
-        const rejectionDetails = context.db.writeTransaction(() => {
-            const row = load(context, input.id);
-            if (row.status === "settled") {
-                const details = row.outcome_json ? JSON.parse(row.outcome_json)?.error?.details : undefined;
-                return details?.effect === "no_effect" && details.retry_command ? details : { effect: "unknown", recoverable: false };
-            }
-            if (!["issued", "observed"].includes(row.status)) {
-                return { effect: "unknown", recoverable: false };
-            }
-            const scope = JSON.parse(row.scope_json);
-            if (scope.runId)
-                assertLifecycleInvocationCurrent(context, scope, row.command);
-            // No executor has claimed this attempt. Atomically retain the rejected
-            // call and issue one corrected command; old IDs only replay the outcome.
-            const details = { ...error.details, effect: "no_effect", recoverable: true,
-                retry_command: successorLifecycleInvocationCommand(context, row),
-                retry_instruction: "Execute retry_command verbatim in this same Session. The rejected call changed no lifecycle state." };
-            context.db.run("UPDATE lifecycle_invocations SET status = 'settled', outcome_json = ?, updated_at = ? WHERE id = ?", [JSON.stringify({ error: { ...errorRecord(error), details } }), context.now(), row.id]);
-            return details;
-        });
-        Object.assign(error.details, rejectionDetails);
+        Object.assign(error.details, settleLifecyclePreparationRejection(context, input.id, error));
         throw error;
     }
     const timeoutMs = input.timeoutMs ?? 30000;

package/dist/services/run-controller.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
+import { quote } from "shell-quote";
 import { ensureRunControllerStorage, getDatabase } from "../storage/database.js";
 import { canonicalPath, resolveProjectRoot } from "../storage/paths.js";
 import { AppError } from "../shared/errors.js";
@@ -608,7 +609,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 assertOwner();
                 // The accepted answer is logical intent; only its generation-bound
                 // adapter operation represents a physical dispatch that stop must drain.
-                const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage resume ${run.id} --stage ${next.stage} --work ${input.work_id} --project-root ${JSON.stringify(run.project_root)} --answer-stdin --json < ${JSON.stringify(input.file)}`);
+                const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage resume ${run.id} --stage ${next.stage} --work ${input.work_id} --project-root ${quote([run.project_root])} --answer-file ${quote([input.file])} --json`);
                 const receipt = await prompt(state.sessions[state.current_session], `The user supplied the raw answer for pause ${pause.id}. Your first tool call must be this exact standalone command:\n\n${command}\n\nDo not alter the answer. Follow the returned packet, then stop at this Stage boundary.`, `${answer.operation_id}:prompt:${row.generation}`);
                 context.db.run("UPDATE run_controller_operations SET status = 'completed', receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify({ delivered: true, session_id: adapterSessionId(receipt) }), context.now(), answer.operation_id]);
                 state.last_continuation = null;
@@ -693,7 +694,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 const responseFile = path.join(row.state_dir, `${next.stage}-${next.attempt ?? 1}.stage-start-response.json`);
                 const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage start ${run.id} --stage ${next.stage} --project-root ${JSON.stringify(run.project_root)} --context-file ${JSON.stringify(stageContext.file)} --context-sha256 ${stageContext.sha256} --require-session-binding --response-file ${JSON.stringify(responseFile)} --json --progress-jsonl`);
                 appendEvent(context, row.controller_id, "stage_entered", { stage: next.stage, session_id: session.id, context_sha256: stageContext.sha256 });
-                await prompt(session, controllerStageEntryPrompt(next.stage, command, responseFile));
+                await prompt(session, controllerStageEntryPrompt(next.stage, command));
                 continue;
             }
             if (state.current_session === null)

package/dist/services/stage-pause.js

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { quote } from "shell-quote";
 import { lifecycleRetryCommands, managedLifecycleCommand } from "./lifecycle-invocations.js";
 import { AppError } from "../shared/errors.js";
 import { entityReferenceVariants, shortEntityReference } from "../shared/entity-references.js";
@@ -49,8 +50,9 @@ export function pauseStageForUser(context, input) {
         throw error;
     }
     refreshRunWorkProjection(context, project.id, run.id);
-    const resume = stageResumeCommand(context, { runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot });
-    const resumeTemplate = `${resume} <<'USER_ANSWER'\n<paste the complete user answer exactly>\nUSER_ANSWER`;
+    const answerInputPath = path.join(pauseRoot, "answer-input.md");
+    const resume = stageResumeCommand(context, { runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, answerInputPath });
+    const resumeTemplate = `Write the complete user answer exactly to ${quote([answerInputPath])}, then run:\n${resume}`;
     return {
         ok: true,
         outcome: "paused",
@@ -59,7 +61,7 @@ export function pauseStageForUser(context, input) {
         stage: stage.stage,
         pause: { id: pauseId, reason: "waiting_for_user", question_path: questionPath, user_message: question },
         next_action: "ask_user_then_resume_same_stage",
-        agent_instruction: "Send user_message to the user and stop this Turn. When the user answers, do not interpret or edit the answer first: make resume_command the first flow command, pass the complete raw answer on stdin, then follow the returned continuation prompt. Do not create a RUN, Work, attempt, or stage start.",
+        agent_instruction: `Send user_message to the user and stop this Turn. When the user answers, write the complete raw answer without interpretation to ${answerInputPath}, then make resume_command the first flow command and follow the returned continuation prompt. Do not create a RUN, Work, attempt, or stage start.`,
         resume_command: resume,
         resume_command_template: resumeTemplate
     };
@@ -157,15 +159,13 @@ export function resumeStageAfterUser(context, input) {
     return { ok: true, outcome: "resumed", run_id: run.id, work_id: work.work_id, stage: stage.stage, pause_id: pause.id, question_path: pause.question_path, answer_path: answerPath, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, next_action: `continue_${stage.stage}` };
 }
 export function stagePauseCommand(context, input) {
-    return managedLifecycleCommand(context, `${flowCommand(context)} stage pause ${shortEntityReference(input.runId)} --stage ${input.stage} --work ${shortEntityReference(input.workId)} --question-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`);
+    const questionInputPath = `@run/works/${input.workId}/question-input.md`;
+    return managedLifecycleCommand(context, `${flowCommand(context)} stage pause ${shortEntityReference(input.runId)} --stage ${input.stage} --work ${shortEntityReference(input.workId)} --question-file '${questionInputPath}' --project-root ${quote([input.projectRoot])} --json`);
 }
-/**
- * The only shell form allowed for an agent-owned HITL pause.  Supplying a
- * complete heredoc makes stdin explicit without asking an agent to invent a
- * pipe, a temporary file or a second command.
- */
+/** Render separate file-write and lifecycle-call instructions for HITL. */
 export function stagePauseCommandTemplate(command) {
-    return `${command} <<'USER_QUESTION'
+    const questionFile = command.match(/--question-file\s+(?:'([^']*)'|"([^"]*)"|(\S+))/)?.slice(1).find(Boolean) ?? "<question-file-from-command>";
+    return `Write this text to ${questionFile}:
 ## Q-001 — <short decision title>
 
 Why this decision is required:
@@ -180,10 +180,12 @@ Recommendation:
 
 Effect on scope or acceptance:
 - <one sentence>
-USER_QUESTION`;
+
+Then run this standalone command:
+${command}`;
 }
 function stageResumeCommand(context, input) {
-    return managedLifecycleCommand(context, `${flowCommand(context)} stage resume ${shortEntityReference(input.runId)} --stage ${input.stage} --work ${shortEntityReference(input.workId)} --answer-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`);
+    return managedLifecycleCommand(context, `${flowCommand(context)} stage resume ${shortEntityReference(input.runId)} --stage ${input.stage} --work ${shortEntityReference(input.workId)} --answer-file ${quote([input.answerInputPath])} --project-root ${quote([input.projectRoot])} --json`);
 }
 export function flowCommand(context) {
     const defaultHome = path.resolve(path.join(os.homedir(), ".dd-flow"));

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

@@ -225,7 +225,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_task_file: `@run/intake/code-review-repair-${failed[0].id}.md`,
+            repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-file @run/intake/code-review-repair-${failed[0].id}.md --project-root ${JSON.stringify(projectRoot)} --json`,
             retry_command: finishCommand(context, run.id, projectRoot, decisionFile, failed[0].id)
         });
     const stopTarget = executionStopTarget(run);

package/dist/services/vnext-code.js

@@ -211,7 +211,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_task_file: `@run/intake/code-repair-${failed[0].id}.md`,
+            repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-file @run/intake/code-repair-${failed[0].id}.md --project-root ${JSON.stringify(projectRoot)} --json`,
             retry_command: finishCommand(context, run.id, projectRoot, input.verificationFile, failed[0].id)
         });
     }
@@ -500,9 +501,9 @@ function coordinatorPrompt(context, input) {
         "<execution_commands>",
         "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: " + `${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(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. Its repair_command only creates the repair Work; use it with the required origin Work IDs, then end the Turn. Do not invoke that new 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. Record it without finishing CODE: ${flowCommand(context)} stage block ${input.run.id} --stage code --work ${input.rootWork.work_id} --kind <engine|harness|environment> --code <stable-code> --summary-stdin --retryable --project-root ${JSON.stringify(input.projectRoot)} --json. Repair it externally, then run the exact unblock_command returned by dd-flow and continue this same stage.`,
+        `A repairable engine, harness, or environment failure is not a user question. Write the evidence summary to @run/works/${input.rootWork.work_id}/block-summary.md, then record it with a separate command: ${flowCommand(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 ${JSON.stringify(input.projectRoot)} --json. Repair it externally, then run the exact unblock_command returned by dd-flow and continue this same stage.`,
         `When every CODE and repair Work is completed, write ${path.join(input.root, "code-verification.json")} using the exact contract below. Mark passed only when all accepted requirements and current-gate acceptance criteria are implemented or explicitly evidenced; list every remaining issue in unresolved. Every evidence_refs item must already exist as a relative workspace path or run://${input.run.id}/ path. Do not claim a browser or other check receipt that was not retained. Then finish: ${finishCommand(context, input.run.id, input.projectRoot, path.join(input.root, "code-verification.json"))}`,
-        "If the aggregate gate fails, do not stop after `code_gate_failed`: that rejected finish does not create a repair Work. In the same coordinator Turn, use its returned repair command with the relevant completed origin Work IDs and a concise repair objective, then stop so the runner can dispatch the newly declared repair. Do not edit invisibly in the root orchestrator.",
+        "If the aggregate gate fails, do not stop after `code_gate_failed`: that rejected finish does not create a repair Work. In the same coordinator Turn, write the concise repair objective to repair_task_file, then use the returned standalone repair_command with the relevant completed origin Work IDs and stop so the runner can dispatch the newly declared repair. Do not edit invisibly in the root orchestrator.",
         "</execution_commands>",
         "",
         "<verification_contract>",

package/dist/services/vnext-merge.js

@@ -11,7 +11,7 @@ import { requireProjectByRoot } from "./projects.js";
 import { nextMergeRequestId } from "./ids.js";
 import { readProjectConfig } from "./config.js";
 import { appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, gitFacts, prepareFlowRunStageAttachment, prepareVnextMergeSourceRepairAttempt } from "./runs.js";
-import { flowCommand, stagePauseCommandTemplate } from "./stage-pause.js";
+import { flowCommand, stagePauseCommand, stagePauseCommandTemplate } from "./stage-pause.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";
@@ -290,7 +290,7 @@ export async function finishVnextMerge(context, input, prepared = prepareVnextMe
     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_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, failed[0].id) });
+        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: repairCommand(context, request, projectRoot), retry_command: finishCommand(context, run.id, request, projectRoot, failed[0].id) });
     }
     const passedRefs = new Set(receipts.flatMap((receipt) => receipt.check_refs));
     const missingRefs = frozenGateRefs(gate).filter((ref) => !passedRefs.has(ref));
@@ -429,7 +429,7 @@ export async function repairVnextMerge(context, input) {
     appendFlowRunTimelineEvent(context, project.id, request.run_id, { type: "merge_source_repair_created", merge_request_id: request.merge_request_id, repair_work_id: repair.repair_work_id, cycle: prepared.cycle, failed_receipt_ids: failed });
     return { ok: true, run_id: request.run_id, merge_request_id: request.merge_request_id, status: "superseded", source_repair: repair, next: { kind: "start_stage", stage: "code", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${request.run_id} --stage code --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`) } };
 }
-function mergePrompt(context, input, checks, settings) { const pause = managedLifecycleCommand(context, `${flowCommand(context)} stage pause ${input.run.id} --stage merge --work ${input.request.executor_work_id} --project-root ${JSON.stringify(input.projectRoot)} --question-stdin --json`); const repair = `${flowCommand(context)} merge repair ${input.request.merge_request_id} --project-root ${JSON.stringify(input.projectRoot)} --json`; return ["<stage_identity>", `- RUN: ${input.run.id}`, `- MERGE request: ${input.request.merge_request_id}`, `- Work: ${input.request.executor_work_id}`, "- stage: merge", "</stage_identity>", "", "<trusted_runtime_context>", `- integration workspace: ${input.request.target_workspace}`, `- source workspace: ${input.request.source_workspace}`, `- frozen source commit: ${input.request.source_commit}`, `- target branch: ${input.request.target_branch}`, `- execution target baseline: ${input.request.execution_target_head}`, `- queue route: ${input.request.execution_route}`, `- delivery: ${JSON.stringify(settings.merge_delivery)}`, `- cleanup: ${JSON.stringify(settings.merge_cleanup)}`, "These facts and the acquired project integration lane were established by dd-flow. Do not repeat discovery and do not run git merge/rebase/squash yourself.", "</trusted_runtime_context>", "", "<effective_merge_gate>", ...checks.map((check) => `- ${check.canonical_ref ?? check.id}: ${check.command} — ${check.purpose}`), "</effective_merge_gate>", "", "<execution_contract>", `1. Run this exact standalone command first: ${applyCommand(context, input.request, input.projectRoot)}`, "2. If it reports conflicts, resolve only the actual unmerged paths in the integration workspace. Do not repeat merge apply and do not edit product code, tests, documentation or configuration merely to make a gate pass.", `3. Write the compact semantic result to ${input.resultPath}:`, "```json", JSON.stringify({ schema_id: "dd-flow/merge-result@1", outcome: "completed", summary: "What was integrated.", conflict_resolution: "How material conflicts were resolved, or empty when none.", verification_summary: "Why the integrated result is ready for deterministic checks.", residual_risks: [] }, null, 2), "```", `4. Finish with this exact standalone command and wait for all progress: ${finishCommand(context, input.run.id, input.request, input.projectRoot)}`, `If a gate fails, read its receipt and logs and determine the cause. For a product defect use ${repair}; it restores the target baseline and opens CODE → independent CODE-REVIEW → replacement MRG. For an environment failure restore the declared environment in this MERGE and use the returned finish command with --retry-check <receipt-id> --reason "<what was restored>". The CLI reruns the real gate and retains the old receipt. Never edit product code in the integration target to make a gate pass.`, "If a material conflict has no reasonable answer in accepted evidence, pause this same Work with the exact heredoc below, ask the returned user_message, then use the exact resume command returned by CLI:", "```sh", stagePauseCommandTemplate(pause), "```", "</execution_contract>", ""].join("\n"); }
+function mergePrompt(context, input, checks, settings) { const pause = stagePauseCommand(context, { runId: input.run.id, stage: "merge", workId: input.request.executor_work_id, projectRoot: input.projectRoot }); const repair = repairCommand(context, input.request, input.projectRoot); return ["<stage_identity>", `- RUN: ${input.run.id}`, `- MERGE request: ${input.request.merge_request_id}`, `- Work: ${input.request.executor_work_id}`, "- stage: merge", "</stage_identity>", "", "<trusted_runtime_context>", `- integration workspace: ${input.request.target_workspace}`, `- source workspace: ${input.request.source_workspace}`, `- frozen source commit: ${input.request.source_commit}`, `- target branch: ${input.request.target_branch}`, `- execution target baseline: ${input.request.execution_target_head}`, `- queue route: ${input.request.execution_route}`, `- delivery: ${JSON.stringify(settings.merge_delivery)}`, `- cleanup: ${JSON.stringify(settings.merge_cleanup)}`, "These facts and the acquired project integration lane were established by dd-flow. Do not repeat discovery and do not run git merge/rebase/squash yourself.", "</trusted_runtime_context>", "", "<effective_merge_gate>", ...checks.map((check) => `- ${check.canonical_ref ?? check.id}: ${check.command} — ${check.purpose}`), "</effective_merge_gate>", "", "<execution_contract>", `1. Run this exact standalone command first: ${applyCommand(context, input.request, input.projectRoot)}`, "2. If it reports conflicts, resolve only the actual unmerged paths in the integration workspace. Do not repeat merge apply and do not edit product code, tests, documentation or configuration merely to make a gate pass.", `3. Write the compact semantic result to ${input.resultPath}:`, "```json", JSON.stringify({ schema_id: "dd-flow/merge-result@1", outcome: "completed", summary: "What was integrated.", conflict_resolution: "How material conflicts were resolved, or empty when none.", verification_summary: "Why the integrated result is ready for deterministic checks.", residual_risks: [] }, null, 2), "```", `4. Finish with this exact standalone command and wait for all progress: ${finishCommand(context, input.run.id, input.request, input.projectRoot)}`, `If a gate fails, read its receipt and logs and determine the cause. For a product defect use ${repair}; it restores the target baseline and opens CODE → independent CODE-REVIEW → replacement MRG. For an environment failure restore the declared environment in this MERGE and use the returned finish command with --retry-check <receipt-id> --reason "<what was restored>". The CLI reruns the real gate and retains the old receipt. Never edit product code in the integration target to make a gate pass.`, "If a material conflict has no reasonable answer in accepted evidence, pause this same Work by writing the question file and then running the separate standalone command below, ask the returned user_message, then use the exact resume command returned by CLI:", "```sh", stagePauseCommandTemplate(pause), "```", "</execution_contract>", ""].join("\n"); }
 function mergeReport(context, run, request, semantic, receipts) { const now = context.now(); const cleanup = cleanupReceiptPath(run); return { schema_id: "dd-flow/stage-report@2", run_id: run.id, stage, generated_at: now, verdict: "done", summary: semantic.summary, semantic: { result: semantic.summary, acceptance: ["source_commit_frozen", "integration_commit_created", "merge_gate_passed", "delivery_confirmed"], changed_files: [], checks: receipts.map((item) => item.command), evidence: [applyReceiptPath(context, request), ...receipts.map((item) => item.receipt_path), ...(fs.existsSync(cleanup) ? [cleanup] : [])], next_action: "merge_completed", merge: { merge_request_id: request.merge_request_id, work_id: request.executor_work_id, protocols: JSON.parse(request.protocol_ids_json), source_commit: request.source_commit, execution_target_head: request.execution_target_head, accepted_tree: request.accepted_tree, integration_commit: request.integration_commit, route: request.execution_route, delivery: executionSettings(run).merge_delivery, cleanup: executionSettings(run).merge_cleanup, verification_summary: semantic.verification_summary, residual_risks: semantic.residual_risks } }, mechanical: { started_at: request.lock_acquired_at, finished_at: now, git: gitFacts(request.target_workspace), queue: queueStatus(context, request) }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html" }, validation: { status: "passed" } }; }
 function effectiveMergeChecks(run, request) { return readFrozenMergeGate(path.join(requireHome(run), stageDir, "merge-gate.json"), request.merge_request_id).checks; }
 function planChecks(workspace, protocols) { return protocols.flatMap((protocol) => { const file = path.join(workspace, ".memory-bank", "protocol", protocol, "plan.json"); if (!fs.existsSync(file))
@@ -588,5 +588,6 @@ function findRootWork(context, projectId, runId) { const work = context.db.get("
     throw new AppError("runtime_missing", "vNext RUN has no root Work", 1); return work; }
 function requireRootWork(context, projectId, runId) { const work = findRootWork(context, projectId, runId); if (work.status !== "running")
     throw new AppError("runtime_missing", "vNext RUN has no running root Work", 1); return work; }
-function applyCommand(context, request, projectRoot) { return `${flowCommand(context)} merge apply ${request.merge_request_id} --work ${request.executor_work_id} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`; }
+function applyCommand(context, request, projectRoot) { return managedLifecycleCommand(context, `${flowCommand(context)} merge apply ${request.merge_request_id} --work ${request.executor_work_id} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`); }
+function repairCommand(context, request, projectRoot) { return managedLifecycleCommand(context, `${flowCommand(context)} merge repair ${request.merge_request_id} --project-root ${JSON.stringify(projectRoot)} --json`); }
 export function finishCommand(context, runId, request, projectRoot, retryCheckId) { const retry = retryCheckId ? ` --retry-check ${retryCheckId} --reason "<environment recovery evidence>"` : ""; return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage merge --request ${request.merge_request_id} --work ${request.executor_work_id} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl${retry}`); }

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

@@ -316,7 +316,7 @@ function orchestratorPrompt(context, input) {
     const reviewerLaunch = capacity.source === "external_policy"
         ? `After dispatch, return at the Work-graph boundary. The shared runtime launches the queued reviewer Works as separate external Sessions, at most ${capacity.available_slots} in parallel under the RUN's frozen profiles. Do not launch native children, create provider roots, run a capacity probe, or record this external limit as native capacity. Reviewers are read-only leaf workers. Continue the semantic decision only after their Work receipts settle; do not substitute a missing result or relaunch a settled reviewer.`
         : "After dispatch, stop at the Work-graph boundary. The shared controller supplies the selected adapter's native tool, exact parameters, child task, and wait contract; do not choose a provider tool from this stage prompt or substitute a shell command. It launches at most the qualified capacity at once and starts unchanged queued Works only after the current wave settles. A launch rejected before it starts is not review evidence: do not create a replacement. Each reviewer must be a genuinely fresh harness child Session; the lifecycle adapter binds that observed Session, so do not bind or supply a Session ID manually. Reviewers are read-only and must not create children. As soon as a reviewer result is accepted, release that reviewer Session when the harness permits.";
-    return ["<stage_identity>", `- RUN: ${input.run.id}`, `- Work: ${input.workId}`, "- Stage: plan-review", `- Mode: ${input.effective}`, "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility, permission or schema discovery.", `- Project root: ${input.projectRoot}`, `- Stage workspace: ${input.root}`, `- PLAN revision: ${revision}`, `- PLAN report checksum: ${input.planChecksum}`, `- Generated CODE batch checksum: ${input.batchChecksum}`, "</trusted_runtime_context>", "", workspaceContract, "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", `Dispatch fresh reviewers: ${dispatchCommand(context, input.run.id, input.projectRoot)}`, `If dispatch reports qualified_capacity_required, stop. The external harness controller qualifies the selected profile outside this RUN and records the resulting integer with ${capacityRecordCommand(context, input.run.id, input.projectRoot, "<qualified-native-child-count>")}. PLAN-REVIEW never launches a capacity probe.`, reviewerLaunch, "Review the execution environment of every selected check as part of its proof: a reset/fixture process, service process and client process must share the intended data and configuration world. A runtime entrypoint that can break that invariant must be explicit in one Work's task and verification and ordered before its consumer. planned_write_areas may advertise likely overlap, but do not treat them as ownership; required_read alone is not a delivery plan.", "If the final decision needs user input with no reasonable default, run this exact one-command heredoc, replacing only its placeholder body. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:", "```sh", input.pauseCommandTemplate, "```", "Ask the returned user_message, stop, then resume this same PLAN-REVIEW Work. Do not write decision.json or finish first.", `When all reviewer results are complete and every user question is resolved, classify every material finding, fix accepted findings in this same PLAN-REVIEW Work, then write ${decision} and finish: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer findings use local FIND-NNN ids. dd-flow exposes each finding to this coordinator as WRK-.../FIND-NNN; use that canonical finding_ref in the decision.", "A completed reviewer result with needs_changes or blocked is evidence, not the stage outcome. Classify its material findings and apply accepted fixes in this one review pass; do not start a second review automatically. Only a missing, malformed or unfinished reviewer result blocks the stage. For an accepted correction, increment PLAN revision and update only plan.json and the relevant aspect map. Do not edit or list code-work-batch.json: the CLI validates final PLAN and regenerates it. If no material correction is needed, set correction.status=not_required. The CLI checks mechanical handoff coherence; it does not prove semantic correctness.", "```json", JSON.stringify({ schema_id: "dd-flow/plan-review-decision@3", outcome: "accepted | failed | cancelled", summary: "Concise evidence-backed final decision.", finding_decisions: [{ finding_ref: "WRK-001-review/FIND-001", decision: "accepted_fix | rejected | deferred_as_DEF | requires_user | duplicate", reason: "Why." }], correction: { status: "not_required | applied", previous_plan_revision: revision, changed_paths: [], summary: "No material correction was needed, or summarize the applied correction." } }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
+    return ["<stage_identity>", `- RUN: ${input.run.id}`, `- Work: ${input.workId}`, "- Stage: plan-review", `- Mode: ${input.effective}`, "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility, permission or schema discovery.", `- Project root: ${input.projectRoot}`, `- Stage workspace: ${input.root}`, `- PLAN revision: ${revision}`, `- PLAN report checksum: ${input.planChecksum}`, `- Generated CODE batch checksum: ${input.batchChecksum}`, "</trusted_runtime_context>", "", workspaceContract, "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", `Dispatch fresh reviewers: ${dispatchCommand(context, input.run.id, input.projectRoot)}`, `If dispatch reports qualified_capacity_required, stop. The external harness controller qualifies the selected profile outside this RUN and records the resulting integer with ${capacityRecordCommand(context, input.run.id, input.projectRoot, "<qualified-native-child-count>")}. PLAN-REVIEW never launches a capacity probe.`, reviewerLaunch, "Review the execution environment of every selected check as part of its proof: a reset/fixture process, service process and client process must share the intended data and configuration world. A runtime entrypoint that can break that invariant must be explicit in one Work's task and verification and ordered before its consumer. planned_write_areas may advertise likely overlap, but do not treat them as ownership; required_read alone is not a delivery plan.", "If the final decision needs user input 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", input.pauseCommandTemplate, "```", "Ask the returned user_message, stop, then resume this same PLAN-REVIEW Work. Do not write decision.json or finish first.", `When all reviewer results are complete and every user question is resolved, classify every material finding, fix accepted findings in this same PLAN-REVIEW Work, then write ${decision} and finish: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer findings use local FIND-NNN ids. dd-flow exposes each finding to this coordinator as WRK-.../FIND-NNN; use that canonical finding_ref in the decision.", "A completed reviewer result with needs_changes or blocked is evidence, not the stage outcome. Classify its material findings and apply accepted fixes in this one review pass; do not start a second review automatically. Only a missing, malformed or unfinished reviewer result blocks the stage. For an accepted correction, increment PLAN revision and update only plan.json and the relevant aspect map. Do not edit or list code-work-batch.json: the CLI validates final PLAN and regenerates it. If no material correction is needed, set correction.status=not_required. The CLI checks mechanical handoff coherence; it does not prove semantic correctness.", "```json", JSON.stringify({ schema_id: "dd-flow/plan-review-decision@3", outcome: "accepted | failed | cancelled", summary: "Concise evidence-backed final decision.", finding_decisions: [{ finding_ref: "WRK-001-review/FIND-001", decision: "accepted_fix | rejected | deferred_as_DEF | requires_user | duplicate", reason: "Why." }], correction: { status: "not_required | applied", previous_plan_revision: revision, changed_paths: [], summary: "No material correction was needed, or summarize the applied correction." } }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
 }
 function reviewGroups(home, workspaceRoot) {
     const root = path.join(home, "03-plan");

package/dist/services/vnext-plan.js

@@ -106,7 +106,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.", "Use protocol-plan@6. Its top-level checks[] is the single check catalog. Every check has id, command, purpose, run_at and availability. available means executable now. planned means one named P* Work first creates a NEW @check/... alias: planned therefore always needs provided_by and the exact alias definition. Every semantic @check alias, including an existing one, repeats its exact accepted profile command in definition so later stages can detect drift. Items and acceptance entries use check_refs only; never duplicate command declarations.", "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 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, run this exact one-command heredoc, replacing only its placeholder body. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second 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.", "Use protocol-plan@6. Its top-level checks[] is the single check catalog. Every check has id, command, purpose, run_at and availability. available means executable now. planned means one named P* Work first creates a NEW @check/... alias: planned therefore always needs provided_by and the exact alias definition. Every semantic @check alias, including an existing one, repeats its exact accepted profile command in definition so later stages can detect drift. Items and acceptance entries use check_refs only; never duplicate command declarations.", "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 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

package/dist/services/vnext-protocolize.js

@@ -481,7 +481,7 @@ function resultTemplate(obligations = []) {
 }
 function renderPrompt(input) {
     const obligationList = input.obligations.map((obligation) => `- ${obligation.id}: ${obligation.statement}`).join("\n");
-    return ["<work_context>", `- RUN: ${input.runId}`, `- Work: ${input.workId}`, `- Accepted SPECIFY JSON: ${input.specifyPath}`, `- Handoff: ${input.handoff.stage_handoff.effective}`, "</work_context>", "", "<accepted_obligations>", obligationList, "</accepted_obligations>", "", "<frozen_git_policy>", `- route: ${input.policy.route}`, `- integration branch: ${input.policy.integration_branch ?? "not applicable"}`, `- base ref: ${input.policy.base_ref ?? "not applicable"}`, `- feature branch: ${input.policy.feature_branch ?? "not applicable"}`, `- service worktree: ${input.policy.worktree_path ?? "not applicable"}`, `- bootstrap: ${input.policy.bootstrap_status}`, `- decision: ${input.policy.reason}`, "The CLI already created and bootstrapped this workspace at PROTOCOLIZE start. Do not create branches, worktrees, protocol files or Git commits yourself. This transition Work may run from the stable session; edit only the supplied RUN result file.", "</frozen_git_policy>", "", "<catalog>", input.catalog.length ? input.catalog.map((x) => `- ${x}`).join("\n") : "- inactive", "</catalog>", "", "<stage_instructions>", input.template.trim(), "</stage_instructions>", "", "<output_contract>", `Edit only ${input.resultPath}. Keep this exact JSON shape; CLI allocates ids and writes PRT/PSET/feature documents in the already provisioned workspace:\n\n\`\`\`json\n${JSON.stringify(resultTemplate(), null, 2)}\n\`\`\``, "Allocate every supplied R-* and AC-* exactly once in obligation_ownership. The CLI rejects unknown, duplicate or missing obligations, and every member must own at least one AC-*.", "If PROTOCOLIZE itself exposes a material user decision with no reasonable default, do not finish and do not return to SPECIFY. Run this exact one-command heredoc, replacing only its placeholder body. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:", "```sh", input.pauseCommandTemplate, "```", "Ask the returned user_message and stop. Resume this same PROTOCOLIZE Work using the exact command returned by pause.", `When the answer is incorporated and the result is protocolized, finish:\n\n${input.finishCommand}`, "</output_contract>", ""].join("\n");
+    return ["<work_context>", `- RUN: ${input.runId}`, `- Work: ${input.workId}`, `- Accepted SPECIFY JSON: ${input.specifyPath}`, `- Handoff: ${input.handoff.stage_handoff.effective}`, "</work_context>", "", "<accepted_obligations>", obligationList, "</accepted_obligations>", "", "<frozen_git_policy>", `- route: ${input.policy.route}`, `- integration branch: ${input.policy.integration_branch ?? "not applicable"}`, `- base ref: ${input.policy.base_ref ?? "not applicable"}`, `- feature branch: ${input.policy.feature_branch ?? "not applicable"}`, `- service worktree: ${input.policy.worktree_path ?? "not applicable"}`, `- bootstrap: ${input.policy.bootstrap_status}`, `- decision: ${input.policy.reason}`, "The CLI already created and bootstrapped this workspace at PROTOCOLIZE start. Do not create branches, worktrees, protocol files or Git commits yourself. This transition Work may run from the stable session; edit only the supplied RUN result file.", "</frozen_git_policy>", "", "<catalog>", input.catalog.length ? input.catalog.map((x) => `- ${x}`).join("\n") : "- inactive", "</catalog>", "", "<stage_instructions>", input.template.trim(), "</stage_instructions>", "", "<output_contract>", `Edit only ${input.resultPath}. Keep this exact JSON shape; CLI allocates ids and writes PRT/PSET/feature documents in the already provisioned workspace:\n\n\`\`\`json\n${JSON.stringify(resultTemplate(), null, 2)}\n\`\`\``, "Allocate every supplied R-* and AC-* exactly once in obligation_ownership. The CLI rejects unknown, duplicate or missing obligations, and every member must own at least one AC-*.", "If PROTOCOLIZE itself exposes a material user decision with no reasonable default, do not finish and do not return to SPECIFY. 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", input.pauseCommandTemplate, "```", "Ask the returned user_message and stop. Resume this same PROTOCOLIZE Work using the exact command returned by pause.", `When the answer is incorporated and the result is protocolized, finish:\n\n${input.finishCommand}`, "</output_contract>", ""].join("\n");
 }
 function prepareWorkspaceForProtocolize(context, projectRoot, projectId, run, stageRoot) {
     const receiptPath = path.join(stageRoot, "workspace-route.json");

package/dist/services/vnext-specify.js

@@ -407,7 +407,7 @@ function renderPrompt(input) {
         "```",
         "The JSON must preserve the problem-space contract for a fresh PROTOCOLIZE worker: user intent, scope, acceptance and verification, settled defaults, relevant project facts, gap-method outcomes, task assessment, delivery shape and handoff. Use stable R-001... identifiers in requirements and AC-001... identifiers in acceptance_criteria. Do not describe implementation design.",
         "Do not finish while a material user question remains. Use stage pause instead of adding a question to specify.json.",
-        "If a user answer is required, make this the lifecycle command instead of finish. Run this exact one-command heredoc, replacing only the placeholder body with the concise user-facing question packet. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:",
+        "If a user answer is required, use the file and standalone lifecycle command below instead of finish. Write only the concise user-facing question packet to the named text file; do not combine file creation and dd-flow in one shell command:",
         "```sh",
         input.pauseCommandTemplate,
         "```",

package/dist/services/work-registry.js

@@ -2,6 +2,7 @@ import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { quote } from "shell-quote";
 import { AppError } from "../shared/errors.js";
 import { entityReferenceVariants, shortEntityReference } from "../shared/entity-references.js";
 import { resolveWorkReference } from "../storage/work-references.js";
@@ -974,7 +975,8 @@ export function validateReviewResolutions(workId, assigned, resolutions) {
 function renderWorkerPrompt(context, work, run, dependencies) {
     const command = flowCommand(context);
     const packet = codePacket(work);
-    const finishWorkCommand = managedLifecycleCommand(context, `${command} work finish ${work.work_id} --result-stdin --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`);
+    const resultInputPath = path.join(requireRunHome(run), "works", work.work_id, "result-input.json");
+    const finishWorkCommand = managedLifecycleCommand(context, `${command} work finish ${work.work_id} --result-file ${quote([resultInputPath])} --project-root ${quote([run.project_root])} --json --progress-jsonl`);
     const failWorkCommand = managedLifecycleCommand(context, `${command} work fail ${shortWorkId(work.work_id)} --reason "receipt path + exact external or semantic blocker" --project-root ${JSON.stringify(run.project_root)} --json`);
     const mergeWork = parsePayload(work)?.kind === "merge";
     const writeBoundary = mergeWork
@@ -988,7 +990,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>", "", "<cli_context>", `- Work commands use the short ID ${shortWorkId(work.work_id)}; dd-flow binds it to this RUN.`, `- @project = ${run.project_root}`, `- @workspace = ${run.workspace_root}`, `- @run = ${requireRunHome(run)}`, "- @ aliases are accepted only by declared dd-flow path parameters. Copy the quoted alias literally; do not add backslashes. Shell tools such as cat and rg require ordinary paths relative to cwd or absolute paths.", "- Lifecycle invocation IDs are internal runtime authority and are intentionally omitted from commands.", "</cli_context>", "", "<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 with a quoted heredoc (replace the example JSON with your result):\n${finishWorkCommand} <<'DD_FLOW_RESULT'\n{}\nDD_FLOW_RESULT`, `Fail only for an evidenced external or semantic-contract blocker: ${failWorkCommand}`, "</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>", "", "<cli_context>", `- Work commands use the short ID ${shortWorkId(work.work_id)}; dd-flow binds it to this RUN.`, `- @project = ${run.project_root}`, `- @workspace = ${run.workspace_root}`, `- @run = ${requireRunHome(run)}`, "- @ aliases are accepted only by declared dd-flow path parameters. Copy the quoted alias literally; do not add backslashes. Shell tools such as cat and rg require ordinary paths relative to cwd or absolute paths.", "- Lifecycle invocation IDs are internal runtime authority and are intentionally omitted from commands.", "</cli_context>", "", "<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), `Write the completed JSON to ${resultInputPath}. This is an attempt input, not the canonical result.json receipt. dd-flow validates the file and atomically 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.", `First write only the result JSON to ${resultInputPath}. Then run this standalone command:\n${finishWorkCommand}`, `Fail only for an evidenced external or semantic-contract blocker: ${failWorkCommand}`, "</completion>", ""].join("\n");
 }
 export function resultSchemaGuidance(work, runId) {
     const schema = work.result_schema;

package/package.json

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