auditor-lambda 0.9.2 → 0.10.0

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)
@@ -64,6 +69,11 @@ export async function cmdMergeAndIngest(argv) {
     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;

package/dist/cli/nextStepCommand.js

@@ -455,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/semanticReviewStep.js

@@ -64,7 +64,10 @@ export async function renderSemanticReviewStep(params) {
         allowedCommands: [mergeCommand, continueCommand],
         allowedMcpTools: ["auditor_merge_and_ingest", "auditor_continue_audit"],
         progress: {
-            summary: `Dispatching ${dispatch.packet_count} review packet(s) covering ` +
+            summary: (dispatch.phase === "canary"
+                ? `Canary: dispatching only the top-priority packet (${dispatch.canary_packet_id}) before fan-out. `
+                : "") +
+                `Dispatching ${dispatch.packet_count} review packet(s) covering ` +
                 `${dispatch.task_count} task(s) in waves of ${dispatch.wave_size}` +
                 (dispatch.skipped_task_count > 0
                     ? `; ${dispatch.skipped_task_count} task(s) already completed.`
@@ -73,6 +76,12 @@ export async function renderSemanticReviewStep(params) {
             pending_tasks: dispatch.task_count,
             completed_tasks: dispatch.skipped_task_count,
             wave_size: dispatch.wave_size,
+            phase: dispatch.phase,
+            canary_packet_id: dispatch.canary_packet_id,
+            agent_count: dispatch.agent_count,
+            wave_count: dispatch.wave_count,
+            confirmation_recommended: dispatch.confirmation_recommended,
+            dispatch_summary: dispatch.dispatch_summary,
         },
         stopCondition: "Dispatch every packet, run merge-and-ingest once, then run next-step.",
         repoRoot: root,
@@ -91,6 +100,8 @@ export async function renderSemanticReviewStep(params) {
             dispatchQuotaPath: dispatch.dispatch_quota_path,
             hostCanRestrictSubagentTools: params.hostCanRestrictSubagentTools,
             hostCanSelectSubagentModel: params.hostCanSelectSubagentModel,
+            phase: dispatch.phase,
+            canaryPacketId: dispatch.canary_packet_id,
         }),
         access: {
             read_paths: [

package/dist/cli/steps.d.ts

@@ -17,6 +17,21 @@ export interface StepProgress {
     completed_tasks?: number;
     /** Subagent parallelism resolved for this dispatch run. */
     wave_size?: number;
+    /** "canary" when only the top packet was emitted this round; "fan_out" otherwise. */
+    phase?: "canary" | "fan_out";
+    /** packet_id of the emitted canary packet when `phase === "canary"`. */
+    canary_packet_id?: string | null;
+    /** Total agents (packets) that will be launched this run. */
+    agent_count?: number;
+    /** Number of dispatch waves for this run (`ceil(agent_count / wave_size)`). */
+    wave_count?: number;
+    /**
+     * True when `agent_count` exceeds the configured confirm threshold and the
+     * loader should pause for user confirmation before fan-out (FINDING-012).
+     */
+    confirmation_recommended?: boolean;
+    /** Human-readable fan-out summary, e.g. "12 agents across 3 waves (wave_size=4)". */
+    dispatch_summary?: string;
 }
 export interface StepArtifact {
     contract_version: typeof STEP_CONTRACT_VERSION;

package/dist/cli.js

@@ -21,7 +21,6 @@ import { deriveAuditState } from "./orchestrator/state.js";
 import { createFreshSessionProvider, resolveFreshSessionProviderName, } from "./providers/index.js";
 import { getSessionConfigPath, loadSessionConfig, readSessionConfigFile, } from "./supervisor/sessionConfig.js";
 import { clearDispatchFiles, ensureSupervisorDirs, } from "./io/runArtifacts.js";
-import { runAuditCodeMcpServer } from "./mcp/server.js";
 import { scheduleWave, buildProviderModelKey, readQuotaState, resolveLimits, resolveHostActiveSubagentLimit, computeMaxSafeConcurrency, getQuotaStatePath, lookupDiscoveredLimits, setQuotaStateDir, } from "./quota/index.js";
 import { DIRECT_CLI_DEFAULTS, getFlag, hasFlag, fromBase64Url, taskResultPath, getArtifactsDir, getRootDir, warnIfNotGitRepo, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, getExplicitProvider, getHostModel, getHostMaxActiveSubagents, resolveRunProviderName, chunkArray, getUiMode, looksLikeCliFlag, countLines, } from "./cli/args.js";
 import { ACTIVE_DISPATCH_FILENAME, loadDispatchResultMap, prepareDispatchArtifacts, } from "./cli/dispatch.js";
@@ -539,9 +538,6 @@ async function cmdCleanup(argv) {
         dry_run: dryRun,
     }, null, 2));
 }
-async function cmdMcp(argv) {
-    await runAuditCodeMcpServer(argv.slice(3));
-}
 async function cmdQuota(argv) {
     const artifactsDir = getArtifactsDir(argv);
     const sessionConfig = await loadSessionConfig(artifactsDir).catch(() => ({}));
@@ -707,9 +703,6 @@ async function main(argv) {
         case "cleanup":
             await cmdCleanup(argv);
             return;
-        case "mcp":
-            await cmdMcp(argv);
-            return;
         case "prepare-dispatch":
             await cmdPrepareDispatch(argv);
             return;
@@ -733,7 +726,7 @@ async function main(argv) {
             return;
         default:
             console.error(`Unknown command: ${command}`);
-            console.error("Available commands: sample-run, advance-audit, next-step, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, cleanup, mcp, prepare-dispatch, merge-and-ingest, submit-packet, validate-result, quota, status, dispatch-status");
+            console.error("Available commands: sample-run, advance-audit, next-step, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, cleanup, prepare-dispatch, merge-and-ingest, submit-packet, validate-result, quota, status, dispatch-status");
             process.exitCode = 1;
     }
 }

package/dist/io/artifacts.d.ts

@@ -12,6 +12,7 @@ import type { DesignAssessment } from "../types/designAssessment.js";
 import type { AnalyzerCapabilityRecord } from "../types/analyzerCapability.js";
 import type { AuditScopeManifest } from "../types/auditScope.js";
 import type { ToolingManifest } from "../types/toolingManifest.js";
+import type { ActiveDispatchState } from "../cli/dispatch.js";
 type ArtifactPayloadMap = {
     repo_manifest: RepoManifest;
     file_disposition: FileDisposition;
@@ -45,8 +46,15 @@ type ArtifactPayloadMap = {
 /**
  * Audit artifacts accumulate phase-by-phase as the orchestrator advances.
  * Missing keys mean the corresponding artifact has not been produced yet.
+ *
+ * `active_dispatch` is loaded specially (like `tooling_manifest`): it lives at
+ * the artifacts root rather than as a standard pruned artifact, and carries the
+ * in-flight dispatch phase plus any budget-deferred task ids the completion
+ * obligation must exclude.
  */
-export type ArtifactBundle = Partial<ArtifactPayloadMap>;
+export type ArtifactBundle = Partial<ArtifactPayloadMap> & {
+    active_dispatch?: ActiveDispatchState;
+};
 export type ArtifactBundleKey = keyof ArtifactPayloadMap;
 type ArtifactPhase = "intake" | "analysis" | "execution" | "reporting" | "supervisor";
 interface ArtifactDefinition<K extends ArtifactBundleKey = ArtifactBundleKey> {

package/dist/io/artifacts.js

@@ -77,6 +77,13 @@ export async function loadArtifactBundle(root) {
         }
     }
     bundle.tooling_manifest = await buildToolingManifest();
+    // active-dispatch.json is written by prepare-dispatch at the artifacts root
+    // (not a standard ARTIFACT_DEFINITIONS entry). Load it so the completion
+    // obligation can exclude budget-deferred tasks. Absent on a fresh run.
+    const activeDispatch = await readOptionalJsonFile(join(root, "active-dispatch.json"));
+    if (activeDispatch !== undefined) {
+        bundle.active_dispatch = activeDispatch;
+    }
     return bundle;
 }
 export async function writeCoreArtifacts(root, bundle, options = {}) {

package/dist/io/runArtifacts.d.ts

@@ -2,6 +2,20 @@ import type { AuditTask } from "../types.js";
 import type { WorkerTask } from "../types/workerSession.js";
 import type { RunPaths, DispatchBatchRun } from "./runArtifactTypes.js";
 export type { RunPaths, DispatchBatchRun } from "./runArtifactTypes.js";
+/**
+ * Schema files copied into a dispatch run's `task-results/` directory so packet
+ * workers can optionally self-validate before submit. `audit_result.schema.json`
+ * `$ref`s the other two by relative filename, so all three must sit side-by-side
+ * for a validator to resolve them. Exported so merge-and-ingest can recognize
+ * them as legitimate (not stray) files in `task-results/`.
+ */
+export declare const PACKET_SCHEMA_FILENAMES: readonly ["audit_result.schema.json", "finding.schema.json", "audit_task.schema.json"];
+/**
+ * Copy {@link PACKET_SCHEMA_FILENAMES} into `targetDir` under their canonical
+ * filenames, making the AuditResult schema reachable from a dispatch run's
+ * `task-results/` directory.
+ */
+export declare function writePacketSchemaFiles(targetDir: string, pkgRoot: string): Promise<void>;
 export declare function buildRunId(obligationId: string | null, index: number, now?: Date): string;
 export declare function getRunPaths(artifactsDir: string, runId: string): RunPaths;
 export declare function ensureSupervisorDirs(artifactsDir: string): Promise<void>;

package/dist/io/runArtifacts.js

@@ -7,6 +7,29 @@ const packageRoot = resolve(moduleDir, "..", "..");
 const auditResultSchemaPath = join(packageRoot, "schemas", "audit_result.schema.json");
 const auditResultsSchemaPath = join(packageRoot, "schemas", "audit_results.schema.json");
 const findingSchemaPath = join(packageRoot, "schemas", "finding.schema.json");
+/**
+ * Schema files copied into a dispatch run's `task-results/` directory so packet
+ * workers can optionally self-validate before submit. `audit_result.schema.json`
+ * `$ref`s the other two by relative filename, so all three must sit side-by-side
+ * for a validator to resolve them. Exported so merge-and-ingest can recognize
+ * them as legitimate (not stray) files in `task-results/`.
+ */
+export const PACKET_SCHEMA_FILENAMES = [
+    "audit_result.schema.json",
+    "finding.schema.json",
+    "audit_task.schema.json",
+];
+/**
+ * Copy {@link PACKET_SCHEMA_FILENAMES} into `targetDir` under their canonical
+ * filenames, making the AuditResult schema reachable from a dispatch run's
+ * `task-results/` directory.
+ */
+export async function writePacketSchemaFiles(targetDir, pkgRoot) {
+    await mkdir(targetDir, { recursive: true });
+    for (const name of PACKET_SCHEMA_FILENAMES) {
+        await writeFile(join(targetDir, name), await readFile(join(pkgRoot, "schemas", name), "utf8"), "utf8");
+    }
+}
 const CURRENT_TASK_FILENAME = "current-task.json";
 const CURRENT_PROMPT_FILENAME = "current-prompt.md";
 const CURRENT_TASKS_FILENAME = "current-tasks.json";

package/dist/orchestrator/designReviewPrompt.d.ts

@@ -1,2 +1,5 @@
 import type { ArtifactBundle } from "../io/artifacts.js";
-export declare function renderDesignReviewPrompt(bundle: ArtifactBundle): string;
+export interface DesignReviewOptions {
+    max_units?: number;
+}
+export declare function renderDesignReviewPrompt(bundle: ArtifactBundle, options?: DesignReviewOptions): string;

package/dist/orchestrator/designReviewPrompt.js

@@ -45,6 +45,39 @@ function summarizeRisk(bundle) {
         ...lines,
     ].join("\n");
 }
+function buildPrioritizedReadingList(bundle, maxUnits) {
+    const items = bundle.risk_register?.items ?? [];
+    const units = bundle.unit_manifest?.units ?? [];
+    if (items.length === 0 && units.length === 0) {
+        return "No risk or unit data available; read the repository root files to orient yourself.";
+    }
+    // Build a map from unit_id → file list for fast lookup
+    const unitFiles = new Map();
+    for (const unit of units) {
+        unitFiles.set(unit.unit_id, unit.files);
+    }
+    // Sort risk items by score descending, then take the top-N
+    const sorted = [...items].sort((a, b) => b.risk_score - a.risk_score);
+    const top = sorted.slice(0, maxUnits);
+    if (top.length === 0) {
+        // Fall back to listing all units if no risk data
+        const allUnits = units.slice(0, maxUnits);
+        const lines = allUnits.map((u) => `- **${u.unit_id}** — ${u.files.join(", ")}`);
+        return [
+            `Top ${allUnits.length} unit(s) (no risk scores available):`,
+            ...lines,
+        ].join("\n");
+    }
+    const lines = top.map((item) => {
+        const files = unitFiles.get(item.unit_id);
+        const fileList = files && files.length > 0 ? files.join(", ") : "(files unknown)";
+        return `- **${item.unit_id}** (risk score: ${item.risk_score}) — ${fileList}`;
+    });
+    return [
+        `Top ${top.length} highest-risk unit(s) by risk score (out of ${items.length} total):`,
+        ...lines,
+    ].join("\n");
+}
 function summarizeSurfaces(bundle) {
     const surfaces = bundle.surface_manifest?.surfaces ?? [];
     if (surfaces.length === 0)
@@ -76,8 +109,12 @@ function formatDeterministicFindings(findings) {
         ...lines,
     ].join("\n");
 }
-export function renderDesignReviewPrompt(bundle) {
+export function renderDesignReviewPrompt(bundle, options = {}) {
     const deterministicFindings = bundle.design_assessment?.findings ?? [];
+    const unitCount = bundle.unit_manifest?.units.length ?? 0;
+    const defaultMaxUnits = Math.max(5, Math.min(20, Math.ceil(unitCount / 5)));
+    const maxUnits = options.max_units ?? defaultMaxUnits;
+    const prioritizedReadingList = buildPrioritizedReadingList(bundle, maxUnits);
     return [
         "# Project design review",
         "",
@@ -117,7 +154,11 @@ export function renderDesignReviewPrompt(bundle) {
         "",
         "## What to assess",
         "",
-        "Read the project source to understand what it does and how it works, then produce findings about:",
+        `Focus on the ${maxUnits} highest-risk units listed below; you need not read the entire repository, though you may follow any thread that demands more context. Produce findings about:`,
+        "",
+        "### Prioritised reading list",
+        "",
+        prioritizedReadingList,
         "",
         "- **Tool and library opportunities**: third-party tools, libraries, or frameworks that would improve the project. Concrete suggestions with rationale, not generic advice.",
         "- **Architecture pattern improvements**: structural changes that would improve extensibility, testability, or maintainability. Consider whether the current abstractions match the problem domain.",