@deksden-com/dd-flow-cli 0.9.0-beta.88 → 0.9.0-beta.89

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.89
+
+### Minor Changes
+
+- Register aggregate CODE and CODE-REVIEW repairs atomically from all failed receipts, with stable replay identity and stage/attempt/cycle membership. Resolve declared contextual file paths independently of lifecycle authority, retain exact native command rejection causes, and emit shell-safe commands with explicit JSON recovery inputs. Keep historical Work out of current dispatch and block ambiguous legacy fanout execution.
+
 ## 0.9.0-beta.88
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,11 +1,11 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.88",
-  "cli_commit": "6cd7da3104a366d4b2866fa31ef8635949e79143",
-  "built_at": "2026-09-21T00:22:16.324Z",
+  "cli_version": "0.9.0-beta.89",
+  "cli_commit": "e36aabd9160805831809ca27575600fb6db47511",
+  "built_at": "2026-09-21T08:53:05.446Z",
   "built_with_canon": {
     "version": "4.1.1",
-    "commit": "acaae844a871ddfbc49fd66355373f166dc3e683",
+    "commit": "d1a6081ab15ab92ac917ff5d037121a40c709db1",
     "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

@@ -11,6 +11,9 @@ const scoped = "project-root"; // Optional when the router resolves a unique ret
 const lifecycle = "invocation-id hook-event-id";
 const worker = "worker-id";
 const control = "project-root run";
+/** Path-shaped arguments default to physical paths unless the route explicitly
+ * opts into contextualPaths. This inventory does not expand arbitrary strings. */
+export const physicalPathOptions = new Set(words("root project-root workspace-root workspace-path path dir file schema-dir output result-file semantic-file data decision-file verification-file reason-file task-file intake-file context-file observations-file observation-file summary-file question-file answer-file payload-file json-file task-profile-file execution-routing-file protocol-override-file manifest-file routing-file config-file input-file report-file snapshot-file output-dir state-dir capture-root capture-path destination source archive snapshot plan-file backup-path database backup source-home target-home stdout stderr adapter-executable memory-bank flow stage-report dashboard report"));
 export const commandInputs = {
     "version": route(0),
     "status": route(0, "", "root project-root", "check-registry"),
@@ -40,19 +43,19 @@ export const commandInputs = {
     "plan item block": route(2, "reason user-required", scoped),
     "plan item skip": route(2, "reason", scoped),
     "plan-review dispatch": route(1, "", scoped),
-    "prompt render": route(0, `${project} run stage profile`, "workspace-root task-file plan-item"),
+    "prompt render": { ...route(0, `${project} run stage profile`, "workspace-root task-file plan-item"), contextualPaths: words("project-root workspace-root task-file") },
     "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 finish": { ...route(1, `${project} stage`, `${lifecycle} dir semantic-file data result-file outcome decision-file verification-file retry-check reason reason-file request work`, "result-stdin"), contextualPaths: words("project-root semantic-file result-file decision-file verification-file reason-file") },
     "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),
-    "stage fanout reconcile": route(1, "stage observations-file", scoped),
-    "stage native observe": route(1, "stage observations-file", scoped),
+    "stage fanout reconcile": { ...route(1, "stage observations-file", scoped), contextualPaths: words("project-root observations-file") },
+    "stage native observe": { ...route(1, "stage observations-file", scoped), contextualPaths: words("project-root observations-file") },
     "work status": route(1, project),
-    "work add-batch": route(0, "parent file", scoped),
+    "work add-batch": { ...route(0, "parent file", scoped), contextualPaths: words("project-root file") },
     "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-file`, "task-stdin", "origin-work from-finding from-unresolved check-ref"), contextualPaths: words("project-root verification-file task-file") },
@@ -63,7 +66,7 @@ export const commandInputs = {
     "work delete": route(1, "", scoped),
     "work launch": route(1, "", `${scoped} stage`),
     "work start": { ...route(1, "", `${scoped} ${lifecycle} recovery-id`), contextualPaths: ["project-root"] },
-    "work finish": { ...route(1, "", `${scoped} ${lifecycle} result-file retry-check reason`, "result-stdin"), contextualPaths: words("project-root result-file") },
+    "work finish": { ...route(1, "", `${scoped} ${lifecycle} result-file retry-check reason reason-file`, "result-stdin"), contextualPaths: words("project-root result-file reason-file") },
     "work fail": { ...route(1, "reason", `${scoped} ${lifecycle}`), contextualPaths: ["project-root"] },
     "work cancel": route(1, "reason", scoped),
     "work retry": route(1, "reason", scoped),
@@ -218,7 +221,7 @@ export const commandInputs = {
     "dashboard open": route(0, "", "project project-root protocol viewer format"),
     "dashboard refresh": route(0, "", "project project-root protocol open format output", "all"),
     "dashboard refresh-global": route(0, "", "output format"),
-    "schema validate": route(0, "schema file", "schema-dir project-root run"),
+    "schema validate": { ...route(0, "schema file", "schema-dir project-root run"), contextualPaths: words("project-root file") },
     "memory permissions preflight": route(0, "root memory-bank flow mode", "tasks")
 };
 export function contextualPathOptionsForLifecycle(operation) {
@@ -286,14 +289,14 @@ export function prepareCommandRoute(args) {
         ["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"], ["question-file", "question-stdin"], ["answer-file", "answer-stdin"],
-        ["summary-file", "summary-stdin"], ["task-file", "task-stdin"]
+        ["summary-file", "summary-stdin"], ["task-file", "task-stdin"], ["reason", "reason-file"]
     ]) {
         const present = aliases.filter(name => parsed.options.has(name));
         if (present.length > 1)
             reject(`Use only one of ${present.map(name => `--${name}`).join(", ")}`);
     }
-    if (contract.values.includes("retry-check") && parsed.options.has("retry-check") !== parsed.options.has("reason"))
-        reject("--retry-check and --reason must be supplied together");
+    if (contract.values.includes("retry-check") && parsed.options.has("retry-check") !== (parsed.options.has("reason") || parsed.options.has("reason-file")))
+        reject("--retry-check requires exactly one of --reason or --reason-file");
     // Retain the dispatcher's historic offsets for nested action positions.
     const family = parsed.positional[0];
     const singleWord = ["status", "version", "transition"].includes(family);

package/dist/cli/help.js

@@ -235,6 +235,8 @@ Usage:
   dd-flow stage resume <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> (--answer-file <path>|--answer-stdin) --json
 
 Managed resume commands restore the accepted answer file from runtime state. Execute the returned command without adding an answer path or recreating the answer. The explicit answer flags above are for unmanaged calls.
+Path aliases @project, @workspace and @run are supported only in declared CLI path parameters and require a uniquely bound context. File-writing tools use physical paths. Both --option value and --option=value are accepted; quoted or escaped aliases are normalized identically. Pre-RUN bootstrap paths and external schema directories require physical paths.
+An aggregate CODE/CODE-REVIEW failure may return continuation.kind=repair_required: its repair Work is already registered. End the coordinator turn and let the controller dispatch the fresh child; do not recreate the repair. A recovery retry uses --retry-check <receipt> --reason-file <recovery.json>, containing only {"reason":"actual environment recovery evidence"}. Legacy --reason remains accepted, but cannot be combined with --reason-file. A needs_input continuation is not yet executable: write its requested file first, then use command_after_input.
   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

package/dist/cli/hook-ingress.js

@@ -1,6 +1,6 @@
 import { fileURLToPath } from "node:url";
 import { performance } from "node:perf_hooks";
-import { parseCommandArgs, parseLifecycleCommand, lifecycleCommandFromPayload } from "../services/lifecycle-command.js";
+import { parseCommandArgs, parseLifecycleCommand, lifecycleCommandFromPayload, continuationCommand } from "../services/lifecycle-command.js";
 import { errorRecord, AppError } from "../shared/errors.js";
 import { parseJsonObject } from "../shared/json.js";
 const workerFile = fileURLToPath(import.meta.url);
@@ -28,7 +28,7 @@ export async function runHookIngress(args) {
         }
         const payload = parseJsonObject(stdin || "{}", "native hook stdin");
         const command = lifecycleCommandFromPayload(payload);
-        if (event !== "PreToolUse" || !command || parseLifecycleCommand(command).kind === "none") {
+        if (event !== "PreToolUse" || !command || (parseLifecycleCommand(command).kind === "none" && !continuationCommand(command))) {
             process.stdout.write("{}\n");
             return 0;
         }

package/dist/cli/run-cli.js

@@ -1,4 +1,6 @@
 import fs from "node:fs";
+import { resolveCommandPaths, resolveCommandProjectRoot } from "../services/command-context.js";
+import { assertAuxiliaryCommandScope } from "../services/lifecycle-invocations.js";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { quote } from "shell-quote";
@@ -171,7 +173,7 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         const retainedOutput = observedInvocation ? parseOutputOptions(expandedInvocationArgs) : null;
         if (retainedOutput?.responseFile)
             output.responseFile = retainedOutput.responseFile;
-        const invocationArgs = retainedOutput?.args ?? expandedInvocationArgs;
+        let invocationArgs = retainedOutput?.args ?? expandedInvocationArgs;
         emitHumanProgress(io, output, progress, "start");
         if (output.progressJsonl) {
             writeProgressJsonl(io, "start", `Starting ${output.args.slice(0, 3).join(" ")}`);
@@ -179,7 +181,9 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         }
         // Route by retained authority, so a mistyped project path reaches the CLI
         // validator instead of selecting a different engine or failing preflight.
-        const scopeProjectRoot = invocationScope?.projectRoot ?? resolveProjectRootBeforeRouting(output.args, env);
+        const scopeProjectRoot = invocationScope?.projectRoot ?? resolveCommandProjectRoot(routerContext, output.args, resolveProjectRootBeforeRouting(output.args, env));
+        assertAuxiliaryCommandScope({ ...routerContext, env }, publicCommand, scopeProjectRoot);
+        invocationArgs = resolveCommandPaths(routerContext, invocationArgs, scopeProjectRoot);
         const routedArgs = output.responseFile ? [...invocationArgs, "--response-file", output.responseFile] : invocationArgs;
         const routed = await routeArgsThroughEngine(routerContext, output.json ? [...routedArgs, "--json", ...(output.progressJsonl ? ["--progress-jsonl"] : [])] : routedArgs, io, io.stdin, env, scopeProjectRoot);
         if (routed?.routed && !routed.inProcess) {
@@ -237,8 +241,11 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile);
         if (!retainedOutcome)
             preflightCliCompatibility(dispatchContext, invocationArgs, env, scopeProjectRoot);
-        if (!retainedOutcome)
-            settleHook = observeLifecycleCommand(dispatchContext, quote(["dd-flow", ...dispatchArgs]));
+        if (!retainedOutcome) {
+            const command = lifecycleCommand.kind === "none" ? publicCommand : quote(["dd-flow", ...dispatchArgs]);
+            const event = lifecycleCommand.kind === "none" && env.DD_FLOW_DAEMON_ID ? observedLifecycleNativeEvent(dispatchContext, command, env.DD_FLOW_DAEMON_ID) : null;
+            settleHook = observeLifecycleCommand(dispatchContext, command, event ?? undefined);
+        }
         const result = retainedOutcome ? retainedOutcome.result : await dispatch(dispatchArgs, dispatchContext, io, scopeProjectRoot, classification, output, preparedInput);
         const completedHook = settleHook;
         settleHook = undefined;
@@ -764,6 +771,14 @@ async function prepareCliInput(...args) {
 async function prepareCliInputValue(args, context, io, scopeProjectRoot, responseFile = null, route = prepareCommandRoute(args)) {
     const { family, command, parsed } = route;
     const prepared = { route };
+    if (optionalOption(parsed, "reason-file")) {
+        const value = prepareJsonFile(requiredOption(parsed, "reason-file"), "Check recovery evidence").value;
+        if (!value || typeof value.reason !== "string" || !value.reason.trim() || Object.keys(value).some(key => key !== "reason"))
+            throw new AppError("validation", "Recovery evidence must be a JSON object with one nonempty reason", 2);
+        prepared.retryReason = value.reason;
+    }
+    else if (optionalOption(parsed, "retry-check"))
+        prepared.retryReason = optionalOption(parsed, "reason");
     if (route.key === "project register")
         resolveProjectRoot(requiredOption(parsed, "root"));
     if (route.key === "project archive")
@@ -1200,7 +1215,7 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
         }
     }
     if (family === "work" && command === "finish") {
-        const retryReceiptId = optionalOption(parsed, "retry-check"), retryReason = optionalOption(parsed, "reason");
+        const retryReceiptId = optionalOption(parsed, "retry-check"), retryReason = prepared.retryReason;
         if (Boolean(retryReceiptId) !== Boolean(retryReason))
             throw new AppError("usage", "--retry-check and --reason must be supplied together", 2);
         const resultFile = optionalOption(parsed, "result-file");
@@ -1225,8 +1240,8 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
         throw new AppError("usage", "Stage status belongs in the semantic input file", 2);
     if (["result-file", "semantic-file", "data", "result-stdin"].filter(key => hasOption(parsed, key)).length > 1)
         throw new AppError("usage", "Use exactly one result input: --result-file, --semantic-file, --data or --result-stdin", 2);
-    if (Boolean(optionalOption(parsed, "retry-check")) !== Boolean(optionalOption(parsed, "reason")))
-        throw new AppError("usage", "--retry-check and --reason must be supplied together", 2);
+    if (Boolean(optionalOption(parsed, "retry-check")) !== Boolean(prepared.retryReason))
+        throw new AppError("usage", "--retry-check requires recovery evidence", 2);
     const resultStdin = hasOption(parsed, "result-stdin");
     const semanticFile = optionalOption(parsed, "semantic-file") ?? optionalOption(parsed, "data");
     const resultFile = optionalOption(parsed, "result-file") ?? semanticFile;
@@ -1244,8 +1259,8 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
     };
     const acceptStageInputs = (allowed) => {
         const options = allowed.split(" ");
-        for (const name of ["dir", "semantic-file", "data", "result-file", "result-stdin", "outcome", "decision-file", "verification-file", "retry-check", "reason", "request", "work"]) {
-            if (hasOption(parsed, name) && !options.includes(name))
+        for (const name of ["dir", "semantic-file", "data", "result-file", "result-stdin", "outcome", "decision-file", "verification-file", "retry-check", "reason", "reason-file", "request", "work"]) {
+            if (hasOption(parsed, name) && !options.includes(name === "reason-file" ? "reason" : name))
                 throw new AppError("usage", `stage finish ${stage} does not accept --${name} for this flow`, 2, { parameter: name });
         }
     };
@@ -1302,7 +1317,7 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
         requiredOption(parsed, "request");
         requiredOption(parsed, "work");
         try {
-            prepared.mergeFinish = prepareVnextMergeFinish(context, { projectRoot, runId, requestId: requiredOption(parsed, "request"), workId: requiredOption(parsed, "work"), ...(optionalOption(parsed, "retry-check") ? { retryCheckId: optionalOption(parsed, "retry-check"), retryReason: optionalOption(parsed, "reason") } : {}) });
+            prepared.mergeFinish = prepareVnextMergeFinish(context, { projectRoot, runId, requestId: requiredOption(parsed, "request"), workId: requiredOption(parsed, "work"), ...(optionalOption(parsed, "retry-check") ? { retryCheckId: optionalOption(parsed, "retry-check"), retryReason: prepared.retryReason } : {}) });
         }
         catch (error) {
             return prepareError(error, { parameter: "MERGE finish" });
@@ -1574,7 +1589,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         const workId = requiredPosition(parsed, 0, "work-id");
         const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "work finish");
         assertWorkLifecycleOwner(context, { workId, projectRoot, operation: "work_finish", ...(optionalOption(parsed, "hook-event-id") ? { hookEventId: optionalOption(parsed, "hook-event-id") } : {}) });
-        const retryReceiptId = optionalOption(parsed, "retry-check"), retryReason = optionalOption(parsed, "reason");
+        const retryReceiptId = optionalOption(parsed, "retry-check"), retryReason = prepared.retryReason;
         if (Boolean(retryReceiptId) !== Boolean(retryReason))
             throw new AppError("usage", "--retry-check and --reason must be supplied together", 2);
         const result = prepared.workFinish?.result ?? (resultFile ? prepareTextFile(resultFile, "Work result").text : await readStdin(io.stdin));
@@ -1698,7 +1713,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         const resultFile = optionalOption(parsed, "result-file") ?? semanticFile;
         const resultStdin = hasOption(parsed, "result-stdin");
         const retryCheckId = optionalOption(parsed, "retry-check");
-        const retryReason = optionalOption(parsed, "reason");
+        const retryReason = prepared.retryReason;
         const hookEventId = optionalOption(parsed, "hook-event-id");
         if (retryCheckId && !retryReason?.trim())
             throw new AppError("usage", "--retry-check requires --reason explaining the recovered environment", 2);

package/dist/services/codex-hook-delivery.js

@@ -1,14 +1,14 @@
 import path from "node:path";
 import { callDaemon } from "../harness-runtime/lib/dd-codex-daemon.mjs";
 import { AppError } from "../shared/errors.js";
-import { commandOption, lifecycleCommandFromPayload, parseLifecycleCommand } from "./lifecycle-command.js";
+import { commandOption, lifecycleCommandFromPayload, parseLifecycleCommand, continuationCommand } from "./lifecycle-command.js";
 /** The hook asks the existing daemon about native evidence; it cannot mint it. */
 export async function verifyCodexHookDelivery(env, payload) {
     const command = lifecycleCommandFromPayload(payload);
     const parsed = command ? parseLifecycleCommand(command) : { kind: "none" };
-    if (parsed.kind === "none")
+    if (parsed.kind === "none" && !(command && continuationCommand(command)))
         return undefined;
-    const managed = commandOption(parsed.invocation, "invocation-id") || env.DD_FLOW_DAEMON_ID;
+    const managed = (parsed.kind !== "none" && commandOption(parsed.invocation, "invocation-id")) || env.DD_FLOW_DAEMON_ID;
     if (!managed)
         return undefined; // Explicit legacy/unmanaged transport.
     if (!env.DD_FLOW_CODEX_STATE_DIR || !env.DD_FLOW_DAEMON_ID)

package/dist/services/command-context.js

@@ -0,0 +1,80 @@
+import path from "node:path";
+import { commandInputs, physicalPathOptions } from "../cli/command-inputs.js";
+import { parseCommandArgs } from "./lifecycle-command.js";
+import { assertPathWithin, canonicalPath } from "../storage/paths.js";
+import { AppError } from "../shared/errors.js";
+import { resolveWorkReference } from "../storage/work-references.js";
+export function normalizedPathAlias(value) {
+    return value.replace(/^\\+(?=@(?:project|workspace|run)(?:\/|$))/, "");
+}
+export function resolveContextualPaths(args, options, roots) {
+    const resolve = (option, original) => {
+        if (!options.has(option))
+            return original;
+        const value = normalizedPathAlias(original);
+        if (!value.startsWith("@"))
+            return value;
+        const match = /^@(project|workspace|run)(?:\/(.*))?$/.exec(value);
+        if (!match || !roots[match[1]])
+            throw new AppError("usage", `Unknown or unavailable path alias: ${value}`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
+        const root = roots[match[1]];
+        return assertPathWithin(root, path.join(root, match[2] ?? ""), `${match[1]}_alias`);
+    };
+    return args.map((value, index) => {
+        const equal = /^--([^=]+)=(.*)$/s.exec(value);
+        if (equal)
+            return `--${equal[1]}=${resolve(equal[1], equal[2])}`;
+        const option = args[index - 1]?.match(/^--([^=]+)$/)?.[1];
+        return option ? resolve(option, value) : value;
+    });
+}
+/** Contextual paths are route semantics, not lifecycle invocation authority. */
+export function resolveCommandProjectRoot(context, args, explicit) {
+    if (explicit && !normalizedPathAlias(explicit).startsWith("@"))
+        return canonicalPath(explicit, false);
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'runs'"))
+        return null;
+    const parsed = parseCommandArgs(args);
+    const key = Object.keys(commandInputs).filter(key => key.split(" ").every((part, i) => parsed.positional[i] === part)).sort((a, b) => b.length - a.length)[0];
+    const reference = parsed.options.get("run")?.[0] ?? (key?.startsWith("stage ") ? parsed.positional[key.split(" ").length] : undefined);
+    if (reference) {
+        const rows = context.db.all("SELECT project_root FROM runs WHERE id = ? OR short_id = ?", [reference, reference]);
+        if (rows.length === 1)
+            return rows[0].project_root;
+        if (rows.length > 1)
+            throw new AppError("usage", "RUN reference requires an explicit project scope", 2, { phase: "prepare", effect: "no_effect" });
+    }
+    const work = parsed.options.get("parent")?.[0] ?? (key?.startsWith("work ") && !key.startsWith("work repair") ? parsed.positional[key.split(" ").length] : undefined);
+    if (work) {
+        const resolved = resolveWorkReference(context, work);
+        return context.db.get("SELECT root FROM projects WHERE id = ?", [resolved.project_id])?.root ?? null;
+    }
+    return null;
+}
+export function resolveCommandPaths(context, args, projectRoot) {
+    const parsed = parseCommandArgs(args);
+    const key = Object.keys(commandInputs).filter(key => key.split(" ").every((part, i) => parsed.positional[i] === part)).sort((a, b) => b.length - a.length)[0];
+    const options = new Set(key ? commandInputs[key]?.contextualPaths ?? [] : []);
+    if (!args.some(value => /(?:^|=)\\*@/.test(value)))
+        return args;
+    for (const [option, values] of parsed.options) {
+        if (physicalPathOptions.has(option) && !options.has(option) && values.some(value => normalizedPathAlias(value).startsWith("@")))
+            throw new AppError("usage", `--${option} requires a physical path on this route`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
+    }
+    const project = projectRoot ? context.db.get("SELECT id FROM projects WHERE root = ?", [projectRoot]) : undefined;
+    const reference = parsed.options.get("run")?.[0] ?? (key?.startsWith("stage ") ? parsed.positional[key.split(" ").length] : undefined);
+    let run;
+    if (reference && project) {
+        const rows = context.db.all("SELECT id, workspace_root, run_root FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [project.id, reference, reference]);
+        if (rows.length !== 1)
+            throw new AppError("usage", "Path aliases require one RUN in the selected project", 2, { phase: "prepare", effect: "no_effect" });
+        run = rows[0];
+    }
+    const work = parsed.options.get("parent")?.[0] ?? (key?.startsWith("work ") && !key.startsWith("work repair") ? parsed.positional[key.split(" ").length] : undefined);
+    if (work && project) {
+        const resolved = resolveWorkReference(context, work, { projectId: project.id, ...(run ? { runId: run.id } : {}) });
+        if (!run)
+            run = context.db.get("SELECT id, workspace_root, run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, resolved.run_id]);
+    }
+    return resolveContextualPaths(args, options, { project: projectRoot, workspace: run?.workspace_root, run: run?.run_root });
+}

package/dist/services/continuation-outcome.js

@@ -0,0 +1,20 @@
+import { AppError } from "../shared/errors.js";
+import { isRegisteredRepair } from "./repair-intents.js";
+import { stageAttempt } from "./stage-work-graph.js";
+/** Only the settled coordinator turn can explain a repeated continuation.
+ * A stale error from another stage/turn or an error followed by success is not
+ * authority. Never inspect the assistant's prose for this decision. */
+export function assertNoCorrelatedRejection(context, scope) {
+    const rows = context.db.all(`SELECT outcome_json FROM hook_events
+    WHERE project_id = ? AND json_extract(outcome_json, '$.run_id') = ?
+    AND json_extract(outcome_json, '$.generation') = ? AND json_extract(outcome_json, '$.stage') = ?
+    AND json_extract(outcome_json, '$.controller_turn') = ? AND json_extract(outcome_json, '$.attempt') = ? ORDER BY id`, [scope.projectId, scope.runId, scope.generation, scope.stage, scope.turn, stageAttempt(context, scope.projectId, scope.runId, scope.stage)]);
+    const latest = new Map();
+    for (const row of rows) {
+        const value = JSON.parse(row.outcome_json);
+        latest.set(value.operation, value);
+    }
+    for (const value of latest.values())
+        if (value.error && !isRegisteredRepair(context, value.error.details.continuation, scope))
+            throw new AppError(value.error.code, value.error.message, 1, { ...value.error.details, operation: value.operation, hook_event_id: value.hook_event_id, continuation_scope: scope });
+}

package/dist/services/controller-fanout.js

@@ -28,6 +28,8 @@ export async function nextControllerFanout(context, input) {
     let fanout = getVnextFanoutStatus(context, input).orchestration;
     if (!fanout)
         return { kind: "none" };
+    if (fanout.state === "compatibility_required")
+        throw new AppError("stage_graph_compatibility_required", "The retained graph cannot be dispatched by this controller; use the RUN's pinned engine", 1, { stage: input.stage, run_id: input.runId, graph: fanout });
     if (children.length) {
         const reconciled = await reconcileVnextFanout(context, { ...input, observations });
         const issues = reconciled.issues.filter(issue => issue.code !== "child_check_in_progress");
@@ -43,7 +45,7 @@ export async function nextControllerFanout(context, input) {
         if (fanout.state === "dispatch_required" || fanout.state === "capacity_required")
             return { kind: "wait", reason: "qualified_capacity_required" };
     }
-    const prompt = (text) => ({ kind: "prompt", prompt: text, fingerprint: JSON.stringify({ stage: input.stage, parent: fanout.parent_work_id, works: fanout.works, text }) });
+    const prompt = (text) => ({ kind: "prompt", prompt: text, fingerprint: JSON.stringify({ stage: input.stage, parent: fanout.parent_work_id, state: fanout.state, graph: fanout.graph_revision }) });
     if (fanout.state === "coordinator_required")
         return prompt(`Continue the current ${input.stage} Stage using its authoritative packet. Materialize only its required Work graph with real dependencies. Do not launch children, finish the Stage, or start a successor. Return after registering the graph; the runtime will dispatch its ready Work.`);
     if (fanout.works.failed || fanout.works.cancelled)
@@ -73,7 +75,7 @@ export async function nextControllerFanout(context, input) {
         return { kind: "wait", reason: "work_receipts_pending" };
     if (fanout.works.created)
         throw new AppError("fanout_graph_stalled", "Created Work has no ready or running dependency path", 1);
-    return prompt(`All declared ${input.stage} child Work has settled (${fanout.works.completed} completed). Read the accepted result receipts and continue this Stage's semantic decision under its original packet. A rejected stage finish may return either a repair creation command or an already-registered repair Work. Execute only a returned repair creation command, then return. If it reports repair_required with an existing repair Work/start_command, do not invoke that start_command in this coordinator Session: return immediately so the controller can launch a fresh child. Do not start a successor Stage.`);
+    return prompt(`All declared ${input.stage} child Work has settled (${fanout.works.completed} completed). Read the accepted result receipts and continue this Stage's semantic decision under its original packet. A rejected stage finish with repair_required has already registered its repair Work. End this Turn immediately so the controller can launch a fresh child; do not create another repair or invoke its start_command in this coordinator Session. Do not start a successor Stage.`);
 }
 /** Normalize provider-observed topology only; never parse assistant prose. */
 export function controllerNativeChildren(receipt, rootSessionId) {

package/dist/services/hooks.js

@@ -12,7 +12,7 @@ import { prepareTextFile, prepareJsonText, prepareError } from "../cli/input-pre
 import { nativeSessionIdentity, storageSessionId } from "./session-identity.js";
 import { assertRecoveryHookCurrent } from "./run-recovery.js";
 import { observeLifecycleInvocation } from "./lifecycle-invocations.js";
-import { commandHasOption, commandOption, commandPosition, shellSuffixOffset, parseLifecycleCommand, lifecycleCommandFromPayload } from "./lifecycle-command.js";
+import { commandHasOption, commandOption, commandPosition, shellSuffixOffset, parseLifecycleCommand, lifecycleCommandFromPayload, continuationCommand } from "./lifecycle-command.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { activeFlowSessionsForProject, recordFlowSessionObservation } from "./sessions.js";
 const defaultProfileName = "default";
@@ -309,13 +309,13 @@ export function handleCodexHook(context, input) {
     if (!command)
         return { ok: true, observed: false, reason: "non_bash_tool" };
     const lifecycle = lifecycleFacts(command);
-    if (!lifecycle)
+    if (!lifecycle && !continuationCommand(command))
         return { ok: true, observed: false, reason: "event_not_participating", event: eventName };
     const parentProviderSessionId = rawChildProviderSessionId ? codexNativeParentId(payload, rawChildProviderSessionId) : null;
     // Resume legitimately receives an answer through stdin. It is matched by
     // immutable lifecycle arguments below; never reject or rewrite that pipe.
-    const { bootstrapStageStart } = lifecycle;
-    const invocationId = commandOption(lifecycle.invocation, "invocation-id");
+    const bootstrapStageStart = lifecycle?.bootstrapStageStart;
+    const invocationId = lifecycle ? commandOption(lifecycle.invocation, "invocation-id") : undefined;
     if (invocationId || context.env.DD_FLOW_DAEMON_ID) {
         const proof = context.codexHookProof;
         if (!proof || proof.daemonId !== context.env.DD_FLOW_DAEMON_ID || proof.rootSessionId !== rootProviderSessionId
@@ -337,7 +337,7 @@ export function handleCodexHook(context, input) {
             throw new AppError("project_not_registered", "Managed lifecycle invocation has no registered project", 1, { project_root: nativeProjectRoot ?? null });
         return { ok: true, observed: false, reason: "unrelated_cwd" };
     }
-    let matchKey = lifecycleMatchKey(lifecycle, project.root);
+    let matchKey = lifecycle ? lifecycleMatchKey(lifecycle, project.root) : null;
     // Codex retains the root session_id for a thread-spawned child, while the
     // payload transcript belongs to the current agent_id. Keep lineage separate
     // from ownership: otherwise a child overwrites the root transcript binding.
@@ -396,6 +396,10 @@ export function handleCodexHook(context, input) {
         ...(parentProviderSessionId ? { parent_session: nativeSessionIdentity("codex-desktop", parentProviderSessionId) } : {}),
         protocol_id: null
     };
+    if (!lifecycle) {
+        const persisted = context.db.writeTransaction(() => persist());
+        return { ...common, observed: persisted.inserted, duplicate: !persisted.inserted };
+    }
     if (invocationId || context.env.DD_FLOW_DAEMON_ID) {
         const daemonId = stringValue(context.env.DD_FLOW_DAEMON_ID);
         const toolCallId = stringValue(payload.tool_use_id) ?? stringValue(payload.event_id) ?? stringValue(payload.delivery_id) ?? stringValue(payload.id);
@@ -517,9 +521,9 @@ function recordZcodeLifecycle(context, input, invocationId) {
     if (!command || (toolName && toolName !== "Bash" && toolName !== "bash" && toolName !== "execute"))
         return { ok: true, observed: false, reason: "non_bash_tool" };
     const lifecycle = lifecycleFacts(command);
-    if (!lifecycle)
+    if (!lifecycle && !continuationCommand(command))
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (!invocationId && commandOption(lifecycle.invocation, "invocation-id"))
+    if (!invocationId && lifecycle && commandOption(lifecycle.invocation, "invocation-id"))
         return { ok: true, observed: false, reason: "cli_invocation_owns_admission" };
     const expectedRoot = resolveProjectRoot(input.projectRoot);
     const meta = objectRecord(hook._meta);
@@ -539,13 +543,13 @@ function recordZcodeLifecycle(context, input, invocationId) {
         throw new AppError("zcode_hook_event_missing", "ZCode native hook has no tool-use ID", 1);
     const eventKey = crypto.createHash("sha256").update(JSON.stringify(["zcode-acp", daemonId, providerSessionId, toolUseId])).digest("hex");
     const rewritten = invocationId ? command : commandWithHookEvent(command, eventKey);
-    if (lifecycle.bootstrapStageStart)
+    if (lifecycle?.bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
     const project = requireProjectByRoot(context, expectedRoot);
     const sessionId = storageSessionId(nativeSessionIdentity("zcode-acp", providerSessionId));
     const parentSessionId = parentProviderSessionId ? storageSessionId(nativeSessionIdentity("zcode-acp", parentProviderSessionId)) : null;
     const observedProfile = objectRecord(ddZcode.observedProfile);
-    let matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
+    let matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
     const eventNameForReceipt = invocationId ? "ToolCallObserved" : "PreToolUse";
     const persist = (scope) => {
         if (scope)
@@ -563,6 +567,8 @@ function recordZcodeLifecycle(context, input, invocationId) {
         const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: eventKey, harness: "zcode-acp", session: nativeSessionIdentity("zcode-acp", providerSessionId), ...(parentProviderSessionId ? { parent_session: nativeSessionIdentity("zcode-acp", parentProviderSessionId) } : {}), daemon_id: daemonId };
         return { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: rewritten } } };
     };
+    if (!lifecycle)
+        return context.db.writeTransaction(() => persist());
     let persistedResult;
     const receipt = observeLifecycleInvocation(context, {
         ...(invocationId ? { id: invocationId } : {}), command,
@@ -592,11 +598,11 @@ export function handleGrokEvent(context, input) {
         return { ok: true, observed: false, reason: "non_bash_tool" };
     }
     const lifecycle = lifecycleFacts(command);
-    if (!lifecycle)
+    if (!lifecycle && !continuationCommand(command))
         return { ok: true, observed: false, reason: "event_not_participating" };
-    const { bootstrapStageStart } = lifecycle;
+    const bootstrapStageStart = lifecycle?.bootstrapStageStart;
     const expectedRoot = resolveProjectRoot(input.projectRoot);
-    const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
+    const matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
     if (bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
     const project = requireProjectByRoot(context, expectedRoot);
@@ -692,10 +698,10 @@ function handleControlledToolEvent(context, input, event, harness) {
         return { ok: true, observed: false, reason: command ? "non_bash_tool" : "event_not_participating" };
     }
     const lifecycle = lifecycleFacts(command);
-    if (!lifecycle)
+    if (!lifecycle && !continuationCommand(command))
         return { ok: true, observed: false, reason: "event_not_participating" };
-    const { bootstrapStageStart } = lifecycle;
-    const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
+    const bootstrapStageStart = lifecycle?.bootstrapStageStart;
+    const matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
     if (bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
     const project = requireProjectByRoot(context, expectedRoot);

package/dist/services/lifecycle-command.js

@@ -12,6 +12,33 @@ const redirectionOperators = new Set(["<", ">", ">>", ">|", "<&", ">&", "<<<"]);
 export function parseLifecycleCommand(command) {
     return parseLifecycleCommandInner(command, false);
 }
+/** Exact diagnostic routes; these deliberately confer no lifecycle authority. */
+export function continuationCommand(command) {
+    let entries;
+    try {
+        entries = parse(command, name => `$${name}`);
+    }
+    catch {
+        return null;
+    }
+    if (!entries.every(entry => typeof entry === "string"))
+        return null;
+    const words = entries;
+    const start = words.findIndex(word => ["stage", "work"].includes(word));
+    if (start < 1)
+        return null;
+    const launcher = words.slice(0, start);
+    while (launcher[0] && /^[A-Za-z_][A-Za-z0-9_]*=/.test(launcher[0]))
+        launcher.shift();
+    const direct = launcher.length === 1 && (path.basename(launcher[0]) === "dd-flow" || launcher[0] === "$DD_FLOW_BIN");
+    const node = launcher.length === 2 && path.basename(launcher[0]) === "node" && (path.basename(launcher[1]) === "cli.js" || launcher[1] === "$DD_FLOW_BIN");
+    if (!direct && !node)
+        return null;
+    const args = parseCommandArgs(words.slice(start));
+    const route = args.positional.slice(0, 3).join(" ");
+    const operation = route === "work repair add" ? "work_repair_add" : args.positional[0] === "stage" && args.positional[1] === "block" ? "stage_block" : null;
+    return operation ? { operation, args } : null;
+}
 /** Preserve the historical Desktop contract: execute the payload, not its one-command shell wrapper. */
 export function unwrapShellCommand(command) {
     let entries;