@deksden-com/dd-flow-cli 0.9.0-beta.82 → 0.9.0-beta.86

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @deksden-com/dd-flow-cli
 
+## 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
+
+- bf69c56: Accept shell-escaped lifecycle path aliases deterministically and render model-facing aliases with stable quoting.
+
 ## 0.9.0-beta.82
 
 ### Patch Changes
@@ -1230,6 +1257,7 @@ record` command with the bounded 15-probe contract.
 - 16f68a3: Add router-native engine snapshot commands and routed project-command dispatch.
 
   Also include the runtime/dashboard compatibility wave needed by the current Memory Bank canon:
+
   - target-based dashboard `open`/`refresh` commands and related-command help;
   - persisted FIFO lane waiters and merge wait-acquire specialization;
   - `migration plan/report/verify` evidence helpers for controlled `mb-upgrade` runtime migrations;

package/dist/build-info.json

@@ -1,8 +1,8 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.82",
-  "cli_commit": "e6ab8fb3cc284cc7f3c2ca4dd77c4490ef980f76",
-  "built_at": "2026-09-20T10:58:21.835Z",
+  "cli_version": "0.9.0-beta.86",
+  "cli_commit": "979a6151c910228ed3da8daa015bcf89098b04f1",
+  "built_at": "2026-09-20T19:12:05.808Z",
   "built_with_canon": {
     "version": "4.1.1",
     "commit": "97f811d33c212ae3497020178b1ed825c7c3ebac",

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 } from "../services/lifecycle-invocations.js";
+import { assertLifecycleInvocationCurrent, awaitLifecycleInvocation, expandLifecycleInvocationArgs, issueLifecycleInvocation, prepareLifecycleIssuance, lifecycleInvocationScope, 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";
@@ -130,21 +130,44 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         const routerContext = createRouterContext(env);
         const publicCommand = quote(["dd-flow", ...output.args]);
         const lifecycleCommand = parseLifecycleCommand(publicCommand);
+        if (lifecycleCommand.kind === "standalone")
+            validateLifecyclePathAliases(output.args, lifecycleCommand.invocation.operation);
         const observedInvocation = observedLifecycleInvocation(routerContext, publicCommand);
         if (!observedInvocation && !suppliedInvocationId && env.DD_FLOW_DAEMON_ID && lifecycleCommand.kind === "standalone") {
             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(" ")}`);

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,12 +58,53 @@ 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);
     if (key === "project-root" && (path.isAbsolute(value) || value === "@project"))
         return "@project";
     if (["result-file", "decision-file", "verification-file"].includes(key))
@@ -79,12 +120,19 @@ function normalizedInvocationValue(key, value) {
         return shortEntityReference(value);
     return key === "retry-check" ? /(?:^|\/)(RCP-\d{3,})$/.exec(value)?.[1] ?? value : value;
 }
+/** Shell/JSON builders sometimes preserve the shell escape before an alias.
+ * Accept it only for the small declared alias vocabulary. */
+function normalizedPathAlias(value) {
+    return value.replace(/^\\+(?=@(?:project|workspace|run)(?:\/|$))/, "");
+}
+function quoteModelFacingArgs(argv) {
+    return argv.map(value => /^@(project|workspace|run)(?:\/.*)?$/.test(value)
+        ? `'${value.replaceAll("'", `'\\''`)}'`
+        : quote([value])).join(" ");
+}
 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")
@@ -109,14 +157,23 @@ function withoutInvocationId(command, aliases) {
     const executable = parsed.env.DD_FLOW_BIN || parsed.executable === "$DD_FLOW_BIN" ? '"$DD_FLOW_BIN"' : quote([parsed.executable]);
     const prefix = Object.entries(env).map(([key, value]) => `${key}=${quote([value])}`).join(" ");
     const suffix = command.slice(shellSuffixOffset(command)).trimStart();
-    return `${prefix ? `${prefix} ` : ""}${executable}${argv.length ? ` ${quote(argv)}` : ""}${suffix ? ` ${suffix}` : ""}`.trim();
+    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. */
@@ -128,7 +185,10 @@ export function expandLifecycleInvocationArgs(context, args, scope, operation) {
         if (run && !args[index - 1]?.startsWith("--") && [run.short_id, normalizedInvocationValue("positional", run.id)].includes(value) && !operation.startsWith("work_"))
             return run.id;
         const option = args[index - 1]?.replace(/^--/, "");
-        if (!option || !pathOptions.has(option) || !value.startsWith("@"))
+        if (!option || !pathOptions.has(option))
+            return value;
+        value = normalizedPathAlias(value);
+        if (!value.startsWith("@"))
             return value;
         const match = /^@(project|workspace|run)(?:\/(.*))?$/.exec(value);
         if (!match)
@@ -139,6 +199,22 @@ export function expandLifecycleInvocationArgs(context, args, scope, operation) {
         return assertPathWithin(root, path.join(root, match[2] ?? ""), `${match[1]}_alias`);
     });
 }
+/** Validate alias spelling before native-receipt lookup, so a correctable
+ * command typo is never reported as missing infrastructure evidence. */
+export function validateLifecyclePathAliases(args, operation) {
+    const pathOptions = contextualPathOptionsForLifecycle(operation);
+    for (let index = 0; index < args.length; index += 1) {
+        const option = args[index - 1]?.replace(/^--/, "");
+        if (!option || !pathOptions.has(option))
+            continue;
+        const original = args[index];
+        const value = normalizedPathAlias(original);
+        if ((original.startsWith("\\") && original.replace(/^\\+/, "").startsWith("@") && value === original)
+            || (value.startsWith("@") && !/^@(project|workspace|run)(?:\/.*)?$/.test(value))) {
+            throw new AppError("usage", `Unknown path alias: ${original}`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
+        }
+    }
+}
 function canonicalManagedCommand(context, command, scope) {
     const parsed = invocation(command);
     const argv = expandLifecycleInvocationArgs(context, parsed.argv, scope, parsed.operation);
@@ -424,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
@@ -538,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]);
@@ -683,7 +760,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
@@ -733,6 +810,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) {
@@ -752,27 +866,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

@@ -693,7 +693,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/vnext-merge.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 = 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 = 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 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 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/work-registry.js

@@ -988,7 +988,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. 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), "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");
 }
 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.82",
+  "version": "0.9.0-beta.86",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {