auditor-lambda 0.3.40 → 0.5.0

package/dist/providers/subprocessTemplateProvider.js

@@ -1,4 +1,4 @@
-import { readJsonFile } from "../io/json.js";
+import { readJsonFile } from "@audit-tools/shared";
 import { spawnLoggedCommand } from "./spawnLoggedCommand.js";
 function shellQuote(arg) {
     return JSON.stringify(arg);
@@ -25,9 +25,11 @@ function applyTemplate(template, input, task) {
 export class SubprocessTemplateProvider {
     name;
     config;
-    constructor(config, name = "subprocess-template") {
+    opentoken;
+    constructor(config, name = "subprocess-template", opentoken = {}) {
         this.config = config;
         this.name = name;
+        this.opentoken = opentoken;
     }
     async launch(input) {
         const task = await readJsonFile(input.taskPath);
@@ -36,6 +38,9 @@ export class SubprocessTemplateProvider {
         }
         const rendered = this.config.command_template.map((entry) => applyTemplate(entry, input, task));
         const [command, ...args] = rendered;
-        return await spawnLoggedCommand(command, args, input, this.config.env);
+        return await spawnLoggedCommand(command, args, input, this.config.env, {
+            opentoken: this.opentoken.enabled,
+            opentokenCommand: this.opentoken.command,
+        });
     }
 }

package/dist/providers/vscodeTaskProvider.d.ts

@@ -1,8 +1,7 @@
-import type { FreshSessionProvider, LaunchFreshSessionInput } from "./types.js";
-import type { VSCodeTaskConfig } from "../types/sessionConfig.js";
+import type { FreshSessionProvider, LaunchFreshSessionInput, VSCodeTaskConfig, OpenTokenConfig } from "@audit-tools/shared";
 export declare class VSCodeTaskProvider implements FreshSessionProvider {
     name: string;
     private readonly delegate;
-    constructor(config: VSCodeTaskConfig);
-    launch(input: LaunchFreshSessionInput): Promise<import("./types.js").LaunchFreshSessionResult>;
+    constructor(config: VSCodeTaskConfig, opentoken?: OpenTokenConfig);
+    launch(input: LaunchFreshSessionInput): Promise<import("@audit-tools/shared").LaunchFreshSessionResult>;
 }

package/dist/providers/vscodeTaskProvider.js

@@ -2,11 +2,11 @@ import { SubprocessTemplateProvider } from "./subprocessTemplateProvider.js";
 export class VSCodeTaskProvider {
     name = "vscode-task";
     delegate;
-    constructor(config) {
+    constructor(config, opentoken = {}) {
         this.delegate = new SubprocessTemplateProvider({
             command_template: config.command_template,
             env: config.env,
-        }, "vscode-task");
+        }, "vscode-task", opentoken);
     }
     async launch(input) {
         return await this.delegate.launch(input);

package/dist/quota/discoveredLimits.js

@@ -1,6 +1,6 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { getQuotaStatePath } from "./state.js";
+import { getQuotaStatePath } from "@audit-tools/shared";
 function getCachePath() {
     return getQuotaStatePath().replace(/quota-state\.json$/, "discovered-limits.json");
 }

package/dist/quota/hostLimits.d.ts

@@ -1,5 +1,4 @@
-import type { SessionConfig } from "../types/sessionConfig.js";
-import type { HostConcurrencyLimit } from "./types.js";
+import type { SessionConfig, HostConcurrencyLimit } from "@audit-tools/shared";
 export declare function detectHostActiveSubagentLimit(env?: NodeJS.ProcessEnv): HostConcurrencyLimit | null;
 export declare function resolveHostActiveSubagentLimit(options: {
     explicitLimit?: number | null;

package/dist/quota/hostLimits.js

@@ -1,50 +1,8 @@
-const CODEX_DESKTOP_ACTIVE_SUBAGENT_LIMIT = 6;
-function parsePositiveInteger(value) {
-    if (typeof value === "number") {
-        return Number.isInteger(value) && value > 0 ? value : null;
-    }
-    if (typeof value !== "string")
-        return null;
-    const trimmed = value.trim();
-    if (!/^\d+$/.test(trimmed))
-        return null;
-    const parsed = Number(trimmed);
-    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
-}
+import { detectHostActiveSubagentLimit as detectShared, resolveHostActiveSubagentLimit as resolveShared, } from "@audit-tools/shared";
+const ENV_PREFIX = "AUDIT_CODE";
 export function detectHostActiveSubagentLimit(env = process.env) {
-    const explicitEnvLimit = parsePositiveInteger(env.AUDIT_CODE_HOST_MAX_ACTIVE_SUBAGENTS ??
-        env.CODEX_MAX_ACTIVE_SUBAGENTS);
-    if (explicitEnvLimit !== null) {
-        return {
-            active_subagents: explicitEnvLimit,
-            source: "environment",
-            description: "Host active subagent limit from environment.",
-        };
-    }
-    if (env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE === "Codex Desktop") {
-        return {
-            active_subagents: CODEX_DESKTOP_ACTIVE_SUBAGENT_LIMIT,
-            source: "environment",
-            description: "Codex Desktop active subagent limit.",
-        };
-    }
-    return null;
+    return detectShared(ENV_PREFIX, env);
 }
 export function resolveHostActiveSubagentLimit(options) {
-    if (options.explicitLimit !== undefined && options.explicitLimit !== null) {
-        return {
-            active_subagents: options.explicitLimit,
-            source: "cli_flags",
-            description: "Host active subagent limit reported by the conversation host.",
-        };
-    }
-    const configuredLimit = parsePositiveInteger(options.sessionConfig.quota?.host_active_subagent_limit);
-    if (configuredLimit !== null) {
-        return {
-            active_subagents: configuredLimit,
-            source: "session_config",
-            description: "Host active subagent limit from session-config quota settings.",
-        };
-    }
-    return detectHostActiveSubagentLimit(options.env);
+    return resolveShared({ envPrefix: ENV_PREFIX, ...options });
 }

package/dist/quota/index.d.ts

@@ -1,25 +1,28 @@
-export { resolveLimits, lookupKnownModel, classifyProvider } from "./limits.js";
-export type { LimitResolutionResult, ResolveLimitsOptions, ProviderType } from "./limits.js";
-export { detectHostActiveSubagentLimit, resolveHostActiveSubagentLimit, } from "./hostLimits.js";
-export { readQuotaState, writeQuotaState, computeMaxSafeConcurrency, recordWaveOutcome, getQuotaStatePath, decayWeight, applyDecayToEntry, computeBackoffCooldownMs, computeBackoffFailureWeight, computeRampUpConcurrency, } from "./state.js";
+import type { ResolvedLimits as _ResolvedLimits, LimitConfidence as _LimitConfidence, LimitSource as _LimitSource, HostConcurrencyLimit as _HostConcurrencyLimit, QuotaUsageSnapshot as _QuotaUsageSnapshot, BackoffState as _BackoffState } from "@audit-tools/shared";
+export { resolveLimits, lookupKnownModel, classifyProvider, readQuotaState, writeQuotaState, computeMaxSafeConcurrency, recordWaveOutcome, getQuotaStatePath, decayWeight, applyDecayToEntry, computeBackoffCooldownMs, computeBackoffFailureWeight, computeRampUpConcurrency, setQuotaStateDir, detectRateLimitError, computeCooldownUntil, acquireLock, releaseLock, withFileLock, FileLockTimeoutError, runSlidingWindow, LearnedQuotaSource, CompositeQuotaSource, GenericErrorParser, ClaudeCodeErrorParser, getErrorParserForProvider, } from "@audit-tools/shared";
+export type { LimitResolutionResult, ResolveLimitsOptions, ProviderType, ResolvedLimits, LimitSource, LimitConfidence, HostConcurrencyLimit, HostConcurrencyLimitSource, QuotaState, QuotaStateEntry, ConcurrencyBucket, WaveSchedule, BackoffState, ObservedWaveOutcome, RateLimitDetectionResult, SlidingWindowResult, QuotaSource, QuotaUsageSnapshot, ErrorParser, } from "@audit-tools/shared";
 export { scheduleWave, buildProviderModelKey } from "./scheduler.js";
 export type { ScheduleWaveOptions } from "./scheduler.js";
-export { detectRateLimitError, computeCooldownUntil } from "./errorParsing.js";
-export { acquireLock, releaseLock, withFileLock, FileLockTimeoutError } from "./fileLock.js";
-export { runSlidingWindow } from "./slidingWindow.js";
-export type { SlidingWindowResult } from "./slidingWindow.js";
-export type { RateLimitDetectionResult } from "./errorParsing.js";
+export { detectHostActiveSubagentLimit, resolveHostActiveSubagentLimit, } from "./hostLimits.js";
 export { probeProvider } from "./probe.js";
 export type { ProbeResult } from "./probe.js";
-export type { QuotaSource, QuotaUsageSnapshot } from "./quotaSource.js";
-export type { ErrorParser } from "./errorParsers/index.js";
-export { GenericErrorParser, ClaudeCodeErrorParser, getErrorParserForProvider } from "./errorParsers/index.js";
-export { LearnedQuotaSource } from "./learnedQuotaSource.js";
-export { CompositeQuotaSource } from "./compositeQuotaSource.js";
 export { lookupDiscoveredLimits, updateDiscoveredLimits, mergeDiscoveredLimits, readDiscoveredLimitsCache, writeDiscoveredLimitsCache, } from "./discoveredLimits.js";
 export type { DiscoveredRateLimits, DiscoveredLimitsCache, DiscoveredLimitsCacheEntry } from "./discoveredLimits.js";
 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 type { ResolvedLimits, LimitSource, LimitConfidence, HostConcurrencyLimit, HostConcurrencyLimitSource, QuotaState, QuotaStateEntry, ConcurrencyBucket, WaveSchedule, DispatchQuota, ObservedWaveOutcome, } from "./types.js";
+export interface DispatchQuota {
+    contract_version: "audit-code-dispatch-quota/v1alpha1" | "audit-code-dispatch-quota/v1alpha2";
+    run_id: string;
+    model: string | null;
+    resolved_limits: _ResolvedLimits;
+    confidence: _LimitConfidence;
+    source: _LimitSource;
+    host_concurrency_limit: _HostConcurrencyLimit | null;
+    wave_size: number;
+    estimated_wave_tokens: number;
+    cooldown_until: string | null;
+    quota_source_snapshot?: _QuotaUsageSnapshot | null;
+    backoff_state?: _BackoffState | null;
+}

package/dist/quota/index.js

@@ -1,14 +1,9 @@
-export { resolveLimits, lookupKnownModel, classifyProvider } from "./limits.js";
-export { detectHostActiveSubagentLimit, resolveHostActiveSubagentLimit, } from "./hostLimits.js";
-export { readQuotaState, writeQuotaState, computeMaxSafeConcurrency, recordWaveOutcome, getQuotaStatePath, decayWeight, applyDecayToEntry, computeBackoffCooldownMs, computeBackoffFailureWeight, computeRampUpConcurrency, } from "./state.js";
+// Re-exported from @audit-tools/shared
+export { resolveLimits, lookupKnownModel, classifyProvider, readQuotaState, writeQuotaState, computeMaxSafeConcurrency, recordWaveOutcome, getQuotaStatePath, decayWeight, applyDecayToEntry, computeBackoffCooldownMs, computeBackoffFailureWeight, computeRampUpConcurrency, setQuotaStateDir, detectRateLimitError, computeCooldownUntil, acquireLock, releaseLock, withFileLock, FileLockTimeoutError, runSlidingWindow, LearnedQuotaSource, CompositeQuotaSource, GenericErrorParser, ClaudeCodeErrorParser, getErrorParserForProvider, } from "@audit-tools/shared";
+// Auditor-specific: local scheduler, probe, discovered limits, header extraction
 export { scheduleWave, buildProviderModelKey } from "./scheduler.js";
-export { detectRateLimitError, computeCooldownUntil } from "./errorParsing.js";
-export { acquireLock, releaseLock, withFileLock, FileLockTimeoutError } from "./fileLock.js";
-export { runSlidingWindow } from "./slidingWindow.js";
+export { detectHostActiveSubagentLimit, resolveHostActiveSubagentLimit, } from "./hostLimits.js";
 export { probeProvider } from "./probe.js";
-export { GenericErrorParser, ClaudeCodeErrorParser, getErrorParserForProvider } from "./errorParsers/index.js";
-export { LearnedQuotaSource } from "./learnedQuotaSource.js";
-export { CompositeQuotaSource } from "./compositeQuotaSource.js";
 export { lookupDiscoveredLimits, updateDiscoveredLimits, mergeDiscoveredLimits, readDiscoveredLimitsCache, writeDiscoveredLimitsCache, } from "./discoveredLimits.js";
 export { extractRateLimitHeaders } from "./headerExtraction.js";
 export { GenericHeaderExtractor, ClaudeCodeHeaderExtractor, getHeaderExtractorForProvider } from "./headerExtractors/index.js";

package/dist/quota/scheduler.d.ts

@@ -1,6 +1,4 @@
-import type { ResolvedProviderName, SessionConfig } from "../types/sessionConfig.js";
-import type { HostConcurrencyLimit, QuotaStateEntry, WaveSchedule } from "./types.js";
-import type { QuotaUsageSnapshot } from "./quotaSource.js";
+import type { ResolvedProviderName, SessionConfig, HostConcurrencyLimit, QuotaStateEntry, WaveSchedule, QuotaUsageSnapshot } from "@audit-tools/shared";
 import type { DiscoveredRateLimits } from "./discoveredLimits.js";
 export interface ScheduleWaveOptions {
     providerName: ResolvedProviderName;

package/dist/quota/scheduler.js

@@ -1,5 +1,4 @@
-import { classifyProvider, resolveLimits } from "./limits.js";
-import { computeMaxSafeConcurrency, computeRampUpConcurrency } from "./state.js";
+import { classifyProvider, resolveLimits, computeMaxSafeConcurrency, computeRampUpConcurrency } from "@audit-tools/shared";
 function sumTopN(sorted, n) {
     let sum = 0;
     for (let i = 0; i < Math.min(n, sorted.length); i++)

package/dist/reporting/synthesis.d.ts

@@ -1,10 +1,26 @@
 import type { AuditResult, CoverageMatrix, Finding, UnitManifest } from "../types.js";
+import type { AuditScopeManifest } from "../types/auditScope.js";
 import type { DesignAssessment } from "../types/designAssessment.js";
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
-import type { CriticalFlowManifest } from "../types/flows.js";
-import type { GraphBundle } from "../types/graph.js";
+import type { AuditFindingsReport, CriticalFlowManifest, Finding as SharedFinding, FindingTheme, GraphBundle, SynthesisNarrative } from "@audit-tools/shared";
 import type { RuntimeValidationReport } 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";
+/**
+ * Anything renderable as the deterministic audit report. Both `AuditReportModel`
+ * (no narrative) and the canonical `AuditFindingsReport` (optionally carrying
+ * themes/executive_summary/top_risks) satisfy this shape, so the same renderer
+ * produces the base report and the narrative-enriched report.
+ */
+export interface RenderableAuditReport {
+    summary: AuditReportSummary;
+    findings: SharedFinding[];
+    work_blocks: WorkBlock[];
+    themes?: FindingTheme[];
+    executive_summary?: string;
+    top_risks?: string[];
+}
 export interface AuditReportSummary {
     finding_count: number;
     work_block_count: number;
@@ -28,4 +44,22 @@ export declare function buildAuditReportModel(params: {
     externalAnalyzerResults?: ExternalAnalyzerResults;
     designAssessment?: DesignAssessment;
 }): AuditReportModel;
-export declare function renderAuditReportMarkdown(model: AuditReportModel): string;
+/**
+ * Wrap the deterministic report model in the canonical `audit-findings.json`
+ * contract — the machine hand-off consumed by the remediator. Narrative fields
+ * are absent here; they are layered on later by {@link applyNarrative}.
+ */
+export declare function buildAuditFindingsReport(model: AuditReportModel): AuditFindingsReport;
+/**
+ * Merge an LLM synthesis narrative into the canonical findings report: keep only
+ * themes whose `finding_ids` reference real findings, tag each covered finding
+ * with its (first-claiming) `theme_id`, and attach the executive summary / top
+ * risks. Deterministic and idempotent — the same narrative yields the same
+ * report.
+ */
+export declare function applyNarrative(report: AuditFindingsReport, narrative: SynthesisNarrative): AuditFindingsReport;
+export interface RenderAuditReportOptions {
+    /** Scope manifest for the run; when delta, the report header reports it honestly. */
+    scope?: AuditScopeManifest;
+}
+export declare function renderAuditReportMarkdown(report: RenderableAuditReport, options?: RenderAuditReportOptions): string;

package/dist/reporting/synthesis.js

@@ -1,5 +1,8 @@
+import { AUDITOR_REPORT_MARKER } from "@audit-tools/shared";
 import { buildWorkBlocks } from "./workBlocks.js";
 import { mergeFindings } from "./mergeFindings.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) {
     const breakdown = {};
     for (const item of items) {
@@ -53,26 +56,92 @@ export function buildAuditReportModel(params) {
         work_blocks: workBlocks,
     };
 }
-export function renderAuditReportMarkdown(model) {
+/**
+ * Wrap the deterministic report model in the canonical `audit-findings.json`
+ * contract — the machine hand-off consumed by the remediator. Narrative fields
+ * are absent here; they are layered on later by {@link applyNarrative}.
+ */
+export function buildAuditFindingsReport(model) {
+    return {
+        contract_version: AUDIT_FINDINGS_CONTRACT_VERSION,
+        summary: { ...model.summary },
+        findings: model.findings,
+        work_blocks: model.work_blocks,
+    };
+}
+/**
+ * Merge an LLM synthesis narrative into the canonical findings report: keep only
+ * themes whose `finding_ids` reference real findings, tag each covered finding
+ * with its (first-claiming) `theme_id`, and attach the executive summary / top
+ * risks. Deterministic and idempotent — the same narrative yields the same
+ * report.
+ */
+export function applyNarrative(report, narrative) {
+    const validFindingIds = new Set(report.findings.map((finding) => finding.id));
+    const themeByFinding = new Map();
+    const themes = [];
+    for (const theme of narrative.themes ?? []) {
+        const findingIds = [
+            ...new Set((theme.finding_ids ?? []).filter((id) => validFindingIds.has(id))),
+        ];
+        themes.push({
+            theme_id: theme.theme_id,
+            title: theme.title,
+            root_cause: theme.root_cause,
+            finding_ids: findingIds,
+            suggested_fix_pattern: theme.suggested_fix_pattern,
+        });
+        for (const id of findingIds) {
+            if (!themeByFinding.has(id)) {
+                themeByFinding.set(id, theme.theme_id);
+            }
+        }
+    }
+    const findings = report.findings.map((finding) => themeByFinding.has(finding.id)
+        ? { ...finding, theme_id: themeByFinding.get(finding.id) }
+        : finding);
+    return {
+        ...report,
+        findings,
+        themes,
+        executive_summary: narrative.executive_summary,
+        top_risks: narrative.top_risks,
+    };
+}
+export function renderAuditReportMarkdown(report, options = {}) {
     const lines = [
+        AUDITOR_REPORT_MARKER,
         "# Audit Report",
         "",
-        "## Summary",
-        "",
-        `- Findings: ${model.summary.finding_count}`,
-        `- Work blocks: ${model.summary.work_block_count}`,
-        `- Severity breakdown: ${formatSeverityList(model.summary.severity_breakdown)}`,
-        `- Fully audited files: ${model.summary.audited_file_count}`,
-        `- Excluded non-auditable files: ${model.summary.excluded_file_count}`,
-        "",
-        "## Work Blocks",
-        "",
     ];
-    if (model.work_blocks.length === 0) {
+    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}`, "");
+    if (report.top_risks && report.top_risks.length > 0) {
+        lines.push("## Top Risks", "");
+        for (const risk of report.top_risks) {
+            lines.push(`- ${risk}`);
+        }
+        lines.push("");
+    }
+    if (report.themes && report.themes.length > 0) {
+        lines.push("## Themes", "");
+        for (const theme of report.themes) {
+            lines.push(`### ${theme.theme_id} — ${theme.title}`);
+            lines.push("");
+            lines.push(`- Root cause: ${theme.root_cause}`);
+            lines.push(`- Findings: ${theme.finding_ids.length > 0 ? theme.finding_ids.join(", ") : "none"}`);
+            lines.push(`- Suggested fix pattern: ${theme.suggested_fix_pattern}`);
+            lines.push("");
+        }
+    }
+    lines.push("## Work Blocks", "");
+    if (report.work_blocks.length === 0) {
         lines.push("No remediation work blocks were generated.", "");
     }
     else {
-        for (const block of model.work_blocks) {
+        for (const block of report.work_blocks) {
             lines.push(`### ${block.id}`);
             lines.push("");
             lines.push(`- Max severity: ${block.max_severity}`);
@@ -85,16 +154,19 @@ export function renderAuditReportMarkdown(model) {
         }
     }
     lines.push("## Findings", "");
-    if (model.findings.length === 0) {
+    if (report.findings.length === 0) {
         lines.push("No findings were recorded.", "");
     }
     else {
-        for (const finding of model.findings) {
+        for (const finding of report.findings) {
             lines.push(`### ${finding.id} — ${finding.title}`);
             lines.push("");
             lines.push(`- Severity: ${finding.severity}`);
             lines.push(`- Confidence: ${finding.confidence}`);
             lines.push(`- Lens: ${finding.lens}`);
+            if (finding.theme_id) {
+                lines.push(`- Theme: ${finding.theme_id}`);
+            }
             lines.push(`- Files: ${finding.affected_files.map((file) => file.path).join(", ")}`);
             lines.push(`- Summary: ${finding.summary}`);
             if (finding.evidence && finding.evidence.length > 0) {
@@ -107,7 +179,16 @@ export function renderAuditReportMarkdown(model) {
         }
     }
     lines.push("## Scope and Coverage", "");
-    lines.push("This report is deterministic output from the completed audit. Non-auditable files were excluded from scope before task generation.");
+    const scope = options.scope;
+    if (scope && scope.mode === "delta") {
+        lines.push(`**Delta audit since \`${scope.since}\`.** This run audited ${scope.seed_files.length} changed file(s) and ${scope.expanded_files.length} graph neighbour(s); all other auditable files were left out of scope (inherited from a prior audit where complete, otherwise excluded from this run). **A full audit is advised before release.**`);
+        if (scope.dropped_note) {
+            lines.push("", scope.dropped_note);
+        }
+    }
+    else {
+        lines.push("This report is deterministic output from the completed audit. Non-auditable files were excluded from scope before task generation.");
+    }
     lines.push("");
     return lines.join("\n");
 }

package/dist/reporting/synthesisNarrativePrompt.d.ts

@@ -0,0 +1,7 @@
+import type { AuditFindingsReport } from "@audit-tools/shared";
+/**
+ * Prompt for the optional synthesis-narrative pass. The host groups the
+ * already-finalized deterministic findings into root-cause themes and writes a
+ * `SynthesisNarrative` JSON document — it does not re-audit or invent findings.
+ */
+export declare function renderSynthesisNarrativePrompt(report: AuditFindingsReport): string;

package/dist/reporting/synthesisNarrativePrompt.js

@@ -0,0 +1,60 @@
+const MAX_RENDERED_FINDINGS = 120;
+function summarizeFinding(finding) {
+    const files = finding.affected_files
+        .map((file) => file.path)
+        .slice(0, 4)
+        .join(", ");
+    return `- ${finding.id} [${finding.severity}/${finding.lens}] ${finding.title} — ${finding.summary}${files ? ` (files: ${files})` : ""}`;
+}
+/**
+ * Prompt for the optional synthesis-narrative pass. The host groups the
+ * already-finalized deterministic findings into root-cause themes and writes a
+ * `SynthesisNarrative` JSON document — it does not re-audit or invent findings.
+ */
+export function renderSynthesisNarrativePrompt(report) {
+    const findings = report.findings;
+    const rendered = findings.slice(0, MAX_RENDERED_FINDINGS).map(summarizeFinding);
+    const overflowNote = findings.length > MAX_RENDERED_FINDINGS
+        ? [`  ... and ${findings.length - MAX_RENDERED_FINDINGS} more findings (see audit-findings.json).`]
+        : [];
+    return [
+        "# Synthesis narrative",
+        "",
+        "The deterministic audit is complete. Your job is to add an interpretive narrative on top of the finalized findings — group them into a small number of root-cause themes, write a short executive summary, and list the top risks.",
+        "",
+        "Do not re-audit the code, change severities, or invent new findings. Use only the findings below; reference them by their exact `id`.",
+        "",
+        "## Summary",
+        "",
+        `- Findings: ${report.summary.finding_count}`,
+        `- Work blocks: ${report.summary.work_block_count}`,
+        "",
+        "## Findings",
+        "",
+        ...(rendered.length > 0 ? rendered : ["- (no findings were recorded)"]),
+        ...overflowNote,
+        "",
+        "## Output format",
+        "",
+        "Write a single JSON object conforming to:",
+        "",
+        "```json",
+        "{",
+        '  "themes": [',
+        "    {",
+        '      "theme_id": "T-001",',
+        '      "title": "short root-cause title",',
+        '      "root_cause": "what underlying cause ties these findings together",',
+        '      "finding_ids": ["<finding id>", "..."],',
+        '      "suggested_fix_pattern": "the shared remediation approach for this theme"',
+        "    }",
+        "  ],",
+        '  "executive_summary": "2-4 sentence overview of the audit outcome",',
+        '  "top_risks": ["highest-impact risk", "..."]',
+        "}",
+        "```",
+        "",
+        "Prefer a handful of substantive themes over many thin ones. Every `finding_ids` entry must be an id listed above; unknown ids are dropped. A finding may belong to at most one theme.",
+        "",
+    ].join("\n");
+}

package/dist/reporting/workBlocks.d.ts

@@ -1,15 +1,6 @@
 import type { Finding, UnitManifest } from "../types.js";
-import type { CriticalFlowManifest } from "../types/flows.js";
-import type { GraphBundle } from "../types/graph.js";
-export interface WorkBlock {
-    id: string;
-    finding_ids: string[];
-    unit_ids: string[];
-    owned_files: string[];
-    max_severity: Finding["severity"];
-    rationale: string;
-    depends_on: string[];
-}
+import type { CriticalFlowManifest, GraphBundle, WorkBlock } from "@audit-tools/shared";
+export type { WorkBlock } from "@audit-tools/shared";
 export declare function buildWorkBlocks(params: {
     findings: Finding[];
     unitManifest?: UnitManifest;

package/dist/supervisor/operatorHandoff.js

@@ -1,6 +1,6 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { writeJsonFile } from "../io/json.js";
+import { writeJsonFile } from "@audit-tools/shared";
 import { LOCAL_SUBPROCESS_PROVIDER_NAME } from "../providers/constants.js";
 export const CONFIG_ERROR_BLOCKER_PREFIX = "config-error:";
 const INCOMING_DIRNAME = "incoming";

package/dist/supervisor/runLedger.d.ts

@@ -1,3 +1,3 @@
-import { type RunLedger, type RunLedgerEntry } from "../types/runLedger.js";
+import { type RunLedger, type RunLedgerEntry } from "@audit-tools/shared";
 export declare function loadRunLedger(artifactsDir: string): Promise<RunLedger>;
 export declare function appendRunLedgerEntry(artifactsDir: string, entry: RunLedgerEntry): Promise<void>;

package/dist/supervisor/runLedger.js

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { mkdir, open, rename, rm } from "node:fs/promises";
 import { join } from "node:path";
-import { RUN_LEDGER_STATUSES, } from "../types/runLedger.js";
-import { isFileMissingError, readJsonFile, writeJsonFile } from "../io/json.js";
+import { RUN_LEDGER_STATUSES, } from "@audit-tools/shared";
+import { isFileMissingError, readJsonFile, writeJsonFile } 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;

package/dist/supervisor/sessionConfig.d.ts

@@ -1,4 +1,11 @@
-import type { SessionConfig } from "../types/sessionConfig.js";
+import { type AnalyzerSetting, type SessionConfig } from "@audit-tools/shared";
 export declare function getSessionConfigPath(artifactsDir: string): string;
 export declare function readSessionConfigFile(artifactsDir: string): Promise<unknown | undefined>;
 export declare function loadSessionConfig(artifactsDir: string): Promise<SessionConfig>;
+/**
+ * Merge per-analyzer resolution decisions into `session-config.json`,
+ * preserving any unknown fields, validating, and persisting the result. Used by
+ * the conversation-first `analyzer_install` step to durably record the host's
+ * `{ephemeral|permanent|skip}` choices under `analyzers.<id>`.
+ */
+export declare function persistAnalyzerSettings(artifactsDir: string, settings: Record<string, AnalyzerSetting>): Promise<SessionConfig>;

package/dist/supervisor/sessionConfig.js

@@ -1,8 +1,6 @@
 import { join } from "node:path";
-import { readOptionalJsonFile } from "../io/json.js";
-import { formatValidationIssues, } from "../validation/basic.js";
+import { isRecord, readOptionalJsonFile, writeJsonFile, formatValidationIssues, } from "@audit-tools/shared";
 import { validateSessionConfig } from "../validation/sessionConfig.js";
-import { writeJsonFile } from "../io/json.js";
 const SESSION_CONFIG_FILENAME = "session-config.json";
 const DEFAULT_SESSION_CONFIG = { provider: "local-subprocess" };
 export function getSessionConfigPath(artifactsDir) {
@@ -27,3 +25,24 @@ export async function loadSessionConfig(artifactsDir) {
     }
     return rawConfig;
 }
+/**
+ * Merge per-analyzer resolution decisions into `session-config.json`,
+ * preserving any unknown fields, validating, and persisting the result. Used by
+ * the conversation-first `analyzer_install` step to durably record the host's
+ * `{ephemeral|permanent|skip}` choices under `analyzers.<id>`.
+ */
+export async function persistAnalyzerSettings(artifactsDir, settings) {
+    const configPath = getSessionConfigPath(artifactsDir);
+    const raw = (await readOptionalJsonFile(configPath)) ?? {
+        ...DEFAULT_SESSION_CONFIG,
+    };
+    const base = isRecord(raw) ? raw : { ...DEFAULT_SESSION_CONFIG };
+    const current = isRecord(base.analyzers) ? base.analyzers : {};
+    const merged = { ...base, analyzers: { ...current, ...settings } };
+    const issues = validateSessionConfig(merged);
+    if (issues.length > 0) {
+        throw new Error(formatConfigValidationIssues(configPath, issues));
+    }
+    await writeJsonFile(configPath, merged);
+    return merged;
+}

package/dist/types/analyzerCapability.d.ts

@@ -0,0 +1,16 @@
+import type { AnalyzerSetting } from "@audit-tools/shared";
+import type { AnalyzerResolution } from "../extractors/analyzers/types.js";
+export type AnalyzerCapabilityStatus = "applied" | "omitted";
+export interface AnalyzerCapabilityEntry {
+    id: string;
+    resolution: AnalyzerResolution;
+    setting: AnalyzerSetting;
+    edges_added: number;
+    routes_added: number;
+    note?: string;
+}
+export interface AnalyzerCapabilityRecord {
+    /** `applied` when ≥1 analyzer contributed edges/routes; `omitted` otherwise. */
+    status: AnalyzerCapabilityStatus;
+    analyzers: AnalyzerCapabilityEntry[];
+}