auditor-lambda 0.2.4 → 0.2.6

package/README.md

@@ -102,6 +102,18 @@ audit-code validate
 
 That check now covers the artifact bundle plus `session-config.json` and explicit provider readiness.
 
+For native batch ingestion of multiple result files:
+
+```bash
+audit-code --batch-results /path/to/audit-results-dir
+```
+
+For task-to-coverage inspection without reverse-engineering multiple artifacts:
+
+```bash
+audit-code explain-task <task_id>
+```
+
 The backend wrapper response schema is `schemas/audit-code-v1alpha1.schema.json`.
 
 ## Backend Provider Modes

package/audit-code-wrapper-lib.mjs

@@ -234,13 +234,14 @@ async function ensureBuilt() {
 
 function printHelp({ usageName, preferredEntrypoint }) {
   const lines = [
-    `Usage: node ${usageName} [--single-step] [--root PATH] [--artifacts-dir PATH] [--results FILE] [--updates FILE] [--external-analyzer-results FILE]`,
+    `Usage: node ${usageName} [--single-step] [--root PATH] [--artifacts-dir PATH] [--results FILE] [--batch-results DIR] [--updates FILE] [--external-analyzer-results FILE] [--timeout MS]`,
     '',
     'Helper commands:',
     '- prompt-path prints the absolute path to the canonical /audit-code prompt asset',
     '- install bootstraps /audit-code into supported repo-local host surfaces',
     '- install-host --host copilot keeps the narrower Copilot-focused install path available',
     '- validate checks the current artifact bundle plus session-config/provider readiness and exits non-zero when issues exist',
+    '- explain-task <task_id> prints the resolved file coverage and current status for a task id',
     '',
     'Primary usage:',
     '- from the repository root, run the wrapper with no arguments',
@@ -903,6 +904,11 @@ export async function runAuditCodeWrapper({
     return;
   }
 
+  if (argv[0] === 'explain-task') {
+    await runDistCommand('explain-task', argv.slice(1));
+    return;
+  }
+
   const wrapperArgs = [...argv];
   if (defaultSingleStep && !hasFlag(wrapperArgs, '--single-step')) {
     wrapperArgs.push('--single-step');

package/dist/cli.js

@@ -1,6 +1,6 @@
-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";
@@ -50,6 +50,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 +82,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 +216,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 +265,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,7 +401,9 @@ 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 }],
+            reviewed_ranges: [
+                { path: "src/api/auth.ts", start: 1, end: 100, line_count: 100 },
+            ],
             findings: [],
             notes: ["Sample result ingestion path."],
             requires_followup: false,
@@ -322,6 +449,34 @@ 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,
+        });
+        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 cleanupIntermediateArtifacts(artifactsDir);
+        }
+        return;
+    }
     const externalAnalyzerPath = getFlag(argv, "--external-analyzer-results");
     const result = await runAuditStep({
         root,
@@ -358,10 +513,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 +573,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 +624,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,
@@ -527,12 +694,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 +711,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 +765,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 +783,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 +865,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 +901,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 +910,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 +936,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 +951,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;
@@ -770,6 +1011,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 +1027,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 +1038,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 +1074,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 +1127,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 +1157,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({
@@ -990,6 +1284,9 @@ 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;
@@ -1004,7 +1301,7 @@ async function main(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, requeue, synthesize");
             process.exitCode = 1;
     }
 }

package/dist/io/runArtifacts.d.ts

@@ -1,3 +1,4 @@
+import type { AuditTask } from "../types.js";
 import type { WorkerTask } from "../types/workerSession.js";
 export interface RunPaths {
     runDir: string;
@@ -11,4 +12,4 @@ export interface RunPaths {
 export declare function buildRunId(obligationId: string | null, index: number): string;
 export declare function getRunPaths(artifactsDir: string, runId: string): RunPaths;
 export declare function ensureSupervisorDirs(artifactsDir: string): Promise<void>;
-export declare function writeWorkerTaskFiles(task: WorkerTask, prompt: string, paths: RunPaths, artifactsDir: string): Promise<void>;
+export declare function writeWorkerTaskFiles(task: WorkerTask, prompt: string, paths: RunPaths, artifactsDir: string, currentTasks?: AuditTask[]): Promise<void>;

package/dist/io/runArtifacts.js

@@ -24,7 +24,7 @@ export async function ensureSupervisorDirs(artifactsDir) {
     await mkdir(join(artifactsDir, "worker-logs"), { recursive: true });
     await mkdir(join(artifactsDir, "runs"), { recursive: true });
 }
-export async function writeWorkerTaskFiles(task, prompt, paths, artifactsDir) {
+export async function writeWorkerTaskFiles(task, prompt, paths, artifactsDir, currentTasks) {
     await mkdir(paths.runDir, { recursive: true });
     await writeJsonFile(paths.taskPath, task);
     await writeFile(paths.promptPath, prompt, "utf8");
@@ -34,4 +34,5 @@ export async function writeWorkerTaskFiles(task, prompt, paths, artifactsDir) {
     });
     await writeJsonFile(join(artifactsDir, "dispatch", "current-task.json"), task);
     await writeFile(join(artifactsDir, "dispatch", "current-prompt.md"), prompt, "utf8");
+    await writeJsonFile(join(artifactsDir, "dispatch", "current-tasks.json"), currentTasks ?? []);
 }

package/dist/orchestrator/flowRequeue.d.ts

@@ -1,5 +1,5 @@
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
-import type { AuditTask } from "../types.js";
+import type { AuditTask, CoverageMatrix } from "../types.js";
 import type { FlowCoverageManifest } from "../types/flowCoverage.js";
 import type { CriticalFlowManifest } from "../types/flows.js";
-export declare function buildFlowRequeueTasks(criticalFlows: CriticalFlowManifest, flowCoverage: FlowCoverageManifest, externalAnalyzerResults?: ExternalAnalyzerResults): AuditTask[];
+export declare function buildFlowRequeueTasks(criticalFlows: CriticalFlowManifest, flowCoverage: FlowCoverageManifest, coverageMatrix: CoverageMatrix, externalAnalyzerResults?: ExternalAnalyzerResults): AuditTask[];