auditor-lambda 0.3.3 → 0.3.5

package/dist/cli.js

@@ -1,6 +1,8 @@
 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 { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildRepoManifest } from "./extractors/fileInventory.js";
 import { buildFileDisposition } from "./extractors/disposition.js";
@@ -11,7 +13,7 @@ import { buildFlowCoverage } from "./orchestrator/flowCoverage.js";
 import { buildRuntimeValidationTasks, } from "./orchestrator/runtimeValidation.js";
 import { initializeCoverageFromPlan } from "./orchestrator/planning.js";
 import { loadArtifactBundle, writeCoreArtifacts, promoteFinalAuditReport, } from "./io/artifacts.js";
-import { readJsonFile, writeJsonFile } from "./io/json.js";
+import { isFileMissingError, readJsonFile, writeJsonFile } from "./io/json.js";
 import { validateArtifactBundle } from "./validation/artifacts.js";
 import { validateAuditResults, formatAuditResultIssues, } from "./validation/auditResults.js";
 import { prefixValidationIssues } from "./validation/basic.js";
@@ -26,16 +28,19 @@ import { buildAuditCodeHandoff, writeAuditCodeHandoffArtifacts, } from "./superv
 import { getSessionConfigPath, loadSessionConfig, readSessionConfigFile, } from "./supervisor/sessionConfig.js";
 import { clearDispatchFiles, buildRunId, ensureSupervisorDirs, getRunPaths, writeDispatchBatchFiles, writeWorkerTaskFiles, } from "./io/runArtifacts.js";
 import { renderWorkerPrompt } from "./prompts/renderWorkerPrompt.js";
+import { buildReviewPackets, orderTasksForPacketReview, } from "./orchestrator/reviewPackets.js";
+import { buildFileAnchorSummary, } from "./orchestrator/fileAnchors.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 LARGE_FILE_PACKET_TARGET_LINES = 2500;
 const DIRECT_CLI_DEFAULTS = {
     rootDir: ".",
     artifactsDir: ".artifacts",
     maxRuns: 1000,
-    agentBatchSize: 1,
+    agentBatchSize: 6,
     parallelWorkers: 1,
     timeoutMs: 30 * 60 * 1000, // 30 minutes
     uiMode: "headless",
@@ -64,6 +69,45 @@ function getFlag(argv, name, fallback) {
 function hasFlag(argv, name) {
     return argv.includes(name);
 }
+function toBase64Url(value) {
+    return Buffer.from(value, "utf8").toString("base64url");
+}
+function fromBase64Url(value) {
+    return Buffer.from(value, "base64url").toString("utf8");
+}
+function digestId(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+function safeArtifactStem(value) {
+    const sanitized = value
+        .replace(/[^a-zA-Z0-9_-]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 80);
+    return sanitized.length > 0 ? sanitized : "artifact";
+}
+function artifactNameForId(value, extension) {
+    return `${safeArtifactStem(value)}_${digestId(value)}.${extension}`;
+}
+function taskResultPath(taskResultsDir, taskId) {
+    return join(taskResultsDir, artifactNameForId(taskId, "json"));
+}
+function packetPromptPath(taskResultsDir, packetId) {
+    return join(taskResultsDir, artifactNameForId(packetId, "prompt.md"));
+}
+async function readStdinText() {
+    if (process.stdin.isTTY) {
+        return "";
+    }
+    return await new Promise((resolveInput, reject) => {
+        let input = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            input += chunk;
+        });
+        process.stdin.on("end", () => resolveInput(input));
+        process.stdin.on("error", reject);
+    });
+}
 function resolveFlagPath(argv, name, fallback) {
     return resolve(getFlag(argv, name, fallback));
 }
@@ -287,7 +331,12 @@ 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) => task.status !== "complete" && !completedTaskIds.has(task.task_id));
+    const pendingTasks = (bundle.audit_tasks ?? []).filter((task) => task.status !== "complete" && !completedTaskIds.has(task.task_id));
+    const lineIndex = Object.fromEntries(pendingTasks.flatMap((task) => Object.entries(task.file_line_counts ?? {})));
+    return orderTasksForPacketReview(pendingTasks, {
+        graphBundle: bundle.graph_bundle,
+        lineIndex,
+    });
 }
 async function addFileLineCountHints(root, tasks) {
     const lineIndex = await buildLineIndexForPaths(root, tasks.flatMap((task) => task.file_paths));
@@ -1398,6 +1447,60 @@ async function cmdWorkerRun(argv) {
         process.exitCode = 1;
     }
 }
+const DISPATCH_RESULT_MAP_FILENAME = "dispatch-result-map.json";
+function dispatchResultMapPath(runDir) {
+    return join(runDir, DISPATCH_RESULT_MAP_FILENAME);
+}
+function resolveRunScopedArg(argv, rawFlag, b64Flag) {
+    const raw = getFlag(argv, rawFlag);
+    const encoded = getFlag(argv, b64Flag);
+    return raw ?? (encoded ? fromBase64Url(encoded) : undefined);
+}
+async function loadDispatchResultMap(runDir) {
+    try {
+        return await readJsonFile(dispatchResultMapPath(runDir));
+    }
+    catch (error) {
+        if (!isFileMissingError(error)) {
+            throw error;
+        }
+        return null;
+    }
+}
+function entriesByTaskId(entries) {
+    return new Map(entries.map((entry) => [entry.task_id, entry]));
+}
+function isIsolatedLargeFilePacket(packet) {
+    return (packet.file_paths.length === 1 &&
+        packet.total_lines > LARGE_FILE_PACKET_TARGET_LINES);
+}
+function withinRoot(root, path) {
+    const rootPath = resolve(root);
+    const absolutePath = resolve(rootPath, path);
+    const relativePath = relative(rootPath, absolutePath);
+    if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+        throw new Error(`Path '${path}' escapes repository root '${rootPath}'.`);
+    }
+    return absolutePath;
+}
+function renderAnchorPreview(summary, anchorPath) {
+    const preview = summary.anchors.slice(0, 24).map((anchor) => {
+        const location = anchor.line ? `${summary.path}:${anchor.line}` : summary.path;
+        const detail = anchor.detail ? ` - ${anchor.detail}` : "";
+        return `- ${location} [${anchor.kind}] ${anchor.name}${detail}`;
+    });
+    return [
+        "## Large File Review Mode",
+        "This packet is intentionally isolated because it covers one large file.",
+        "Use targeted reads/searches within this file, guided by the mechanical anchors.",
+        "Do not read unrelated files unless a finding cannot be evidenced without a direct boundary check.",
+        `Anchor file: ${anchorPath}`,
+        `Anchor counts: symbols=${summary.counts.symbols}, routes=${summary.counts.routes}, keywords=${summary.counts.keywords}, graph_edges=${summary.counts.graph_edges}, analyzer_signals=${summary.counts.analyzer_signals}, omitted=${summary.omitted_anchor_count}`,
+        "Anchor preview:",
+        ...(preview.length > 0 ? preview : ["- no anchors extracted beyond file boundaries"]),
+        "",
+    ];
+}
 async function cmdPrepareDispatch(argv) {
     const runId = getFlag(argv, "--run-id");
     if (!runId)
@@ -1407,95 +1510,337 @@ async function cmdPrepareDispatch(argv) {
     const tasksPath = join(runDir, "pending-audit-tasks.json");
     const taskResultsDir = join(runDir, "task-results");
     const dispatchPlanPath = join(runDir, "dispatch-plan.json");
+    const explicitRoot = getFlag(argv, "--root") ? getRootDir(argv) : undefined;
+    let reviewRoot = explicitRoot;
+    try {
+        const workerTask = await readJsonFile(join(runDir, "task.json"));
+        reviewRoot ??= workerTask.repo_root;
+    }
+    catch (error) {
+        if (!isFileMissingError(error)) {
+            throw error;
+        }
+    }
     const tasks = await readJsonFile(tasksPath);
+    const bundle = await loadArtifactBundle(artifactsDir);
     const lensDefsPath = join(packageRoot, "dispatch", "lens-definitions.json");
     const lensDefs = await readJsonFile(lensDefsPath);
     await mkdir(taskResultsDir, { recursive: true });
+    const lineIndex = Object.fromEntries(tasks.flatMap((task) => Object.entries(task.file_line_counts ?? {})));
+    const orderedTasks = orderTasksForPacketReview(tasks, {
+        graphBundle: bundle.graph_bundle,
+        lineIndex,
+    });
+    const packets = buildReviewPackets(orderedTasks, {
+        graphBundle: bundle.graph_bundle,
+        lineIndex,
+    });
+    const tasksById = new Map(orderedTasks.map((task) => [task.task_id, task]));
+    const resultPathByTaskId = new Map(orderedTasks.map((task) => [
+        task.task_id,
+        taskResultPath(taskResultsDir, task.task_id),
+    ]));
+    const resultPathSet = new Set(resultPathByTaskId.values());
+    if (resultPathSet.size !== resultPathByTaskId.size) {
+        throw new Error("prepare-dispatch generated duplicate result paths; task ids must be uniquely addressable.");
+    }
     const plan = [];
-    let largestTask = null;
+    const resultMapEntries = [];
+    let largestPacketId = 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`);
+    let largestEstimatedTokens = 0;
+    const warnings = [];
+    for (const packet of packets) {
+        const promptPath = packetPromptPath(taskResultsDir, packet.packet_id);
+        const packetTasks = packet.task_ids
+            .map((taskId) => tasksById.get(taskId))
+            .filter((task) => task !== undefined);
+        if (packet.total_lines > largestLines) {
+            largestLines = packet.total_lines;
+            largestEstimatedTokens = packet.estimated_tokens;
+            largestPacketId = packet.packet_id;
         }
-        const totalLines = Object.values(task.file_line_counts ?? {}).reduce((a, b) => a + b, 0);
-        if (totalLines > largestLines) {
-            largestLines = totalLines;
-            largestTask = task.task_id;
+        const largeFileMode = isIsolatedLargeFilePacket(packet);
+        if (packet.total_lines > LARGE_FILE_PACKET_TARGET_LINES && !largeFileMode) {
+            warnings.push({
+                code: "large_packet",
+                message: `large packet ${packet.packet_id} (~${packet.total_lines} lines) may hit quota limits`,
+            });
         }
-        if (totalLines > 1500) {
-            process.stderr.write(`Warning: large task ${task.task_id} (~${totalLines} lines) may hit quota limits\n`);
+        for (const task of packetTasks) {
+            if (!lensDefs[task.lens]) {
+                warnings.push({
+                    code: "missing_lens_definition",
+                    message: `no lens definition for '${task.lens}' (task ${task.task_id})`,
+                });
+            }
         }
-        const fileList = task.file_paths.map(p => {
-            const lines = task.file_line_counts?.[p] ?? 0;
-            return `- ${p} (${lines} lines)`;
+        const fileList = packet.file_paths.map((path) => {
+            const lines = packet.file_line_counts[path] ?? 0;
+            return `- ${path} (${lines} lines)`;
         }).join("\n");
+        let anchorPath = null;
+        let anchorSummary = null;
+        if (largeFileMode) {
+            const filePath = packet.file_paths[0];
+            if (!reviewRoot) {
+                warnings.push({
+                    code: "large_file_anchor_unavailable",
+                    message: `large single-file packet ${packet.packet_id} has no repo root available for anchor extraction`,
+                });
+            }
+            else {
+                try {
+                    const totalLines = packet.file_line_counts[filePath] ?? packet.total_lines;
+                    const content = await readFile(withinRoot(reviewRoot, filePath), "utf8");
+                    anchorSummary = buildFileAnchorSummary({
+                        path: filePath,
+                        content,
+                        totalLines,
+                        graphBundle: bundle.graph_bundle,
+                        externalAnalyzerResults: bundle.external_analyzer_results,
+                    });
+                    anchorPath = join(taskResultsDir, artifactNameForId(packet.packet_id, "anchors.json"));
+                    await writeJsonFile(anchorPath, anchorSummary);
+                }
+                catch (error) {
+                    warnings.push({
+                        code: "large_file_anchor_failed",
+                        message: `large single-file packet ${packet.packet_id} could not be anchored mechanically: ` +
+                            (error instanceof Error ? error.message : String(error)),
+                    });
+                }
+            }
+        }
+        const largeFileSection = anchorSummary && anchorPath
+            ? renderAnchorPreview(anchorSummary, anchorPath)
+            : largeFileMode
+                ? [
+                    "## Large File Review Mode",
+                    "This packet is intentionally isolated because it covers one large file.",
+                    "Use targeted reads/searches within this file only.",
+                    "No mechanical anchor file was available, so rely on targeted symbol and keyword searches before reading broad ranges.",
+                    "",
+                ]
+                : [];
+        const taskSections = packetTasks.flatMap((task) => {
+            const lensDef = lensDefs[task.lens];
+            return [
+                `### ${task.task_id}`,
+                `unit_id: ${task.unit_id}`,
+                `pass_id: ${task.pass_id}`,
+                `lens: ${task.lens}`,
+                `rationale: ${task.rationale}`,
+                "",
+                `Lens guidance: ${lensDef?.description ?? task.lens}`,
+                `Do NOT report: ${lensDef?.do_not_report ?? "N/A"}`,
+                "",
+            ];
+        });
+        const submitCommand = `"${process.execPath}" "${join(packageRoot, "audit-code.mjs")}" submit-packet ` +
+            `--run-id-b64 ${toBase64Url(runId)} ` +
+            `--packet-id-b64 ${toBase64Url(packet.packet_id)} ` +
+            `--artifacts-dir-b64 ${toBase64Url(artifactsDir)}`;
+        for (const task of packetTasks) {
+            resultMapEntries.push({
+                packet_id: packet.packet_id,
+                task_id: task.task_id,
+                result_path: resultPathByTaskId.get(task.task_id),
+            });
+        }
         const prompt = [
-            "You are a code auditor. Review the files below under the specified lens.",
+            "You are a code auditor. Review this packet once, then submit exactly one result per listed task.",
             "",
-            "## Task",
-            `task_id: ${task.task_id}`,
-            `unit_id: ${task.unit_id}`,
-            `pass_id: ${task.pass_id}`,
-            `lens: ${task.lens}`,
+            "## Packet",
+            `packet_id: ${packet.packet_id}`,
+            `task_count: ${packet.task_ids.length}`,
+            `lenses: ${packet.lenses.join(", ")}`,
+            `estimated_tokens: ${packet.estimated_tokens}`,
             "",
             "## Files to read",
-            "Use your Read tool. Paths are repo-relative from the current working directory.",
+            largeFileMode
+                ? "Use targeted Read/Grep calls. Paths are repo-relative from the current working directory."
+                : "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"}`,
-            "",
+            ...largeFileSection,
+            "## Tasks",
+            ...taskSections,
             "## Output",
-            `Write a single JSON object to: ${outputPath}`,
-            "Write only this assigned task's AuditResult object. Do not edit source files,",
+            "Do not write files directly. Do not use a Write tool, create temp files, edit source files,",
             "remediate findings, create extra task results, or run unrelated audits.",
+            "Produce one JSON array containing exactly one AuditResult object for each listed task.",
             "",
-            "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)",
+            "Required AuditResult fields:",
+            "  task_id       copy from the task metadata",
+            "  unit_id       copy from the task metadata",
+            "  pass_id       copy from the task metadata",
+            "  lens          copy from the task metadata",
+            "  file_coverage [{path, total_lines}] - one entry per assigned file; use the line counts listed above",
+            "  findings      [] or array of finding objects",
             "",
             "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",
+            "  category      specific finding category, such as missing-validation or command-execution",
             "  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",
+            "  lens          must match the 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",
+            "1. line_end must not exceed the file's actual line count.",
+            "2. affected_files entries are objects with a path key, not plain strings.",
+            "3. Only reference files from the packet unless a finding genuinely crosses a boundary.",
+            "4. findings: [] is correct when you find nothing genuine.",
+            "",
+            "## Submit",
+            "Pipe the JSON array on stdin to this command:",
+            `  ${submitCommand}`,
             "",
-            "## 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}"`,
+            "The command validates and writes the packet-owned result files. Exit 0 means accepted.",
+            "Non-zero: read the errors, fix the JSON, and run the same submit command again. Retry up to 3 times.",
             "",
-            "Exit 0 means valid. Non-zero: read the errors, fix your JSON, rewrite the file, run again. Retry up to 3 times.",
+            "## Final response",
+            `After the submit command succeeds, reply exactly: valid: ${packet.packet_id}, findings=<total finding count>`,
         ].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 });
+        plan.push({
+            packet_id: packet.packet_id,
+            description: `Audit ${packet.file_paths.length} file(s), ${packet.task_ids.length} task(s), ${packet.lenses.length} lens(es) (~${packet.total_lines} lines)` +
+                (largeFileMode ? " [isolated large-file mode]" : ""),
+            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)`);
+    await writeJsonFile(dispatchResultMapPath(runDir), {
+        contract_version: "audit-code-dispatch-results/v1alpha1",
+        run_id: runId,
+        entries: resultMapEntries,
+    });
+    const warningsPath = warnings.length > 0
+        ? join(runDir, "dispatch-warnings.json")
+        : null;
+    if (warningsPath) {
+        await writeJsonFile(warningsPath, warnings);
+    }
+    console.log(JSON.stringify({
+        run_id: runId,
+        dispatch_plan_path: dispatchPlanPath,
+        packet_count: plan.length,
+        task_count: orderedTasks.length,
+        largest_packet: largestPacketId
+            ? {
+                packet_id: largestPacketId,
+                total_lines: largestLines,
+                estimated_tokens: largestEstimatedTokens,
+            }
+            : null,
+        warning_count: warnings.length,
+        dispatch_warnings_path: warningsPath,
+    }, null, 2));
+}
+async function cmdSubmitPacket(argv) {
+    const runId = resolveRunScopedArg(argv, "--run-id", "--run-id-b64");
+    const packetId = resolveRunScopedArg(argv, "--packet-id", "--packet-id-b64");
+    const artifactsDirB64 = getFlag(argv, "--artifacts-dir-b64");
+    const artifactsDir = artifactsDirB64
+        ? resolve(fromBase64Url(artifactsDirB64))
+        : getArtifactsDir(argv);
+    if (!runId || !packetId) {
+        throw new Error("submit-packet requires --run-id and --packet-id (or --run-id-b64/--packet-id-b64)");
+    }
+    const runDir = join(artifactsDir, "runs", runId);
+    const tasksPath = join(runDir, "pending-audit-tasks.json");
+    const resultMap = await loadDispatchResultMap(runDir);
+    if (!resultMap) {
+        throw new Error(`No ${DISPATCH_RESULT_MAP_FILENAME} found for run ${runId}; run prepare-dispatch first.`);
+    }
+    const packetEntries = resultMap.entries.filter((entry) => entry.packet_id === packetId);
+    if (packetEntries.length === 0) {
+        throw new Error(`Unknown packet_id '${packetId}' for run ${runId}.`);
+    }
+    if (entriesByTaskId(packetEntries).size !== packetEntries.length) {
+        throw new Error(`Dispatch result map has duplicate task entries for packet '${packetId}'.`);
+    }
+    const allTasks = await readJsonFile(tasksPath);
+    const taskById = new Map(allTasks.map((task) => [task.task_id, task]));
+    const packetTasks = packetEntries.map((entry) => taskById.get(entry.task_id));
+    const missingTask = packetEntries.find((entry, index) => !packetTasks[index]);
+    if (missingTask) {
+        throw new Error(`Dispatch result map references unknown task '${missingTask.task_id}'.`);
+    }
+    const tasks = packetTasks;
+    const expectedTaskIds = new Set(tasks.map((task) => task.task_id));
+    const lineIndex = Object.fromEntries(tasks.flatMap((task) => Object.entries(task.file_line_counts ?? {})));
+    const encodedResults = getFlag(argv, "--results-b64");
+    const raw = encodedResults ? fromBase64Url(encodedResults) : await readStdinText();
+    if (raw.trim().length === 0) {
+        throw new Error("submit-packet requires an AuditResult[] JSON payload on stdin or --results-b64.");
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid submit-packet JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const resultErrors = [];
+    const issues = validateAuditResults(payload, tasks, { lineIndex });
+    const validationErrors = issues.filter((issue) => issue.severity === "error");
+    const validationWarnings = issues.filter((issue) => issue.severity === "warning");
+    if (validationWarnings.length > 0) {
+        process.stderr.write(`audit-results validation: ${validationWarnings.length} warning(s):\n` +
+            formatAuditResultIssues(validationWarnings) +
+            "\n");
+    }
+    if (validationErrors.length > 0) {
+        resultErrors.push(formatAuditResultIssues(validationErrors));
+    }
+    if (Array.isArray(payload)) {
+        const seen = new Set();
+        for (const [index, result] of payload.entries()) {
+            if (!result || typeof result !== "object" || Array.isArray(result)) {
+                continue;
+            }
+            const taskId = result.task_id;
+            if (typeof taskId !== "string" || taskId.trim().length === 0) {
+                continue;
+            }
+            if (seen.has(taskId)) {
+                resultErrors.push(`Duplicate audit result for assigned task '${taskId}'.`);
+            }
+            seen.add(taskId);
+            if (!expectedTaskIds.has(taskId)) {
+                resultErrors.push(`Result at index ${index} uses task_id '${taskId}', which is not assigned to packet '${packetId}'.`);
+            }
+        }
+        for (const task of tasks) {
+            if (!seen.has(task.task_id)) {
+                resultErrors.push(`Missing audit result for assigned task '${task.task_id}'.`);
+            }
+        }
+    }
+    if (resultErrors.length > 0) {
+        throw new Error(`submit-packet rejected ${packetId}:\n${resultErrors.join("\n")}`);
+    }
+    const entryByTaskId = entriesByTaskId(packetEntries);
+    for (const result of payload) {
+        const entry = entryByTaskId.get(result.task_id);
+        if (!entry) {
+            throw new Error(`Internal error: no result path for accepted task '${result.task_id}'.`);
+        }
+        await writeJsonFile(entry.result_path, result);
+    }
+    const findingCount = payload.reduce((sum, result) => sum + result.findings.length, 0);
+    console.log(JSON.stringify({
+        run_id: runId,
+        packet_id: packetId,
+        accepted_count: payload.length,
+        finding_count: findingCount,
+    }, null, 2));
 }
 async function cmdMergeAndIngest(argv) {
     const runId = getFlag(argv, "--run-id");
@@ -1507,12 +1852,21 @@ async function cmdMergeAndIngest(argv) {
     const auditResultsPath = join(runDir, "audit-results.json");
     const taskPath = join(runDir, "task.json");
     const tasksPath = join(runDir, "pending-audit-tasks.json");
+    const workerTask = await readJsonFile(taskPath);
+    const resultMap = await loadDispatchResultMap(runDir);
+    if (!resultMap) {
+        throw new Error(`No ${DISPATCH_RESULT_MAP_FILENAME} found for run ${runId}; run prepare-dispatch first.`);
+    }
     let allTasks = [];
     try {
         allTasks = await readJsonFile(tasksPath);
     }
     catch { /* may not exist */ }
-    const taskMap = new Map(allTasks.map(t => [t.task_id, t]));
+    const entryByTaskId = entriesByTaskId(resultMap.entries);
+    if (entryByTaskId.size !== resultMap.entries.length) {
+        throw new Error(`Dispatch result map for run ${runId} contains duplicate task entries.`);
+    }
+    const expectedPaths = new Set(resultMap.entries.map((entry) => resolve(entry.result_path)));
     let files;
     try {
         files = (await readdir(taskResultsDir)).filter(f => f.endsWith(".json")).sort();
@@ -1524,36 +1878,66 @@ async function cmdMergeAndIngest(argv) {
     const failing = [];
     const seenTaskIds = new Set();
     for (const filename of files) {
-        const filePath = join(taskResultsDir, filename);
+        const filePath = resolve(join(taskResultsDir, filename));
+        if (!expectedPaths.has(filePath)) {
+            failing.push({
+                task_id: filename,
+                errors: ["Unexpected task result file; only backend-assigned result paths may be ingested."],
+            });
+        }
+    }
+    for (const task of allTasks) {
+        const entry = entryByTaskId.get(task.task_id);
+        if (!entry) {
+            failing.push({
+                task_id: task.task_id,
+                errors: ["Missing dispatch result-map entry for assigned task."],
+            });
+            continue;
+        }
+        const filePath = entry.result_path;
         let obj;
         try {
             obj = JSON.parse(await readFile(filePath, "utf8"));
         }
         catch (e) {
-            failing.push({ task_id: filename, errors: [`Invalid JSON: ${e.message}`] });
+            if (isFileMissingError(e)) {
+                failing.push({
+                    task_id: task.task_id,
+                    errors: ["Missing audit result for assigned task."],
+                });
+            }
+            else {
+                failing.push({ task_id: task.task_id, errors: [`Invalid JSON: ${e.message}`] });
+            }
             continue;
         }
-        const taskId = typeof obj.task_id === "string"
-            ? String(obj.task_id) : undefined;
+        const record = obj && typeof obj === "object" && !Array.isArray(obj)
+            ? obj
+            : undefined;
+        const taskId = typeof record?.task_id === "string"
+            ? String(record.task_id) : undefined;
+        const resultErrors = [];
         if (taskId) {
-            seenTaskIds.add(taskId);
+            if (seenTaskIds.has(taskId)) {
+                resultErrors.push(`Duplicate audit result for assigned task '${taskId}'.`);
+            }
+            else {
+                seenTaskIds.add(taskId);
+            }
+            if (taskId !== task.task_id) {
+                resultErrors.push(`Result file is assigned to '${task.task_id}' but contains task_id '${taskId}'.`);
+            }
         }
-        const matchingTask = taskId ? taskMap.get(taskId) : undefined;
-        const issues = validateAuditResults([obj], matchingTask ? [matchingTask] : [], { lineIndex: matchingTask?.file_line_counts ?? {} });
-        const errors = issues.filter(i => i.severity === "error");
-        if (errors.length === 0) {
+        const issues = validateAuditResults([obj], [task], { lineIndex: task.file_line_counts ?? {} });
+        resultErrors.push(...issues
+            .filter(i => i.severity === "error")
+            .map(i => i.message));
+        if (resultErrors.length === 0) {
             passing.push(obj);
         }
         else {
-            failing.push({ task_id: taskId ?? filename, errors: errors.map(i => i.message) });
-        }
-    }
-    for (const task of allTasks) {
-        if (!seenTaskIds.has(task.task_id)) {
-            failing.push({
-                task_id: task.task_id,
-                errors: ["Missing audit result for assigned task."],
-            });
+            failing.push({ task_id: taskId ?? task.task_id, errors: resultErrors });
         }
     }
     await writeJsonFile(auditResultsPath, passing);
@@ -1562,19 +1946,58 @@ async function cmdMergeAndIngest(argv) {
         await writeJsonFile(failedTasksPath, failing);
         throw new Error(`${failing.length} assigned task result(s) were missing or invalid; blocked before ingestion. See ${failedTasksPath}`);
     }
-    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 findingCount = passing.reduce((sum, result) => sum + result.findings.length, 0);
+    const result = await runAuditStep({
+        root: workerTask.repo_root,
+        artifactsDir,
+        preferredExecutor: "result_ingestion_executor",
+        auditResultsPath,
+    });
+    const workerResult = buildWorkerResult({
+        runId,
+        obligationId: workerTask.obligation_id,
+        status: result.progress_made ? "completed" : "no_progress",
+        progressMade: result.progress_made,
+        selectedExecutor: result.selected_executor,
+        artifactsWritten: result.artifacts_written,
+        summary: result.progress_summary,
+        nextLikelyStep: result.next_likely_step,
+        errors: [],
+    });
+    await writeJsonFile(workerTask.result_path, workerResult);
+    console.log(JSON.stringify({
+        run_id: runId,
+        status: workerResult.status,
+        accepted_count: passing.length,
+        rejected_count: 0,
+        finding_count: findingCount,
+        audit_results_path: auditResultsPath,
+        selected_executor: workerResult.selected_executor,
+        progress_made: workerResult.progress_made,
+        progress_summary: workerResult.summary,
+        next_likely_step: workerResult.next_likely_step,
+    }, null, 2));
 }
 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");
+    const rawRunId = getFlag(argv, "--run-id");
+    const runIdB64 = getFlag(argv, "--run-id-b64");
+    const rawTaskId = getFlag(argv, "--task-id");
+    const artifactsDirB64 = getFlag(argv, "--artifacts-dir-b64");
+    const runId = rawRunId ?? (runIdB64 ? fromBase64Url(runIdB64) : undefined);
+    const taskIdB64 = getFlag(argv, "--task-id-b64");
+    const taskId = rawTaskId ?? (taskIdB64 ? fromBase64Url(taskIdB64) : undefined);
+    const artifactsDir = artifactsDirB64
+        ? resolve(fromBase64Url(artifactsDirB64))
+        : getArtifactsDir(argv);
+    if (!runId || !taskId) {
+        throw new Error("validate-result requires --run-id and --task-id (or --run-id-b64/--task-id-b64)");
+    }
+    const runDir = join(artifactsDir, "runs", runId);
+    const taskResultsDir = join(runDir, "task-results");
+    const resultMap = await loadDispatchResultMap(runDir);
+    const resultPath = resultMap?.entries.find((entry) => entry.task_id === taskId)?.result_path ??
+        taskResultPath(taskResultsDir, taskId);
+    const tasksPath = join(runDir, "pending-audit-tasks.json");
     let raw;
     try {
         raw = await readFile(resultPath, "utf8");
@@ -1866,12 +2289,15 @@ async function main(argv) {
         case "merge-and-ingest":
             await cmdMergeAndIngest(argv);
             return;
+        case "submit-packet":
+            await cmdSubmitPacket(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, prepare-dispatch, merge-and-ingest, validate-result");
+            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, submit-packet, validate-result");
             process.exitCode = 1;
     }
 }