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

package/dist/services/lifecycle-invocations.js

@@ -6,7 +6,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { AppError, errorRecord } from "../shared/errors.js";
 import { shortEntityReference } from "../shared/entity-references.js";
 import { resolveWorkReference } from "../storage/work-references.js";
-import { commandOption, lifecycleCommandFromPayload, parseLifecycleCommand, shellSuffixOffset } from "./lifecycle-command.js";
+import { commandOption, continuationCommand, lifecycleCommandFromPayload, parseLifecycleCommand, shellSuffixOffset } from "./lifecycle-command.js";
 import { requireProjectByRoot } from "./projects.js";
 import { assertRunMutationAllowed, assertStageSettlementAllowed, assertWorkSettlementAllowed, recoveryGuard } from "./run-recovery.js";
 import { readNativeDaemonState, requireManagedDaemonBinding } from "./managed-daemon-binding.js";
@@ -15,8 +15,49 @@ import { appendEvent } from "./run-controller-state.js";
 import { recoverCommittedWorkStart } from "./work-registry.js";
 import { observeCommandHook } from "./hooks.js";
 import { runtimeHarness } from "./execution-policy.js";
-import { assertPathWithin } from "../storage/paths.js";
+import { normalizedPathAlias, resolveContextualPaths } from "./command-context.js";
+import { isRegisteredRepair } from "./repair-intents.js";
+import { stageAttempt } from "./stage-work-graph.js";
 import { contextualPathOptionsForLifecycle } from "../cli/command-inputs.js";
+import { canonicalPath } from "../storage/paths.js";
+/** Auxiliary commands have no invocation capability, but may not escape their
+ * native daemon's project/RUN. Context aliases never grant mutation authority. */
+export function assertAuxiliaryCommandScope(context, command, projectRoot) {
+    const auxiliary = continuationCommand(command);
+    const daemonId = context.env.DD_FLOW_DAEMON_ID;
+    if (!auxiliary || !daemonId)
+        return;
+    const event = observedLifecycleNativeEvent(context, command, daemonId);
+    if (!event)
+        throw new AppError("invocation_receipt_missing", "Auxiliary command has no exact native receipt", 1, { phase: "prepare", effect: "no_effect" });
+    const project = context.db.get("SELECT root FROM projects WHERE id = ?", [event.project_id]);
+    if (!project || !projectRoot || canonicalPath(projectRoot, false) !== project.root)
+        throw new AppError("invocation_scope_mismatch", "Auxiliary command differs from its native project scope", 1, { phase: "prepare", effect: "no_effect" });
+    for (const record of managedProcessStatus(context)) {
+        if (record.project_id !== event.project_id || !record.run_id || !record.kind.endsWith("-daemon"))
+            continue;
+        const metadata = JSON.parse(record.metadata_json);
+        if (typeof metadata.state_dir !== "string")
+            continue;
+        let state;
+        try {
+            state = readNativeDaemonState(metadata.state_dir);
+        }
+        catch {
+            continue;
+        }
+        if (state.daemon_id !== daemonId)
+            continue;
+        requireManagedDaemonBinding(context, { stateDir: metadata.state_dir, projectId: event.project_id, runId: record.run_id });
+        const reference = auxiliary.args.options.get("run")?.[0] ?? auxiliary.args.positional[2];
+        const run = context.db.get("SELECT id FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [event.project_id, reference, reference]);
+        if (run?.id !== record.run_id)
+            throw new AppError("invocation_scope_mismatch", "Auxiliary command differs from its native RUN scope", 1, { phase: "prepare", effect: "no_effect" });
+        assertRunMutationAllowed(context, event.project_id, record.run_id, metadata.run_generation);
+        return;
+    }
+    throw new AppError("invocation_scope_unavailable", "Auxiliary command has no live managed daemon binding", 1, { phase: "prepare", effect: "no_effect" });
+}
 // Conclusive result/check rejections, never transport, ownership, registry or
 // unknown-effect failures. These validators reject before accepting the result.
 export function isRetryableLifecycleRejection(code, details = {}) {
@@ -122,9 +163,6 @@ function normalizedInvocationValue(key, 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("'", `'\\''`)}'`
@@ -181,23 +219,11 @@ export function expandLifecycleInvocationArgs(context, args, scope, operation) {
     const pathOptions = contextualPathOptionsForLifecycle(operation);
     const run = scope.runId ? context.db.get("SELECT id, short_id, workspace_root, run_root FROM runs WHERE id = ?", [scope.runId]) : undefined;
     const roots = { project: scope.projectRoot, workspace: run?.workspace_root, run: run?.run_root };
-    return args.map((value, index) => {
+    return resolveContextualPaths(args.map((value, index) => {
         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))
-            return value;
-        value = normalizedPathAlias(value);
-        if (!value.startsWith("@"))
-            return value;
-        const match = /^@(project|workspace|run)(?:\/(.*))?$/.exec(value);
-        if (!match)
-            throw new AppError("usage", `Unknown path alias: ${value}`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
-        const root = roots[match[1]];
-        if (!root)
-            throw new AppError("usage", `Path alias @${match[1]} is unavailable without a bound RUN`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
-        return assertPathWithin(root, path.join(root, match[2] ?? ""), `${match[1]}_alias`);
-    });
+        return value;
+    }), pathOptions, roots);
 }
 /** Validate alias spelling before native-receipt lookup, so a correctable
  * command typo is never reported as missing infrastructure evidence. */
@@ -259,7 +285,7 @@ export function assertLifecycleOutcomes(context, scope) {
             const outcome = JSON.parse(row.outcome_json);
             if (outcome.disposition === "retrying" && outcome.deadline <= Date.now())
                 throw new AppError("lifecycle_outcome_unknown", "Storage retry has no terminal receipt; reconcile its committed evidence", 1, { lifecycle_outcome: outcome, effect: "unknown" });
-            if (outcome.disposition === "fatal")
+            if (outcome.disposition === "fatal" && !isRegisteredRepair(context, outcome.error?.details?.continuation, { projectId: project.id, runId: scope.runId }))
                 throw new AppError(outcome.error?.code ?? "lifecycle_outcome_unknown", outcome.error?.message || "Mandatory lifecycle failed (historical receipt has no message)", 1, { ...outcome.error?.details, lifecycle_outcome: outcome });
         }
     }
@@ -272,7 +298,7 @@ export function assertLifecycleOutcomes(context, scope) {
     ORDER BY a.rowid`, [scope.projectRoot, scope.runId, scope.generation]);
     for (const row of rows) {
         const error = (row.outcome_json ? JSON.parse(row.outcome_json) : null)?.error;
-        if (typeof error?.code === "string" && !isCorrectableLifecycleRejection(error.code, error.details))
+        if (typeof error?.code === "string" && !isCorrectableLifecycleRejection(error.code, error.details) && !isRegisteredRepair(context, error.details?.continuation, { projectId: project.id, runId: scope.runId }))
             throw new AppError(error.code, typeof error.message === "string" ? error.message : "Mandatory lifecycle failed", 1, { ...(error.details ?? {}), invocation_id: row.id });
     }
 }
@@ -280,7 +306,8 @@ export function assertLifecycleOutcomes(context, scope) {
  * atomic controller notification; missing notifications reconcile from the row. */
 export function observeLifecycleCommand(context, command, nativeEvent) {
     const parsed = parseLifecycleCommand(command);
-    if (parsed.kind !== "standalone")
+    const auxiliary = continuationCommand(command);
+    if (parsed.kind !== "standalone" && !auxiliary)
         return () => { };
     let anchor;
     context.observeLifecycleHook = (projectId, eventId) => {
@@ -291,6 +318,7 @@ export function observeLifecycleCommand(context, command, nativeEvent) {
             return;
         let runId = context.db.get("SELECT run_id FROM sessions WHERE project_id = ? AND harness = ? AND (session_id = ? OR session_id = ? OR provider_session_id = ?) AND run_id IS NOT NULL ORDER BY session_id = ? DESC LIMIT 1", [projectId, event.harness, event.session_id, event.parent_session_id, event.parent_session_id, event.session_id])?.run_id;
         let generation;
+        let correlation = {};
         // A first Stage command precedes logical Session binding. Its native root
         // is already owned by the controller's retained create receipt.
         if (context.db.get("SELECT 1 FROM sqlite_master WHERE name = 'run_controllers'")) {
@@ -305,6 +333,8 @@ export function observeLifecycleCommand(context, command, nativeEvent) {
                     return;
                 runId = owners[0].run_id;
                 generation = owners[0].generation;
+                const current = JSON.parse(owners[0].state_json);
+                correlation = { stage: current.stage, ...(current.stage ? { attempt: stageAttempt(context, projectId, runId, current.stage) } : {}), controller_turn: current.turns };
             }
         }
         if (event.daemon_id) {
@@ -333,13 +363,13 @@ export function observeLifecycleCommand(context, command, nativeEvent) {
         }
         if (!runId)
             return;
-        anchor = { project_id: projectId, run_id: runId, generation: generation ?? recoveryGuard(context, projectId, runId)?.generation ?? 0, hook_event_id: eventId, session_id: event.session_id, harness: event.harness, operation: parsed.invocation.operation };
+        anchor = { project_id: projectId, run_id: runId, generation: generation ?? recoveryGuard(context, projectId, runId)?.generation ?? 0, hook_event_id: eventId, session_id: event.session_id, harness: event.harness, operation: parsed.kind === "standalone" ? parsed.invocation.operation : auxiliary.operation, ...correlation, ...(auxiliary ? { auxiliary: true } : {}) };
     };
     if (nativeEvent)
         context.observeLifecycleHook(nativeEvent.project_id, nativeEvent.id);
     else
         observeCommandHook(context, command);
-    const invocationId = commandOption(parsed.invocation, "invocation-id");
+    const invocationId = parsed.kind === "standalone" ? commandOption(parsed.invocation, "invocation-id") : undefined;
     if (!anchor && invocationId && !nativeEvent) {
         const attempt = load(context, invocationId);
         checkCommand(attempt, command);
@@ -359,7 +389,7 @@ export function observeLifecycleCommand(context, command, nativeEvent) {
             return;
         const error = outcome.error ? errorRecord(outcome.error) : undefined;
         const correctable = error && isCorrectableLifecycleRejection(error.code, error.details);
-        const record = { ...anchor, ...(error ? { error } : outcome), effect: error ? error.details.effect ?? (correctable ? "no_effect" : "unknown") : "committed", disposition: error ? correctable ? "correctable" : "fatal" : "completed" };
+        const record = { ...anchor, ...(error ? { error } : outcome), effect: error ? error.details.effect ?? (correctable ? "no_effect" : "unknown") : "committed", disposition: error ? auxiliary ? "pending_continuation" : correctable ? "correctable" : "fatal" : "completed" };
         try {
             context.db.writeTransaction(() => {
                 const retained = context.db.get("SELECT outcome_json FROM hook_events WHERE id = ?", [anchor.hook_event_id]);
@@ -550,7 +580,9 @@ export function settleLifecycleRejection(context, id, error) {
             details.recoverable = true;
             if (storageRetry)
                 details.storage_retry = 1;
-            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.";
+            details.retry_instruction = isRegisteredRepair(context, details.continuation)
+                ? "The repair is already registered. End this coordinator turn so the controller can launch its fresh child. Use retry_command only after that repair completes, with fresh semantic verification."
+                : "Correct only the evidenced defect, then use retry_command with the required result input. Reissuing the old command only reads its retained outcome.";
         }
         else if (isCorrectableLifecycleRejection(error.code, error.details)) {
             details.effect = "no_effect";
@@ -829,15 +861,17 @@ export function observedLifecycleNativeEvent(context, command, daemonId) {
         return null;
     const signature = (value) => {
         const parsed = parseLifecycleCommand(value);
-        if (parsed.kind !== "standalone" || parsed.invocation.wrapped)
+        const candidate = parsed.kind === "standalone" && !parsed.invocation.wrapped ? parsed.invocation : continuationCommand(value);
+        if (!candidate)
             return null;
-        return JSON.stringify([parsed.invocation.operation, parsed.invocation.args.positional,
-            [...parsed.invocation.args.options].filter(([key]) => !["json", "progress-jsonl", "hook-event-id"].includes(key)).sort(([a], [b]) => a.localeCompare(b))]);
+        return JSON.stringify([candidate.operation, candidate.args.positional,
+            [...candidate.args.options].filter(([key]) => !["json", "progress-jsonl", "hook-event-id"].includes(key)).sort(([a], [b]) => a.localeCompare(b))]);
     };
     const expected = signature(command);
     if (!expected)
         return null;
-    const eventKey = commandOption(invocation(command), "hook-event-id");
+    const parsed = parseLifecycleCommand(command);
+    const eventKey = parsed.kind === "standalone" ? commandOption(parsed.invocation, "hook-event-id") : undefined;
     const matches = context.db.all("SELECT project_id, id, event_key, sanitized_summary FROM hook_events WHERE daemon_id = ? AND status = 'observed' AND outcome_json IS NULL", [daemonId]).filter(row => {
         if (eventKey && row.event_key !== eventKey)
             return false;

package/dist/services/recovery-snapshot-database.js

@@ -49,7 +49,7 @@ export function captureRecoveryDatabase(source, output, projectId, runId, protoc
             merge_servers: "0", merge_sessions: "0", merge_queue: "0", lanes: "0", lane_locks: "0", lane_waiters: "0",
             sqlite_sequence: "0"
         };
-        for (const table of ["works", "check_receipts", "merge_requests", "flow_run_flag_mutations", "usage", "flow_session_segments", "flow_jobs", "run_recovery_guards", "run_controllers", "run_controls"])
+        for (const table of ["works", "stage_work_memberships", "repair_intents", "check_receipts", "merge_requests", "flow_run_flag_mutations", "usage", "flow_session_segments", "flow_jobs", "run_recovery_guards", "run_controllers", "run_controls"])
             rules[table] = ownRun;
         for (const table of ["plan_bindings", "plan_progress", "worktree_records", "audit_events"])
             rules[table] = `${ownProject} AND protocol_id IN (${protocols})`;

package/dist/services/repair-intents.js

@@ -0,0 +1,40 @@
+import crypto from "node:crypto";
+import { stageAttempt, stageCycle, bindStageWork } from "./stage-work-graph.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { AppError } from "../shared/errors.js";
+/** Checks finish before entering this synchronous registration transaction. */
+export function ensureAggregateRepair(context, input, create) {
+    if (!input.failures.length || input.failures.some(receipt => receipt.status !== "failed" && receipt.status !== "aborted"))
+        throw new AppError("repair_intent_invalid", "Repair requires settled failed receipts", 1);
+    const causes = input.failures.map(receipt => ({ id: receipt.id, epoch: receipt.verification_epoch, fingerprint: receipt.workspace_fingerprint })).sort((a, b) => a.id.localeCompare(b.id));
+    return ensureRepairIntent(context, { ...input, causes: { receipts: causes, origins: [...(input.origins ?? [])].sort() } }, create);
+}
+export function ensureRepairIntent(context, input, create) {
+    return context.db.writeTransaction(() => {
+        assertRunMutationAllowed(context, input.projectId, input.runId, input.generation);
+        const attempt = stageAttempt(context, input.projectId, input.runId, input.stage);
+        const payload = JSON.stringify({ project_id: input.projectId, run_id: input.runId, stage: input.stage, attempt, cycle: stageCycle(context, input.projectId, input.runId, input.stage), causes: input.causes });
+        const identity = crypto.createHash("sha256").update(payload).digest("hex");
+        const prior = context.db.get("SELECT work_id, payload_json FROM repair_intents WHERE identity = ?", [identity]);
+        if (prior && prior.payload_json !== payload)
+            throw new AppError("repair_intent_conflict", "Repair identity has different causes", 1);
+        const workId = prior?.work_id ?? create();
+        if (!prior) {
+            bindStageWork(context, { projectId: input.projectId, runId: input.runId, workId, stage: input.stage, attempt });
+            context.db.run("INSERT INTO repair_intents (identity, project_id, run_id, stage, attempt, payload_hash, payload_json, work_id, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)", [identity, input.projectId, input.runId, input.stage, attempt, identity, payload, workId, context.now()]);
+        }
+        return { schema_id: "dd-flow/continuation@1", kind: "repair_required", project_id: input.projectId, run_id: input.runId, stage: input.stage, attempt, identity, work_id: workId };
+    });
+}
+export function isRegisteredRepair(context, value, scope) {
+    if (!value || typeof value !== "object")
+        return false;
+    const receipt = value;
+    if (receipt.schema_id !== "dd-flow/continuation@1" || receipt.kind !== "repair_required")
+        return false;
+    if (scope && (receipt.project_id !== scope.projectId || receipt.run_id !== scope.runId))
+        return false;
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'repair_intents'"))
+        return false;
+    return Boolean(context.db.get("SELECT 1 FROM repair_intents i JOIN works w ON w.work_id = i.work_id AND w.project_id = i.project_id AND w.run_id = i.run_id WHERE i.identity = ? AND i.project_id = ? AND i.run_id = ? AND i.stage = ? AND i.attempt = ? AND i.work_id = ?", [receipt.identity, receipt.project_id, receipt.run_id, receipt.stage, receipt.attempt, receipt.work_id]));
+}

package/dist/services/run-controller.js

@@ -26,6 +26,7 @@ import { controllerNativeChildren, controllerStageEntryPrompt, nextControllerFan
 import { claimQueuedMergeRequest } from "./merge-server.js";
 import { prepareVnextCodeWorkspace } from "./vnext-code.js";
 import { requireRun, requireController, controllerReceipt, appendEvent, saveState, retainControllerContinuation, digest, digestBytes, errorRecord } from "./run-controller-state.js";
+import { assertNoCorrelatedRejection } from "./continuation-outcome.js";
 import { spawnController, recordControllerLauncher, claimControllerProcess, markControllerDispatchReady } from "./run-controller-process.js";
 import { controllerAdapter, controllerEnvironment, sessionArguments } from "./run-controller-adapter.js";
 import { resumeControllerSession, failControllerRecovery } from "./run-controller-recovery.js";
@@ -750,7 +751,9 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 saveState(context, row, state);
                 continue;
             }
-            retainControllerContinuation(state, fanout.fingerprint, { code: "fanout_stage_nonprogressing", message: "The coordinator repeated an unchanged Work-graph continuation", details: { stage: next.stage } });
+            if (state.last_continuation === fanout.fingerprint)
+                assertNoCorrelatedRejection(context, { projectId: row.project_id, runId: row.run_id, generation: row.generation, stage: next.stage, turn: state.turns });
+            retainControllerContinuation(state, fanout.fingerprint, { code: "fanout_stage_nonprogressing", message: "The coordinator repeated an unchanged Work-graph continuation", details: { stage: next.stage, before: state.last_continuation, after: fanout.fingerprint, controller_turn: state.turns } });
             saveState(context, row, state);
             await prompt(session, fanout.prompt);
         }

package/dist/services/runtime-command.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import { AppError } from "../shared/errors.js";
+/** Only the trusted launcher is a shell fragment; all caller data is argv. */
+export function runtimeCommand(context, args) {
+    return `${flowCommand(context)} ${args.map(shellArgument).join(" ")}`;
+}
+export function shellArgument(value) {
+    return /^[A-Za-z0-9_./:@=-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+export function flowCommand(context) {
+    const defaultHome = path.resolve(path.join(os.homedir(), ".dd-flow"));
+    const quoted = (value) => `"${value.replace(/[\\"$`]/g, character => `\\${character}`)}"`;
+    const home = `DD_FLOW_HOME=${quoted(context.ddFlowHome)}`;
+    // The runner binds this variable to its isolated published executable.
+    if (context.env.DD_FLOW_BIN && path.isAbsolute(context.env.DD_FLOW_BIN))
+        return `${home} "$DD_FLOW_BIN"`;
+    const isolated = path.join(context.ddFlowHome, "bin", "dd-flow");
+    if (context.ddFlowHome !== defaultHome && fs.existsSync(isolated))
+        return `${home} ${quoted(isolated)}`;
+    return context.ddFlowHome === defaultHome ? "dd-flow" : `${home} dd-flow`;
+}
+export function recoveryEvidenceInput(runRoot, receiptId) {
+    const basename = crypto.createHash("sha256").update(receiptId).digest("hex").slice(0, 20);
+    return {
+        schema_id: "dd-flow/continuation@1",
+        kind: "needs_input",
+        actor: "coordinator",
+        input_file: path.join(runRoot, `check-recovery-${basename}.json`),
+        input_contract: { reason: "Nonempty evidence explaining what environment was restored; do not invent recovery." },
+        instruction: "Only after restoring the environment, write this JSON file. Then use command_after_input. This is not permission to change product code or bypass the failed check."
+    };
+}
+export function checkRetryArgs(context, projectRoot, runId, receiptId) {
+    if (!receiptId)
+        return [];
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_root = ? AND id = ?", [projectRoot, runId]);
+    if (!run?.run_root)
+        throw new AppError("runtime_missing", "Check recovery requires a bound RUN root", 1);
+    return ["--retry-check", receiptId, "--reason-file", recoveryEvidenceInput(run.run_root, receiptId).input_file];
+}

package/dist/services/stage-pause.js

@@ -1,6 +1,5 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { quote } from "shell-quote";
 import { lifecycleRetryCommands, managedLifecycleCommand } from "./lifecycle-invocations.js";
@@ -13,6 +12,8 @@ import { requireProjectByRoot } from "./projects.js";
 import { appendFlowRunTimelineEvent, pauseFlowRunStage, resumeFlowRunStage } from "./runs.js";
 import { bindSessionForResume, refreshRunWorkProjection } from "./work-registry.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
+import { runtimeCommand } from "./runtime-command.js";
+export { flowCommand } from "./runtime-command.js";
 export function prepareStagePause(context, input) {
     if (typeof input.question !== "string" || !input.question.trim())
         throw new AppError("validation", "stage pause requires a non-empty user question", 2);
@@ -159,8 +160,10 @@ export function resumeStageAfterUser(context, input) {
     return { ok: true, outcome: "resumed", run_id: run.id, work_id: work.work_id, stage: stage.stage, pause_id: pause.id, question_path: pause.question_path, answer_path: answerPath, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, next_action: `continue_${stage.stage}` };
 }
 export function stagePauseCommand(context, input) {
-    const questionInputPath = `@run/works/${input.workId}/question-input.md`;
-    return managedLifecycleCommand(context, `${flowCommand(context)} stage pause ${shortEntityReference(input.runId)} --stage ${input.stage} --work ${shortEntityReference(input.workId)} --question-file '${questionInputPath}' --project-root ${quote([input.projectRoot])} --json`);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const questionInputPath = path.join(requireRunHome(run), "works", input.workId, "question-input.md");
+    return managedLifecycleCommand(context, runtimeCommand(context, ["stage", "pause", shortEntityReference(input.runId), "--stage", input.stage, "--work", shortEntityReference(input.workId), "--question-file", questionInputPath, "--project-root", input.projectRoot, "--json"]));
 }
 /** Render separate file-write and lifecycle-call instructions for HITL. */
 export function stagePauseCommandTemplate(command) {
@@ -185,24 +188,7 @@ Then run this standalone command:
 ${command}`;
 }
 function stageResumeCommand(context, input) {
-    return managedLifecycleCommand(context, `${flowCommand(context)} stage resume ${shortEntityReference(input.runId)} --stage ${input.stage} --work ${shortEntityReference(input.workId)} --answer-file ${quote([input.answerInputPath])} --project-root ${quote([input.projectRoot])} --json`);
-}
-export function flowCommand(context) {
-    const defaultHome = path.resolve(path.join(os.homedir(), ".dd-flow"));
-    // Desktop/ACP tool processes are not required to inherit the environment of
-    // the adapter that created their Session.  In an isolated runtime, a bare
-    // `dd-flow` can therefore select the host-global router despite a correct
-    // DD_FLOW_HOME.  The runner supplies an absolute executable for that case;
-    // make every generated lifecycle command self-contained.
-    const executable = context.env.DD_FLOW_BIN;
-    if (executable && path.isAbsolute(executable)) {
-        return `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} "$DD_FLOW_BIN"`;
-    }
-    const isolatedExecutable = path.join(context.ddFlowHome, "bin", "dd-flow");
-    if (context.ddFlowHome !== defaultHome && fs.existsSync(isolatedExecutable)) {
-        return `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} ${JSON.stringify(isolatedExecutable)}`;
-    }
-    return context.ddFlowHome === defaultHome ? "dd-flow" : `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow`;
+    return managedLifecycleCommand(context, runtimeCommand(context, ["stage", "resume", shortEntityReference(input.runId), "--stage", input.stage, "--work", shortEntityReference(input.workId), "--answer-file", input.answerInputPath, "--project-root", input.projectRoot, "--json"]));
 }
 function requireRun(context, projectId, id) {
     const rows = context.db.all("SELECT id, short_id, project_id, project_root, run_root, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, id, id]);

package/dist/services/stage-work-graph.js

@@ -0,0 +1,35 @@
+import { AppError } from "../shared/errors.js";
+export function stageAttempt(context, projectId, runId, stage) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!run)
+        throw new AppError("not_found", "Stage graph RUN is unavailable", 1);
+    const stages = JSON.parse(run.index_json).stage_runs ?? [];
+    return [...stages].reverse().find(item => item.stage === stage)?.attempt ?? "try-001";
+}
+export function bindStageWork(context, input) {
+    context.db.run("INSERT OR IGNORE INTO stage_work_memberships (project_id, run_id, work_id, stage, attempt, cycle) VALUES (?, ?, ?, ?, ?, ?)", [input.projectId, input.runId, input.workId, input.stage, input.attempt ?? stageAttempt(context, input.projectId, input.runId, input.stage), input.cycle ?? stageCycle(context, input.projectId, input.runId, input.stage)]);
+}
+export function stageCycle(context, projectId, runId, stage) {
+    if (stage !== "code" && stage !== "code-review")
+        return "";
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const cycle = row ? JSON.parse(row.index_json).variables?.["merge.source_repair"]?.cycle : undefined;
+    return typeof cycle === "string" ? cycle : stage === "code-review" ? "initial" : "";
+}
+export function stageWorkIds(context, projectId, runId, stage) {
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'stage_work_memberships'"))
+        throw new AppError("stage_graph_compatibility_required", "Stage Work membership is unavailable; use the RUN's pinned engine", 1);
+    return new Set(context.db.all("SELECT work_id FROM stage_work_memberships WHERE project_id = ? AND run_id = ? AND stage = ? AND attempt = ? AND cycle = ?", [projectId, runId, stage, stageAttempt(context, projectId, runId, stage), stageCycle(context, projectId, runId, stage)]).map(row => row.work_id));
+}
+/** Generic Work APIs also serve non-stage runs; null preserves that contract. */
+export function currentStageWorkIds(context, projectId, runId) {
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!row)
+        return null;
+    const index = JSON.parse(row.index_json);
+    const stage = [...(index.stage_runs ?? [])].reverse().find(item => item.status === "running")?.stage;
+    return stage ? stageWorkIds(context, projectId, runId, stage) : null;
+}
+export function stageGraphScope(context, projectId, runId, stage) {
+    return { project_id: projectId, run_id: runId, attempt: stageAttempt(context, projectId, runId, stage), cycle: stageCycle(context, projectId, runId, stage) };
+}

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

@@ -7,10 +7,10 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
 import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, freezeFlowRunReviewMode, gitFacts } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
-import { flowCommand } from "./stage-pause.js";
+import { runtimeCommand, checkRetryArgs } from "./runtime-command.js";
 import { assertStageStartHookEvent } from "./hooks.js";
 import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
-import { addVnextCodeRepair, prepareVnextCodeRepair, resumeAcceptedCodeStage } from "./vnext-code.js";
+import { addVnextCodeRepair, prepareVnextCodeRepair, registerAggregateCodeRepair, resumeAcceptedCodeStage } from "./vnext-code.js";
 import { finalCodeCheckDeclarations, runCodeChecks, validateFailedCheckRetry, workspaceChangedPaths } from "./code-checks.js";
 import { addWorkBatch, prepareWorkBatch, bindStageCoordinatorWork, finishStageCoordinatorWork, refreshRunWorkProjection } from "./work-registry.js";
 import { withStageSettlement, prepareFlowRunStageAttachment } from "./runs.js";
@@ -18,6 +18,7 @@ import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { writeStageReport } from "./stage-report-renderer.js";
 import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
+import { stageGraphScope } from "./stage-work-graph.js";
 import { prepareVnextMergeRequest } from "./vnext-merge.js";
 import { validateVnextCodeHandoff } from "./vnext-plan.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
@@ -93,8 +94,8 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-    const registered = addWorkBatch(context, { parentWorkId: rootWork.work_id, value: batch, prepared: items });
-    const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
+    const registered = addWorkBatch(context, { parentWorkId: rootWork.work_id, value: batch, prepared: items, stage, cycle });
+    const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true, scope: stageGraphScope(context, project.id, run.id, stage) });
     attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_started", work_id: rootWork.work_id, mode: mode.mode, mode_source: mode.source, groups, registered });
     return { ok: true, run_id: run.id, stage, mode: mode.mode, mode_source: mode.source, id: binding.work_session_id, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, review: { groups, works: registered }, next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
@@ -225,15 +226,14 @@ export async function finishVnextCodeReview(context, input) {
             outcome: "repair_required",
             retry_after_workspace_change: true,
             workspace_fingerprint: failed[0].workspace_fingerprint,
-            repair_task_file: `@run/intake/code-review-repair-${failed[0].id}.md`,
-            repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-file @run/intake/code-review-repair-${failed[0].id}.md --project-root ${JSON.stringify(projectRoot)} --json`,
-            retry_command: finishCommand(context, run.id, projectRoot, decisionFile, failed[0].id)
+            continuation: registerAggregateCodeRepair(context, { projectRoot, runId: run.id, stage, failures: failed, checks: finalChecks, generation }),
+            instruction: "Repair Work is already registered. End this Turn so the controller can launch a fresh child; after it finishes, repeat finish with the already accepted review decision. Do not redo review."
         });
     const stopTarget = executionStopTarget(run);
     const nextAction = stopTarget === "merge_completed" ? "start_merge" : "code_review_completed";
     const now = context.now();
     const startedAt = stageStartedAt(run, now);
-    const report = { schema_id: "dd-flow/stage-report@1", run_id: run.id, stage, generated_at: now, verdict: "done", semantic: { result: `Independent CODE review completed: ${reviewers.length} reviewer Work(s), ${repairs.length} repair Work(s).`, acceptance: ["all_selected_review_groups_completed", "all_material_findings_classified", ...(repairs.length ? ["all_accepted_repairs_completed"] : []), "current_final_gate_passed"], run_changed_files: changedPaths(run.workspace_root), checks: receipts.map((receipt) => receipt.command), evidence: [...reviewers.flatMap((work) => readJsonString(work.result).findings.flatMap((finding) => finding.evidence_refs)), ...receipts.map((receipt) => runRef(run.id, home, receipt.receipt_path))], next_action: nextAction, code_review: { mode, reviewer_work_ids: reviewers.map((work) => work.work_id), repair_work_ids: repairs.map((work) => work.work_id), decision } }, mechanical: { started_at: startedAt, finished_at: now, wall_clock_ms: Math.max(0, Date.parse(now) - Date.parse(startedAt)), git: gitFacts(run.workspace_root), session_stats_command: `${flowCommand(context)} stat run sessions ls --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json`, usage_stats_command: `${flowCommand(context)} stat usage --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json` }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html" }, validation: { status: "passed" } };
+    const report = { schema_id: "dd-flow/stage-report@1", run_id: run.id, stage, generated_at: now, verdict: "done", semantic: { result: `Independent CODE review completed: ${reviewers.length} reviewer Work(s), ${repairs.length} repair Work(s).`, acceptance: ["all_selected_review_groups_completed", "all_material_findings_classified", ...(repairs.length ? ["all_accepted_repairs_completed"] : []), "current_final_gate_passed"], run_changed_files: changedPaths(run.workspace_root), checks: receipts.map((receipt) => receipt.command), evidence: [...reviewers.flatMap((work) => readJsonString(work.result).findings.flatMap((finding) => finding.evidence_refs)), ...receipts.map((receipt) => runRef(run.id, home, receipt.receipt_path))], next_action: nextAction, code_review: { mode, reviewer_work_ids: reviewers.map((work) => work.work_id), repair_work_ids: repairs.map((work) => work.work_id), decision } }, mechanical: { started_at: startedAt, finished_at: now, wall_clock_ms: Math.max(0, Date.parse(now) - Date.parse(startedAt)), git: gitFacts(run.workspace_root), session_stats_command: runtimeCommand(context, ["stat", "run", "sessions", "ls", "--run", run.id, "--project-root", projectRoot, "--json"]), usage_stats_command: runtimeCommand(context, ["stat", "usage", "--run", run.id, "--project-root", projectRoot, "--json"]) }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html" }, validation: { status: "passed" } };
     // The request must exist before CODE-REVIEW becomes terminal. Otherwise a
     // merge-gate error creates an irrecoverable `done` report with no MRG-*.
     const acceptedPaths = changedPaths(run.workspace_root);
@@ -259,7 +259,7 @@ export async function finishVnextCodeReview(context, input) {
         }
         refreshRunWorkProjection(context, project.id, run.id);
     });
-    return { ok: true, run_id: run.id, stage, outcome, report_path: path.join(root, "stage-report.json"), next_action: nextAction, ...(mergeRequest ? { merge_request: mergeRequest, next: { kind: "start_stage", stage: "merge", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`) } } : {}) };
+    return { ok: true, run_id: run.id, stage, outcome, report_path: path.join(root, "stage-report.json"), next_action: nextAction, ...(mergeRequest ? { merge_request: mergeRequest, next: { kind: "start_stage", stage: "merge", command: managedLifecycleCommand(context, runtimeCommand(context, ["stage", "start", run.id, "--stage", "merge", "--project-root", projectRoot, "--json", "--progress-jsonl"])) } } : {}) };
 }
 export function readCodeReviewDecision(file, accepted, explicit = false, prepared) {
     if (!accepted)
@@ -327,7 +327,7 @@ export function assertCodeReviewCoverage(groups, reviewers) {
         throw new AppError("reviewer_coverage_invalid", "CODE-REVIEW requires every expected reviewer group", 2, { missing_groups: missing });
 }
 export function reviewerTask(home, group) { return `Read-only independent CODE review for ${group.key}. Assess every assigned aspect exactly once: ${group.aspect_ids.join(", ")}. Read the accepted PLAN, ${path.join(home, "05-code", "stage-report.json")}, and any files needed under the bounded CODE evidence root ${path.join(home, "05-code")}. Verify that universal and exclusive constraints (only, any, all, never, whole) and stated exceptions were not narrowed. For every changed mutation guarded by membership, ownership, authorization or parent lifecycle state, trace the decision to the write boundary: the predicate must remain in the write statement or the guard and write must share one explicit transaction with the needed lock. A separate earlier read is not proof of current authority or lifecycle state; report a material finding when this invariant is broken. Evidence closes a claim only when it exercises the named failure mechanism; a sequential negative test does not prove a concurrency race, and proof limits cannot waive an accepted obligation. Report only material, evidenced defects: a violated obligation or rule, direct evidence, impact, and minimum required outcome. Do not report taste, cosmetics, or untargeted refactoring. Use local finding ids FIND-001, FIND-002, and so on; dd-flow adds the Work-qualified canonical reference. Return dd-flow/code-review-result@1.`; }
-function orchestratorPrompt(context, input) { const { template, checks } = input; const decision = path.join(input.root, "decision.json"); return ["<stage_identity>", `- RUN: ${input.run.id}`, `- root Work: ${input.rootWork.work_id}`, `- stage: ${stage}`, `- mode: ${input.mode}`, "</stage_identity>", "", "<trusted_runtime_context>", `- project root: ${input.projectRoot}`, `- immutable write workspace: ${input.run.workspace_root}`, `- stage workspace: ${input.root}`, `- bounded CODE evidence root: ${path.join(input.run.run_root, "05-code")}`, "CODE is already semantically verified and all declared checks passed. Do not redo CODE verification; conduct independent quality review.", "</trusted_runtime_context>", "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", "Do not choose a provider delegation tool from this stage prompt. At the Work-graph boundary, return immediately; the shared controller supplies the selected adapter's native tool, exact parameters, child task, and wait contract. Each reviewer Work must run in one fresh child session. The coordinator must never invoke a Work start_command itself: a child runs its exact start_command after native delegation. Reviewers are read-only and must not create subagents. Do not interrupt a quiet worker.", `Ready reviewer Works: ${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(input.projectRoot)} --json`, `Write the decision to this exact absolute path, not a relative look-alike: ${decision}`, `Finish only after every reviewer Work settles and that exact file exists: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer results use local FIND-NNN ids. Classify them by the canonical WRK-.../FIND-NNN finding_ref returned by dd-flow. Fix P0/P1. Fix bounded safe P2 by default; defer only a legitimate P2 with a named DEF. P3 is an observation or a reasoned rejection, not automatic repair/DEF. For every disposition fix, check_refs is mandatory: choose the one or more causal checks from the accepted list below that the repair must rerun. Do not guess a CHK id or copy every check. The first successful Finish freezes this decision and creates one repair Work when needed. Do not invoke that Work's start_command from the coordinator Session: end this Turn so the controller can launch a fresh child, then call the returned next.finish_command after it completes. Internal invocation IDs are runtime-owned and must not be copied or reused. Review is not repeated.", "If the post-repair aggregate gate fails, do not stop after `code_review_gate_failed`: that rejected finish does not create a repair Work. In the same coordinator Turn, use the returned repair command with the failed receipt, a relevant completed origin Work ID, and a concise repair objective; then end the Turn so the runner can dispatch the new repair. The repair command creates Work only; do not invoke its start_command in the coordinator Session. Do not edit invisibly in the root orchestrator.", `Accepted repair checks: ${JSON.stringify(checks)}`, "```json", JSON.stringify({ schema_id: "dd-flow/code-review-decision@3", summary: "Evidence-backed conclusion.", findings: [{ finding_ref: "WRK-001-review/FIND-001", disposition: "fix | defer | reject | duplicate", reason: "Why this classification is correct.", check_refs: ["CHK-CAUSAL-CHECK only when disposition is fix"], def_id: "DEF-0001 only for an allowed P2 deferral", duplicate_of: "canonical finding_ref only for duplicate" }] }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n"); }
+function orchestratorPrompt(context, input) { const { template, checks } = input; const decision = path.join(input.root, "decision.json"); return ["<stage_identity>", `- RUN: ${input.run.id}`, `- root Work: ${input.rootWork.work_id}`, `- stage: ${stage}`, `- mode: ${input.mode}`, "</stage_identity>", "", "<trusted_runtime_context>", `- project root: ${input.projectRoot}`, `- immutable write workspace: ${input.run.workspace_root}`, `- stage workspace: ${input.root}`, `- bounded CODE evidence root: ${path.join(input.run.run_root, "05-code")}`, "CODE is already semantically verified and all declared checks passed. Do not redo CODE verification; conduct independent quality review.", "</trusted_runtime_context>", "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", "Do not choose a provider delegation tool from this stage prompt. At the Work-graph boundary, return immediately; the shared controller supplies the selected adapter's native tool, exact parameters, child task, and wait contract. Each reviewer Work must run in one fresh child session. The coordinator must never invoke a Work start_command itself: a child runs its exact start_command after native delegation. Reviewers are read-only and must not create subagents. Do not interrupt a quiet worker.", "Ready reviewer Works: " + runtimeCommand(context, ["work", "ls", "--run", input.run.id, "--ready", "--project-root", input.projectRoot, "--json"]), `Write the decision to this exact absolute path, not a relative look-alike: ${decision}`, `Finish only after every reviewer Work settles and that exact file exists: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer results use local FIND-NNN ids. Classify them by the canonical WRK-.../FIND-NNN finding_ref returned by dd-flow. Fix P0/P1. Fix bounded safe P2 by default; defer only a legitimate P2 with a named DEF. P3 is an observation or a reasoned rejection, not automatic repair/DEF. For every disposition fix, check_refs is mandatory: choose the one or more causal checks from the accepted list below that the repair must rerun. Do not guess a CHK id or copy every check. The first successful Finish freezes this decision and creates one repair Work when needed. Do not invoke that Work's start_command from the coordinator Session: end this Turn so the controller can launch a fresh child, then call the returned next.finish_command after it completes. Internal invocation IDs are runtime-owned and must not be copied or reused. Review is not repeated.", "If the aggregate gate fails with repair_required, its repair Work is already registered with all causal checks. End this Turn so the controller launches a fresh child. Do not copy receipt IDs, create another repair, invoke its start_command in the coordinator, or edit invisibly in the root orchestrator.", `Accepted repair checks: ${JSON.stringify(checks)}`, "```json", JSON.stringify({ schema_id: "dd-flow/code-review-decision@3", summary: "Evidence-backed conclusion.", findings: [{ finding_ref: "WRK-001-review/FIND-001", disposition: "fix | defer | reject | duplicate", reason: "Why this classification is correct.", check_refs: ["CHK-CAUSAL-CHECK only when disposition is fix"], def_id: "DEF-0001 only for an allowed P2 deferral", duplicate_of: "canonical finding_ref only for duplicate" }] }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n"); }
 function canonicalReviewEvidence(decision, reviewers) {
     const known = new Set(canonicalCodeFindings(reviewers).map((item) => item.finding_ref));
     const items = new Map(decision.findings.map((item) => [item.finding_ref, item]));
@@ -483,7 +483,9 @@ function requireRun(context, projectId, runId) { const run = context.db.get("SEL
     throw new AppError("not_found", "RUN is not registered", 1); return run; }
 function requireHome(run) { if (!run.run_root)
     throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1); return run.run_root; }
-export function finishCommand(context, runId, projectRoot, decision, retryCheckId) { const retry = retryCheckId ? ` --retry-check ${retryCheckId} --reason "<environment recovery evidence>"` : ""; return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage code-review --decision-file ${JSON.stringify(decision)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl${retry}`); }
+export function finishCommand(context, runId, projectRoot, decision, retryCheckId) {
+    return managedLifecycleCommand(context, runtimeCommand(context, ["stage", "finish", runId, "--stage", "code-review", "--decision-file", decision, "--project-root", projectRoot, "--json", "--progress-jsonl", ...checkRetryArgs(context, projectRoot, runId, retryCheckId)]));
+}
 function findFiles(root, name) { if (!fs.existsSync(root))
     return []; const out = []; for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
     const file = path.join(root, entry.name);