auditor-lambda 0.2.18 → 0.3.1

package/audit-code-wrapper-lib.mjs

@@ -260,6 +260,9 @@ function printHelp({ usageName, preferredEntrypoint }) {
     '- validate checks the current artifact bundle plus session-config/provider readiness and exits non-zero when issues exist',
     '- validate-results --results FILE validates AuditResult payloads against the active task manifest without ingesting them',
     '- explain-task <task_id> prints the resolved file coverage and current status for a task id',
+    '- prepare-dispatch --run-id <id> [--artifacts-dir <dir>] creates per-task prompt files and dispatch-plan.json for parallel subagent dispatch',
+    '- merge-and-ingest --run-id <id> [--root <dir>] [--artifacts-dir <dir>] merges per-task results and ingests them into the coverage matrix',
+    '- validate-result --run-id <id> --task-id <id> [--artifacts-dir <dir>] validates a single task result against the schema and line counts',
     '',
     'Primary usage:',
     '- from the repository root, run the wrapper with no arguments',
@@ -2195,6 +2198,21 @@ export async function runAuditCodeWrapper({
     return;
   }
 
+  if (argv[0] === 'prepare-dispatch') {
+    await runDistCommand('prepare-dispatch', argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'validate-result') {
+    await runDistCommand('validate-result', argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'merge-and-ingest') {
+    await runDistCommand('merge-and-ingest', argv.slice(1), { ensureArtifactsDir: true });
+    return;
+  }
+
   const wrapperArgs = [...argv];
   if (defaultSingleStep && !hasFlag(wrapperArgs, '--single-step')) {
     wrapperArgs.push('--single-step');

package/dispatch/merge-results.mjs

@@ -5,17 +5,21 @@ import { validateResult } from "./validate.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PROJECT_ROOT = resolve(__dirname, "..");
 
 // Parse --run-id
 const runIdIdx = process.argv.indexOf("--run-id");
 if (runIdIdx === -1 || !process.argv[runIdIdx + 1]) {
-  console.error("Usage: node dispatch/merge-results.mjs --run-id <run_id>");
+  console.error("Usage: node dispatch/merge-results.mjs --run-id <run_id> [--artifacts-dir <dir>]");
   process.exit(1);
 }
 const run_id = process.argv[runIdIdx + 1];
 
-const artifactsDir = join(PROJECT_ROOT, ".audit-artifacts");
+// Parse --artifacts-dir (default: CWD/.audit-artifacts)
+const artifactsDirIdx = process.argv.indexOf("--artifacts-dir");
+const artifactsDir = artifactsDirIdx !== -1 && process.argv[artifactsDirIdx + 1]
+  ? resolve(process.argv[artifactsDirIdx + 1])
+  : join(process.cwd(), ".audit-artifacts");
+
 const taskResultsDir = join(artifactsDir, "runs", run_id, "task-results");
 const auditResultsPath = join(artifactsDir, "runs", run_id, "audit-results.json");
 const failedTasksPath = join(artifactsDir, "runs", run_id, "failed-tasks.json");
@@ -69,9 +73,9 @@ writeFileSync(auditResultsPath, JSON.stringify(passing, null, 2));
 
 if (failing.length > 0) {
   writeFileSync(failedTasksPath, JSON.stringify(failing, null, 2));
-  console.warn(`${failing.length} task(s) failed validation and were excluded:`);
+  process.stderr.write(`${failing.length} task(s) failed validation and were excluded:\n`);
   for (const f of failing) {
-    console.warn(`  ✗ ${f.task_id}: ${f.errors[0]}`);
+    process.stderr.write(`  ✗ ${f.task_id}: ${f.errors[0]}\n`);
   }
 }
 

package/dispatch/prepare-dispatch.mjs

@@ -1,143 +1,131 @@
 import { dirname, resolve, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PROJECT_ROOT = resolve(__dirname, "..");
+const PACKAGE_ROOT = resolve(__dirname, "..");
 
 // Parse --run-id
 const runIdIdx = process.argv.indexOf("--run-id");
 if (runIdIdx === -1 || !process.argv[runIdIdx + 1]) {
-  console.error("Usage: node dispatch/prepare-dispatch.mjs --run-id <run_id>");
+  console.error("Usage: node dispatch/prepare-dispatch.mjs --run-id <run_id> [--artifacts-dir <dir>]");
   process.exit(1);
 }
 const run_id = process.argv[runIdIdx + 1];
 
-const artifactsDir = join(PROJECT_ROOT, ".audit-artifacts");
+// Parse --artifacts-dir (default: CWD/.audit-artifacts)
+const artifactsDirIdx = process.argv.indexOf("--artifacts-dir");
+const artifactsDir = artifactsDirIdx !== -1 && process.argv[artifactsDirIdx + 1]
+  ? resolve(process.argv[artifactsDirIdx + 1])
+  : join(process.cwd(), ".audit-artifacts");
+
 const runDir = join(artifactsDir, "runs", run_id);
 const tasksPath = join(runDir, "pending-audit-tasks.json");
+const taskResultsDir = join(runDir, "task-results");
 const dispatchPlanPath = join(runDir, "dispatch-plan.json");
 
-if (!existsSync(tasksPath)) {
-  console.error(`File not found: ${tasksPath}`);
+let tasks;
+try {
+  tasks = JSON.parse(readFileSync(tasksPath, "utf8"));
+} catch (e) {
+  console.error(`Cannot read ${tasksPath}: ${e.message}`);
   process.exit(1);
 }
 
-const tasks = JSON.parse(readFileSync(tasksPath, "utf8"));
 const lensDefinitions = JSON.parse(
   readFileSync(join(__dirname, "lens-definitions.json"), "utf8")
 );
-const auditResultSchema = JSON.parse(
-  readFileSync(join(PROJECT_ROOT, "schemas", "audit_result.schema.json"), "utf8")
-);
-const findingSchema = JSON.parse(
-  readFileSync(join(PROJECT_ROOT, "schemas", "finding.schema.json"), "utf8")
-);
 
-function buildPrompt(task, lensDef, auditResultSchema, findingSchema, outputPath, runId, artifactsDir) {
-  const fallback = {
-    task_id: task.task_id,
-    unit_id: task.unit_id,
-    pass_id: task.pass_id,
-    lens: task.lens,
-    file_coverage: task.file_paths.map(p => ({ path: p, total_lines: task.file_line_counts[p] })),
-    findings: [],
-    notes: ["Validation failed after 3 attempts — empty result written as fallback."]
-  };
+mkdirSync(taskResultsDir, { recursive: true });
 
-  return `You are a code auditor. Perform a bounded audit of the files listed below under the specified lens.
+function buildPrompt(task, lensDef, outputPath, runId, artifactsDir) {
+  const fileList = task.file_paths.map(p => {
+    const lines = task.file_line_counts?.[p] ?? 0;
+    return `- ${p} (${lines} lines)`;
+  }).join("\n");
 
-## Task metadata
-${JSON.stringify(task, null, 2)}
+  return `You are a code auditor. Review the files below under the specified lens.
 
-## Files to read
-Read each path in task.file_paths using your Read tool. The repo root is the current working directory — paths are repo-relative (e.g. "src/foo.ts").
+## Task
+task_id: ${task.task_id}
+unit_id: ${task.unit_id}
+pass_id: ${task.pass_id}
+lens: ${task.lens}
 
-file_line_counts gives the expected total line count for each file. Use those exact values for file_coverage[].total_lines in your result.
+## Files to read
+Use your Read tool. Paths are repo-relative from the current working directory.
+${fileList}
 
 ## Lens: ${task.lens}
-${lensDef.description}
-
-Do NOT report: ${lensDef.do_not_report}
-
-## Output format
-Write your result as a single JSON **object** (not an array) to this exact path:
-  ${outputPath}
-
-The result must conform to the following schema:
-
-### audit_result.schema.json
-${JSON.stringify(auditResultSchema, null, 2)}
-
-### finding.schema.json
-${JSON.stringify(findingSchema, null, 2)}
-
-## Hard constraints (violations will fail validation)
-1. NEVER set line_end higher than the file's actual line count.
-   Use file_line_counts as your reference. If in doubt, leave line_end omitted.
-2. Every finding MUST have ALL required fields:
-   id, title, category, severity, confidence, lens, summary, affected_files, evidence
-3. lens on every finding must be exactly "${task.lens}"
-4. No fields outside the schema. Forbidden: "recommendation", "tags", "description" (use "summary").
-5. evidence[] must contain at least one specific file:line reference.
-   Format: "path/to/file.ts:42 - brief description of what you see there"
-6. affected_files[] entries are OBJECTS with a "path" key — NOT plain strings.
-   Example: {"path": "src/foo.ts", "line_start": 10, "line_end": 20, "symbol": "myFunc"}
-7. Only reference file paths that appear in this task's file_paths.
-8. findings: [] is correct when you genuinely find nothing. Do not invent findings.
-
-## Validation step (required)
+${lensDef?.description ?? task.lens}
+
+Do NOT report: ${lensDef?.do_not_report ?? "N/A"}
+
+## Output
+Write a single JSON object to: ${outputPath}
+
+Required fields:
+  task_id       copy from task metadata above
+  unit_id       copy from task metadata above
+  pass_id       copy from task metadata above
+  lens          copy from task metadata above
+  file_coverage [{path, total_lines}] — one entry per file; use the line counts listed above
+  findings      [] or array of finding objects (see below)
+
+Each finding object (omit optional fields if not applicable):
+  id            unique ID, e.g. "SEC-001"
+  title         short title
+  category      correctness|architecture|maintainability|security|reliability|performance|data_integrity|tests|operability|config_deployment
+  severity      critical|high|medium|low|info
+  confidence    high|medium|low
+  lens          "${task.lens}" — must match task lens exactly
+  summary       1–2 sentence description
+  affected_files  [{path, line_start?, line_end?, symbol?}] — objects, not strings; min 1 entry
+  evidence     ["path/to/file.ts:42 — description of what you see there"] — min 1 entry
+
+Constraints:
+1. line_end must not exceed the file's actual line count (use the counts listed above)
+2. affected_files entries are OBJECTS with a "path" key — NOT plain strings
+3. Only reference files from the list above
+4. findings: [] is correct when you find nothing genuine — do not invent findings
+
+## Validate
 After writing your result, run:
-  node dispatch/validate-result.mjs ${runId} ${task.task_id}
-
-- If it exits 0: you are done. Stop.
-- If it exits non-zero: read the error output, fix the JSON, rewrite the file, run again.
-- Repeat up to 3 times.
+  audit-code validate-result --run-id ${runId} --task-id ${task.task_id} --artifacts-dir ${artifactsDir}
 
-If you cannot produce a valid result after 3 attempts, write this fallback (substituting real values):
-${JSON.stringify(fallback, null, 2)}
-
-Then validate the fallback passes before finishing.`;
+Exit 0 means valid. Non-zero: read the errors, fix your JSON, rewrite the file, run again. Retry up to 3 times.`;
 }
 
-mkdirSync(join(runDir, "task-results"), { recursive: true });
-
 const plan = [];
 let largestTask = null;
 let largestLines = 0;
 
 for (const task of tasks) {
   const sanitizedId = task.task_id.replace(/[^a-zA-Z0-9_-]/g, "_");
-  const outputPath = join(runDir, "task-results", sanitizedId + ".json");
+  const outputPath = join(taskResultsDir, sanitizedId + ".json");
+  const promptPath = join(taskResultsDir, sanitizedId + ".prompt.md");
   const lensDef = lensDefinitions[task.lens];
 
   if (!lensDef) {
-    console.warn(`Warning: no lens definition for '${task.lens}' (task ${task.task_id})`);
+    process.stderr.write(`Warning: no lens definition for '${task.lens}' (task ${task.task_id})\n`);
   }
 
-  const totalFileLines = Object.values(task.file_line_counts).reduce((a, b) => a + b, 0);
-  const description = `Audit ${task.unit_id} (${task.file_paths.length} file(s), ~${totalFileLines} lines) — ${task.lens} lens`;
-  const prompt = buildPrompt(
-    task,
-    lensDef ?? { description: task.lens, do_not_report: "N/A" },
-    auditResultSchema,
-    findingSchema,
-    outputPath,
-    run_id,
-    artifactsDir
-  );
+  const totalFileLines = Object.values(task.file_line_counts ?? {}).reduce((a, b) => a + b, 0);
 
   if (totalFileLines > largestLines) {
     largestLines = totalFileLines;
     largestTask = task.task_id;
   }
-
   if (totalFileLines > 1500) {
-    console.warn(`Warning: large task ${task.task_id} (~${totalFileLines} lines) may hit quota limits`);
+    process.stderr.write(`Warning: large task ${task.task_id} (~${totalFileLines} lines) may hit quota limits\n`);
   }
 
-  plan.push({ task_id: task.task_id, description, output_path: outputPath, prompt });
+  const prompt = buildPrompt(task, lensDef, outputPath, run_id, artifactsDir);
+  writeFileSync(promptPath, prompt, "utf8");
+
+  const description = `Audit ${task.unit_id} (${task.file_paths.length} file(s), ~${totalFileLines} lines) — ${task.lens} lens`;
+  plan.push({ task_id: task.task_id, description, output_path: outputPath, prompt_path: promptPath });
 }
 
 writeFileSync(dispatchPlanPath, JSON.stringify(plan, null, 2));
@@ -146,10 +134,3 @@ console.log(`Wrote dispatch-plan.json — ${plan.length} tasks ready for dispatc
 if (largestTask) {
   console.log(`Largest task: ${largestTask} (~${largestLines} lines)`);
 }
-console.log("");
-console.log("--- ORCHESTRATOR INSTRUCTIONS ---");
-console.log("Read dispatch-plan.json. For each entry, fire one Agent call with:");
-console.log("  description: <entry.description>");
-console.log("  prompt: <entry.prompt>");
-console.log(`Fire all ${plan.length} calls in a single message for parallel execution.`);
-console.log(`When all complete, run: node dispatch/merge-results.mjs --run-id ${run_id}`);

package/dispatch/validate-result.mjs

@@ -5,27 +5,31 @@ import { validateResult } from "./validate.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PROJECT_ROOT = resolve(__dirname, "..");
 
-const run_id = process.argv[2];
-const task_id = process.argv[3];
+// Support both named flags and legacy positional args:
+//   Named:    --run-id <id> --task-id <id> [--artifacts-dir <dir>]
+//   Positional (legacy): <run_id> <task_id>
+const runIdFlagIdx = process.argv.indexOf("--run-id");
+const taskIdFlagIdx = process.argv.indexOf("--task-id");
+const artifactsDirIdx = process.argv.indexOf("--artifacts-dir");
+
+const run_id = runIdFlagIdx !== -1
+  ? process.argv[runIdFlagIdx + 1]
+  : process.argv[2];
+
+const task_id = taskIdFlagIdx !== -1
+  ? process.argv[taskIdFlagIdx + 1]
+  : process.argv[3];
 
 if (!run_id || !task_id) {
-  console.error("Usage: node dispatch/validate-result.mjs <run_id> <task_id>");
+  console.error("Usage: node dispatch/validate-result.mjs --run-id <run_id> --task-id <task_id> [--artifacts-dir <dir>]");
   process.exit(1);
 }
 
-// Locate artifacts_dir
-let artifactsDir = join(PROJECT_ROOT, ".audit-artifacts");
-const sessionConfigPath = join(artifactsDir, "session-config.json");
-if (existsSync(sessionConfigPath)) {
-  try {
-    const cfg = JSON.parse(readFileSync(sessionConfigPath, "utf8"));
-    if (cfg.artifacts_dir) artifactsDir = cfg.artifacts_dir;
-  } catch {
-    // use default
-  }
-}
+// Artifacts dir: explicit flag > CWD default
+const artifactsDir = artifactsDirIdx !== -1 && process.argv[artifactsDirIdx + 1]
+  ? resolve(process.argv[artifactsDirIdx + 1])
+  : join(process.cwd(), ".audit-artifacts");
 
 const sanitized = task_id.replace(/[^a-zA-Z0-9_-]/g, "_");
 const resultPath = join(artifactsDir, "runs", run_id, "task-results", sanitized + ".json");

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readdir, rename } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -28,6 +28,7 @@ import { clearDispatchFiles, buildRunId, ensureSupervisorDirs, getRunPaths, writ
 import { renderWorkerPrompt } from "./prompts/renderWorkerPrompt.js";
 import { LOCAL_SUBPROCESS_PROVIDER_NAME } from "./providers/constants.js";
 import { runAuditCodeMcpServer } from "./mcp/server.js";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const ADVANCE_AUDIT_CONTRACT_VERSION = "audit-code/v1alpha1";
 const WORKER_RESULT_CONTRACT_VERSION = "audit-code-worker-result/v1alpha1";
 const DIRECT_CLI_DEFAULTS = {
@@ -111,7 +112,7 @@ function getExplicitProvider(argv) {
     return getFlag(argv, "--provider");
 }
 function resolveRunProviderName(argv, sessionConfig) {
-    return resolveFreshSessionProviderName(getExplicitProvider(argv) ?? "auto", sessionConfig);
+    return resolveFreshSessionProviderName(getExplicitProvider(argv), sessionConfig);
 }
 function chunkArray(arr, size) {
     const chunkSize = normalizePositiveInteger(size);
@@ -170,8 +171,9 @@ async function emitEnvelope(params) {
 }
 function buildManualReviewBlocker(providerName) {
     return providerName === LOCAL_SUBPROCESS_PROVIDER_NAME
-        ? "Automatic backend steps are exhausted. Remaining semantic review now belongs to the active conversation agent. Review the dispatched files, write structured audit results to the run-scoped audit_results_path, and execute the worker_command from current-task.json exactly as written. If you intentionally want a backend bridge instead, re-run audit-code with --provider auto, --provider claude-code, --provider opencode, --provider subprocess-template, or --provider vscode-task."
-        : "Automatic work is exhausted. Remaining audit tasks require explicit audit results or an interactive provider.";
+        ? "Ready for LLM review. Dispatched task files are in .audit-artifacts/dispatch/. " +
+            "Review the code, write audit results to the specified path, then run the worker_command to continue."
+        : "Audit blocked: waiting for manual audit results or interactive provider configuration.";
 }
 function shouldRunInlineExecutor(selectedExecutor) {
     return selectedExecutor !== null && selectedExecutor !== "agent";
@@ -646,7 +648,7 @@ async function cmdRunToCompletion(argv) {
         throw error;
     }
     const explicitProvider = getExplicitProvider(argv);
-    const provider = createFreshSessionProvider(explicitProvider ?? "auto", sessionConfig);
+    const provider = createFreshSessionProvider(explicitProvider, sessionConfig);
     const uiMode = getUiMode(argv, sessionConfig.ui_mode ?? "headless");
     const maxRuns = getMaxRuns(argv);
     const agentBatchSize = getAgentBatchSize(argv, sessionConfig);
@@ -1393,6 +1395,284 @@ async function cmdWorkerRun(argv) {
         process.exitCode = 1;
     }
 }
+async function cmdPrepareDispatch(argv) {
+    const runId = getFlag(argv, "--run-id");
+    if (!runId)
+        throw new Error("prepare-dispatch requires --run-id <run_id>");
+    const artifactsDir = getArtifactsDir(argv);
+    const runDir = join(artifactsDir, "runs", runId);
+    const tasksPath = join(runDir, "pending-audit-tasks.json");
+    const taskResultsDir = join(runDir, "task-results");
+    const dispatchPlanPath = join(runDir, "dispatch-plan.json");
+    const tasks = await readJsonFile(tasksPath);
+    const lensDefsPath = join(packageRoot, "dispatch", "lens-definitions.json");
+    const lensDefs = await readJsonFile(lensDefsPath);
+    await mkdir(taskResultsDir, { recursive: true });
+    const plan = [];
+    let largestTask = null;
+    let largestLines = 0;
+    for (const task of tasks) {
+        const sanitized = task.task_id.replace(/[^a-zA-Z0-9_-]/g, "_");
+        const outputPath = join(taskResultsDir, `${sanitized}.json`);
+        const promptPath = join(taskResultsDir, `${sanitized}.prompt.md`);
+        const lensDef = lensDefs[task.lens];
+        if (!lensDef) {
+            process.stderr.write(`Warning: no lens definition for '${task.lens}' (task ${task.task_id})\n`);
+        }
+        const totalLines = Object.values(task.file_line_counts ?? {}).reduce((a, b) => a + b, 0);
+        if (totalLines > largestLines) {
+            largestLines = totalLines;
+            largestTask = task.task_id;
+        }
+        if (totalLines > 1500) {
+            process.stderr.write(`Warning: large task ${task.task_id} (~${totalLines} lines) may hit quota limits\n`);
+        }
+        const fileList = task.file_paths.map(p => {
+            const lines = task.file_line_counts?.[p] ?? 0;
+            return `- ${p} (${lines} lines)`;
+        }).join("\n");
+        const prompt = [
+            "You are a code auditor. Review the files below under the specified lens.",
+            "",
+            "## Task",
+            `task_id: ${task.task_id}`,
+            `unit_id: ${task.unit_id}`,
+            `pass_id: ${task.pass_id}`,
+            `lens: ${task.lens}`,
+            "",
+            "## Files to read",
+            "Use your Read tool. Paths are repo-relative from the current working directory.",
+            fileList,
+            "",
+            `## Lens: ${task.lens}`,
+            lensDef?.description ?? task.lens,
+            "",
+            `Do NOT report: ${lensDef?.do_not_report ?? "N/A"}`,
+            "",
+            "## Output",
+            `Write a single JSON object to: ${outputPath}`,
+            "",
+            "Required fields:",
+            "  task_id       copy from task metadata above",
+            "  unit_id       copy from task metadata above",
+            "  pass_id       copy from task metadata above",
+            "  lens          copy from task metadata above",
+            "  file_coverage [{path, total_lines}] — one entry per file; use the line counts listed above",
+            "  findings      [] or array of finding objects (see below)",
+            "",
+            "Each finding object:",
+            "  id            unique ID, e.g. \"COR-001\"",
+            "  title         short title",
+            "  category      correctness|architecture|maintainability|security|reliability|performance|data_integrity|tests|operability|config_deployment",
+            "  severity      critical|high|medium|low|info",
+            "  confidence    high|medium|low",
+            `  lens          "${task.lens}" — must match task lens exactly`,
+            "  summary       1–2 sentence description",
+            "  affected_files  [{path, line_start?, line_end?, symbol?}] — objects, not strings; min 1 entry",
+            "  evidence     [\"path/to/file.ts:42 — description of what you see there\"] — min 1 entry",
+            "",
+            "Constraints:",
+            "1. line_end must not exceed the file's actual line count (use counts listed above)",
+            "2. affected_files entries are OBJECTS with a \"path\" key — NOT plain strings",
+            "3. Only reference files from the list above",
+            "4. findings: [] is correct when you find nothing genuine",
+            "",
+            "## Validate",
+            "After writing your result, run:",
+            `  "${process.execPath}" "${join(packageRoot, "audit-code.mjs")}" validate-result --run-id ${runId} --task-id ${task.task_id} --artifacts-dir "${artifactsDir}"`,
+            "",
+            "Exit 0 means valid. Non-zero: read the errors, fix your JSON, rewrite the file, run again. Retry up to 3 times.",
+        ].join("\n");
+        await writeFile(promptPath, prompt, "utf8");
+        const description = `Audit ${task.unit_id} (${task.file_paths.length} file(s), ~${totalLines} lines) — ${task.lens} lens`;
+        plan.push({ task_id: task.task_id, description, output_path: outputPath, prompt_path: promptPath });
+    }
+    await writeJsonFile(dispatchPlanPath, plan);
+    console.log(`Wrote dispatch-plan.json — ${plan.length} tasks ready for dispatch`);
+    if (largestTask)
+        console.log(`Largest task: ${largestTask} (~${largestLines} lines)`);
+}
+async function cmdMergeAndIngest(argv) {
+    const runId = getFlag(argv, "--run-id");
+    if (!runId)
+        throw new Error("merge-and-ingest requires --run-id <run_id>");
+    const artifactsDir = getArtifactsDir(argv);
+    const runDir = join(artifactsDir, "runs", runId);
+    const taskResultsDir = join(runDir, "task-results");
+    const auditResultsPath = join(runDir, "audit-results.json");
+    const taskPath = join(runDir, "task.json");
+    // Merge: collect all per-task result files (skip .prompt.md files)
+    let files;
+    try {
+        files = (await readdir(taskResultsDir))
+            .filter(f => f.endsWith(".json"))
+            .sort();
+    }
+    catch {
+        files = [];
+    }
+    const passing = [];
+    const failing = [];
+    for (const filename of files) {
+        const filePath = join(taskResultsDir, filename);
+        let obj;
+        try {
+            obj = JSON.parse(await readFile(filePath, "utf8"));
+        }
+        catch (e) {
+            failing.push({ task_id: filename, errors: [`Invalid JSON: ${e.message}`] });
+            continue;
+        }
+        const r = obj;
+        const missing = ["task_id", "unit_id", "pass_id", "lens", "file_coverage", "findings"].filter(f => !(f in r));
+        if (missing.length > 0) {
+            failing.push({ task_id: String(r.task_id ?? filename), errors: [`Missing required fields: ${missing.join(", ")}`] });
+        }
+        else {
+            passing.push(obj);
+        }
+    }
+    await writeJsonFile(auditResultsPath, passing);
+    if (failing.length > 0) {
+        await writeJsonFile(join(runDir, "failed-tasks.json"), failing);
+        process.stderr.write(`${failing.length} task(s) excluded — see ${join(runDir, "failed-tasks.json")}\n`);
+    }
+    process.stderr.write(`✓ ${passing.length}/${files.length} results merged → ${auditResultsPath}\n`);
+    // Ingest: run worker-run logic against the merged results file
+    await cmdWorkerRun([argv[0], argv[1], "worker-run", "--task", taskPath, "--artifacts-dir", artifactsDir]);
+}
+const VALID_LENSES_SET = new Set([
+    "correctness", "architecture", "maintainability", "security", "reliability",
+    "performance", "data_integrity", "tests", "operability", "config_deployment",
+]);
+const VALID_SEVERITIES_SET = new Set(["critical", "high", "medium", "low", "info"]);
+const VALID_CONFIDENCES_SET = new Set(["high", "medium", "low"]);
+async function cmdValidateResult(argv) {
+    const runId = getFlag(argv, "--run-id");
+    const taskId = getFlag(argv, "--task-id");
+    if (!runId || !taskId)
+        throw new Error("validate-result requires --run-id and --task-id");
+    const artifactsDir = getArtifactsDir(argv);
+    const sanitized = taskId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    const resultPath = join(artifactsDir, "runs", runId, "task-results", `${sanitized}.json`);
+    const tasksPath = join(artifactsDir, "runs", runId, "pending-audit-tasks.json");
+    let raw;
+    try {
+        raw = await readFile(resultPath, "utf8");
+    }
+    catch {
+        console.error(`File not found: ${resultPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch (e) {
+        console.error(`Invalid JSON: ${e.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    const errors = [];
+    // Required top-level fields
+    for (const field of ["task_id", "unit_id", "pass_id", "lens", "file_coverage", "findings"]) {
+        if (!(field in obj))
+            errors.push(`Missing required field: ${field}`);
+    }
+    if (errors.length > 0) {
+        console.error(`✗ invalid: ${taskId}`);
+        for (const e of errors)
+            console.error(`  ${e}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Lens
+    if (typeof obj.lens !== "string" || !VALID_LENSES_SET.has(obj.lens)) {
+        errors.push(`lens must be one of: ${[...VALID_LENSES_SET].join("|")}`);
+    }
+    // file_coverage
+    if (!Array.isArray(obj.file_coverage) || obj.file_coverage.length === 0) {
+        errors.push("file_coverage must be a non-empty array");
+    }
+    else {
+        for (const fc of obj.file_coverage) {
+            const entry = fc;
+            if (typeof entry.path !== "string")
+                errors.push(`file_coverage entry missing string 'path'`);
+            if (typeof entry.total_lines !== "number")
+                errors.push(`file_coverage entry missing numeric 'total_lines'`);
+        }
+    }
+    // findings
+    if (!Array.isArray(obj.findings)) {
+        errors.push("findings must be an array");
+    }
+    else {
+        for (const f of obj.findings) {
+            const finding = f;
+            for (const field of ["id", "title", "category", "severity", "confidence", "lens", "summary"]) {
+                if (typeof finding[field] !== "string")
+                    errors.push(`finding missing string '${field}'`);
+            }
+            if (typeof finding.severity === "string" && !VALID_SEVERITIES_SET.has(finding.severity)) {
+                errors.push(`finding '${finding.id}': invalid severity '${finding.severity}'`);
+            }
+            if (typeof finding.confidence === "string" && !VALID_CONFIDENCES_SET.has(finding.confidence)) {
+                errors.push(`finding '${finding.id}': invalid confidence '${finding.confidence}'`);
+            }
+            if (!Array.isArray(finding.affected_files) || finding.affected_files.length === 0) {
+                errors.push(`finding '${finding.id}': affected_files must be a non-empty array`);
+            }
+            else {
+                for (const af of finding.affected_files) {
+                    if (typeof af.path !== "string") {
+                        errors.push(`finding '${finding.id}': affected_files entries must be objects with a 'path' key`);
+                    }
+                }
+            }
+            if (!Array.isArray(finding.evidence) || finding.evidence.length === 0) {
+                errors.push(`finding '${finding.id}': evidence must be a non-empty array`);
+            }
+            if (typeof finding.lens === "string" && finding.lens !== obj.lens) {
+                errors.push(`finding '${finding.id}': lens '${finding.lens}' does not match task lens '${obj.lens}'`);
+            }
+        }
+    }
+    // Line range bounds (load from pending-audit-tasks.json if available)
+    let fileLineCounts = {};
+    try {
+        const tasks = await readJsonFile(tasksPath);
+        const task = tasks.find(t => t.task_id === taskId);
+        fileLineCounts = task?.file_line_counts ?? {};
+    }
+    catch { /* ignore */ }
+    if (Array.isArray(obj.file_coverage) && Array.isArray(obj.findings)) {
+        const coverageMap = new Map(obj.file_coverage.map(fc => [fc.path, fc.total_lines]));
+        const allowedPaths = new Set(coverageMap.keys());
+        for (const f of obj.findings) {
+            for (const af of (f.affected_files ?? [])) {
+                const p = af.path;
+                if (!allowedPaths.has(p))
+                    errors.push(`finding '${f.id}': path '${p}' not in file_coverage`);
+                if (typeof af.line_end === "number") {
+                    const max = coverageMap.get(p) ?? fileLineCounts[p] ?? Infinity;
+                    if (af.line_end > max)
+                        errors.push(`finding '${f.id}': line_end ${af.line_end} exceeds total_lines ${max} for ${p}`);
+                }
+            }
+        }
+    }
+    if (errors.length === 0) {
+        console.log(`✓ valid: ${taskId}`);
+    }
+    else {
+        console.error(`✗ invalid: ${taskId}`);
+        for (const e of errors)
+            console.error(`  ${e}`);
+        process.exitCode = 1;
+    }
+}
 async function cmdImportExternalAnalyzer(argv) {
     const artifactsDir = getArtifactsDir(argv);
     const sourcePath = getFlag(argv, "--external-analyzer-results", `${artifactsDir}/external_analyzer_results.json`);
@@ -1641,9 +1921,18 @@ async function main(argv) {
         case "mcp":
             await cmdMcp(argv);
             return;
+        case "prepare-dispatch":
+            await cmdPrepareDispatch(argv);
+            return;
+        case "merge-and-ingest":
+            await cmdMergeAndIngest(argv);
+            return;
+        case "validate-result":
+            await cmdValidateResult(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, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, mcp");
+            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, prepare-dispatch, merge-and-ingest, validate-result");
             process.exitCode = 1;
     }
 }

package/dist/prompts/renderWorkerPrompt.js

@@ -8,60 +8,33 @@ export function renderWorkerPrompt(task) {
         const tasksPath = task.pending_audit_tasks_path ??
             `${task.artifacts_dir}/audit_tasks.json`;
         const lines = [
-            "You are executing one bounded audit run for audit-code.",
-            `Run ID: ${task.run_id}`,
-            `Repository root: ${task.repo_root}`,
-            "",
-            `Read the task file: ${tasksPath}`,
-            "It contains the task(s) assigned to this run.",
-            "",
-            "For each task:",
-            "  1. Read every file listed in file_paths in full using your file-reading tool.",
-            "     If line_ranges are present, they are a focus hint — still read the whole file.",
-            "  2. Review the content under the specified lens.",
-            "  3. Emit one AuditResult with:",
-            "       task_id, unit_id, pass_id, lens",
-            "       file_coverage: [{path, total_lines}] for every assigned file you reviewed",
-            "       findings: array (empty if nothing found)",
-            "     If the task includes file_line_counts, use those values for file_coverage.total_lines.",
-            "     total_lines must match the file's current total line count.",
-            "     Each finding must include:",
-            "       id, title, category, severity, confidence, lens, summary",
-            "       affected_files: [{path, line_start?, line_end?, symbol?}] — path is repo-relative, NOT a plain string",
-            "       evidence: array of plain strings only, at least one excerpt or line reference from the file you read",
-            "       Example evidence entry: src/foo.ts:42 - variable overwritten before use",
-            "       Example affected_files entry: {\"path\": \"src/foo.ts\", \"line_start\": 42, \"line_end\": 55, \"symbol\": \"myFunction\"}",
-            "     Optional finding fields: impact, likelihood, reproduction, systemic, related_findings",
-            "     Low-priority tasks still require a real review. Use findings: [] only when you genuinely found nothing notable.",
-            task.timeout_ms
-                ? `     Time budget for this task: ${task.timeout_ms} ms.`
-                : "     Keep the task bounded to the assigned files only.",
-            `Reference schemas: ${task.artifacts_dir}/dispatch/audit-result.schema.json and ${task.artifacts_dir}/dispatch/finding.schema.json`,
-            `Write the AuditResult[] JSON array to: ${task.audit_results_path}`,
+            `Audit run: ${task.run_id}`,
+            `Read: ${tasksPath}`,
+            "For each task: read all file_paths in full, review under the specified lens,",
+            "and emit one AuditResult with:",
+            "  task_id, unit_id, pass_id, lens (copy from task),",
+            "  file_coverage: [{path, total_lines}] — use file_line_counts[path] from the task for each file,",
+            "  findings: [] or array of finding objects.",
+            "Each finding: id, title, category, severity, confidence, lens, summary,",
+            "  affected_files [{path, line_start, line_end, symbol}] (objects, not strings; min 1 entry),",
+            "  evidence [strings] (min 1 entry).",
+            "Constraint: line_end must not exceed total_lines for that file.",
+            `Write all results as a JSON array to: ${task.audit_results_path}`,
         ];
         if (usesDeferredWorkerCommand(task)) {
-            lines.push("", "This run is using deferred worker-command ingestion.", "Do not execute worker_command in this session.", "Stop after writing the results file.");
+            lines.push("Deferred mode: write results, do not execute worker_command.");
         }
         else {
-            lines.push("", "Then execute the worker_command array from task.json exactly as written.", "Preserve argv boundaries instead of reconstructing shell quoting.", `worker_command argv JSON: ${commandArgv}`, "Stop after the command completes.");
+            lines.push("Then execute worker_command from task.json exactly.", `Command: ${commandArgv}`);
         }
         return lines.join("\n");
     }
     return [
-        "You are executing one bounded audit step for audit-code.",
-        `Run ID: ${task.run_id}`,
-        `Repository root: ${task.repo_root}`,
-        `Obligation: ${task.obligation_id ?? "unknown"}`,
+        `Task: ${task.run_id}`,
         `Executor: ${task.preferred_executor}`,
-        "Execute the worker_command array from task.json exactly as written.",
-        "Preserve argv boundaries instead of reconstructing shell quoting.",
-        `worker_command argv JSON: ${commandArgv}`,
-        "Do not continue the audit recursively.",
-        "Do not choose another task.",
-        task.timeout_ms
-            ? `The worker command is budgeted for ${task.timeout_ms} ms.`
-            : "If the command hangs or fails, stop and let the supervisor handle it.",
-        `The command must write the worker result JSON to: ${task.result_path}`,
-        "After the command completes, stop.",
+        "Execute worker_command from task.json exactly.",
+        `Command: ${commandArgv}`,
+        "Write result to: " + task.result_path,
+        "Stop after completion.",
     ].join("\n");
 }

package/dist/providers/index.js

@@ -29,6 +29,14 @@ export function resolveFreshSessionProviderName(name, sessionConfig = {}, option
     const lookupCommand = options.commandExists ?? commandExists;
     const inVSCode = (env.TERM_PROGRAM ?? "").toLowerCase() === "vscode";
     const insideClaudeCode = Boolean(env.CLAUDECODE);
+    const insideOpenCode = Boolean(env.OPENCODE);
+    // If we're inside a specific IDE/conversation, use that as the provider
+    if (insideOpenCode) {
+        return "opencode";
+    }
+    if (insideClaudeCode) {
+        return "claude-code";
+    }
     if (inVSCode && hasEntries(sessionConfig.vscode_task?.command_template)) {
         return "vscode-task";
     }

package/dist/supervisor/operatorHandoff.d.ts

@@ -38,6 +38,8 @@ export interface AuditCodeHandoff {
     interactive_provider_hint: string | null;
     artifact_paths: AuditCodeHandoffArtifactPaths;
     active_review_run?: ActiveReviewRun;
+    quick_start?: string;
+    file_map?: Record<string, string>;
 }
 export declare function buildAuditCodeHandoff(params: {
     root: string;

package/dist/supervisor/operatorHandoff.js

@@ -115,10 +115,10 @@ function buildInteractiveProviderHint(status, providerName, sessionConfigPath, i
         return null;
     }
     if (isConfigError) {
-        return `A project configuration issue is blocking the audit. Verify that --root points to the repository root containing a project file (package.json, go.mod, etc.), then run audit-code again.`;
+        return `Configuration error: Verify --root points to a repository root (with package.json, go.mod, etc.).`;
     }
     const providerLabel = providerName ?? LOCAL_SUBPROCESS_PROVIDER_NAME;
-    return `Current backend worker provider is ${providerLabel}. Remaining semantic review belongs to the active conversation agent by default. If you intentionally want the backend to continue through a compatibility bridge instead, configure ${sessionConfigPath} for ${formatQuotedList(INTERACTIVE_PROVIDER_OPTIONS)} and re-run audit-code with an explicit --provider value from the repository root.`;
+    return `Provider: ${providerLabel}. For automatic LLM review, configure an interactive provider in ${sessionConfigPath}.`;
 }
 function renderMarkdown(handoff) {
     const lines = [
@@ -208,7 +208,7 @@ export function buildAuditCodeHandoff(params) {
             : null,
     };
     const suggestedInputs = buildSuggestedInputs(params.artifactsDir, params.state.status, isConfigError, params.activeReviewRun);
-    return {
+    const handoff = {
         status: params.state.status,
         repo_root: params.root,
         artifacts_dir: params.artifactsDir,
@@ -221,6 +221,17 @@ export function buildAuditCodeHandoff(params) {
         artifact_paths: artifactPaths,
         active_review_run: params.activeReviewRun,
     };
+    // Add quick_start command and file map when blocked for review
+    if (params.state.status === BLOCKED_STATUS && params.activeReviewRun) {
+        handoff.quick_start = `audit-code worker-run --task ${params.activeReviewRun.task_path}`;
+        handoff.file_map = {
+            current_task: artifactPaths.current_task,
+            current_prompt: artifactPaths.current_prompt,
+            audit_results: params.activeReviewRun.audit_results_path,
+            final_report: join(params.root, "audit-report.md"),
+        };
+    }
+    return handoff;
 }
 export async function writeAuditCodeHandoffArtifacts(handoff) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.2.18",
+  "version": "0.3.1",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",

package/schemas/audit-code-v1alpha1.schema.json

@@ -236,6 +236,15 @@
               "type": ["string", "null"]
             }
           }
+        },
+        "quick_start": {
+          "type": "string"
+        },
+        "file_map": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
         }
       }
     }

package/skills/audit-code/audit-code.prompt.md

@@ -21,10 +21,10 @@ Repeat Steps 1–5 until the audit status is `"complete"`.
 Run:
 
 ```bash
-node audit-code.mjs
+audit-code
 ```
 
-_(Outside the `auditor-lambda` repo itself, use `audit-code` or `npx audit-code` instead.)_
+_(Inside the `auditor-lambda` repo itself, use `node audit-code.mjs` instead.)_
 
 Parse the JSON output. Check `audit_state.status`:
 
@@ -36,15 +36,13 @@ Parse the JSON output. Check `audit_state.status`:
 
 ---
 
-### Step 2 — Read the Task
+### Step 2 — Extract the Task IDs
 
-Read `.audit-artifacts/dispatch/current-task.json`.
+Parse these fields directly from the Step 1 JSON output:
+- `run_id` — from `handoff.active_review_run.run_id`
+- `artifacts_dir` — from `handoff.artifacts_dir`
 
-Note these fields:
-- `run_id` — identifies this batch of audit work
-- `artifacts_dir` — base artifacts directory
-- `pending_audit_tasks_path` — path to the pending task list
-- `worker_command` — JSON array; run this after the audit work is complete
+_(If `audit_state.blockers` contains a message that requires operator input rather than code review, stop and report the blocker verbatim to the user.)_
 
 ---
 
@@ -53,16 +51,14 @@ Note these fields:
 Run:
 
 ```bash
-node dispatch/prepare-dispatch.mjs --run-id <run_id>
+audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
 ```
 
-This reads every pending audit task, pre-computes a complete subagent prompt for each, and writes `dispatch-plan.json` to the same directory as `pending_audit_tasks_path`. It prints the task count and warns about any tasks exceeding 1500 lines.
-
-Read `dispatch-plan.json`. It is a JSON array where each entry has:
+Read `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`. It is a JSON array where each entry has:
 - `task_id` — task identifier
 - `description` — short label for the Agent call
 - `output_path` — where the subagent writes its result
-- `prompt` — the complete, ready-to-use subagent prompt (do not modify it)
+- `prompt_path` — path to the complete subagent instructions file
 
 ---
 
@@ -71,25 +67,23 @@ Read `dispatch-plan.json`. It is a JSON array where each entry has:
 **In a single message**, fire one `Agent` call per entry in `dispatch-plan.json`:
 
 ```
-Agent({ description: entry.description, prompt: entry.prompt })
+Agent({ description: entry.description, prompt: "Read and follow the audit instructions in: " + entry.prompt_path })
 ```
 
 All calls must be sent simultaneously — never await one before firing the next. This is the critical performance constraint. Wait for all to complete before proceeding.
 
-Each subagent reads its assigned files, writes a validated JSON result to `output_path`, and self-validates via `node dispatch/validate-result.mjs`. You do not need to check individual subagent output.
+Each subagent reads its instruction file, reviews the assigned code, writes a validated JSON result to `output_path`, and self-validates. You do not need to inspect individual subagent output.
 
 ---
 
 ### Step 5 — Merge and Ingest
 
-Run in sequence:
+Run:
 
 ```bash
-node dispatch/merge-results.mjs --run-id <run_id>
+audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
 ```
 
-Then execute the `worker_command` from `current-task.json`. It is a JSON array — join the elements into a shell command and run it.
-
 Loop back to **Step 1**.
 
 ---
@@ -98,14 +92,14 @@ Loop back to **Step 1**.
 
 When `audit_state.status` is `"complete"`, stop the loop. Do **not** run the orchestrator again.
 
-Read `audit-report.md` and present the completed audit to the user. Lead with the work blocks — they are the primary remediation handoff. Wait for the user to ask you to begin resolving one or more work blocks.
+Read `audit-report.md` and present the completed audit to the user. Lead with the work blocks — they are the primary remediation handoff.
 
 ---
 
 ## Edge Cases
 
-**Non-agent blocker:** If `audit_state.blockers` contains a message that requires operator input (not code review), stop and report the blocker verbatim to the user.
+**Large task warnings:** `prepare-dispatch` warns about tasks exceeding ~1500 lines. If a subagent hits a quota limit and fails to produce output, `merge-and-ingest` excludes it silently — those tasks remain pending and are picked up in the next loop iteration. No manual intervention needed.
 
-**Large task warnings:** `prepare-dispatch.mjs` warns about tasks exceeding ~1500 lines. If a subagent hits a quota limit and fails to produce output, `merge-results.mjs` excludes it silently — those tasks remain pending and are picked up in the next loop iteration. No manual intervention needed.
+**Failed validation:** Subagents self-validate and retry up to 3 times before finishing. `merge-and-ingest` excludes any results that still lack required fields and writes `failed-tasks.json`. Those tasks are requeued automatically in the next cycle.
 
-**Failed validation:** Subagents self-validate and retry up to 3 times before writing a fallback empty result. `merge-results.mjs` writes `failed-tasks.json` listing any tasks that still failed. Those tasks are requeued automatically in the next cycle.
+**Command failures:** If `prepare-dispatch` or `merge-and-ingest` exits non-zero, **STOP immediately** and report the exact error output to the user. Do NOT improvise manual dispatch, manually split tasks, manually create directories, manually construct prompts, or manually merge results. These scripts are the canonical mechanism — operating without them produces incorrect output. Fix the underlying issue and re-run the failed command.