auditor-lambda 0.3.20 → 0.3.22

package/dist/cli.js

@@ -32,9 +32,11 @@ import { buildReviewPackets, orderTasksForPacketReview, } from "./orchestrator/r
 import { buildFileAnchorSummary, } from "./orchestrator/fileAnchors.js";
 import { LOCAL_SUBPROCESS_PROVIDER_NAME } from "./providers/constants.js";
 import { runAuditCodeMcpServer } from "./mcp/server.js";
+import { scheduleWave, buildProviderModelKey, readQuotaState, recordWaveOutcome, resolveLimits, probeProvider, computeMaxSafeConcurrency, getQuotaStatePath, } from "./quota/index.js";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const ADVANCE_AUDIT_CONTRACT_VERSION = "audit-code/v1alpha1";
 const WORKER_RESULT_CONTRACT_VERSION = "audit-code-worker-result/v1alpha1";
+const STEP_CONTRACT_VERSION = "audit-code-step/v1alpha1";
 const LARGE_FILE_PACKET_TARGET_LINES = 2500;
 const SMALL_MODEL_HINT_MAX_LINES = 500;
 const SMALL_MODEL_HINT_MAX_ESTIMATED_TOKENS = 3000;
@@ -72,6 +74,19 @@ function getFlag(argv, name, fallback) {
 function hasFlag(argv, name) {
     return argv.includes(name);
 }
+function getOptionalBooleanFlag(argv, name) {
+    const raw = getFlag(argv, name);
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (raw === "true") {
+        return true;
+    }
+    if (raw === "false") {
+        return false;
+    }
+    throw new Error(`${name} must be either true or false.`);
+}
 function toBase64Url(value) {
     return Buffer.from(value, "utf8").toString("base64url");
 }
@@ -91,6 +106,12 @@ function safeArtifactStem(value) {
 function artifactNameForId(value, extension) {
     return `${safeArtifactStem(value)}_${digestId(value)}.${extension}`;
 }
+function quoteCommandArg(value) {
+    return /[\s"]/u.test(value) ? `"${value.replace(/"/g, '\\"')}"` : value;
+}
+function renderCommand(argv) {
+    return argv.map((item) => quoteCommandArg(item)).join(" ");
+}
 function taskResultPath(taskResultsDir, taskId) {
     return join(taskResultsDir, artifactNameForId(taskId, "json"));
 }
@@ -158,6 +179,27 @@ function getTimeoutMs(argv, sessionConfig) {
 function getExplicitProvider(argv) {
     return getFlag(argv, "--provider");
 }
+function getHostModel(argv) {
+    return getFlag(argv, "--host-model") ?? null;
+}
+function getQuotaProbeMode(argv, sessionConfig) {
+    const raw = getFlag(argv, "--quota-probe") ?? sessionConfig.quota?.probe ?? "auto";
+    if (raw === "auto" || raw === "never" || raw === "force")
+        return raw;
+    return "auto";
+}
+function detectRateLimitError(errorText) {
+    const lower = errorText.toLowerCase();
+    return lower.includes("429") || lower.includes("rate limit") || lower.includes("rate_limit");
+}
+function defaultCooldownUntil(resetAtHeader) {
+    if (resetAtHeader) {
+        const t = new Date(resetAtHeader).getTime();
+        if (!Number.isNaN(t))
+            return new Date(t).toISOString();
+    }
+    return new Date(Date.now() + 60_000).toISOString();
+}
 function resolveRunProviderName(argv, sessionConfig) {
     return resolveFreshSessionProviderName(getExplicitProvider(argv), sessionConfig);
 }
@@ -324,6 +366,309 @@ async function addFileLineCountHints(root, tasks) {
         file_line_counts: Object.fromEntries(task.file_paths.map((path) => [path, lineIndex[path] ?? 0])),
     }));
 }
+function activeReviewRunFromTask(artifactsDir, task) {
+    if (task.preferred_executor !== "agent" || !task.audit_results_path) {
+        return null;
+    }
+    const paths = getRunPaths(artifactsDir, task.run_id);
+    return {
+        run_id: task.run_id,
+        task_path: paths.taskPath,
+        prompt_path: paths.promptPath,
+        pending_audit_tasks_path: task.pending_audit_tasks_path,
+        audit_results_path: task.audit_results_path,
+        worker_command: task.worker_command,
+    };
+}
+async function loadCurrentActiveReviewRun(artifactsDir) {
+    try {
+        const task = await readJsonFile(join(artifactsDir, "dispatch", "current-task.json"));
+        return activeReviewRunFromTask(artifactsDir, task);
+    }
+    catch (error) {
+        if (isFileMissingError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+async function writeHandoffOnly(params) {
+    const handoff = buildAuditCodeHandoff({
+        root: params.root,
+        artifactsDir: params.artifactsDir,
+        state: params.audit_state,
+        bundle: params.bundle,
+        providerName: params.providerName,
+        progressSummary: params.progress_summary,
+        isConfigError: params.isConfigError,
+        activeReviewRun: params.activeReviewRun,
+    });
+    await writeAuditCodeHandoffArtifacts(handoff);
+}
+async function ensureSemanticReviewRun(params) {
+    const existingRun = await loadCurrentActiveReviewRun(params.artifactsDir);
+    if (existingRun) {
+        const blockedState = params.bundle.audit_state?.status === "blocked"
+            ? params.bundle.audit_state
+            : buildBlockedAuditState({
+                state: params.state,
+                obligationId: params.obligationId,
+                executor: "agent",
+                blocker: buildManualReviewBlocker(LOCAL_SUBPROCESS_PROVIDER_NAME),
+            });
+        const blockedBundle = { ...params.bundle, audit_state: blockedState };
+        await writeCoreArtifacts(params.artifactsDir, blockedBundle);
+        await writeHandoffOnly({
+            root: params.root,
+            artifactsDir: params.artifactsDir,
+            bundle: blockedBundle,
+            audit_state: blockedState,
+            progress_summary: buildManualReviewBlocker(LOCAL_SUBPROCESS_PROVIDER_NAME),
+            providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
+            activeReviewRun: existingRun,
+        });
+        return {
+            state: blockedState,
+            bundle: blockedBundle,
+            activeReviewRun: existingRun,
+        };
+    }
+    const blockedState = buildBlockedAuditState({
+        state: params.state,
+        obligationId: params.obligationId,
+        executor: "agent",
+        blocker: buildManualReviewBlocker(LOCAL_SUBPROCESS_PROVIDER_NAME),
+    });
+    await writeCoreArtifacts(params.artifactsDir, {
+        ...params.bundle,
+        audit_state: blockedState,
+    });
+    const runId = buildRunId(params.obligationId, 1);
+    const paths = getRunPaths(params.artifactsDir, runId);
+    const pendingTasks = await addFileLineCountHints(params.root, buildPendingAuditTasks(params.bundle));
+    const pendingTasksPath = join(paths.runDir, "pending-audit-tasks.json");
+    const auditResultsPath = join(paths.runDir, "audit-results.json");
+    const task = {
+        contract_version: "audit-code-worker/v1alpha1",
+        run_id: runId,
+        repo_root: params.root,
+        artifacts_dir: params.artifactsDir,
+        obligation_id: params.obligationId,
+        preferred_executor: "agent",
+        result_path: paths.resultPath,
+        worker_command: [
+            process.execPath,
+            params.selfCliPath,
+            "worker-run",
+            "--task",
+            paths.taskPath,
+        ],
+        audit_results_path: auditResultsPath,
+        pending_audit_tasks_path: pendingTasksPath,
+        timeout_ms: params.timeoutMs,
+        max_retries: 0,
+    };
+    const prompt = renderWorkerPrompt(task);
+    await writeWorkerTaskFiles(task, prompt, paths, params.artifactsDir, pendingTasks);
+    await writeJsonFile(pendingTasksPath, pendingTasks);
+    const activeReviewRun = activeReviewRunFromTask(params.artifactsDir, task);
+    if (!activeReviewRun) {
+        throw new Error("Internal error: failed to materialize active review run.");
+    }
+    const blockedBundle = {
+        ...params.bundle,
+        audit_state: blockedState,
+    };
+    await writeHandoffOnly({
+        root: params.root,
+        artifactsDir: params.artifactsDir,
+        bundle: blockedBundle,
+        audit_state: blockedState,
+        progress_summary: buildManualReviewBlocker(LOCAL_SUBPROCESS_PROVIDER_NAME),
+        providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
+        activeReviewRun,
+    });
+    return { state: blockedState, bundle: blockedBundle, activeReviewRun };
+}
+function nextStepCommand(root, artifactsDir, extraArgs = []) {
+    return renderCommand([
+        "audit-code",
+        "next-step",
+        "--root",
+        root,
+        "--artifacts-dir",
+        artifactsDir,
+        ...extraArgs,
+    ]);
+}
+function mergeAndIngestCommand(artifactsDir, runId) {
+    return renderCommand([
+        "audit-code",
+        "merge-and-ingest",
+        "--run-id",
+        runId,
+        "--artifacts-dir",
+        artifactsDir,
+    ]);
+}
+function renderCapabilityCheckPrompt(params) {
+    const yesCommand = nextStepCommand(params.root, params.artifactsDir, [
+        "--host-can-dispatch-subagents",
+        "true",
+    ]);
+    const noCommand = nextStepCommand(params.root, params.artifactsDir, [
+        "--host-can-dispatch-subagents",
+        "false",
+    ]);
+    return [
+        "# audit-code capability check",
+        "",
+        "Decide one thing from the active toolset: does this host expose a callable subagent/delegation tool for source-code review, such as Agent, Task, or an equivalent built-in subagent call?",
+        "",
+        "Do not run shell commands to answer this. Do not inspect packet prompts, schemas, or backend command catalogs.",
+        "",
+        "If callable subagents are available, run:",
+        "",
+        `  ${yesCommand}`,
+        "",
+        "If callable subagents are not available, run:",
+        "",
+        `  ${noCommand}`,
+        "",
+        "If the host can also restrict tools per subagent or select models per subagent, add the matching `--host-can-restrict-subagent-tools true` or `--host-can-select-subagent-model true` flags to the same command. Omit those flags when unsure.",
+        "",
+        "After the command writes the next step, read and follow only its `prompt_path`.",
+        "",
+    ].join("\n");
+}
+function renderDispatchReviewPrompt(params) {
+    const mergeCommand = mergeAndIngestCommand(params.artifactsDir, params.activeReviewRun.run_id);
+    const continueCommand = nextStepCommand(params.root, params.artifactsDir);
+    const modelLine = params.hostCanSelectSubagentModel
+        ? "When launching each subagent, map `entry.model_hint.tier` (`small`, `standard`, `deep`) to an available host model without asking the user for model names."
+        : "Ignore `entry.model_hint`; this host did not report per-subagent model selection.";
+    const toolsLine = params.hostCanRestrictSubagentTools
+        ? "Restrict review subagents to read/search plus the packet submit command named in their prompt. Do not give them source edit/write tools."
+        : "Do not ask the user about per-subagent tool restrictions; this host did not report a callable restriction facility.";
+    const fileLines = params.dispatchQuotaPath
+        ? [
+            "Dispatch is prepared. Read both of these files:",
+            "",
+            `  Dispatch plan:  ${params.dispatchPlanPath}`,
+            `  Dispatch quota: ${params.dispatchQuotaPath}`,
+            "",
+            "The quota file contains a `wave_size` field. Dispatch at most `wave_size` subagents at a time. If `cooldown_until` is non-null, wait until that timestamp before starting the first wave.",
+            "",
+            "For each wave: launch up to `wave_size` subagents in parallel (one per plan entry), wait for all of them to finish, then start the next wave. Repeat until all entries are dispatched.",
+        ]
+        : [
+            "Dispatch is prepared. Read only this dispatch plan JSON:",
+            "",
+            `  ${params.dispatchPlanPath}`,
+            "",
+            "Launch one host subagent for each entry in the plan.",
+        ];
+    return [
+        "# audit-code dispatch review",
+        "",
+        ...fileLines,
+        "",
+        "Pass each packet prompt path literally to its subagent; do not load packet prompt files into this orchestrator context.",
+        "",
+        "Subagent prompt shape:",
+        "",
+        '  Read and follow the audit instructions in: <entry.prompt_path>',
+        "",
+        modelLine,
+        toolsLine,
+        "",
+        "Each subagent must submit its packet through the submit command printed in its packet prompt and stop after successful submission.",
+        "",
+        "After all waves complete, run exactly:",
+        "",
+        `  ${mergeCommand}`,
+        "",
+        "If merge-and-ingest fails, stop and report the exact command and error output. Do not manually merge results or edit audit state.",
+        "",
+        "If merge-and-ingest succeeds, run:",
+        "",
+        `  ${continueCommand}`,
+        "",
+        "Read and follow only the new step prompt path returned by that command.",
+        "",
+    ].join("\n");
+}
+function renderSingleTaskFallbackStepPrompt(params) {
+    return [
+        "# audit-code single-task fallback step",
+        "",
+        "Use this step only because the host reported no callable subagent facility.",
+        "",
+        "Read and follow exactly this generated single-task prompt:",
+        "",
+        `  ${params.singleTaskPromptPath}`,
+        "",
+        "Complete exactly one AuditResult for the task named there, write the JSON array to the prompt's audit_results_path, run the exact worker_command from that prompt, then stop.",
+        "",
+        "Do not run dispatch commands, do not prepare packets, do not run next-step again in this turn, and do not read a report after the worker command.",
+        "",
+        "The only backend command allowed after writing the result is:",
+        "",
+        `  ${renderCommand(params.activeReviewRun.worker_command)}`,
+        "",
+    ].join("\n");
+}
+function renderPresentReportPrompt(finalReportPath) {
+    return [
+        "# audit-code present report",
+        "",
+        "The deterministic audit is complete.",
+        "",
+        "Read this report and present the completed audit with work blocks first:",
+        "",
+        `  ${finalReportPath}`,
+        "",
+        "Do not run the orchestrator again for this completed audit.",
+        "",
+    ].join("\n");
+}
+function renderBlockedStepPrompt(reason) {
+    return [
+        "# audit-code blocked",
+        "",
+        "The audit cannot continue automatically from this step.",
+        "",
+        "Report this blocker verbatim and stop:",
+        "",
+        reason,
+        "",
+    ].join("\n");
+}
+async function writeCurrentStep(params) {
+    const stepsDir = join(params.artifactsDir, "steps");
+    await mkdir(stepsDir, { recursive: true });
+    const promptPath = join(stepsDir, "current-prompt.md");
+    const stepPath = join(stepsDir, "current-step.json");
+    await writeFile(promptPath, params.prompt, "utf8");
+    const step = {
+        contract_version: STEP_CONTRACT_VERSION,
+        step_kind: params.stepKind,
+        prompt_path: promptPath,
+        status: params.status,
+        run_id: params.runId,
+        allowed_commands: params.allowedCommands,
+        stop_condition: params.stopCondition,
+        repo_root: params.repoRoot,
+        artifacts_dir: params.artifactsDir,
+        artifact_paths: {
+            current_step: stepPath,
+            current_prompt: promptPath,
+            ...params.artifactPaths,
+        },
+    };
+    await writeJsonFile(stepPath, step);
+    return step;
+}
 function formatAuditResultValidationError(issues) {
     return (`audit-results validation failed with ${issues.length} error(s):\n` +
         formatAuditResultIssues(issues));
@@ -659,6 +1004,255 @@ async function cmdAdvanceAudit(argv) {
         await promoteFinalAuditReport({ artifactsDir, repoRoot: root });
     }
 }
+async function runDeterministicForNextStep(params) {
+    let lastSummary = "";
+    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.md")
+                    : join(params.artifactsDir, "audit-report.md"),
+            };
+        }
+        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,
+            };
+        }
+        const result = await runAuditStep({
+            root: params.root,
+            artifactsDir: params.artifactsDir,
+        });
+        lastSummary = result.progress_summary;
+        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.`,
+    };
+}
+async function cmdNextStep(argv) {
+    const root = getRootDir(argv);
+    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;
+    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 result = await runDeterministicForNextStep({
+        root,
+        artifactsDir,
+        selfCliPath: resolve(argv[1] ?? process.argv[1] ?? ""),
+        timeoutMs: getTimeoutMs(argv, sessionConfig),
+        maxRuns: getMaxRuns(argv),
+    });
+    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 (hostCanDispatchSubagents === undefined) {
+        const yesCommand = nextStepCommand(root, artifactsDir, [
+            "--host-can-dispatch-subagents",
+            "true",
+        ]);
+        const noCommand = nextStepCommand(root, artifactsDir, [
+            "--host-can-dispatch-subagents",
+            "false",
+        ]);
+        const step = await writeCurrentStep({
+            artifactsDir,
+            stepKind: "capability_check",
+            status: "ready",
+            runId: result.activeReviewRun.run_id,
+            allowedCommands: [yesCommand, noCommand],
+            stopCondition: "Run exactly one next-step command with an explicit host dispatch capability.",
+            repoRoot: root,
+            artifactPaths: {
+                active_review_task: result.activeReviewRun.task_path,
+                active_review_prompt: result.activeReviewRun.prompt_path,
+                pending_audit_tasks: result.activeReviewRun.pending_audit_tasks_path ?? null,
+                single_task_prompt: join(artifactsDir, "dispatch", "current-single-task-prompt.md"),
+            },
+            prompt: renderCapabilityCheckPrompt({ root, artifactsDir }),
+        });
+        console.log(JSON.stringify(step, null, 2));
+        return;
+    }
+    if (!hostCanDispatchSubagents) {
+        const singleTaskPromptPath = join(artifactsDir, "dispatch", "current-single-task-prompt.md");
+        const workerCommand = renderCommand(result.activeReviewRun.worker_command);
+        const step = await writeCurrentStep({
+            artifactsDir,
+            stepKind: "single_task_fallback",
+            status: "ready",
+            runId: result.activeReviewRun.run_id,
+            allowedCommands: [workerCommand],
+            stopCondition: "Run the exact worker_command after one result, then stop without looping.",
+            repoRoot: root,
+            artifactPaths: {
+                active_review_task: result.activeReviewRun.task_path,
+                active_review_prompt: result.activeReviewRun.prompt_path,
+                pending_audit_tasks: result.activeReviewRun.pending_audit_tasks_path ?? null,
+                audit_results: result.activeReviewRun.audit_results_path,
+                single_task_prompt: singleTaskPromptPath,
+            },
+            prompt: renderSingleTaskFallbackStepPrompt({
+                singleTaskPromptPath,
+                activeReviewRun: result.activeReviewRun,
+            }),
+        });
+        console.log(JSON.stringify(step, null, 2));
+        return;
+    }
+    const dispatch = await prepareDispatchArtifacts({
+        runId: result.activeReviewRun.run_id,
+        artifactsDir,
+        root,
+    });
+    const mergeCommand = mergeAndIngestCommand(artifactsDir, result.activeReviewRun.run_id);
+    const continueCommand = nextStepCommand(root, artifactsDir);
+    const step = await writeCurrentStep({
+        artifactsDir,
+        stepKind: "dispatch_review",
+        status: "ready",
+        runId: result.activeReviewRun.run_id,
+        allowedCommands: [mergeCommand, continueCommand],
+        stopCondition: "Dispatch every packet, merge-and-ingest once, then run next-step again.",
+        repoRoot: root,
+        artifactPaths: {
+            dispatch_plan: dispatch.dispatch_plan_path,
+            dispatch_quota: dispatch.dispatch_quota_path,
+            dispatch_warnings: dispatch.dispatch_warnings_path,
+            active_review_task: result.activeReviewRun.task_path,
+            pending_audit_tasks: result.activeReviewRun.pending_audit_tasks_path ?? null,
+        },
+        prompt: renderDispatchReviewPrompt({
+            root,
+            artifactsDir,
+            activeReviewRun: result.activeReviewRun,
+            dispatchPlanPath: dispatch.dispatch_plan_path,
+            dispatchQuotaPath: dispatch.dispatch_quota_path,
+            hostCanRestrictSubagentTools,
+            hostCanSelectSubagentModel,
+        }),
+    });
+    console.log(JSON.stringify(step, null, 2));
+}
 async function cmdRunToCompletion(argv) {
     const root = getRootDir(argv);
     const artifactsDir = getArtifactsDir(argv);
@@ -684,6 +1278,7 @@ async function cmdRunToCompletion(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")) {
@@ -821,8 +1416,27 @@ async function cmdRunToCompletion(argv) {
             return;
         }
         if (preferredExecutor === "agent" && parallelWorkers > 1) {
+            const quotaState = await readQuotaState();
+            const providerModelKey = buildProviderModelKey(provider.name, hostModel);
+            const quotaStateEntry = quotaState.entries[providerModelKey] ?? null;
+            const waveSchedule = scheduleWave({
+                providerName: resolveFreshSessionProviderName(getExplicitProvider(argv), sessionConfig),
+                sessionConfig,
+                hostModel,
+                requestedConcurrency: parallelWorkers,
+                quotaStateEntry,
+            });
+            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 allPendingTasks = buildPendingAuditTasks(bundle);
-            const taskGroups = chunkArray(allPendingTasks.slice(0, parallelWorkers * agentBatchSize), agentBatchSize);
+            const taskGroups = chunkArray(allPendingTasks.slice(0, waveSize * agentBatchSize), agentBatchSize);
             const workerSlots = [];
             for (const rawGroup of taskGroups) {
                 const group = await addFileLineCountHints(root, rawGroup);
@@ -976,6 +1590,16 @@ async function cmdRunToCompletion(argv) {
                 });
                 artifactsWritten.add("run-ledger.json");
             }
+            // Record outcome for adaptive learning (best-effort — never blocks dispatch)
+            {
+                const hasRateLimit = batchErrors.some(detectRateLimitError);
+                await recordWaveOutcome(providerModelKey, {
+                    concurrency: workerSlots.length,
+                    estimated_tokens: waveSize * agentBatchSize * 900,
+                    outcome: hasRateLimit ? "rate_limited" : batchErrors.length > 0 ? "timeout" : "success",
+                    cooldown_until: hasRateLimit ? defaultCooldownUntil(null) : null,
+                }, sessionConfig.quota?.empirical_half_life_hours ?? 24).catch(() => undefined);
+            }
             if (batchErrors.length > 0) {
                 const bundleAfter = await loadArtifactBundle(artifactsDir);
                 const blockedState = buildBlockedAuditState({
@@ -1544,17 +2168,14 @@ function renderPacketGraphContext(packet) {
     lines.push("");
     return lines;
 }
-async function cmdPrepareDispatch(argv) {
-    const runId = getFlag(argv, "--run-id");
-    if (!runId)
-        throw new Error("prepare-dispatch requires --run-id <run_id>");
-    const artifactsDir = getArtifactsDir(argv);
+async function prepareDispatchArtifacts(params) {
+    const runId = params.runId;
+    const artifactsDir = params.artifactsDir;
     const runDir = join(artifactsDir, "runs", runId);
     const tasksPath = join(runDir, "pending-audit-tasks.json");
     const taskResultsDir = join(runDir, "task-results");
     const dispatchPlanPath = join(runDir, "dispatch-plan.json");
-    const explicitRoot = getFlag(argv, "--root") ? getRootDir(argv) : undefined;
-    let reviewRoot = explicitRoot;
+    let reviewRoot = params.root;
     try {
         const workerTask = await readJsonFile(join(runDir, "task.json"));
         reviewRoot ??= workerTask.repo_root;
@@ -1566,6 +2187,7 @@ async function cmdPrepareDispatch(argv) {
     }
     const tasks = await readJsonFile(tasksPath);
     const bundle = await loadArtifactBundle(artifactsDir);
+    const sessionConfig = params.sessionConfig ?? (await loadSessionConfig(artifactsDir).catch(() => ({})));
     const lensDefsPath = join(packageRoot, "dispatch", "lens-definitions.json");
     const lensDefs = await readJsonFile(lensDefsPath);
     await mkdir(taskResultsDir, { recursive: true });
@@ -1721,6 +2343,7 @@ async function cmdPrepareDispatch(argv) {
             largeFileMode
                 ? "Use targeted Read/Grep calls. Paths are repo-relative from the current working directory."
                 : "Use your Read tool. Paths are repo-relative from the current working directory.",
+            "Prefer host Read/Grep tools. On native Windows, do not use Unix pipelines like `grep ... | head`; if shell search is unavoidable, use `Select-String` as a fallback.",
             fileList,
             "",
             ...renderPacketGraphContext(packet),
@@ -1790,15 +2413,62 @@ async function cmdPrepareDispatch(argv) {
         run_id: runId,
         entries: resultMapEntries,
     });
+    // Compute and write dispatch-quota.json
+    const hostModel = params.hostModel ?? null;
+    const avgPacketTokens = plan.length > 0
+        ? Math.floor(plan.reduce((s, p) => s + p.complexity.estimated_tokens, 0) / plan.length)
+        : 0;
+    const quotaProviderName = resolveFreshSessionProviderName(undefined, sessionConfig);
+    const quotaProviderKey = buildProviderModelKey(quotaProviderName, hostModel);
+    const quotaState = await readQuotaState().catch(() => ({ version: 1, entries: {} }));
+    const quotaStateEntry = quotaState.entries[quotaProviderKey] ?? null;
+    const waveSchedule = scheduleWave({
+        providerName: quotaProviderName,
+        sessionConfig,
+        hostModel,
+        requestedConcurrency: sessionConfig.parallel_workers ?? 1,
+        estimatedPacketTokens: avgPacketTokens,
+        quotaStateEntry,
+    });
+    const dispatchQuota = {
+        contract_version: "audit-code-dispatch-quota/v1alpha1",
+        run_id: runId,
+        model: hostModel,
+        resolved_limits: waveSchedule.resolved_limits,
+        confidence: waveSchedule.confidence,
+        source: waveSchedule.source,
+        wave_size: waveSchedule.wave_size,
+        estimated_wave_tokens: waveSchedule.estimated_wave_tokens,
+        cooldown_until: waveSchedule.cooldown_until,
+    };
+    const dispatchQuotaPath = join(runDir, "dispatch-quota.json");
+    await writeJsonFile(dispatchQuotaPath, dispatchQuota);
+    // Warn about packets that exceed the context budget only when we have reliable limit
+    // information (confidence medium/high). Low-confidence limits are conservative defaults
+    // and would produce misleading warnings since the real context window is unknown.
+    if (waveSchedule.confidence !== "low") {
+        const contextBudget = waveSchedule.resolved_limits.context_tokens - waveSchedule.resolved_limits.output_tokens;
+        for (const p of plan) {
+            if (p.complexity.estimated_tokens > contextBudget) {
+                warnings.push({
+                    code: "oversized_packet",
+                    message: `Packet ${p.packet_id} estimated tokens (${p.complexity.estimated_tokens}) exceed ` +
+                        `context budget (${contextBudget}). This packet may fail at dispatch. ` +
+                        `Set quota.default_context_tokens or quota.models in session-config.json to override.`,
+                });
+            }
+        }
+    }
     const warningsPath = warnings.length > 0
         ? join(runDir, "dispatch-warnings.json")
         : null;
     if (warningsPath) {
         await writeJsonFile(warningsPath, warnings);
     }
-    console.log(JSON.stringify({
+    return {
         run_id: runId,
         dispatch_plan_path: dispatchPlanPath,
+        dispatch_quota_path: dispatchQuotaPath,
         packet_count: plan.length,
         task_count: orderedTasks.length,
         largest_packet: largestPacketId
@@ -1810,7 +2480,19 @@ async function cmdPrepareDispatch(argv) {
             : null,
         warning_count: warnings.length,
         dispatch_warnings_path: warningsPath,
-    }, null, 2));
+    };
+}
+async function cmdPrepareDispatch(argv) {
+    const runId = getFlag(argv, "--run-id");
+    if (!runId)
+        throw new Error("prepare-dispatch requires --run-id <run_id>");
+    const result = await prepareDispatchArtifacts({
+        runId,
+        artifactsDir: getArtifactsDir(argv),
+        root: getFlag(argv, "--root") ? getRootDir(argv) : undefined,
+        hostModel: getHostModel(argv),
+    });
+    console.log(JSON.stringify(result, null, 2));
 }
 async function cmdSubmitPacket(argv) {
     const runId = resolveRunScopedArg(argv, "--run-id", "--run-id-b64");
@@ -2360,6 +3042,45 @@ async function cmdCleanup(argv) {
 async function cmdMcp(argv) {
     await runAuditCodeMcpServer(argv.slice(3));
 }
+async function cmdQuota(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const sessionConfig = await loadSessionConfig(artifactsDir).catch(() => ({}));
+    const explicitProvider = getExplicitProvider(argv);
+    const hostModel = getHostModel(argv);
+    const probeMode = getQuotaProbeMode(argv, sessionConfig);
+    const providerName = resolveFreshSessionProviderName(explicitProvider, sessionConfig);
+    const providerModelKey = buildProviderModelKey(providerName, hostModel);
+    const { limits, source, confidence } = resolveLimits({ providerName, sessionConfig, hostModel });
+    const probeResult = await probeProvider(providerName, probeMode);
+    const quotaState = await readQuotaState().catch(() => ({ version: 1, entries: {} }));
+    const quotaStateEntry = quotaState.entries[providerModelKey] ?? null;
+    const halfLifeHours = sessionConfig.quota?.empirical_half_life_hours ?? 24;
+    const waveSchedule = scheduleWave({
+        providerName,
+        sessionConfig,
+        hostModel,
+        requestedConcurrency: sessionConfig.parallel_workers ?? 1,
+        quotaStateEntry,
+    });
+    console.log(JSON.stringify({
+        provider: providerName,
+        model: hostModel,
+        provider_model_key: providerModelKey,
+        resolved_limits: limits,
+        confidence,
+        source,
+        probe: probeResult,
+        learned_caps: quotaStateEntry
+            ? {
+                max_safe_concurrency: computeMaxSafeConcurrency(quotaStateEntry, halfLifeHours),
+                cooldown_until: quotaStateEntry.cooldown_until,
+                last_429_at: quotaStateEntry.last_429_at,
+            }
+            : null,
+        wave_schedule: waveSchedule,
+        quota_state_path: getQuotaStatePath(),
+    }, null, 2));
+}
 async function main(argv) {
     const command = argv[2] ?? "sample-run";
     switch (command) {
@@ -2369,6 +3090,9 @@ async function main(argv) {
         case "advance-audit":
             await cmdAdvanceAudit(argv);
             return;
+        case "next-step":
+            await cmdNextStep(argv);
+            return;
         case "run-to-completion":
             await cmdRunToCompletion(argv);
             return;
@@ -2423,9 +3147,12 @@ async function main(argv) {
         case "validate-result":
             await cmdValidateResult(argv);
             return;
+        case "quota":
+            await cmdQuota(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, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, cleanup, mcp, prepare-dispatch, merge-and-ingest, submit-packet, validate-result");
+            console.error("Available commands: sample-run, advance-audit, next-step, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, cleanup, mcp, prepare-dispatch, merge-and-ingest, submit-packet, validate-result, quota");
             process.exitCode = 1;
     }
 }