auditor-lambda 0.2.8 → 0.2.9

package/dist/prompts/renderWorkerPrompt.js

@@ -1,8 +1,9 @@
-function shellQuote(arg) {
-    return JSON.stringify(arg);
+import { usesDeferredWorkerCommand, } from "../types/workerSession.js";
+function renderArgv(task) {
+    return JSON.stringify(task.worker_command);
 }
 export function renderWorkerPrompt(task) {
-    const command = task.worker_command.map(shellQuote).join(" ");
+    const commandArgv = renderArgv(task);
     if (task.preferred_executor === "agent" && task.audit_results_path) {
         const tasksPath = task.pending_audit_tasks_path ??
             `${task.artifacts_dir}/audit_tasks.json`;
@@ -29,14 +30,17 @@ export function renderWorkerPrompt(task) {
             "       Example evidence entry: src/foo.ts:42 - variable overwritten before use",
             "     Optional finding fields: impact, likelihood, reproduction, systemic, related_findings",
             "     Low-priority tasks still require a real review. Use findings: [] only when you genuinely found nothing notable.",
+            task.timeout_ms
+                ? `     Time budget for this task: ${task.timeout_ms} ms.`
+                : "     Keep the task bounded to the assigned files only.",
             `Reference schema: ${task.artifacts_dir}/dispatch/audit-result.schema.json`,
             `Write the AuditResult[] JSON array to: ${task.audit_results_path}`,
         ];
-        if (task.skip_worker_command) {
-            lines.push("", "Stop after writing the results file.");
+        if (usesDeferredWorkerCommand(task)) {
+            lines.push("", "This run is using deferred worker-command ingestion.", "Do not execute worker_command in this session.", "Stop after writing the results file.");
         }
         else {
-            lines.push("", "Then run this command exactly:", command, "Stop after the command completes.");
+            lines.push("", "Then execute the worker_command array from task.json exactly as written.", "Preserve argv boundaries instead of reconstructing shell quoting.", `worker_command argv JSON: ${commandArgv}`, "Stop after the command completes.");
         }
         return lines.join("\n");
     }
@@ -46,10 +50,14 @@ export function renderWorkerPrompt(task) {
         `Repository root: ${task.repo_root}`,
         `Obligation: ${task.obligation_id ?? "unknown"}`,
         `Executor: ${task.preferred_executor}`,
-        "Execute the following command exactly, without modification:",
-        command,
+        "Execute the worker_command array from task.json exactly as written.",
+        "Preserve argv boundaries instead of reconstructing shell quoting.",
+        `worker_command argv JSON: ${commandArgv}`,
         "Do not continue the audit recursively.",
         "Do not choose another task.",
+        task.timeout_ms
+            ? `The worker command is budgeted for ${task.timeout_ms} ms.`
+            : "If the command hangs or fails, stop and let the supervisor handle it.",
         `The command must write the worker result JSON to: ${task.result_path}`,
         "After the command completes, stop.",
     ].join("\n");

package/dist/providers/claudeCodeProvider.d.ts

@@ -1,8 +1,11 @@
 import type { FreshSessionProvider, LaunchFreshSessionInput } from "./types.js";
 import type { ClaudeCodeConfig } from "../types/sessionConfig.js";
+import { spawnLoggedCommand } from "./spawnLoggedCommand.js";
+export declare const ACTIVE_CLAUDE_CODE_SESSION_MESSAGE: string;
 export declare class ClaudeCodeProvider implements FreshSessionProvider {
     name: string;
     private readonly config;
-    constructor(config?: ClaudeCodeConfig);
+    private readonly launchCommand;
+    constructor(config?: ClaudeCodeConfig, launchCommand?: typeof spawnLoggedCommand);
     launch(input: LaunchFreshSessionInput): Promise<import("./types.js").LaunchFreshSessionResult>;
 }

package/dist/providers/claudeCodeProvider.js

@@ -1,16 +1,19 @@
 import { readFile } from "node:fs/promises";
 import { spawnLoggedCommand } from "./spawnLoggedCommand.js";
+export const ACTIVE_CLAUDE_CODE_SESSION_MESSAGE = "claude-code provider cannot be used inside an active Claude Code session. " +
+    'Set provider to "local-subprocess" in .audit-artifacts/session-config.json, ' +
+    "then run /audit-code conversationally and follow the dispatch prompts manually.";
 export class ClaudeCodeProvider {
     name = "claude-code";
     config;
-    constructor(config = {}) {
+    launchCommand;
+    constructor(config = {}, launchCommand = spawnLoggedCommand) {
         this.config = config;
+        this.launchCommand = launchCommand;
     }
     async launch(input) {
         if (process.env.CLAUDECODE) {
-            throw new Error("claude-code provider cannot be used inside an active Claude Code session. " +
-                "Set provider to \"local-subprocess\" in .audit-artifacts/session-config.json, " +
-                "then run /audit-code conversationally and follow the dispatch prompts manually.");
+            throw new Error(ACTIVE_CLAUDE_CODE_SESSION_MESSAGE);
         }
         const prompt = await readFile(input.promptPath, "utf8");
         const command = this.config.command ?? "claude";
@@ -20,6 +23,6 @@ export class ClaudeCodeProvider {
             ...(this.config.extra_args ?? []),
             "--dangerously-skip-permissions",
         ];
-        return await spawnLoggedCommand(command, args, input);
+        return await this.launchCommand(command, args, input);
     }
 }

package/dist/providers/localSubprocessProvider.d.ts

@@ -1,5 +1,9 @@
 import type { FreshSessionProvider, LaunchFreshSessionInput } from "./types.js";
+import { spawnLoggedCommand } from "./spawnLoggedCommand.js";
+export declare const MISSING_WORKER_COMMAND_MESSAGE = "local-subprocess provider requires task.worker_command.";
 export declare class LocalSubprocessProvider implements FreshSessionProvider {
     name: string;
+    private readonly launchCommand;
+    constructor(launchCommand?: typeof spawnLoggedCommand);
     launch(input: LaunchFreshSessionInput): Promise<import("./types.js").LaunchFreshSessionResult>;
 }

package/dist/providers/localSubprocessProvider.js

@@ -1,13 +1,18 @@
 import { readJsonFile } from "../io/json.js";
 import { spawnLoggedCommand } from "./spawnLoggedCommand.js";
+export const MISSING_WORKER_COMMAND_MESSAGE = "local-subprocess provider requires task.worker_command.";
 export class LocalSubprocessProvider {
     name = "local-subprocess";
+    launchCommand;
+    constructor(launchCommand = spawnLoggedCommand) {
+        this.launchCommand = launchCommand;
+    }
     async launch(input) {
         const task = await readJsonFile(input.taskPath);
         if (!task.worker_command.length) {
-            throw new Error("local-subprocess provider requires task.worker_command.");
+            throw new Error(MISSING_WORKER_COMMAND_MESSAGE);
         }
         const [command, ...args] = task.worker_command;
-        return await spawnLoggedCommand(command, args, input);
+        return await this.launchCommand(command, args, input);
     }
 }

package/dist/providers/spawnLoggedCommand.d.ts

@@ -1,2 +1,10 @@
+import { createWriteStream } from "node:fs";
+import { spawn } from "node:child_process";
 import type { LaunchFreshSessionInput, LaunchFreshSessionResult } from "./types.js";
-export declare function spawnLoggedCommand(command: string, args: string[], input: LaunchFreshSessionInput, env?: Record<string, string>): Promise<LaunchFreshSessionResult>;
+interface SpawnLoggedCommandOptions {
+    createWriteStream?: typeof createWriteStream;
+    spawn?: typeof spawn;
+    killGraceMs?: number;
+}
+export declare function spawnLoggedCommand(command: string, args: string[], input: LaunchFreshSessionInput, env?: Record<string, string>, options?: SpawnLoggedCommandOptions): Promise<LaunchFreshSessionResult>;
+export {};

package/dist/providers/spawnLoggedCommand.js

@@ -1,5 +1,8 @@
 import { createWriteStream } from "node:fs";
 import { spawn } from "node:child_process";
+const TERMINATION_SIGNAL = "SIGTERM";
+const FORCE_KILL_SIGNAL = "SIGKILL";
+const FORCE_KILL_GRACE_MS = 1_000;
 function tee(write, chunk) {
     write.write(chunk);
 }
@@ -7,22 +10,77 @@ function tee(write, chunk) {
 // does not consult PATH for executables without a shell. Callers should use
 // `platformCommand()` (scripts/smoke-packaged-audit-code.mjs) or similar to
 // supply the correct command form for the host OS.
-export async function spawnLoggedCommand(command, args, input, env) {
+export async function spawnLoggedCommand(command, args, input, env, options = {}) {
+    const openWriteStream = options.createWriteStream ?? createWriteStream;
+    const spawnProcess = options.spawn ?? spawn;
+    const killGraceMs = options.killGraceMs ?? FORCE_KILL_GRACE_MS;
     return await new Promise((resolve, reject) => {
-        const stdoutLog = createWriteStream(input.stdoutPath, { flags: "a" });
-        const stderrLog = createWriteStream(input.stderrPath, { flags: "a" });
+        const stdoutLog = openWriteStream(input.stdoutPath, { flags: "a" });
+        const stderrLog = openWriteStream(input.stderrPath, { flags: "a" });
         const startedAt = Date.now();
         let timedOut = false;
-        const child = spawn(command, args, {
-            cwd: input.repoRoot,
-            env: { ...process.env, ...env },
-            stdio: ["ignore", "pipe", "pipe"],
-        });
-        const timer = setTimeout(() => {
+        let settled = false;
+        let child = null;
+        let timer;
+        let heartbeat;
+        let forceKillTimer;
+        const cleanup = () => {
+            if (timer) {
+                clearTimeout(timer);
+            }
+            if (heartbeat) {
+                clearInterval(heartbeat);
+            }
+            if (forceKillTimer) {
+                clearTimeout(forceKillTimer);
+            }
+            stdoutLog.end();
+            stderrLog.end();
+        };
+        const settle = (callback) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            callback();
+        };
+        const fail = (error) => {
+            if (child && !child.killed) {
+                child.kill(FORCE_KILL_SIGNAL);
+            }
+            const normalized = error instanceof Error ? error : new Error(String(error));
+            settle(() => reject(normalized));
+        };
+        stdoutLog.on("error", fail);
+        stderrLog.on("error", fail);
+        let spawnedChild;
+        try {
+            spawnedChild = spawnProcess(command, args, {
+                cwd: input.repoRoot,
+                env: { ...process.env, ...env },
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            child = spawnedChild;
+        }
+        catch (error) {
+            fail(error);
+            return;
+        }
+        if (!spawnedChild.stdout || !spawnedChild.stderr) {
+            fail(new Error(`Fresh session spawn for run ${input.runId} did not provide pipe-backed stdout/stderr streams.`));
+            return;
+        }
+        timer = setTimeout(() => {
             timedOut = true;
-            child.kill("SIGTERM");
+            spawnedChild.kill(TERMINATION_SIGNAL);
+            forceKillTimer = setTimeout(() => {
+                if (!settled) {
+                    spawnedChild.kill(FORCE_KILL_SIGNAL);
+                }
+            }, killGraceMs);
         }, input.timeoutMs);
-        const heartbeat = setInterval(() => {
+        heartbeat = setInterval(() => {
             const elapsedMs = Date.now() - startedAt;
             const message = `[provider] run ${input.runId} still running after ${elapsedMs}ms\n`;
             tee(stderrLog, message);
@@ -30,40 +88,30 @@ export async function spawnLoggedCommand(command, args, input, env) {
                 process.stderr.write(message);
             }
         }, 30_000);
-        child.stdout.on("data", (chunk) => {
+        spawnedChild.stdout.on("data", (chunk) => {
             tee(stdoutLog, chunk);
             if (input.uiMode === "visible") {
                 process.stdout.write(chunk);
             }
         });
-        child.stderr.on("data", (chunk) => {
+        spawnedChild.stderr.on("data", (chunk) => {
             tee(stderrLog, chunk);
             if (input.uiMode === "visible") {
                 process.stderr.write(chunk);
             }
         });
-        child.on("error", (error) => {
-            clearTimeout(timer);
-            clearInterval(heartbeat);
-            stdoutLog.end();
-            stderrLog.end();
-            reject(error);
-        });
-        child.on("exit", (code, signal) => {
-            clearTimeout(timer);
-            clearInterval(heartbeat);
-            stdoutLog.end();
-            stderrLog.end();
+        spawnedChild.on("error", fail);
+        spawnedChild.on("exit", (code, signal) => {
             if (timedOut) {
-                reject(new Error(`Fresh session timed out after ${input.timeoutMs}ms for run ${input.runId}.`));
+                settle(() => reject(new Error(`Fresh session timed out after ${input.timeoutMs}ms for run ${input.runId}.`)));
                 return;
             }
-            resolve({
+            settle(() => resolve({
                 accepted: true,
-                processId: child.pid,
+                processId: spawnedChild.pid,
                 exitCode: code,
                 signal,
-            });
+            }));
         });
     });
 }

package/dist/reporting/synthesis.d.ts

@@ -1,4 +1,5 @@
 import type { AuditResult, CoverageMatrix, Finding, UnitManifest } from "../types.js";
+import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 import type { CriticalFlowManifest } from "../types/flows.js";
 import type { GraphBundle } from "../types/graph.js";
 import type { RuntimeValidationReport } from "../types/runtimeValidation.js";
@@ -23,5 +24,6 @@ export declare function buildAuditReportModel(params: {
     criticalFlows?: CriticalFlowManifest;
     coverageMatrix?: CoverageMatrix;
     runtimeValidationReport?: RuntimeValidationReport;
+    externalAnalyzerResults?: ExternalAnalyzerResults;
 }): AuditReportModel;
 export declare function renderAuditReportMarkdown(model: AuditReportModel): string;

package/dist/reporting/synthesis.js

@@ -1,18 +1,21 @@
 import { buildWorkBlocks } from "./workBlocks.js";
 import { mergeFindings } from "./mergeFindings.js";
-function severityBreakdown(findings) {
+function countBy(items, selectKey) {
     const breakdown = {};
-    for (const finding of findings) {
-        breakdown[finding.severity] = (breakdown[finding.severity] ?? 0) + 1;
+    for (const item of items) {
+        const key = selectKey(item);
+        if (!key) {
+            continue;
+        }
+        breakdown[key] = (breakdown[key] ?? 0) + 1;
     }
     return breakdown;
 }
+function severityBreakdown(findings) {
+    return countBy(findings, (finding) => finding.severity);
+}
 function runtimeStatusBreakdown(report) {
-    const breakdown = {};
-    for (const result of report?.results ?? []) {
-        breakdown[result.status] = (breakdown[result.status] ?? 0) + 1;
-    }
-    return breakdown;
+    return countBy(report?.results ?? [], (result) => result.status);
 }
 function coverageSummary(coverage) {
     const files = coverage?.files ?? [];
@@ -29,7 +32,7 @@ function formatSeverityList(summary) {
     return parts.length > 0 ? parts.join(", ") : "none";
 }
 export function buildAuditReportModel(params) {
-    const findings = mergeFindings(params.results, params.runtimeValidationReport);
+    const findings = mergeFindings(params.results, params.runtimeValidationReport, params.externalAnalyzerResults);
     const workBlocks = buildWorkBlocks({
         findings,
         unitManifest: params.unitManifest,

package/dist/supervisor/operatorHandoff.js

@@ -3,22 +3,52 @@ import { join } from "node:path";
 import { writeJsonFile } from "../io/json.js";
 import { LOCAL_SUBPROCESS_PROVIDER_NAME } from "../providers/constants.js";
 export const CONFIG_ERROR_BLOCKER_PREFIX = "config-error:";
-function quoteShellPath(path) {
-    return `"${path.replace(/"/g, '\\"')}"`;
+const INCOMING_DIRNAME = "incoming";
+const OPERATOR_HANDOFF_JSON_FILENAME = "operator-handoff.json";
+const OPERATOR_HANDOFF_MARKDOWN_FILENAME = "operator-handoff.md";
+const SESSION_CONFIG_FILENAME = "session-config.json";
+const RUN_LEDGER_FILENAME = "run-ledger.json";
+const AUDIT_TASKS_FILENAME = "audit_tasks.json";
+const RUNTIME_VALIDATION_TASKS_FILENAME = "runtime_validation_tasks.json";
+const BLOCKED_STATUS = "blocked";
+const COMPLETE_STATUS = "complete";
+const NOT_STARTED_STATUS = "not_started";
+const NON_PENDING_OBLIGATION_STATES = new Set([
+    "present",
+    "satisfied",
+]);
+const INTERACTIVE_PROVIDER_OPTIONS = [
+    "auto",
+    "claude-code",
+    "opencode",
+    "subprocess-template",
+    "vscode-task",
+];
+function quoteShellPath(filePath) {
+    // The handoff renders a single shell argument, so the snippet only needs
+    // double-quote wrapping plus escaping embedded double quotes.
+    return `"${filePath.replace(/"/g, '\\"')}"`;
 }
 function buildPendingObligations(state) {
     return state.obligations
-        .filter((item) => item.state !== "satisfied" && item.state !== "present")
+        .filter((item) => !NON_PENDING_OBLIGATION_STATES.has(item.state))
         .map((item) => item.id);
 }
+function formatQuotedList(values) {
+    if (values.length === 1) {
+        return `"${values[0]}"`;
+    }
+    const head = values.slice(0, -1).map((value) => `"${value}"`).join(", ");
+    return `${head}, or "${values[values.length - 1]}"`;
+}
 function buildSummary(status, providerName, fallbackSummary) {
-    if (status === "complete") {
+    if (status === COMPLETE_STATUS) {
         return "No operator handoff is required. All known obligations are currently satisfied.";
     }
-    if (status === "blocked") {
+    if (status === BLOCKED_STATUS) {
         return fallbackSummary;
     }
-    if (status === "not_started") {
+    if (status === NOT_STARTED_STATUS) {
         return "The artifact bundle is not initialized yet. Run the wrapper from the repository root to create the initial audit artifacts.";
     }
     return providerName
@@ -26,10 +56,10 @@ function buildSummary(status, providerName, fallbackSummary) {
         : "Automatic work can continue. Re-run the same wrapper or inspect the listed artifacts if you need operator context.";
 }
 function buildSuggestedInputs(artifactsDir, status, isConfigError) {
-    if (status !== "blocked" || isConfigError) {
+    if (status !== BLOCKED_STATUS || isConfigError) {
         return [];
     }
-    const incomingDir = join(artifactsDir, "incoming");
+    const incomingDir = join(artifactsDir, INCOMING_DIRNAME);
     return [
         {
             flag: "--results",
@@ -49,20 +79,20 @@ function buildSuggestedInputs(artifactsDir, status, isConfigError) {
     ];
 }
 function buildSuggestedCommands(suggestedInputs, status) {
-    if (status !== "blocked") {
+    if (status !== BLOCKED_STATUS) {
         return [];
     }
     return suggestedInputs.map((item) => `audit-code ${item.flag} ${quoteShellPath(item.suggested_path)}`);
 }
 function buildInteractiveProviderHint(status, providerName, sessionConfigPath, isConfigError) {
-    if (status !== "blocked") {
+    if (status !== BLOCKED_STATUS) {
         return null;
     }
     if (isConfigError) {
         return `A project configuration issue is blocking the audit. Verify that --root points to the repository root containing a project file (package.json, go.mod, etc.), then run audit-code again.`;
     }
     const providerLabel = providerName ?? LOCAL_SUBPROCESS_PROVIDER_NAME;
-    return `Current provider is ${providerLabel}. If you want the backend to continue through an interactive provider instead of importing results manually, set "provider" in ${sessionConfigPath} to "auto", "claude-code", "opencode", "subprocess-template", or "vscode-task", then run audit-code again from the repository root.`;
+    return `Current backend worker provider is ${providerLabel}. Remaining semantic review belongs to the active conversation agent by default. If you intentionally want the backend to continue through a compatibility bridge instead, configure ${sessionConfigPath} for ${formatQuotedList(INTERACTIVE_PROVIDER_OPTIONS)} and re-run audit-code with an explicit --provider value from the repository root.`;
 }
 function renderMarkdown(handoff) {
     const lines = [
@@ -115,18 +145,18 @@ function renderMarkdown(handoff) {
 }
 export function buildAuditCodeHandoff(params) {
     const isConfigError = params.isConfigError ?? false;
-    const incomingDir = join(params.artifactsDir, "incoming");
+    const incomingDir = join(params.artifactsDir, INCOMING_DIRNAME);
     const artifactPaths = {
         incoming_dir: incomingDir,
-        operator_handoff_json: join(params.artifactsDir, "operator-handoff.json"),
-        operator_handoff_markdown: join(params.artifactsDir, "operator-handoff.md"),
-        session_config: join(params.artifactsDir, "session-config.json"),
-        run_ledger: join(params.artifactsDir, "run-ledger.json"),
+        operator_handoff_json: join(params.artifactsDir, OPERATOR_HANDOFF_JSON_FILENAME),
+        operator_handoff_markdown: join(params.artifactsDir, OPERATOR_HANDOFF_MARKDOWN_FILENAME),
+        session_config: join(params.artifactsDir, SESSION_CONFIG_FILENAME),
+        run_ledger: join(params.artifactsDir, RUN_LEDGER_FILENAME),
         audit_tasks: params.bundle.audit_tasks
-            ? join(params.artifactsDir, "audit_tasks.json")
+            ? join(params.artifactsDir, AUDIT_TASKS_FILENAME)
             : null,
         runtime_validation_tasks: params.bundle.runtime_validation_tasks
-            ? join(params.artifactsDir, "runtime_validation_tasks.json")
+            ? join(params.artifactsDir, RUNTIME_VALIDATION_TASKS_FILENAME)
             : null,
     };
     const suggestedInputs = buildSuggestedInputs(params.artifactsDir, params.state.status, isConfigError);

package/dist/supervisor/runLedger.d.ts

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

package/dist/supervisor/runLedger.js

@@ -1,20 +1,127 @@
+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";
+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 `${artifactsDir}/run-ledger.json`;
+    return join(artifactsDir, RUN_LEDGER_FILENAME);
+}
+function ledgerLockPath(artifactsDir) {
+    return join(artifactsDir, RUN_LEDGER_LOCK_FILENAME);
+}
+function buildTempLedgerPath(artifactsDir) {
+    return join(artifactsDir, `${RUN_LEDGER_FILENAME}.${process.pid}.${randomUUID()}.tmp`);
+}
+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.`);
+    }
+    const requireString = (field) => {
+        const entry = value[field];
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new Error(`Invalid run ledger in ${fieldPath}.${field}: expected a non-empty string.`);
+        }
+        return entry;
+    };
+    const requireNullableString = (field) => {
+        const entry = value[field];
+        if (entry === null) {
+            return null;
+        }
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new Error(`Invalid run ledger in ${fieldPath}.${field}: expected a string or null.`);
+        }
+        return entry;
+    };
+    const status = value.status;
+    if (typeof status !== "string" ||
+        !VALID_RUN_LEDGER_STATUSES.has(status)) {
+        throw new Error(`Invalid run ledger in ${fieldPath}.status: expected one of ${Array.from(VALID_RUN_LEDGER_STATUSES).join(", ")}.`);
+    }
+    return {
+        run_id: requireString("run_id"),
+        provider: requireString("provider"),
+        obligation_id: requireNullableString("obligation_id"),
+        selected_executor: requireNullableString("selected_executor"),
+        status: status,
+        started_at: requireString("started_at"),
+        ended_at: requireString("ended_at"),
+        result_path: requireString("result_path"),
+    };
+}
+function parseRunLedger(value, path) {
+    if (!isRecord(value)) {
+        throw new Error(`Invalid run ledger in ${path}: expected an object.`);
+    }
+    if (!Array.isArray(value.runs)) {
+        throw new Error(`Invalid run ledger in ${path}: expected runs to be an array.`);
+    }
+    return {
+        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 {
-        return await readJsonFile(ledgerPath(artifactsDir));
+        return parseRunLedger(await readJsonFile(path), path);
     }
     catch (error) {
         if (isFileMissingError(error)) {
+            // A missing run ledger just means no worker runs have been recorded yet.
             return { runs: [] };
         }
         throw error;
     }
 }
 export async function appendRunLedgerEntry(artifactsDir, entry) {
-    const ledger = await loadRunLedger(artifactsDir);
-    ledger.runs.push(entry);
-    await writeJsonFile(ledgerPath(artifactsDir), ledger);
+    const lockHandle = await acquireLedgerLock(artifactsDir);
+    const path = ledgerPath(artifactsDir);
+    const tempPath = buildTempLedgerPath(artifactsDir);
+    try {
+        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 rm(tempPath, { force: true }).catch(() => undefined);
+    }
 }

package/dist/supervisor/sessionConfig.js

@@ -1,29 +1,29 @@
+import { join } from "node:path";
 import { readOptionalJsonFile } from "../io/json.js";
+import { formatValidationIssues, } from "../validation/basic.js";
 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) {
-    return `${artifactsDir}/session-config.json`;
+    return join(artifactsDir, SESSION_CONFIG_FILENAME);
 }
 export async function readSessionConfigFile(artifactsDir) {
     return await readOptionalJsonFile(getSessionConfigPath(artifactsDir));
 }
-function formatValidationIssues(configPath, issues) {
-    const details = issues
-        .map((issue) => `- ${issue.path}: ${issue.message}`)
-        .join("\n");
-    return `Invalid ${configPath}:\n${details}`;
+function formatConfigValidationIssues(configPath, issues) {
+    return `Invalid ${configPath}:\n${formatValidationIssues(issues).replace(/^  /gm, "- ")}`;
 }
 export async function loadSessionConfig(artifactsDir) {
     const configPath = getSessionConfigPath(artifactsDir);
     const rawConfig = await readOptionalJsonFile(configPath);
     if (rawConfig === undefined) {
-        const defaultConfig = { provider: "local-subprocess" };
-        await writeJsonFile(configPath, defaultConfig);
-        return defaultConfig;
+        await writeJsonFile(configPath, DEFAULT_SESSION_CONFIG);
+        return { ...DEFAULT_SESSION_CONFIG };
     }
     const issues = validateSessionConfig(rawConfig);
     if (issues.length > 0) {
-        throw new Error(formatValidationIssues(configPath, issues));
+        throw new Error(formatConfigValidationIssues(configPath, issues));
     }
     return rawConfig;
 }