@deksden-com/dd-flow-cli 0.9.0-beta.124 → 0.9.0-beta.127

package/dist/services/stage-pause.js

@@ -14,6 +14,7 @@ import { appendFlowRunTimelineEvent, pauseFlowRunStage, resumeFlowRunStage } fro
 import { bindSessionForResume, refreshRunWorkProjection } from "./work-registry.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
 import { runtimeCommand } from "./runtime-command.js";
+import { prepareAgentOutputFile } from "../storage/agent-output.js";
 export { flowCommand } from "./runtime-command.js";
 export function prepareStagePause(context, input) {
     if (typeof input.question !== "string" || !input.question.trim())
@@ -38,6 +39,7 @@ export function pauseStageForUser(context, input) {
     const questionPath = path.join(pauseRoot, "question.md");
     fs.mkdirSync(pauseRoot, { recursive: true });
     publishImmutableInput(questionPath, Buffer.from(question), "hitl_question_conflict");
+    const answerInputPath = prepareAgentOutputFile(path.join(pauseRoot, "answer-input.md"));
     const now = context.now();
     context.db.writeTransaction(() => {
         const paused = context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
@@ -46,7 +48,6 @@ export function pauseStageForUser(context, input) {
         pauseFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, pauseId, questionPath });
         context.db.afterCommit(() => refreshRunWorkProjection(context, project.id, run.id));
     });
-    const answerInputPath = path.join(pauseRoot, "answer-input.md");
     const resume = stageResumeCommand(context, { runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, answerInputPath });
     const resumeTemplate = `Write the complete user answer exactly to ${quote([answerInputPath])}, then run:\n${resume}`;
     return {
@@ -146,7 +147,7 @@ export function resumeStageAfterUser(context, input) {
 export function stagePauseCommand(context, input) {
     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");
+    const questionInputPath = prepareAgentOutputFile(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. */

package/dist/services/usage.js

@@ -369,7 +369,7 @@ function usageRowsForPhysicalSessions(context, links, observedAt, stage) {
             : completedTurn?.completed_at ?? sessionLinks.map((item) => item.completed_at ?? observedAt).sort().at(-1);
         const endedAt = stage?.completedAt ?? (Date.parse(naturalEnd) > Date.parse(observedAt) ? observedAt : naturalEnd);
         const harnessUsage = isExternalHarness(link.harness)
-            ? readHarnessUsageWindow(context, link.harness, link.project_id, link.provider_session_id, startedAt, endedAt, observedAt)
+            ? readHarnessUsageWindow(context, link.harness, link.project_id, link.provider_session_id, startedAt, endedAt, observedAt, Boolean(stage))
             : null;
         const parsed = harnessUsage ?? readCodexTranscriptWindow(link.transcript_path, nativeSessionId(link), startedAt, endedAt);
         return {
@@ -393,18 +393,29 @@ function hasInclusiveUsageSnapshot(context, projectId, harness, providerSessionI
         return false;
     return Boolean(context.db.get("SELECT 1 FROM harness_usage_snapshots WHERE project_id = ? AND harness = ? AND provider_session_id = ? AND usage_scope = 'execution_tree_inclusive' AND observed_at <= ? LIMIT 1", [projectId, harness, providerSessionId, observedAt]));
 }
-function readHarnessUsageWindow(context, harness, projectId, providerSessionId, startedAt, endedAt, observedAt) {
+function readHarnessUsageWindow(context, harness, projectId, providerSessionId, startedAt, endedAt, observedAt, stageWindow) {
     if (!providerSessionId)
         return { status: "not_observable", diagnostic: "provider_session_id_missing" };
     const snapshots = context.db.all(`SELECT completeness, observed_at, total_tokens, input_tokens, cache_read_input_tokens, cache_write_input_tokens, output_tokens, reasoning_output_tokens
        FROM harness_usage_snapshots
       WHERE project_id = ? AND harness = ? AND provider_session_id = ? AND observed_at <= ?
       ORDER BY observed_at, id`, [projectId, harness, providerSessionId, observedAt]);
-    const last = snapshots.find((snapshot) => Date.parse(snapshot.observed_at) > Date.parse(endedAt))
+    const last = (!stageWindow ? snapshots.find((snapshot) => Date.parse(snapshot.observed_at) > Date.parse(endedAt)) : undefined)
         ?? snapshots.filter((snapshot) => Date.parse(snapshot.observed_at) <= Date.parse(endedAt)).at(-1);
     const before = snapshots.filter((snapshot) => Date.parse(snapshot.observed_at) <= Date.parse(startedAt)).at(-1);
     if (!last || !before || last === before)
         return { status: "not_yet_emitted", diagnostic: `${harness}_usage_window_incomplete` };
+    // Cumulative counters outside an attempt's boundaries cannot establish its
+    // spend: adjacent attempts would otherwise charge overlapping intervals.
+    if (stageWindow && (Date.parse(before.observed_at) !== Date.parse(startedAt)
+        || Date.parse(last.observed_at) !== Date.parse(endedAt)
+        || before.completeness !== "complete" || last.completeness !== "complete")) {
+        return { status: "not_observable", diagnostic: `${harness}_stage_window_unconfirmed` };
+    }
+    if (stageWindow && ["total_tokens", "input_tokens", "cache_read_input_tokens", "cache_write_input_tokens", "output_tokens", "reasoning_output_tokens"]
+        .some(key => last[key] !== null && before[key] !== null && last[key] < before[key])) {
+        return { status: "not_observable", diagnostic: `${harness}_stage_counter_reset` };
+    }
     if (harness === "droid-cli" && (last.completeness !== "complete" || before.completeness !== "complete"))
         return { status: "not_observable", diagnostic: "droid-cli_usage_window_partial" };
     const delta = (value, baseline) => value === null || baseline === null ? null : Math.max(0, value - baseline);

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

@@ -18,7 +18,7 @@ import { withStageSettlement, prepareFlowRunStageAttachment } from "./runs.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { acceptStageReport, prepareStageReport } from "./stage-report-renderer.js";
 import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, latestRunVerificationMatrix, publishVerificationMatrix } from "./verification-matrix.js";
-import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
+import { currentStagePrompt, 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";
@@ -27,6 +27,7 @@ import { assertRunMutationAllowed } from "./run-recovery.js";
 import { prepareJsonFile, prepareOutputFile } from "../cli/input-preparation.js";
 import { reviewerSourceInputs, reviewerSourceInstruction } from "./review-copy.js";
 import { reviewDefEvidence } from "./review-deferral.js";
+import { stageSuccessor } from "./vnext-contracts.js";
 const stage = "code-review";
 const stageDir = vnextStageDirectory(stage);
 const baselineAspects = ["goal_traceability", "coding_standards_design_review", "verification_evidence_review"];
@@ -76,11 +77,11 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
     if (prepared.resumed) {
         if (effectiveMode(prepared.home, run).mode !== "off")
             resumeVerificationMatrix(context, project.id, run.id, stage);
-        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath: existingPrompt, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        const externalContext = applyExternalStageContext({ context, stageRoot: root, promptPath: existingPrompt, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath: existingPrompt, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-        const prompt = fs.readFileSync(existingPrompt, "utf8");
+        const delivered = currentStagePrompt(context, existingPrompt);
         const orchestration = prepared.orchestration;
-        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prepared.prior, id: binding.work_session_id, prompt_path: existingPrompt, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), ...(orchestration ? { orchestration } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
+        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prepared.prior, id: binding.work_session_id, ...delivered, ...(externalContext ? { external_context: externalContext } : {}), ...(orchestration ? { orchestration } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
     }
     const { mode, cycle, groups, batch, items, template, checks, codeReportSha256 } = prepared;
     prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" }, true);
@@ -96,17 +97,17 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
         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`;
         fs.writeFileSync(promptPath, prompt);
-        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        const externalContext = applyExternalStageContext({ context, 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 attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" };
         attachFlowRunStage(context, attachmentInput, prepareFlowRunStageAttachment(context, attachmentInput));
-        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 } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
+        return { ok: true, run_id: run.id, stage, mode: mode.mode, mode_source: mode.source, id: binding.work_session_id, ...currentStagePrompt(context, promptPath), ...(externalContext ? { external_context: externalContext } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
     }
     const batchFile = path.join(root, "review-work-batch.json");
     fs.writeFileSync(batchFile, `${JSON.stringify(batch, null, 2)}\n`);
     const prompt = `${orchestratorPrompt(context, { projectRoot, run, root, rootWork, mode: mode.mode, groups, template, checks })}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, prepared.home, "reviewing whether current evidence proves the accepted obligations")}\n`;
     fs.writeFileSync(promptPath, prompt);
-    const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    const externalContext = applyExternalStageContext({ context, 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, 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) });
@@ -114,7 +115,7 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
     const attachment = prepareFlowRunStageAttachment(context, attachmentInput);
     commitVerificationMatrixStart(context, prepared.matrix, () => attachFlowRunStage(context, attachmentInput, attachment));
     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")) } };
+    return { ok: true, run_id: run.id, stage, mode: mode.mode, mode_source: mode.source, id: binding.work_session_id, ...currentStagePrompt(context, promptPath), ...(externalContext ? { external_context: externalContext } : {}), orchestration, review: { groups, works: registered }, next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
 }
 export function prepareVnextCodeReviewRepair(context, input) {
     if (!Array.isArray(input.findingIds) || !input.findingIds.length || input.findingIds.some(id => typeof id !== "string" || !id.trim()))
@@ -293,7 +294,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, runtimeCommand(context, ["stage", "start", run.id, "--stage", "merge", "--project-root", 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: stageSuccessor(context, { projectRoot, runId: run.id, stage: "merge", command: runtimeCommand(context, ["stage", "start", run.id, "--stage", "merge", "--project-root", projectRoot, "--json", "--progress-jsonl"]) }) } : {}) };
 }
 export function readCodeReviewDecision(file, accepted, explicit = false, prepared) {
     if (!accepted)

package/dist/services/vnext-code.js

@@ -4,6 +4,7 @@ import { ensureAggregateRepair, ensureRepairIntent } from "./repair-intents.js";
 import { runWorkspaceBootstrap } from "./workspace-bootstrap.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
+import { prepareAgentOutputFile } from "../storage/agent-output.js";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
@@ -21,11 +22,12 @@ import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { acceptStageReport, prepareStageReport } from "./stage-report-renderer.js";
 import { prepareVnextMergeRequest } from "./vnext-merge.js";
 import { assertStageStartHookEvent } from "./hooks.js";
-import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
+import { currentStagePrompt, applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
 import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
 import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, publishVerificationMatrix, latestRunVerificationMatrix } from "./verification-matrix.js";
+import { stageSuccessor } from "./vnext-contracts.js";
 const stage = "code";
 const stageDir = vnextStageDirectory("code");
 /** A controller prepares slow, deterministic project tooling before it asks an
@@ -93,12 +95,13 @@ export async function startVnextCode(context, input, prepared = prepareVnextCode
     const { projectRoot, project, run, root, promptPath, rootWork, sourceRepairAttempt } = prepared;
     assertRunMutationAllowed(context, project.id, run.id);
     assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    prepareAgentOutputFile(path.join(requireHome(run), "works", rootWork.work_id, "block-summary.md"));
     if (prepared.resumed) {
         resumeVerificationMatrix(context, project.id, run.id, stage);
-        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        const externalContext = applyExternalStageContext({ context, stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
         const orchestration = prepared.orchestration ?? writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true, scope: stageGraphScope(context, project.id, run.id, stage) });
-        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prepared.existingStage, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, graph: codeWorkGraph(context, project.id, run.id), next: { refresh_graph_command: runtimeCommand(context, ["work", "ls", "--run", run.id, "--ready", "--project-root", projectRoot, "--json"]), finish_command: finishCommand(context, input.runId, projectRoot, path.join(root, "code-verification.json")) } };
+        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prepared.existingStage, ...currentStagePrompt(context, promptPath), ...(externalContext ? { external_context: externalContext } : {}), orchestration, graph: codeWorkGraph(context, project.id, run.id), next: { refresh_graph_command: runtimeCommand(context, ["work", "ls", "--run", run.id, "--ready", "--project-root", projectRoot, "--json"]), finish_command: finishCommand(context, input.runId, projectRoot, path.join(root, "code-verification.json")) } };
     }
     if (!sourceRepairAttempt)
         prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" }, true);
@@ -108,7 +111,7 @@ export async function startVnextCode(context, input, prepared = prepareVnextCode
     const graph = codeWorkGraph(context, project.id, run.id);
     const prompt = `${coordinatorPrompt(context, { projectRoot, run, root, rootWork, readiness, template: prepared.template, capacity: prepared.capacity, graph })}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, prepared.home, "implementation and code-verification.json")}\n`;
     fs.writeFileSync(promptPath, prompt);
-    const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    const externalContext = applyExternalStageContext({ context, stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, {
         workId: rootWork.work_id,
         hookEventId: input.hookEventId,
@@ -139,8 +142,7 @@ export async function startVnextCode(context, input, prepared = prepareVnextCode
         stage,
         root_work_id: rootWork.work_id,
         id: binding.work_session_id,
-        prompt_path: promptPath,
-        worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"),
+        ...currentStagePrompt(context, promptPath),
         ...(externalContext ? { external_context: externalContext } : {}),
         graph,
         orchestration,
@@ -332,7 +334,7 @@ export async function finishVnextCode(context, input) {
         outcome: "accepted",
         report_path: path.join(root, "stage-report.json"),
         next_action: next,
-        ...(next === "start_code_review" ? { next: { kind: "start_stage", stage: "code-review", command: managedLifecycleCommand(context, runtimeCommand(context, ["stage", "start", run.id, "--stage", "code-review", "--project-root", projectRoot, "--json"])) } } : next === "start_merge" ? { 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"])) } } : {})
+        ...(next === "start_code_review" ? { next: stageSuccessor(context, { projectRoot, runId: run.id, stage: "code-review", command: runtimeCommand(context, ["stage", "start", run.id, "--stage", "code-review", "--project-root", projectRoot, "--json"]) }) } : next === "start_merge" ? { merge_request: mergeRequest, next: stageSuccessor(context, { projectRoot, runId: run.id, stage: "merge", command: runtimeCommand(context, ["stage", "start", run.id, "--stage", "merge", "--project-root", projectRoot, "--json", "--progress-jsonl"]) }) } : {})
     };
 }
 export function registerAggregateCodeRepair(context, input) {
@@ -539,7 +541,7 @@ function receiptRepairPaths(workspaceRoot, receipt) {
     }
     return [...paths].sort();
 }
-function coordinatorPrompt(context, input) {
+export function coordinatorPrompt(context, input) {
     const { graph, capacity, template } = input;
     return [
         "<stage_identity>",

package/dist/services/vnext-contracts.js

@@ -1 +1,10 @@
-export {};
+import { isControllerManagedInvocation, managedLifecycleCommand } from "./lifecycle-invocations.js";
+/** Successor authority belongs to the controller, not the finishing Session.
+ * Manual flows still need an executable next step. Current-stage finish and
+ * paused/child Work commands do not pass through this boundary. */
+export function stageSuccessor(context, input) {
+    const next = { ...input.metadata, kind: "start_stage", stage: input.stage };
+    return isControllerManagedInvocation(context, input.projectRoot, input.runId)
+        ? { ...next, controller_owned: true, stop_turn: true, instruction: "This Stage is complete. End this Turn now and await the controller's next Stage assignment. Do not start the successor Stage or prepare its command." }
+        : { ...next, command: managedLifecycleCommand(context, input.command) };
+}

package/dist/services/vnext-execution-profile.js

@@ -1,18 +1,89 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import { AppError } from "../shared/errors.js";
+import { canonicalPath } from "../storage/paths.js";
 import { isExecutionRouting } from "./execution-policy.js";
+export const RUN_OPERATIONAL_DECISION_CONTRACT = "run-operational-decision@1";
+const object = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const text = (value) => typeof value === "string" && Boolean(value.trim());
+const keys = (value, allowed) => object(value) && Object.keys(value).every(key => allowed.includes(key));
+/** Structural validation only: acceptance is supplied by the caller, never inferred from settings. */
+export function validateRunOperationalDecision(value, settings) {
+    if (!object(value) || value.schema_id !== RUN_OPERATIONAL_DECISION_CONTRACT || !text(value.id)
+        || !object(value.scope) || !text(value.scope.project_root) || !path.isAbsolute(value.scope.project_root)
+        || [value.scope.eval_id, value.scope.execution_id].some(item => item !== undefined && !text(item))
+        || !object(value.settings) || !object(value.settings.merge_delivery) || value.settings.merge_delivery.strategy !== settings.merge_delivery.strategy
+        || !object(value.settings.merge_cleanup) || value.settings.merge_cleanup.source !== settings.merge_cleanup.source
+        || !object(value.policy) || !text(value.policy.path) || !text(value.policy.sha256) || !/^[a-f0-9]{64}$/.test(value.policy.sha256)
+        || !Array.isArray(value.policy.clauses) || !value.policy.clauses.length || !value.policy.clauses.every(text)
+        || !object(value.acceptance) || !text(value.acceptance.source) || !text(value.acceptance.reference)
+        || value.exception !== undefined && (!object(value.exception) || !text(value.exception.reason) || !text(value.exception.owner)
+            || !text(value.exception.review_at) || !Number.isFinite(Date.parse(value.exception.review_at))
+            || value.exception.expires_at !== undefined && (!text(value.exception.expires_at) || !Number.isFinite(Date.parse(value.exception.expires_at))))) {
+        throw new AppError("operational_decision_invalid", "Operational decision requires explicit acceptance, scoped authority and matching settings", 2);
+    }
+    if (!keys(value, ["schema_id", "id", "scope", "settings", "policy", "acceptance", "exception", "declaration"])
+        || !keys(value.scope, ["project_root", "eval_id", "execution_id"])
+        || !keys(value.settings, ["merge_delivery", "merge_cleanup"])
+        || !keys(value.settings.merge_delivery, ["strategy"]) || !keys(value.settings.merge_cleanup, ["source"])
+        || !keys(value.policy, ["path", "sha256", "clauses"]) || !keys(value.acceptance, ["source", "reference"])
+        || value.exception !== undefined && !keys(value.exception, ["reason", "owner", "review_at", "expires_at"])
+        || value.declaration !== undefined && !keys(value.declaration, ["bytes", "sha256"]))
+        throw new AppError("operational_decision_invalid", "Operational decision contains unsupported authority fields", 2);
+    if (value.declaration !== undefined) {
+        if (!object(value.declaration) || !text(value.declaration.bytes) || !text(value.declaration.sha256)
+            || crypto.createHash("sha256").update(value.declaration.bytes).digest("hex") !== value.declaration.sha256)
+            throw new AppError("operational_decision_invalid", "Original operational declaration checksum does not match", 2);
+        let declaration;
+        try {
+            declaration = JSON.parse(value.declaration.bytes);
+        }
+        catch {
+            throw new AppError("operational_decision_invalid", "Original operational declaration must be JSON", 2);
+        }
+        if (!object(declaration) || !keys(declaration, ["schema_id", "id", "scope", "settings", "policy", "acceptance", "exception"])
+            || declaration.scope !== undefined && !keys(declaration.scope, ["project_root", "eval_id", "execution_id"])
+            || ["schema_id", "id", "settings", "policy", "acceptance", "exception"].some(key => !isDeepStrictEqual(declaration[key], value[key])))
+            throw new AppError("operational_decision_invalid", "Materialized decision changed the accepted declaration", 2);
+    }
+    return value;
+}
+/** Machine validation of declared policy bytes, not an NLP interpretation of Markdown. */
+export function assertOperationalDecisionSource(decision, projectRoot, now) {
+    if (canonicalPath(decision.scope.project_root, false) !== canonicalPath(projectRoot, false))
+        throw new AppError("operational_decision_scope_mismatch", "Operational decision belongs to another project", 2);
+    const file = path.resolve(projectRoot, decision.policy.path);
+    const relative = path.relative(fs.realpathSync(projectRoot), fs.existsSync(file) ? fs.realpathSync(file) : file);
+    if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) || relative === ".." || !fs.existsSync(file) || crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") !== decision.policy.sha256)
+        throw new AppError("operational_decision_policy_changed", "Operational decision policy source checksum does not match an owned file", 2, { file });
+    if (decision.exception?.expires_at && Date.parse(decision.exception.expires_at) <= Date.parse(now))
+        throw new AppError("operational_decision_expired", "Explicit operational decision expiration has passed", 2);
+}
 const relativePath = path.join(".memory-bank", "dd-flow", "project-execution.json");
 /** The project owns defaults; a RUN snapshots them once and never re-infers them. */
 export function loadVnextExecutionProfile(projectRoot) {
+    return loadVnextExecutionProfileSnapshot(projectRoot).profile;
+}
+/** Parse and identify the same source bytes; a second read cannot bind another declaration. */
+export function loadVnextExecutionProfileSnapshot(projectRoot) {
     const file = path.join(projectRoot, relativePath);
+    let bytes;
     let value;
     try {
-        value = JSON.parse(fs.readFileSync(file, "utf8"));
+        bytes = fs.readFileSync(file);
+        value = JSON.parse(bytes.toString("utf8"));
     }
     catch (error) {
         throw new AppError("execution_profile_missing", "vNext flow requires .memory-bank/dd-flow/project-execution.json", 1, { file, cause: String(error) });
     }
+    return { profile: validateVnextExecutionProfile(value), bytes };
+}
+/** Pure shared admission contract for project-execution@2 and @3. */
+export function validateVnextExecutionProfile(value) {
+    if (!object(value))
+        throw new AppError("execution_profile_invalid", "Project execution profile must be an object", 1);
     const profile = value;
     if ((profile.schema_id !== "dd-flow/project-execution@2" && profile.schema_id !== "dd-flow/project-execution@3")
         || (profile.stage_session_mode !== undefined && profile.stage_session_mode !== "same_session" && profile.stage_session_mode !== "new_session")
@@ -25,8 +96,10 @@ export function loadVnextExecutionProfile(projectRoot) {
         || !profile.code_bootstrap || typeof profile.code_bootstrap.command !== "string" || !profile.code_bootstrap.command.trim()
         || typeof profile.code_bootstrap.policy_ref !== "string" || !profile.code_bootstrap.policy_ref.trim()
         || (profile.execution === undefined ? profile.schema_id === "dd-flow/project-execution@3" : !isExecutionRouting(profile.execution))) {
-        throw new AppError("execution_profile_invalid", "Project execution profile does not match its supported dd-flow schema", 1, { file });
+        throw new AppError("execution_profile_invalid", "Project execution profile does not match its supported dd-flow schema", 1);
     }
+    if (profile.operational_decision !== undefined)
+        validateRunOperationalDecision(profile.operational_decision, profile);
     return { ...profile, stage_session_mode: profile.stage_session_mode ?? "same_session", code_review_mode: profile.code_review_mode ?? "off" };
 }
 export function executionProfilePath(projectRoot) { return path.join(projectRoot, relativePath); }

package/dist/services/vnext-fanout.js

@@ -10,6 +10,7 @@ import { storageSessionId } from "./session-identity.js";
 import { reconcileUnfinishedChecks } from "./code-checks.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { stageWorkIds, stageGraphScope } from "./stage-work-graph.js";
+import { eligibleCodexChildOverload } from "./codex-capacity.js";
 export const subagentCapacityKey = "runtime.subagent.available_slots";
 /** External concurrency is policy, never evidence of native child qualification. */
 export function getStageFanoutCapacity(context, input) {
@@ -143,6 +144,10 @@ export async function reconcileVnextFanout(context, input) {
             continue;
         }
         const link = active[0];
+        if (value.harness_id === "codex-desktop" && eligibleCodexChildOverload(child, value.parent_session_id)) {
+            issues.push({ code: "child_capacity_pending", work_id: link.work_id, session_id: child.session_id });
+            continue;
+        }
         const pendingCheck = () => context.db.get("SELECT 1 FROM check_receipts WHERE project_id = ? AND run_id = ? AND work_id = ? AND status = 'running' LIMIT 1", [project.id, input.runId, link.work_id]);
         if (pendingCheck()) {
             const run = context.db.get("SELECT workspace_root, run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);

package/dist/services/vnext-merge.js

@@ -18,12 +18,13 @@ import { acceptStageReport, prepareStageReport, publishStageReport } from "./sta
 import { bindStageCoordinatorWork, createChildWork, failWork, finishFanInWork, finishWork, refreshRunWorkProjection, startStageCoordinatorWork } from "./work-registry.js";
 import { addVnextCodeRepair } from "./vnext-code.js";
 import { checkReceiptEvidenceValid, checkReceipts, effectiveCheckDeclarations, mergeCheckProfileHash, readCodeCheckProfile, runCodeChecks, validateCheckDeclaration, validateFailedCheckRetry, workspaceChangedPaths, workspaceFingerprint } from "./code-checks.js";
-import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
+import { currentStagePrompt, applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { ensureLaneWorkspace, prepareLaneWorkspace, heartbeatLaneLock, releaseLaneLock, waitAcquireLaneLock } from "./lanes.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
 import { assertStageStartHookEvent } from "./hooks.js";
 import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
 import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, latestRunVerificationMatrix, publishVerificationMatrix } from "./verification-matrix.js";
+import { stageSuccessor } from "./vnext-contracts.js";
 const stage = "merge";
 const stageDir = vnextStageDirectory(stage);
 export function isVnextMergeRun(context, input) {
@@ -176,11 +177,11 @@ export async function startVnextMerge(context, input, prepared = prepareVnextMer
             const prompt = existingPrompt ?? `${mergePrompt(context, { run, request, resultPath, projectRoot }, checks, settings)}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, run.run_root, "MERGE source/target verification and residual-risk assessment")}\n`;
             if (existingPrompt === null)
                 fs.writeFileSync(promptPath, prompt);
-            const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+            const externalContext = applyExternalStageContext({ context, stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
             const attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" };
             const attachment = alreadyAttached ? null : prepareFlowRunStageAttachment(context, attachmentInput);
             commitVerificationMatrixStart(context, prepared.matrix, () => attachment ? attachFlowRunStage(context, attachmentInput, attachment) : undefined);
-            return startPacket(context, run, request, binding, promptPath, resultPath, prompt, projectRoot, checks, externalContext);
+            return startPacket(context, run, request, binding, promptPath, resultPath, projectRoot, checks, externalContext);
         }
         const current = requireRequest(context, request.merge_request_id);
         const targetHead = gitValue(current.target_workspace, ["rev-parse", current.target_branch], true);
@@ -196,13 +197,13 @@ export async function startVnextMerge(context, input, prepared = prepareVnextMer
         const started = startStageCoordinatorWork(context, { workId: current.executor_work_id, hookEventId: input.hookEventId, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
         const prompt = `${mergePrompt(context, { run, request: requireRequest(context, current.merge_request_id), resultPath, projectRoot }, checks, settings)}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, run.run_root, "MERGE source/target verification and residual-risk assessment")}\n`;
         fs.writeFileSync(promptPath, prompt);
-        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        const externalContext = applyExternalStageContext({ context, stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         context.db.run("UPDATE work_sessions SET prompt_path = ?, result_path = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [promptPath, resultPath, context.now(), current.executor_work_id]);
         const attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" };
         const attachment = alreadyAttached ? null : prepareFlowRunStageAttachment(context, attachmentInput);
         commitVerificationMatrixStart(context, prepared.matrix, () => attachment ? attachFlowRunStage(context, attachmentInput, attachment) : undefined);
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "merge_started", merge_request_id: current.merge_request_id, work_id: current.executor_work_id, target_head: targetHead });
-        return startPacket(context, run, current, started, promptPath, resultPath, prompt, projectRoot, checks, externalContext);
+        return startPacket(context, run, current, started, promptPath, resultPath, projectRoot, checks, externalContext);
     }
     catch (error) {
         const latest = requireRequest(context, request.merge_request_id);
@@ -216,8 +217,8 @@ export async function startVnextMerge(context, input, prepared = prepareVnextMer
         throw error;
     }
 }
-function startPacket(context, run, request, binding, promptPath, resultPath, prompt, projectRoot, checks, externalContext) {
-    return { ok: true, run_id: run.id, stage, merge_request_id: request.merge_request_id, work_id: request.executor_work_id, session_binding: binding.session_binding ?? binding, prompt_path: promptPath, result_path: resultPath, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), queue: queueStatus(context, request), effective_checks: checks, next: { apply_command: applyCommand(context, request, projectRoot), finish_command: finishCommand(context, run.id, request, projectRoot) } };
+function startPacket(context, run, request, binding, promptPath, resultPath, projectRoot, checks, externalContext) {
+    return { ok: true, run_id: run.id, stage, merge_request_id: request.merge_request_id, work_id: request.executor_work_id, session_binding: binding.session_binding ?? binding, result_path: resultPath, ...currentStagePrompt(context, promptPath), ...(externalContext ? { external_context: externalContext } : {}), queue: queueStatus(context, request), effective_checks: checks, next: { apply_command: applyCommand(context, request, projectRoot), finish_command: finishCommand(context, run.id, request, projectRoot) } };
 }
 export function applyVnextMerge(context, input) {
     const existing = requireRequest(context, input.requestId);
@@ -470,7 +471,7 @@ export async function repairVnextMerge(context, input) {
     if (request.project_id === project.id && request.status === "superseded" && errorCode(request) === "merge_source_repair") {
         const saved = JSON.parse(request.last_error_json);
         releaseMergeLane(context, projectRoot, request, `MERGE ${request.merge_request_id} moved to source repair`);
-        return { ok: true, run_id: request.run_id, merge_request_id: request.merge_request_id, status: "superseded", source_repair: { repair_work_id: saved.repair_work_id }, next: { kind: "start_stage", stage: "code", command: managedLifecycleCommand(context, runtimeCommand(context, ["stage", "start", request.run_id, "--stage", "code", "--project-root", projectRoot, "--json", "--progress-jsonl"])) } };
+        return { ok: true, run_id: request.run_id, merge_request_id: request.merge_request_id, status: "superseded", source_repair: { repair_work_id: saved.repair_work_id }, next: stageSuccessor(context, { projectRoot, runId: request.run_id, stage: "code", command: runtimeCommand(context, ["stage", "start", request.run_id, "--stage", "code", "--project-root", projectRoot, "--json", "--progress-jsonl"]) }) };
     }
     if (request.project_id !== project.id || request.status !== "action_required" || errorCode(request) !== "merge_gate_failed") {
         throw new AppError("invalid_merge_repair_state", "MERGE source repair requires an action-required failed integration gate", 2, { merge_request_id: input.requestId, status: request.status, code: errorCode(request) });
@@ -494,7 +495,7 @@ export async function repairVnextMerge(context, input) {
     context.db.run("UPDATE merge_requests SET status = 'superseded', checkpoint = 'source_repair_required', last_error_json = ?, completed_at = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "merge_source_repair", replacement_pending: true, failed_receipt_ids: failed, repair_work_id: repair.repair_work_id }), now, now, request.merge_request_id]);
     releaseMergeLane(context, projectRoot, request, `MERGE ${request.merge_request_id} moved to source repair`);
     appendFlowRunTimelineEvent(context, project.id, request.run_id, { type: "merge_source_repair_created", merge_request_id: request.merge_request_id, repair_work_id: repair.repair_work_id, cycle: prepared.cycle, failed_receipt_ids: failed });
-    return { ok: true, run_id: request.run_id, merge_request_id: request.merge_request_id, status: "superseded", source_repair: repair, next: { kind: "start_stage", stage: "code", command: managedLifecycleCommand(context, runtimeCommand(context, ["stage", "start", request.run_id, "--stage", "code", "--project-root", projectRoot, "--json", "--progress-jsonl"])) } };
+    return { ok: true, run_id: request.run_id, merge_request_id: request.merge_request_id, status: "superseded", source_repair: repair, next: stageSuccessor(context, { projectRoot, runId: request.run_id, stage: "code", command: runtimeCommand(context, ["stage", "start", request.run_id, "--stage", "code", "--project-root", projectRoot, "--json", "--progress-jsonl"]) }) };
 }
 function mergePrompt(context, input, checks, settings) { const pause = stagePauseCommand(context, { runId: input.run.id, stage: "merge", workId: input.request.executor_work_id, projectRoot: input.projectRoot }); const repair = repairCommand(context, input.request, input.projectRoot); return ["<stage_identity>", `- RUN: ${input.run.id}`, `- MERGE request: ${input.request.merge_request_id}`, `- Work: ${input.request.executor_work_id}`, "- stage: merge", "</stage_identity>", "", "<trusted_runtime_context>", `- integration workspace: ${input.request.target_workspace}`, `- source workspace: ${input.request.source_workspace}`, `- frozen source commit: ${input.request.source_commit}`, `- target branch: ${input.request.target_branch}`, `- execution target baseline: ${input.request.execution_target_head}`, `- queue route: ${input.request.execution_route}`, `- delivery: ${JSON.stringify(settings.merge_delivery)}`, `- cleanup: ${JSON.stringify(settings.merge_cleanup)}`, "These facts and the acquired project integration lane were established by dd-flow. Do not repeat discovery and do not run git merge/rebase/squash yourself.", "</trusted_runtime_context>", "", "<effective_merge_gate>", ...checks.map((check) => `- ${check.canonical_ref ?? check.id}: ${check.command} — ${check.purpose}`), "</effective_merge_gate>", "", "<execution_contract>", `1. Run this exact standalone command first: ${applyCommand(context, input.request, input.projectRoot)}`, "2. If it reports conflicts, resolve only the actual unmerged paths in the integration workspace. Do not repeat merge apply and do not edit product code, tests, documentation or configuration merely to make a gate pass.", `3. Write the compact semantic result to ${input.resultPath}:`, "```json", JSON.stringify({ schema_id: "dd-flow/merge-result@1", outcome: "completed", summary: "What was integrated.", conflict_resolution: "How material conflicts were resolved, or empty when none.", verification_summary: "Why the integrated result is ready for deterministic checks.", residual_risks: [] }, null, 2), "```", `4. Finish with this exact standalone command and wait for all progress: ${finishCommand(context, input.run.id, input.request, input.projectRoot)}`, `If a gate fails, read its receipt and logs and determine the cause. For a product defect use ${repair}; it restores the target baseline and opens CODE → independent CODE-REVIEW → replacement MRG. For an environment failure restore the declared environment in this MERGE and write the returned recovery JSON file and use continuation.command_after_input. The CLI reruns the real gate and retains the old receipt. Never edit product code in the integration target to make a gate pass.`, "If a material conflict has no reasonable answer in accepted evidence, pause this same Work by writing the question file and then running the separate standalone command below, ask the returned user_message, then use the exact resume command returned by CLI:", "```sh", stagePauseCommandTemplate(pause), "```", "</execution_contract>", ""].join("\n"); }
 function mergeReport(context, run, request, semantic, receipts) {