@deksden-com/dd-flow-cli 0.9.0-beta.53 → 0.9.0-beta.54

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.54
+
+### Patch Changes
+
+- Preserve current lifecycle command input, atomically settle retry authority, select current resume commands, and stop ZCode productive admission immediately on fatal identity errors. Reject ambiguous result inputs and keep diagnostic commands read-only.
+
 ## 0.9.0-beta.53
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,8 +1,8 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.53",
-  "cli_commit": "db14065f43f320bc69dacbec425cd04eac8236ae",
-  "built_at": "2026-09-13T02:52:44.434Z",
+  "cli_version": "0.9.0-beta.54",
+  "cli_commit": "eb2cb9746a9ee386d40f63791f5dbe0847bf5017",
+  "built_at": "2026-09-13T12:29:37.211Z",
   "built_with_canon": {
     "version": "4.1.0",
     "commit": "ef349bf47cba1c987468e51d73a0dbadbd48dc1f",

package/dist/cli/run-cli.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { quote } from "shell-quote";
-import { assertLifecycleInvocationCurrent, awaitLifecycleInvocation, issueLifecycleInvocation, isRetryableLifecycleRejection, lifecycleInvocationScope, retryLifecycleInvocationCommand, settleLifecycleInvocation } from "../services/lifecycle-invocations.js";
+import { assertLifecycleInvocationCurrent, awaitLifecycleInvocation, issueLifecycleInvocation, lifecycleInvocationScope, settleLifecycleInvocation, settleLifecycleRejection } from "../services/lifecycle-invocations.js";
 import { createContext, createRouterContext } from "../runtime/context.js";
 import { migrateStoreWriter } from "../storage/writer-migration.js";
 import { helpForArgs } from "./help.js";
@@ -72,7 +72,15 @@ const defaultIo = {
 };
 const flagValue = "__dd_flow_flag__";
 export async function runCli(args, io = defaultIo, env = process.env) {
-    const output = parseOutputOptions(args);
+    let output;
+    try {
+        output = parseOutputOptions(args);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeJson(io.stderr, { ok: false, error: { code: "usage", message } });
+        return 2;
+    }
     const progress = progressForCommand(output.args);
     let heartbeat;
     let invocationSettlement;
@@ -90,6 +98,7 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             io.stdout.write(`${help}\n`);
             return 0;
         }
+        assertSingletonOptions(output.args);
         if (io.stdin?.isTTY && ["work", "stage"].includes(output.args[0] ?? "") && output.args[1] === "finish"
             && hasOption(parseArgs(output.args.slice(2)), "result-stdin")) {
             throw new AppError("usage", "--result-stdin requires non-interactive input. Pipe or redirect the complete JSON into this command, or use --result-file; interactive terminals can truncate long JSON and wait indefinitely for EOF.", 2);
@@ -113,7 +122,9 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         if (routed?.routed && !routed.inProcess) {
             if (heartbeat)
                 clearInterval(heartbeat);
-            emitHumanProgress(io, output, progress, "done");
+            emitHumanProgress(io, output, progress, routed.exitCode === 0 ? "done" : "failed");
+            if (output.progressJsonl && routed.exitCode !== 0)
+                writeProgressJsonl(io, "failed", "Routed engine failed", { exit_code: routed.exitCode });
             return routed.exitCode;
         }
         const dispatchContext = routed?.inProcess
@@ -168,21 +179,11 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         if (heartbeat)
             clearInterval(heartbeat);
         if (invocationSettlement) {
-            // Optional retry preparation must never prevent recording the primary
-            // operation rejection. Otherwise a known failure becomes an unknown run.
-            if (isAppError(error) && isRetryableLifecycleRejection(error.code)) {
-                try {
-                    error.details.retry_command = retryLifecycleInvocationCommand(invocationSettlement.context, invocationSettlement.id);
-                    error.details.retry_instruction = "Correct only the evidenced defect, then use retry_command with the required result input. Reissuing the old command only reads its retained outcome.";
-                }
-                catch (retryError) {
-                    error.details.retry_preparation_error = String(retryError);
-                }
-            }
             try {
-                settleLifecycleInvocation(invocationSettlement.context, invocationSettlement.id, { error: isAppError(error)
-                        ? { code: error.code, message: error.message, exitCode: error.exitCode, details: error.details }
-                        : { code: "unexpected", message: String(error), exitCode: 1, details: {} } });
+                if (isAppError(error))
+                    settleLifecycleRejection(invocationSettlement.context, invocationSettlement.id, { code: error.code, message: error.message, exitCode: error.exitCode, details: error.details });
+                else
+                    settleLifecycleInvocation(invocationSettlement.context, invocationSettlement.id, { error: { code: "unexpected", message: String(error), exitCode: 1, details: {} } });
             }
             catch (persistenceError) {
                 io.stderr.write(`Invocation settlement persistence failed: ${String(persistenceError)}\n`);
@@ -2442,6 +2443,21 @@ function parseFlowFlagOverrides(values) {
 function parseArgs(args) {
     return parseCommandArgs(args);
 }
+/** Most CLI options name one authority, path or target.  Silently taking the
+ * last duplicate can widen a mutation after an operator typo.  Keep only the
+ * options consumed as intentional arrays repeatable. */
+function assertSingletonOptions(args) {
+    const repeatable = new Set(["alias", "flag", "hide", "check-ref", "evidence", "from-check", "from-finding", "from-unresolved", "on", "origin-work"]);
+    const parsed = parseCommandArgs(args);
+    if (args[0] === "stage" && args[1] === "finish"
+        && ["result-file", "semantic-file", "data", "result-stdin"].filter(name => parsed.options.has(name)).length > 1) {
+        throw new AppError("usage", "Stage finish requires exactly one result input; result-file, semantic-file, data and result-stdin are mutually exclusive", 2);
+    }
+    for (const [name, values] of parsed.options) {
+        if (!repeatable.has(name) && values.length > 1)
+            throw new AppError("usage", `--${name} may be supplied only once`, 2);
+    }
+}
 function requiredPosition(parsed, index, label) {
     const value = parsed.positional[index];
     if (!value) {

package/dist/harness-runtime/lib/dd-zcode.mjs

@@ -11,6 +11,9 @@ import { checkObservedProfile, observeModel, observedFields } from "./model-obse
 const ZCODE_HARNESS_CONTRACT = "dd-zcode-harness@1";
 
 function fail(message, code) { const error = new Error(message); if (code) error.code = code; throw error; }
+function fatalLifecycleError(error) {
+  return ["invocation_unknown", "invocation_identity_mismatch", "invocation_identity_conflict", "invocation_receipt_missing", "invocation_command_mismatch", "invocation_scope_mismatch", "invocation_generation_stale", "invocation_expired", "zcode_parent_identity_missing", "zcode_tool_identity_conflict"].includes(error?.code);
+}
 function absolute(value, label) { if (!value || !path.isAbsolute(value)) fail(`${label} must be an absolute path`); return path.resolve(value); }
 function text(value, label) { if (typeof value !== "string" || !value.trim()) fail(`${label} is required`); return value.trim(); }
 function now() { return new Date().toISOString(); }
@@ -134,9 +137,17 @@ export class AcpBridge {
     if (message.method === "session/update" && this.options.onLifecycleNotification) {
       const observer = this.options.onLifecycleNotification;
       const pending = Promise.resolve().then(() => observer(message)).catch(async error => {
-        this.notificationError ??= error;
-        await this.journal.write("notification_failure", { code: error.code ?? "invocation_observation_failed", message: error.message,
-          session_id: message.params?.sessionId ?? null, tool_call_id: update?.toolCallId ?? null, event_time: now(), delivery_stage: "lifecycle_receipt", completeness: "incomplete" });
+        if (!this.notificationError || (fatalLifecycleError(error) && !fatalLifecycleError(this.notificationError))) this.notificationError = error;
+        // A missing/foreign authority is not a recoverable CLI validation
+        // result. Stop admitting productive requests immediately; the managed
+        // controller still owns physical stop/drain and evidence capture.
+        if (fatalLifecycleError(error)) this.rejectAll(error);
+        try {
+          await this.journal.write("notification_failure", { code: error.code ?? "invocation_observation_failed", message: error.message,
+            session_id: message.params?.sessionId ?? null, tool_call_id: update?.toolCallId ?? null, event_time: now(), delivery_stage: "lifecycle_receipt", completeness: "incomplete" });
+        } catch (persistenceError) {
+          process.stderr.write(`${JSON.stringify({ code: error.code, message: error.message, persistence_error: persistenceError.message })}\n`);
+        }
       });
       this.lifecycleNotifications.add(pending);
       void pending.then(() => this.lifecycleNotifications.delete(pending), () => this.lifecycleNotifications.delete(pending));
@@ -224,7 +235,7 @@ export class AcpBridge {
   }
 
   request(method, params = {}, timeoutMs = 30_000, { idleSessionId = null, idleTimeoutMs = null } = {}) {
-    if (this.notificationError?.code === "profile_integrity_violation" && ["session/new", "session/prompt", "session/fork"].includes(method)) return Promise.reject(this.notificationError);
+    if ((this.notificationError?.code === "profile_integrity_violation" || fatalLifecycleError(this.notificationError)) && ["session/new", "session/prompt", "session/fork"].includes(method)) return Promise.reject(this.notificationError);
     const id = this.nextId++;
     return new Promise((resolve, reject) => {
       const finish = (error) => {
@@ -270,7 +281,11 @@ export class AcpBridge {
   notify(method, params = {}) { this.send({ jsonrpc: "2.0", method, params }); }
   send(message) { this.journal.write("outbound", message); this.child.stdin.write(`${JSON.stringify(message)}\n`); }
   rejectAll(error) { for (const pending of this.pending.values()) { clearTimeout(pending.timer); if (pending.idleTimer) clearInterval(pending.idleTimer); pending.reject(error); } this.pending.clear(); }
-  async flush() { await Promise.all([...this.lifecycleNotifications]); await this.notifications; await this.journal.flush(); if (this.notificationError) throw this.notificationError; }
+  async flush() {
+    try { await Promise.all([...this.lifecycleNotifications]); await this.notifications; await this.journal.flush(); }
+    catch (error) { throw this.notificationError ?? error; }
+    if (this.notificationError) throw this.notificationError;
+  }
   async close() {
     let flushError = null;
     try { await this.flush(); } catch (error) { flushError = error; }

package/dist/services/cli-operation-classifier.js

@@ -131,7 +131,11 @@ function isReadOnlyDiagnostic(family, command, action) {
     if (family === "plan")
         return command === "status";
     if (family === "run")
-        return command === "status" || command === "list" || (["drive", "control"].includes(command ?? "") && action === "status");
+        return command === "status" || command === "list" || (command === "recovery" && action === "inspect") || (["drive", "control"].includes(command ?? "") && action === "status");
+    if (family === "work")
+        return ["status", "ls", "show"].includes(command ?? "");
+    if (family === "stage")
+        return command === "fanout" && action === "status";
     if (family === "lane") {
         return (command === "status" ||
             command === "waiters" ||

package/dist/services/lifecycle-invocations.js

@@ -9,12 +9,13 @@ import { assertRunMutationAllowed, assertStageSettlementAllowed, assertWorkSettl
 import { requireManagedDaemonBinding } from "./managed-daemon-binding.js";
 // Conclusive result/check rejections, never transport, ownership, registry or
 // unknown-effect failures. These validators reject before accepting the result.
-export function isRetryableLifecycleRejection(code) {
+export function isRetryableLifecycleRejection(code, details = {}) {
     return ["validation", "schema_validation", "work_checks_failed", "code_review_gate_failed",
         "review_repair_incomplete", "plan_review_incomplete", "semantic_result_invalid",
         "review_evidence_invalid", "evidence_obligation_unknown", "invalid_evidence_ref",
         "evidence_ref_missing", "evidence_line_out_of_range", "document_update_missing",
-        "document_update_not_materialized", "review_repair_no_change"].includes(code);
+        "document_update_not_materialized", "review_repair_no_change"].includes(code)
+        || (code === "invalid_work_state" && details.retryable_no_effect === true);
 }
 function storage(context) {
     context.db.execSchema(`CREATE TABLE IF NOT EXISTS lifecycle_invocations (
@@ -51,6 +52,30 @@ function load(context, id) {
 export function lifecycleInvocationScope(context, id) {
     return JSON.parse(load(context, id).scope_json);
 }
+/** Current, explicitly-issued replacements for commands from the resumed stage.
+ * Original prompts remain immutable evidence; callers may present this small
+ * overlay after a state transition made an earlier no-effect rejection retryable. */
+export function lifecycleRetryCommands(context, stage) {
+    const scope = context.env.DD_FLOW_INVOCATION_SCOPE;
+    if (!scope || !context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lifecycle_invocations'"))
+        return [];
+    return context.db.all("SELECT * FROM lifecycle_invocations WHERE scope_json = ? AND status = 'settled' ORDER BY rowid", [scope])
+        .flatMap((row) => {
+        try {
+            const outcome = row.outcome_json ? JSON.parse(row.outcome_json) : null;
+            const retry = outcome?.error?.details?.retry_command;
+            const parsed = invocation(row.command);
+            if (typeof retry !== "string" || parsed.operation !== "stage_finish" || commandOption(parsed, "stage") !== stage)
+                return [];
+            const successor = load(context, commandOption(invocation(retry), "invocation-id") ?? "");
+            const latest = context.db.get("SELECT * FROM lifecycle_invocations WHERE scope_json = ? AND fingerprint = ? ORDER BY rowid DESC LIMIT 1", [row.scope_json, row.fingerprint]);
+            return successor.id === latest?.id && successor.status === "issued" ? [retry] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
 export function managedInvocationContext(context, input) {
     const env = { ...context.env, DD_FLOW_CURRENT_INVOCATION: undefined, DD_FLOW_INVOCATION_SCOPE: undefined };
     if (input.harness !== "zcode-acp")
@@ -81,15 +106,16 @@ export function managedLifecycleCommand(context, command) {
             ? context.db.get("SELECT * FROM lifecycle_invocations WHERE scope_json = ? AND fingerprint = ? ORDER BY rowid DESC LIMIT 1", [JSON.stringify(scope), fingerprint(parsed)]) : undefined;
         if (!retained)
             throw new AppError("invocation_command_unprepared", "Read-only inspection has no retained lifecycle command", 1);
-        return retained.command;
+        return renderInvocationCommand(retained, command);
     }
     storage(context);
     context.db.exec("SAVEPOINT invocation_command");
     try {
         const prior = context.db.get("SELECT * FROM lifecycle_invocations WHERE scope_json = ? AND fingerprint = ? ORDER BY rowid DESC LIMIT 1", [JSON.stringify(scope), fingerprint(parsed)]);
         if (prior && prior.id !== context.env.DD_FLOW_CURRENT_INVOCATION) {
+            const rendered = renderInvocationCommand(prior, command);
             context.db.exec("RELEASE invocation_command");
-            return prior.command;
+            return rendered;
         }
         if (context.env.DD_FLOW_INVOCATION_READONLY === "1")
             throw new AppError("invocation_command_unprepared", "No prepared lifecycle command is available; read-only inspection cannot issue one", 1);
@@ -112,6 +138,31 @@ export function retryLifecycleInvocationCommand(context, id) {
         throw new AppError("invocation_command_invalid", "Retained issued command lost its invocation marker", 1);
     return managedLifecycleCommand({ ...context, env: { ...context.env, DD_FLOW_INVOCATION_SCOPE: prior.scope_json, DD_FLOW_CURRENT_INVOCATION: id } }, prior.command.replace(marker, ""));
 }
+/** Settle a conclusive rejection and publish its only legal successor atomically.
+ * A crash must leave either the old attempt executing, or both the settled
+ * outcome and its successor; never a usable successor beside an unknown effect. */
+export function settleLifecycleRejection(context, id, error) {
+    storage(context);
+    const details = { ...error.details };
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        const prior = load(context, id);
+        if (prior.status !== "executing")
+            throw new AppError("invocation_settlement_conflict", "Attempt is no longer executing", 1, { invocation_id: id });
+        if (isRetryableLifecycleRejection(error.code, error.details)) {
+            const retry = retryLifecycleInvocationCommand(context, id);
+            details.retry_command = retry;
+            details.retry_instruction = "Correct only the evidenced defect, then use retry_command with the required result input. Reissuing the old command only reads its retained outcome.";
+        }
+        settleLifecycleInvocation(context, id, { error: { ...error, details } });
+        context.db.exec("COMMIT");
+        Object.assign(error.details, details);
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}
 /** Recovery preserves the original packet as evidence. Only its retained,
  * never-executed commands receive new authority; unknown effects never replay. */
 export function recoverLifecycleCommands(context, originalPrompt, scope) {
@@ -206,14 +257,28 @@ export function issueLifecycleInvocation(context, command, scope) {
         throw new AppError("invocation_scope_invalid", "Lifecycle issuance requires explicit managed scope and a new command", 1);
     }
     const id = crypto.randomUUID();
-    const at = shellSuffixOffset(command);
-    const prepared = `${command.slice(0, at).trimEnd()} --invocation-id ${id} ${command.slice(at)}`.trimEnd();
+    const prepared = commandWithInvocationId(command, id);
     // Validate the actual inserted argv, including quoted heredoc boundaries.
     const row = { id, scope_json: JSON.stringify(scope), fingerprint: fingerprint(parsed) };
     checkCommand(row, prepared);
     context.db.run("INSERT INTO lifecycle_invocations (id, scope_json, command, fingerprint, status, created_at, updated_at) VALUES (?, ?, ?, ?, 'issued', ?, ?)", [id, row.scope_json, prepared, row.fingerprint, context.now(), context.now()]);
     return { id, command: prepared };
 }
+function commandWithInvocationId(command, id) {
+    const at = shellSuffixOffset(command);
+    return `${command.slice(0, at).trimEnd()} --invocation-id ${id} ${command.slice(at)}`.trimEnd();
+}
+/** The attempt owns authority; the caller owns presentation-only shell input.
+ * Preserve current stdin/heredoc/response-file text while validating that it
+ * still names the exact persisted operation and project. */
+function renderInvocationCommand(row, command) {
+    const parsed = invocation(command);
+    if (commandOption(parsed, "invocation-id"))
+        throw new AppError("invocation_command_invalid", "Rendered lifecycle command already has an invocation id", 1);
+    const rendered = commandWithInvocationId(command, row.id);
+    checkCommand(row, rendered);
+    return rendered;
+}
 /** Native observer and receipt writer commit together. Never await I/O inside
  * this transaction; the callback must write to this same SQLite connection. */
 export function observeLifecycleInvocation(context, input) {

package/dist/services/stage-pause.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { quote } from "shell-quote";
-import { managedLifecycleCommand } from "./lifecycle-invocations.js";
+import { lifecycleRetryCommands, managedLifecycleCommand } from "./lifecycle-invocations.js";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { findRecentMatchingHookEvent, claimStageResumeHookEvent, stageResumeMatchKey } from "./hooks.js";
@@ -73,16 +73,22 @@ export function resumeStageAfterUser(context, input) {
         errorCode: "trusted_stage_resume_required",
         operation: "stage resume"
     }).eventKey;
-    const answerPath = path.join(path.dirname(stage.pause.question_path), "answer.md");
-    fs.writeFileSync(answerPath, input.answer);
     const now = context.now();
     const workSession = context.db.get("SELECT id, session_id, prompt_path, result_path, status FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
     if (!workSession)
         throw new AppError("runtime_missing", "Paused Work has no open Session link", 1, { work_id: work.work_id });
+    const answerPath = path.join(path.dirname(stage.pause.question_path), `answer-${crypto.createHash("sha256").update(`${stage.pause.id}\0${input.answer}`).digest("hex")}.md`);
     context.db.exec("BEGIN IMMEDIATE");
     let identity;
     try {
         identity = claimStageResumeHookEvent(context, { projectId: project.id, runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, eventKey: hookEventId });
+        try {
+            fs.writeFileSync(answerPath, input.answer, { flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST" || fs.readFileSync(answerPath, "utf8") !== input.answer)
+                throw error;
+        }
         if (workSession.session_id !== identity.sessionId) {
             bindSessionForResume(context, work.work_id, identity, now);
             context.db.run("UPDATE work_sessions SET status = 'completed', updated_at = ?, completed_at = ? WHERE id = ?", [now, now, workSession.id]);
@@ -101,6 +107,7 @@ export function resumeStageAfterUser(context, input) {
     refreshRunWorkProjection(context, project.id, run.id);
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_resume_session_bound", stage: stage.stage, work_id: work.work_id, session_id: identity.sessionId });
     const prompt = fs.readFileSync(workSession.prompt_path, "utf8");
+    const retryCommands = lifecycleRetryCommands(context, stage.stage);
     const continuation = [
         prompt.trimEnd(),
         "",
@@ -109,6 +116,7 @@ export function resumeStageAfterUser(context, input) {
         `- Question source: ${stage.pause.question_path}`,
         `- Answer source: ${answerPath}`,
         "- Continue the same stage, Work and attempt. Do not call stage start or repeat completed preparation.",
+        ...(retryCommands.length ? ["- A prior no-effect lifecycle rejection now has these authoritative replacement commands; use only these replacements, never invent an invocation id:", ...retryCommands.map(command => `  ${command}`)] : []),
         "",
         "<user_question>",
         fs.readFileSync(stage.pause.question_path, "utf8"),

package/dist/services/vnext-specify.js

@@ -128,7 +128,9 @@ export function submitVnextSpecify(context, input) {
     if (work.project_id !== project.id)
         throw new AppError("project_mismatch", "Work does not belong to --project-root", 1, { work_id: work.work_id });
     if (work.status !== "running") {
-        throw new AppError("invalid_work_state", "Work is not waiting for a SPECIFY result", 1, { work_id: work.work_id, status: work.status });
+        // This check precedes all result reads and mutations. A later legal state
+        // transition may make a new invocation appropriate, but never replays this one.
+        throw new AppError("invalid_work_state", "Work is not waiting for a SPECIFY result", 1, { work_id: work.work_id, status: work.status, retryable_no_effect: true });
     }
     const run = requireRun(context, projectRoot, work.run_id);
     if (runStatus(context, project.id, run.id) !== "running") {

package/package.json

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