@deksden-com/dd-flow-cli 0.9.0-beta.90 → 0.9.0-beta.91

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.91
+
+### Patch Changes
+
+- 8650f0f: Unify managed lifecycle command syntax, preserve terminal preparation errors,
+  bound unchanged retries, and retain causal controller failures through MERGE.
+
 ## 0.9.0-beta.90
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,8 +1,8 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.90",
-  "cli_commit": "a4e9733f871af5032fc372d324d8fd0dfd2ec44f",
-  "built_at": "2026-09-21T11:54:11.387Z",
+  "cli_version": "0.9.0-beta.91",
+  "cli_commit": "82e57ba33fbc4e915c2b5809dd82fe9033969c3a",
+  "built_at": "2026-09-21T18:07:32.802Z",
   "built_with_canon": {
     "version": "4.1.1",
     "commit": "d1a6081ab15ab92ac917ff5d037121a40c709db1",

package/dist/cli/command-inputs.js

@@ -1,5 +1,6 @@
 import { AppError } from "../shared/errors.js";
 import { parseCommandArgs } from "../services/lifecycle-command.js";
+import { lifecycleInternalOptions, lifecycleRouteForOperation } from "../services/lifecycle-contract.js";
 import { isUpgradeAllowlisted } from "../services/cli-operation-classifier.js";
 const words = (value) => value.split(" ").filter(Boolean);
 const route = (positions, required = "", values = "", switches = "", repeatable = "", enums = {}) => ({
@@ -8,7 +9,7 @@ const route = (positions, required = "", values = "", switches = "", repeatable
 });
 const project = "project-root";
 const scoped = "project-root"; // Optional when the router resolves a unique retained scope.
-const lifecycle = "invocation-id hook-event-id";
+const lifecycle = lifecycleInternalOptions.join(" ");
 const worker = "worker-id";
 const control = "project-root run";
 /** Path-shaped arguments default to physical paths unless the route explicitly
@@ -154,8 +155,8 @@ export const commandInputs = {
     "merge serve": route(0, "agent-profile", "poll-seconds max-parallel-projects", "once"),
     "merge server status": route(0),
     "merge server stop": route(1),
-    "merge apply": route(1, `${project} work`),
-    "merge repair": route(1, project),
+    "merge apply": route(1, `${project} work`, lifecycle),
+    "merge repair": route(1, project, lifecycle),
     "merge request status": route(1, project),
     "merge request route": route(1, `${project} mode reason`, "", "", "", { mode: ["same_session", "server"] }),
     "merge status": route(0, project, "path"),
@@ -225,7 +226,7 @@ export const commandInputs = {
     "memory permissions preflight": route(0, "root memory-bank flow mode", "tasks")
 };
 export function contextualPathOptionsForLifecycle(operation) {
-    const key = operation === "recovery_accept" ? "run recovery accept" : operation.replaceAll("_", " ");
+    const key = lifecycleRouteForOperation(operation);
     return new Set(commandInputs[key]?.contextualPaths ?? []);
 }
 const flag = "__dd_flow_flag__";

package/dist/cli/input-preparation.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
 import { AppError, isAppError } from "../shared/errors.js";
 import { validateSchema } from "../services/schema-validation.js";
 export function prepareError(error, input = {}) {
@@ -19,8 +20,8 @@ export function prepareError(error, input = {}) {
         throw new AppError(error.code, error.message, 2, {
             ...error.details,
             phase: "prepare",
-            effect: "no_effect",
-            recoverable: true,
+            effect: error.details.effect ?? "no_effect",
+            recoverable: error.details.recoverable ?? true,
             ...input
         });
     }
@@ -68,7 +69,7 @@ export function prepareJsonText(text, input) {
         // safe correction-and-retry condition.
         throw new AppError("invalid_json", `Invalid JSON in ${input.label ?? "input"}: ${input.file}`, 2, {
             phase: "prepare", effect: "no_effect", recoverable: true, file: input.file, label: input.label ?? "input",
-            cause: "Invalid JSON syntax"
+            cause: "Invalid JSON syntax", input_sha256: crypto.createHash("sha256").update(text).digest("hex")
         });
     }
 }

package/dist/cli/run-cli.js

@@ -217,7 +217,17 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         if (invocationId) {
             const command = quote(["dd-flow", ...invocationArgs]);
             const admission = await awaitLifecycleInvocation(dispatchContext, { id: invocationId, command,
-                validateArgs: () => { preparedRoute = prepareCommandRoute(invocationArgs); },
+                validateArgs: () => {
+                    try {
+                        preparedRoute = prepareCommandRoute(invocationArgs);
+                    }
+                    catch (error) {
+                        if (error instanceof AppError && error.code === "usage" && ["invocation-id", "hook-event-id"].includes(String(error.details.parameter ?? ""))) {
+                            throw new AppError("lifecycle_contract_invalid", `The runtime generated arguments rejected by its own CLI contract: ${error.message}`, 1, { ...error.details, recoverable: false, operation: observedOperation });
+                        }
+                        throw error;
+                    }
+                },
                 prepare: async () => { preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile, preparedRoute); },
                 assertCurrent: scope => assertLifecycleInvocationCurrent(dispatchContext, scope, command) });
             if (admission.replay) {
@@ -3330,7 +3340,7 @@ function projectRootForMutation(context, args, result, resolvedScope) {
         return projectRootForMergeQueueMutation(context, command, parsed);
     }
     if (family === "merge" && ["one-shot", "apply", "repair", "request"].includes(command ?? "")) {
-        return requiredOption(parsed, "project-root");
+        return resolvedScope ?? requiredOption(parsed, "project-root");
     }
     if (family === "merge-worker" && ["start", "stop"].includes(command ?? "")) {
         return requiredOption(parsed, "project-root");
@@ -3348,7 +3358,7 @@ function projectRootForMutation(context, args, result, resolvedScope) {
         return requiredOption(parsed, "project-root");
     }
     if (family === "stage" && ["start", "pause", "resume", "finish"].includes(command ?? "")) {
-        return requiredOption(parsed, "project-root");
+        return resolvedScope ?? requiredOption(parsed, "project-root");
     }
     if (family === "worktree" && ["create", "bootstrap", "close"].includes(command ?? "")) {
         return protocolProjectRoot(context, requiredOption(parsed, "protocol-id"));

package/dist/services/lifecycle-command.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { parse, quote } from "shell-quote";
+import { lifecycleOperationForArgv } from "./lifecycle-contract.js";
 /** Native hooks and the lightweight ingress must recognize the same shell. */
 export function lifecycleCommandFromPayload(payload) {
     const input = payload.tool_input && typeof payload.tool_input === "object" ? payload.tool_input : {};
@@ -203,33 +204,7 @@ function wrappedInvocationFromSegment(segment) {
     return parseLifecycleCommandInner(payload, true);
 }
 function lifecycleOperation(argv) {
-    // The CLI handles help before dispatch, wherever the flag occurs.
-    if (argv.some(arg => arg === "--help" || arg === "-h"))
-        return null;
-    if (argv[0] === "run" && argv[1] === "recovery" && argv[2] === "accept")
-        return "recovery_accept";
-    const key = `${argv[0] ?? ""} ${argv[1] ?? ""}`;
-    if (key === "session register")
-        return "session_register";
-    if (key === "stage start")
-        return "stage_start";
-    if (key === "stage finish")
-        return "stage_finish";
-    if (key === "stage pause")
-        return "stage_pause";
-    if (key === "stage resume")
-        return "stage_resume";
-    if (key === "work start")
-        return "work_start";
-    if (key === "work finish")
-        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;
+    return lifecycleOperationForArgv(argv);
 }
 export function parseCommandArgs(argv) {
     const positional = [];

package/dist/services/lifecycle-contract.js

@@ -0,0 +1,30 @@
+export const lifecycleRoutes = {
+    "session register": "session_register",
+    "stage start": "stage_start",
+    "stage finish": "stage_finish",
+    "stage pause": "stage_pause",
+    "stage resume": "stage_resume",
+    "work start": "work_start",
+    "work finish": "work_finish",
+    "work fail": "work_fail",
+    "merge apply": "merge_apply",
+    "merge repair": "merge_repair",
+    "run recovery accept": "recovery_accept"
+};
+export const lifecycleInternalOptions = ["invocation-id", "hook-event-id"];
+export function lifecycleOperationForArgv(argv) {
+    if (argv.some(arg => arg === "--help" || arg === "-h"))
+        return null;
+    for (const [route, operation] of Object.entries(lifecycleRoutes)) {
+        const parts = route.split(" ");
+        if (parts.every((part, index) => argv[index] === part))
+            return operation;
+    }
+    return null;
+}
+export function lifecycleRouteForOperation(operation) {
+    const entry = Object.entries(lifecycleRoutes).find(([, value]) => value === operation);
+    if (!entry)
+        throw new Error(`Unknown lifecycle operation: ${operation}`);
+    return entry[0];
+}

package/dist/services/lifecycle-invocations.js

@@ -67,6 +67,8 @@ export function isRetryableLifecycleRejection(code, details = {}) {
         return false;
     if (code === "validation" || code === "schema_validation")
         return details.phase === "prepare" && details.effect === "no_effect" && details.recoverable === true;
+    if (["invocation_command_mismatch", "invocation_argument_mismatch"].includes(code))
+        return details.recoverable !== false;
     return details.recoverable === true || ["work_checks_failed", "code_gate_failed", "code_review_gate_failed", "merge_gate_failed",
         "review_repair_incomplete", "plan_review_incomplete", "semantic_result_invalid",
         "review_evidence_invalid", "evidence_obligation_unknown", "invalid_evidence_ref",
@@ -966,13 +968,78 @@ export function settleLifecyclePreparationRejection(context, id, error) {
         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." };
+        const signature = preparationRejectionSignature(error);
+        const repeated = context.db.all("SELECT outcome_json FROM lifecycle_invocations WHERE scope_json = ? AND fingerprint = ? AND id <> ? AND status = 'settled'", [row.scope_json, row.fingerprint, row.id])
+            .some(prior => { try {
+            return JSON.parse(prior.outcome_json ?? "null")?.error?.details?.rejection_signature === signature;
+        }
+        catch {
+            return false;
+        } });
+        const retryable = !repeated && isRetryableLifecycleRejection(error.code, error.details);
+        const details = { ...error.details, effect: "no_effect", recoverable: retryable, rejection_signature: signature,
+            ...(repeated ? { repeated_without_progress: true } : {}),
+            ...(retryable ? {
+                retry_command: successorLifecycleInvocationCommand(context, row),
+                retry_instruction: "Correct the reported input, then 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;
     });
 }
+function preparationRejectionSignature(error) {
+    const omitted = new Set(["retry_command", "retry_instruction", "invocation_id", "hook_event_id", "rejection_signature"]);
+    const normalize = (value) => {
+        if (Array.isArray(value))
+            return value.map(normalize);
+        if (!value || typeof value !== "object")
+            return value;
+        return Object.fromEntries(Object.entries(value).filter(([key]) => !omitted.has(key)).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, normalize(item)]));
+    };
+    return crypto.createHash("sha256").update(JSON.stringify([error.code, normalize(error.details)])).digest("hex");
+}
+export function currentLifecycleFailure(context, input) {
+    const attempts = context.db.all("SELECT * FROM lifecycle_invocations ORDER BY updated_at DESC, rowid DESC");
+    const scoped = attempts.filter(row => {
+        try {
+            const scope = JSON.parse(row.scope_json);
+            return scope.runId === input.runId && scope.generation === input.generation;
+        }
+        catch {
+            return false;
+        }
+    });
+    const fingerprints = [...new Set(scoped.map(row => row.fingerprint))];
+    for (const fingerprint of fingerprints) {
+        const rows = scoped.filter(row => row.fingerprint === fingerprint);
+        if (rows.some(row => ["issued", "observed", "executing"].includes(row.status)))
+            continue;
+        const row = rows.find(candidate => candidate.status === "settled");
+        if (!row)
+            continue;
+        let outcome;
+        try {
+            outcome = JSON.parse(row.outcome_json ?? "null") ?? {};
+        }
+        catch {
+            continue;
+        }
+        if (!outcome.error?.code || !outcome.error.message)
+            continue;
+        let parsed;
+        try {
+            parsed = invocation(row.command);
+        }
+        catch {
+            continue;
+        }
+        const stage = parsed.operation.startsWith("merge_") ? "merge" : commandOption(parsed, "stage");
+        if (stage !== input.stage)
+            continue;
+        return { code: outcome.error.code, message: outcome.error.message, details: outcome.error.details ?? {}, invocation_id: row.id };
+    }
+    return null;
+}
 /** 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) {

package/dist/services/run-controller.js

@@ -1,4 +1,4 @@
-import { assertLifecycleOutcomes, managedInvocationContext, managedLifecycleCommand } from "./lifecycle-invocations.js";
+import { assertLifecycleOutcomes, currentLifecycleFailure, managedInvocationContext, managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -711,8 +711,12 @@ async function executeController(context, row, manifest, state, assertOwnership,
             const children = controllerNativeChildren(state.last_receipt ?? {}, session.id).filter(child => !baseline.has(child.session_id));
             const fanout = await nextControllerFanout(executionContext, { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles });
             assertOwner();
-            if (fanout.kind === "none")
+            if (fanout.kind === "none") {
+                const cause = currentLifecycleFailure(executionContext, { runId: run.id, generation: row.generation, stage: next.stage });
+                if (cause)
+                    throw new AppError(cause.code, cause.message, 1, { ...cause.details, invocation_id: cause.invocation_id, controller_wrapper: "incomplete_subject_turn", stage: next.stage });
                 throw new AppError("incomplete_subject_turn", "Managed Turn ended without a completed Stage or declared continuation", 1, { stage: next.stage });
+            }
             if (fanout.kind === "wait") {
                 setStatus(fanout.reason === "qualified_capacity_required" ? "waiting_for_capacity" : "waiting_for_children");
                 await delay(1000);

package/package.json

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