@deksden-com/dd-flow-cli 0.9.0-beta.122 → 0.9.0-beta.123

package/dist/services/run-controller.js

@@ -30,7 +30,7 @@ import { requireRun, requireController, controllerReceipt, appendEvent, saveStat
 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 { continueCodexCapacity } from "./codex-capacity.js";
+import { capacityDelay, continueCodexCapacity } from "./codex-capacity.js";
 import { resumeControllerSession, failControllerRecovery } from "./run-controller-recovery.js";
 import { captureControllerBoundary } from "./run-controller-capture.js";
 import { requestRunControl } from "./run-control-worker.js";
@@ -534,8 +534,15 @@ async function executeController(context, row, manifest, state, assertOwnership,
         await reconcilePromptPredecessor(session);
         const firstOperationId = operationId ?? `${row.controller_id}:prompt:${crypto.randomUUID()}`;
         const send = (value, id) => {
+            const retained = context.db.get("SELECT input_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND generation = ?", [id, row.controller_id, row.generation]);
+            if (retained) {
+                const dispatch = JSON.parse(retained.input_json);
+                if (![value, `${value}\n`].some(text => dispatch.prompt_sha256 === crypto.createHash("sha256").update(text).digest("hex")))
+                    throw new AppError("capacity_continuation_conflict", "Retained prompt differs from continuation", 1);
+                return controllerAdapter(executionContext, row, manifest, session, dispatch.args, assertOwner, id, cancellation.signal);
+            }
             const file = path.join(row.state_dir, `turn-${String(state.turns + 1).padStart(5, "0")}.md`);
-            fs.writeFileSync(file, `${value}\n`, { flag: "wx", mode: 0o600 });
+            fs.writeFileSync(file, value, { flag: "wx", mode: 0o600 });
             state.turns += 1;
             saveState(context, row, state);
             return controllerAdapter(executionContext, row, manifest, session, ["session", "prompt", "--session-id", session.id, "--prompt-file", file, ...sessionArguments(context, manifest, session)], assertOwner, id, cancellation.signal);
@@ -553,24 +560,45 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     throw error;
                 const inspect = (args, id) => runHarnessAdapter({ executable: manifest.adapters["codex-desktop"].executable,
                     args, env: controllerEnvironment(context, manifest, session), runtimeOwner: session.owner, operationId: id, timeoutMs: 30_000, signal: cancellation.signal });
-                const resumed = await continueCodexCapacity({ error, sessionId: session.id, operationId: firstOperationId,
+                const resumed = await continueCodexCapacity({ error, sessionId: session.id, operationId: firstOperationId, signal: cancellation.signal, allowSettledDescendants: true,
+                    retainedIntents: () => context.db.all("SELECT receipt_json FROM run_controller_operations WHERE controller_id = ? AND generation = ? AND operation_id IN (?, ?)", [row.controller_id, row.generation, firstOperationId, `${firstOperationId}:capacity:1:session.prompt`])
+                        .flatMap(item => { const retained = JSON.parse(item.receipt_json || "null"); return retained?.capacity_intent ? [retained.capacity_intent] : []; }).sort((a, b) => a.ordinal - b.ordinal),
                     inspectOperation: id => inspect(["daemon", "operation", "--state-dir", session.state_dir, "--operation-id", id, "--json"], `${id}:capacity-observe`),
-                    inspectSession: () => inspect(["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], `${firstOperationId}:capacity-inspect`),
+                    inspectSession: turnId => inspect(["session", "inspect", "--session-id", session.id, ...(turnId ? ["--turn-id", turnId] : []), ...sessionArguments(context, manifest, session)], `${firstOperationId}:capacity-inspect`),
                     assertCurrent: () => {
                         assertOwner();
+                    },
+                    decision: async () => {
+                        if (kind === "child") {
+                            const target = Object.entries(state.child_capacity ?? {}).find(([, retained]) => retained.operation_id === firstOperationId);
+                            if (!target)
+                                return "reconciliation_blocked";
+                            const seen = await inspect(["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], `${firstOperationId}:child-followup-observe`);
+                            const child = controllerNativeChildren(seen, session.id).find(item => item.session_id === target[0]);
+                            if (child?.parent_session_id === session.id && (child.status === "running" || child.terminal_turn_id && child.terminal_turn_id !== target[1].turn_id))
+                                return "completed";
+                        }
                         const view = getFlowRunStatus(executionContext, { projectRoot: manifest.request.project_root, runId: row.run_id });
                         const next = view.continuation;
+                        if (next.kind === "blocked")
+                            return "reconciliation_blocked";
+                        if (next.kind === "paused" && next.stage !== state.stage)
+                            return "paused";
+                        if (next.kind === "terminal" || next.stage !== state.stage)
+                            return "completed";
                         if (hitl) {
                             const answerId = firstOperationId.slice(0, -`:prompt:${row.generation}`.length);
                             const answer = context.db.get("SELECT input_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND status = 'accepted'", [answerId, row.controller_id]);
                             const accepted = answer && JSON.parse(answer.input_json);
                             const pause = view.index.stage_runs.find(item => item.stage === accepted?.stage)?.pause;
-                            if (next.kind !== "paused" || next.stage !== state.stage || !accepted || pause?.id !== accepted.pause_id || pause.work_id !== accepted.work_id || pause.answer_path)
-                                throw new AppError("capacity_continuation_blocked", "Accepted HITL pause changed during capacity wait", 1, { continuation: next });
-                        }
-                        else if (next.stage !== state.stage || ["terminal", "paused", "blocked", "wait"].includes(next.kind)) {
-                            throw new AppError("capacity_continuation_blocked", "RUN changed while native capacity was unavailable", 1, { continuation: next });
+                            if (next.kind !== "paused")
+                                return "continue";
+                            if (!accepted || pause?.id !== accepted.pause_id || pause.work_id !== accepted.work_id || pause.answer_path)
+                                return "paused";
                         }
+                        else if (next.kind === "paused")
+                            return "paused";
+                        return next.kind === "wait" ? "reconciliation_blocked" : "continue";
                     },
                     retainIntent: intent => context.db.writeTransaction(() => {
                         const changed = context.db.run("UPDATE run_controller_operations SET status = 'failed', receipt_json = ?, updated_at = ? WHERE operation_id = ? AND controller_id = ? AND generation = ? AND status = 'outcome_unknown'", [JSON.stringify({ capacity_intent: intent }), context.now(), intent.predecessor, row.controller_id, row.generation]);
@@ -579,7 +607,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                         appendEvent(context, row.controller_id, "capacity_continuation", intent);
                     }),
                     prompt: (id, value) => send(value, id),
-                    ...(resumeCommand ? { continuationText: `The preceding Turn failed before any tool call. Continue the same accepted HITL answer in this Session. If the pause is still current, run this exact previously issued standalone command once without changing the answer:\n\n${resumeCommand}\n\nDo not accept or deliver the answer again if the pause has changed.` } : {}) });
+                    ...(resumeCommand ? { continuationText: `Continue the same accepted HITL task in this Session. First inspect current durable RUN and pause state. Only if the exact pause still awaits the accepted answer, run this previously issued command once:\n\n${resumeCommand}\n\nNever replay an already committed answer. Otherwise use only the current issued successor.` } : {}) });
                 if (!resumed)
                     throw error;
                 receipt = resumed;
@@ -773,18 +801,22 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 const prior = child && state.child_capacity?.[child.session_id];
                 const links = child ? context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: "codex-desktop", session_id: child.session_id })]) : [];
                 if (child && turnId && native && terminalCodexOverload(native, child.session_id, turnId)
-                    && child.native_turn_items?.observed === true && child.native_turn_items.possible_effects === false
+                    && child.native_turn_items?.observed === true && (child.native_turn_items.possible_effects === false || child.native_turn_items.pending === false)
                     && inspected.settled === true && child.parent_session_id === session.id && links.length <= 1
-                    && (!links.length || links[0].status === "running") && (prior?.attempts ?? 0) < 2) {
-                    if (prior?.turn_id === turnId)
+                    && (!links.length || links[0].status === "running") && ((prior?.attempts ?? 0) < 2 || prior?.turn_id === turnId && prior.dispatched === false)) {
+                    const prepared = prior?.turn_id === turnId && prior.dispatched === false && prior.operation_id && prior.not_before ? prior : null;
+                    if (prior?.turn_id === turnId && !prepared)
                         throw new AppError("capacity_child_followup_unconfirmed", "Parent continuation did not start a new native child Turn", 1, { child_session_id: child.session_id, turn_id: turnId });
-                    const attempt = (prior?.attempts ?? 0) + 1;
+                    const attempt = prepared ? prepared.attempts : (prior?.attempts ?? 0) + 1;
+                    const wait = prepared ? Math.max(0, Date.parse(prepared.not_before) - Date.now()) : capacityDelay(native, attempt);
+                    if (!Number.isFinite(wait) || wait > 30_000)
+                        throw new AppError("capacity_child_retry_delay_exceeded", "Native child retry delay exceeds the bounded continuation window", 1, { child_session_id: child.session_id, delay_ms: wait });
+                    const operationId = prepared?.operation_id ?? `${row.controller_id}:child:${digest([child.session_id, turnId]).slice(0, 16)}:followup:${attempt}`;
                     state.child_capacity ??= {};
-                    state.child_capacity[child.session_id] = { turn_id: turnId, attempts: attempt };
+                    state.child_capacity[child.session_id] = { turn_id: turnId, attempts: attempt, operation_id: operationId, not_before: prepared?.not_before ?? new Date(Date.now() + wait).toISOString(), dispatched: false };
                     saveState(context, row, state);
-                    const operationId = `${row.controller_id}:child:${digest([child.session_id, turnId]).slice(0, 16)}:followup:${attempt}`;
                     appendEvent(context, row.controller_id, "capacity_child_followup", { child_session_id: child.session_id, turn_id: turnId, attempt, operation_id: operationId });
-                    await delay(attempt === 1 ? 5_000 : 15_000);
+                    await delay(wait, undefined, { signal: cancellation.signal });
                     assertOwner();
                     const current = getFlowRunStatus(executionContext, { projectRoot: manifest.request.project_root, runId: row.run_id });
                     if (current.continuation.stage !== state.stage || ["terminal", "paused", "blocked", "wait"].includes(current.continuation.kind))
@@ -792,13 +824,20 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     const fresh = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
                     const still = controllerNativeChildren(fresh, session.id).find(item => item.session_id === child.session_id);
                     const currentLinks = context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: "codex-desktop", session_id: child.session_id })]);
+                    if (still?.status === "completed" && currentLinks.length <= 1 && currentLinks.every(link => link.status === "completed")) {
+                        state.last_receipt = fresh;
+                        saveState(context, row, state);
+                        continue;
+                    }
                     if (fresh.settled !== true || !still || still.parent_session_id !== session.id || still.status !== "failed" || still.terminal_turn_id !== turnId
-                        || still.native_turn_items?.observed !== true || still.native_turn_items.possible_effects !== false || currentLinks.length > 1
+                        || still.native_turn_items?.observed !== true || still.native_turn_items.possible_effects !== false && still.native_turn_items.pending !== false || currentLinks.length > 1
                         || currentLinks.some(link => link.status !== "running"))
                         throw new AppError("capacity_child_followup_blocked", "Native child or Work changed during capacity wait", 1, { child_session_id: child.session_id, turn_id: turnId });
                     assertOwner();
-                    const text = `The existing native child ${child.session_id} has a confirmed effect-free failed Turn. Use the native followup_task tool exactly once for that same child ID with this short message: "Continue your assigned Work from its current durable state. Do not repeat an observed lifecycle command. Finish only the original Work." Do not spawn another child, claim another Work, or perform the child's Work in this parent Turn. End this Turn after the followup_task response.`;
+                    const text = `The existing native child ${child.session_id} has a confirmed terminal overloaded Turn. Use the native followup_task tool exactly once for that same child ID with this short message: "Continue your assigned Work from its current durable state. Do not repeat an observed lifecycle command. Finish only the original Work." Do not spawn another child, claim another Work, or perform the child's Work in this parent Turn. End this Turn after the followup_task response.`;
                     await prompt(session, text, operationId, "child");
+                    state.child_capacity[child.session_id].dispatched = true;
+                    saveState(context, row, state);
                     const after = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
                     state.last_receipt = after;
                     saveState(context, row, state);
@@ -829,7 +868,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 const results = await Promise.allSettled(fanout.works.map(async (work) => {
                     try {
                         assertOwner();
-                        const receipt = await launchExternalWork(executionContext, { workId: work.work_id, stage: next.stage });
+                        const receipt = await launchExternalWork(executionContext, { workId: work.work_id, stage: next.stage, signal: cancellation.signal });
                         if (fatal)
                             throw fatal;
                         appendEvent(context, row.controller_id, "external_work_observed", { work_id: work.work_id, receipt });

package/dist/services/run-observations.js

@@ -90,7 +90,7 @@ export function runObservations(context, projectId, runId) {
             const actual = fs.realpathSync(file);
             if (!inside(home, actual))
                 throw new Error("journal escaped owned home");
-            fd = fs.openSync(actual, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+            fd = fs.openSync(actual, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
             if (!fs.fstatSync(fd).isFile())
                 throw new Error("journal is not a regular file");
             replayToolJournal(file, { harness: source.session.harness_id, rootSessionId: sessionId, text: fs.readFileSync(fd, "utf8"), ...(source.session.harness_id === "codex-desktop" ? { expectedSessionIds: expectedCodexIds } : {}) }, reducer);
@@ -114,7 +114,9 @@ export function runObservations(context, projectId, runId) {
     // Select transcript fallback only after replay reveals an actual gap.
     for (const session of sessions) {
         const nativeId = session.provider_session_id ?? session.session_id;
-        if (!session.transcript_path || covered().has(JSON.stringify({ harness_id: session.harness, session_id: nativeId })))
+        const sessionSummary = reducer.summary(nativeId);
+        if (!session.transcript_path || covered().has(JSON.stringify({ harness_id: session.harness, session_id: nativeId }))
+            && sessionSummary.completeness === "complete" && sessionSummary.outcome_completeness === "complete")
             continue;
         const id = `transcript:${session.harness}:${nativeId}`;
         add(id, nativeId, session.transcript_path, home, "current", session.harness);
@@ -136,6 +138,9 @@ export function runObservations(context, projectId, runId) {
         if (!expectedIds.has(JSON.stringify(event.session))) {
             reducer.turns.delete(key);
         }
+    for (const [key, event] of reducer.sources)
+        if (!expectedIds.has(JSON.stringify(event.session)))
+            reducer.sources.delete(key);
     const summary = reducer.summary();
     const observed = new Set(summary.sessions.map(s => JSON.stringify(s.session)));
     const missing = expected.filter(s => !observed.has(JSON.stringify(s)));

package/dist/services/stage-report-renderer.js

@@ -39,6 +39,7 @@ export function acceptStagePacket(context, input) {
     context.db.afterCommit(() => publishStagePacket(context, input.projectId, input.runId, input.stage, input.prepared.file));
 }
 export function publishStagePacket(context, projectId, runId, stage, file) {
+    file = resolveStagePublicationPath(context, projectId, runId, file);
     assertPublicationPath(context, projectId, runId, file);
     fs.mkdirSync(path.dirname(file), { recursive: true });
     withProjectionLock(`${file}.publish-lock`, () => {
@@ -47,7 +48,7 @@ export function publishStagePacket(context, projectId, runId, stage, file) {
         const index = run ? JSON.parse(run.index_json) : null;
         const currentAttempt = index?.stage_runs?.find((item) => item.stage === stage)?.attempt;
         const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' ORDER BY id DESC", [projectId]);
-        const packet = rows.map((row) => JSON.parse(row.payload_json)).find((item) => item.run_id === runId && item.stage === stage && item.attempt === currentAttempt && item.file === file);
+        const packet = rows.map((row) => JSON.parse(row.payload_json)).find((item) => item.run_id === runId && item.stage === stage && item.attempt === currentAttempt && resolveStagePublicationPath(context, projectId, runId, item.file) === file);
         if (!packet)
             return;
         const bytes = Buffer.from(packet.base64, "base64");
@@ -78,6 +79,7 @@ export function acceptStageReport(context, input) {
 }
 /** Replays the latest committed receipt, never an obsolete attempt. */
 export function publishStageReport(context, projectId, runId, stage, root) {
+    root = resolveStagePublicationPath(context, projectId, runId, root);
     assertPublicationPath(context, projectId, runId, root);
     withProjectionLock(`${root}.report-publish-lock`, () => {
         assertPublicationPath(context, projectId, runId, root);
@@ -85,7 +87,7 @@ export function publishStageReport(context, projectId, runId, stage, root) {
         const index = run ? JSON.parse(run.index_json) : null;
         const currentAttempt = index?.stage_runs?.find((item) => item.stage === stage)?.attempt;
         const events = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_report' ORDER BY id DESC", [projectId]);
-        const receipt = events.map((row) => JSON.parse(row.payload_json)).find((item) => item.run_id === runId && item.stage === stage && item.root === root && item.attempt === currentAttempt);
+        const receipt = events.map((row) => JSON.parse(row.payload_json)).find((item) => item.run_id === runId && item.stage === stage && item.attempt === currentAttempt && resolveStagePublicationPath(context, projectId, runId, item.root) === root);
         if (!receipt)
             return;
         fs.mkdirSync(root, { recursive: true });
@@ -104,6 +106,27 @@ export function publishStageReport(context, projectId, runId, stage, root) {
         }
     });
 }
+/** Operational destinations follow validated imports, while audit bytes retain
+ * their original locators. SQL-only so readers may also use it in settlement. */
+export function resolveStagePublicationPath(context, projectId, runId, locator) {
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!run?.run_root || !path.isAbsolute(locator))
+        throw new AppError("stage_packet_invalid", "Stage publication has no absolute bound RUN locator", 1, { run_id: runId, locator });
+    let destination = path.resolve(locator);
+    const mappings = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.publication_relocation' ORDER BY id", [projectId]);
+    for (const row of mappings) {
+        const mapping = JSON.parse(row.payload_json);
+        if (mapping.run_id !== runId || !path.isAbsolute(mapping.from) || !path.isAbsolute(mapping.to))
+            continue;
+        const relative = path.relative(mapping.from, destination);
+        if (relative && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+            destination = path.resolve(mapping.to, relative);
+    }
+    const relative = path.relative(run.run_root, destination);
+    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        throw new AppError("publication_pending", "Stage publication escaped its bound RUN lineage", 1, { effect: "committed", run_id: runId, locator });
+    return destination;
+}
 /** Recheck the actual destination after preparation: a missing leaf may have
  * an existing symlink ancestor, and retained packet bytes never authorize it. */
 function assertPublicationPath(context, projectId, runId, file) {

package/dist/services/verification-matrix.js

@@ -4,13 +4,18 @@ import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { checkReceiptEvidenceValid, checkReceipts, effectiveCheckDeclarations } from "./code-checks.js";
-import { acceptStagePacket, prepareStagePacket, publishStagePacket } from "./stage-report-renderer.js";
+import { acceptStagePacket, prepareStagePacket, publishStagePacket, resolveStagePublicationPath } from "./stage-report-renderer.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
 export const verificationMatrixContract = "dd-flow/verification-matrix@1";
 /** A view of already validated facts: never a gate or a receipt selector. */
 export function buildVerificationMatrix(input) {
     const sourceCatalog = new Map();
+    const pathChecksums = new Map();
     for (const source of input.sources) {
+        const location = JSON.stringify([source.root, source.path]);
+        if (pathChecksums.has(location) && pathChecksums.get(location) !== source.sha256)
+            throw new AppError("verification_matrix_source_changed", "Matrix source aliases have conflicting checksums", 1, { root: source.root, path: source.path });
+        pathChecksums.set(location, source.sha256);
         const identity = JSON.stringify([source.role, source.root, source.path]);
         const prior = sourceCatalog.get(identity);
         if (prior && prior.sha256 !== source.sha256)
@@ -105,9 +110,24 @@ export function prepareRunVerificationMatrix(context, input) {
     const ownership = Object.fromEntries(protocols.map((protocol, i) => [protocol, protocolize.obligation_ownership.filter(item => item.member_keys.includes(protocolize.delivery.members[i].key)).map(item => item.obligation_id)]));
     const skeleton = input.stage === "plan" && input.role === "input";
     const plans = [];
-    const predecessor = input.stage === "plan-review" ? "plan" : input.stage === "code" ? "plan-review" : input.stage === "code-review" ? "code" : input.stage === "merge" ? "code-review" : null;
-    const priorMatrix = input.role === "input" && predecessor ? latestRunVerificationMatrix(context, input.projectId, input.runId, predecessor) : null;
+    const reviewSkipped = index.settings?.code_review?.mode === "off" && Boolean(index.settings.code_review.reason?.trim()) && !index.stage_runs?.some(item => item.stage === "code-review");
+    const predecessor = input.stage === "plan-review" ? "plan" : input.stage === "code" ? "plan-review" : input.stage === "code-review" ? "code" : input.stage === "merge" ? reviewSkipped ? "code" : "code-review" : null;
+    const priorMatrix = input.role === "input" && predecessor ? latestRunVerificationMatrix(context, input.projectId, input.runId, predecessor, "output") : null;
+    if (input.role === "input" && predecessor && !priorMatrix)
+        throw new AppError("verification_matrix_packet_missing", "Marked Stage requires its accepted predecessor output matrix", 1, { stage: input.stage, predecessor });
     if (!skeleton) {
+        const batchPath = "03-plan/code-work-batch.json", batchFile = safePath(home, batchPath);
+        if (!fs.existsSync(batchFile))
+            throw new AppError("verification_matrix_source_missing", "Marked matrix requires its generated CODE batch", 1, { path: batchPath });
+        const batchBytes = fs.readFileSync(batchFile), batchSha = digest(batchBytes);
+        const acceptedBatch = priorMatrix?.matrix.sources.find(source => source.role === "code_work_batch");
+        if (acceptedBatch && acceptedBatch.sha256 !== batchSha)
+            throw new AppError("verification_matrix_source_changed", "CODE batch differs from accepted predecessor matrix", 1, { path: batchPath, expected: acceptedBatch.sha256, current: batchSha });
+        const batchSnapshot = `${vnextStageDirectory(input.stage)}/verification/sources/${batchSha}/code-work-batch.json`;
+        packets.push(prepareStagePacket(safePath(home, batchSnapshot), batchBytes));
+        sources.push({ role: "code_work_batch", root: "run", path: batchSnapshot, sha256: batchSha });
+        if (input.stage === "merge" && input.role === "output")
+            sources.push({ role: "code_work_batch_current", root: "run", path: batchPath, sha256: batchSha });
         for (const protocol of protocols) {
             const relative = `.memory-bank/protocol/${protocol}/plan.json`, file = safePath(workspace, relative);
             // PLAN bytes are retained before MERGE cleanup; later recovery does not
@@ -266,9 +286,9 @@ export function latestRunVerificationMatrix(context, projectId, runId, stage, ro
             continue;
         if (matrix.schema_id !== verificationMatrixContract || matrix.header.run_id !== runId || matrix.header.stage !== stage || matrix.header.stage_attempt !== attempt)
             throw new AppError("stage_packet_invalid", "Retained matrix owner differs from its packet", 1);
-        safePath(run.run_root, path.relative(run.run_root, packet.file), false);
+        packet.file = resolveStagePublicationPath(context, projectId, runId, packet.file);
         const mdFile = packet.file.replace(/\.json$/, ".md");
-        const paired = rows.map(row => JSON.parse(row.payload_json)).find(item => item.run_id === runId && item.stage === stage && item.attempt === attempt && item.file === mdFile);
+        const paired = rows.map(row => JSON.parse(row.payload_json)).find(item => item.run_id === runId && item.stage === stage && item.attempt === attempt && resolveStagePublicationPath(context, projectId, runId, item.file) === mdFile);
         if (!paired)
             throw new AppError("stage_packet_invalid", "Retained matrix lacks its exact Markdown packet", 1);
         const mdBytes = Buffer.from(paired.base64, "base64");
@@ -277,9 +297,9 @@ export function latestRunVerificationMatrix(context, projectId, runId, stage, ro
         const md = { file: mdFile, bytes: mdBytes, sha256: paired.sha256 };
         const json = { file: packet.file, bytes, sha256: packet.sha256 };
         const metadata = { contract: verificationMatrixContract, role: matrix.header.role, completeness: matrix.header.completeness, source_fingerprint: matrix.header.source_fingerprint, json: { path: slash(path.relative(run.run_root, packet.file)), sha256: packet.sha256 }, markdown: { path: slash(path.relative(run.run_root, mdFile)), sha256: md.sha256 } };
-        const sourcePackets = matrix.sources.filter(source => source.role.startsWith("plan:") && source.root === "run").map(source => {
+        const sourcePackets = matrix.sources.filter(source => (source.role.startsWith("plan:") || source.role === "code_work_batch") && source.root === "run").map(source => {
             const file = safePath(run.run_root, source.path, false);
-            const retained = rows.map(row => JSON.parse(row.payload_json)).find(item => item.run_id === runId && item.stage === stage && item.attempt === attempt && item.file === file && item.sha256 === source.sha256);
+            const retained = rows.map(row => JSON.parse(row.payload_json)).find(item => item.run_id === runId && item.stage === stage && item.attempt === attempt && resolveStagePublicationPath(context, projectId, runId, item.file) === file && item.sha256 === source.sha256);
             if (!retained)
                 throw new AppError("stage_packet_invalid", "Matrix PLAN source lacks retained bytes", 1, { path: source.path });
             const bytes = Buffer.from(retained.base64, "base64");

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

@@ -25,6 +25,7 @@ import { prepareVnextMergeRequest } from "./vnext-merge.js";
 import { validateVnextCodeHandoff } from "./vnext-plan.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
 import { prepareJsonFile, prepareOutputFile } from "../cli/input-preparation.js";
+import { reviewerSourceInputs, reviewerSourceInstruction } from "./review-copy.js";
 const stage = "code-review";
 const stageDir = vnextStageDirectory(stage);
 const baselineAspects = ["goal_traceability", "coding_standards_design_review", "verification_evidence_review"];
@@ -56,14 +57,15 @@ export function prepareVnextCodeReviewStart(context, input) {
     const cycle = reviewCycle(run);
     const codeReportSha256 = sha256File(path.join(home, "05-code", "stage-report.json"));
     const groups = mode.mode === "off" ? [] : reviewGroups(home);
-    const batch = { works: groups.map((group, index) => ({ key: `code-review-${index + 1}`, task: reviewerTask(home, group), launch_policy: "fresh_agent_required", result_schema: "dd-flow/code-review-result@1", payload: { kind: "code-review", review_cycle: cycle, group, read_only: true } })) };
+    const reviewerInputs = mode.mode === "off" ? [] : reviewerSourceInputs(run.workspace_root, groups.flatMap(group => group.aspect_ids));
+    const batch = { works: groups.map((group, index) => ({ key: `code-review-${index + 1}`, task: `${reviewerTask(home, group)}\n${reviewerSourceInstruction(run.workspace_root, group.aspect_ids)}`, launch_policy: "fresh_agent_required", result_schema: "dd-flow/code-review-result@1", payload: { kind: "code-review", review_cycle: cycle, group, read_only: true } })) };
     const items = mode.mode === "off" ? [] : prepareWorkBatch(context, { parentWorkId: rootWork.work_id, value: batch });
     const template = mode.mode === "off" ? "" : read(path.join(run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code-review.md"));
     const checks = mode.mode === "off" ? [] : acceptedCodeChecks(context, project.id, run.id).map(({ id, purpose }) => ({ id, purpose }));
     for (const name of ["review-context.json", ...(mode.mode === "off" ? ["decision.json"] : ["review-work-batch.json", "fanout.json"])])
         prepareOutputFile(path.join(root, name));
     const matrix = mode.mode === "off" ? null : prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "input", stageAttempt: attachment.attempt });
-    return { ...common, resumed: false, mode, cycle, codeReportSha256, groups, batch, items, template, checks, matrix };
+    return { ...common, resumed: false, mode, cycle, codeReportSha256, groups, batch, items, template, checks, matrix, reviewerInputs };
 }
 export function startVnextCodeReview(context, input, prepared = prepareVnextCodeReviewStart(context, input)) {
     const { projectRoot, project, run, root, rootWork, existingPrompt } = prepared;
@@ -88,7 +90,7 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
     freezeFlowRunReviewMode(context, { projectRoot, runId: run.id, review: "code", mode: mode.mode, source: mode.source, reason: mode.reason });
     const promptPath = path.join(root, "stage-prompt.md");
     const reviewContextPath = path.join(root, "review-context.json");
-    fs.writeFileSync(reviewContextPath, `${JSON.stringify({ schema_id: "dd-flow/code-review-context@1", cycle, mode: mode.mode, mode_source: mode.source, mode_reason: mode.reason, ...(mode.mode !== "off" ? { read_only_input: { parent_work_id: rootWork.work_id, version: 3 } } : {}), code_report_sha256: codeReportSha256, review_batch_sha256: sha256Value(`${JSON.stringify(batch, null, 2)}\n`), aspect_map_checksums: aspectMapChecksums }, null, 2)}\n`);
+    fs.writeFileSync(reviewContextPath, `${JSON.stringify({ schema_id: "dd-flow/code-review-context@1", reviewer_inputs: prepared.reviewerInputs, cycle, mode: mode.mode, mode_source: mode.source, mode_reason: mode.reason, ...(mode.mode !== "off" ? { read_only_input: { parent_work_id: rootWork.work_id, version: 3 } } : {}), code_report_sha256: codeReportSha256, review_batch_sha256: sha256Value(`${JSON.stringify(batch, null, 2)}\n`), aspect_map_checksums: aspectMapChecksums }, null, 2)}\n`);
     if (mode.mode === "off") {
         fs.writeFileSync(path.join(root, "decision.json"), `${JSON.stringify(disabledReviewDecision(), null, 2)}\n`);
         const prompt = `<stage_identity>\n- RUN: ${run.id}\n- stage: code-review\n- mode: off\n</stage_identity>\n\nCODE-REVIEW is disabled by the frozen RUN configuration. Finish with: ${finishCommand(context, run.id, projectRoot, path.join(root, "decision.json"))}\n${stageLifecycleInstruction}\n`;
@@ -352,7 +354,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: " + 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 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 passed its declared checks; each check proves only its named contour and proof limits, not complete semantic acceptance. Conduct independent quality review and do not manually rerun every declared check.", "</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]));

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

@@ -23,6 +23,7 @@ import { getStageFanoutCapacity, readFanoutDescriptor, subagentCapacityKey, writ
 import { stageGraphScope } from "./stage-work-graph.js";
 import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, latestRunVerificationMatrix } from "./verification-matrix.js";
+import { reviewerSourceInputs, reviewerSourceInstruction } from "./review-copy.js";
 const stage = "plan-review";
 const stageDir = vnextStageDirectory(stage);
 const reviewTask = "Independently review the accepted PLAN and decide whether CODE may open.";
@@ -55,6 +56,10 @@ export function prepareVnextPlanReviewStart(context, input) {
     assertReviewWorkspace(run.workspace_root, protocolIds);
     const groups = reviewGroups(home, run.workspace_root);
     const effective = resolveMode(requested, groups, home, run.workspace_root);
+    const reviewerInputs = effective === "off" ? [] : reviewerSourceInputs(run.workspace_root, groups.flatMap(group => group.aspect_ids));
+    if (effective !== "off")
+        for (const group of groups)
+            group.task += `\n${reviewerSourceInstruction(run.workspace_root, group.aspect_ids)}`;
     const existing = context.db.get("SELECT work_id, status FROM works WHERE project_id = ? AND run_id = ? AND task = ? ORDER BY created_at DESC LIMIT 1", [project.id, run.id, reviewTask]);
     const batchChecksum = checksum(batch), planChecksum = planSetChecksum(home, run.workspace_root);
     if (input.externalContext)
@@ -62,7 +67,7 @@ export function prepareVnextPlanReviewStart(context, input) {
     prepareOutputFile(path.join(root, "stage-prompt.md"));
     const attachment = existing?.status === "running" ? null : prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" });
     const matrix = existing?.status === "running" ? latestRunVerificationMatrix(context, project.id, run.id, stage, "input") : prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "input", ...(attachment ? { stageAttempt: attachment.attempt } : {}) });
-    const active = { ...common, requested, protocolIds, groups, effective, workspaceRoute, batchChecksum, planChecksum, matrix };
+    const active = { ...common, requested, protocolIds, groups, effective, workspaceRoute, batchChecksum, planChecksum, matrix, reviewerInputs };
     if (existing?.status === "running") {
         const orchestration = readFanoutDescriptor(root);
         if (!orchestration)
@@ -163,7 +168,7 @@ export function startVnextPlanReview(context, input, prepared = prepareVnextPlan
     const workSessionId = String(binding.work_session_id);
     const sessionId = String(binding.session_id);
     const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: workId, dispatch: "plan-review", capacity_required: true, scope: stageGraphScope(context, project.id, run.id, stage) });
-    writeJson(path.join(root, "work-context.json"), { schema_id: "dd-flow/plan-review-context@1", read_only_input: { parent_work_id: workId, version: 3 }, system: { run_id: run.id, work_id: workId, stage, requested_mode: requested, effective_mode: effective, plan_revision: prepared.revision, plan_checksum: planChecksum, batch_checksum: batchChecksum }, groups, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root, plan_root: planRoot } });
+    writeJson(path.join(root, "work-context.json"), { schema_id: "dd-flow/plan-review-context@1", reviewer_inputs: prepared.reviewerInputs, read_only_input: { parent_work_id: workId, version: 3 }, system: { run_id: run.id, work_id: workId, stage, requested_mode: requested, effective_mode: effective, plan_revision: prepared.revision, plan_checksum: planChecksum, batch_checksum: batchChecksum }, groups, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root, plan_root: planRoot } });
     refreshRunWorkProjection(context, project.id, run.id);
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "work_session_started", stage, work_id: workId, id: workSessionId, session_id: sessionId });
     return { ok: true, run_id: run.id, stage, outcome: "review_required", work_id: workId, id: workSessionId, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, plan_review: { requested_mode: requested, effective_mode: effective, policy_source: policySource(run), groups }, next: { dispatch_command: dispatchCommand(context, run.id, projectRoot), finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };

package/dist/services/work-registry.js

@@ -995,6 +995,8 @@ function assertSharedReviewInput(context, work, run, generation = recoveryGuard(
         add("run", matrix.metadata.json.path, matrix.metadata.json.sha256);
         add("run", matrix.metadata.markdown.path, matrix.metadata.markdown.sha256);
     }
+    for (const item of value.reviewer_inputs ?? [])
+        add("workspace", item.path, item.sha256);
     const runInputs = [...expected].map(([key, sha]) => { const [root, ...parts] = key.split(":"); return { root: root, path: parts.join(":"), sha256: sha }; }).sort((a, b) => `${a.root}:${a.path}`.localeCompare(`${b.root}:${b.path}`));
     for (const item of runInputs) {
         const target = reviewInputPath(item.root === "run" ? home : run.workspace_root, item.path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.122",
+  "version": "0.9.0-beta.123",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "packageManager": "pnpm@10.23.0",