auditor-lambda 0.2.5 → 0.2.6

package/dist/orchestrator/flowRequeue.js

@@ -19,7 +19,14 @@ function taskPriority(hasExternalSignal, lens) {
     }
     return hasExternalSignal ? "medium" : "low";
 }
-export function buildFlowRequeueTasks(criticalFlows, flowCoverage, externalAnalyzerResults) {
+function fileStillNeedsLens(coverageMatrix, path, lens) {
+    const record = coverageMatrix.files.find((file) => file.path === path);
+    if (!record || record.audit_status === "excluded") {
+        return false;
+    }
+    return !record.completed_lenses.includes(lens);
+}
+export function buildFlowRequeueTasks(criticalFlows, flowCoverage, coverageMatrix, externalAnalyzerResults) {
     const flowMap = new Map(criticalFlows.flows.map((flow) => [flow.id, flow]));
     const tasks = [];
     const seen = new Set();
@@ -35,6 +42,9 @@ export function buildFlowRequeueTasks(criticalFlows, flowCoverage, externalAnaly
                 continue;
             }
             for (const path of flow.paths) {
+                if (!fileStillNeedsLens(coverageMatrix, path, lensName)) {
+                    continue;
+                }
                 const signature = `${flow.id}|${lensName}|${path}`;
                 if (seen.has(signature)) {
                     continue;
@@ -49,7 +59,10 @@ export function buildFlowRequeueTasks(criticalFlows, flowCoverage, externalAnaly
                     file_paths: [path],
                     rationale: `Requeue ${path} because critical flow ${flow.id} is still missing the ${lensName} lens.${hasExternalSignal ? " External analyzer signals make this follow-up higher priority." : ""}`,
                     priority: taskPriority(hasExternalSignal, lensName),
-                    tags: hasExternalSignal ? ["external_analyzer_signal"] : [],
+                    tags: hasExternalSignal
+                        ? ["critical_flow_followup", "external_analyzer_signal"]
+                        : ["critical_flow_followup"],
+                    status: "pending",
                 });
             }
         }

package/dist/orchestrator/internalExecutors.js

@@ -13,8 +13,16 @@ import { buildChunkedAuditTasks, buildExternalSignalTasks, } from "./taskBuilder
 import { buildUnitManifest } from "./unitBuilder.js";
 import { buildRepoManifestFromFs } from "../extractors/fsIntake.js";
 import { loadIgnoreFile } from "../extractors/ignore.js";
-import { ingestAuditResults } from "./resultIngestion.js";
+import { ingestAuditResults, updateAuditTaskStatuses, } from "./resultIngestion.js";
 import { updateRuntimeValidationReport } from "./runtimeValidationUpdate.js";
+import { autoCompleteTrivialCoverage } from "./trivialAudit.js";
+function buildSynthesisArtifacts(synthesisReport) {
+    return {
+        synthesis_report: synthesisReport,
+        merged_findings: { findings: synthesisReport.merged_findings },
+        root_cause_clusters: { clusters: synthesisReport.root_cause_clusters },
+    };
+}
 function preserveOrPlaceholder(tasks, existing) {
     return existing
         ? mergeRuntimeValidationReport(tasks, existing)
@@ -83,6 +91,7 @@ export function runPlanningExecutor(bundle, lineIndex = {}) {
     }
     const externalAnalyzerResults = bundle.external_analyzer_results;
     const coverage = initializeCoverageFromPlan(bundle.repo_manifest, bundle.unit_manifest, bundle.file_disposition, externalAnalyzerResults);
+    const autoSkippedTrivialFiles = autoCompleteTrivialCoverage(coverage, lineIndex, externalAnalyzerResults);
     const flowCoverage = buildFlowCoverage(bundle.critical_flows, coverage);
     const runtimeValidationTasks = buildRuntimeValidationTasks(bundle.unit_manifest, bundle.critical_flows, flowCoverage);
     const runtimeValidationReport = preserveOrPlaceholder(runtimeValidationTasks, bundle.runtime_validation_report);
@@ -91,7 +100,10 @@ export function runPlanningExecutor(bundle, lineIndex = {}) {
     });
     const analyzerTasks = buildExternalSignalTasks(coverage, lineIndex, externalAnalyzerResults);
     const flowTasks = buildFlowAwareTaskAugmentations([...baseTasks, ...analyzerTasks], bundle.critical_flows, lineIndex);
-    const auditTasks = [...baseTasks, ...analyzerTasks, ...flowTasks];
+    const auditTasks = [...baseTasks, ...analyzerTasks, ...flowTasks].map((task) => ({
+        ...task,
+        status: task.status ?? "pending",
+    }));
     const requeuePayload = buildRequeuePayload(coverage, bundle.critical_flows, flowCoverage, externalAnalyzerResults);
     return {
         updated: {
@@ -111,7 +123,13 @@ export function runPlanningExecutor(bundle, lineIndex = {}) {
             "audit_tasks.json",
             "requeue_tasks.json",
         ],
-        progress_summary: `Built planning artifacts; generated ${auditTasks.length} tasks and ${requeuePayload.task_count} requeue tasks.${externalAnalyzerResults?.results.length ? ` External analyzer signals influenced lenses and produced ${analyzerTasks.length} dedicated follow-up task(s).` : ""}`,
+        progress_summary: `Built planning artifacts; generated ${auditTasks.length} tasks and ${requeuePayload.task_count} requeue tasks.` +
+            (autoSkippedTrivialFiles.length > 0
+                ? ` Auto-completed ${autoSkippedTrivialFiles.length} trivial file${autoSkippedTrivialFiles.length === 1 ? "" : "s"} without dispatch.`
+                : "") +
+            (externalAnalyzerResults?.results.length
+                ? ` External analyzer signals influenced lenses and produced ${analyzerTasks.length} dedicated follow-up task(s).`
+                : ""),
     };
 }
 export function runResultIngestionExecutor(bundle, results) {
@@ -130,7 +148,9 @@ export function runResultIngestionExecutor(bundle, results) {
         : bundle.runtime_validation_report;
     const requeuePayload = buildRequeuePayload(updatedCoverageMatrix, bundle.critical_flows, flowCoverage, bundle.external_analyzer_results);
     const mergedResults = [...(bundle.audit_results ?? []), ...results];
+    const updatedAuditTasks = updateAuditTaskStatuses(bundle.audit_tasks, mergedResults);
     const synthesisReport = buildSynthesisReport(mergedResults, runtimeValidationReport, bundle.external_analyzer_results);
+    const synthesisArtifacts = buildSynthesisArtifacts(synthesisReport);
     return {
         updated: {
             ...bundle,
@@ -139,8 +159,9 @@ export function runResultIngestionExecutor(bundle, results) {
             runtime_validation_tasks: runtimeValidationTasks,
             runtime_validation_report: runtimeValidationReport,
             audit_results: mergedResults,
+            audit_tasks: updatedAuditTasks,
             requeue_tasks: requeuePayload.tasks,
-            synthesis_report: synthesisReport,
+            ...synthesisArtifacts,
         },
         artifacts_written: [
             "coverage_matrix.json",
@@ -148,7 +169,10 @@ export function runResultIngestionExecutor(bundle, results) {
             "runtime_validation_tasks.json",
             "runtime_validation_report.json",
             "audit_results.jsonl",
+            "audit_tasks.json",
             "requeue_tasks.json",
+            "merged_findings.json",
+            "root_cause_clusters.json",
             "synthesis_report.json",
         ],
         progress_summary: `Ingested ${results.length} audit result entries and refreshed dependent artifacts.`,
@@ -162,14 +186,17 @@ export function runRuntimeValidationUpdateExecutor(bundle, updates) {
         buildPlaceholderRuntimeValidationReport(bundle.runtime_validation_tasks);
     const mergedReport = updateRuntimeValidationReport(bundle.runtime_validation_tasks, existingReport, updates);
     const synthesisReport = buildSynthesisReport(bundle.audit_results ?? [], mergedReport, bundle.external_analyzer_results);
+    const synthesisArtifacts = buildSynthesisArtifacts(synthesisReport);
     return {
         updated: {
             ...bundle,
             runtime_validation_report: mergedReport,
-            synthesis_report: synthesisReport,
+            ...synthesisArtifacts,
         },
         artifacts_written: [
             "runtime_validation_report.json",
+            "merged_findings.json",
+            "root_cause_clusters.json",
             "synthesis_report.json",
         ],
         progress_summary: `Merged ${updates.results.length} runtime validation updates.`,
@@ -178,15 +205,12 @@ export function runRuntimeValidationUpdateExecutor(bundle, updates) {
 export function runSynthesisExecutor(bundle, results) {
     const finalResults = results ?? bundle.audit_results ?? [];
     const synthesisReport = buildSynthesisReport(finalResults, bundle.runtime_validation_report, bundle.external_analyzer_results);
-    const mergedFindings = { findings: synthesisReport.merged_findings };
-    const rootCauseClusters = { clusters: synthesisReport.root_cause_clusters };
+    const synthesisArtifacts = buildSynthesisArtifacts(synthesisReport);
     return {
         updated: {
             ...bundle,
             audit_results: finalResults,
-            merged_findings: mergedFindings,
-            root_cause_clusters: rootCauseClusters,
-            synthesis_report: synthesisReport,
+            ...synthesisArtifacts,
         },
         artifacts_written: [
             "merged_findings.json",

package/dist/orchestrator/requeue.js

@@ -18,6 +18,7 @@ export function buildRequeueTasks(matrix, externalAnalyzerResults) {
                 rationale: `Requeue ${target.path} because the ${lens} lens is still missing.${hasExternalSignal ? " External analyzer signals make this follow-up higher priority." : ""}`,
                 priority: taskPriority(hasExternalSignal),
                 tags: hasExternalSignal ? ["external_analyzer_signal"] : [],
+                status: "pending",
             });
         }
     }

package/dist/orchestrator/requeueCommand.js

@@ -12,12 +12,25 @@ function dedupeTasks(tasks) {
     }
     return deduped;
 }
+function dedupeByScope(tasks) {
+    const seen = new Set();
+    const deduped = [];
+    for (const task of tasks) {
+        const signature = `${task.lens}:${[...task.file_paths].sort().join(",")}`;
+        if (seen.has(signature)) {
+            continue;
+        }
+        seen.add(signature);
+        deduped.push(task);
+    }
+    return deduped;
+}
 export function buildRequeuePayload(matrix, criticalFlows, flowCoverage, externalAnalyzerResults) {
     const fileTasks = dedupeTasks(buildRequeueTasks(matrix, externalAnalyzerResults));
     const flowTasks = criticalFlows && flowCoverage
-        ? dedupeTasks(buildFlowRequeueTasks(criticalFlows, flowCoverage, externalAnalyzerResults))
+        ? dedupeTasks(buildFlowRequeueTasks(criticalFlows, flowCoverage, matrix, externalAnalyzerResults))
         : [];
-    const tasks = dedupeTasks([...fileTasks, ...flowTasks]);
+    const tasks = dedupeByScope(dedupeTasks([...fileTasks, ...flowTasks]));
     return {
         task_count: tasks.length,
         file_task_count: fileTasks.length,

package/dist/orchestrator/resultIngestion.d.ts

@@ -1,2 +1,3 @@
-import type { AuditResult, CoverageMatrix } from "../types.js";
+import type { AuditResult, AuditTask, CoverageMatrix } from "../types.js";
 export declare function ingestAuditResults(coverageMatrix: CoverageMatrix, results: AuditResult[]): CoverageMatrix;
+export declare function updateAuditTaskStatuses(tasks: AuditTask[] | undefined, results: AuditResult[]): AuditTask[] | undefined;

package/dist/orchestrator/resultIngestion.js

@@ -12,3 +12,24 @@ export function ingestAuditResults(coverageMatrix, results) {
     applyReviewedRanges(matrix, reviewedRanges);
     return matrix;
 }
+export function updateAuditTaskStatuses(tasks, results) {
+    if (!tasks) {
+        return undefined;
+    }
+    const completedTaskIds = new Set(results.map((result) => result.task_id));
+    const completedAt = new Date().toISOString();
+    return tasks.map((task) => {
+        if (completedTaskIds.has(task.task_id)) {
+            return {
+                ...task,
+                status: "complete",
+                completed_at: task.completed_at ?? completedAt,
+                completion_reason: task.completion_reason ?? "result_ingested",
+            };
+        }
+        return {
+            ...task,
+            status: task.status ?? "pending",
+        };
+    });
+}

package/dist/orchestrator/state.js

@@ -43,12 +43,21 @@ export function deriveAuditState(bundle) {
         "requeue_tasks.json",
     ], planningReady)));
     const hasRequiredCoverage = bundle.coverage_matrix?.files.every((f) => f.required_lenses.every((req) => f.completed_lenses.includes(req))) ?? true;
+    const hasCompletedTaskStatuses = bundle.audit_tasks?.length
+        ? bundle.audit_tasks.every((task) => task.status === "complete")
+        : false;
+    const hasResultForEveryTask = bundle.audit_tasks?.length && bundle.audit_results
+        ? bundle.audit_tasks.every((task) => bundle.audit_results?.some((result) => result.task_id === task.task_id))
+        : false;
     if (!hasRequiredCoverage &&
+        !hasCompletedTaskStatuses &&
+        !hasResultForEveryTask &&
         has(bundle.audit_tasks) &&
         (bundle.audit_tasks?.length ?? 0) > 0) {
         obligations.push(obligation("audit_tasks_completed", "missing"));
     }
-    else if (hasRequiredCoverage && has(bundle.audit_tasks)) {
+    else if ((hasRequiredCoverage || hasCompletedTaskStatuses || hasResultForEveryTask) &&
+        has(bundle.audit_tasks)) {
         obligations.push(obligation("audit_tasks_completed", "satisfied"));
     }
     obligations.push(obligation("audit_results_ingested", has(bundle.audit_results) ? "present" : "missing"));

package/dist/orchestrator/taskBuilder.js

@@ -1,3 +1,4 @@
+import { isTrivialAuditPath } from "./trivialAudit.js";
 function taskPriority(hasExternalSignal, lens) {
     if (hasExternalSignal &&
         (lens === "security" || lens === "data_integrity" || lens === "reliability")) {
@@ -57,12 +58,13 @@ export function buildChunkedAuditTasks(unitManifest, unitLineIndex, options = {}
             const hasExternalSignal = unit.files.some((f) => externalPaths.has(f));
             const priority = taskPriority(hasExternalSignal, lens);
             const tags = hasExternalSignal ? ["external_analyzer_signal"] : [];
+            const candidateFiles = unit.files.filter((filePath) => !isTrivialAuditPath(filePath, unitLineIndex[filePath] ?? 0, externalPaths.has(filePath)));
             // Split files that are individually too large to group; everything else
             // goes into one task so the agent can reason across file boundaries.
             const oversizedFiles = fileSplitThreshold > 0
-                ? unit.files.filter((f) => (unitLineIndex[f] ?? 0) > fileSplitThreshold)
+                ? candidateFiles.filter((f) => (unitLineIndex[f] ?? 0) > fileSplitThreshold)
                 : [];
-            const normalFiles = unit.files.filter((f) => !oversizedFiles.includes(f));
+            const normalFiles = candidateFiles.filter((f) => !oversizedFiles.includes(f));
             // One task for all normal-sized files in this unit under this lens.
             if (normalFiles.length > 0) {
                 const id = `${unit.unit_id}:${lens}`;

package/dist/orchestrator/trivialAudit.d.ts

@@ -0,0 +1,4 @@
+import type { CoverageMatrix } from "../types.js";
+import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
+export declare function isTrivialAuditPath(path: string, lineCount: number, hasExternalSignal?: boolean): boolean;
+export declare function autoCompleteTrivialCoverage(coverage: CoverageMatrix, lineIndex: Record<string, number>, externalAnalyzerResults?: ExternalAnalyzerResults): string[];

package/dist/orchestrator/trivialAudit.js

@@ -0,0 +1,46 @@
+const TRIVIAL_DOTFILES = new Set([".gitignore", ".gitattributes"]);
+function basename(path) {
+    const normalized = path.replaceAll("\\", "/");
+    const parts = normalized.split("/");
+    return parts[parts.length - 1] ?? normalized;
+}
+export function isTrivialAuditPath(path, lineCount, hasExternalSignal = false) {
+    if (hasExternalSignal) {
+        return false;
+    }
+    if (lineCount === 0) {
+        return true;
+    }
+    const name = basename(path).toLowerCase();
+    if (TRIVIAL_DOTFILES.has(name)) {
+        return true;
+    }
+    // Empty package markers and docstring-only __init__.py files create a lot of
+    // audit churn without adding meaningful coverage signal.
+    if (name === "__init__.py" && lineCount <= 3) {
+        return true;
+    }
+    return false;
+}
+export function autoCompleteTrivialCoverage(coverage, lineIndex, externalAnalyzerResults) {
+    const externalPaths = new Set((externalAnalyzerResults?.results ?? []).map((item) => item.path));
+    const skipped = [];
+    for (const file of coverage.files) {
+        if (file.audit_status === "excluded") {
+            continue;
+        }
+        if (!isTrivialAuditPath(file.path, lineIndex[file.path] ?? 0, externalPaths.has(file.path))) {
+            continue;
+        }
+        if (file.required_lenses.length === 0) {
+            continue;
+        }
+        file.completed_lenses = [...new Set(file.required_lenses)];
+        file.audit_status = "complete";
+        if (file.classification_status === "unclassified") {
+            file.classification_status = "classified";
+        }
+        skipped.push(file.path);
+    }
+    return skipped.sort();
+}

package/dist/prompts/renderWorkerPrompt.js

@@ -20,12 +20,15 @@ export function renderWorkerPrompt(task) {
             "  2. Review the content under the specified lens.",
             "  3. Emit one AuditResult with:",
             "       task_id, unit_id, pass_id, lens",
-            "       reviewed_ranges: [{path, start, end}] covering what you read",
+            "       reviewed_ranges: [{path, start, end, line_count}] covering what you read",
             "       findings: array (empty if nothing found)",
+            "     line_count must match the file's current total line count so ingestion can verify the cited ranges.",
             "     Each finding must include:",
             "       id, title, category, severity, confidence, lens, summary, affected_files,",
-            "       evidence (at least one excerpt or line reference from the file you read)",
+            "       evidence (an 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",
             "     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.",
             `Write the AuditResult[] JSON array to: ${task.audit_results_path}`,
         ];
         if (task.skip_worker_command) {

package/dist/providers/spawnLoggedCommand.js

@@ -11,14 +11,25 @@ export async function spawnLoggedCommand(command, args, input, env) {
     return await new Promise((resolve, reject) => {
         const stdoutLog = createWriteStream(input.stdoutPath, { flags: "a" });
         const stderrLog = createWriteStream(input.stderrPath, { flags: "a" });
+        const startedAt = Date.now();
+        let timedOut = false;
         const child = spawn(command, args, {
             cwd: input.repoRoot,
             env: { ...process.env, ...env },
             stdio: ["ignore", "pipe", "pipe"],
         });
         const timer = setTimeout(() => {
+            timedOut = true;
             child.kill("SIGTERM");
         }, input.timeoutMs);
+        const heartbeat = setInterval(() => {
+            const elapsedMs = Date.now() - startedAt;
+            const message = `[provider] run ${input.runId} still running after ${elapsedMs}ms\n`;
+            tee(stderrLog, message);
+            if (input.uiMode === "visible") {
+                process.stderr.write(message);
+            }
+        }, 30_000);
         child.stdout.on("data", (chunk) => {
             tee(stdoutLog, chunk);
             if (input.uiMode === "visible") {
@@ -33,14 +44,20 @@ export async function spawnLoggedCommand(command, args, input, env) {
         });
         child.on("error", (error) => {
             clearTimeout(timer);
+            clearInterval(heartbeat);
             stdoutLog.end();
             stderrLog.end();
             reject(error);
         });
         child.on("exit", (code, signal) => {
             clearTimeout(timer);
+            clearInterval(heartbeat);
             stdoutLog.end();
             stderrLog.end();
+            if (timedOut) {
+                reject(new Error(`Fresh session timed out after ${input.timeoutMs}ms for run ${input.runId}.`));
+                return;
+            }
             resolve({
                 accepted: true,
                 processId: child.pid,

package/dist/reporting/mergeFindings.js

@@ -42,7 +42,9 @@ function runtimeSummary(report) {
     if (!report) {
         return [];
     }
-    return report.results.map((result) => `${result.task_id}: ${result.status} — ${result.summary}`);
+    return report.results
+        .filter((result) => result.status !== "pending")
+        .map((result) => `${result.task_id}: ${result.status} — ${result.summary}`);
 }
 function externalSummary(results) {
     if (!results) {
@@ -80,9 +82,9 @@ export function mergeFindings(results, runtimeReport, externalAnalyzerResults) {
                             ...analyzerEvidence,
                         ]),
                     ],
-                    related_findings: [
-                        ...new Set([...(finding.related_findings ?? []), finding.id]),
-                    ],
+                    related_findings: finding.related_findings && finding.related_findings.length > 0
+                        ? [...new Set(finding.related_findings)]
+                        : undefined,
                 });
                 continue;
             }
@@ -108,13 +110,14 @@ export function mergeFindings(results, runtimeReport, externalAnalyzerResults) {
                     ...analyzerEvidence,
                 ]),
             ];
-            existing.related_findings = [
-                ...new Set([
-                    ...(existing.related_findings ?? []),
-                    ...(finding.related_findings ?? []),
-                    finding.id,
-                ]),
-            ];
+            const related = new Set([
+                ...(existing.related_findings ?? []),
+                ...(finding.related_findings ?? []),
+                existing.id,
+                finding.id,
+            ]);
+            existing.related_findings =
+                related.size > 0 ? [...related].sort() : undefined;
         }
     }
     return [...merged.values()].sort((a, b) => {

package/dist/reporting/rootCause.js

@@ -29,14 +29,94 @@ function summarizeExternal(results) {
         return "No external analyzer signals attached.";
     return `${results.tool}:${results.results.length}`;
 }
+const STOP_WORDS = new Set([
+    "a",
+    "an",
+    "and",
+    "are",
+    "be",
+    "by",
+    "for",
+    "from",
+    "in",
+    "into",
+    "is",
+    "missing",
+    "not",
+    "of",
+    "on",
+    "or",
+    "that",
+    "the",
+    "this",
+    "to",
+    "under",
+    "when",
+    "with",
+]);
+function normalizeToken(token) {
+    if (token.endsWith("ies") && token.length > 4) {
+        return `${token.slice(0, -3)}y`;
+    }
+    if (token.endsWith("ing") && token.length > 6) {
+        return token.slice(0, -3);
+    }
+    if (token.endsWith("ed") && token.length > 5) {
+        return token.slice(0, -2);
+    }
+    if (token.endsWith("s") && token.length > 4) {
+        return token.slice(0, -1);
+    }
+    return token;
+}
+function extractSemanticTerms(finding) {
+    const source = [
+        finding.title,
+        finding.summary,
+        ...(finding.evidence ?? []).slice(0, 2),
+    ]
+        .join(" ")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ");
+    const terms = source
+        .split(/\s+/)
+        .map(normalizeToken)
+        .filter((token) => token.length >= 3 &&
+        !STOP_WORDS.has(token) &&
+        token !== finding.lens &&
+        token !== finding.category &&
+        !/^\d+$/.test(token));
+    return [...new Set(terms)];
+}
 function clusterKey(finding) {
-    const primaryPath = finding.affected_files[0]?.path ?? "";
-    const pathPrefix = primaryPath.split("/").slice(0, 2).join("/");
-    return `${finding.lens}:${finding.category}:${pathPrefix}`;
+    const semanticTerms = extractSemanticTerms(finding).slice(0, 3).join(" ");
+    return `${finding.lens}:${finding.category}:${semanticTerms || finding.title.toLowerCase()}`;
+}
+function representativeFinding(grouped) {
+    return [...grouped].sort((a, b) => {
+        const severityDelta = severityRank(b.severity) - severityRank(a.severity);
+        if (severityDelta !== 0)
+            return severityDelta;
+        const systemicDelta = Number(Boolean(b.systemic)) - Number(Boolean(a.systemic));
+        if (systemicDelta !== 0)
+            return systemicDelta;
+        return a.title.localeCompare(b.title);
+    })[0];
+}
+function titleForCluster(grouped) {
+    return representativeFinding(grouped).title;
 }
-function titleForCluster(key) {
-    const [lens, category, scope] = key.split(":");
-    return `${lens}/${category}${scope ? ` in ${scope}` : ""}`;
+function summarizeFiles(grouped) {
+    const paths = [
+        ...new Set(grouped.flatMap((finding) => finding.affected_files.map((file) => file.path))),
+    ].sort();
+    if (paths.length === 0) {
+        return "no representative files recorded";
+    }
+    if (paths.length <= 3) {
+        return paths.join(", ");
+    }
+    return `${paths.slice(0, 3).join(", ")}, +${paths.length - 3} more`;
 }
 export function buildRootCauseClusters(findings, runtimeReport, externalAnalyzerResults) {
     const groups = new Map();
@@ -50,12 +130,15 @@ export function buildRootCauseClusters(findings, runtimeReport, externalAnalyzer
     const externalSummary = summarizeExternal(externalAnalyzerResults);
     return [...groups.entries()]
         .map(([key, grouped], index) => {
-        const highestSeverity = grouped.reduce((max, finding) => Math.max(max, severityRank(finding.severity)), 1);
+        const representative = representativeFinding(grouped);
         const systemicCount = grouped.filter((finding) => finding.systemic).length;
+        const theme = key.split(":").slice(2).join(":") || representative.title;
         return {
             id: `cluster-${index + 1}`,
-            title: titleForCluster(key),
-            summary: `Grouped ${grouped.length} finding(s); highest severity ${highestSeverity}; systemic flags ${systemicCount}. Runtime validation status: ${runtimeSummary}. External analyzer summary: ${externalSummary}.`,
+            title: titleForCluster(grouped),
+            summary: `Theme "${theme}" groups ${grouped.length} finding(s) across ${summarizeFiles(grouped)}; ` +
+                `highest severity ${representative.severity}; systemic flags ${systemicCount}. ` +
+                `Runtime validation status: ${runtimeSummary}. External analyzer summary: ${externalSummary}.`,
             finding_ids: grouped.map((finding) => finding.id),
         };
     })

package/dist/supervisor/sessionConfig.js

@@ -1,5 +1,6 @@
 import { readOptionalJsonFile } from "../io/json.js";
 import { validateSessionConfig } from "../validation/sessionConfig.js";
+import { writeJsonFile } from "../io/json.js";
 export function getSessionConfigPath(artifactsDir) {
     return `${artifactsDir}/session-config.json`;
 }
@@ -16,8 +17,9 @@ export async function loadSessionConfig(artifactsDir) {
     const configPath = getSessionConfigPath(artifactsDir);
     const rawConfig = await readOptionalJsonFile(configPath);
     if (rawConfig === undefined) {
-        process.stderr.write(`[session-config] no session-config.json found at ${configPath}; using empty defaults\n`);
-        return {};
+        const defaultConfig = { provider: "local-subprocess" };
+        await writeJsonFile(configPath, defaultConfig);
+        return defaultConfig;
     }
     const issues = validateSessionConfig(rawConfig);
     if (issues.length > 0) {

package/dist/types.d.ts

@@ -47,6 +47,7 @@ export interface CoverageFileRecord {
 export interface CoverageMatrix {
     files: CoverageFileRecord[];
 }
+export type AuditTaskStatus = "pending" | "complete";
 export interface AuditTask {
     task_id: string;
     unit_id: string;
@@ -62,6 +63,9 @@ export interface AuditTask {
     rationale: string;
     priority?: "high" | "medium" | "low";
     tags?: string[];
+    status?: AuditTaskStatus;
+    completed_at?: string;
+    completion_reason?: string;
 }
 export interface Finding {
     id: string;
@@ -94,6 +98,7 @@ export interface AuditResult {
         path: string;
         start: number;
         end: number;
+        line_count: number;
     }>;
     findings: Finding[];
     notes?: string[];

package/dist/validation/auditResults.d.ts

@@ -1,4 +1,4 @@
-import type { AuditResult, AuditTask } from "../types.js";
+import type { AuditTask } from "../types.js";
 export type IssueSeverity = "error" | "warning";
 export interface AuditResultIssue {
     result_index: number;
@@ -7,5 +7,8 @@ export interface AuditResultIssue {
     field: string;
     message: string;
 }
-export declare function validateAuditResults(results: AuditResult[], tasks: AuditTask[]): AuditResultIssue[];
+export interface ValidateAuditResultOptions {
+    lineIndex?: Record<string, number>;
+}
+export declare function validateAuditResults(results: unknown, tasks: AuditTask[], options?: ValidateAuditResultOptions): AuditResultIssue[];
 export declare function formatAuditResultIssues(issues: AuditResultIssue[]): string;