auditor-lambda 0.10.2 → 0.10.7

package/dist/orchestrator/taskBuilder.js

@@ -131,6 +131,9 @@ function addTaskBlock(params, context) {
         });
     }
 }
+function withSignalTag(baseTags, hasExternalSignal) {
+    return hasExternalSignal ? [...baseTags, "external_analyzer_signal"] : baseTags;
+}
 function buildCoverageIndex(coverageMatrix) {
     return new Map(coverageMatrix.files.map((file) => [file.path, file]));
 }
@@ -206,9 +209,7 @@ export function buildChunkedAuditTasks(coverageMatrix, unitLineIndex, options =
             lens: block.lens,
             filePaths: block.file_paths,
             priority: taskPriority(hasExternalSignal, block.lens, true),
-            tags: hasExternalSignal
-                ? ["critical_flow", `critical_flow:${block.flow_id}`, "external_analyzer_signal"]
-                : ["critical_flow", `critical_flow:${block.flow_id}`],
+            tags: withSignalTag(["critical_flow", `critical_flow:${block.flow_id}`], hasExternalSignal),
             rationale: (filePaths, splitKind) => splitKind === "large_file"
                 ? `Audit ${filePaths[0]} (large file from critical flow ${block.flow_id}) under the ${block.lens} lens.${hasExternalSignal ? " External analyzer signals raise priority." : ""}`
                 : splitKind === "budget"
@@ -259,7 +260,7 @@ export function buildChunkedAuditTasks(coverageMatrix, unitLineIndex, options =
             lens: block.lens,
             filePaths: block.filePaths,
             priority: taskPriority(hasExternalSignal, block.lens),
-            tags: hasExternalSignal ? ["external_analyzer_signal"] : [],
+            tags: withSignalTag([], hasExternalSignal),
             rationale: (filePaths, splitKind) => splitKind === "large_file"
                 ? `Audit ${filePaths[0]} (large file split from ${block.unitId}) under the ${block.lens} lens.${hasExternalSignal ? " External analyzer signals raise priority." : ""}`
                 : splitKind === "budget"

package/dist/providers/claudeCodeProvider.js

@@ -29,9 +29,12 @@ export class ClaudeCodeProvider {
                 ? ["--dangerously-skip-permissions"]
                 : []),
         ];
-        return await this.launchCommand(command, args, applyWorkerTaskLaunchSettings(input, task), undefined, {
+        process.stderr.write(JSON.stringify({ event: "provider_launch", provider: this.name, runId: input.runId, obligationId: input.obligationId, promptPath: input.promptPath, taskPath: input.taskPath }) + "\n");
+        const result = await this.launchCommand(command, args, applyWorkerTaskLaunchSettings(input, task), undefined, {
             opentoken: this.opentoken.enabled,
             opentokenCommand: this.opentoken.command,
         });
+        process.stderr.write(JSON.stringify({ event: "provider_done", provider: this.name, runId: input.runId, obligationId: input.obligationId, accepted: result.accepted, exitCode: result.exitCode ?? null }) + "\n");
+        return result;
     }
 }

package/dist/providers/opencodeProvider.js

@@ -16,9 +16,12 @@ export class OpenCodeProvider {
         // On Windows the `opencode` launcher is a `.cmd` shim that `spawn` cannot
         // run without a shell; resolve it through cmd.exe (no-op on other OSes).
         const { command, args } = resolveOpenCodeSpawnCommand(baseCommand, baseArgs);
-        return await spawnLoggedCommand(command, args, applyWorkerTaskLaunchSettings(input, task), undefined, {
+        process.stderr.write(JSON.stringify({ event: "provider_launch", provider: this.name, runId: input.runId, obligationId: input.obligationId, promptPath: input.promptPath, taskPath: input.taskPath }) + "\n");
+        const result = await spawnLoggedCommand(command, args, applyWorkerTaskLaunchSettings(input, task), undefined, {
             opentoken: this.opentoken.enabled,
             opentokenCommand: this.opentoken.command,
         });
+        process.stderr.write(JSON.stringify({ event: "provider_done", provider: this.name, runId: input.runId, obligationId: input.obligationId, accepted: result.accepted, exitCode: result.exitCode ?? null }) + "\n");
+        return result;
     }
 }

package/dist/quota/discoveredLimits.js

@@ -1,8 +1,8 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { getQuotaStatePath } from "@audit-tools/shared";
 function getCachePath() {
-    return getQuotaStatePath().replace(/quota-state\.json$/, "discovered-limits.json");
+    return join(dirname(getQuotaStatePath()), "discovered-limits.json");
 }
 export async function readDiscoveredLimitsCache() {
     try {
@@ -17,7 +17,7 @@ export async function readDiscoveredLimitsCache() {
     }
     catch (error) {
         if (error.code !== "ENOENT") {
-            process.stderr.write(`[quota] ignoring unreadable discovered-limits cache: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.stderr.write(`[quota] ignoring unreadable discovered-limits cache (${getCachePath()}): ${error instanceof Error ? error.message : String(error)}\n`);
         }
     }
     return { version: 1, entries: {} };

package/dist/quota/headerExtraction.js

@@ -30,7 +30,7 @@ function parseResetValue(value) {
 }
 function parseNumericValue(value) {
     const n = parseInt(value, 10);
-    return Number.isFinite(n) && n > 0 ? n : null;
+    return Number.isFinite(n) && n >= 0 ? n : null;
 }
 export function extractRateLimitHeaders(text) {
     const result = {
@@ -68,6 +68,9 @@ export function extractRateLimitHeaders(text) {
         if (jsonResult)
             return jsonResult;
     }
+    if (!found && text.trim().length > 0) {
+        process.stderr.write("[quota] header extraction: no rate-limit data found in non-empty stderr text (possible provider format change)\n");
+    }
     return found ? result : null;
 }
 function extractFromJson(text) {
@@ -108,7 +111,7 @@ function extractFromHeaderObject(headers) {
             const val = headers[key] ?? headers[key.toLowerCase()];
             if (val != null) {
                 const n = typeof val === "number" ? val : parseInt(String(val), 10);
-                if (Number.isFinite(n) && n > 0)
+                if (Number.isFinite(n) && n >= 0)
                     return n;
             }
         }

package/dist/quota/headerExtractors/claudeCodeHeaderExtractor.js

@@ -23,6 +23,9 @@ export class ClaudeCodeHeaderExtractor {
             return extractRateLimitHeaders(candidates.join("\n"));
         }
         // Fall back to scanning the full text for raw header lines
+        if (stderr.trim().length > 0) {
+            process.stderr.write("[quota] claude-code header extractor: no structured JSON lines with headers/response_headers found in non-empty stderr; falling back to raw-text scan\n");
+        }
         return extractRateLimitHeaders(stderr);
     }
 }

package/dist/quota/headerExtractors/index.js

@@ -3,10 +3,10 @@ export { ClaudeCodeHeaderExtractor } from "./claudeCodeHeaderExtractor.js";
 import { GenericHeaderExtractor } from "./genericHeaderExtractor.js";
 import { ClaudeCodeHeaderExtractor } from "./claudeCodeHeaderExtractor.js";
 const PROVIDER_EXTRACTORS = {
-    "claude-code": () => new ClaudeCodeHeaderExtractor(),
+    "claude-code": new ClaudeCodeHeaderExtractor(),
 };
 const genericExtractor = new GenericHeaderExtractor();
 export function getHeaderExtractorForProvider(providerName) {
-    const factory = PROVIDER_EXTRACTORS[providerName];
-    return factory ? factory() : genericExtractor;
+    const extractor = PROVIDER_EXTRACTORS[providerName];
+    return extractor ?? genericExtractor;
 }

package/dist/quota/index.d.ts

@@ -12,8 +12,10 @@ export { extractRateLimitHeaders } from "./headerExtraction.js";
 export type { ExtractedRateLimits } from "./headerExtraction.js";
 export type { HeaderExtractor } from "./headerExtractors/index.js";
 export { GenericHeaderExtractor, ClaudeCodeHeaderExtractor, getHeaderExtractorForProvider } from "./headerExtractors/index.js";
+export declare const DISPATCH_QUOTA_V1ALPHA1: "audit-code-dispatch-quota/v1alpha1";
+export declare const DISPATCH_QUOTA_V1ALPHA2: "audit-code-dispatch-quota/v1alpha2";
 export interface DispatchQuota {
-    contract_version: "audit-code-dispatch-quota/v1alpha1" | "audit-code-dispatch-quota/v1alpha2";
+    contract_version: typeof DISPATCH_QUOTA_V1ALPHA1 | typeof DISPATCH_QUOTA_V1ALPHA2;
     run_id: string;
     model: string | null;
     resolved_limits: _ResolvedLimits;

package/dist/quota/index.js

@@ -13,3 +13,6 @@ export { detectHostActiveSubagentLimit, resolveHostActiveSubagentLimit, } from "
 export { lookupDiscoveredLimits, updateDiscoveredLimits, mergeDiscoveredLimits, readDiscoveredLimitsCache, writeDiscoveredLimitsCache, } from "./discoveredLimits.js";
 export { extractRateLimitHeaders } from "./headerExtraction.js";
 export { GenericHeaderExtractor, ClaudeCodeHeaderExtractor, getHeaderExtractorForProvider } from "./headerExtractors/index.js";
+// Auditor-only type (not in shared)
+export const DISPATCH_QUOTA_V1ALPHA1 = "audit-code-dispatch-quota/v1alpha1";
+export const DISPATCH_QUOTA_V1ALPHA2 = "audit-code-dispatch-quota/v1alpha2";

package/dist/reporting/findingIdentity.d.ts

@@ -0,0 +1,21 @@
+import type { Finding } from "../types.js";
+/**
+ * Re-key finalized findings with globally-unique, content-derived ids at the
+ * synthesis boundary.
+ *
+ * Worker packets assign locally-scoped ids (e.g. `MNT-001`) that collide across
+ * packets once merged, which breaks `audit-findings.json` as a machine contract:
+ * `buildWorkBlocks` keys its union-find on `id` (so colliding ids fuse unrelated
+ * findings into one block), and `work_blocks.finding_ids` / theme `finding_ids` /
+ * the remediator's per-finding addressing can no longer resolve a single finding.
+ *
+ * The id is `<LENS_PREFIX>-<sha256(content)[:8]>`, deterministic and stable so a
+ * re-synthesis of the same findings produces the same ids. A vanishingly rare
+ * hash collision between two *distinct* findings is broken deterministically with
+ * a numeric suffix (findings arrive in mergeFindings()' stable order).
+ *
+ * `related_findings`, when present, referenced the old colliding ids and cannot
+ * be remapped unambiguously, so it is dropped rather than left dangling. (It is
+ * unpopulated by every current extractor.)
+ */
+export declare function assignStableFindingIds(findings: Finding[]): Finding[];

package/dist/reporting/findingIdentity.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+// Stable lens -> id prefix. The lens is the canonical addressing axis, so the
+// prefix always matches it (no convention drift) and the content hash that
+// follows guarantees global uniqueness.
+const LENS_ID_PREFIX = {
+    correctness: "COR",
+    architecture: "ARC",
+    maintainability: "MNT",
+    security: "SEC",
+    reliability: "REL",
+    performance: "PRF",
+    data_integrity: "DAT",
+    tests: "TST",
+    operability: "OPR",
+    config_deployment: "CFG",
+    observability: "OBS",
+};
+/**
+ * A stable signature of a finding's identity-bearing content. The same logical
+ * finding yields the same signature across runs (so its id is reproducible),
+ * while two distinct findings — which only coexist after surviving merge and
+ * dedup with different content — yield different signatures.
+ */
+function contentSignature(finding) {
+    const files = finding.affected_files
+        .map((file) => `${file.path}:${file.line_start ?? ""}:${file.line_end ?? ""}:${file.symbol ?? ""}`)
+        .sort()
+        .join(",");
+    return [
+        finding.lens.trim().toLowerCase(),
+        finding.category.trim().toLowerCase(),
+        finding.title.trim().toLowerCase(),
+        files,
+    ].join("|");
+}
+/**
+ * Re-key finalized findings with globally-unique, content-derived ids at the
+ * synthesis boundary.
+ *
+ * Worker packets assign locally-scoped ids (e.g. `MNT-001`) that collide across
+ * packets once merged, which breaks `audit-findings.json` as a machine contract:
+ * `buildWorkBlocks` keys its union-find on `id` (so colliding ids fuse unrelated
+ * findings into one block), and `work_blocks.finding_ids` / theme `finding_ids` /
+ * the remediator's per-finding addressing can no longer resolve a single finding.
+ *
+ * The id is `<LENS_PREFIX>-<sha256(content)[:8]>`, deterministic and stable so a
+ * re-synthesis of the same findings produces the same ids. A vanishingly rare
+ * hash collision between two *distinct* findings is broken deterministically with
+ * a numeric suffix (findings arrive in mergeFindings()' stable order).
+ *
+ * `related_findings`, when present, referenced the old colliding ids and cannot
+ * be remapped unambiguously, so it is dropped rather than left dangling. (It is
+ * unpopulated by every current extractor.)
+ */
+export function assignStableFindingIds(findings) {
+    const used = new Set();
+    return findings.map((finding) => {
+        const prefix = LENS_ID_PREFIX[finding.lens.trim().toLowerCase()] ?? "FND";
+        const hash = createHash("sha256")
+            .update(contentSignature(finding))
+            .digest("hex")
+            .slice(0, 8);
+        let id = `${prefix}-${hash}`;
+        for (let n = 2; used.has(id); n++) {
+            id = `${prefix}-${hash}-${n}`;
+        }
+        used.add(id);
+        const reKeyed = { ...finding, id };
+        delete reKeyed.related_findings;
+        return reKeyed;
+    });
+}

package/dist/reporting/findingRanks.d.ts

@@ -0,0 +1,3 @@
+import type { Finding } from "../types.js";
+export declare function severityRank(severity: Finding["severity"]): number;
+export declare function confidenceRank(confidence: Finding["confidence"]): number;

package/dist/reporting/findingRanks.js

@@ -0,0 +1,24 @@
+export function severityRank(severity) {
+    switch (severity) {
+        case "critical":
+            return 5;
+        case "high":
+            return 4;
+        case "medium":
+            return 3;
+        case "low":
+            return 2;
+        case "info":
+            return 1;
+    }
+}
+export function confidenceRank(confidence) {
+    switch (confidence) {
+        case "high":
+            return 3;
+        case "medium":
+            return 2;
+        case "low":
+            return 1;
+    }
+}

package/dist/reporting/mergeFindings.js

@@ -1,3 +1,4 @@
+import { severityRank, confidenceRank } from "./findingRanks.js";
 function normalizeText(value) {
     return (value ?? "").trim().toLowerCase();
 }
@@ -43,30 +44,6 @@ function findingKey(finding) {
         String(finding.affected_files[0]?.line_end ?? ""),
     ].join("|");
 }
-function severityRank(severity) {
-    switch (severity) {
-        case "critical":
-            return 5;
-        case "high":
-            return 4;
-        case "medium":
-            return 3;
-        case "low":
-            return 2;
-        case "info":
-            return 1;
-    }
-}
-function confidenceRank(confidence) {
-    switch (confidence) {
-        case "high":
-            return 3;
-        case "medium":
-            return 2;
-        case "low":
-            return 1;
-    }
-}
 function runtimeSummary(report) {
     if (!report) {
         return [];

package/dist/reporting/synthesis.d.ts

@@ -3,7 +3,7 @@ import type { AuditScopeManifest } from "../types/auditScope.js";
 import type { DesignAssessment } from "../types/designAssessment.js";
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 import type { AuditFindingsReport, CriticalFlowManifest, Finding as SharedFinding, FindingTheme, GraphBundle, SynthesisNarrative } from "@audit-tools/shared";
-import type { RuntimeValidationReport } from "../types/runtimeValidation.js";
+import type { RuntimeValidationReport, RuntimeValidationTaskManifest } from "../types/runtimeValidation.js";
 import { type WorkBlock } from "./workBlocks.js";
 /** Contract version stamped onto the canonical `audit-findings.json`. */
 export declare const AUDIT_FINDINGS_CONTRACT_VERSION = "audit-tools/audit-findings/v1";
@@ -25,6 +25,7 @@ export interface AuditReportSummary {
     finding_count: number;
     work_block_count: number;
     severity_breakdown: Record<string, number>;
+    lens_breakdown?: Record<string, number>;
     audited_file_count: number;
     excluded_file_count: number;
     runtime_validation_status_breakdown: Record<string, number>;
@@ -49,6 +50,7 @@ export declare function buildAuditReportModel(params: {
     criticalFlows?: CriticalFlowManifest;
     coverageMatrix?: CoverageMatrix;
     runtimeValidationReport?: RuntimeValidationReport;
+    runtimeValidationTaskManifest?: RuntimeValidationTaskManifest;
     externalAnalyzerResults?: ExternalAnalyzerResults;
     designAssessment?: DesignAssessment;
 }): AuditReportModel;

package/dist/reporting/synthesis.js

@@ -1,6 +1,7 @@
 import { AUDITOR_REPORT_MARKER } from "@audit-tools/shared";
 import { buildWorkBlocks } from "./workBlocks.js";
 import { mergeFindings } from "./mergeFindings.js";
+import { assignStableFindingIds } from "./findingIdentity.js";
 /** Contract version stamped onto the canonical `audit-findings.json`. */
 export const AUDIT_FINDINGS_CONTRACT_VERSION = "audit-tools/audit-findings/v1";
 function countBy(items, selectKey) {
@@ -17,8 +18,18 @@ function countBy(items, selectKey) {
 function severityBreakdown(findings) {
     return countBy(findings, (finding) => finding.severity);
 }
-function runtimeStatusBreakdown(report) {
-    return countBy(report?.results ?? [], (result) => result.status);
+function lensBreakdown(findings) {
+    return countBy(findings, (finding) => finding.lens);
+}
+function runtimeStatusBreakdown(report, taskManifest) {
+    const breakdown = countBy(report?.results ?? [], (result) => result.status);
+    const resultTaskIds = new Set((report?.results ?? []).map((result) => result.task_id));
+    for (const task of taskManifest?.tasks ?? []) {
+        if (!resultTaskIds.has(task.id)) {
+            breakdown.pending = (breakdown.pending ?? 0) + 1;
+        }
+    }
+    return breakdown;
 }
 function coverageSummary(coverage) {
     const files = coverage?.files ?? [];
@@ -36,8 +47,19 @@ function formatSeverityList(summary) {
         .map((severity) => `${severity}: ${summary[severity]}`);
     return parts.length > 0 ? parts.join(", ") : "none";
 }
+function formatCountList(summary) {
+    const parts = Object.entries(summary)
+        .filter(([, count]) => count > 0)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, count]) => `${key}: ${count}`);
+    return parts.length > 0 ? parts.join(", ") : "none";
+}
 export function buildAuditReportModel(params) {
-    const findings = mergeFindings(params.results, params.runtimeValidationReport, params.externalAnalyzerResults, params.designAssessment);
+    // Re-key the finalized findings with globally-unique, content-derived ids
+    // before anything addresses them by id. buildWorkBlocks keys its union-find on
+    // finding.id, so the locally-scoped, collision-prone ids worker packets emit
+    // must be replaced here or unrelated findings fuse into one block.
+    const findings = assignStableFindingIds(mergeFindings(params.results, params.runtimeValidationReport, params.externalAnalyzerResults, params.designAssessment));
     const workBlocks = buildWorkBlocks({
         findings,
         unitManifest: params.unitManifest,
@@ -45,19 +67,22 @@ export function buildAuditReportModel(params) {
         criticalFlows: params.criticalFlows,
     });
     const coverage = coverageSummary(params.coverageMatrix);
-    return {
+    const model = {
         summary: {
             finding_count: findings.length,
             work_block_count: workBlocks.length,
             severity_breakdown: severityBreakdown(findings),
+            lens_breakdown: lensBreakdown(findings),
             audited_file_count: coverage.audited_file_count,
             excluded_file_count: coverage.excluded_file_count,
             budget_deferred_task_count: coverage.budget_deferred_task_count,
-            runtime_validation_status_breakdown: runtimeStatusBreakdown(params.runtimeValidationReport),
+            runtime_validation_status_breakdown: runtimeStatusBreakdown(params.runtimeValidationReport, params.runtimeValidationTaskManifest),
         },
         findings,
         work_blocks: workBlocks,
     };
+    console.error(JSON.stringify({ tag: 'synthesis_complete', finding_count: findings.length, work_block_count: workBlocks.length, severity_breakdown: severityBreakdown(findings), audited_file_count: coverage.audited_file_count, excluded_file_count: coverage.excluded_file_count, budget_deferred_task_count: coverage.budget_deferred_task_count }));
+    return model;
 }
 /**
  * Wrap the deterministic report model in the canonical `audit-findings.json`
@@ -65,12 +90,14 @@ export function buildAuditReportModel(params) {
  * are absent here; they are layered on later by {@link applyNarrative}.
  */
 export function buildAuditFindingsReport(model) {
-    return {
+    const report = {
         contract_version: AUDIT_FINDINGS_CONTRACT_VERSION,
         summary: { ...model.summary },
         findings: model.findings,
         work_blocks: model.work_blocks,
     };
+    console.error(JSON.stringify({ tag: 'audit_findings_report_built', contract_version: AUDIT_FINDINGS_CONTRACT_VERSION, finding_count: model.findings.length, work_block_count: model.work_blocks.length }));
+    return report;
 }
 /**
  * Merge an LLM synthesis narrative into the canonical findings report: keep only
@@ -120,7 +147,9 @@ export function renderAuditReportMarkdown(report, options = {}) {
     if (report.executive_summary && report.executive_summary.trim().length > 0) {
         lines.push("## Executive Summary", "", report.executive_summary.trim(), "");
     }
-    lines.push("## Summary", "", `- Findings: ${report.summary.finding_count}`, `- Work blocks: ${report.summary.work_block_count}`, `- Severity breakdown: ${formatSeverityList(report.summary.severity_breakdown)}`, `- Fully audited files: ${report.summary.audited_file_count}`, `- Excluded non-auditable files: ${report.summary.excluded_file_count}`, ...((report.summary.budget_deferred_task_count ?? 0) > 0
+    lines.push("## Summary", "", `- Findings: ${report.summary.finding_count}`, `- Work blocks: ${report.summary.work_block_count}`, `- Severity breakdown: ${formatSeverityList(report.summary.severity_breakdown)}`, ...(report.summary.lens_breakdown && Object.keys(report.summary.lens_breakdown).length > 0
+        ? [`- Lens breakdown: ${formatCountList(report.summary.lens_breakdown)}`]
+        : []), `- Fully audited files: ${report.summary.audited_file_count}`, `- Excluded non-auditable files: ${report.summary.excluded_file_count}`, ...((report.summary.budget_deferred_task_count ?? 0) > 0
         ? [
             `- Not audited (budget): ${report.summary.budget_deferred_task_count} task(s) skipped by packet budget cap`,
         ]

package/dist/reporting/synthesisNarrativePrompt.js

@@ -17,6 +17,9 @@ export function renderSynthesisNarrativePrompt(report) {
     const overflowNote = findings.length > MAX_RENDERED_FINDINGS
         ? [`  ... and ${findings.length - MAX_RENDERED_FINDINGS} more findings (see audit-findings.json).`]
         : [];
+    if (findings.length > MAX_RENDERED_FINDINGS) {
+        console.warn(`[audit-code] synthesisNarrative: truncated findings list to ${MAX_RENDERED_FINDINGS} of ${findings.length} total — remaining findings omitted from narrative prompt (see audit-findings.json)`);
+    }
     return [
         "# Synthesis narrative",
         "",

package/dist/reporting/workBlocks.js

@@ -1,17 +1,4 @@
-function severityRank(severity) {
-    switch (severity) {
-        case "critical":
-            return 5;
-        case "high":
-            return 4;
-        case "medium":
-            return 3;
-        case "low":
-            return 2;
-        case "info":
-            return 1;
-    }
-}
+import { severityRank } from "./findingRanks.js";
 function buildFileUnitMap(unitManifest) {
     const map = new Map();
     for (const unit of unitManifest?.units ?? []) {

package/dist/supervisor/operatorHandoff.js

@@ -35,11 +35,8 @@ function quoteShellPath(filePath) {
     // double-quote wrapping plus escaping embedded double quotes.
     return `"${filePath.replace(/"/g, '\\"')}"`;
 }
-function quoteShellArg(value) {
-    return quoteShellPath(value);
-}
 function renderShellCommand(argv) {
-    return argv.map((item) => quoteShellArg(item)).join(" ");
+    return argv.map((item) => quoteShellPath(item)).join(" ");
 }
 function buildPendingObligations(state) {
     return state.obligations
@@ -274,7 +271,6 @@ export async function writeAuditCodeHandoffArtifacts(handoff) {
         await writeFile(handoff.artifact_paths.operator_handoff_markdown, renderMarkdown(handoff), "utf8");
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to write operator handoff artifacts: ${message}`);
+        throw new Error(`Failed to write operator handoff artifacts: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
 }

package/dist/supervisor/runLedger.js

@@ -1,16 +1,36 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, open, rename, rm } from "node:fs/promises";
+import { open, mkdir, rename, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { RUN_LEDGER_STATUSES, } from "@audit-tools/shared";
-import { isFileMissingError, readJsonFile, writeJsonFile } from "@audit-tools/shared";
+import { isFileMissingError, readJsonFile, writeJsonFile, withFileLock, withFsRetry } from "@audit-tools/shared";
 const RUN_LEDGER_FILENAME = "run-ledger.json";
 const RUN_LEDGER_LOCK_FILENAME = "run-ledger.lock";
-const LOCK_RETRY_DELAY_MS = 20;
-const LOCK_RETRY_LIMIT = 100;
 const VALID_RUN_LEDGER_STATUSES = new Set(RUN_LEDGER_STATUSES);
 function ledgerPath(artifactsDir) {
     return join(artifactsDir, RUN_LEDGER_FILENAME);
 }
+/**
+ * Wrap withFileLock for the run ledger, emitting a stderr message on the first
+ * contention event so operators can observe prolonged lock waits before the
+ * full timeout expires.
+ */
+async function withLedgerLock(lockPath, fn) {
+    // Probe for an immediate lock acquisition; if the lock file already exists,
+    // log contention before delegating to withFileLock for the full retry loop.
+    try {
+        const fd = await open(lockPath, "wx");
+        await fd.close();
+        // Lock acquired on the first attempt — no contention; release and let
+        // withFileLock manage the full acquire + release lifecycle.
+        await rm(lockPath, { force: true });
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            process.stderr.write(`[audit-code] runLedger: lock contention detected on ${lockPath}, waiting...\n`);
+        }
+    }
+    return withFileLock(lockPath, fn);
+}
 function ledgerLockPath(artifactsDir) {
     return join(artifactsDir, RUN_LEDGER_LOCK_FILENAME);
 }
@@ -20,12 +40,6 @@ function buildTempLedgerPath(artifactsDir) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isFileExistsError(error) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === "EEXIST");
-}
 function assertRunLedgerEntry(value, fieldPath) {
     if (!isRecord(value)) {
         throw new Error(`Invalid run ledger in ${fieldPath}: expected an object.`);
@@ -43,7 +57,7 @@ function assertRunLedgerEntry(value, fieldPath) {
             return null;
         }
         if (typeof entry !== "string" || entry.trim().length === 0) {
-            throw new Error(`Invalid run ledger in ${fieldPath}.${field}: expected a string or null.`);
+            throw new Error(`Invalid run ledger in ${fieldPath}.${field}: expected a non-empty string or null.`);
         }
         return entry;
     };
@@ -74,28 +88,6 @@ function parseRunLedger(value, path) {
         runs: value.runs.map((entry, index) => assertRunLedgerEntry(entry, `${path}.runs[${index}]`)),
     };
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-async function acquireLedgerLock(artifactsDir) {
-    const lockPath = ledgerLockPath(artifactsDir);
-    await mkdir(artifactsDir, { recursive: true });
-    for (let attempt = 0; attempt < LOCK_RETRY_LIMIT; attempt += 1) {
-        try {
-            return await open(lockPath, "wx");
-        }
-        catch (error) {
-            if (!isFileExistsError(error)) {
-                throw error;
-            }
-            if (attempt === LOCK_RETRY_LIMIT - 1) {
-                throw new Error(`Timed out waiting to update ${ledgerPath(artifactsDir)} because ${lockPath} is locked.`);
-            }
-            await sleep(LOCK_RETRY_DELAY_MS);
-        }
-    }
-    throw new Error(`Failed to acquire lock for ${ledgerPath(artifactsDir)}.`);
-}
 export async function loadRunLedger(artifactsDir) {
     const path = ledgerPath(artifactsDir);
     try {
@@ -110,18 +102,15 @@ export async function loadRunLedger(artifactsDir) {
     }
 }
 export async function appendRunLedgerEntry(artifactsDir, entry) {
-    const lockHandle = await acquireLedgerLock(artifactsDir);
     const path = ledgerPath(artifactsDir);
+    const lockPath = ledgerLockPath(artifactsDir);
     const tempPath = buildTempLedgerPath(artifactsDir);
-    try {
+    await mkdir(artifactsDir, { recursive: true });
+    await withLedgerLock(lockPath, async () => {
         const ledger = await loadRunLedger(artifactsDir);
         ledger.runs.push(entry);
         await writeJsonFile(tempPath, ledger);
-        await rename(tempPath, path);
-    }
-    finally {
-        await lockHandle.close();
-        await rm(ledgerLockPath(artifactsDir), { force: true });
+        await withFsRetry(() => rename(tempPath, path));
         await rm(tempPath, { force: true }).catch(() => undefined);
-    }
+    });
 }

package/dist/types/activeDispatch.d.ts

@@ -0,0 +1,31 @@
+export declare const DISPATCH_RESULT_MAP_FILENAME = "dispatch-result-map.json";
+export declare const ACTIVE_DISPATCH_FILENAME = "active-dispatch.json";
+export interface ActiveDispatchState {
+    run_id: string;
+    created_at: string;
+    /** Emitted packets only (after canary/budget filtering). */
+    packet_count: number;
+    /** Tasks remaining this round (not-yet-done), not just emitted-packet tasks. */
+    task_count: number;
+    status: "active" | "merged";
+    /** "canary" on first contact when only the top packet was emitted; "fan_out" otherwise. */
+    phase: "canary" | "fan_out";
+    /** packet_id of the emitted canary packet when phase==="canary", else null. */
+    canary_packet_id: string | null;
+    /** Total packets that would have been emitted before a budget cap (present only when capped). */
+    budget_packet_count?: number;
+    /** packet_ids NOT emitted due to the budget cap. */
+    deferred_packet_ids?: string[];
+    /** task_ids NOT emitted due to the budget cap. */
+    deferred_task_ids?: string[];
+}
+export interface DispatchResultMapEntry {
+    packet_id: string;
+    task_id: string;
+    result_path: string;
+}
+export interface DispatchResultMap {
+    contract_version: "audit-code-dispatch-results/v1alpha1";
+    run_id: string;
+    entries: DispatchResultMapEntry[];
+}

package/dist/types/activeDispatch.js

@@ -0,0 +1,2 @@
+export const DISPATCH_RESULT_MAP_FILENAME = "dispatch-result-map.json";
+export const ACTIVE_DISPATCH_FILENAME = "active-dispatch.json";