@deksden-com/dd-flow-cli 0.9.0-beta.1 → 0.9.0-beta.7

package/dist/services/usage.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import { parseJsonObject } from "../shared/json.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
+import { publicSessionIdentity } from "./session-identity.js";
 export function ingestZcodeUsage(context, input) {
     return ingestHarnessUsage(context, input, { harness: "zcode-acp", label: "ZCode", idPrefix: "ZUSG", sourceKind: "zcode_session_usage_v1" });
 }
@@ -55,11 +56,11 @@ function ingestHarnessUsage(context, input, harness) {
         values.input, values.cacheRead, values.cacheWrite, values.output, values.reasoning, values.requests, values.errors,
         values.toolCalls, values.toolFailures, values.toolByName ? JSON.stringify(values.toolByName) : null, harness.sourceKind,
         stringValue(payload.usage_scope) ?? "physical_session", stringValue(payload.completeness) ?? "complete", context.now()]);
-    return { ok: true, observed: inserted.changes === 1, duplicate: inserted.changes === 0, snapshot_id: id, provider_session_id: providerSessionId, harness: harness.harness };
+    return { ok: true, observed: inserted.changes === 1, duplicate: inserted.changes === 0, snapshot_id: id, session: publicSessionIdentity({ harness: harness.harness, provider_session_id: providerSessionId, session_id: providerSessionId }) };
 }
 export function checkpointSessionUsage(context, session, input) {
     const observedAt = context.now();
-    const result = readCodexTranscript(session.transcript_path, session.session_id);
+    const result = readCodexTranscript(session.transcript_path, nativeSessionId(session));
     const source = sourceFacts(session.transcript_path);
     const snapshot = {
         id: `USG-${crypto.randomUUID()}`,
@@ -114,7 +115,7 @@ export function checkpointSessionUsage(context, session, input) {
     return snapshotForOutput(snapshot);
 }
 export function checkpointRunUsage(context, input) {
-    const sessions = context.db.all(`SELECT session_id, project_id, run_id, transcript_path, parent_session_id, role, aspect_id, plan_item_id, session_kind
+    const sessions = context.db.all(`SELECT session_id, project_id, run_id, transcript_path, provider_session_id, parent_session_id, role, aspect_id, plan_item_id, session_kind
      FROM sessions WHERE project_id = ? AND run_id = ?`, [input.projectId, input.runId]);
     return sessions.map((session) => checkpointSessionUsage(context, session, input));
 }
@@ -136,7 +137,7 @@ export function recalculateRunUsage(context, input) {
     // after `work finish` but before the agent's actual terminal event.
     const accountingAt = observedAt;
     const links = context.db.all(`SELECT ws.id, ws.work_id, ws.session_id, ws.created_at, ws.completed_at,
-            w.project_id, s.harness, s.transcript_path, s.parent_session_id, s.agent_id, s.provider_session_id
+            w.project_id, s.harness, s.transcript_path, s.parent_session_id, s.provider_parent_session_id, s.agent_id, s.provider_session_id
        FROM work_sessions ws
        JOIN works w ON w.work_id = ws.work_id
        LEFT JOIN sessions s ON s.project_id = w.project_id AND s.session_id = ws.session_id
@@ -154,31 +155,34 @@ export function recalculateRunUsage(context, input) {
     const settledSessions = settledRunSessions(context, links, observedAt);
     const unsettledSessions = [...new Set(links.map((link) => link.session_id))].filter((sessionId) => !settledSessions.some((session) => session.session_id === sessionId));
     const usageFinal = final && unsettledSessions.length === 0;
-    context.db.exec("BEGIN IMMEDIATE");
-    try {
-        context.db.run("DELETE FROM usage WHERE project_id = ? AND run_id = ?", [input.projectId, input.runId]);
-        for (const row of rows) {
-            context.db.run(`INSERT INTO usage (id, project_id, run_id, session_id, checkpoint, stage, stage_attempt, observed_at, total_tokens, input_tokens, cached_input_tokens, cache_read_input_tokens, cache_write_input_tokens, uncached_input_tokens, output_tokens, reasoning_output_tokens, source_kind, source_locator, source_sha256, source_size_bytes, source_mtime_ms, token_event_at, turn_id, turn_attribution, parser_version, extraction_status, diagnostic_code, created_at)
+    const persistRunProjection = !input.sessionId && !input.stage;
+    if (persistRunProjection) {
+        context.db.exec("BEGIN IMMEDIATE");
+        try {
+            context.db.run("DELETE FROM usage WHERE project_id = ? AND run_id = ?", [input.projectId, input.runId]);
+            for (const row of rows) {
+                context.db.run(`INSERT INTO usage (id, project_id, run_id, session_id, checkpoint, stage, stage_attempt, observed_at, total_tokens, input_tokens, cached_input_tokens, cache_read_input_tokens, cache_write_input_tokens, uncached_input_tokens, output_tokens, reasoning_output_tokens, source_kind, source_locator, source_sha256, source_size_bytes, source_mtime_ms, token_event_at, turn_id, turn_attribution, parser_version, extraction_status, diagnostic_code, created_at)
          VALUES (?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, 'windowed_work_session', 1, ?, ?, ?)`, [
-                `USG-${crypto.randomUUID()}`, input.projectId, input.runId, row.session_id, usageFinal ? "final" : "provisional", input.stage?.name ?? null, row.observed_at,
-                row.tokens?.total_tokens ?? null, row.tokens?.input_tokens ?? null, row.tokens?.cache_read_input_tokens ?? null,
-                row.tokens?.cache_read_input_tokens ?? null, row.tokens?.cache_write_input_tokens ?? null, row.tokens?.uncached_input_tokens ?? null,
-                row.tokens?.output_tokens ?? null, row.tokens?.reasoning_output_tokens ?? null, row.source_kind, row.source.locator, row.source.sha256, row.source.size, row.source.mtime,
-                row.status, row.diagnostic, observedAt
-            ]);
-        }
-        for (const session of settledSessions) {
-            context.db.run(`UPDATE sessions
+                    `USG-${crypto.randomUUID()}`, input.projectId, input.runId, row.session_id, usageFinal ? "final" : "provisional", input.stage?.name ?? null, row.observed_at,
+                    row.tokens?.total_tokens ?? null, row.tokens?.input_tokens ?? null, row.tokens?.cache_read_input_tokens ?? null,
+                    row.tokens?.cache_read_input_tokens ?? null, row.tokens?.cache_write_input_tokens ?? null, row.tokens?.uncached_input_tokens ?? null,
+                    row.tokens?.output_tokens ?? null, row.tokens?.reasoning_output_tokens ?? null, row.source_kind, row.source.locator, row.source.sha256, row.source.size, row.source.mtime,
+                    row.status, row.diagnostic, observedAt
+                ]);
+            }
+            for (const session of settledSessions) {
+                context.db.run(`UPDATE sessions
             SET status = 'stopped', stop_reason = 'provider_turn_complete', updated_at = ?, stopped_at = ?
           WHERE project_id = ? AND run_id = ? AND session_id = ?
             AND status = 'idle'
             AND NOT EXISTS (SELECT 1 FROM work_sessions WHERE session_id = ? AND status = 'running')`, [observedAt, session.completed_at, input.projectId, input.runId, session.session_id, session.session_id]);
+            }
+            context.db.exec("COMMIT");
+        }
+        catch (error) {
+            context.db.exec("ROLLBACK");
+            throw error;
         }
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
     }
     return {
         ok: true,
@@ -187,16 +191,28 @@ export function recalculateRunUsage(context, input) {
         status: usageFinal ? "final" : "provisional",
         scope: input.stage ? { kind: "stage", stage: input.stage.name, started_at: input.stage.startedAt, completed_at: input.stage.completedAt } : { kind: "run" },
         observed_at: observedAt,
+        persisted: persistRunProjection,
         totals: outputUsageTotals(totals),
-        sessions: rows,
+        sessions: publicUsageRows(context, input.projectId, rows),
         session_reconciliation: {
-            stopped: settledSessions.map((session) => session.session_id),
-            unsettled: unsettledSessions
+            stopped: publicSessionIdentities(context, input.projectId, settledSessions.map((session) => session.session_id)),
+            unsettled: publicSessionIdentities(context, input.projectId, unsettledSessions)
         },
         tool_calls: toolCallsForLinks(context, links, accountingAt),
         coverage: rows.reduce((coverage, row) => ({ ...coverage, [row.status]: (coverage[row.status] ?? 0) + 1 }), {})
     };
 }
+function publicUsageRows(context, projectId, rows) {
+    const identityFor = (storageId) => {
+        const row = context.db.get("SELECT harness, provider_session_id FROM sessions WHERE project_id = ? AND session_id = ?", [projectId, storageId]);
+        return row ? publicSessionIdentity({ harness: row.harness, provider_session_id: row.provider_session_id, session_id: storageId }) : null;
+    };
+    return rows.map(({ session_id, provider_session_id: _providerSessionId, parent_session_id, ...row }) => ({
+        ...row,
+        session: identityFor(session_id),
+        ...(parent_session_id ? { parent_session: identityFor(parent_session_id) } : {})
+    }));
+}
 function overlapsStage(link, stage, observedAt) {
     const linkStart = Date.parse(link.created_at);
     const linkEnd = Date.parse(link.completed_at ?? observedAt);
@@ -212,6 +228,17 @@ function clipToStage(link, stage, observedAt) {
     const completedAt = Date.parse(naturalEnd) > Date.parse(stageEnd) ? stageEnd : naturalEnd;
     return { ...link, created_at: startedAt, completed_at: completedAt };
 }
+function nativeSessionId(session) {
+    return session.provider_session_id ?? session.session_id;
+}
+function publicSessionIdentities(context, projectId, storageIds) {
+    if (storageIds.length === 0)
+        return [];
+    const marks = storageIds.map(() => "?").join(", ");
+    const rows = context.db.all(`SELECT session_id, harness, provider_session_id FROM sessions WHERE project_id = ? AND session_id IN (${marks})`, [projectId, ...storageIds]);
+    const byStorage = new Map(rows.map((row) => [row.session_id, publicSessionIdentity(row)]));
+    return storageIds.flatMap((id) => byStorage.get(id) ?? []);
+}
 function toolCallsForLinks(context, links, observedAt) {
     const result = { status: "unavailable", total: 0, failures: 0, by_tool: {}, observed_sessions: 0, unavailable_sessions: [] };
     const sessions = new Map();
@@ -221,7 +248,7 @@ function toolCallsForLinks(context, links, observedAt) {
         const first = windows[0];
         const parsed = isExternalHarness(first.harness)
             ? readHarnessToolCallsWindow(context, first.harness, first.project_id, first.provider_session_id, windows.map((item) => item.created_at).sort()[0], windows.map((item) => item.completed_at ?? observedAt).sort().at(-1), observedAt)
-            : readToolCallsForWindows(first.transcript_path, sessionId, windows, observedAt);
+            : readToolCallsForWindows(first.transcript_path, nativeSessionId(first), windows, observedAt);
         if (!parsed) {
             result.unavailable_sessions.push(sessionId);
             continue;
@@ -357,15 +384,15 @@ function usageRowsForPhysicalSessions(context, links, observedAt, stage) {
         sessions.set(link.session_id, [...(sessions.get(link.session_id) ?? []), link]);
     const physicalSessions = [...sessions.values()].filter((sessionLinks) => {
         const link = sessionLinks[0];
-        if (!link.parent_session_id)
+        if (!link.provider_parent_session_id)
             return true;
-        const parent = links.find((candidate) => candidate.session_id === link.parent_session_id);
+        const parent = links.find((candidate) => candidate.session_id === link.provider_parent_session_id);
         return !parent || !hasInclusiveUsageSnapshot(context, parent.project_id, parent.harness, parent.provider_session_id, observedAt);
     });
     return physicalSessions.map((sessionLinks) => {
         const link = sessionLinks[0];
         const startedAt = stage?.startedAt ?? sessionLinks.map((item) => item.created_at).sort()[0];
-        const completedTurn = stage ? null : completedProviderTurn(link.transcript_path, link.session_id);
+        const completedTurn = stage ? null : completedProviderTurn(link.transcript_path, nativeSessionId(link));
         const naturalEnd = isExternalHarness(link.harness)
             ? observedAt
             : completedTurn?.completed_at ?? sessionLinks.map((item) => item.completed_at ?? observedAt).sort().at(-1);
@@ -373,7 +400,7 @@ function usageRowsForPhysicalSessions(context, links, observedAt, stage) {
         const harnessUsage = isExternalHarness(link.harness)
             ? readHarnessUsageWindow(context, link.harness, link.project_id, link.provider_session_id, startedAt, endedAt, observedAt)
             : null;
-        const parsed = harnessUsage ?? readCodexTranscriptWindow(link.transcript_path, link.session_id, startedAt, endedAt);
+        const parsed = harnessUsage ?? readCodexTranscriptWindow(link.transcript_path, nativeSessionId(link), startedAt, endedAt);
         return {
             work_session_id: link.id,
             work_id: link.work_id,
@@ -437,15 +464,16 @@ function settledRunSessions(context, links, observedAt) {
             return [];
         const link = sessionLinks[0];
         const sessionStartedAt = sessionLinks.map((item) => item.created_at).sort()[0];
+        const workCompletedAt = sessionLinks.map((item) => item.completed_at).sort().at(-1);
         if (isExternalHarness(link.harness) && link.provider_session_id) {
             const snapshot = context.db.get(`SELECT observed_at FROM harness_usage_snapshots
           WHERE project_id = ? AND harness = ? AND provider_session_id = ?
             AND completeness = 'complete' AND observed_at >= ? AND observed_at <= ?
-          ORDER BY observed_at DESC, id DESC LIMIT 1`, [link.project_id, link.harness, link.provider_session_id, sessionStartedAt, observedAt]);
+          ORDER BY observed_at DESC, id DESC LIMIT 1`, [link.project_id, link.harness, link.provider_session_id, workCompletedAt, observedAt]);
             return snapshot ? [{ session_id: sessionId, completed_at: snapshot.observed_at }] : [];
         }
-        const completed = completedProviderTurn(sessionLinks[0].transcript_path, sessionId);
-        if (!completed || Date.parse(completed.completed_at) < Date.parse(sessionStartedAt))
+        const completed = completedProviderTurn(sessionLinks[0].transcript_path, nativeSessionId(sessionLinks[0]));
+        if (!completed || Date.parse(completed.completed_at) < Date.parse(workCompletedAt) || Date.parse(completed.completed_at) < Date.parse(sessionStartedAt))
             return [];
         return [{ session_id: sessionId, completed_at: completed.completed_at }];
     });
@@ -484,10 +512,10 @@ function completedProviderTurn(transcriptPath, expectedSessionId) {
     }
 }
 function usageReport(context, input, refresh) {
-    const sessions = context.db.all(`SELECT DISTINCT session_id, project_id, ? AS run_id, transcript_path, parent_session_id, role, aspect_id, plan_item_id, session_kind
+    const sessions = context.db.all(`SELECT DISTINCT session_id, project_id, ? AS run_id, transcript_path, harness, provider_session_id, parent_session_id, role, aspect_id, plan_item_id, session_kind
      FROM sessions WHERE project_id = ? AND run_id = ?
      UNION
-     SELECT DISTINCT f.session_id, f.project_id, ? AS run_id, f.transcript_path, f.parent_session_id, f.role, f.aspect_id, f.plan_item_id, f.session_kind
+     SELECT DISTINCT f.session_id, f.project_id, ? AS run_id, f.transcript_path, f.harness, f.provider_session_id, f.parent_session_id, f.role, f.aspect_id, f.plan_item_id, f.session_kind
      FROM flow_session_segments s JOIN sessions f ON f.project_id = s.project_id AND f.session_id = s.session_id
      WHERE s.project_id = ? AND s.run_id = ?`, [input.runId, input.projectId, input.runId, input.runId, input.projectId, input.runId]);
     const selectedSessions = input.sessionId ? sessions.filter((session) => session.session_id === input.sessionId) : sessions;
@@ -500,13 +528,15 @@ function usageReport(context, input, refresh) {
      LEFT JOIN sessions f ON f.project_id = s.project_id AND f.session_id = s.session_id
      WHERE s.project_id = ? AND s.run_id = ? ORDER BY s.session_id, s.observed_at, s.id`, [input.projectId, input.runId]);
     const selectedRows = input.sessionId ? rows.filter((row) => row.session_id === input.sessionId) : rows;
-    const deltas = usageDeltas(selectedRows);
+    const publicSessions = new Map(sessions.map((session) => [session.session_id, publicSessionIdentity({ harness: session.harness ?? "codex-desktop", provider_session_id: session.provider_session_id ?? null, session_id: session.session_id })]));
+    const rawDeltas = usageDeltas(selectedRows);
+    const deltas = rawDeltas.map(({ session_id, ...delta }) => ({ ...delta, session: publicSessions.get(session_id) ?? null }));
     const segments = context.db.all(`SELECT id, session_id, run_id, protocol_id, started_at, ended_at, cwd, tool_name
      FROM flow_session_segments WHERE project_id = ? AND run_id = ? ORDER BY started_at, id`, [input.projectId, input.runId]);
     const supported = new Set(["session", "role", "aspect", "plan-item", "stage", "protocol"]);
     const groupBy = supported.has(input.groupBy) ? input.groupBy : "session";
     const groups = new Map();
-    for (const delta of deltas) {
+    for (const delta of rawDeltas) {
         const key = groupKey(delta, groupBy);
         const group = groups.get(key) ?? { tokens: emptyUsage(), snapshots: 0, statuses: {}, transition_buckets: 0 };
         group.snapshots += 1;
@@ -523,7 +553,9 @@ function usageReport(context, input, refresh) {
         run_id: input.runId,
         source: { kind: "codex_transcript_v1", parser_version: 1, refreshed_sessions: refreshed.length, checkpoint_source: refresh ? "refreshed" : "stored" },
         sessions: selectedSessions.map((session) => ({
-            session_id: session.session_id, parent_session_id: session.parent_session_id ?? null, role: session.role ?? null,
+            session: publicSessionIdentity({ harness: session.harness ?? "codex-desktop", provider_session_id: session.provider_session_id ?? null, session_id: session.session_id }),
+            ...(session.parent_session_id ? { parent_session: publicSessions.get(session.parent_session_id) ?? null } : {}),
+            role: session.role ?? null,
             aspect_id: session.aspect_id ?? null, plan_item_id: session.plan_item_id ?? null, session_kind: session.session_kind ?? null
         })),
         groups: [...groups.entries()].map(([key, group]) => ({ key, ...group, tokens: outputUsageTotals(group.tokens) })),
@@ -531,7 +563,7 @@ function usageReport(context, input, refresh) {
         tool_calls: toolCallsForSessions(sessions),
         segments: segments.map((segment) => ({
             segment_id: segment.id,
-            session_id: segment.session_id,
+            session: publicSessions.get(segment.session_id) ?? null,
             run_id: segment.run_id,
             protocol_id: segment.protocol_id,
             started_at: segment.started_at,
@@ -544,7 +576,7 @@ function usageReport(context, input, refresh) {
 function toolCallsForSessions(sessions) {
     const result = { status: "unavailable", total: 0, failures: 0, by_tool: {}, observed_sessions: 0, unavailable_sessions: [] };
     for (const session of sessions) {
-        const parsed = readToolCalls(session.transcript_path, session.session_id);
+        const parsed = readToolCalls(session.transcript_path, nativeSessionId(session));
         if (!parsed) {
             result.unavailable_sessions.push(session.session_id);
             continue;
@@ -603,7 +635,7 @@ function readToolCalls(transcriptPath, expectedSessionId) {
 function segmentUsage(context, session, segment) {
     if (!session)
         return { status: "unavailable", diagnostic: "session_record_missing" };
-    const result = readCodexTranscriptWindow(session.transcript_path, session.session_id, segment.started_at, segment.ended_at ?? context.now());
+    const result = readCodexTranscriptWindow(session.transcript_path, nativeSessionId(session), segment.started_at, segment.ended_at ?? context.now());
     return result.counter ? { status: result.status, tokens: result.counter.usage, token_event_at: result.counter.token_event_at } : { status: result.status, diagnostic: result.diagnostic ?? null };
 }
 function readCodexTranscript(transcriptPath, expectedSessionId) {

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

@@ -10,14 +10,15 @@ import { validateSchema } from "./schema-validation.js";
 import { flowCommand } from "./stage-pause.js";
 import { assertStageStartHookEvent } from "./hooks.js";
 import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
-import { addVnextCodeRepair, writeProtocolFlowStatus } from "./vnext-code.js";
-import { finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures } from "./code-checks.js";
+import { addVnextCodeRepair } from "./vnext-code.js";
+import { finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceFingerprint } from "./code-checks.js";
 import { addWorkBatch, bindStageCoordinatorWork, finishWork, refreshRunWorkProjection } from "./work-registry.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { writeStageReport } from "./stage-report-renderer.js";
 import { applyExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
 import { ensureVnextMergeRequest } from "./vnext-merge.js";
+import { validateVnextCodeHandoff } from "./vnext-plan.js";
 const stage = "code-review";
 const stageDir = vnextStageDirectory(stage);
 const baselineAspects = ["goal_traceability", "coding_standards_design_review", "verification_evidence_review"];
@@ -46,8 +47,10 @@ export function startVnextCodeReview(context, input) {
         const orchestration = readFanoutDescriptor(root);
         return { ok: true, resumed: true, run_id: run.id, stage, stage_status: 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")) } };
     }
-    const mode = effectiveMode(run, changedPaths(run.workspace_root));
+    const mode = effectiveMode(run, acceptedCodeChangedPaths(home));
     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", mode, workspace_fingerprint: workspaceFingerprint(run.workspace_root), code_report_sha256: sha256File(path.join(home, "05-code", "stage-report.json")) }, null, 2)}\n`);
     if (mode === "off") {
         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`;
         fs.writeFileSync(promptPath, prompt);
@@ -96,6 +99,8 @@ export function addVnextCodeReviewRepair(context, input) {
     if (unknown.length)
         throw new AppError("review_check_reference_unknown", "CODE-REVIEW finding cites a check absent from the accepted CODE handoff", 2, { check_refs: unknown });
     const reviewChecks = requestedCheckRefs.map((ref) => checks.get(ref)).filter((check) => check.run_at !== "external");
+    if (!reviewChecks.length)
+        throw new AppError("review_repair_executable_check_required", "CODE-REVIEW repair requires at least one executable causal check; external-only evidence cannot validate a repair Work", 2, { finding_ids: input.findingIds, check_refs: requestedCheckRefs });
     return addVnextCodeRepair(context, {
         projectRoot,
         runId: run.id,
@@ -113,7 +118,15 @@ export async function finishVnextCodeReview(context, input) {
     const run = requireRun(context, project.id, input.runId);
     const home = requireHome(run);
     const root = path.join(home, stageDir);
-    const mode = effectiveMode(run, changedPaths(run.workspace_root));
+    const reviewContext = readJson(path.join(root, "review-context.json"));
+    const mode = reviewContext.mode;
+    if (!mode)
+        throw new AppError("runtime_missing", "CODE-REVIEW effective mode was not frozen at stage start", 1);
+    if (reviewContext.code_report_sha256 !== sha256File(path.join(home, "05-code", "stage-report.json")))
+        throw new AppError("code_review_input_changed", "Accepted CODE report changed after CODE-REVIEW start", 2);
+    const handoffFailures = validateVnextCodeHandoff(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home });
+    if (handoffFailures.length)
+        throw new AppError("validation", "CODE-REVIEW handoff no longer matches the accepted PLAN", 2, { errors: handoffFailures });
     const reportPath = path.join(root, "stage-report.json");
     if (stageStatus(run, stage) === "done" && fs.existsSync(reportPath)) {
         const report = readJson(reportPath);
@@ -157,10 +170,10 @@ export async function finishVnextCodeReview(context, input) {
     const outcome = decision.findings.some((item) => item.disposition === "defer") ? "accepted_with_DEF" : "accepted";
     const repairs = reviewRepairWorks(context, project.id, run.id, root);
     const finalChecks = finalCodeCheckDeclarations(run.workspace_root, codeWorks(context, project.id, run.id).flatMap((work) => { const payload = readJsonString(work.payload_json); return Array.isArray(payload.checks) ? payload.checks : []; }));
-    const unchangedFailures = repairs.length ? unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: finalChecks }) : [];
+    const unchangedFailures = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: finalChecks });
     if (unchangedFailures.length)
         throw new AppError("code_review_gate_repair_required", "CODE-REVIEW final gate already failed for the unchanged workspace; repair the evidenced failure before retrying", 2, { outcome: "repair_required", retry_after_workspace_change: true, workspace_fingerprint: unchangedFailures[0].workspace_fingerprint, failures: unchangedFailures });
-    const receipts = repairs.length ? await runCodeChecks(context, { projectId: project.id, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, artifactDir: stageDir, scope: "aggregate", checks: finalChecks, ...(input.progress ? { progress: input.progress } : {}) }) : [];
+    const receipts = await runCodeChecks(context, { projectId: project.id, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, artifactDir: stageDir, scope: "aggregate", checks: finalChecks, ...(input.progress ? { progress: input.progress } : {}) });
     const failed = receipts.filter((receipt) => receipt.status !== "passed");
     if (failed.length)
         throw new AppError("code_review_gate_failed", "CODE-REVIEW repair changed the project but the aggregate gate failed", 2, {
@@ -174,8 +187,11 @@ export async function finishVnextCodeReview(context, input) {
     const nextAction = stopTarget === "merge_completed" ? "start_merge" : "code_review_completed";
     const now = context.now();
     const startedAt = stageStartedAt(run, now);
-    writeProtocolFlowStatus(run.workspace_root, home, run.id, nextAction === "start_merge" ? "CODE-REVIEW complete; MERGE is queued." : "CODE-REVIEW complete; this RUN reached its configured terminal boundary.");
-    const report = { schema_id: "dd-flow/stage-report@1", run_id: run.id, stage, generated_at: now, verdict: "done", semantic: { result: `Independent CODE review completed: ${reviewers.length} reviewer Work(s), ${repairs.length} repair Work(s).`, acceptance: ["all_selected_review_groups_completed", "all_material_findings_classified", ...(repairs.length ? ["all_accepted_repairs_completed", "post_repair_final_gate_passed"] : [])], run_changed_files: changedPaths(run.workspace_root), checks: receipts.map((receipt) => receipt.command), evidence: [...reviewers.flatMap((work) => readJsonString(work.result).findings.flatMap((finding) => finding.evidence_refs)), ...receipts.map((receipt) => runRef(run.id, home, receipt.receipt_path))], next_action: nextAction, code_review: { mode, reviewer_work_ids: reviewers.map((work) => work.work_id), repair_work_ids: repairs.map((work) => work.work_id), decision } }, mechanical: { started_at: startedAt, finished_at: now, wall_clock_ms: Math.max(0, Date.parse(now) - Date.parse(startedAt)), git: gitFacts(run.workspace_root), session_stats_command: `${flowCommand(context)} stat run sessions ls --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json`, usage_stats_command: `${flowCommand(context)} stat usage --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json` }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html" }, validation: { status: "passed" } };
+    const report = { schema_id: "dd-flow/stage-report@1", run_id: run.id, stage, generated_at: now, verdict: "done", semantic: { result: `Independent CODE review completed: ${reviewers.length} reviewer Work(s), ${repairs.length} repair Work(s).`, acceptance: ["all_selected_review_groups_completed", "all_material_findings_classified", ...(repairs.length ? ["all_accepted_repairs_completed"] : []), "current_final_gate_passed"], run_changed_files: changedPaths(run.workspace_root), checks: receipts.map((receipt) => receipt.command), evidence: [...reviewers.flatMap((work) => readJsonString(work.result).findings.flatMap((finding) => finding.evidence_refs)), ...receipts.map((receipt) => runRef(run.id, home, receipt.receipt_path))], next_action: nextAction, code_review: { mode, reviewer_work_ids: reviewers.map((work) => work.work_id), repair_work_ids: repairs.map((work) => work.work_id), decision } }, mechanical: { started_at: startedAt, finished_at: now, wall_clock_ms: Math.max(0, Date.parse(now) - Date.parse(startedAt)), git: gitFacts(run.workspace_root), session_stats_command: `${flowCommand(context)} stat run sessions ls --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json`, usage_stats_command: `${flowCommand(context)} stat usage --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json` }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html" }, validation: { status: "passed" } };
+    // The request must exist before CODE-REVIEW becomes terminal. Otherwise a
+    // merge-gate error creates an irrecoverable `done` report with no MRG-*.
+    const acceptedPaths = changedPaths(run.workspace_root);
+    const mergeRequest = nextAction === "start_merge" ? ensureVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths }) : null;
     writeReport(root, report);
     completeFlowRunStage(context, { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html" });
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_completed", work_id: rootWork.work_id, outcome });
@@ -186,7 +202,6 @@ export async function finishVnextCodeReview(context, input) {
         completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "code_review_completed", nextAction: undefined });
     }
     refreshRunWorkProjection(context, project.id, run.id);
-    const mergeRequest = nextAction === "start_merge" ? ensureVnextMergeRequest(context, { projectRoot, runId: run.id }) : null;
     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: `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl` } } : {}) };
 }
 function reviewGroups(run, home, mode) {
@@ -202,7 +217,7 @@ function reviewGroups(run, home, mode) {
     const chunk = mode === "deep" ? 1 : 3;
     return Array.from({ length: Math.ceil(all.length / chunk) }, (_, index) => ({ key: `group-${index + 1}`, aspect_ids: all.slice(index * chunk, (index + 1) * chunk) }));
 }
-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")}. 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. Finding ids must use the unique prefix FIND-${group.key}-. Return dd-flow/code-review-result@1.`; }
+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")}. 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 = read(path.join(input.run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code-review.md")); const decision = path.join(input.root, "decision.json"); const checks = acceptedCodeChecks(context, input.run.project_id, input.run.id).map(({ id, purpose }) => ({ id, purpose })); 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_home_path, "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>", "Each reviewer Work must run in one fresh child session. The coordinator must never claim a reviewer Work itself. Start each ready Work with its exact start_command from the work graph; it receives the task and result schema. Reviewers are read-only and must not create subagents. Do not interrupt a quiet worker.", `Ready reviewer Works: ${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(input.projectRoot)} --json`, `Finish only after every reviewer Work settles and you have written ${decision}: ${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. Run it, then call the same Finish command again. Review is not repeated.", "If the post-repair aggregate gate fails, do not stop after `code_review_gate_failed`: that rejected finish does not create a repair Work. In the same coordinator Turn, use the returned repair command with the failed receipt, a relevant completed origin Work ID, and a concise repair objective; then stop so the runner can dispatch the new repair. Do not edit invisibly in the root orchestrator.", `Accepted repair checks: ${JSON.stringify(checks)}`, "```json", JSON.stringify({ schema_id: "dd-flow/code-review-decision@3", summary: "Evidence-backed conclusion.", findings: [{ finding_ref: "WRK-001-review/FIND-001", disposition: "fix | defer | reject | duplicate", reason: "Why this classification is correct.", check_refs: ["CHK-CAUSAL-CHECK only when disposition is fix"], def_id: "DEF-0001 only for an allowed P2 deferral", duplicate_of: "canonical finding_ref only for duplicate" }] }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n"); }
 function canonicalReviewEvidence(decision, reviewers) {
     const known = new Set(canonicalCodeFindings(reviewers).map((item) => item.finding_ref));
@@ -278,8 +293,20 @@ function validateDecision(context, input) {
         if (!known.has(item.finding_ref))
             throw new AppError("review_evidence_invalid", "Decision references an unknown reviewer finding", 2, { finding_ref: item.finding_ref });
 }
-function validateReviewerResult(context, work, run) { if (!work.result)
-    throw new AppError("review_evidence_invalid", "Reviewer Work has no result", 2, { work_id: work.work_id }); const file = path.join(requireHome(run), stageDir, `${work.work_id}.result.json`); fs.writeFileSync(file, work.result); validateSchema({ schemaName: "code-review-result", file, projectRoot: run.workspace_root, ddFlowHome: context.ddFlowHome, runId: run.id }); }
+function validateReviewerResult(_context, work, _run) {
+    if (!work.result)
+        throw new AppError("review_evidence_invalid", "Reviewer Work has no result", 2, { work_id: work.work_id });
+    // Schema, group identity and portable evidence references were validated
+    // before this Work was accepted. This fan-in guard only checks semantic
+    // relationships that depend on the aggregate review decision.
+    const result = readJsonString(work.result);
+    if (result.verdict === "blocked")
+        throw new AppError("review_blocked", "A blocked reviewer result cannot be accepted as completed review evidence", 2, { work_id: work.work_id });
+    if (result.verdict === "pass" && result.findings.length)
+        throw new AppError("review_evidence_invalid", "A passing reviewer result cannot contain material findings", 2, { work_id: work.work_id });
+    if (result.aspects.some((aspect) => aspect.verdict === "blocked"))
+        throw new AppError("review_blocked", "A blocked review aspect must be resolved before CODE-REVIEW can finish", 2, { work_id: work.work_id });
+}
 function reviewerWorks(context, projectId, runId) { return context.db.all("SELECT * FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id", [projectId, runId]).filter((work) => { const p = readJsonString(work.payload_json); return Boolean(p && p.kind === "code-review"); }); }
 function codeWorks(context, projectId, runId) { return context.db.all("SELECT * FROM works WHERE project_id = ? AND run_id = ? AND status = 'completed' ORDER BY created_at, work_id", [projectId, runId]).filter((work) => readJsonString(work.payload_json).schema_id === "dd-flow/code-work-packet@5" && !reviewFindingIds(work).length); }
 function acceptedCodeChecks(context, projectId, runId) { return codeWorks(context, projectId, runId).flatMap((work) => { const payload = readJsonString(work.payload_json); return Array.isArray(payload.checks) ? payload.checks : []; }); }
@@ -311,6 +338,13 @@ function reviewCheckRefs(work) { const repair = readJsonString(work.payload_json
     return []; const refs = repair.review_check_refs; return Array.isArray(refs) ? refs.filter((value) => typeof value === "string") : []; }
 function canonicalCodeFindings(works) { return works.flatMap((work) => readJsonString(work.result).findings.map((finding) => ({ finding_ref: `${work.work_id}/${finding.finding_id}`, finding }))); }
 function effectiveMode(run, paths) { const index = JSON.parse(run.index_json); const requested = index.settings?.code_review?.mode ?? "auto"; return requested === "auto" ? (paths.length ? "standard" : "off") : requested; }
+function acceptedCodeChangedPaths(home) { try {
+    const report = readJson(path.join(home, "05-code", "stage-report.json"));
+    return Array.isArray(report.semantic?.changed_files) ? report.semantic.changed_files.filter((item) => typeof item === "string") : [];
+}
+catch {
+    return [];
+} }
 function executionStopTarget(run) { return JSON.parse(run.index_json).execution_profile?.settings?.stop_target ?? "code_review_completed"; }
 function changedPaths(workspaceRoot) { try {
     return execFileSync("git", ["status", "--porcelain=v1", "--untracked-files=all"], { cwd: workspaceRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split(/\r?\n/).filter(Boolean).map((line) => line.slice(3).replace(/^.* -> /, ""));

package/dist/services/vnext-code.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
-import { aggregateCheckDeclarations, checkReceipts, codeExecutionEnvironment, finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceFingerprint } from "./code-checks.js";
+import { aggregateCheckDeclarations, checkReceipts, codeExecutionEnvironment, finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceChangedPaths, workspaceFingerprint } from "./code-checks.js";
 import { requireProjectByRoot } from "./projects.js";
 import { appendFlowRunTimelineEvent, advanceFlowRun, attachFlowRunStage, completeFlowRunStage, completeFlowRun, getFlowRunVariables, gitFacts } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
@@ -135,8 +135,22 @@ export async function finishVnextCode(context, input) {
     }
     // Reject a malformed semantic receipt before running the expensive gate.
     const verification = verificationForFinish(context, { file: input.verificationFile, projectRoot: run.workspace_root, runId: run.id });
-    if (verification.verdict !== "passed" || verification.unresolved.length > 0) {
-        throw new AppError("code_verification_incomplete", "CODE verification is not accepted; create or complete the necessary repair Work first", 2, { verification });
+    if (verification.verdict === "blocked") {
+        return { ok: true, run_id: run.id, stage, outcome: "blocked", verification, instruction: "CODE remains running. Resolve the stated external or user-input blocker in this same coordinator session, update code-verification.json, then invoke this same stage finish command again." };
+    }
+    if (verification.verdict === "passed" && verification.unresolved.length > 0) {
+        throw new AppError("verification_contradictory", "A passed CODE verification cannot contain unresolved obligations", 2, { unresolved: verification.unresolved });
+    }
+    if (verification.verdict === "needs_repair") {
+        const repair = addVnextCodeRepair(context, {
+            projectRoot,
+            runId: run.id,
+            originWorkIds: works.filter((work) => work.status === "completed").map((work) => work.work_id),
+            semanticUnresolved: verification.unresolved.length ? verification.unresolved : [verification.summary],
+            verificationPath: input.verificationFile,
+            objective: verification.summary
+        });
+        return { ok: true, run_id: run.id, stage, outcome: "repair_required", verification, repair, instruction: "The semantic verification is not accepted. Run the returned repair Work, then update code-verification.json and invoke this same stage finish command again." };
     }
     const checks = finalCodeCheckDeclarations(run.workspace_root, works.flatMap((work) => packet(work)?.checks ?? []));
     const unchangedFailures = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: checks });
@@ -174,18 +188,26 @@ export async function finishVnextCode(context, input) {
     }
     const allReceipts = checkReceipts(context, { projectId: project.id, runId: run.id });
     const finalReceipts = latestReceiptsByCommand(allReceipts);
+    const projectedVerification = verificationProjection(works, finalReceipts);
+    const unresolvedAcceptance = (projectedVerification.acceptance ?? []).filter((item) => item.status === "unresolved");
+    if (unresolvedAcceptance.length)
+        throw new AppError("code_acceptance_unresolved", "CODE cannot finish until every due acceptance criterion has current checks and evidence", 2, { unresolved: unresolvedAcceptance });
     const now = context.now();
     const timing = stageTiming(home, stage, now);
-    const changedPaths = [...new Set(works.flatMap((work) => resultPaths(work.result)))];
+    const reportedPaths = [...new Set(works.flatMap((work) => resultPaths(work.result)))];
+    const observedChangedPaths = workspaceChangedPaths(run.workspace_root);
+    const changedPaths = observedChangedPaths ?? reportedPaths;
+    const missingReportedPaths = observedChangedPaths === null ? [] : reportedPaths.filter((item) => !observedChangedPaths.includes(item));
+    if (missingReportedPaths.length)
+        throw new AppError("changed_path_not_materialized", "CODE Work reported paths that are not changed in the accepted workspace", 2, { paths: missingReportedPaths });
     const next = nextAction(run, changedPaths);
-    writeProtocolFlowStatus(run.workspace_root, home, run.id, next === "start_code_review" ? "CODE complete; CODE-REVIEW is next." : next === "start_merge" ? "CODE complete; MERGE is queued." : "CODE complete; this RUN reached its configured terminal boundary.");
     const report = {
         schema_id: "dd-flow/stage-report@1",
         run_id: run.id,
         stage,
         generated_at: now,
         verdict: "done",
-        verification: verificationProjection(works, finalReceipts),
+        verification: projectedVerification,
         semantic: {
             result: `Completed ${works.length} CODE Work item${works.length === 1 ? "" : "s"}; ${finalReceipts.filter((receipt) => receipt.status === "passed").length} current final check receipt${finalReceipts.length === 1 ? "" : "s"} passed.`,
             acceptance: [...expected],
@@ -213,6 +235,10 @@ export async function finishVnextCode(context, input) {
         artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html", summary: "stage-report.md" },
         validation: { permission_scope: "known_targets_only", memory_bank_scope: "changed_files_and_links_only", status: "passed" }
     };
+    // Creating the MERGE request is part of accepting this terminal handoff.
+    // Do it before materialising a terminal stage report or changing RUN state,
+    // so an invalid merge policy leaves CODE safely running and retryable.
+    const mergeRequest = next === "start_merge" ? ensureVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths: changedPaths }) : null;
     writeReport(root, report);
     completeFlowRunStage(context, {
         projectRoot,
@@ -237,7 +263,6 @@ export async function finishVnextCode(context, input) {
     else {
         advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "code_completed", nextAction: next });
     }
-    const mergeRequest = next === "start_merge" ? ensureVnextMergeRequest(context, { projectRoot, runId: run.id }) : null;
     return {
         ok: true,
         run_id: run.id,
@@ -255,8 +280,8 @@ export function addVnextCodeRepair(context, input) {
     const home = requireHome(run);
     if (!input.objective.trim())
         throw new AppError("validation", "Repair objective must not be empty", 2);
-    if (!input.checkReceiptId && !input.reviewFindingIds?.length) {
-        throw new AppError("validation", "Repair needs a failed check receipt or CODE-REVIEW finding", 2);
+    if (!input.checkReceiptId && !input.reviewFindingIds?.length && !input.semanticUnresolved?.length) {
+        throw new AppError("validation", "Repair needs failed check evidence, a CODE-REVIEW finding, or an unresolved CODE verification", 2);
     }
     const receipt = input.checkReceiptId ? context.db.get("SELECT id, declaration_id, run_id, command, status, receipt_path, stdout_path, stderr_path FROM check_receipts WHERE project_id = ? AND id = ?", [
         project.id,
@@ -269,11 +294,19 @@ export function addVnextCodeRepair(context, input) {
     }
     const origins = [...new Set(input.originWorkIds)].map((id) => requireCodeWork(context, project.id, run.id, id));
     const packets = origins.map((work) => packet(work));
-    const invariantPackets = receipt
+    const invariantPackets = receipt || input.semanticUnresolved?.length
         ? codeWorks(context, project.id, run.id).map((work) => packet(work)).filter((value) => !value.repair)
         : packets;
     const first = packets[0];
-    const declaredChecks = finalCodeCheckDeclarations(run.workspace_root, packets.flatMap((value) => value.checks));
+    // A later repair may be caused by any accepted aggregate declaration, not
+    // only the checks copied into its immediate repair parent.  Otherwise a
+    // repair that fixes one failed aggregate check can make a second, already
+    // declared aggregate failure impossible to repair.  The immutable source
+    // of repair eligibility is the original CODE graph.
+    const declaredChecks = finalCodeCheckDeclarations(run.workspace_root, codeWorks(context, project.id, run.id)
+        .map((work) => packet(work))
+        .filter((value) => !value.repair)
+        .flatMap((value) => value.checks));
     const failedCheck = receipt ? declaredChecks.find((check) => check.id === receipt.declaration_id) : undefined;
     if (receipt && !failedCheck) {
         throw new AppError("repair_check_declaration_missing", "Repair receipt is not backed by an accepted CODE check declaration", 2, {
@@ -281,7 +314,8 @@ export function addVnextCodeRepair(context, input) {
             declaration_id: receipt.declaration_id
         });
     }
-    const key = input.reviewFindingIds?.length ? "code-review-repair" : "code-gate-repair";
+    const semanticRepair = Boolean(input.semanticUnresolved?.length);
+    const key = input.reviewFindingIds?.length ? "code-review-repair" : semanticRepair ? "code-verification-repair" : "code-gate-repair";
     const receiptWriteScope = receipt ? receiptRepairPaths(run.workspace_root, receipt) : [];
     const repair = {
         schema_id: "dd-flow/code-work-packet@5",
@@ -291,22 +325,23 @@ export function addVnextCodeRepair(context, input) {
         repair: {
             origin_work_ids: origins.map((work) => work.work_id),
             ...(receipt ? { check_receipt_id: receipt.id, failure_receipt_path: receipt.receipt_path } : {}),
-            ...(input.reviewFindingIds?.length ? { review_finding_ids: unique(input.reviewFindingIds), review_evidence_refs: unique(input.reviewEvidenceRefs ?? []), review_check_refs: unique(input.reviewCheckRefs ?? (input.reviewChecks ?? []).map((check) => check.id)) } : {})
+            ...(input.reviewFindingIds?.length ? { review_finding_ids: unique(input.reviewFindingIds), review_evidence_refs: unique(input.reviewEvidenceRefs ?? []), review_check_refs: unique(input.reviewCheckRefs ?? (input.reviewChecks ?? []).map((check) => check.id)) } : {}),
+            ...(semanticRepair ? { semantic_unresolved: unique(input.semanticUnresolved ?? []), verification_path: input.verificationPath } : {})
         },
         task: input.objective,
         semantic_spine: {
-            user_outcome: receipt ? `Restore the accepted behavior after aggregate failure: ${input.objective}` : `Resolve accepted CODE-REVIEW finding: ${input.objective}`,
+            user_outcome: receipt ? `Restore the accepted behavior after aggregate failure: ${input.objective}` : semanticRepair ? `Close the unresolved CODE verification: ${input.objective}` : `Resolve accepted CODE-REVIEW finding: ${input.objective}`,
             component_responsibility: "Diagnose and repair the failed accepted CODE result without changing unrelated behavior.",
             must_preserve: unique(invariantPackets.flatMap((value) => value.semantic_spine.must_preserve)),
             non_goals: unique(invariantPackets.flatMap((value) => value.semantic_spine.non_goals)),
-            acceptance_contribution: receipt ? `Make failed check pass: ${receipt.command}` : `Resolve CODE-REVIEW finding(s): ${input.reviewFindingIds.join(", ")}`
+            acceptance_contribution: receipt ? `Make failed check pass: ${receipt.command}` : semanticRepair ? `Resolve CODE verification gap(s): ${input.semanticUnresolved.join("; ")}` : `Resolve CODE-REVIEW finding(s): ${input.reviewFindingIds.join(", ")}`
         },
         requirements: uniqueBy(invariantPackets.flatMap((value) => value.requirements), (value) => value.id),
         acceptance: uniqueBy(invariantPackets.flatMap((value) => value.acceptance), (value) => JSON.stringify(value)),
         // A CODE-REVIEW repair changes delivered code/evidence, never the
         // already accepted PLAN or its ownership declaration.
         document_updates: [],
-        required_read: unique([...(receipt ? [receipt.receipt_path] : input.reviewEvidenceRefs ?? []), ...packets.flatMap((value) => value.required_read)]),
+        required_read: unique([...(receipt ? [receipt.receipt_path] : input.reviewEvidenceRefs ?? []), ...(semanticRepair && input.verificationPath ? [input.verificationPath] : []), ...packets.flatMap((value) => value.required_read)]),
         discovery_boundary: unique(packets.flatMap((value) => value.discovery_boundary)),
         // These are collision-avoidance hints. Receipt paths enrich the coordinator
         // picture but never restrict the repair's project-local edits.
@@ -314,7 +349,7 @@ export function addVnextCodeRepair(context, input) {
         // Receipts record the resolved shell command. A repair must retain the
         // accepted declaration (including its immutable @check alias) and only
         // change when it runs, so work finish can validate it again.
-        checks: selectRepairChecks({ ...(failedCheck ? { failedCheck } : {}), ...(input.reviewChecks ? { reviewChecks: input.reviewChecks } : {}) }),
+        checks: selectRepairChecks({ ...(failedCheck ? { failedCheck } : {}), ...(input.reviewChecks ? { reviewChecks: input.reviewChecks } : {}), ...(semanticRepair ? { semanticChecks: declaredChecks } : {}) }),
         provides_checks: [],
         stop_conditions: unique([
             ...invariantPackets.flatMap((value) => value.stop_conditions),
@@ -339,16 +374,18 @@ export function addVnextCodeRepair(context, input) {
         type: "code_repair_created",
         work_id: id,
         origin_work_ids: input.originWorkIds,
-        ...(receipt ? { check_receipt_id: receipt.id } : { review_finding_ids: input.reviewFindingIds })
+        ...(receipt ? { check_receipt_id: receipt.id } : input.reviewFindingIds?.length ? { review_finding_ids: input.reviewFindingIds } : { semantic_unresolved: input.semanticUnresolved })
     });
     refreshRunWorkProjection(context, project.id, run.id);
     return { ok: true, run_id: run.id, repair_work_id: id, start_command: workStartCommand(context, work) };
 }
-/** The repair Work runs only the check that motivated it; the stage retains the aggregate gate. */
+/** Retain the causal declaration for worker context; run_at keeps aggregate gates at stage scope. */
 export function selectRepairChecks(input) {
-    const checks = input.failedCheck
-        ? [{ ...input.failedCheck, purpose: "Re-run the failed accepted check.", run_at: "work" }]
-        : (input.reviewChecks ?? []).map((check) => ({ ...check, purpose: `Prove the CODE-REVIEW repair: ${check.purpose}`, run_at: "work" }));
+    // Gate placement belongs to the accepted PLAN. `runCodeChecks` executes only
+    // work-scoped entries, while retaining the aggregate declaration tells the
+    // worker exactly what will be rerun by the coordinator.
+    const candidates = input.failedCheck ? [input.failedCheck] : input.reviewChecks ?? input.semanticChecks ?? [];
+    const checks = candidates.map((check) => ({ ...check, purpose: `${input.semanticChecks ? "Prove the CODE verification repair" : "Prove the CODE-REVIEW repair"}: ${check.purpose}` }));
     return uniqueBy(checks, (check) => check.id);
 }
 function receiptRepairPaths(workspaceRoot, receipt) {