code-auditor-mcp 3.4.13 → 3.4.15

package/dist/mcpAuditJobs.js

@@ -2,20 +2,45 @@ import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { fork } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { cpus } from 'node:os';
+import { cpus, hostname } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { CodeIndexDB } from './codeIndexDB.js';
-import { syncFileIndex } from './codeIndexService.js';
 import { CodeMapGenerator } from './services/CodeMapGenerator.js';
 import { analyzeDocumentation } from './analyzers/documentationAnalyzer.js';
 import { assertAuditPathExists, ContextualError } from './mcpToolErrors.js';
 import { createAuditJob, getAuditJob, patchAuditJob, setAuditJobProgress } from './services/auditJobService.js';
+import { detectRunInput, evaluateStaleRunning, hashFileSet, markRunsFailed, patchLedgerRun, writeAuditToLedger, } from './ledger.js';
+import { PACKAGE_VERSION } from './constants.js';
 import { mcpDebugStderr } from './mcpDiagnostics.js';
 import { findFiles } from './utils/fileDiscovery.js';
-import { makeVisitorStatus, getFilesProcessed } from './pipeline.js';
+import { makeVisitorStatus, getFilesProcessed, violationMatchesRule } from './pipeline.js';
+import { RULE_REGISTRY } from './analyzers/ruleRegistry.js';
 import chalk from 'chalk';
 const SOURCE_FOLDERS = ['app', 'src'];
-const GLOBAL_ONLY_ANALYZERS = new Set(['dry', 'data-access', 'schema']);
+// Cross-file reducers run once over the FULL scope, never inside partition
+// shards. A shard sees only its partition's files and (worse) reads shared
+// index tables that other shards are still writing, so any reducer that reads
+// accumulated state must be global. The set is every reducer/derived-reducer
+// in the pipeline stage model:
+//   dry         — cross-file duplicate detection over the function index
+//   data-access — per-file, but kept global so its coverage/status is a single
+//                 full-scope row (harmless to shard, but global is uniform)
+//   schema      — schema_usage reducers (unknown-table, JSON validation)
+//   styles      — reads style_declarations/tokens/class_usage written by the
+//                 styles-css visitor + syncStyleIndex (same analyzer gate)
+//   conventions — reads function_calls/conventions via updateDependencyGraph +
+//                 mineAllConventions (same analyzer gate)
+//   invariants  — call-constraint/module-boundary need the full file list
+//   cross-domain— reads schema_usage/indexed_functions/graph_cache (stage 4)
+const GLOBAL_ONLY_ANALYZERS = new Set([
+    'dry',
+    'data-access',
+    'schema',
+    'styles',
+    'conventions',
+    'invariants',
+    'cross-domain',
+]);
 const RETRYABLE_ERROR_PATTERNS = [/timed out/i, /timeout/i, /econnreset/i, /eagain/i, /emfile/i];
 /** Hard cap so pathological configs cannot fork unbounded processes. */
 const MAX_AUDIT_WORKERS = 8;
@@ -31,6 +56,100 @@ function defaultJobTimeoutMs() {
         return DEFAULT_JOB_TIMEOUT_MS;
     return Math.min(n, ABSOLUTE_MAX_JOB_TIMEOUT_MS);
 }
+// Spec 41 R5 — heartbeat-based concurrency lease. A plain `status='running'`
+// count wedges the queue behind a crashed job's ghost row forever; a stale
+// heartbeat is reclaimable instead.
+const DEFAULT_JOB_LEASE_TTL_MS = 30 * 1000;
+const DEFAULT_MAX_RUNNING_JOBS = 1;
+function jobLeaseTtlMs() {
+    const raw = process.env.CODE_AUDITOR_JOB_LEASE_TTL_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_JOB_LEASE_TTL_MS;
+}
+function maxRunningJobs() {
+    const raw = process.env.CODE_AUDITOR_MAX_RUNNING_JOBS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 1 ? n : DEFAULT_MAX_RUNNING_JOBS;
+}
+/** True when a write hit better-sqlite3's busy timeout under lock contention. */
+function isBusyError(e) {
+    if (!(e instanceof Error))
+        return false;
+    const code = e.code;
+    return code === 'SQLITE_BUSY' || /database is locked/i.test(e.message);
+}
+/**
+ * Claims the `running` slot for `jobId`. The reclaim-then-count-then-claim
+ * sequence runs under `BEGIN IMMEDIATE` because the lease is contested by
+ * separate forked processes (better-sqlite3 serializes writes per-connection,
+ * not per-DB) — without the write lock two children could both see zero
+ * `running` rows and both claim the slot. Stale `running` rows (killed runners)
+ * are reclaimed first, so a ghost never wedges the queue.
+ *
+ * The polling path is deliberately read-only: while a healthy runner holds the
+ * slot, a queued job evaluates the lease pool via `evaluateStaleRunning` (SELECT
+ * + `kill(0)`/`ps`, no write lock) and sleeps. It only grabs `BEGIN IMMEDIATE`
+ * when the pool shows a free slot or a reclaimable ghost. Grabbing the write
+ * lock every poll would contend with the running job's own write transactions
+ * (the long `syncFileIndex`/`updateDependencyGraph` phase) and crash it with
+ * `database is locked`.
+ */
+async function acquireLease(db, projectRoot, jobId) {
+    const ttl = jobLeaseTtlMs();
+    const limit = maxRunningJobs();
+    const now = () => new Date().toISOString();
+    // The transaction only performs the *write* half of reclaim — `reclaimable`
+    // and `cutoff` are computed read-only outside the lock (see below), so the
+    // `ps` liveness check never runs while holding the write lock.
+    const claim = db.transaction((reclaimable, cutoff) => {
+        markRunsFailed(db, reclaimable, cutoff);
+        const row = db
+            .prepare('SELECT COUNT(*) AS cnt FROM findings_ledger_runs WHERE project_root = ? AND status = ?')
+            .get(projectRoot, 'running');
+        if (row.cnt < limit) {
+            // Record PID-based liveness at claim (Spec 41 Amendment B): the child's
+            // PID + process start time (defeats PID reuse) + hostname (foreign hosts
+            // fall back to the heartbeat). `process.uptime()` in the forked child is
+            // measured from the child's start, so `now - uptime` is its true start.
+            patchLedgerRun(db, jobId, {
+                status: 'running',
+                startedAt: now(),
+                heartbeatAt: now(),
+                runnerPid: process.pid,
+                runnerPidStartedAt: new Date(Date.now() - process.uptime() * 1000).toISOString(),
+                runnerHost: hostname(),
+            });
+            return true;
+        }
+        return false;
+    });
+    for (;;) {
+        // Read-only evaluation — no write lock, so it never contends with the
+        // running job's write transactions (the `ps` spawn for a stale-heartbeat
+        // candidate happens here, outside the lock).
+        const evaluation = evaluateStaleRunning(db, projectRoot, ttl);
+        const mightClaim = evaluation.runningCount < limit || evaluation.reclaimable.length > 0;
+        if (mightClaim) {
+            try {
+                if (claim.immediate(evaluation.reclaimable, evaluation.cutoff))
+                    return;
+            }
+            catch (e) {
+                // The lease is contested by separate forked processes. A running job can
+                // hold the write lock longer than the busy timeout (e.g. the long
+                // `writeAuditToLedger` completion transaction), surfacing as SQLITE_BUSY.
+                // That is contention, not failure — wait and retry rather than failing
+                // the queued job (which would cascade into failing the running job too).
+                if (isBusyError(e)) {
+                    await new Promise((resolve) => setTimeout(resolve, Math.max(250, Math.floor(ttl / 4))));
+                    continue;
+                }
+                throw e;
+            }
+        }
+        await new Promise((resolve) => setTimeout(resolve, Math.max(250, Math.floor(ttl / 4))));
+    }
+}
 function resolveWorkerEntrypoint() {
     const current = fileURLToPath(import.meta.url);
     const ext = path.extname(current);
@@ -38,6 +157,14 @@ function resolveWorkerEntrypoint() {
     const filename = ext === '.ts' ? 'auditWorker.ts' : 'auditWorker.js';
     return path.join(dir, 'workers', filename);
 }
+/** Entrypoint for the detached CLI runner (Spec 41 `--detach`). */
+export function resolveJobRunnerEntrypoint() {
+    const current = fileURLToPath(import.meta.url);
+    const ext = path.extname(current);
+    const dir = path.dirname(current);
+    const filename = ext === '.ts' ? 'auditJobRunner.ts' : 'auditJobRunner.js';
+    return path.join(dir, 'workers', filename);
+}
 function asSerializableConfig(options) {
     return {
         projectRoot: options.projectRoot || process.cwd(),
@@ -57,7 +184,7 @@ function asSerializableConfig(options) {
 function isRetryableShardError(error) {
     return RETRYABLE_ERROR_PATTERNS.some((p) => p.test(error));
 }
-async function runShardTasksWithWorkerPool(jobId, tasks, options) {
+async function runShardTasksWithWorkerPool(getDb, jobId, tasks, options) {
     if (tasks.length === 0)
         return [];
     const queue = [...tasks];
@@ -198,7 +325,7 @@ async function runShardTasksWithWorkerPool(jobId, tasks, options) {
                         retryCount++;
                         setTimeout(() => {
                             queue.push(next);
-                            setAuditJobProgress(jobId, {
+                            setAuditJobProgress(getDb(), jobId, {
                                 phase: 'analysis',
                                 message: `Retrying shard ${next.shardId} (${next.attempts}/${options.maxRetries}) after worker recycle`,
                                 current: completedResults.length,
@@ -287,7 +414,7 @@ async function runShardTasksWithWorkerPool(jobId, tasks, options) {
                     return;
                 const overallCurrent = completedResults.length +
                     Math.min(1, (message.progress.current ?? 0) / Math.max(1, message.progress.total ?? 1));
-                setAuditJobProgress(jobId, {
+                setAuditJobProgress(getDb(), jobId, {
                     phase: message.progress.phase ?? 'analysis',
                     message: `${message.shardId}: ${message.progress.message ?? 'running'} (retries=${retryCount})`,
                     current: Math.floor(overallCurrent),
@@ -308,7 +435,7 @@ async function runShardTasksWithWorkerPool(jobId, tasks, options) {
                     attempts: 0,
                     config: message.continuation,
                 });
-                setAuditJobProgress(jobId, {
+                setAuditJobProgress(getDb(), jobId, {
                     phase: 'analysis',
                     message: `Chunk done for ${entry.task.shardId}; queued ${message.remainingFiles.length} remaining file(s) (retries=${retryCount})`,
                     current: completedResults.length,
@@ -326,7 +453,7 @@ async function runShardTasksWithWorkerPool(jobId, tasks, options) {
                 runningShards--;
                 if (message.kind === 'worker-result') {
                     completedResults.push(message.result);
-                    setAuditJobProgress(jobId, {
+                    setAuditJobProgress(getDb(), jobId, {
                         phase: 'analysis',
                         message: `Completed shard ${entry.task.shardId} (${completedResults.length} chunk(s), retries=${retryCount})`,
                         current: completedResults.length,
@@ -459,14 +586,99 @@ function mergeAnalyzerResult(base, next) {
         errors: [...(base.errors || []), ...(next.errors || [])],
     };
 }
+/**
+ * Merge per-shard coverage rows into the project-wide coverage a synchronous
+ * (non-sharded) run would have produced. Every shard's `buildCoverageReport`
+ * iterates the full rule registry and emits, for rules whose analyzer that
+ * shard did not run, a placeholder `notApplicable` row with reason
+ * `analyzer "<name>" not in results`. Those placeholders are filtered out so a
+ * rule's real state comes only from the shards that actually ran its analyzer.
+ *
+ * Precedence across the remaining rows: `fired` wins (its count re-derived from
+ * the merged deduped violations — never the summed per-shard counts, which
+ * over-count DB-based analyzers that emit full-project findings in every
+ * shard), then `clean` (ran somewhere with input present and found nothing)
+ * over `unassessed`, over `notApplicable` (only when every shard that ran the
+ * rule reported no input). Global-only analyzers (GLOBAL_ONLY_ANALYZERS) run
+ * in a single shard over the full scope, so their rows — including Spec 39
+ * applicability predicates like `missing-org-filter` — pass through untouched.
+ */
+function mergeCoverage(results, ordered) {
+    const rows = results.flatMap((r) => r.metadata?.coverage ?? []);
+    if (rows.length === 0)
+        return undefined;
+    const byRule = new Map();
+    for (const row of rows) {
+        const key = JSON.stringify([row.analyzer, row.ruleId]);
+        const group = byRule.get(key);
+        if (group)
+            group.push(row);
+        else
+            byRule.set(key, [row]);
+    }
+    const merged = [];
+    for (const [key, group] of byRule) {
+        const [analyzer, ruleId] = JSON.parse(key);
+        // Rows from shards that did not run this analyzer are placeholders, not a
+        // real state. Prefer the shards that ran it; fall back to placeholders only
+        // if the analyzer ran nowhere (then the placeholder's reason is truthful).
+        const real = group.filter((r) => r.reason !== `analyzer "${analyzer}" not in results`);
+        const src = real.length > 0 ? real : group;
+        const fired = src.filter((r) => r.state === 'fired');
+        if (fired.length > 0) {
+            // Derive the fired count from the merged (deduped) violations, exactly as
+            // the synchronous path's buildCoverageReport does. Summing per-shard
+            // counts would over-count if a DB-based analyzer ever ran in multiple
+            // shards (it no longer does — reducers are global-only), but deduping
+            // from the merged set stays correct regardless and keeps coverage.count
+            // in agreement with the ledger findings count.
+            const field = RULE_REGISTRY[ruleId]?.field;
+            const dedupedCount = (ordered[analyzer]?.violations ?? []).filter((v) => violationMatchesRule(v, ruleId, field)).length;
+            merged.push({
+                ruleId,
+                analyzer,
+                state: 'fired',
+                count: dedupedCount,
+            });
+            continue;
+        }
+        const clean = src.find((r) => r.state === 'clean');
+        if (clean) {
+            merged.push({ ruleId, analyzer, state: 'clean', count: 0 });
+            continue;
+        }
+        const unassessed = src.find((r) => r.state === 'unassessed');
+        if (unassessed) {
+            merged.push({ ruleId, analyzer, state: 'unassessed', count: 0 });
+            continue;
+        }
+        const notApplicable = src.find((r) => r.state === 'notApplicable');
+        if (notApplicable) {
+            merged.push({
+                ruleId,
+                analyzer,
+                state: 'notApplicable',
+                count: 0,
+                reason: notApplicable.reason,
+            });
+            continue;
+        }
+        merged.push({ ruleId, analyzer, state: src[0].state, count: src[0].count, reason: src[0].reason });
+    }
+    return merged;
+}
 function mergeAuditResults(results, orderedAnalyzers) {
     const analyzerResults = {};
     const fileToFunctionsMap = {};
     const collectedFunctions = [];
     const recommendations = [];
+    const skippedFiles = [];
+    const unparsedFiles = [];
+    const diagnostics = [];
     let filesAnalyzed = 0;
     let auditDuration = 0;
     let provenanceResolutionMs = 0;
+    let tableCatalog;
     for (const result of results) {
         for (const [analyzerName, analyzerResult] of Object.entries(result.analyzerResults || {})) {
             analyzerResults[analyzerName] = mergeAnalyzerResult(analyzerResults[analyzerName], analyzerResult);
@@ -477,6 +689,18 @@ function mergeAuditResults(results, orderedAnalyzers) {
         if (result.metadata?.collectedFunctions) {
             collectedFunctions.push(...result.metadata.collectedFunctions);
         }
+        if (result.metadata?.skippedFiles)
+            skippedFiles.push(...result.metadata.skippedFiles);
+        if (result.metadata?.unparsedFiles)
+            unparsedFiles.push(...result.metadata.unparsedFiles);
+        if (result.metadata?.diagnostics)
+            diagnostics.push(...result.metadata.diagnostics);
+        // tableCatalog is produced by the schema analyzer, which is global-only and
+        // therefore runs in a single shard over the full scope — first non-undefined
+        // is the whole catalog, never a fragment.
+        if (result.metadata?.tableCatalog && tableCatalog === undefined) {
+            tableCatalog = result.metadata.tableCatalog;
+        }
         filesAnalyzed += result.metadata?.filesAnalyzed || 0;
         auditDuration += result.metadata?.auditDuration || 0;
         provenanceResolutionMs += result.metadata?.provenanceResolutionMs || 0;
@@ -488,6 +712,7 @@ function mergeAuditResults(results, orderedAnalyzers) {
         if (analyzerResults[name])
             ordered[name] = analyzerResults[name];
     }
+    const coverage = mergeCoverage(results, ordered);
     return {
         timestamp: new Date(),
         summary: summarizeAnalyzerResults(ordered, filesAnalyzed),
@@ -500,6 +725,11 @@ function mergeAuditResults(results, orderedAnalyzers) {
             provenanceResolutionMs,
             ...(collectedFunctions.length > 0 && { collectedFunctions }),
             ...(Object.keys(fileToFunctionsMap).length > 0 && { fileToFunctionsMap }),
+            ...(coverage !== undefined && { coverage }),
+            ...(tableCatalog !== undefined && { tableCatalog }),
+            ...(skippedFiles.length > 0 && { skippedFiles }),
+            ...(unparsedFiles.length > 0 && { unparsedFiles }),
+            ...(diagnostics.length > 0 && { diagnostics }),
         },
     };
 }
@@ -559,12 +789,15 @@ export async function derivePartitionPlan(args, projectRoot, isFile, enabledAnal
 }
 export async function startAuditJob(args, defaults) {
     const auditPath = path.resolve(args.path || process.cwd());
-    await assertAuditPathExists(auditPath);
-    const job = createAuditJob(auditPath);
+    const { isFile } = await assertAuditPathExists(auditPath);
+    const projectRoot = isFile ? path.dirname(auditPath) : auditPath;
+    const db = CodeIndexDB.getInstance(undefined, projectRoot);
+    await db.initialize();
+    const job = createAuditJob(db.rawDb, projectRoot, { surface: 'mcp', command: 'audit.start' });
     setTimeout(() => {
         void runAuditJob(job.jobId, args, defaults).catch((err) => {
             try {
-                patchAuditJob(job.jobId, {
+                patchAuditJob(db.rawDb, job.jobId, {
                     status: 'failed',
                     finishedAt: new Date().toISOString(),
                     error: err instanceof Error ? err.message : String(err),
@@ -582,19 +815,47 @@ export async function startAuditJob(args, defaults) {
         path: auditPath,
     };
 }
-async function runAuditJob(jobId, args, defaults) {
+export async function runAuditJob(jobId, args, defaults) {
     let jobTimer;
+    let heartbeat;
+    // Declared as `| undefined` so a failure thrown before the DB handle resolves
+    // is still catchable; getJobDb() asserts it via `!` and the catch block
+    // swallows the resulting throw rather than masking the original error.
+    let db;
     const ac = new AbortController();
+    // All progress/heartbeat writes go through the singleton connection — there is
+    // no transient second connection. A detached run forks shard workers, each of
+    // which opens its own SQLite connection to the shared per-project DB;
+    // better-sqlite3 opens its fd O_CLOEXEC, so forked children never inherit this
+    // parent's fd. A second open connection to the same WAL database left open
+    // into the indexing loop participates in the shared -shm state and makes the
+    // parent's deferred read→write transactions fail with "database is locked" —
+    // the defect that originally motivated a separate progress connection, so this
+    // stays a single connection throughout.
+    const getJobDb = () => db.rawDb;
     try {
-        patchAuditJob(jobId, {
-            status: 'running',
-            startedAt: new Date().toISOString(),
-            progress: {
-                phase: 'queued',
-                message: 'Audit queued',
-            },
-        });
         const auditPath = path.resolve(args.path || process.cwd());
+        const { isFile } = await assertAuditPathExists(auditPath);
+        const projectRoot = isFile ? path.dirname(auditPath) : auditPath;
+        // Open the per-project DB so a detached child resolves the same DB as the
+        // parent, not the child's cwd.
+        db = CodeIndexDB.getInstance(undefined, projectRoot);
+        await db.initialize();
+        // Spec 41 R5 — heartbeat lease in the prologue, before queued→running.
+        await acquireLease(db.rawDb, projectRoot, jobId);
+        patchAuditJob(db.rawDb, jobId, {
+            progress: { phase: 'queued', message: 'Audit queued' },
+        });
+        const startedMs = Date.now();
+        const heartbeatMs = Math.max(1000, Math.floor(jobLeaseTtlMs() / 2));
+        heartbeat = setInterval(() => {
+            try {
+                patchLedgerRun(getJobDb(), jobId, { heartbeatAt: new Date().toISOString() });
+            }
+            catch (e) {
+                // best-effort — a lost beat only matters after the lease TTL expires
+            }
+        }, heartbeatMs);
         const indexFunctions = args.indexFunctions !== false;
         const generateCodeMap = args.generateCodeMap ?? defaults.defaultGenerateCodeMap;
         const jobTimeoutMs = Math.min(ABSOLUTE_MAX_JOB_TIMEOUT_MS, Math.max(MIN_JOB_TIMEOUT_MS, Number(args.jobTimeoutMs) || defaultJobTimeoutMs()));
@@ -606,15 +867,11 @@ async function runAuditJob(jobId, args, defaults) {
                 ac.abort();
             }
         }, jobTimeoutMs);
-        const { isFile } = await assertAuditPathExists(auditPath);
-        const db = CodeIndexDB.getInstance();
-        await db.initialize();
         const storedConfigs = await db.getAllAnalyzerConfigs(auditPath);
         const analyzerConfigs = {
             ...storedConfigs,
             ...(args.analyzerConfigs || {}),
         };
-        const projectRoot = isFile ? path.dirname(auditPath) : auditPath;
         const enabledAnalyzers = args.analyzers || defaults.defaultAnalyzers;
         const maxWorkers = Math.max(1, Math.min(MAX_AUDIT_WORKERS, Number(args.workerCount) || Math.max(1, Math.min(4, cpus().length - 1 || 1)), Number(args.maxPartitions) || 4));
         const maxRetries = Math.max(0, Number(args.maxRetries) || 1);
@@ -641,7 +898,7 @@ async function runAuditJob(jobId, args, defaults) {
             ...(Object.keys(analyzerConfigs).length > 0 && { analyzerConfigs }),
             ...(args.scope && args.scope !== 'all' && { scope: args.scope }),
             progressCallback: (p) => {
-                setAuditJobProgress(jobId, {
+                setAuditJobProgress(getJobDb(), jobId, {
                     phase: p.phase ?? 'analysis',
                     message: p.message ?? p.phase ?? 'running',
                     current: typeof p.current === 'number' ? p.current : undefined,
@@ -650,21 +907,30 @@ async function runAuditJob(jobId, args, defaults) {
             },
         };
         const plan = await derivePartitionPlan(args, projectRoot, isFile, enabledAnalyzers);
-        const shardTasks = [];
+        // Spec 41 R3 — provenance: capture an aggregate content hash + per-file
+        // manifest so `result`/`status` can report staleness cheaply.
+        const fileHash = hashFileSet(await findFiles(projectRoot), projectRoot);
+        patchLedgerRun(db.rawDb, jobId, {
+            contentHash: fileHash.contentHash,
+            filesCount: fileHash.filesCount,
+            fileManifestJson: JSON.stringify(fileHash.manifest),
+        });
+        const partitionTasks = [];
+        const globalTasks = [];
         if (plan.mode === 'none') {
-            shardTasks.push({
+            partitionTasks.push({
                 shardId: 'full-scope',
                 attempts: 0,
                 config: asSerializableConfig(baseOptions),
             });
         }
         else {
-            setAuditJobProgress(jobId, {
+            setAuditJobProgress(getJobDb(), jobId, {
                 phase: 'partitioning',
                 message: `Planning ${plan.partitionPaths.length} shard(s) + ${plan.globalAnalyzers.length > 0 ? 'global' : 'no-global'} analyzers`,
             });
             if (plan.globalAnalyzers.length > 0) {
-                shardTasks.push({
+                globalTasks.push({
                     shardId: 'global-analyzers',
                     attempts: 0,
                     config: asSerializableConfig({
@@ -675,7 +941,7 @@ async function runAuditJob(jobId, args, defaults) {
                 });
             }
             for (const partitionPath of plan.partitionPaths) {
-                shardTasks.push({
+                partitionTasks.push({
                     shardId: `shard:${path.basename(partitionPath)}`,
                     attempts: 0,
                     config: asSerializableConfig({
@@ -686,19 +952,32 @@ async function runAuditJob(jobId, args, defaults) {
                 });
             }
         }
-        setAuditJobProgress(jobId, {
+        const totalTasks = partitionTasks.length + globalTasks.length;
+        setAuditJobProgress(getJobDb(), jobId, {
             phase: 'analysis',
-            message: `Running ${shardTasks.length} shard task(s) with ${maxWorkers} worker(s)`,
+            message: `Running ${totalTasks} shard task(s) with ${maxWorkers} worker(s)`,
             current: 0,
-            total: shardTasks.length,
+            total: totalTasks,
         });
-        const resultParts = await runShardTasksWithWorkerPool(jobId, shardTasks, {
+        const poolOptions = {
             maxWorkers,
             maxRetries,
             shardTimeoutMs,
             retryBackoffMs,
             signal: ac.signal,
-        });
+        };
+        // Partition shards run first; the global-analyzers shard is scheduled only
+        // after every partition shard has completed. The global shard's full-scope
+        // reducers (conventions, cross-domain, styles) read cross-file index tables
+        // (`functions`, `function_calls`, `style_*`) that the always-on function-index
+        // visitor writes from *every* shard. Running it concurrently — even pushed
+        // "first" — left a `functions`-table write/read race in principle. Serializing
+        // it after the partitions closes that last multi-writer window structurally.
+        const resultParts = [];
+        resultParts.push(...(await runShardTasksWithWorkerPool(getJobDb, jobId, partitionTasks, poolOptions)));
+        if (globalTasks.length > 0) {
+            resultParts.push(...(await runShardTasksWithWorkerPool(getJobDb, jobId, globalTasks, poolOptions)));
+        }
         if (ac.signal.aborted) {
             throw ac.signal.reason instanceof Error
                 ? ac.signal.reason
@@ -707,18 +986,14 @@ async function runAuditJob(jobId, args, defaults) {
         const auditResult = resultParts.length === 1 ? resultParts[0] : mergeAuditResults(resultParts, enabledAnalyzers);
         let indexingResult = null;
         if (indexFunctions && auditResult.metadata.fileToFunctionsMap) {
-            const syncStats = { added: 0, updated: 0, removed: 0 };
-            for (const [filePath, functions] of Object.entries(auditResult.metadata.fileToFunctionsMap)) {
-                if (ac.signal.aborted) {
-                    throw ac.signal.reason instanceof Error
-                        ? ac.signal.reason
-                        : new Error(String(ac.signal.reason || 'Audit job was cancelled during indexing'));
-                }
-                const fileStats = await syncFileIndex(filePath, functions);
-                syncStats.added += fileStats.added;
-                syncStats.updated += fileStats.updated;
-                syncStats.removed += fileStats.removed;
+            if (ac.signal.aborted) {
+                throw ac.signal.reason instanceof Error
+                    ? ac.signal.reason
+                    : new Error(String(ac.signal.reason || 'Audit job was cancelled during indexing'));
             }
+            // Batch all per-file upserts into a single transaction (Amendment B2).
+            const entries = Object.entries(auditResult.metadata.fileToFunctionsMap).map(([filePath, functions]) => ({ filePath, currentFunctions: functions }));
+            const syncStats = await db.syncFileIndexBatch(entries);
             indexingResult = {
                 success: true,
                 registered: syncStats.added + syncStats.updated,
@@ -771,7 +1046,11 @@ async function runAuditJob(jobId, args, defaults) {
             ...(codeMapResult && { codeMap: codeMapResult }),
         };
         const resultId = await db.storeAuditResults(persisted, projectRootForStore);
-        patchAuditJob(jobId, {
+        // Spec 41 R2 — converge on the one ledger write path: attach findings +
+        // coverage to the pre-existing run, then close the lifecycle.
+        const runInput = detectRunInput('audit.start', 'mcp', args.scope || 'all', projectRoot, PACKAGE_VERSION);
+        writeAuditToLedger(db.rawDb, runInput, getAllViolations(auditResult), Date.now() - startedMs, 0, { runId: jobId, coverage: auditResult.metadata.coverage });
+        patchAuditJob(db.rawDb, jobId, {
             status: 'completed',
             finishedAt: new Date().toISOString(),
             progress: { phase: 'completed', message: 'Audit completed' },
@@ -779,21 +1058,47 @@ async function runAuditJob(jobId, args, defaults) {
         });
     }
     catch (e) {
-        patchAuditJob(jobId, {
-            status: 'failed',
-            finishedAt: new Date().toISOString(),
-            error: e instanceof Error ? e.message : String(e),
-            progress: { phase: 'failed', message: 'Audit failed' },
-        });
+        // Write the full trace to stderr (the detached child's per-run log) so a
+        // failure is diagnosable without re-running — the error row alone drops the
+        // stack that says *where* the run died.
+        try {
+            process.stderr.write(`[code-auditor] job ${jobId} failed: ${e instanceof Error ? (e.stack || e.message) : String(e)}\n`);
+        }
+        catch {
+            // ignore — the log write is best-effort
+        }
+        // Record the failure through the singleton connection (best-effort — never
+        // mask the original error, and the run already failed). If the error was
+        // thrown before the DB handle resolved, getJobDb() itself throws and is
+        // swallowed here.
+        try {
+            patchAuditJob(getJobDb(), jobId, {
+                status: 'failed',
+                finishedAt: new Date().toISOString(),
+                error: e instanceof Error ? e.message : String(e),
+                progress: { phase: 'failed', message: 'Audit failed' },
+            });
+        }
+        catch {
+            // best-effort — the run already failed; never mask the original error
+        }
     }
     finally {
+        if (heartbeat !== undefined) {
+            clearInterval(heartbeat);
+        }
         if (jobTimer !== undefined) {
             clearTimeout(jobTimer);
         }
     }
 }
-export function getAuditJobStatus(jobId) {
-    const job = getAuditJob(jobId);
+export async function getAuditJobStatus(jobId) {
+    // Resolve the same DB the writer opened: startAuditJob/runAuditJob set the
+    // singleton to the project-scoped DB, so read from the current singleton's
+    // project root rather than cwd (which would flip the singleton away).
+    const db = CodeIndexDB.getInstance(undefined, CodeIndexDB.currentProject);
+    await db.initialize();
+    const job = getAuditJob(db.rawDb, jobId);
     if (!job) {
         throw new ContextualError(`Audit job not found: ${jobId}`, {
             jobId,
@@ -822,7 +1127,7 @@ export async function getAuditResultsAsSarif(args) {
             hint: 'Call audit.start, poll audit.status until completed, then pass resultId to audit.results with format: "sarif".',
         });
     }
-    const db = CodeIndexDB.getInstance();
+    const db = CodeIndexDB.getInstance(undefined, CodeIndexDB.currentProject);
     await db.initialize();
     const stored = await db.getAuditResults(resultId);
     if (!stored) {
@@ -867,7 +1172,7 @@ export async function getAuditResultsPage(args) {
     }
     const limit = Math.min(Math.max(0, Number(args.limit)) || 50, 100);
     const offset = Math.max(0, Number(args.offset) || 0);
-    const db = CodeIndexDB.getInstance();
+    const db = CodeIndexDB.getInstance(undefined, CodeIndexDB.currentProject);
     await db.initialize();
     const auditResult = await db.getAuditResults(resultId);
     if (!auditResult) {
@@ -907,5 +1212,6 @@ export async function getAuditResultsPage(args) {
 export const __testables = {
     isRetryableShardError,
     mergeAnalyzerResult,
+    mergeCoverage,
 };
 //# sourceMappingURL=mcpAuditJobs.js.map