auditor-lambda 0.2.5 → 0.2.8

package/dist/cli.js

@@ -1,20 +1,20 @@
-import { access, mkdir } from "node:fs/promises";
+import { access, mkdir, readdir, rename } from "node:fs/promises";
 import { createReadStream } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { buildRepoManifest } from "./extractors/fileInventory.js";
 import { buildFileDisposition } from "./extractors/disposition.js";
 import { buildCriticalFlowManifest } from "./extractors/flows.js";
 import { buildSurfaceManifest } from "./extractors/surfaces.js";
 import { buildUnitManifest } from "./orchestrator/unitBuilder.js";
 import { buildFlowCoverage } from "./orchestrator/flowCoverage.js";
-import { buildRuntimeValidationTasks, buildPlaceholderRuntimeValidationReport, } from "./orchestrator/runtimeValidation.js";
+import { buildRuntimeValidationTasks, } from "./orchestrator/runtimeValidation.js";
 import { initializeCoverageFromPlan } from "./orchestrator/planning.js";
-import { loadArtifactBundle, writeCoreArtifacts, cleanupIntermediateArtifacts, } from "./io/artifacts.js";
+import { loadArtifactBundle, writeCoreArtifacts, promoteFinalAuditReport, } from "./io/artifacts.js";
 import { readJsonFile, writeJsonFile } from "./io/json.js";
 import { validateArtifactBundle } from "./validation/artifacts.js";
 import { validateAuditResults, formatAuditResultIssues, } from "./validation/auditResults.js";
 import { validateConfiguredProviderEnvironment, validateSessionConfig, } from "./validation/sessionConfig.js";
-import { buildSynthesisReport } from "./reporting/synthesis.js";
+import { buildAuditReportModel, renderAuditReportMarkdown, } from "./reporting/synthesis.js";
 import { deriveAuditState } from "./orchestrator/state.js";
 import { advanceAudit } from "./orchestrator/advance.js";
 import { decideNextStep } from "./orchestrator/nextStep.js";
@@ -22,9 +22,10 @@ import { createFreshSessionProvider, resolveFreshSessionProviderName, } from "./
 import { appendRunLedgerEntry } from "./supervisor/runLedger.js";
 import { buildAuditCodeHandoff, writeAuditCodeHandoffArtifacts, } from "./supervisor/operatorHandoff.js";
 import { getSessionConfigPath, loadSessionConfig, readSessionConfigFile, } from "./supervisor/sessionConfig.js";
-import { buildRunId, ensureSupervisorDirs, getRunPaths, writeWorkerTaskFiles, } from "./io/runArtifacts.js";
+import { clearDispatchFiles, buildRunId, ensureSupervisorDirs, getRunPaths, writeWorkerTaskFiles, } from "./io/runArtifacts.js";
 import { renderWorkerPrompt } from "./prompts/renderWorkerPrompt.js";
 import { LOCAL_SUBPROCESS_PROVIDER_NAME } from "./providers/constants.js";
+import { runAuditCodeMcpServer } from "./mcp/server.js";
 const ADVANCE_AUDIT_CONTRACT_VERSION = "audit-code/v1alpha1";
 const WORKER_RESULT_CONTRACT_VERSION = "audit-code-worker-result/v1alpha1";
 const DEFAULT_MAX_RUNS = 1000;
@@ -50,6 +51,10 @@ function getArtifactsDir(argv) {
 function getRootDir(argv) {
     return resolve(getFlag(argv, "--root", "."));
 }
+function getBatchResultsDir(argv) {
+    const value = getFlag(argv, "--batch-results");
+    return value ? resolve(value) : undefined;
+}
 function getMaxRuns(argv) {
     const raw = Number(getFlag(argv, "--max-runs", String(DEFAULT_MAX_RUNS)));
     return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_MAX_RUNS;
@@ -78,6 +83,15 @@ function getParallelWorkers(argv, sessionConfig) {
     }
     return 1;
 }
+function getTimeoutMs(argv, sessionConfig) {
+    const fromArg = getFlag(argv, "--timeout");
+    if (fromArg !== undefined) {
+        const parsed = Number(fromArg);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return Math.floor(parsed);
+    }
+    return sessionConfig.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+}
 function chunkArray(arr, size) {
     const chunks = [];
     for (let i = 0; i < arr.length; i += size) {
@@ -203,6 +217,29 @@ async function buildLineIndex(root, repoManifest) {
     }
     return Object.fromEntries(entries);
 }
+async function buildLineIndexForPaths(root, paths) {
+    const uniquePaths = [...new Set(paths)].sort();
+    const entries = await Promise.all(uniquePaths.map(async (path) => {
+        try {
+            return [path, await countLines(resolve(root, path))];
+        }
+        catch {
+            return [path, 0];
+        }
+    }));
+    return Object.fromEntries(entries);
+}
+async function listBatchResultFiles(batchDir) {
+    const entries = await readdir(batchDir, { withFileTypes: true });
+    const files = entries
+        .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".json"))
+        .map((entry) => join(batchDir, entry.name))
+        .sort((a, b) => a.localeCompare(b));
+    if (files.length === 0) {
+        throw new Error(`No JSON audit result files found in ${batchDir}.`);
+    }
+    return files;
+}
 const PROJECT_SIGNALS = [
     "package.json",
     "go.mod",
@@ -229,33 +266,122 @@ async function detectProjectRoot(root) {
 }
 function buildPendingAuditTasks(bundle) {
     const completedTaskIds = new Set((bundle.audit_results ?? []).map((result) => result.task_id));
-    return (bundle.audit_tasks ?? []).filter((task) => !completedTaskIds.has(task.task_id));
+    return (bundle.audit_tasks ?? []).filter((task) => task.status !== "complete" && !completedTaskIds.has(task.task_id));
+}
+function formatAuditResultValidationError(issues) {
+    return (`audit-results validation failed with ${issues.length} error(s):\n` +
+        formatAuditResultIssues(issues));
+}
+function buildWorkerFailureBlocker(workerResult) {
+    const details = workerResult.errors.filter((error) => error.trim().length > 0);
+    return details.length > 0
+        ? `${workerResult.summary} ${details.join(" ")}`
+        : workerResult.summary;
+}
+function looksLikeCliFlag(value) {
+    return typeof value === "string" && value.startsWith("--");
+}
+async function maybeArchiveLegacyPendingResults(auditResultsPath) {
+    if (!auditResultsPath || basename(auditResultsPath) !== "worker_results_pending.json") {
+        return undefined;
+    }
+    const archivedPath = join(dirname(auditResultsPath), `worker_results_submitted_${new Date().toISOString().replace(/[:.]/g, "-")}.json`);
+    try {
+        await rename(auditResultsPath, archivedPath);
+        return archivedPath;
+    }
+    catch (error) {
+        process.stderr.write(`[audit-results cleanup] failed to archive ${auditResultsPath}: ${error instanceof Error ? error.message : String(error)}\n`);
+        return undefined;
+    }
 }
 async function runAuditStep(options) {
     const bundle = await loadArtifactBundle(options.artifactsDir);
+    const lineIndex = bundle.repo_manifest
+        ? await buildLineIndex(options.root, bundle.repo_manifest)
+        : undefined;
+    if (looksLikeCliFlag(options.auditResultsPath)) {
+        throw new Error(`Invalid audit results path '${options.auditResultsPath}'. This looks like a CLI flag rather than a file path.`);
+    }
     const auditResults = options.auditResultsPath
         ? await readJsonFile(options.auditResultsPath)
         : undefined;
+    if (auditResults !== undefined) {
+        const issues = validateAuditResults(auditResults, bundle.audit_tasks ?? [], {
+            lineIndex,
+        });
+        const errors = issues.filter((issue) => issue.severity === "error");
+        const warnings = issues.filter((issue) => issue.severity === "warning");
+        if (warnings.length > 0) {
+            process.stderr.write(`audit-results validation: ${warnings.length} warning(s):\n` +
+                formatAuditResultIssues(warnings) +
+                "\n");
+        }
+        if (errors.length > 0) {
+            throw new Error(formatAuditResultValidationError(errors));
+        }
+    }
     const runtimeValidationUpdates = options.runtimeUpdatesPath
         ? await readJsonFile(options.runtimeUpdatesPath)
         : undefined;
     const externalAnalyzerResults = options.externalAnalyzerPath
         ? await readJsonFile(options.externalAnalyzerPath)
         : undefined;
-    const lineIndex = bundle.repo_manifest
-        ? await buildLineIndex(options.root, bundle.repo_manifest)
-        : undefined;
     const result = await advanceAudit(bundle, {
         root: options.root,
         lineIndex,
-        auditResults,
+        auditResults: auditResults,
         runtimeValidationUpdates,
         externalAnalyzerResults,
         preferredExecutor: options.preferredExecutor,
     });
     await writeCoreArtifacts(options.artifactsDir, result.updated_bundle);
+    const archivedPendingResults = await maybeArchiveLegacyPendingResults(options.auditResultsPath);
+    if (archivedPendingResults) {
+        result.progress_summary +=
+            ` Archived legacy staging file to ${archivedPendingResults}.`;
+    }
     return result;
 }
+async function ingestBatchAuditResults(options) {
+    const batchFiles = await listBatchResultFiles(options.batchDir);
+    const artifactsWritten = new Set();
+    const progressSummaries = [];
+    let lastStep = null;
+    let anyProgress = false;
+    for (const batchFile of batchFiles) {
+        const step = await runAuditStep({
+            root: options.root,
+            artifactsDir: options.artifactsDir,
+            preferredExecutor: "result_ingestion_executor",
+            auditResultsPath: batchFile,
+        });
+        lastStep = step;
+        anyProgress ||= step.progress_made;
+        for (const artifact of step.artifacts_written) {
+            artifactsWritten.add(artifact);
+        }
+        progressSummaries.push(`${basename(batchFile)}: ${step.progress_summary}`);
+    }
+    const bundle = lastStep?.updated_bundle ??
+        (await loadArtifactBundle(options.artifactsDir));
+    const state = lastStep?.audit_state ?? deriveAuditState(bundle);
+    const decision = decideNextStep(bundle);
+    return {
+        batchFiles,
+        bundle,
+        audit_state: state,
+        selected_obligation: lastStep?.selected_obligation ?? decision.selected_obligation,
+        selected_executor: lastStep?.selected_executor ?? "result_ingestion_executor",
+        progress_made: anyProgress,
+        artifacts_written: Array.from(artifactsWritten),
+        progress_summary: `Imported ${batchFiles.length} batch result file${batchFiles.length === 1 ? "" : "s"} from ${options.batchDir}.` +
+            (progressSummaries.length > 0
+                ? `\n${progressSummaries.join("\n")}`
+                : ""),
+        next_likely_step: state.status === "complete" ? null : decision.selected_obligation,
+    };
+}
 function isWorkerResult(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -276,16 +402,35 @@ export async function runSample() {
             pass_id: "pass:security",
             lens: "security",
             agent_role: "security-auditor",
-            reviewed_ranges: [{ path: "src/api/auth.ts", start: 1, end: 100 }],
+            file_coverage: [{ path: "src/api/auth.ts", total_lines: 100 }],
             findings: [],
             notes: ["Sample result ingestion path."],
             requires_followup: false,
         },
     ];
     const flowCoverage = buildFlowCoverage(criticalFlows, coverage);
-    const runtimeValidationTasks = buildRuntimeValidationTasks(unitManifest, criticalFlows, flowCoverage);
-    const runtimeValidationReport = buildPlaceholderRuntimeValidationReport(runtimeValidationTasks);
-    const synthesisReport = buildSynthesisReport(sampleResults, runtimeValidationReport);
+    const runtimeValidationTasks = buildRuntimeValidationTasks({
+        unitManifest,
+        criticalFlows,
+        flowCoverage,
+        command: ["npm", "test"],
+    });
+    const runtimeValidationReport = {
+        results: runtimeValidationTasks.tasks.map((task) => ({
+            task_id: task.id,
+            status: "confirmed",
+            summary: "Sample runtime validation completed.",
+            evidence: [],
+            notes: [],
+        })),
+    };
+    const auditReport = renderAuditReportMarkdown(buildAuditReportModel({
+        results: sampleResults,
+        unitManifest,
+        criticalFlows,
+        coverageMatrix: coverage,
+        runtimeValidationReport,
+    }));
     const auditState = deriveAuditState({
         repo_manifest: repoManifest,
         file_disposition: disposition,
@@ -297,7 +442,7 @@ export async function runSample() {
         runtime_validation_tasks: runtimeValidationTasks,
         runtime_validation_report: runtimeValidationReport,
         audit_results: sampleResults,
-        synthesis_report: synthesisReport,
+        audit_report: auditReport,
     });
     const artifactsDir = getArtifactsDir(process.argv);
     await mkdir(artifactsDir, { recursive: true });
@@ -312,7 +457,7 @@ export async function runSample() {
         runtime_validation_tasks: runtimeValidationTasks,
         runtime_validation_report: runtimeValidationReport,
         audit_results: sampleResults,
-        synthesis_report: synthesisReport,
+        audit_report: auditReport,
         audit_state: auditState,
     });
     console.log(JSON.stringify({ audit_state: auditState, artifacts_dir: artifactsDir }, null, 2));
@@ -322,6 +467,37 @@ async function cmdAdvanceAudit(argv) {
     const artifactsDir = getArtifactsDir(argv);
     const sessionConfig = await loadSessionConfig(artifactsDir);
     const providerName = resolveFreshSessionProviderName(getFlag(argv, "--provider"), sessionConfig);
+    const batchResultsDir = getBatchResultsDir(argv);
+    if (batchResultsDir && getFlag(argv, "--results")) {
+        throw new Error("Use either --results <file> or --batch-results <dir>, not both.");
+    }
+    if (batchResultsDir) {
+        const result = await ingestBatchAuditResults({
+            root,
+            artifactsDir,
+            batchDir: batchResultsDir,
+        });
+        if (result.selected_executor !== "agent") {
+            await clearDispatchFiles(artifactsDir);
+        }
+        await emitEnvelope({
+            root,
+            artifactsDir,
+            bundle: result.bundle,
+            audit_state: result.audit_state,
+            selected_obligation: result.selected_obligation,
+            selected_executor: result.selected_executor,
+            progress_made: result.progress_made,
+            artifacts_written: result.artifacts_written,
+            progress_summary: result.progress_summary,
+            next_likely_step: result.next_likely_step,
+            providerName,
+        });
+        if (result.audit_state.status === "complete") {
+            await promoteFinalAuditReport({ artifactsDir, repoRoot: root });
+        }
+        return;
+    }
     const externalAnalyzerPath = getFlag(argv, "--external-analyzer-results");
     const result = await runAuditStep({
         root,
@@ -332,6 +508,9 @@ async function cmdAdvanceAudit(argv) {
         runtimeUpdatesPath: getFlag(argv, "--updates"),
         externalAnalyzerPath,
     });
+    if (result.selected_executor !== "agent") {
+        await clearDispatchFiles(artifactsDir);
+    }
     await emitEnvelope({
         root,
         artifactsDir,
@@ -346,7 +525,7 @@ async function cmdAdvanceAudit(argv) {
         providerName,
     });
     if (result.audit_state.status === "complete") {
-        await cleanupIntermediateArtifacts(artifactsDir);
+        await promoteFinalAuditReport({ artifactsDir, repoRoot: root });
     }
 }
 async function cmdRunToCompletion(argv) {
@@ -358,10 +537,17 @@ async function cmdRunToCompletion(argv) {
     const maxRuns = getMaxRuns(argv);
     const agentBatchSize = getAgentBatchSize(argv, sessionConfig);
     const parallelWorkers = getParallelWorkers(argv, sessionConfig);
-    const timeoutMs = sessionConfig.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+    const timeoutMs = getTimeoutMs(argv, sessionConfig);
     const selfCliPath = resolve(process.argv[1] ?? "");
     await mkdir(artifactsDir, { recursive: true });
     await ensureSupervisorDirs(artifactsDir);
+    const batchResultsDir = getBatchResultsDir(argv);
+    if (batchResultsDir && getFlag(argv, "--results")) {
+        throw new Error("Use either --results <file> or --batch-results <dir>, not both.");
+    }
+    let pendingBatchAuditResults = batchResultsDir
+        ? await listBatchResultFiles(batchResultsDir)
+        : [];
     const earlyBundle = await loadArtifactBundle(artifactsDir);
     if (!earlyBundle.unit_manifest) {
         const foundSignal = await detectProjectRoot(root);
@@ -411,6 +597,11 @@ async function cmdRunToCompletion(argv) {
             obligationId = "external_analyzer_import";
             externalAnalyzerPath = pendingExternalAnalyzerPath;
         }
+        else if (pendingBatchAuditResults.length > 0 && bundle.coverage_matrix) {
+            preferredExecutor = "result_ingestion_executor";
+            obligationId = "audit_results_ingested";
+            auditResultsPath = pendingBatchAuditResults[0];
+        }
         else if (pendingAuditResultsPath && bundle.coverage_matrix) {
             preferredExecutor = "result_ingestion_executor";
             obligationId = "audit_results_ingested";
@@ -457,7 +648,7 @@ async function cmdRunToCompletion(argv) {
                 pending_audit_tasks_path: blockPendingTasksPath,
             };
             const blockPrompt = renderWorkerPrompt(blockTask);
-            await writeWorkerTaskFiles(blockTask, blockPrompt, blockPaths, artifactsDir);
+            await writeWorkerTaskFiles(blockTask, blockPrompt, blockPaths, artifactsDir, blockPendingTasks);
             await writeJsonFile(blockPendingTasksPath, blockPendingTasks);
             await emitEnvelope({
                 root,
@@ -479,6 +670,7 @@ async function cmdRunToCompletion(argv) {
         }
         if (!preferredExecutor) {
             const state = bundle.audit_state ?? decision.state;
+            await clearDispatchFiles(artifactsDir);
             await emitEnvelope({
                 root,
                 artifactsDir,
@@ -499,7 +691,7 @@ async function cmdRunToCompletion(argv) {
                 providerName: provider.name,
             });
             if (state.status === "complete") {
-                await cleanupIntermediateArtifacts(artifactsDir);
+                await promoteFinalAuditReport({ artifactsDir, repoRoot: root });
             }
             return;
         }
@@ -527,12 +719,12 @@ async function cmdRunToCompletion(argv) {
                     skip_worker_command: true,
                 };
                 const slotPrompt = renderWorkerPrompt(slotTask);
-                await writeWorkerTaskFiles(slotTask, slotPrompt, slotPaths, artifactsDir);
+                await writeWorkerTaskFiles(slotTask, slotPrompt, slotPaths, artifactsDir, group);
                 await writeJsonFile(slotPendingTasksPath, group);
                 workerSlots.push({ runId: slotRunId, paths: slotPaths, auditResultsPath: slotAuditResultsPath, pendingTasksPath: slotPendingTasksPath, group });
             }
             const parallelStartedAt = new Date().toISOString();
-            await Promise.allSettled(workerSlots.map((slot) => provider.launch({
+            const launchResults = await Promise.allSettled(workerSlots.map((slot) => provider.launch({
                 repoRoot: root,
                 runId: slot.runId,
                 obligationId,
@@ -544,21 +736,37 @@ async function cmdRunToCompletion(argv) {
                 uiMode,
                 timeoutMs,
             })));
+            const launchErrorsByRunId = new Map();
+            for (let index = 0; index < launchResults.length; index++) {
+                const outcome = launchResults[index];
+                if (outcome?.status === "rejected") {
+                    launchErrorsByRunId.set(workerSlots[index].runId, outcome.reason instanceof Error
+                        ? outcome.reason.message
+                        : String(outcome.reason));
+                }
+            }
             // Result ingestion is intentionally sequential even though agent launch
             // was parallel. Writing to coverage_matrix.json is not atomic, so
             // concurrent ingest calls would race and corrupt coverage state.
             let batchProgress = false;
+            const batchErrors = [];
             for (const slot of workerSlots) {
                 const parallelEndedAt = new Date().toISOString();
                 let slotStatus = "no_progress";
                 try {
+                    const launchError = launchErrorsByRunId.get(slot.runId);
+                    if (launchError) {
+                        throw new Error(`Worker launch failed: ${launchError}`);
+                    }
                     const auditResults = await readJsonFile(slot.auditResultsPath);
                     const pendingTaskIds = new Set(slot.group.map((t) => t.task_id));
                     const matchedCount = auditResults.filter((r) => pendingTaskIds.has(r.task_id)).length;
                     if (slot.group.length > 0 && matchedCount === 0) {
                         throw new Error("Worker did not emit any audit results for the assigned tasks.");
                     }
-                    const issues = validateAuditResults(auditResults, slot.group);
+                    const issues = validateAuditResults(auditResults, slot.group, {
+                        lineIndex: await buildLineIndexForPaths(root, slot.group.flatMap((task) => task.file_paths)),
+                    });
                     const errors = issues.filter((issue) => issue.severity === "error");
                     const warnings = issues.filter((issue) => issue.severity === "warning");
                     if (warnings.length > 0) {
@@ -582,8 +790,11 @@ async function cmdRunToCompletion(argv) {
                     for (const a of stepResult.artifacts_written)
                         artifactsWritten.add(a);
                 }
-                catch {
+                catch (error) {
                     slotStatus = "failed";
+                    const message = error instanceof Error ? error.message : String(error);
+                    batchErrors.push(`${slot.runId}: ${message}`);
+                    process.stderr.write(`[agent-batch] ${slot.runId} failed: ${message}\n`);
                 }
                 await appendRunLedgerEntry(artifactsDir, {
                     run_id: slot.runId,
@@ -597,6 +808,35 @@ async function cmdRunToCompletion(argv) {
                 });
                 artifactsWritten.add("run-ledger.json");
             }
+            if (batchErrors.length > 0) {
+                const bundleAfter = await loadArtifactBundle(artifactsDir);
+                const blockedState = buildBlockedAuditState({
+                    state: bundleAfter.audit_state ?? deriveAuditState(bundleAfter),
+                    obligationId,
+                    executor: "agent",
+                    blocker: `Parallel worker batch failed for ${batchErrors.length} run(s). ` +
+                        batchErrors.slice(0, 3).join(" | "),
+                });
+                await writeCoreArtifacts(artifactsDir, {
+                    ...bundleAfter,
+                    audit_state: blockedState,
+                });
+                await emitEnvelope({
+                    root,
+                    artifactsDir,
+                    bundle: { ...bundleAfter, audit_state: blockedState },
+                    audit_state: blockedState,
+                    selected_obligation: obligationId,
+                    selected_executor: "agent",
+                    progress_made: anyProgress,
+                    artifacts_written: Array.from(new Set([...artifactsWritten, "audit_state.json"])),
+                    progress_summary: `Parallel worker batch failed for ${batchErrors.length} run(s).\n` +
+                        batchErrors.join("\n"),
+                    next_likely_step: null,
+                    providerName: provider.name,
+                });
+                return;
+            }
             if (!batchProgress) {
                 const bundleAfter = await loadArtifactBundle(artifactsDir);
                 const state = bundleAfter.audit_state ?? deriveAuditState(bundleAfter);
@@ -650,7 +890,7 @@ async function cmdRunToCompletion(argv) {
             external_analyzer_results_path: externalAnalyzerPath,
         };
         const prompt = renderWorkerPrompt(task);
-        await writeWorkerTaskFiles(task, prompt, paths, artifactsDir);
+        await writeWorkerTaskFiles(task, prompt, paths, artifactsDir, pendingAuditTasks);
         if (pendingAuditTasksPath && pendingAuditTasks) {
             await writeJsonFile(pendingAuditTasksPath, pendingAuditTasks);
         }
@@ -686,6 +926,7 @@ async function cmdRunToCompletion(argv) {
                 };
         }
         catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
             workerResult = {
                 contract_version: WORKER_RESULT_CONTRACT_VERSION,
                 run_id: runId,
@@ -694,9 +935,9 @@ async function cmdRunToCompletion(argv) {
                 progress_made: false,
                 selected_executor: preferredExecutor,
                 artifacts_written: [],
-                summary: `Worker launch failed for ${preferredExecutor}.`,
+                summary: `Worker launch failed for ${preferredExecutor}: ${message}`,
                 next_likely_step: decision.selected_obligation,
-                errors: [error instanceof Error ? error.message : String(error)],
+                errors: [message],
             };
             await writeJsonFile(paths.resultPath, workerResult);
         }
@@ -720,6 +961,13 @@ async function cmdRunToCompletion(argv) {
         artifactsWritten.add("run-ledger.json");
         if (externalAnalyzerPath)
             pendingExternalAnalyzerPath = undefined;
+        if (auditResultsPath &&
+            pendingBatchAuditResults[0] === auditResultsPath &&
+            preferredExecutor === "result_ingestion_executor" &&
+            workerResult.status !== "failed" &&
+            workerResult.status !== "blocked") {
+            pendingBatchAuditResults.shift();
+        }
         if (providerAuditResultsPath)
             pendingAuditResultsPath = undefined;
         if (runtimeUpdatesPath)
@@ -728,18 +976,36 @@ async function cmdRunToCompletion(argv) {
             workerResult.status === "blocked" ||
             workerResult.status === "no_progress") {
             const bundleAfter = await loadArtifactBundle(artifactsDir);
-            const state = bundleAfter.audit_state ?? deriveAuditState(bundleAfter);
+            const shouldBlock = workerResult.status === "failed" || workerResult.status === "blocked";
+            const state = shouldBlock
+                ? buildBlockedAuditState({
+                    state: bundleAfter.audit_state ?? deriveAuditState(bundleAfter),
+                    obligationId: workerResult.obligation_id,
+                    executor: workerResult.selected_executor,
+                    blocker: buildWorkerFailureBlocker(workerResult),
+                })
+                : bundleAfter.audit_state ?? deriveAuditState(bundleAfter);
+            if (shouldBlock) {
+                await writeCoreArtifacts(artifactsDir, {
+                    ...bundleAfter,
+                    audit_state: state,
+                });
+            }
             await emitEnvelope({
                 root,
                 artifactsDir,
-                bundle: bundleAfter,
+                bundle: shouldBlock
+                    ? { ...bundleAfter, audit_state: state }
+                    : bundleAfter,
                 audit_state: state,
                 selected_obligation: workerResult.obligation_id,
                 selected_executor: workerResult.selected_executor,
                 progress_made: anyProgress,
-                artifacts_written: Array.from(artifactsWritten),
-                progress_summary: workerResult.summary,
-                next_likely_step: workerResult.next_likely_step,
+                artifacts_written: Array.from(shouldBlock
+                    ? new Set([...artifactsWritten, "audit_state.json"])
+                    : artifactsWritten),
+                progress_summary: buildWorkerFailureBlocker(workerResult),
+                next_likely_step: shouldBlock ? null : workerResult.next_likely_step,
                 providerName: provider.name,
             });
             return;
@@ -748,6 +1014,9 @@ async function cmdRunToCompletion(argv) {
     const bundle = await loadArtifactBundle(artifactsDir);
     const decision = decideNextStep(bundle);
     const state = bundle.audit_state ?? decision.state;
+    if (state.status === "complete") {
+        await clearDispatchFiles(artifactsDir);
+    }
     await emitEnvelope({
         root,
         artifactsDir,
@@ -770,6 +1039,9 @@ async function cmdWorkerRun(argv) {
     const task = await readJsonFile(taskPath);
     let workerResult;
     try {
+        if (looksLikeCliFlag(task.audit_results_path)) {
+            throw new Error(`task.audit_results_path resolved to '${task.audit_results_path}', which looks like a CLI flag instead of a file path.`);
+        }
         if (task.preferred_executor === "agent" && !task.audit_results_path) {
             throw new Error("agent worker-run requires audit_results_path so provider-assisted review can be ingested.");
         }
@@ -783,7 +1055,9 @@ async function cmdWorkerRun(argv) {
             if (pendingTasks.length > 0 && matchedResultCount === 0) {
                 throw new Error("Provider-assisted review did not emit any audit results for the pending audit tasks.");
             }
-            const issues = validateAuditResults(auditResults, pendingTasks);
+            const issues = validateAuditResults(auditResults, pendingTasks, {
+                lineIndex: await buildLineIndexForPaths(task.repo_root, pendingTasks.flatMap((item) => item.file_paths)),
+            });
             const errors = issues.filter((issue) => issue.severity === "error");
             const warnings = issues.filter((issue) => issue.severity === "warning");
             if (warnings.length > 0) {
@@ -792,8 +1066,7 @@ async function cmdWorkerRun(argv) {
                     "\n");
             }
             if (errors.length > 0) {
-                throw new Error(`audit-results validation failed with ${errors.length} error(s):\n` +
-                    formatAuditResultIssues(errors));
+                throw new Error(formatAuditResultValidationError(errors));
             }
         }
         const preferredExecutor = task.preferred_executor === "agent"
@@ -829,7 +1102,7 @@ async function cmdWorkerRun(argv) {
             progress_made: false,
             selected_executor: task.preferred_executor,
             artifacts_written: [],
-            summary: `Worker failed for executor ${task.preferred_executor}.`,
+            summary: `Worker failed for executor ${task.preferred_executor}: ${error instanceof Error ? error.message : String(error)}`,
             next_likely_step: task.obligation_id,
             errors: [error instanceof Error ? error.message : String(error)],
         };
@@ -882,6 +1155,24 @@ async function cmdPlan(argv) {
 }
 async function cmdIngestResults(argv) {
     const artifactsDir = getArtifactsDir(argv);
+    const batchResultsDir = getBatchResultsDir(argv);
+    if (batchResultsDir && getFlag(argv, "--results")) {
+        throw new Error("Use either --results <file> or --batch-results <dir>, not both.");
+    }
+    if (batchResultsDir) {
+        const result = await ingestBatchAuditResults({
+            root: getRootDir(argv),
+            artifactsDir,
+            batchDir: batchResultsDir,
+        });
+        console.log(JSON.stringify({
+            artifacts_dir: artifactsDir,
+            imported_files: result.batchFiles,
+            selected_executor: result.selected_executor,
+            progress_summary: result.progress_summary,
+        }, null, 2));
+        return;
+    }
     const result = await runAuditStep({
         root: getRootDir(argv),
         artifactsDir,
@@ -894,6 +1185,37 @@ async function cmdIngestResults(argv) {
         progress_summary: result.progress_summary,
     }, null, 2));
 }
+async function cmdExplainTask(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const taskId = getFlag(argv, "--task-id") ?? argv[3];
+    if (!taskId) {
+        throw new Error("explain-task requires <task_id> or --task-id <task_id>");
+    }
+    const bundle = await loadArtifactBundle(artifactsDir);
+    const task = [...(bundle.audit_tasks ?? []), ...(bundle.requeue_tasks ?? [])].find((item) => item.task_id === taskId);
+    if (!task) {
+        throw new Error(`Unknown task_id '${taskId}'.`);
+    }
+    const coverageEntries = (bundle.coverage_matrix?.files ?? [])
+        .filter((file) => task.file_paths.includes(file.path))
+        .sort((a, b) => a.path.localeCompare(b.path));
+    const matchingResults = (bundle.audit_results ?? []).filter((result) => result.task_id === task.task_id);
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        task_id: task.task_id,
+        task,
+        file_count: task.file_paths.length,
+        coverage_entries: coverageEntries,
+        pending_coverage: coverageEntries
+            .map((file) => ({
+            path: file.path,
+            missing_lenses: file.required_lenses.filter((lens) => !file.completed_lenses.includes(lens)),
+        }))
+            .filter((file) => file.missing_lenses.length > 0),
+        matching_result_count: matchingResults.length,
+        matching_finding_ids: matchingResults.flatMap((result) => result.findings.map((finding) => finding.id)),
+    }, null, 2));
+}
 async function cmdUpdateRuntimeValidation(argv) {
     const artifactsDir = getArtifactsDir(argv);
     const result = await runAuditStep({
@@ -942,6 +1264,31 @@ async function cmdValidate(argv) {
     }, null, 2));
     process.exitCode = issues.length > 0 ? 1 : 0;
 }
+async function cmdValidateResults(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const resultsPath = getFlag(argv, "--results");
+    if (!resultsPath) {
+        throw new Error("validate-results requires --results <file>");
+    }
+    const bundle = await loadArtifactBundle(artifactsDir);
+    const lineIndex = bundle.repo_manifest
+        ? await buildLineIndex(getRootDir(argv), bundle.repo_manifest)
+        : undefined;
+    const auditResults = await readJsonFile(resultsPath);
+    const issues = validateAuditResults(auditResults, bundle.audit_tasks ?? [], {
+        lineIndex,
+    });
+    const errors = issues.filter((issue) => issue.severity === "error");
+    const warnings = issues.filter((issue) => issue.severity === "warning");
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        results_path: resolve(resultsPath),
+        warning_count: warnings.length,
+        error_count: errors.length,
+        issues,
+    }, null, 2));
+    process.exitCode = errors.length > 0 ? 1 : 0;
+}
 async function cmdRequeue(argv) {
     const artifactsDir = getArtifactsDir(argv);
     const bundle = await loadArtifactBundle(artifactsDir);
@@ -963,6 +1310,9 @@ async function cmdSynthesize(argv) {
         progress_summary: result.progress_summary,
     }, null, 2));
 }
+async function cmdMcp(argv) {
+    await runAuditCodeMcpServer(argv.slice(3));
+}
 async function main(argv) {
     const command = argv[2] ?? "sample-run";
     switch (command) {
@@ -990,21 +1340,30 @@ async function main(argv) {
         case "ingest-results":
             await cmdIngestResults(argv);
             return;
+        case "explain-task":
+            await cmdExplainTask(argv);
+            return;
         case "update-runtime-validation":
             await cmdUpdateRuntimeValidation(argv);
             return;
         case "validate":
             await cmdValidate(argv);
             return;
+        case "validate-results":
+            await cmdValidateResults(argv);
+            return;
         case "requeue":
             await cmdRequeue(argv);
             return;
         case "synthesize":
             await cmdSynthesize(argv);
             return;
+        case "mcp":
+            await cmdMcp(argv);
+            return;
         default:
             console.error(`Unknown command: ${command}`);
-            console.error("Available commands: sample-run, advance-audit, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, update-runtime-validation, validate, requeue, synthesize");
+            console.error("Available commands: sample-run, advance-audit, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, mcp");
             process.exitCode = 1;
     }
 }