auditor-lambda 0.9.1 → 0.10.0

package/dispatch/merge-results.mjs

@@ -15,7 +15,7 @@ const artifactsDir = artifactsDirIdx !== -1 && process.argv[artifactsDirIdx + 1]
   : join(process.cwd(), ".audit-artifacts");
 
 const taskResultsDir = join(artifactsDir, "runs", runId, "task-results");
-const auditResultsPath = join(artifactsDir, "runs", runId, "audit-results.json");
+const auditResultsPath = join(artifactsDir, "runs", runId, "run-results.json");
 const failedTasksPath = join(artifactsDir, "runs", runId, "failed-tasks.json");
 const tasksPath = join(artifactsDir, "runs", runId, "pending-audit-tasks.json");
 

package/dist/cli/auditStep.d.ts

@@ -1,7 +1,4 @@
-import type { AuditResult } from "../types.js";
 import type { AnalyzerSetting } from "@audit-tools/shared";
-import type { RuntimeValidationReport } from "../types/runtimeValidation.js";
-import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 export declare function runAuditStep(options: {
     root: string;
     artifactsDir: string;
@@ -23,36 +20,7 @@ export declare function ingestBatchAuditResults(options: {
     batchDir: string;
 }): Promise<{
     batchFiles: string[];
-    bundle: Partial<{
-        repo_manifest: import("../types.js").RepoManifest;
-        file_disposition: import("@audit-tools/shared").FileDisposition;
-        auto_fixes_applied: unknown;
-        unit_manifest: import("../types.js").UnitManifest;
-        graph_bundle: import("@audit-tools/shared").GraphBundle;
-        surface_manifest: import("@audit-tools/shared").SurfaceManifest;
-        critical_flows: import("@audit-tools/shared").CriticalFlowManifest;
-        flow_coverage: import("../types/flowCoverage.js").FlowCoverageManifest;
-        risk_register: import("@audit-tools/shared").RiskRegister;
-        design_assessment: import("../types/designAssessment.js").DesignAssessment;
-        analyzer_capability: import("../types/analyzerCapability.js").AnalyzerCapabilityRecord;
-        scope: import("../types/auditScope.js").AuditScopeManifest;
-        coverage_matrix: import("../types.js").CoverageMatrix;
-        runtime_validation_tasks: import("../types/runtimeValidation.js").RuntimeValidationTaskManifest;
-        runtime_validation_report: RuntimeValidationReport;
-        external_analyzer_results: ExternalAnalyzerResults;
-        syntax_resolution_status: unknown;
-        audit_results: AuditResult[];
-        audit_tasks: import("../types.js").AuditTask[];
-        audit_plan_metrics: import("../types/reviewPlanning.js").AuditPlanMetrics;
-        review_packets: import("../types/reviewPlanning.js").ReviewPacket[];
-        requeue_tasks: import("../types.js").AuditTask[];
-        audit_report: string;
-        audit_findings: import("@audit-tools/shared").AuditFindingsReport;
-        synthesis_narrative: import("../types/synthesisNarrative.js").SynthesisNarrativeRecord;
-        audit_state: import("../types/auditState.js").AuditState;
-        artifact_metadata: import("../types/artifactMetadata.js").ArtifactMetadataManifest;
-        tooling_manifest: import("../types/toolingManifest.js").ToolingManifest;
-    }>;
+    bundle: import("../io/artifacts.js").ArtifactBundle;
     audit_state: import("../types/auditState.js").AuditState;
     selected_obligation: string | null;
     selected_executor: string;

package/dist/cli/dispatch.d.ts

@@ -20,9 +20,21 @@ export declare const ACTIVE_DISPATCH_FILENAME = "active-dispatch.json";
 export interface ActiveDispatchState {
     run_id: string;
     created_at: string;
+    /** Emitted packets only (after canary/budget filtering). */
     packet_count: number;
+    /** Tasks remaining this round (not-yet-done), not just emitted-packet tasks. */
     task_count: number;
     status: "active" | "merged";
+    /** "canary" on first contact when only the top packet was emitted; "fan_out" otherwise. */
+    phase: "canary" | "fan_out";
+    /** packet_id of the emitted canary packet when phase==="canary", else null. */
+    canary_packet_id: string | null;
+    /** Total packets that would have been emitted before a budget cap (present only when capped). */
+    budget_packet_count?: number;
+    /** packet_ids NOT emitted due to the budget cap. */
+    deferred_packet_ids?: string[];
+    /** task_ids NOT emitted due to the budget cap. */
+    deferred_task_ids?: string[];
 }
 export interface DispatchResultMapEntry {
     packet_id: string;
@@ -34,6 +46,25 @@ export interface DispatchResultMap {
     run_id: string;
     entries: DispatchResultMapEntry[];
 }
+export declare const DEFAULT_DISPATCH_CONFIRM_THRESHOLD = 10;
+export interface DispatchFanout {
+    agent_count: number;
+    wave_count: number;
+    confirmation_recommended: boolean;
+    dispatch_summary: string;
+}
+/**
+ * FINDING-012: pure-arithmetic fan-out summary the loader can gate on. Given the
+ * number of agents (packets emitted this round, after canary/budget filtering)
+ * and the resolved wave size, derive the wave count, a human-readable summary,
+ * and whether the agent count exceeds the confirmation threshold (default 10).
+ * No LLM call, no side effects, no prompting.
+ */
+export declare function computeDispatchFanout(params: {
+    agentCount: number;
+    waveSize: number;
+    confirmThreshold?: number;
+}): DispatchFanout;
 export interface PrepareDispatchResult {
     run_id: string;
     dispatch_plan_path: string;
@@ -43,6 +74,22 @@ export interface PrepareDispatchResult {
     skipped_task_count: number;
     /** Subagent parallelism resolved for this dispatch run. */
     wave_size: number;
+    /** "canary" on first contact when only the top packet was emitted; "fan_out" otherwise. */
+    phase: "canary" | "fan_out";
+    /** packet_id of the emitted canary packet when phase==="canary", else null. */
+    canary_packet_id: string | null;
+    /** Total agents that will be launched this run (packet_count after canary/budget). */
+    agent_count: number;
+    /** ceil(agent_count / max(1, wave_size)). */
+    wave_count: number;
+    /** True when agent_count exceeds sessionConfig.dispatch?.confirm_threshold (default 10). */
+    confirmation_recommended: boolean;
+    /** Human-readable summary, e.g. "12 agents across 3 waves (wave_size=4)". */
+    dispatch_summary: string;
+    /** True when a max_packets budget capped the emitted packets this run. */
+    budget_capped: boolean;
+    /** Number of packets deferred (not emitted) due to the budget cap. */
+    deferred_packet_count: number;
     largest_packet: {
         packet_id: string;
         total_lines: number;

package/dist/cli/dispatch.js

@@ -4,6 +4,7 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 import { isFileMissingError, readJsonFile, writeJsonFile, DEFAULT_EMPIRICAL_HALF_LIFE_HOURS, } from "@audit-tools/shared";
 import { buildQuotaSource } from "@audit-tools/shared/quota/compositeQuotaSource";
 import { loadArtifactBundle } from "../io/artifacts.js";
+import { writePacketSchemaFiles } from "../io/runArtifacts.js";
 import { orderTasksForPacketReview, buildReviewPackets, sizeIndexFromManifest, } from "../orchestrator/reviewPackets.js";
 import { buildFileAnchorSummary } from "../orchestrator/fileAnchors.js";
 import { resolveFreshSessionProviderName } from "../providers/index.js";
@@ -16,6 +17,29 @@ export const SMALL_MODEL_HINT_MAX_ESTIMATED_TOKENS = 3000;
 export const DEEP_MODEL_HINT_MIN_ESTIMATED_TOKENS = 9000;
 export const DISPATCH_RESULT_MAP_FILENAME = "dispatch-result-map.json";
 export const ACTIVE_DISPATCH_FILENAME = "active-dispatch.json";
+export const DEFAULT_DISPATCH_CONFIRM_THRESHOLD = 10;
+/**
+ * FINDING-012: pure-arithmetic fan-out summary the loader can gate on. Given the
+ * number of agents (packets emitted this round, after canary/budget filtering)
+ * and the resolved wave size, derive the wave count, a human-readable summary,
+ * and whether the agent count exceeds the confirmation threshold (default 10).
+ * No LLM call, no side effects, no prompting.
+ */
+export function computeDispatchFanout(params) {
+    const agentCount = params.agentCount;
+    const waveSize = params.waveSize;
+    const waveCount = Math.ceil(agentCount / Math.max(1, waveSize));
+    const confirmThreshold = params.confirmThreshold ?? DEFAULT_DISPATCH_CONFIRM_THRESHOLD;
+    const confirmationRecommended = agentCount > confirmThreshold;
+    const dispatchSummary = `${agentCount} agent${agentCount !== 1 ? "s" : ""} across ` +
+        `${waveCount} wave${waveCount !== 1 ? "s" : ""} (wave_size=${waveSize})`;
+    return {
+        agent_count: agentCount,
+        wave_count: waveCount,
+        confirmation_recommended: confirmationRecommended,
+        dispatch_summary: dispatchSummary,
+    };
+}
 export function dispatchResultMapPath(runDir) {
     return join(runDir, DISPATCH_RESULT_MAP_FILENAME);
 }
@@ -200,6 +224,19 @@ export async function prepareDispatchArtifacts(params) {
     const lensDefsPath = join(params.packageRoot, "dispatch", "lens-definitions.json");
     const lensDefs = await readJsonFile(lensDefsPath);
     await mkdir(taskResultsDir, { recursive: true });
+    // FINDING-009: make the AuditResult JSON-Schema (and the two sibling schemas
+    // it $refs) reachable from this run's task-results directory so packet workers
+    // can optionally self-validate before calling submit-packet.
+    await writePacketSchemaFiles(taskResultsDir, params.packageRoot);
+    // FINDING-011: read the prior dispatch state (if any) so a fan-out round can
+    // detect a preceding canary that never produced an accepted result.
+    let priorActiveDispatch = null;
+    try {
+        priorActiveDispatch = await readJsonFile(join(artifactsDir, ACTIVE_DISPATCH_FILENAME));
+    }
+    catch {
+        /* none yet */
+    }
     const priorResultTaskIds = new Set();
     for (const task of tasks) {
         if (existsSync(taskResultPath(taskResultsDir, task.task_id))) {
@@ -230,6 +267,34 @@ export async function prepareDispatchArtifacts(params) {
     if (resultPathSet.size !== resultPathByTaskId.size) {
         throw new Error("prepare-dispatch generated duplicate result paths; task ids must be uniquely addressable.");
     }
+    // Packets come back priority-ordered (high -> medium -> low), so packets[0] is
+    // the top-priority packet. Filtering composes in a fixed order: canary first
+    // (emit only the top packet on first contact), then the budget cap (top-K).
+    //
+    // FINDING-011: single-worker canary. On first contact with a multi-packet run,
+    // dispatch only the top packet; the held-back packets' tasks keep no result
+    // file, so they re-enter `dispatchTasks` on the next call (fan-out).
+    const firstContact = priorResultTaskIds.size === 0;
+    const canaryEnabled = sessionConfig.dispatch?.canary !== false; // default on
+    const doCanary = firstContact && canaryEnabled && packets.length > 1;
+    const canaryPacketId = doCanary ? packets[0].packet_id : null;
+    const phase = doCanary ? "canary" : "fan_out";
+    const postCanaryPackets = doCanary ? packets.slice(0, 1) : packets;
+    // FINDING-013: top-K coverage budget. Cap the (already priority-ordered)
+    // packets at max_packets; the remainder are recorded as DEFERRED and excluded
+    // from the completion check so the run can finish honestly under budget.
+    // Budget defaults OFF (no cap) so default behavior is unchanged. Canary takes
+    // precedence: a canary round only emits 1 packet regardless of the budget.
+    const maxPackets = sessionConfig.dispatch?.max_packets;
+    const budgetCapped = typeof maxPackets === "number" &&
+        maxPackets >= 0 &&
+        maxPackets < postCanaryPackets.length;
+    const emitPackets = budgetCapped
+        ? postCanaryPackets.slice(0, maxPackets)
+        : postCanaryPackets;
+    const deferredPackets = budgetCapped
+        ? postCanaryPackets.slice(maxPackets)
+        : [];
     const plan = [];
     const resultMapEntries = [];
     for (const task of tasks) {
@@ -245,7 +310,7 @@ export async function prepareDispatchArtifacts(params) {
     let largestLines = 0;
     let largestEstimatedTokens = 0;
     const warnings = [];
-    for (const packet of packets) {
+    for (const packet of emitPackets) {
         const promptPath = packetPromptPath(taskResultsDir, packet.packet_id);
         const packetTasks = packet.task_ids
             .map((taskId) => tasksById.get(taskId))
@@ -396,6 +461,11 @@ export async function prepareDispatchArtifacts(params) {
             "way to record results, and it writes them inside the artifacts directory for you.",
             "Produce one JSON array containing exactly one AuditResult object for each listed task.",
             "",
+            "Schema file (resolve relative to this prompt's directory): audit_result.schema.json",
+            "  $refs resolved from the same directory: finding.schema.json, audit_task.schema.json",
+            "You MAY validate your JSON array against the schema before calling submit-packet. This is optional;",
+            "  the submit command performs the authoritative validation and will report any errors.",
+            "",
             "Required AuditResult fields:",
             "  task_id       copy from the task metadata",
             "  unit_id       copy from the task metadata",
@@ -524,20 +594,57 @@ export async function prepareDispatchArtifacts(params) {
             }
         }
     }
+    // FINDING-011: when advancing past a canary, warn if it never produced an
+    // accepted result. submit-packet writes the per-task result file ONLY after
+    // validation passes, so presence of that file == ACCEPTED. We map the recorded
+    // canary packet_id back to its task ids via the result map and check whether
+    // those tasks now have accepted results (i.e. landed in priorResultTaskIds).
+    if (!doCanary && priorActiveDispatch?.phase === "canary" && priorActiveDispatch.canary_packet_id) {
+        const canaryAccepted = priorActiveDispatch.run_id === runId
+            ? (await loadDispatchResultMap(runDir))?.entries
+                .filter((entry) => entry.packet_id === priorActiveDispatch.canary_packet_id)
+                .every((entry) => priorResultTaskIds.has(entry.task_id)) ?? false
+            : false;
+        if (!canaryAccepted) {
+            warnings.push({
+                code: "canary_not_accepted",
+                message: `Canary packet ${priorActiveDispatch.canary_packet_id} did not produce an accepted result before fan-out; remaining packets are being dispatched anyway.`,
+            });
+        }
+    }
     const warningsPath = warnings.length > 0
         ? join(runDir, "dispatch-warnings.json")
         : null;
     if (warningsPath) {
         await writeJsonFile(warningsPath, warnings);
     }
+    // FINDING-013: record deferred packets/tasks so the completion obligation can
+    // exclude them under a budget cap (present only when actually capped).
+    const deferredPacketIds = deferredPackets.map((packet) => packet.packet_id);
+    const deferredTaskIds = deferredPackets.flatMap((packet) => packet.task_ids);
     const activeDispatch = {
         run_id: runId,
         created_at: new Date().toISOString(),
         packet_count: plan.length,
         task_count: orderedTasks.length,
         status: "active",
+        phase,
+        canary_packet_id: canaryPacketId,
+        ...(budgetCapped
+            ? {
+                budget_packet_count: postCanaryPackets.length,
+                deferred_packet_ids: deferredPacketIds,
+                deferred_task_ids: deferredTaskIds,
+            }
+            : {}),
     };
     await writeJsonFile(join(artifactsDir, ACTIVE_DISPATCH_FILENAME), activeDispatch);
+    // FINDING-012: pure-arithmetic fan-out summary the loader can gate on.
+    const fanout = computeDispatchFanout({
+        agentCount: plan.length,
+        waveSize: waveSchedule.wave_size,
+        confirmThreshold: sessionConfig.dispatch?.confirm_threshold,
+    });
     return {
         run_id: runId,
         dispatch_plan_path: dispatchPlanPath,
@@ -546,6 +653,14 @@ export async function prepareDispatchArtifacts(params) {
         task_count: orderedTasks.length,
         skipped_task_count: priorResultTaskIds.size,
         wave_size: waveSchedule.wave_size,
+        phase,
+        canary_packet_id: canaryPacketId,
+        agent_count: fanout.agent_count,
+        wave_count: fanout.wave_count,
+        confirmation_recommended: fanout.confirmation_recommended,
+        dispatch_summary: fanout.dispatch_summary,
+        budget_capped: budgetCapped,
+        deferred_packet_count: deferredPackets.length,
         largest_packet: largestPacketId
             ? {
                 packet_id: largestPacketId,

package/dist/cli/mergeAndIngestCommand.js

@@ -7,6 +7,11 @@ import { DISPATCH_RESULT_MAP_FILENAME, ACTIVE_DISPATCH_FILENAME, loadDispatchRes
 import { addFileLineCountHints } from "./lineIndex.js";
 import { isCanonicalResultFilename, getArtifactsDir, getFlag } from "./args.js";
 import { buildWorkerResult } from "./workerResult.js";
+import { PACKET_SCHEMA_FILENAMES } from "../io/runArtifacts.js";
+// Schema pointer files prepare-dispatch copies into task-results/ for optional
+// worker self-validation. They are expected, not stray — skip them when
+// scanning for spurious files.
+const PACKET_SCHEMA_FILENAME_SET = new Set(PACKET_SCHEMA_FILENAMES);
 export async function cmdMergeAndIngest(argv) {
     const runId = getFlag(argv, "--run-id");
     if (!runId)
@@ -14,9 +19,28 @@ export async function cmdMergeAndIngest(argv) {
     const artifactsDir = getArtifactsDir(argv);
     const runDir = join(artifactsDir, "runs", runId);
     const taskResultsDir = join(runDir, "task-results");
-    const auditResultsPath = join(runDir, "audit-results.json");
+    const auditResultsPath = join(runDir, "run-results.json");
     const taskPath = join(runDir, "task.json");
     const tasksPath = join(runDir, "pending-audit-tasks.json");
+    const mergeCompletePath = join(runDir, "merge-complete.json");
+    // Idempotency: a fully-merged run is terminal. A stray re-invocation for the
+    // same run-id (e.g. after the run already advanced to the next deepening
+    // round, which rewrites this run dir's pending-audit-tasks.json to the *next*
+    // round's tasks) must be a clean no-op — not a spurious "all results missing"
+    // hard failure that also truncates the transient results file. Replay the
+    // recorded summary and exit 0.
+    let priorSummary = null;
+    try {
+        priorSummary = await readJsonFile(mergeCompletePath);
+    }
+    catch (e) {
+        if (!isFileMissingError(e))
+            throw e;
+    }
+    if (priorSummary) {
+        console.log(JSON.stringify({ ...priorSummary, idempotent_replay: true }, null, 2));
+        return;
+    }
     const workerTask = await readJsonFile(taskPath);
     const resultMap = await loadDispatchResultMap(runDir);
     if (!resultMap) {
@@ -42,9 +66,14 @@ export async function cmdMergeAndIngest(argv) {
     const passing = [];
     const failing = [];
     const seenTaskIds = new Set();
-    let spuriousFileCount = 0;
+    const spuriousFiles = [];
     const fallbackByTaskId = new Map();
     for (const filename of files) {
+        // Schema pointer files (audit_result/finding/audit_task .schema.json) are
+        // copied into task-results/ by prepare-dispatch for optional worker
+        // self-validation; they are expected, not stray.
+        if (PACKET_SCHEMA_FILENAME_SET.has(filename))
+            continue;
         const filePath = resolve(join(taskResultsDir, filename));
         if (expectedPaths.has(filePath))
             continue;
@@ -68,10 +97,16 @@ export async function cmdMergeAndIngest(argv) {
         // task-results/ dir are legitimate and must not inflate the count or bury
         // the real stray-file signal (3 -> 191 over a run before this fix).
         if (!isCanonicalResultFilename(filename)) {
-            spuriousFileCount++;
-            process.stderr.write(`[merge-and-ingest] Warning: unexpected file in task-results/: ${filename}\n`);
+            spuriousFiles.push(filename);
         }
     }
+    // Collapse stray-file warnings into a single stderr line so the real summary
+    // (emitted as the sole stdout JSON payload) is never buried under a wall of
+    // per-file warnings.
+    if (spuriousFiles.length > 0) {
+        process.stderr.write(`[merge-and-ingest] Warning: ${spuriousFiles.length} unexpected file(s) in ` +
+            `task-results/ ignored: ${spuriousFiles.join(", ")}\n`);
+    }
     for (const task of allTasks) {
         const entry = entryByTaskId.get(task.task_id);
         if (!entry) {
@@ -134,14 +169,18 @@ export async function cmdMergeAndIngest(argv) {
             failing.push({ task_id: taskId ?? task.task_id, errors: resultErrors });
         }
     }
-    await writeJsonFile(auditResultsPath, passing);
     const failedTasksPath = join(runDir, "failed-tasks.json");
     if (failing.length > 0) {
         await writeJsonFile(failedTasksPath, failing);
     }
     if (passing.length === 0 && failing.length > 0) {
+        // Nothing merged and at least one failure: a blocked no-op. Do NOT write the
+        // transient results file here — truncating it to [] reads as catastrophic
+        // data loss on a re-run when the cumulative audit_results.jsonl store is in
+        // fact intact and the first merge had simply already succeeded.
         throw new Error(`All ${failing.length} assigned task result(s) were missing or invalid; blocked before ingestion. See ${failedTasksPath}`);
     }
+    await writeJsonFile(auditResultsPath, passing);
     const findingCount = passing.reduce((sum, result) => sum + result.findings.length, 0);
     let result = null;
     if (passing.length > 0) {
@@ -197,12 +236,12 @@ export async function cmdMergeAndIngest(argv) {
         errors: [],
     });
     await writeJsonFile(workerTask.result_path, workerResult);
-    console.log(JSON.stringify({
+    const summaryPayload = {
         run_id: runId,
         status,
         accepted_count: passing.length,
         rejected_count: failing.length,
-        spurious_file_count: spuriousFileCount,
+        spurious_file_count: spuriousFiles.length,
         finding_count: findingCount,
         audit_results_path: auditResultsPath,
         ...(retryDispatchPath ? { retry_dispatch_path: retryDispatchPath } : {}),
@@ -212,7 +251,15 @@ export async function cmdMergeAndIngest(argv) {
             progress_summary: workerResult.summary,
             next_likely_step: workerResult.next_likely_step,
         } : {}),
-    }, null, 2));
+    };
+    // Record a completion marker for a fully-merged run so a stray re-invocation
+    // replays this summary (above) instead of re-processing — and possibly
+    // clobbering — terminal state. Only on full success: a partial merge is meant
+    // to be re-run after the failed packets are retried, so it stays replayable.
+    if (failing.length === 0) {
+        await writeJsonFile(mergeCompletePath, summaryPayload);
+    }
+    console.log(JSON.stringify(summaryPayload, null, 2));
     if (failing.length > 0) {
         process.exitCode = 2;
     }

package/dist/cli/nextStepCommand.js

@@ -35,6 +35,42 @@ async function runDeterministicForNextStep(params) {
     const FINALIZATION_CYCLE_TOLERANCE = 16;
     const seenStateSignatures = new Set();
     const obligationTrail = [];
+    // Build the terminal step for a deterministic loop that has stopped advancing
+    // (hit the run backstop or the finalization cycle guard). A rendered report is
+    // the deliverable: if synthesis already produced one — or the state is formally
+    // complete — present it instead of reporting the stopped loop as a bare
+    // "blocked" failure. A completed audit must never surface as blocked just
+    // because finalization kept churning (e.g. a runtime_validation <-> synthesis
+    // ping-pong, or revision churn from filesystem retries) after the report was
+    // written. With no report yet, the stop is a genuine block.
+    async function terminalStep(bundle, state, blockedReason) {
+        const reportRendered = state.status === "complete" || Boolean(bundle.audit_report);
+        await writeHandoffOnly({
+            root: params.root,
+            artifactsDir: params.artifactsDir,
+            bundle,
+            audit_state: state,
+            progress_summary: reportRendered && state.status !== "complete"
+                ? `Audit report already rendered; ending run. ${blockedReason}`
+                : blockedReason,
+            providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
+        });
+        if (!reportRendered) {
+            return { kind: "blocked", state, bundle, reason: blockedReason };
+        }
+        const promoted = await promoteFinalAuditReport({
+            artifactsDir: params.artifactsDir,
+            repoRoot: params.root,
+        });
+        return {
+            kind: "complete",
+            state,
+            bundle,
+            finalReportPath: promoted.promoted
+                ? join(params.root, AUDIT_REPORT_FILENAME)
+                : join(params.artifactsDir, AUDIT_REPORT_FILENAME),
+        };
+    }
     for (let index = 0; index < params.maxRuns; index++) {
         const bundle = await loadArtifactBundle(params.artifactsDir);
         const decision = decideNextStep(bundle);
@@ -318,24 +354,14 @@ async function runDeterministicForNextStep(params) {
                     `progress; stopping. Cycling obligations: ${cycle.join(" -> ")}.`,
                 timestamp: new Date().toISOString(),
             });
-            return {
-                kind: "blocked",
-                state: result.audit_state,
-                bundle: result.updated_bundle,
-                reason: "Finalization is not converging: deterministic executors kept revisiting " +
-                    `prior artifact states (${cycle.join(" -> ")}). The report has been ` +
-                    "rendered; review whether these obligations are erroneously invalidating each other.",
-            };
+            return await terminalStep(result.updated_bundle, result.audit_state, "Finalization is not converging: deterministic executors kept revisiting " +
+                `prior artifact states (${cycle.join(" -> ")}). Review whether these ` +
+                "obligations are erroneously invalidating each other.");
         }
     }
     const bundle = await loadArtifactBundle(params.artifactsDir);
     const state = deriveAuditState(bundle);
-    return {
-        kind: "blocked",
-        state,
-        bundle,
-        reason: `Reached max run limit (${params.maxRuns}) before a review, report, or blocker step was ready.`,
-    };
+    return await terminalStep(bundle, state, `Reached max run limit (${params.maxRuns}) before a review, report, or blocker step was ready.`);
 }
 export async function cmdNextStep(argv) {
     const root = getRootDir(argv);
@@ -429,7 +455,9 @@ export async function cmdNextStep(argv) {
         const designReviewResultsPath = join(artifactsDir, "incoming", "design-review-findings.json");
         await mkdir(join(artifactsDir, "incoming"), { recursive: true });
         const continueCommand = nextStepCommand(root, artifactsDir);
-        const prompt = renderDesignReviewPrompt(result.bundle);
+        const prompt = renderDesignReviewPrompt(result.bundle, {
+            max_units: sessionConfig.design_review?.max_units,
+        });
         const fullPrompt = [
             prompt,
             "## Results path",

package/dist/cli/prompts.d.ts

@@ -10,6 +10,8 @@ export declare function renderDispatchReviewPrompt(params: {
     dispatchQuotaPath: string | null;
     hostCanRestrictSubagentTools: boolean;
     hostCanSelectSubagentModel: boolean;
+    phase?: "canary" | "fan_out";
+    canaryPacketId?: string | null;
 }): string;
 export declare function renderSingleTaskFallbackStepPrompt(params: {
     singleTaskPromptPath: string;

package/dist/cli/prompts.js

@@ -78,10 +78,19 @@ export function renderDispatchReviewPrompt(params) {
             "",
             "Launch one subagent for each entry in the plan.",
         ];
+    const canaryLines = params.phase === "canary"
+        ? [
+            "",
+            "This is a CANARY round: the plan contains only the single top-priority packet. " +
+                "Dispatch it, run merge-and-ingest, then run next-step — the remaining packets fan out " +
+                "on the following step once this packet's result is accepted.",
+        ]
+        : [];
     return [
         "# audit-code dispatch review",
         "",
         ...dispatchDataLines,
+        ...canaryLines,
         "",
         "Pass each `entry.prompt_path` literally to its subagent; do not load packet prompt files into this orchestrator context.",
         "",

package/dist/cli/reviewRun.js

@@ -90,7 +90,7 @@ export async function ensureSemanticReviewRun(params) {
     const paths = getRunPaths(params.artifactsDir, runId);
     const pendingTasks = await addFileLineCountHints(params.root, buildPendingAuditTasks(params.bundle));
     const pendingTasksPath = join(paths.runDir, "pending-audit-tasks.json");
-    const auditResultsPath = join(paths.runDir, "audit-results.json");
+    const auditResultsPath = join(paths.runDir, "run-results.json");
     const taskReadPaths = new Set();
     for (const pt of pendingTasks) {
         for (const fp of pt.file_paths)

package/dist/cli/runToCompletion.js

@@ -70,7 +70,7 @@ async function buildParallelWaveSlots(params) {
         runCount += 1;
         const slotRunId = buildRunId(obligationId, runCount);
         const slotPaths = getRunPaths(artifactsDir, slotRunId);
-        const slotAuditResultsPath = join(slotPaths.runDir, "audit-results.json");
+        const slotAuditResultsPath = join(slotPaths.runDir, "run-results.json");
         const slotPendingTasksPath = join(slotPaths.runDir, "pending-audit-tasks.json");
         const slotReadPaths = new Set();
         for (const t of group) {
@@ -398,7 +398,7 @@ async function runSingleWorkerStep(params) {
         ? join(paths.runDir, "pending-audit-tasks.json")
         : undefined;
     const providerAuditResultsPath = preferredExecutor === "agent"
-        ? join(paths.runDir, "audit-results.json")
+        ? join(paths.runDir, "run-results.json")
         : auditResultsPath;
     const providerReadPaths = new Set();
     if (pendingAuditTasks) {
@@ -694,7 +694,7 @@ export async function cmdRunToCompletion(argv) {
             const blockPaths = getRunPaths(artifactsDir, blockRunId);
             const blockPendingTasks = await addFileLineCountHints(root, buildPendingAuditTasks(bundle));
             const blockPendingTasksPath = join(blockPaths.runDir, "pending-audit-tasks.json");
-            const blockAuditResultsPath = join(blockPaths.runDir, "audit-results.json");
+            const blockAuditResultsPath = join(blockPaths.runDir, "run-results.json");
             const blockReadPaths = new Set();
             for (const pt of blockPendingTasks) {
                 for (const fp of pt.file_paths)
@@ -1031,23 +1031,36 @@ export async function cmdRunToCompletion(argv) {
     const bundle = await loadArtifactBundle(artifactsDir);
     const decision = decideNextStep(bundle);
     const state = decision.state;
-    if (state.status === "complete") {
+    // A rendered report is the deliverable: if synthesis already produced one (or
+    // the state is formally complete), finish the run on it instead of stranding
+    // it in the artifacts dir behind a bare "max run limit" non-completion. This
+    // mirrors next-step's terminalStep so both loops present a completed audit the
+    // same way, even when finalization churned (runtime_validation <-> synthesis
+    // ping-pong, or filesystem-retry revision churn) up to the backstop. With no
+    // report yet, the run limit is a genuine non-terminal stop.
+    const reportRendered = state.status === "complete" || Boolean(bundle.audit_report);
+    if (reportRendered) {
         await clearDispatchFiles(artifactsDir);
     }
+    const terminalState = reportRendered && state.status !== "complete"
+        ? { ...state, status: "complete" }
+        : state;
     await emitEnvelope({
         root,
         artifactsDir,
         bundle,
-        audit_state: state,
+        audit_state: terminalState,
         selected_obligation: lastResult?.obligation_id ?? decision.selected_obligation,
         selected_executor: lastResult?.selected_executor ?? decision.selected_executor,
         progress_made: anyProgress,
         artifacts_written: Array.from(artifactsWritten),
-        progress_summary: `Reached max run limit (${maxRuns}) before terminal state.`,
-        next_likely_step: state.status === "complete" ? null : decision.selected_obligation,
+        progress_summary: reportRendered && state.status !== "complete"
+            ? `Audit report already rendered; completing the run after reaching the max run limit (${maxRuns}) during finalization.`
+            : `Reached max run limit (${maxRuns}) before terminal state.`,
+        next_likely_step: reportRendered ? null : decision.selected_obligation,
         providerName: provider.name,
     });
-    if (state.status === "complete") {
+    if (reportRendered) {
         await promoteFinalAuditReport({ artifactsDir, repoRoot: root });
     }
 }