auditor-lambda 0.1.0

package/dist/cli.js

@@ -0,0 +1,724 @@
+import { mkdir } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { resolve } from "node:path";
+import { buildRepoManifest } from "./extractors/fileInventory.js";
+import { buildFileDisposition } from "./extractors/disposition.js";
+import { buildCriticalFlowManifest } from "./extractors/flows.js";
+import { buildSurfaceManifest } from "./extractors/surfaces.js";
+import { buildUnitManifest } from "./orchestrator/unitBuilder.js";
+import { buildFlowCoverage } from "./orchestrator/flowCoverage.js";
+import { buildRuntimeValidationTasks, buildPlaceholderRuntimeValidationReport, } from "./orchestrator/runtimeValidation.js";
+import { initializeCoverageFromPlan } from "./orchestrator/planning.js";
+import { loadArtifactBundle, writeCoreArtifacts, } from "./io/artifacts.js";
+import { readJsonFile, writeJsonFile } from "./io/json.js";
+import { validateArtifactBundle } from "./validation/artifacts.js";
+import { validateConfiguredProviderEnvironment, validateSessionConfig, } from "./validation/sessionConfig.js";
+import { buildSynthesisReport } from "./reporting/synthesis.js";
+import { deriveAuditState } from "./orchestrator/state.js";
+import { advanceAudit } from "./orchestrator/advance.js";
+import { decideNextStep } from "./orchestrator/nextStep.js";
+import { createFreshSessionProvider, resolveFreshSessionProviderName, } from "./providers/index.js";
+import { appendRunLedgerEntry } from "./supervisor/runLedger.js";
+import { buildAuditCodeHandoff, writeAuditCodeHandoffArtifacts, } from "./supervisor/operatorHandoff.js";
+import { getSessionConfigPath, loadSessionConfig, readSessionConfigFile, } from "./supervisor/sessionConfig.js";
+import { buildRunId, ensureSupervisorDirs, getRunPaths, writeWorkerTaskFiles, } from "./io/runArtifacts.js";
+import { renderWorkerPrompt } from "./prompts/renderWorkerPrompt.js";
+const ADVANCE_AUDIT_CONTRACT_VERSION = "audit-code/v1alpha1";
+const WORKER_RESULT_CONTRACT_VERSION = "audit-code-worker-result/v1alpha1";
+const sampleFiles = [
+    { path: "src/api/auth.ts", size_bytes: 1240, hash: "abc123" },
+    { path: "src/lib/session.ts", size_bytes: 980, hash: "def456" },
+    { path: "infra/deploy.yml", size_bytes: 420, hash: "ghi789" },
+    { path: "docs/notes.md", size_bytes: 300, hash: "doc111" },
+];
+function getFlag(argv, name, fallback) {
+    const index = argv.indexOf(name);
+    if (index >= 0 && argv[index + 1])
+        return argv[index + 1];
+    return fallback;
+}
+function hasFlag(argv, name) {
+    return argv.includes(name);
+}
+function getArtifactsDir(argv) {
+    return resolve(getFlag(argv, "--artifacts-dir", ".artifacts"));
+}
+function getRootDir(argv) {
+    return resolve(getFlag(argv, "--root", "."));
+}
+function getMaxRuns(argv) {
+    const raw = Number(getFlag(argv, "--max-runs", "25"));
+    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 25;
+}
+function getUiMode(argv, fallback = "headless") {
+    const raw = getFlag(argv, "--ui");
+    if (raw === "visible")
+        return "visible";
+    if (raw === "headless")
+        return "headless";
+    return fallback;
+}
+function buildEnvelope(params) {
+    return {
+        contract_version: ADVANCE_AUDIT_CONTRACT_VERSION,
+        audit_state: params.audit_state,
+        selected_obligation: params.selected_obligation,
+        selected_executor: params.selected_executor,
+        progress_made: params.progress_made,
+        artifacts_written: params.artifacts_written,
+        progress_summary: params.progress_summary,
+        next_likely_step: params.next_likely_step,
+        handoff: params.handoff,
+    };
+}
+async function emitEnvelope(params) {
+    const handoff = buildAuditCodeHandoff({
+        root: params.root,
+        artifactsDir: params.artifactsDir,
+        state: params.audit_state,
+        bundle: params.bundle,
+        providerName: params.providerName,
+        progressSummary: params.progress_summary,
+    });
+    await writeAuditCodeHandoffArtifacts(handoff);
+    console.log(JSON.stringify(buildEnvelope({
+        audit_state: params.audit_state,
+        selected_obligation: params.selected_obligation,
+        selected_executor: params.selected_executor,
+        progress_made: params.progress_made,
+        artifacts_written: params.artifacts_written,
+        progress_summary: params.progress_summary,
+        next_likely_step: params.next_likely_step,
+        handoff,
+    }), null, 2));
+}
+function buildManualReviewBlocker(providerName) {
+    return providerName === "local-subprocess"
+        ? "Automatic local-subprocess work is exhausted. Remaining audit tasks require explicit audit results or an interactive provider such as claude-code, opencode, or subprocess-template."
+        : "Automatic work is exhausted. Remaining audit tasks require explicit audit results or an interactive provider.";
+}
+function prefixValidationIssues(prefix, issues) {
+    return issues.map((issue) => ({
+        path: issue.path.length === 0
+            ? prefix
+            : issue.path === prefix || issue.path.startsWith(`${prefix}.`)
+                ? issue.path
+                : `${prefix}.${issue.path}`,
+        message: issue.message,
+    }));
+}
+function buildBlockedAuditState(params) {
+    return {
+        ...params.state,
+        status: "blocked",
+        last_executor: params.executor ?? params.state.last_executor,
+        last_obligation: params.obligationId ?? params.state.last_obligation,
+        blockers: [...new Set([...(params.state.blockers ?? []), params.blocker])],
+        obligations: params.state.obligations.map((item) => item.id === params.obligationId
+            ? {
+                ...item,
+                state: "blocked",
+                reason: params.blocker,
+            }
+            : item),
+    };
+}
+async function countLines(path) {
+    return new Promise((resolve, reject) => {
+        let lines = 1;
+        let byteCount = 0;
+        const stream = createReadStream(path);
+        stream.on("data", (chunk) => {
+            const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            byteCount += buffer.length;
+            for (let i = 0; i < buffer.length; ++i) {
+                if (buffer[i] === 10)
+                    lines++;
+            }
+        });
+        stream.on("end", () => resolve(byteCount === 0 ? 0 : lines));
+        stream.on("error", reject);
+    });
+}
+async function buildLineIndex(root, repoManifest) {
+    const entries = [];
+    const batchSize = 25;
+    for (let i = 0; i < repoManifest.files.length; i += batchSize) {
+        const batch = repoManifest.files.slice(i, i + batchSize);
+        const results = await Promise.all(batch.map(async (file) => {
+            try {
+                return [
+                    file.path,
+                    await countLines(resolve(root, file.path)),
+                ];
+            }
+            catch {
+                return [file.path, 0];
+            }
+        }));
+        entries.push(...results);
+    }
+    return Object.fromEntries(entries);
+}
+async function runAuditStep(options) {
+    const bundle = await loadArtifactBundle(options.artifactsDir);
+    const auditResults = options.auditResultsPath
+        ? await readJsonFile(options.auditResultsPath)
+        : undefined;
+    const runtimeValidationUpdates = options.runtimeUpdatesPath
+        ? await readJsonFile(options.runtimeUpdatesPath)
+        : undefined;
+    const externalAnalyzerResults = options.externalAnalyzerPath
+        ? await readJsonFile(options.externalAnalyzerPath)
+        : undefined;
+    const lineIndex = bundle.repo_manifest
+        ? await buildLineIndex(options.root, bundle.repo_manifest)
+        : undefined;
+    const result = await advanceAudit(bundle, {
+        root: options.root,
+        lineIndex,
+        auditResults,
+        runtimeValidationUpdates,
+        externalAnalyzerResults,
+        preferredExecutor: options.preferredExecutor,
+    });
+    await writeCoreArtifacts(options.artifactsDir, result.updated_bundle);
+    return result;
+}
+function isWorkerResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.contract_version ===
+            WORKER_RESULT_CONTRACT_VERSION);
+}
+export async function runSample() {
+    const repoManifest = buildRepoManifest("sample-repo", sampleFiles);
+    const disposition = buildFileDisposition(repoManifest);
+    const unitManifest = buildUnitManifest(repoManifest, disposition);
+    const surfaceManifest = buildSurfaceManifest(repoManifest, disposition);
+    const criticalFlows = buildCriticalFlowManifest(repoManifest, surfaceManifest, disposition);
+    const coverage = initializeCoverageFromPlan(repoManifest, unitManifest, disposition);
+    const sampleResults = [
+        {
+            task_id: "src-api:security:src/api/auth.ts:1-100",
+            unit_id: unitManifest.units[0]?.unit_id ?? "sample-unit",
+            pass_id: "pass:security",
+            lens: "security",
+            agent_role: "security-auditor",
+            reviewed_ranges: [{ path: "src/api/auth.ts", start: 1, end: 100 }],
+            findings: [],
+            notes: ["Sample result ingestion path."],
+            requires_followup: false,
+        },
+    ];
+    const flowCoverage = buildFlowCoverage(criticalFlows, coverage);
+    const runtimeValidationTasks = buildRuntimeValidationTasks(unitManifest, criticalFlows, flowCoverage);
+    const runtimeValidationReport = buildPlaceholderRuntimeValidationReport(runtimeValidationTasks);
+    const synthesisReport = buildSynthesisReport(sampleResults, runtimeValidationReport);
+    const auditState = deriveAuditState({
+        repo_manifest: repoManifest,
+        file_disposition: disposition,
+        unit_manifest: unitManifest,
+        surface_manifest: surfaceManifest,
+        critical_flows: criticalFlows,
+        flow_coverage: flowCoverage,
+        coverage_matrix: coverage,
+        runtime_validation_tasks: runtimeValidationTasks,
+        runtime_validation_report: runtimeValidationReport,
+        audit_results: sampleResults,
+        synthesis_report: synthesisReport,
+    });
+    const artifactsDir = getArtifactsDir(process.argv);
+    await mkdir(artifactsDir, { recursive: true });
+    await writeCoreArtifacts(artifactsDir, {
+        repo_manifest: repoManifest,
+        file_disposition: disposition,
+        unit_manifest: unitManifest,
+        surface_manifest: surfaceManifest,
+        critical_flows: criticalFlows,
+        flow_coverage: flowCoverage,
+        coverage_matrix: coverage,
+        runtime_validation_tasks: runtimeValidationTasks,
+        runtime_validation_report: runtimeValidationReport,
+        audit_results: sampleResults,
+        synthesis_report: synthesisReport,
+        audit_state: auditState,
+    });
+    console.log(JSON.stringify({ audit_state: auditState, artifacts_dir: artifactsDir }, null, 2));
+}
+async function cmdAdvanceAudit(argv) {
+    const root = getRootDir(argv);
+    const artifactsDir = getArtifactsDir(argv);
+    const sessionConfig = await loadSessionConfig(artifactsDir);
+    const providerName = resolveFreshSessionProviderName(getFlag(argv, "--provider"), sessionConfig);
+    const externalAnalyzerPath = getFlag(argv, "--external-analyzer-results");
+    const result = await runAuditStep({
+        root,
+        artifactsDir,
+        preferredExecutor: getFlag(argv, "--preferred-executor") ??
+            (externalAnalyzerPath ? "external_analyzer_import_executor" : undefined),
+        auditResultsPath: getFlag(argv, "--results"),
+        runtimeUpdatesPath: getFlag(argv, "--updates"),
+        externalAnalyzerPath,
+    });
+    await emitEnvelope({
+        root,
+        artifactsDir,
+        bundle: result.updated_bundle,
+        audit_state: result.audit_state,
+        selected_obligation: result.selected_obligation,
+        selected_executor: result.selected_executor,
+        progress_made: result.progress_made,
+        artifacts_written: result.artifacts_written,
+        progress_summary: result.progress_summary,
+        next_likely_step: result.next_likely_step,
+        providerName,
+    });
+}
+async function cmdRunToCompletion(argv) {
+    const root = getRootDir(argv);
+    const artifactsDir = getArtifactsDir(argv);
+    const sessionConfig = await loadSessionConfig(artifactsDir);
+    const provider = createFreshSessionProvider(getFlag(argv, "--provider"), sessionConfig);
+    const uiMode = getUiMode(argv, sessionConfig.ui_mode ?? "headless");
+    const maxRuns = getMaxRuns(argv);
+    const timeoutMs = sessionConfig.timeout_ms ?? 30 * 60 * 1000;
+    const selfCliPath = resolve(process.argv[1] ?? "");
+    await mkdir(artifactsDir, { recursive: true });
+    await ensureSupervisorDirs(artifactsDir);
+    let pendingAuditResultsPath = getFlag(argv, "--results");
+    let pendingRuntimeUpdatesPath = getFlag(argv, "--updates");
+    let pendingExternalAnalyzerPath = getFlag(argv, "--external-analyzer-results");
+    let runCount = 0;
+    let anyProgress = false;
+    let lastResult = null;
+    const artifactsWritten = new Set();
+    while (runCount < maxRuns) {
+        const bundle = await loadArtifactBundle(artifactsDir);
+        const decision = decideNextStep(bundle);
+        let preferredExecutor = decision.selected_executor;
+        let obligationId = decision.selected_obligation;
+        let auditResultsPath;
+        let runtimeUpdatesPath;
+        let externalAnalyzerPath;
+        if (pendingExternalAnalyzerPath) {
+            preferredExecutor = "external_analyzer_import_executor";
+            obligationId = "external_analyzer_import";
+            externalAnalyzerPath = pendingExternalAnalyzerPath;
+        }
+        else if (pendingAuditResultsPath && bundle.coverage_matrix) {
+            preferredExecutor = "result_ingestion_executor";
+            obligationId = "audit_results_ingested";
+            auditResultsPath = pendingAuditResultsPath;
+        }
+        else if (pendingRuntimeUpdatesPath && bundle.runtime_validation_tasks) {
+            preferredExecutor = "runtime_validation_update_executor";
+            obligationId = "runtime_validation_current";
+            runtimeUpdatesPath = pendingRuntimeUpdatesPath;
+        }
+        if (preferredExecutor === "agent" && provider.name === "local-subprocess") {
+            const blocker = buildManualReviewBlocker(provider.name);
+            const blockedState = buildBlockedAuditState({
+                state: bundle.audit_state ?? decision.state,
+                obligationId,
+                executor: preferredExecutor,
+                blocker,
+            });
+            await writeCoreArtifacts(artifactsDir, {
+                ...bundle,
+                audit_state: blockedState,
+            });
+            await emitEnvelope({
+                root,
+                artifactsDir,
+                bundle: {
+                    ...bundle,
+                    audit_state: blockedState,
+                },
+                audit_state: blockedState,
+                selected_obligation: obligationId,
+                selected_executor: preferredExecutor,
+                progress_made: anyProgress,
+                artifacts_written: Array.from(new Set([...artifactsWritten, "audit_state.json"])),
+                progress_summary: blocker,
+                next_likely_step: null,
+                providerName: provider.name,
+            });
+            return;
+        }
+        if (!preferredExecutor) {
+            const state = bundle.audit_state ?? decision.state;
+            await emitEnvelope({
+                root,
+                artifactsDir,
+                bundle,
+                audit_state: state,
+                selected_obligation: anyProgress
+                    ? (lastResult?.obligation_id ?? null)
+                    : null,
+                selected_executor: anyProgress
+                    ? (lastResult?.selected_executor ?? null)
+                    : null,
+                progress_made: anyProgress,
+                artifacts_written: Array.from(artifactsWritten),
+                progress_summary: anyProgress && state.status === "complete"
+                    ? `Completed audit in ${runCount} fresh worker runs.`
+                    : decision.reason,
+                next_likely_step: state.status === "complete" ? null : decision.selected_obligation,
+                providerName: provider.name,
+            });
+            return;
+        }
+        runCount += 1;
+        const runId = buildRunId(obligationId, runCount);
+        const paths = getRunPaths(artifactsDir, runId);
+        const task = {
+            contract_version: "audit-code-worker/v1alpha1",
+            run_id: runId,
+            repo_root: root,
+            artifacts_dir: artifactsDir,
+            obligation_id: obligationId,
+            preferred_executor: preferredExecutor,
+            result_path: paths.resultPath,
+            worker_command: [
+                process.execPath,
+                selfCliPath,
+                "worker-run",
+                "--task",
+                paths.taskPath,
+            ],
+            audit_results_path: auditResultsPath,
+            runtime_updates_path: runtimeUpdatesPath,
+            external_analyzer_results_path: externalAnalyzerPath,
+        };
+        const prompt = renderWorkerPrompt(task);
+        await writeWorkerTaskFiles(task, prompt, paths, artifactsDir);
+        const startedAt = new Date().toISOString();
+        let workerResult;
+        try {
+            await provider.launch({
+                repoRoot: root,
+                runId,
+                obligationId,
+                promptPath: paths.promptPath,
+                taskPath: paths.taskPath,
+                resultPath: paths.resultPath,
+                stdoutPath: paths.stdoutPath,
+                stderrPath: paths.stderrPath,
+                uiMode,
+                timeoutMs,
+            });
+            const candidate = await readJsonFile(paths.resultPath);
+            workerResult = isWorkerResult(candidate)
+                ? candidate
+                : {
+                    contract_version: WORKER_RESULT_CONTRACT_VERSION,
+                    run_id: runId,
+                    obligation_id: obligationId,
+                    status: "failed",
+                    progress_made: false,
+                    selected_executor: preferredExecutor,
+                    artifacts_written: [],
+                    summary: "Worker did not emit a valid worker result.",
+                    next_likely_step: decision.selected_obligation,
+                    errors: ["Invalid worker result contract."],
+                };
+        }
+        catch (error) {
+            workerResult = {
+                contract_version: WORKER_RESULT_CONTRACT_VERSION,
+                run_id: runId,
+                obligation_id: obligationId,
+                status: "failed",
+                progress_made: false,
+                selected_executor: preferredExecutor,
+                artifacts_written: [],
+                summary: `Worker launch failed for ${preferredExecutor}.`,
+                next_likely_step: decision.selected_obligation,
+                errors: [error instanceof Error ? error.message : String(error)],
+            };
+            await writeJsonFile(paths.resultPath, workerResult);
+        }
+        await appendRunLedgerEntry(artifactsDir, {
+            run_id: runId,
+            provider: provider.name,
+            obligation_id: obligationId,
+            selected_executor: workerResult.selected_executor,
+            status: workerResult.status,
+            started_at: startedAt,
+            ended_at: new Date().toISOString(),
+            result_path: paths.resultPath,
+        });
+        lastResult = workerResult;
+        if (workerResult.progress_made) {
+            anyProgress = true;
+        }
+        for (const artifact of workerResult.artifacts_written) {
+            artifactsWritten.add(artifact);
+        }
+        artifactsWritten.add("run-ledger.json");
+        if (externalAnalyzerPath)
+            pendingExternalAnalyzerPath = undefined;
+        if (auditResultsPath)
+            pendingAuditResultsPath = undefined;
+        if (runtimeUpdatesPath)
+            pendingRuntimeUpdatesPath = undefined;
+        if (workerResult.status === "failed" ||
+            workerResult.status === "blocked" ||
+            workerResult.status === "no_progress") {
+            const bundleAfter = await loadArtifactBundle(artifactsDir);
+            const state = bundleAfter.audit_state ?? deriveAuditState(bundleAfter);
+            await emitEnvelope({
+                root,
+                artifactsDir,
+                bundle: bundleAfter,
+                audit_state: state,
+                selected_obligation: workerResult.obligation_id,
+                selected_executor: workerResult.selected_executor,
+                progress_made: anyProgress,
+                artifacts_written: Array.from(artifactsWritten),
+                progress_summary: workerResult.summary,
+                next_likely_step: workerResult.next_likely_step,
+                providerName: provider.name,
+            });
+            return;
+        }
+    }
+    const bundle = await loadArtifactBundle(artifactsDir);
+    const decision = decideNextStep(bundle);
+    const state = bundle.audit_state ?? decision.state;
+    await emitEnvelope({
+        root,
+        artifactsDir,
+        bundle,
+        audit_state: state,
+        selected_obligation: lastResult?.obligation_id ?? decision.selected_obligation,
+        selected_executor: lastResult?.selected_executor ?? decision.selected_executor,
+        progress_made: anyProgress,
+        artifacts_written: Array.from(artifactsWritten),
+        progress_summary: `Reached max run limit (${maxRuns}) before terminal state.`,
+        next_likely_step: state.status === "complete" ? null : decision.selected_obligation,
+        providerName: provider.name,
+    });
+}
+async function cmdWorkerRun(argv) {
+    const taskPath = getFlag(argv, "--task");
+    if (!taskPath) {
+        throw new Error("worker-run requires --task <path>");
+    }
+    const task = await readJsonFile(taskPath);
+    let workerResult;
+    try {
+        const result = await runAuditStep({
+            root: task.repo_root,
+            artifactsDir: task.artifacts_dir,
+            preferredExecutor: task.preferred_executor,
+            auditResultsPath: task.audit_results_path,
+            runtimeUpdatesPath: task.runtime_updates_path,
+            externalAnalyzerPath: task.external_analyzer_results_path,
+        });
+        workerResult = {
+            contract_version: WORKER_RESULT_CONTRACT_VERSION,
+            run_id: task.run_id,
+            obligation_id: task.obligation_id,
+            status: result.progress_made ? "completed" : "no_progress",
+            progress_made: result.progress_made,
+            selected_executor: result.selected_executor,
+            artifacts_written: result.artifacts_written,
+            summary: result.progress_summary,
+            next_likely_step: result.next_likely_step,
+            errors: [],
+        };
+    }
+    catch (error) {
+        workerResult = {
+            contract_version: WORKER_RESULT_CONTRACT_VERSION,
+            run_id: task.run_id,
+            obligation_id: task.obligation_id,
+            status: "failed",
+            progress_made: false,
+            selected_executor: task.preferred_executor,
+            artifacts_written: [],
+            summary: `Worker failed for executor ${task.preferred_executor}.`,
+            next_likely_step: task.obligation_id,
+            errors: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+    await writeJsonFile(task.result_path, workerResult);
+    console.log(JSON.stringify(workerResult, null, 2));
+    if (workerResult.status === "failed") {
+        process.exitCode = 1;
+    }
+}
+async function cmdImportExternalAnalyzer(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const sourcePath = getFlag(argv, "--external-analyzer-results", `${artifactsDir}/external_analyzer_results.json`);
+    const externalAnalyzerResults = await readJsonFile(sourcePath);
+    const result = await runAuditStep({
+        root: getRootDir(argv),
+        artifactsDir,
+        preferredExecutor: "external_analyzer_import_executor",
+        externalAnalyzerPath: sourcePath,
+    });
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        tool: externalAnalyzerResults.tool,
+        imported_count: externalAnalyzerResults.results.length,
+        selected_executor: result.selected_executor,
+    }, null, 2));
+}
+async function cmdIntake(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const result = await runAuditStep({
+        root: getRootDir(argv),
+        artifactsDir,
+        preferredExecutor: "intake_executor",
+    });
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        selected_executor: result.selected_executor,
+        progress_summary: result.progress_summary,
+    }, null, 2));
+}
+async function cmdPlan(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const result = await runAuditStep({ root: getRootDir(argv), artifactsDir });
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        selected_executor: result.selected_executor,
+        progress_summary: result.progress_summary,
+        next_likely_step: result.next_likely_step,
+    }, null, 2));
+}
+async function cmdIngestResults(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const result = await runAuditStep({
+        root: getRootDir(argv),
+        artifactsDir,
+        preferredExecutor: "result_ingestion_executor",
+        auditResultsPath: getFlag(argv, "--results"),
+    });
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        selected_executor: result.selected_executor,
+        progress_summary: result.progress_summary,
+    }, null, 2));
+}
+async function cmdUpdateRuntimeValidation(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const result = await runAuditStep({
+        root: getRootDir(argv),
+        artifactsDir,
+        preferredExecutor: "runtime_validation_update_executor",
+        runtimeUpdatesPath: getFlag(argv, "--updates"),
+    });
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        selected_executor: result.selected_executor,
+        progress_summary: result.progress_summary,
+    }, null, 2));
+}
+async function cmdValidate(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const bundle = await loadArtifactBundle(artifactsDir);
+    const sessionConfigPath = getSessionConfigPath(artifactsDir);
+    const rawSessionConfig = await readSessionConfigFile(artifactsDir);
+    const artifactIssues = validateArtifactBundle(bundle);
+    const sessionConfigIssues = rawSessionConfig === undefined
+        ? []
+        : prefixValidationIssues("session_config", validateSessionConfig(rawSessionConfig));
+    const providerIssues = rawSessionConfig === undefined || sessionConfigIssues.length > 0
+        ? []
+        : prefixValidationIssues("session_config", validateConfiguredProviderEnvironment(rawSessionConfig));
+    const issues = [
+        ...artifactIssues,
+        ...sessionConfigIssues,
+        ...providerIssues,
+    ];
+    const resolvedProvider = rawSessionConfig === undefined
+        ? "local-subprocess"
+        : sessionConfigIssues.length > 0
+            ? null
+            : resolveFreshSessionProviderName(undefined, rawSessionConfig);
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        session_config_path: sessionConfigPath,
+        session_config_present: rawSessionConfig !== undefined,
+        resolved_provider: resolvedProvider,
+        artifact_issue_count: artifactIssues.length,
+        session_config_issue_count: sessionConfigIssues.length + providerIssues.length,
+        issue_count: issues.length,
+        issues,
+    }, null, 2));
+    process.exitCode = issues.length > 0 ? 1 : 0;
+}
+async function cmdRequeue(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const bundle = await loadArtifactBundle(artifactsDir);
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        task_count: bundle.requeue_tasks?.length ?? 0,
+    }, null, 2));
+}
+async function cmdSynthesize(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const result = await runAuditStep({
+        root: getRootDir(argv),
+        artifactsDir,
+        preferredExecutor: "synthesis_executor",
+    });
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        selected_executor: result.selected_executor,
+        progress_summary: result.progress_summary,
+    }, null, 2));
+}
+async function main(argv) {
+    const command = argv[2] ?? "sample-run";
+    switch (command) {
+        case "sample-run":
+            await runSample();
+            return;
+        case "advance-audit":
+            await cmdAdvanceAudit(argv);
+            return;
+        case "run-to-completion":
+            await cmdRunToCompletion(argv);
+            return;
+        case "worker-run":
+            await cmdWorkerRun(argv);
+            return;
+        case "import-external-analyzer":
+            await cmdImportExternalAnalyzer(argv);
+            return;
+        case "intake":
+            await cmdIntake(argv);
+            return;
+        case "plan":
+            await cmdPlan(argv);
+            return;
+        case "ingest-results":
+            await cmdIngestResults(argv);
+            return;
+        case "update-runtime-validation":
+            await cmdUpdateRuntimeValidation(argv);
+            return;
+        case "validate":
+            await cmdValidate(argv);
+            return;
+        case "requeue":
+            await cmdRequeue(argv);
+            return;
+        case "synthesize":
+            await cmdSynthesize(argv);
+            return;
+        default:
+            console.error(`Unknown command: ${command}`);
+            console.error("Available commands: sample-run, advance-audit, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, update-runtime-validation, validate, requeue, synthesize");
+            process.exitCode = 1;
+    }
+}
+await main(process.argv).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});