auditor-lambda 0.6.10 → 0.6.11

package/dist/cli.js

@@ -1,6 +1,6 @@
-import { mkdir, readFile, readdir, rm, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rm, } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { join, resolve, } from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildRepoManifest } from "./extractors/fileInventory.js";
 import { buildFileDisposition } from "./extractors/disposition.js";
@@ -10,46 +10,33 @@ import { buildUnitManifest } from "./orchestrator/unitBuilder.js";
 import { buildFlowCoverage } from "./orchestrator/flowCoverage.js";
 import { buildRuntimeValidationTasks, } from "./orchestrator/runtimeValidation.js";
 import { initializeCoverageFromPlan } from "./orchestrator/planning.js";
-import { loadArtifactBundle, writeCoreArtifacts, promoteFinalAuditReport, AUDIT_REPORT_FILENAME, } from "./io/artifacts.js";
-import { isFileMissingError, readJsonFile, writeJsonFile, prefixValidationIssues } from "@audit-tools/shared";
+import { loadArtifactBundle, writeCoreArtifacts, promoteFinalAuditReport, } from "./io/artifacts.js";
+import { isFileMissingError, readJsonFile, writeJsonFile, prefixValidationIssues, } from "@audit-tools/shared";
 import { buildQuotaSource } from "@audit-tools/shared/quota/compositeQuotaSource";
 import { validateArtifactBundle } from "./validation/artifacts.js";
 import { validateAuditResults, formatAuditResultIssues, } from "./validation/auditResults.js";
 import { validateConfiguredProviderEnvironment, validateSessionConfig, } from "./validation/sessionConfig.js";
 import { buildAuditReportModel, renderAuditReportMarkdown, } from "./reporting/synthesis.js";
 import { deriveAuditState } from "./orchestrator/state.js";
-import { advanceAudit } from "./orchestrator/advance.js";
-import { checkFileIntegrity } from "./orchestrator/fileIntegrity.js";
-import { decideNextStep } from "./orchestrator/nextStep.js";
-import { collectLowConfidenceEdges, buildEdgeReasoningPrompt, edgeReasoningContentHash, } from "./orchestrator/edgeReasoning.js";
-import { renderDesignReviewPrompt } from "./orchestrator/designReviewPrompt.js";
-import { renderSynthesisNarrativePrompt } from "./reporting/synthesisNarrativePrompt.js";
 import { createFreshSessionProvider, resolveFreshSessionProviderName, } from "./providers/index.js";
-import { appendRunLedgerEntry, loadRunLedger } from "./supervisor/runLedger.js";
-import { buildAuditCodeHandoff, writeAuditCodeHandoffArtifacts, } from "./supervisor/operatorHandoff.js";
-import { getSessionConfigPath, loadSessionConfig, persistAnalyzerSettings, readSessionConfigFile, } from "./supervisor/sessionConfig.js";
-import { resolveAnalyzerPlan, needsInstallDecision, } from "./extractors/analyzers/registry.js";
-import { buildPathLookup } from "./extractors/graph.js";
-import { buildDispositionMap } from "./extractors/disposition.js";
-import { clearDispatchFiles, buildRunId, ensureSupervisorDirs, getRunPaths, writeDispatchBatchFiles, writeWorkerTaskFiles, } from "./io/runArtifacts.js";
-import { renderWorkerPrompt } from "./prompts/renderWorkerPrompt.js";
-import { estimateTaskGroupTokens, sizeIndexFromManifest, } from "./orchestrator/reviewPackets.js";
-import { LOCAL_SUBPROCESS_PROVIDER_NAME } from "./providers/constants.js";
+import { loadRunLedger, } from "./supervisor/runLedger.js";
+import { getSessionConfigPath, loadSessionConfig, readSessionConfigFile, } from "./supervisor/sessionConfig.js";
+import { clearDispatchFiles, ensureSupervisorDirs, } from "./io/runArtifacts.js";
 import { runAuditCodeMcpServer } from "./mcp/server.js";
-import { scheduleWave, buildProviderModelKey, readQuotaState, recordWaveOutcome, resolveLimits, resolveHostActiveSubagentLimit, probeProvider, computeMaxSafeConcurrency, getQuotaStatePath, detectRateLimitError, computeCooldownUntil, runSlidingWindow, lookupDiscoveredLimits, updateDiscoveredLimits, mergeDiscoveredLimits, getHeaderExtractorForProvider, setQuotaStateDir, } from "./quota/index.js";
+import { scheduleWave, buildProviderModelKey, readQuotaState, resolveLimits, resolveHostActiveSubagentLimit, probeProvider, computeMaxSafeConcurrency, getQuotaStatePath, lookupDiscoveredLimits, setQuotaStateDir, } from "./quota/index.js";
 // Re-exports from extracted modules
 export { resolveHostDispatchCapability, DIRECT_CLI_DEFAULTS, getFlag, hasFlag, getOptionalBooleanFlag, getArtifactsDir, getRootDir, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, chunkArray, getUiMode, looksLikeCliFlag, countLines, warnIfNotGitRepo, } from "./cli/args.js";
-import { DIRECT_CLI_DEFAULTS, getFlag, hasFlag, getOptionalBooleanFlag, fromBase64Url, renderCommand, summarizeLaunchExit, taskResultPath, readStdinText, getArtifactsDir, getRootDir, warnIfNotGitRepo, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, getExplicitProvider, getHostModel, getHostMaxActiveSubagents, getQuotaProbeMode, resolveRunProviderName, chunkArray, getUiMode, looksLikeCliFlag, resolveHostDispatchCapability, countLines, listBatchResultFiles, } from "./cli/args.js";
-import { nextStepCommand, mergeAndIngestCommand, renderDispatchReviewPrompt, renderSingleTaskFallbackStepPrompt, renderPresentReportPrompt, renderAnalyzerInstallPrompt, renderEdgeReasoningStepPrompt, renderEdgeReasoningDispatchPrompt, renderBlockedStepPrompt, } from "./cli/prompts.js";
-import { writeCurrentStep, } from "./cli/steps.js";
-import { WORKER_RESULT_CONTRACT_VERSION, buildWorkerResult, persistWorkerRunArtifacts, isWorkerResult, buildWorkerFailureBlocker, formatAuditResultValidationError, } from "./cli/workerResult.js";
+import { DIRECT_CLI_DEFAULTS, getFlag, hasFlag, fromBase64Url, taskResultPath, readStdinText, getArtifactsDir, getRootDir, warnIfNotGitRepo, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, getExplicitProvider, getHostModel, getHostMaxActiveSubagents, getQuotaProbeMode, resolveRunProviderName, chunkArray, getUiMode, looksLikeCliFlag, countLines, } from "./cli/args.js";
+import { WORKER_RESULT_CONTRACT_VERSION, buildWorkerResult, formatAuditResultValidationError, } from "./cli/workerResult.js";
 import { DISPATCH_RESULT_MAP_FILENAME, ACTIVE_DISPATCH_FILENAME, resolveRunScopedArg, loadDispatchResultMap, entriesByTaskId, buildPendingAuditTasks, prepareDispatchArtifacts, } from "./cli/dispatch.js";
-import { readWaveManifest, writeWaveManifest, removeWaveManifest, buildWaveSlotEntry, } from "./cli/waveManifest.js";
 import { buildLineIndex, buildLineIndexForPaths, addFileLineCountHints, } from "./cli/lineIndex.js";
-import { emitEnvelope, buildBlockedAuditState, buildManualReviewBlocker, shouldRunInlineExecutor, } from "./cli/envelope.js";
-import { writeHandoffOnly, ensureSemanticReviewRun, } from "./cli/reviewRun.js";
+import { emitEnvelope, } from "./cli/envelope.js";
+import { persistConfigErrorHandoff } from "./cli/reviewRun.js";
 import { runAuditStep, ingestBatchAuditResults, } from "./cli/auditStep.js";
-const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+import { packageRoot } from "./cli/paths.js";
+import { cmdNextStep } from "./cli/nextStepCommand.js";
+import { cmdRunToCompletion } from "./cli/runToCompletion.js";
+import { cleanupStaleArtifactsDir } from "./cli/cleanup.js";
 const SAMPLE_REPO_FILES = [
     { path: "src/api/auth.ts", size_bytes: 1240, hash: "abc123" },
     { path: "src/lib/session.ts", size_bytes: 980, hash: "def456" },
@@ -73,28 +60,6 @@ export const cliTestUtils = {
     countLines,
     warnIfNotGitRepo,
 };
-async function persistConfigErrorHandoff(params) {
-    const bundle = await loadArtifactBundle(params.artifactsDir);
-    const blockedState = buildBlockedAuditState({
-        state: bundle.audit_state ?? deriveAuditState(bundle),
-        obligationId: null,
-        executor: null,
-        blocker: params.progressSummary,
-    });
-    await writeCoreArtifacts(params.artifactsDir, {
-        ...bundle,
-        audit_state: blockedState,
-    });
-    const handoff = buildAuditCodeHandoff({
-        root: params.root,
-        artifactsDir: params.artifactsDir,
-        state: blockedState,
-        bundle: { ...bundle, audit_state: blockedState },
-        progressSummary: params.progressSummary,
-        isConfigError: true,
-    });
-    await writeAuditCodeHandoffArtifacts(handoff);
-}
 export async function runSample(argv = process.argv) {
     const repoManifest = buildRepoManifest("sample-repo", SAMPLE_REPO_FILES);
     const disposition = buildFileDisposition(repoManifest);
@@ -255,1482 +220,6 @@ async function cmdAdvanceAudit(argv) {
         await promoteFinalAuditReport({ artifactsDir, repoRoot: root });
     }
 }
-async function runDeterministicForNextStep(params) {
-    let lastSummary = "";
-    let analyzers = params.analyzers;
-    for (let index = 0; index < params.maxRuns; index++) {
-        const bundle = await loadArtifactBundle(params.artifactsDir);
-        const decision = decideNextStep(bundle);
-        const state = decision.state;
-        if (state.status === "complete") {
-            await writeHandoffOnly({
-                root: params.root,
-                artifactsDir: params.artifactsDir,
-                bundle,
-                audit_state: state,
-                progress_summary: decision.reason,
-                providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
-            });
-            const promoted = await promoteFinalAuditReport({
-                artifactsDir: params.artifactsDir,
-                repoRoot: params.root,
-            });
-            return {
-                kind: "complete",
-                state,
-                bundle,
-                finalReportPath: promoted.promoted
-                    ? join(params.root, AUDIT_REPORT_FILENAME)
-                    : join(params.artifactsDir, AUDIT_REPORT_FILENAME),
-            };
-        }
-        if (index === 0 && bundle.repo_manifest) {
-            const pendingTasks = buildPendingAuditTasks(bundle);
-            const taskFiles = new Set();
-            for (const task of pendingTasks) {
-                for (const fp of Object.keys(task.file_line_counts ?? {}))
-                    taskFiles.add(fp);
-            }
-            if (taskFiles.size > 0) {
-                const integrity = await checkFileIntegrity(params.root, bundle.repo_manifest, [...taskFiles]);
-                if (!integrity.is_clean) {
-                    console.log(`File integrity check: ${integrity.changed_files.length} changed, ${integrity.missing_files.length} missing — re-running intake.`);
-                    await advanceAudit(bundle, { root: params.root, preferredExecutor: "intake_executor", opentoken: params.opentoken });
-                    continue;
-                }
-            }
-        }
-        if (decision.selected_executor === "graph_enrichment_executor") {
-            const includedFiles = bundle.repo_manifest
-                ? [
-                    ...new Set(buildPathLookup(bundle.repo_manifest, buildDispositionMap(bundle.file_disposition)).values()),
-                ]
-                : [];
-            const plan = resolveAnalyzerPlan(params.root, analyzers, includedFiles);
-            const unresolved = plan.filter(needsInstallDecision);
-            if (unresolved.length > 0) {
-                const decisionsPath = join(params.artifactsDir, "incoming", "analyzer-decisions.json");
-                let decisions;
-                try {
-                    decisions = await readJsonFile(decisionsPath);
-                }
-                catch (error) {
-                    if (!isFileMissingError(error))
-                        throw error;
-                }
-                if (decisions && typeof decisions === "object") {
-                    const settings = {};
-                    for (const [id, value] of Object.entries(decisions)) {
-                        if (value === "ephemeral" ||
-                            value === "permanent" ||
-                            value === "skip" ||
-                            value === "repo" ||
-                            value === "auto") {
-                            settings[id] = value;
-                        }
-                    }
-                    if (Object.keys(settings).length > 0) {
-                        const merged = await persistAnalyzerSettings(params.artifactsDir, settings);
-                        analyzers = merged.analyzers;
-                    }
-                    await unlink(decisionsPath).catch(() => { });
-                    continue;
-                }
-                return {
-                    kind: "analyzer_install",
-                    state,
-                    bundle,
-                    unresolved,
-                };
-            }
-            // Phase 4B — optional edge-reasoning producing turn. Once analyzer installs
-            // are resolved, if the flag is on and the floor carries low-confidence
-            // (< 0.65) edges, emit one bounded host turn (subagent dispatch or a single
-            // host step) to produce reason rewrites, then re-run. The enrichment
-            // executor applies the host-supplied rewrites in the SAME advanceAudit call
-            // that merges analyzer edges and writes analyzer_capability, so graph_bundle
-            // and its marker stay revision-consistent (no staleness loop). Flag off or
-            // no candidates → fall through and run the executor with no rewrites.
-            if (params.graphLlmEdgeReasoning === true && bundle.graph_bundle) {
-                const candidates = collectLowConfidenceEdges(bundle.graph_bundle);
-                if (candidates.length > 0) {
-                    const edgeReasoningResultsPath = join(params.artifactsDir, "incoming", "edge-reasoning.json");
-                    let edgeReasoningResults;
-                    try {
-                        edgeReasoningResults = await readJsonFile(edgeReasoningResultsPath);
-                    }
-                    catch (error) {
-                        if (!isFileMissingError(error))
-                            throw error;
-                    }
-                    if (edgeReasoningResults) {
-                        await runAuditStep({
-                            root: params.root,
-                            artifactsDir: params.artifactsDir,
-                            analyzers,
-                            graphLlmEdgeReasoning: true,
-                            edgeReasoningResultsPath,
-                            since: params.since,
-                            opentoken: params.opentoken,
-                        });
-                        await unlink(edgeReasoningResultsPath).catch(() => { });
-                        continue;
-                    }
-                    return { kind: "edge_reasoning", state, bundle, candidates };
-                }
-            }
-            // No undecided installs (and no pending edge reasoning): fall through to run
-            // the executor below (it installs for ephemeral/permanent, uses repo/cache,
-            // skips the rest).
-        }
-        if (decision.selected_executor === "design_review") {
-            const findingsPath = join(params.artifactsDir, "incoming", "design-review-findings.json");
-            let reviewFindings;
-            try {
-                reviewFindings = await readJsonFile(findingsPath);
-            }
-            catch (error) {
-                if (!isFileMissingError(error))
-                    throw error;
-            }
-            if (reviewFindings && Array.isArray(reviewFindings)) {
-                const existing = bundle.design_assessment;
-                if (existing) {
-                    existing.review_findings = reviewFindings;
-                    existing.reviewed = true;
-                    await writeJsonFile(join(params.artifactsDir, "design_assessment.json"), existing);
-                    await unlink(findingsPath).catch(() => { });
-                    continue;
-                }
-            }
-            return {
-                kind: "design_review",
-                state,
-                bundle,
-            };
-        }
-        if (decision.selected_executor === "synthesis_narrative_executor") {
-            const narrativePath = join(params.artifactsDir, "incoming", "synthesis-narrative.json");
-            let narrativeResults;
-            try {
-                narrativeResults = await readJsonFile(narrativePath);
-            }
-            catch (error) {
-                if (!isFileMissingError(error))
-                    throw error;
-            }
-            if (narrativeResults) {
-                await runAuditStep({
-                    root: params.root,
-                    artifactsDir: params.artifactsDir,
-                    preferredExecutor: "synthesis_narrative_executor",
-                    narrativeResultsPath: narrativePath,
-                    opentoken: params.opentoken,
-                });
-                await unlink(narrativePath).catch(() => { });
-                continue;
-            }
-            if (params.narrativeEnabled) {
-                return {
-                    kind: "synthesis_narrative",
-                    state,
-                    bundle,
-                };
-            }
-            // Narrative disabled: fall through so the deterministic omit runs below.
-        }
-        if (decision.selected_executor === "agent") {
-            return {
-                kind: "semantic_review",
-                ...(await ensureSemanticReviewRun({
-                    root: params.root,
-                    artifactsDir: params.artifactsDir,
-                    bundle,
-                    state,
-                    obligationId: decision.selected_obligation,
-                    selfCliPath: params.selfCliPath,
-                    timeoutMs: params.timeoutMs,
-                })),
-            };
-        }
-        if (!decision.selected_executor) {
-            await writeHandoffOnly({
-                root: params.root,
-                artifactsDir: params.artifactsDir,
-                bundle,
-                audit_state: state,
-                progress_summary: lastSummary || decision.reason,
-                providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
-            });
-            return {
-                kind: "blocked",
-                state,
-                bundle,
-                reason: lastSummary || decision.reason,
-            };
-        }
-        let result;
-        try {
-            result = await runAuditStep({
-                root: params.root,
-                artifactsDir: params.artifactsDir,
-                analyzers,
-                graphLlmEdgeReasoning: params.graphLlmEdgeReasoning,
-                since: params.since,
-                opentoken: params.opentoken,
-            });
-        }
-        catch (error) {
-            const current = await loadArtifactBundle(params.artifactsDir);
-            const currentState = deriveAuditState(current);
-            currentState.last_executor = decision.selected_executor ?? undefined;
-            currentState.last_obligation = decision.selected_obligation ?? undefined;
-            await writeCoreArtifacts(params.artifactsDir, { ...current, audit_state: currentState });
-            await writeJsonFile(join(params.artifactsDir, "steps", "deterministic-progress.json"), {
-                iteration: index + 1,
-                max_runs: params.maxRuns,
-                last_executor: decision.selected_executor,
-                last_obligation: decision.selected_obligation,
-                prior_summary: lastSummary || null,
-                error: error instanceof Error ? error.message : String(error),
-                timestamp: new Date().toISOString(),
-            });
-            const detail = error instanceof Error ? error.message : String(error);
-            throw new Error(`Deterministic executor ${decision.selected_executor} failed on obligation ${decision.selected_obligation} (iteration ${index + 1}/${params.maxRuns}, prior progress: ${lastSummary || "none"}): ${detail}`, { cause: error instanceof Error ? error : undefined });
-        }
-        lastSummary = result.progress_summary;
-        await writeJsonFile(join(params.artifactsDir, "steps", "deterministic-progress.json"), {
-            iteration: index + 1,
-            max_runs: params.maxRuns,
-            last_executor: result.selected_executor,
-            last_obligation: decision.selected_obligation,
-            progress_made: result.progress_made,
-            summary: result.progress_summary,
-            timestamp: new Date().toISOString(),
-        });
-        if (result.selected_executor !== "agent") {
-            await clearDispatchFiles(params.artifactsDir);
-        }
-        if (!result.progress_made) {
-            return {
-                kind: "blocked",
-                state: result.audit_state,
-                bundle: result.updated_bundle,
-                reason: result.progress_summary,
-            };
-        }
-    }
-    const bundle = await loadArtifactBundle(params.artifactsDir);
-    const state = deriveAuditState(bundle);
-    return {
-        kind: "blocked",
-        state,
-        bundle,
-        reason: `Reached max run limit (${params.maxRuns}) before a review, report, or blocker step was ready.`,
-    };
-}
-// Renders the actionable semantic-review step (packet dispatch or single-task
-// fallback) and writes steps/current-step.json. Shared by next-step and
-// run-to-completion so the backend produces the actionable step itself rather
-// than handing the host a second command. Host dispatch capability is resolved
-// by the caller (flag -> session config -> env -> default true) and is never
-// required from the host to make progress.
-async function renderSemanticReviewStep(params) {
-    const { root, artifactsDir, activeReviewRun } = params;
-    if (!params.hostCanDispatch) {
-        const singleTaskPromptPath = join(artifactsDir, "dispatch", "current-single-task-prompt.md");
-        const workerCommand = renderCommand(activeReviewRun.worker_command);
-        return writeCurrentStep({
-            artifactsDir,
-            stepKind: "single_task_fallback",
-            status: "ready",
-            runId: activeReviewRun.run_id,
-            allowedCommands: [workerCommand],
-            stopCondition: "Run the exact worker_command after one result, then stop without looping.",
-            repoRoot: root,
-            artifactPaths: {
-                active_review_task: activeReviewRun.task_path,
-                active_review_prompt: activeReviewRun.prompt_path,
-                pending_audit_tasks: activeReviewRun.pending_audit_tasks_path ?? null,
-                audit_results: activeReviewRun.audit_results_path,
-                single_task_prompt: singleTaskPromptPath,
-            },
-            prompt: renderSingleTaskFallbackStepPrompt({
-                singleTaskPromptPath,
-                activeReviewRun,
-            }),
-            access: {
-                read_paths: [singleTaskPromptPath],
-                write_paths: [activeReviewRun.audit_results_path],
-            },
-        });
-    }
-    const sessionConfig = await loadSessionConfig(artifactsDir).catch(() => ({}));
-    const provider = createFreshSessionProvider(undefined, sessionConfig);
-    const dispatch = await prepareDispatchArtifacts({
-        packageRoot,
-        runId: activeReviewRun.run_id,
-        artifactsDir,
-        root,
-        sessionConfig,
-        hostModel: sessionConfig.block_quota?.host_model ?? null,
-        queryLimits: provider.queryLimits?.bind(provider),
-        hostActiveSubagentLimit: params.hostMaxActiveSubagents,
-    });
-    const mergeCommand = mergeAndIngestCommand(artifactsDir, activeReviewRun.run_id);
-    const continueCommand = nextStepCommand(root, artifactsDir);
-    return writeCurrentStep({
-        artifactsDir,
-        stepKind: "dispatch_review",
-        status: "ready",
-        runId: activeReviewRun.run_id,
-        allowedCommands: [mergeCommand, continueCommand],
-        allowedMcpTools: ["auditor_merge_and_ingest", "auditor_continue_audit"],
-        progress: {
-            summary: `Dispatching ${dispatch.packet_count} review packet(s) covering ` +
-                `${dispatch.task_count} task(s) in waves of ${dispatch.wave_size}` +
-                (dispatch.skipped_task_count > 0
-                    ? `; ${dispatch.skipped_task_count} task(s) already completed.`
-                    : "."),
-            pending_packets: dispatch.packet_count,
-            pending_tasks: dispatch.task_count,
-            completed_tasks: dispatch.skipped_task_count,
-            wave_size: dispatch.wave_size,
-        },
-        stopCondition: "Dispatch every packet, run merge-and-ingest once, then run next-step.",
-        repoRoot: root,
-        artifactPaths: {
-            dispatch_plan: dispatch.dispatch_plan_path,
-            dispatch_quota: dispatch.dispatch_quota_path,
-            dispatch_warnings: dispatch.dispatch_warnings_path,
-            active_review_task: activeReviewRun.task_path,
-            pending_audit_tasks: activeReviewRun.pending_audit_tasks_path ?? null,
-        },
-        prompt: renderDispatchReviewPrompt({
-            root,
-            artifactsDir,
-            activeReviewRun,
-            dispatchPlanPath: dispatch.dispatch_plan_path,
-            dispatchQuotaPath: dispatch.dispatch_quota_path,
-            hostCanRestrictSubagentTools: params.hostCanRestrictSubagentTools,
-            hostCanSelectSubagentModel: params.hostCanSelectSubagentModel,
-        }),
-        access: {
-            read_paths: [
-                dispatch.dispatch_plan_path,
-                ...(dispatch.dispatch_quota_path ? [dispatch.dispatch_quota_path] : []),
-            ],
-            write_paths: [],
-        },
-    });
-}
-async function cmdNextStep(argv) {
-    const root = getRootDir(argv);
-    warnIfNotGitRepo(root);
-    const artifactsDir = getArtifactsDir(argv);
-    await mkdir(artifactsDir, { recursive: true });
-    await ensureSupervisorDirs(artifactsDir);
-    const hostCanDispatchSubagents = getOptionalBooleanFlag(argv, "--host-can-dispatch-subagents");
-    const hostCanRestrictSubagentTools = getOptionalBooleanFlag(argv, "--host-can-restrict-subagent-tools") ??
-        false;
-    const hostCanSelectSubagentModel = getOptionalBooleanFlag(argv, "--host-can-select-subagent-model") ?? false;
-    const hostMaxActiveSubagents = getHostMaxActiveSubagents(argv);
-    let sessionConfig;
-    try {
-        sessionConfig = await loadSessionConfig(artifactsDir);
-    }
-    catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        await persistConfigErrorHandoff({
-            root,
-            artifactsDir,
-            progressSummary: reason,
-        });
-        const step = await writeCurrentStep({
-            artifactsDir,
-            stepKind: "blocked",
-            status: "blocked",
-            runId: null,
-            allowedCommands: [],
-            stopCondition: "Report the configuration blocker and stop.",
-            repoRoot: root,
-            artifactPaths: {
-                operator_handoff: join(artifactsDir, "operator-handoff.json"),
-            },
-            prompt: renderBlockedStepPrompt(reason),
-        });
-        console.log(JSON.stringify(step, null, 2));
-        return;
-    }
-    const hostCanDispatch = resolveHostDispatchCapability({
-        explicit: hostCanDispatchSubagents,
-        sessionConfig,
-    });
-    const result = await runDeterministicForNextStep({
-        root,
-        artifactsDir,
-        selfCliPath: resolve(argv[1] ?? process.argv[1] ?? ""),
-        timeoutMs: getTimeoutMs(argv, sessionConfig),
-        maxRuns: getMaxRuns(argv),
-        opentoken: sessionConfig.opentoken?.enabled,
-        narrativeEnabled: sessionConfig.synthesis?.narrative !== false,
-        analyzers: sessionConfig.analyzers,
-        graphLlmEdgeReasoning: sessionConfig.graph?.llm_edge_reasoning,
-        since: getFlag(argv, "--since"),
-    });
-    if (result.kind === "complete") {
-        const step = await writeCurrentStep({
-            artifactsDir,
-            stepKind: "present_report",
-            status: "complete",
-            runId: null,
-            allowedCommands: [],
-            stopCondition: "Present the final report and stop.",
-            repoRoot: root,
-            artifactPaths: {
-                final_report: result.finalReportPath,
-            },
-            prompt: renderPresentReportPrompt(result.finalReportPath),
-        });
-        console.log(JSON.stringify(step, null, 2));
-        return;
-    }
-    if (result.kind === "blocked") {
-        const step = await writeCurrentStep({
-            artifactsDir,
-            stepKind: "blocked",
-            status: "blocked",
-            runId: null,
-            allowedCommands: [],
-            stopCondition: "Report the blocker and stop.",
-            repoRoot: root,
-            artifactPaths: {
-                operator_handoff: join(artifactsDir, "operator-handoff.json"),
-            },
-            prompt: renderBlockedStepPrompt(result.reason),
-        });
-        console.log(JSON.stringify(step, null, 2));
-        return;
-    }
-    if (result.kind === "design_review") {
-        const designReviewResultsPath = join(artifactsDir, "incoming", "design-review-findings.json");
-        await mkdir(join(artifactsDir, "incoming"), { recursive: true });
-        const continueCommand = nextStepCommand(root, artifactsDir);
-        const prompt = renderDesignReviewPrompt(result.bundle);
-        const fullPrompt = [
-            prompt,
-            "## Results path",
-            "",
-            `Write the JSON array of findings to:`,
-            "",
-            `  ${designReviewResultsPath}`,
-            "",
-            `Then run: ${continueCommand}`,
-            "",
-        ].join("\n");
-        const step = await writeCurrentStep({
-            artifactsDir,
-            stepKind: "design_review",
-            status: "ready",
-            runId: null,
-            allowedCommands: [continueCommand],
-            stopCondition: "Write design review findings to the results path, then run next-step.",
-            repoRoot: root,
-            artifactPaths: {
-                design_review_results: designReviewResultsPath,
-            },
-            prompt: fullPrompt,
-        });
-        console.log(JSON.stringify(step, null, 2));
-        return;
-    }
-    if (result.kind === "analyzer_install") {
-        const decisionsPath = join(artifactsDir, "incoming", "analyzer-decisions.json");
-        await mkdir(join(artifactsDir, "incoming"), { recursive: true });
-        const continueCommand = nextStepCommand(root, artifactsDir);
-        const step = await writeCurrentStep({
-            artifactsDir,
-            stepKind: "analyzer_install",
-            status: "ready",
-            runId: null,
-            allowedCommands: [continueCommand],
-            stopCondition: "Write analyzer install decisions to the results path, then run next-step.",
-            repoRoot: root,
-            artifactPaths: {
-                analyzer_decisions: decisionsPath,
-            },
-            prompt: renderAnalyzerInstallPrompt({
-                unresolved: result.unresolved,
-                decisionsPath,
-                continueCommand,
-            }),
-        });
-        console.log(JSON.stringify(step, null, 2));
-        return;
-    }
-    if (result.kind === "edge_reasoning") {
-        await mkdir(join(artifactsDir, "incoming"), { recursive: true });
-        const edgeReasoningResultsPath = join(artifactsDir, "incoming", "edge-reasoning.json");
-        const continueCommand = nextStepCommand(root, artifactsDir);
-        const basePrompt = buildEdgeReasoningPrompt(result.candidates);
-        const contentHash = edgeReasoningContentHash(result.candidates);
-        if (hostCanDispatch) {
-            // Dispatch path: isolate the (potentially large) edge-list prompt in a file
-            // and have the host fan it out to one subagent, mirroring the packet review
-            // dispatch contract. The subagent writes the rewrites file; next-step applies.
-            const edgeReasoningPromptPath = join(artifactsDir, "incoming", "edge-reasoning-prompt.md");
-            await writeFile(edgeReasoningPromptPath, basePrompt, "utf8");
-            const step = await writeCurrentStep({
-                artifactsDir,
-                stepKind: "edge_reasoning_dispatch",
-                status: "ready",
-                runId: null,
-                allowedCommands: [continueCommand],
-                stopCondition: "Dispatch one subagent to write the edge-reasoning rewrites, then run next-step.",
-                repoRoot: root,
-                artifactPaths: {
-                    edge_reasoning_prompt: edgeReasoningPromptPath,
-                    edge_reasoning_results: edgeReasoningResultsPath,
-                },
-                prompt: renderEdgeReasoningDispatchPrompt({
-                    promptPath: edgeReasoningPromptPath,
-                    resultsPath: edgeReasoningResultsPath,
-                    continueCommand,
-                    contentHash,
-                    candidateCount: result.candidates.length,
-                }),
-                access: {
-                    read_paths: [edgeReasoningPromptPath],
-                    write_paths: [edgeReasoningResultsPath],
-                },
-            });
-            console.log(JSON.stringify(step, null, 2));
-            return;
-        }
-        // One-step fallback (no callable subagent facility): the host produces the
-        // rewrites itself in a single bounded turn, mirroring the narrative step.
-        const step = await writeCurrentStep({
-            artifactsDir,
-            stepKind: "edge_reasoning",
-            status: "ready",
-            runId: null,
-            allowedCommands: [continueCommand],
-            stopCondition: "Write the edge-reasoning rewrites to the results path, then run next-step.",
-            repoRoot: root,
-            artifactPaths: {
-                edge_reasoning_results: edgeReasoningResultsPath,
-            },
-            prompt: renderEdgeReasoningStepPrompt({
-                basePrompt,
-                resultsPath: edgeReasoningResultsPath,
-                continueCommand,
-                contentHash,
-            }),
-            access: {
-                read_paths: [],
-                write_paths: [edgeReasoningResultsPath],
-            },
-        });
-        console.log(JSON.stringify(step, null, 2));
-        return;
-    }
-    if (result.kind === "synthesis_narrative") {
-        const narrativeResultsPath = join(artifactsDir, "incoming", "synthesis-narrative.json");
-        await mkdir(join(artifactsDir, "incoming"), { recursive: true });
-        const continueCommand = nextStepCommand(root, artifactsDir);
-        const basePrompt = result.bundle.audit_findings
-            ? renderSynthesisNarrativePrompt(result.bundle.audit_findings)
-            : "# Synthesis narrative\n\nNo findings report is available; write an empty themes array.";
-        const fullPrompt = [
-            basePrompt,
-            "## Results path",
-            "",
-            "Write the SynthesisNarrative JSON object to:",
-            "",
-            `  ${narrativeResultsPath}`,
-            "",
-            `Then run: ${continueCommand}`,
-            "",
-        ].join("\n");
-        const step = await writeCurrentStep({
-            artifactsDir,
-            stepKind: "synthesis_narrative",
-            status: "ready",
-            runId: null,
-            allowedCommands: [continueCommand],
-            stopCondition: "Write the synthesis narrative to the results path, then run next-step.",
-            repoRoot: root,
-            artifactPaths: {
-                synthesis_narrative_results: narrativeResultsPath,
-            },
-            prompt: fullPrompt,
-        });
-        console.log(JSON.stringify(step, null, 2));
-        return;
-    }
-    const step = await renderSemanticReviewStep({
-        root,
-        artifactsDir,
-        activeReviewRun: result.activeReviewRun,
-        hostCanDispatch,
-        hostMaxActiveSubagents,
-        hostCanRestrictSubagentTools,
-        hostCanSelectSubagentModel,
-    });
-    console.log(JSON.stringify(step, null, 2));
-}
-async function cmdRunToCompletion(argv) {
-    const root = getRootDir(argv);
-    warnIfNotGitRepo(root);
-    const artifactsDir = getArtifactsDir(argv);
-    await cleanupStaleArtifactsDir(artifactsDir);
-    await mkdir(artifactsDir, { recursive: true });
-    await ensureSupervisorDirs(artifactsDir);
-    let sessionConfig;
-    try {
-        sessionConfig = await loadSessionConfig(artifactsDir);
-    }
-    catch (error) {
-        await persistConfigErrorHandoff({
-            root,
-            artifactsDir,
-            progressSummary: error instanceof Error ? error.message : String(error),
-        });
-        throw error;
-    }
-    const explicitProvider = getExplicitProvider(argv);
-    const provider = createFreshSessionProvider(explicitProvider, sessionConfig);
-    const uiMode = getUiMode(argv, sessionConfig.ui_mode ?? "headless");
-    const maxRuns = getMaxRuns(argv);
-    const agentBatchSize = getAgentBatchSize(argv, sessionConfig);
-    const parallelWorkers = getParallelWorkers(argv, sessionConfig);
-    const timeoutMs = getTimeoutMs(argv, sessionConfig);
-    const hostModel = getHostModel(argv);
-    const selfCliPath = resolve(argv[1] ?? process.argv[1] ?? "");
-    const batchResultsDir = getBatchResultsDir(argv);
-    if (batchResultsDir && getFlag(argv, "--results")) {
-        throw new Error("Use either --results <file> or --batch-results <dir>, not both.");
-    }
-    let pendingBatchAuditResults = batchResultsDir
-        ? await listBatchResultFiles(batchResultsDir)
-        : [];
-    let pendingAuditResultsPath = getFlag(argv, "--results");
-    let pendingRuntimeUpdatesPath = getFlag(argv, "--updates");
-    let pendingExternalAnalyzerPath = getFlag(argv, "--external-analyzer-results");
-    let runCount = 0;
-    let deepeningCycles = 0;
-    const MAX_DEEPENING_CYCLES = 3;
-    let anyProgress = false;
-    let lastResult = null;
-    const artifactsWritten = new Set();
-    while (runCount < maxRuns) {
-        const bundle = await loadArtifactBundle(artifactsDir);
-        const decision = decideNextStep(bundle);
-        // Resume interrupted parallel wave: ingest any results that workers
-        // wrote before the previous process exited.
-        const priorWave = await readWaveManifest(artifactsDir);
-        if (priorWave) {
-            process.stderr.write(`[audit-code] Recovering interrupted wave (${priorWave.slots.length} slot(s), obligation ${priorWave.obligation_id}).\n`);
-            let recoveredProgress = false;
-            for (const entry of priorWave.slots) {
-                try {
-                    const results = await readJsonFile(entry.audit_results_path);
-                    if (!results || results.length === 0)
-                        continue;
-                    const stepResult = await runAuditStep({
-                        root,
-                        artifactsDir,
-                        preferredExecutor: "result_ingestion_executor",
-                        auditResultsPath: entry.audit_results_path,
-                    });
-                    if (stepResult.progress_made) {
-                        recoveredProgress = true;
-                        anyProgress = true;
-                        for (const a of stepResult.artifacts_written)
-                            artifactsWritten.add(a);
-                    }
-                }
-                catch {
-                    process.stderr.write(`[audit-code] Skipping unreadable results for ${entry.run_id}.\n`);
-                }
-            }
-            await removeWaveManifest(artifactsDir);
-            if (recoveredProgress)
-                continue;
-        }
-        if (decision.selected_executor === "agent" &&
-            bundle.audit_tasks?.some((t) => t.tags?.includes("selective_deepening") &&
-                t.status !== "complete") &&
-            !bundle.audit_tasks?.some((t) => !t.tags?.includes("selective_deepening") &&
-                t.status !== "complete")) {
-            deepeningCycles++;
-            if (deepeningCycles > MAX_DEEPENING_CYCLES) {
-                process.stderr.write(`[audit-code] Reached max deepening cycles (${MAX_DEEPENING_CYCLES}). Stopping to prevent churn.\n`);
-                break;
-            }
-        }
-        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 (pendingBatchAuditResults.length > 0 && bundle.coverage_matrix) {
-            preferredExecutor = "result_ingestion_executor";
-            obligationId = "audit_results_ingested";
-            auditResultsPath = pendingBatchAuditResults[0];
-        }
-        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_PROVIDER_NAME) {
-            const blocker = buildManualReviewBlocker(provider.name);
-            const blockedState = buildBlockedAuditState({
-                state: decision.state,
-                obligationId,
-                executor: preferredExecutor,
-                blocker,
-            });
-            await writeCoreArtifacts(artifactsDir, {
-                ...bundle,
-                audit_state: blockedState,
-            });
-            const blockRunId = buildRunId(obligationId, runCount + 1);
-            const blockPaths = getRunPaths(artifactsDir, blockRunId);
-            const blockPendingTasks = await addFileLineCountHints(root, buildPendingAuditTasks(bundle));
-            const blockPendingTasksPath = join(blockPaths.runDir, "pending-audit-tasks.json");
-            const blockAuditResultsPath = join(blockPaths.runDir, "audit-results.json");
-            const blockReadPaths = new Set();
-            for (const pt of blockPendingTasks) {
-                for (const fp of pt.file_paths)
-                    blockReadPaths.add(fp);
-            }
-            const blockTask = {
-                contract_version: "audit-code-worker/v1alpha1",
-                run_id: blockRunId,
-                repo_root: root,
-                artifacts_dir: artifactsDir,
-                obligation_id: obligationId,
-                preferred_executor: preferredExecutor,
-                result_path: blockPaths.resultPath,
-                worker_command: [
-                    process.execPath,
-                    selfCliPath,
-                    "worker-run",
-                    "--task",
-                    blockPaths.taskPath,
-                ],
-                audit_results_path: blockAuditResultsPath,
-                pending_audit_tasks_path: blockPendingTasksPath,
-                timeout_ms: timeoutMs,
-                max_retries: 0,
-                access: {
-                    read_paths: [...blockReadPaths],
-                    write_paths: [blockAuditResultsPath, blockPaths.resultPath],
-                },
-            };
-            const blockPrompt = renderWorkerPrompt(blockTask);
-            await writeWorkerTaskFiles(blockTask, blockPrompt, blockPaths, artifactsDir, blockPendingTasks);
-            await writeJsonFile(blockPendingTasksPath, blockPendingTasks);
-            const reviewRun = {
-                run_id: blockRunId,
-                task_path: blockPaths.taskPath,
-                prompt_path: blockPaths.promptPath,
-                pending_audit_tasks_path: blockPendingTasksPath,
-                audit_results_path: blockAuditResultsPath,
-                worker_command: blockTask.worker_command,
-            };
-            // Render the actionable dispatch / single-task step here instead of
-            // leaving the host to issue next-step as a second command. Capability is
-            // resolved from flags/config/env with a sane default, so nothing is
-            // required from the host to make progress. If rendering fails we still
-            // emit the hand-off below — run-to-completion is never worse than before,
-            // and next-step will re-render and surface the error loudly.
-            try {
-                await renderSemanticReviewStep({
-                    root,
-                    artifactsDir,
-                    activeReviewRun: reviewRun,
-                    hostCanDispatch: resolveHostDispatchCapability({
-                        explicit: getOptionalBooleanFlag(argv, "--host-can-dispatch-subagents"),
-                        sessionConfig,
-                    }),
-                    hostMaxActiveSubagents: getHostMaxActiveSubagents(argv),
-                    hostCanRestrictSubagentTools: getOptionalBooleanFlag(argv, "--host-can-restrict-subagent-tools") ?? false,
-                    hostCanSelectSubagentModel: getOptionalBooleanFlag(argv, "--host-can-select-subagent-model") ?? false,
-                });
-            }
-            catch (stepError) {
-                process.stderr.write(`[audit-code] Could not pre-render the review step; the operator hand-off points to next-step instead. ${stepError instanceof Error ? stepError.message : String(stepError)}\n`);
-            }
-            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,
-                activeReviewRun: reviewRun,
-            });
-            return;
-        }
-        if (!preferredExecutor) {
-            const state = decision.state;
-            await clearDispatchFiles(artifactsDir);
-            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,
-            });
-            if (state.status === "complete") {
-                await promoteFinalAuditReport({ artifactsDir, repoRoot: root });
-            }
-            return;
-        }
-        if (preferredExecutor === "agent" && parallelWorkers > 1) {
-            const quotaState = await readQuotaState();
-            const providerModelKey = buildProviderModelKey(provider.name, hostModel);
-            const quotaStateEntry = quotaState.entries[providerModelKey] ?? null;
-            const allCandidateTasks = buildPendingAuditTasks(bundle);
-            const candidateGroups = chunkArray(allCandidateTasks.slice(0, parallelWorkers * agentBatchSize), agentBatchSize);
-            const candidateSizeIndex = sizeIndexFromManifest(bundle.repo_manifest);
-            const slotTokenEstimates = candidateGroups.map((g) => estimateTaskGroupTokens(g, candidateSizeIndex));
-            const providerLimits = await provider.queryLimits?.(hostModel)
-                .then((r) => r ? { ...r, source: "provider_query" } : null)
-                .catch(() => null)
-                ?? null;
-            const cachedLimits = await lookupDiscoveredLimits(providerModelKey).catch(() => null);
-            const discoveredLimits = mergeDiscoveredLimits(providerLimits, cachedLimits);
-            const halfLifeHours = sessionConfig.quota?.empirical_half_life_hours ?? 24;
-            const quotaSource = buildQuotaSource({ halfLifeHours });
-            const quotaSourceSnapshot = await quotaSource.queryCurrentUsage(providerModelKey).catch(() => null);
-            const hostConcurrencyLimit = resolveHostActiveSubagentLimit({
-                sessionConfig,
-            });
-            const waveSchedule = scheduleWave({
-                providerName: resolveFreshSessionProviderName(getExplicitProvider(argv), sessionConfig),
-                sessionConfig,
-                hostModel,
-                requestedConcurrency: parallelWorkers,
-                estimatedSlotTokens: slotTokenEstimates,
-                quotaStateEntry,
-                hostConcurrencyLimit,
-                quotaSourceSnapshot,
-                discoveredLimits,
-            });
-            const waveSize = waveSchedule.wave_size;
-            if (waveSchedule.cooldown_until) {
-                const waitMs = new Date(waveSchedule.cooldown_until).getTime() - Date.now();
-                if (waitMs > 0) {
-                    const cappedWait = Math.min(waitMs, 120_000);
-                    process.stderr.write(`[quota] Cooldown active — waiting ${Math.ceil(cappedWait / 1000)}s before next wave.\n`);
-                    await new Promise((r) => setTimeout(r, cappedWait));
-                }
-            }
-            const taskGroups = candidateGroups.slice(0, waveSize);
-            const workerSlots = [];
-            for (const rawGroup of taskGroups) {
-                const group = await addFileLineCountHints(root, rawGroup);
-                runCount += 1;
-                const slotRunId = buildRunId(obligationId, runCount);
-                const slotPaths = getRunPaths(artifactsDir, slotRunId);
-                const slotAuditResultsPath = join(slotPaths.runDir, "audit-results.json");
-                const slotPendingTasksPath = join(slotPaths.runDir, "pending-audit-tasks.json");
-                const slotReadPaths = new Set();
-                for (const t of group) {
-                    for (const fp of t.file_paths)
-                        slotReadPaths.add(fp);
-                }
-                const slotTask = {
-                    contract_version: "audit-code-worker/v1alpha1",
-                    run_id: slotRunId,
-                    repo_root: root,
-                    artifacts_dir: artifactsDir,
-                    obligation_id: obligationId,
-                    preferred_executor: "agent",
-                    result_path: slotPaths.resultPath,
-                    worker_command: [process.execPath, selfCliPath, "worker-run", "--task", slotPaths.taskPath],
-                    audit_results_path: slotAuditResultsPath,
-                    pending_audit_tasks_path: slotPendingTasksPath,
-                    worker_command_mode: "deferred",
-                    timeout_ms: timeoutMs,
-                    max_retries: 0,
-                    access: {
-                        read_paths: [...slotReadPaths],
-                        write_paths: [slotAuditResultsPath, slotPaths.resultPath],
-                    },
-                };
-                const slotPrompt = renderWorkerPrompt(slotTask);
-                await writeWorkerTaskFiles(slotTask, slotPrompt, slotPaths, artifactsDir, group, { updateDispatch: false });
-                await writeJsonFile(slotPendingTasksPath, group);
-                workerSlots.push({ runId: slotRunId, paths: slotPaths, auditResultsPath: slotAuditResultsPath, pendingTasksPath: slotPendingTasksPath, group });
-            }
-            await writeDispatchBatchFiles(artifactsDir, workerSlots.map((slot) => ({
-                run_id: slot.runId,
-                task_path: slot.paths.taskPath,
-                prompt_path: slot.paths.promptPath,
-                result_path: slot.paths.resultPath,
-                status_path: slot.paths.statusPath,
-                audit_results_path: slot.auditResultsPath,
-                pending_audit_tasks_path: slot.pendingTasksPath,
-            })), workerSlots.flatMap((slot) => slot.group));
-            const parallelStartedAt = new Date().toISOString();
-            await writeWaveManifest(artifactsDir, {
-                obligation_id: obligationId ?? "unknown",
-                started_at: parallelStartedAt,
-                pid: process.pid,
-                slots: workerSlots.map(buildWaveSlotEntry),
-            });
-            const { results: launchResults } = await runSlidingWindow(workerSlots.map((slot) => () => provider.launch({
-                repoRoot: root,
-                runId: slot.runId,
-                obligationId,
-                promptPath: slot.paths.promptPath,
-                taskPath: slot.paths.taskPath,
-                resultPath: slot.paths.resultPath,
-                stdoutPath: slot.paths.stdoutPath,
-                stderrPath: slot.paths.stderrPath,
-                uiMode,
-                timeoutMs,
-            })), waveSize);
-            const launchErrorsByRunId = new Map();
-            for (let index = 0; index < launchResults.length; index++) {
-                const outcome = launchResults[index];
-                if (outcome?.status === "rejected") {
-                    launchErrorsByRunId.set(workerSlots[index].runId, outcome.reason instanceof Error
-                        ? outcome.reason.message
-                        : String(outcome.reason));
-                }
-                else if (outcome?.status === "fulfilled") {
-                    const launchExitSummary = summarizeLaunchExit(outcome.value);
-                    if (launchExitSummary) {
-                        launchErrorsByRunId.set(workerSlots[index].runId, launchExitSummary);
-                    }
-                }
-            }
-            // Result ingestion is intentionally sequential even though agent launch
-            // was parallel. Writing to coverage_matrix.json is not atomic, so
-            // concurrent ingest calls would race and corrupt coverage state.
-            let batchProgress = false;
-            const batchErrors = [];
-            for (const slot of workerSlots) {
-                const parallelEndedAt = new Date().toISOString();
-                let workerResult = buildWorkerResult({
-                    runId: slot.runId,
-                    obligationId,
-                    status: "no_progress",
-                    progressMade: false,
-                    selectedExecutor: "agent",
-                    artifactsWritten: [],
-                    summary: "Parallel worker batch made no progress.",
-                    nextLikelyStep: obligationId,
-                    errors: [],
-                });
-                try {
-                    const launchError = launchErrorsByRunId.get(slot.runId);
-                    if (launchError) {
-                        throw new Error(`Worker launch failed: ${launchError}`);
-                    }
-                    const auditResults = await readJsonFile(slot.auditResultsPath);
-                    const pendingTaskIds = new Set(slot.group.map((t) => t.task_id));
-                    const matchedCount = auditResults.filter((r) => pendingTaskIds.has(r.task_id)).length;
-                    if (slot.group.length > 0 && matchedCount === 0) {
-                        throw new Error("Worker did not emit any audit results for the assigned tasks.");
-                    }
-                    const issues = validateAuditResults(auditResults, slot.group, {
-                        lineIndex: await buildLineIndexForPaths(root, slot.group.flatMap((task) => task.file_paths)),
-                    });
-                    const errors = issues.filter((issue) => issue.severity === "error");
-                    const warnings = issues.filter((issue) => issue.severity === "warning");
-                    if (warnings.length > 0) {
-                        process.stderr.write(`audit-results validation: ${warnings.length} warning(s) for ${slot.runId}:\n` +
-                            formatAuditResultIssues(warnings) + "\n");
-                    }
-                    if (errors.length > 0) {
-                        throw new Error(`audit-results validation failed with ${errors.length} error(s):\n` +
-                            formatAuditResultIssues(errors));
-                    }
-                    const stepResult = await runAuditStep({
-                        root,
-                        artifactsDir,
-                        preferredExecutor: "result_ingestion_executor",
-                        auditResultsPath: slot.auditResultsPath,
-                    });
-                    workerResult = buildWorkerResult({
-                        runId: slot.runId,
-                        obligationId,
-                        status: stepResult.progress_made ? "completed" : "no_progress",
-                        progressMade: stepResult.progress_made,
-                        selectedExecutor: stepResult.selected_executor,
-                        artifactsWritten: stepResult.artifacts_written,
-                        summary: stepResult.progress_summary,
-                        nextLikelyStep: stepResult.next_likely_step,
-                        errors: [],
-                    });
-                    batchProgress ||= stepResult.progress_made;
-                    if (stepResult.progress_made)
-                        anyProgress = true;
-                    for (const a of stepResult.artifacts_written)
-                        artifactsWritten.add(a);
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    batchErrors.push(`${slot.runId}: ${message}`);
-                    workerResult = buildWorkerResult({
-                        runId: slot.runId,
-                        obligationId,
-                        status: "failed",
-                        progressMade: false,
-                        selectedExecutor: "agent",
-                        artifactsWritten: [],
-                        summary: `Worker failed for executor agent: ${message}`,
-                        nextLikelyStep: obligationId,
-                        errors: [message],
-                    });
-                    process.stderr.write(`[agent-batch] ${slot.runId} failed: ${message}\n`);
-                }
-                await persistWorkerRunArtifacts(slot.paths, workerResult, "parallel-deferred-agent");
-                await appendRunLedgerEntry(artifactsDir, {
-                    run_id: slot.runId,
-                    provider: provider.name,
-                    obligation_id: obligationId,
-                    selected_executor: workerResult.selected_executor,
-                    status: workerResult.status,
-                    started_at: parallelStartedAt,
-                    ended_at: parallelEndedAt,
-                    result_path: slot.paths.resultPath,
-                });
-                artifactsWritten.add("run-ledger.json");
-            }
-            // Record outcome for adaptive learning (best-effort — never blocks dispatch)
-            {
-                const rateLimitResults = batchErrors.map((e) => detectRateLimitError(e));
-                const rateLimitHit = rateLimitResults.find((r) => r.isRateLimited);
-                const retryAfterMs = rateLimitHit?.retryAfterMs ?? null;
-                await recordWaveOutcome(providerModelKey, {
-                    concurrency: workerSlots.length,
-                    estimated_tokens: slotTokenEstimates.slice(0, workerSlots.length).reduce((a, b) => a + b, 0),
-                    outcome: rateLimitHit ? "rate_limited" : batchErrors.length > 0 ? "timeout" : "success",
-                    cooldown_until: rateLimitHit ? computeCooldownUntil(retryAfterMs) : null,
-                }, sessionConfig.quota?.empirical_half_life_hours ?? 24).catch(() => undefined);
-            }
-            // Extract rate-limit headers from worker stderr (best-effort)
-            {
-                const extractor = getHeaderExtractorForProvider(provider.name);
-                for (const slot of workerSlots) {
-                    try {
-                        const stderr = await readFile(slot.paths.stderrPath, "utf8");
-                        const extracted = extractor.extract(stderr);
-                        if (extracted && (extracted.requests_per_minute != null || extracted.input_tokens_per_minute != null)) {
-                            await updateDiscoveredLimits(providerModelKey, {
-                                requests_per_minute: extracted.requests_per_minute,
-                                input_tokens_per_minute: extracted.input_tokens_per_minute,
-                                source: "header_extraction",
-                            });
-                            break; // one successful extraction is enough
-                        }
-                    }
-                    catch {
-                        // stderr file missing or unreadable — skip
-                    }
-                }
-            }
-            await removeWaveManifest(artifactsDir);
-            if (batchErrors.length > 0) {
-                const bundleAfter = await loadArtifactBundle(artifactsDir);
-                const blockedState = buildBlockedAuditState({
-                    state: bundleAfter.audit_state ?? deriveAuditState(bundleAfter),
-                    obligationId,
-                    executor: "agent",
-                    blocker: `Parallel worker batch failed for ${batchErrors.length} run(s). ` +
-                        batchErrors.slice(0, 3).join(" | "),
-                });
-                await writeCoreArtifacts(artifactsDir, {
-                    ...bundleAfter,
-                    audit_state: blockedState,
-                });
-                await emitEnvelope({
-                    root,
-                    artifactsDir,
-                    bundle: { ...bundleAfter, audit_state: blockedState },
-                    audit_state: blockedState,
-                    selected_obligation: obligationId,
-                    selected_executor: "agent",
-                    progress_made: anyProgress,
-                    artifacts_written: Array.from(new Set([...artifactsWritten, "audit_state.json"])),
-                    progress_summary: `Parallel worker batch failed for ${batchErrors.length} run(s).\n` +
-                        batchErrors.join("\n"),
-                    next_likely_step: null,
-                    providerName: provider.name,
-                });
-                return;
-            }
-            if (!batchProgress) {
-                const bundleAfter = await loadArtifactBundle(artifactsDir);
-                const state = bundleAfter.audit_state ?? deriveAuditState(bundleAfter);
-                await emitEnvelope({
-                    root,
-                    artifactsDir,
-                    bundle: bundleAfter,
-                    audit_state: state,
-                    selected_obligation: obligationId,
-                    selected_executor: "agent",
-                    progress_made: anyProgress,
-                    artifacts_written: Array.from(artifactsWritten),
-                    progress_summary: "Parallel worker batch made no progress.",
-                    next_likely_step: obligationId,
-                    providerName: provider.name,
-                });
-                return;
-            }
-            continue;
-        }
-        runCount += 1;
-        const runId = buildRunId(obligationId, runCount);
-        const paths = getRunPaths(artifactsDir, runId);
-        if (shouldRunInlineExecutor(preferredExecutor)) {
-            await clearDispatchFiles(artifactsDir);
-            const startedAt = new Date().toISOString();
-            let workerResult;
-            try {
-                const result = await runAuditStep({
-                    root,
-                    artifactsDir,
-                    preferredExecutor,
-                    auditResultsPath,
-                    runtimeUpdatesPath,
-                    externalAnalyzerPath,
-                    analyzers: sessionConfig.analyzers,
-                    since: getFlag(argv, "--since"),
-                });
-                workerResult = {
-                    contract_version: WORKER_RESULT_CONTRACT_VERSION,
-                    run_id: runId,
-                    obligation_id: obligationId,
-                    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) {
-                const message = error instanceof Error ? error.message : String(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: `Inline executor failed for ${preferredExecutor}: ${message}`,
-                    next_likely_step: decision.selected_obligation,
-                    errors: [message],
-                };
-            }
-            await persistWorkerRunArtifacts(paths, workerResult, "inline");
-            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 &&
-                pendingBatchAuditResults[0] === auditResultsPath &&
-                preferredExecutor === "result_ingestion_executor" &&
-                workerResult.status !== "failed" &&
-                workerResult.status !== "blocked") {
-                pendingBatchAuditResults.shift();
-            }
-            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 shouldBlock = workerResult.status === "failed" || workerResult.status === "blocked";
-                const state = shouldBlock
-                    ? buildBlockedAuditState({
-                        state: bundleAfter.audit_state ?? deriveAuditState(bundleAfter),
-                        obligationId: workerResult.obligation_id,
-                        executor: workerResult.selected_executor,
-                        blocker: buildWorkerFailureBlocker(workerResult),
-                    })
-                    : bundleAfter.audit_state ?? deriveAuditState(bundleAfter);
-                if (shouldBlock) {
-                    await writeCoreArtifacts(artifactsDir, {
-                        ...bundleAfter,
-                        audit_state: state,
-                    });
-                }
-                await emitEnvelope({
-                    root,
-                    artifactsDir,
-                    bundle: shouldBlock
-                        ? { ...bundleAfter, audit_state: state }
-                        : bundleAfter,
-                    audit_state: state,
-                    selected_obligation: workerResult.obligation_id,
-                    selected_executor: workerResult.selected_executor,
-                    progress_made: anyProgress,
-                    artifacts_written: Array.from(shouldBlock
-                        ? new Set([...artifactsWritten, "audit_state.json"])
-                        : artifactsWritten),
-                    progress_summary: buildWorkerFailureBlocker(workerResult),
-                    next_likely_step: shouldBlock ? null : workerResult.next_likely_step,
-                    providerName: provider.name,
-                });
-                return;
-            }
-            continue;
-        }
-        const pendingAuditTasks = preferredExecutor === "agent"
-            ? await addFileLineCountHints(root, buildPendingAuditTasks(bundle))
-            : undefined;
-        const pendingAuditTasksPath = preferredExecutor === "agent"
-            ? join(paths.runDir, "pending-audit-tasks.json")
-            : undefined;
-        const providerAuditResultsPath = preferredExecutor === "agent"
-            ? join(paths.runDir, "audit-results.json")
-            : auditResultsPath;
-        const providerReadPaths = new Set();
-        if (pendingAuditTasks) {
-            for (const pt of pendingAuditTasks) {
-                for (const fp of pt.file_paths)
-                    providerReadPaths.add(fp);
-            }
-        }
-        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: providerAuditResultsPath,
-            pending_audit_tasks_path: pendingAuditTasksPath,
-            runtime_updates_path: runtimeUpdatesPath,
-            external_analyzer_results_path: externalAnalyzerPath,
-            timeout_ms: timeoutMs,
-            max_retries: 0,
-            access: providerReadPaths.size > 0 ? {
-                read_paths: [...providerReadPaths],
-                write_paths: [providerAuditResultsPath ?? paths.resultPath, paths.resultPath],
-            } : undefined,
-        };
-        const prompt = renderWorkerPrompt(task);
-        await writeWorkerTaskFiles(task, prompt, paths, artifactsDir, pendingAuditTasks);
-        if (pendingAuditTasksPath && pendingAuditTasks) {
-            await writeJsonFile(pendingAuditTasksPath, pendingAuditTasks);
-        }
-        const startedAt = new Date().toISOString();
-        let workerResult;
-        let launchResult = null;
-        try {
-            launchResult = 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);
-            if (isWorkerResult(candidate)) {
-                workerResult = candidate;
-            }
-            else {
-                const launchExitSummary = summarizeLaunchExit(launchResult);
-                workerResult = {
-                    contract_version: WORKER_RESULT_CONTRACT_VERSION,
-                    run_id: runId,
-                    obligation_id: obligationId,
-                    status: "failed",
-                    progress_made: false,
-                    selected_executor: preferredExecutor,
-                    artifacts_written: [],
-                    summary: launchExitSummary
-                        ? `Worker did not emit a valid worker result after provider exit: ${launchExitSummary}`
-                        : "Worker did not emit a valid worker result.",
-                    next_likely_step: decision.selected_obligation,
-                    errors: ["Invalid worker result contract."],
-                };
-            }
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const launchExitSummary = launchResult && summarizeLaunchExit(launchResult);
-            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}: ${launchExitSummary ?? message}`,
-                next_likely_step: decision.selected_obligation,
-                errors: launchExitSummary ? [message, launchExitSummary] : [message],
-            };
-            await persistWorkerRunArtifacts(paths, workerResult, "provider-launch");
-        }
-        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 &&
-            pendingBatchAuditResults[0] === auditResultsPath &&
-            preferredExecutor === "result_ingestion_executor" &&
-            workerResult.status !== "failed" &&
-            workerResult.status !== "blocked") {
-            pendingBatchAuditResults.shift();
-        }
-        if (providerAuditResultsPath)
-            pendingAuditResultsPath = undefined;
-        if (runtimeUpdatesPath)
-            pendingRuntimeUpdatesPath = undefined;
-        if (workerResult.status === "failed" ||
-            workerResult.status === "blocked" ||
-            workerResult.status === "no_progress") {
-            const bundleAfter = await loadArtifactBundle(artifactsDir);
-            const shouldBlock = workerResult.status === "failed" || workerResult.status === "blocked";
-            const state = shouldBlock
-                ? buildBlockedAuditState({
-                    state: deriveAuditState(bundleAfter),
-                    obligationId: workerResult.obligation_id,
-                    executor: workerResult.selected_executor,
-                    blocker: buildWorkerFailureBlocker(workerResult),
-                })
-                : deriveAuditState(bundleAfter);
-            if (shouldBlock) {
-                await writeCoreArtifacts(artifactsDir, {
-                    ...bundleAfter,
-                    audit_state: state,
-                });
-            }
-            await emitEnvelope({
-                root,
-                artifactsDir,
-                bundle: shouldBlock
-                    ? { ...bundleAfter, audit_state: state }
-                    : bundleAfter,
-                audit_state: state,
-                selected_obligation: workerResult.obligation_id,
-                selected_executor: workerResult.selected_executor,
-                progress_made: anyProgress,
-                artifacts_written: Array.from(shouldBlock
-                    ? new Set([...artifactsWritten, "audit_state.json"])
-                    : artifactsWritten),
-                progress_summary: buildWorkerFailureBlocker(workerResult),
-                next_likely_step: shouldBlock ? null : workerResult.next_likely_step,
-                providerName: provider.name,
-            });
-            return;
-        }
-    }
-    const bundle = await loadArtifactBundle(artifactsDir);
-    const decision = decideNextStep(bundle);
-    const state = decision.state;
-    if (state.status === "complete") {
-        await clearDispatchFiles(artifactsDir);
-    }
-    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,
-    });
-    if (state.status === "complete") {
-        await promoteFinalAuditReport({ artifactsDir, repoRoot: root });
-    }
-}
 async function cmdWorkerRun(argv) {
     const taskPath = getFlag(argv, "--task");
     if (!taskPath) {
@@ -2443,22 +932,6 @@ async function cmdSynthesize(argv) {
         progress_summary: result.progress_summary,
     }, null, 2));
 }
-async function cleanupStaleArtifactsDir(artifactsDir) {
-    let status;
-    try {
-        const state = await readJsonFile(join(artifactsDir, "audit_state.json"));
-        status = state.status;
-    }
-    catch (error) {
-        if (!isFileMissingError(error)) {
-            throw error;
-        }
-        return;
-    }
-    if (status === "complete" || status === "not_started") {
-        await rm(artifactsDir, { recursive: true, force: true });
-    }
-}
 async function cmdCleanup(argv) {
     const artifactsDir = getArtifactsDir(argv);
     const dryRun = hasFlag(argv, "--dry-run");