auditor-lambda 0.3.4 → 0.3.5

package/audit-code-wrapper-lib.mjs

@@ -260,9 +260,11 @@ 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',
+    '- prepare-dispatch --run-id <id> [--artifacts-dir <dir>] creates packet prompt files and a slim dispatch-plan.json for parallel subagent dispatch',
+    '- submit-packet --run-id <id> --packet-id <id> [--artifacts-dir <dir>] validates AuditResult[] from stdin and writes only backend-assigned result files',
+    '- merge-and-ingest --run-id <id> [--root <dir>] [--artifacts-dir <dir>] merges assigned packet 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',
+    '  generated packet prompts may use --run-id-b64, --task-id-b64, and --artifacts-dir-b64 to avoid shell-sensitive raw ids',
     '',
     'Primary usage:',
     '- from the repository root, run the wrapper with no arguments',
@@ -2281,6 +2283,11 @@ export async function runAuditCodeWrapper({
     return;
   }
 
+  if (argv[0] === 'submit-packet') {
+    await runDistCommand('submit-packet', argv.slice(1));
+    return;
+  }
+
   if (argv[0] === 'merge-and-ingest') {
     await runDistCommand('merge-and-ingest', argv.slice(1), { ensureArtifactsDir: true });
     return;

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";
@@ -27,11 +29,13 @@ import { getSessionConfigPath, loadSessionConfig, readSessionConfigFile, } from
 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",
@@ -65,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));
 }
@@ -1404,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)
@@ -1413,6 +1510,17 @@ 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");
@@ -1428,18 +1536,22 @@ async function cmdPrepareDispatch(argv) {
         lineIndex,
     });
     const tasksById = new Map(orderedTasks.map((task) => [task.task_id, task]));
-    const outputPathByTaskId = new Map(orderedTasks.map((task) => [
+    const resultPathByTaskId = new Map(orderedTasks.map((task) => [
         task.task_id,
-        join(taskResultsDir, `${task.task_id.replace(/[^a-zA-Z0-9_-]/g, "_")}.json`),
+        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 = [];
+    const resultMapEntries = [];
     let largestPacketId = null;
     let largestLines = 0;
     let largestEstimatedTokens = 0;
     const warnings = [];
     for (const packet of packets) {
-        const sanitized = packet.packet_id.replace(/[^a-zA-Z0-9_-]/g, "_");
-        const promptPath = join(taskResultsDir, `${sanitized}.prompt.md`);
+        const promptPath = packetPromptPath(taskResultsDir, packet.packet_id);
         const packetTasks = packet.task_ids
             .map((taskId) => tasksById.get(taskId))
             .filter((task) => task !== undefined);
@@ -1448,7 +1560,8 @@ async function cmdPrepareDispatch(argv) {
             largestEstimatedTokens = packet.estimated_tokens;
             largestPacketId = packet.packet_id;
         }
-        if (packet.total_lines > 2500) {
+        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`,
@@ -1466,15 +1579,57 @@ async function cmdPrepareDispatch(argv) {
             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];
-            const outputPath = outputPathByTaskId.get(task.task_id);
             return [
                 `### ${task.task_id}`,
                 `unit_id: ${task.unit_id}`,
                 `pass_id: ${task.pass_id}`,
                 `lens: ${task.lens}`,
-                `output_path: ${outputPath}`,
                 `rationale: ${task.rationale}`,
                 "",
                 `Lens guidance: ${lensDef?.description ?? task.lens}`,
@@ -1482,13 +1637,19 @@ async function cmdPrepareDispatch(argv) {
                 "",
             ];
         });
-        const validationCommands = packetTasks.map((task) => `  "${process.execPath}" "${join(packageRoot, "audit-code.mjs")}" validate-result --run-id ${runId} --task-id ${task.task_id} --artifacts-dir "${artifactsDir}"`);
-        const outputPaths = Object.fromEntries(packetTasks.map((task) => [
-            task.task_id,
-            outputPathByTaskId.get(task.task_id) ?? "",
-        ]));
+        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 this packet once, then produce one result file per listed task.",
+            "You are a code auditor. Review this packet once, then submit exactly one result per listed task.",
             "",
             "## Packet",
             `packet_id: ${packet.packet_id}`,
@@ -1497,15 +1658,18 @@ async function cmdPrepareDispatch(argv) {
             `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,
             "",
+            ...largeFileSection,
             "## Tasks",
             ...taskSections,
             "## Output",
-            "Write exactly one JSON object for each task to that task's output_path.",
-            "Do not combine the task results into one file. 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 AuditResult fields:",
             "  task_id       copy from the task metadata",
@@ -1532,30 +1696,30 @@ async function cmdPrepareDispatch(argv) {
             "3. Only reference files from the packet unless a finding genuinely crosses a boundary.",
             "4. findings: [] is correct when you find nothing genuine.",
             "",
-            "## Validate",
-            "After writing every result, run:",
-            ...validationCommands,
+            "## Submit",
+            "Pipe the JSON array on stdin to this command:",
+            `  ${submitCommand}`,
             "",
-            "Exit 0 means valid. Non-zero: read the errors, fix the JSON, rewrite the file, run again. Retry up to 3 times.",
+            "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.",
             "",
             "## Final response",
-            `After every validation command succeeds, reply exactly: valid: ${packet.packet_id}, findings=<total finding count>`,
+            `After the submit command succeeds, reply exactly: valid: ${packet.packet_id}, findings=<total finding count>`,
         ].join("\n");
         await writeFile(promptPath, prompt, "utf8");
         plan.push({
             packet_id: packet.packet_id,
-            task_id: packet.task_ids.length === 1 ? packet.task_ids[0] : packet.packet_id,
-            task_ids: packet.task_ids,
-            description: `Audit ${packet.file_paths.length} file(s), ${packet.task_ids.length} task(s), ${packet.lenses.length} lens(es) (~${packet.total_lines} lines)`,
-            output_paths: outputPaths,
+            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,
-            lenses: packet.lenses,
-            file_paths: packet.file_paths,
-            total_lines: packet.total_lines,
-            estimated_tokens: packet.estimated_tokens,
         });
     }
     await writeJsonFile(dispatchPlanPath, plan);
+    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;
@@ -1578,6 +1742,106 @@ async function cmdPrepareDispatch(argv) {
         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");
     if (!runId)
@@ -1589,12 +1853,20 @@ async function cmdMergeAndIngest(argv) {
     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 lineIndex = Object.fromEntries(allTasks.flatMap((task) => Object.entries(task.file_line_counts ?? {})));
+    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();
@@ -1606,13 +1878,38 @@ 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 record = obj && typeof obj === "object" && !Array.isArray(obj)
@@ -1628,8 +1925,11 @@ async function cmdMergeAndIngest(argv) {
             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 issues = validateAuditResults([obj], allTasks, { lineIndex });
+        const issues = validateAuditResults([obj], [task], { lineIndex: task.file_line_counts ?? {} });
         resultErrors.push(...issues
             .filter(i => i.severity === "error")
             .map(i => i.message));
@@ -1637,15 +1937,7 @@ async function cmdMergeAndIngest(argv) {
             passing.push(obj);
         }
         else {
-            failing.push({ task_id: taskId ?? filename, errors: resultErrors });
-        }
-    }
-    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);
@@ -1687,14 +1979,25 @@ async function cmdMergeAndIngest(argv) {
     }, 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");
@@ -1986,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;
     }
 }

package/dist/orchestrator/fileAnchors.d.ts

@@ -0,0 +1,32 @@
+import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
+import type { GraphBundle } from "../types/graph.js";
+export type FileAnchorKind = "boundary" | "import" | "export" | "symbol" | "route" | "keyword" | "graph" | "analyzer_signal";
+export interface FileAnchor {
+    kind: FileAnchorKind;
+    name: string;
+    line?: number;
+    detail?: string;
+}
+export interface FileAnchorSummary {
+    contract_version: "audit-code-file-anchors/v1alpha1";
+    path: string;
+    total_lines: number;
+    review_mode: "isolated_large_file";
+    scope_basis: string[];
+    anchors: FileAnchor[];
+    omitted_anchor_count: number;
+    counts: {
+        symbols: number;
+        routes: number;
+        keywords: number;
+        graph_edges: number;
+        analyzer_signals: number;
+    };
+}
+export declare function buildFileAnchorSummary(params: {
+    path: string;
+    content: string;
+    totalLines: number;
+    graphBundle?: GraphBundle;
+    externalAnalyzerResults?: ExternalAnalyzerResults;
+}): FileAnchorSummary;