auditor-lambda 0.3.32 → 0.3.34

package/README.md

@@ -138,7 +138,8 @@ audit-code next-step
 
 This writes `.audit-artifacts/steps/current-step.json` and
 `.audit-artifacts/steps/current-prompt.md`; hosts should follow only the
-returned step prompt.
+returned step prompt. MCP tools are compatibility adapters over this same
+`next-step` contract rather than a separate orchestration path.
 
 For an operator-side artifact consistency check:
 

package/audit-code-wrapper-lib.mjs

@@ -580,16 +580,17 @@ function replaceBackslashes(value) {
 function renderVSCodeAgentFile() {
   return [
     '---',
-    'description: Plan and orchestrate /audit-code with the installed auditor MCP server before making code changes.',
+    'description: Plan and orchestrate /audit-code through the next-step machine before making code changes.',
     '---',
     '',
     '# Auditor Agent',
     '',
-    'Use the installed auditor MCP server as the primary integration surface for the audit workflow.',
+    'Use `audit-code next-step` as the primary integration surface for the audit workflow. The installed auditor MCP server is a compatibility adapter over the same step contract.',
     '',
     'When the user asks to run or continue `/audit-code`:',
     '',
-    '- call the `start_audit`, `get_status`, and `continue_audit` MCP tools instead of reconstructing backend state manually',
+    '- run `audit-code next-step` directly when shell access is available',
+    '- if MCP is the only available integration, call `start_audit`, `get_status`, and `continue_audit`; those tools return the same one-step contract',
     '- read `audit-code://handoff/current` and `audit-code://artifacts/current` when the audit blocks or you need current context',
     '- prefer imported audit results and runtime updates over ad hoc manual state edits',
     '- treat the deterministic audit report as the final source of truth once the audit completes',
@@ -615,7 +616,7 @@ function renderCodexMcpSetupGuide(root) {
     `args = ["${replaceBackslashes(toRepoRelativePath(root, join(root, '.audit-code', 'install', MCP_LAUNCHER_FILENAME)))}"]`,
     '```',
     '',
-    'Once the server is registered, ask Codex to use the `auditor` MCP tools to start or continue the audit.',
+    'Prefer `audit-code next-step` directly. Use the registered `auditor` MCP tools only when shell access is unavailable; they return the same one-step contract.',
     '',
   ].join('\n');
 }
@@ -626,9 +627,9 @@ function renderCodexAutomationRecipe() {
     '',
     'Suggested recurring task:',
     '',
-    '- Prompt: Re-run the autonomous audit workflow for this repository. Use the installed auditor MCP tools, summarize only new or regressed findings, and stop once the deterministic report is current.',
+    '- Prompt: Re-run the autonomous audit workflow for this repository with `audit-code next-step`, summarize only new or regressed findings, and stop once the deterministic report is current.',
     '- Cadence: daily on active branches or before release cut-offs',
-    '- Inputs: repository root plus the installed `auditor` MCP server',
+    '- Inputs: repository root; the installed `auditor` MCP server is optional compatibility plumbing',
     '',
     'Use this recipe as a starting point for a Codex automation once the local workflow is stable in your environment.',
     '',
@@ -706,16 +707,17 @@ function renderOpenCodePermissionConfig() {
 const OPENCODE_MCP_COMMAND_TEMPLATE = [
   '# audit-code',
   '',
-  'Use the auditor MCP tools as the primary interface to the audit workflow.',
+  'Use `audit-code next-step` as the primary interface to the audit workflow.',
   '',
-  '1. Call `auditor_start_audit` to initialize and receive the first step.',
-  '2. Read `prompt_content` in the response and follow it.',
-  '3. When a step completes (not blocked), call `auditor_continue_audit` to advance.',
-  '4. Stop when the step instructions say to stop.',
+  '1. Run `audit-code next-step` directly when shell access is available.',
+  '2. If MCP is your only available interface, call `auditor_start_audit` or `auditor_continue_audit`; both return the same one-step contract.',
+  '3. Read `prompt_content` in the response and follow it.',
+  '4. When a step completes (not blocked), run `audit-code next-step` again or call `auditor_continue_audit` as the compatibility adapter.',
+  '5. Stop when the step instructions say to stop.',
   '',
-  'Do not run shell commands. Use only `auditor_*` MCP tools and the `task` tool for subagent dispatch.',
+  'Use the `task` tool or equivalent for subagent dispatch when the step tells you to fan out review work.',
   '',
-  'If `auditor_start_audit` is not listed in your available tools, stop immediately and tell the user the auditor MCP server is not connected. Do not read local files as a fallback.',
+  'If neither shell access nor `auditor_start_audit` is available, stop and report that no next-step interface is connected.',
 ].join('\n');
 
 function renderOpenCodeProjectConfig(_root) {
@@ -939,7 +941,7 @@ function renderClaudeDesktopProjectTemplate() {
     'Suggested project instructions:',
     '',
     '- Treat `/audit-code` as the canonical autonomous audit workflow for this repository.',
-    '- Prefer the installed auditor MCP tools over recreating state manually.',
+    '- Prefer `audit-code next-step`; use the installed auditor MCP tools only as a compatibility adapter over the same step contract.',
     '- Read the operator handoff and artifact resources before asking for more context.',
     '- Present the final deterministic audit report as work blocks first.',
     '',
@@ -951,7 +953,7 @@ function renderClaudeDesktopProjectTemplate() {
     '',
     'Starter prompt:',
     '',
-    '> Start `/audit-code` for this repository using the installed auditor MCP tools. Continue until the audit is complete or blocked for operator input, and summarize the current handoff status before you stop.',
+    '> Start `/audit-code` for this repository using `audit-code next-step`. Continue until the audit is complete or blocked for operator input, and summarize the current handoff status before you stop.',
     '',
   ].join('\n');
 }
@@ -981,7 +983,7 @@ function renderAntigravityPlanningGuide(root) {
     '',
     '1. Open Antigravity in Planning mode.',
     '2. Load the repo-local prompt asset or the AGENTS instructions before starting the audit conversation.',
-    '3. Ask Antigravity to use the installed auditor MCP server for structured state inspection and continuation.',
+    '3. Ask Antigravity to use `audit-code next-step` directly. The installed auditor MCP server is available only as compatibility plumbing when direct shell access is unavailable.',
     '4. Review Antigravity artifacts before accepting major code changes or imported evidence.',
     '',
     'Recommended repo-local paths:',
@@ -1266,9 +1268,9 @@ async function buildClaudeDesktopBundle(root, results) {
     name: 'auditor-lambda',
     display_name: 'Auditor Lambda',
     version: packageVersion,
-    description: 'Local MCP bundle for the /audit-code autonomous audit workflow.',
+    description: 'Compatibility MCP bundle for the /audit-code autonomous audit workflow.',
     long_description:
-      'Runs the auditor-lambda MCP server locally so Claude Desktop can start, inspect, and continue repository audits with structured tools, resources, and prompts.',
+      'Runs a local compatibility MCP adapter whose start and continue tools return the same audit-code next-step contract as the direct CLI loop.',
     author: {
       name: 'auditor-lambda',
       url: 'https://github.com/OhOkThisIsFine/auditor-lambda',
@@ -1390,7 +1392,7 @@ const INSTALL_HOST_DEFINITIONS = {
     support_level: 'supported',
     setup_kind: 'local-mcp-bundle',
     summary:
-      'Install the generated local MCP bundle in Claude Desktop, then use the project template and prompt asset as supporting context.',
+      'Install the generated local MCP compatibility bundle in Claude Desktop, then use the project template and prompt asset as supporting context.',
     primary_path_key: 'claudeDesktopDxtPath',
     supporting_path_keys: [
       'claudeDesktopMcpbPath',
@@ -1400,7 +1402,7 @@ const INSTALL_HOST_DEFINITIONS = {
     ],
     steps: [
       'Open Claude Desktop Settings and install the generated `.dxt` bundle.',
-      'Configure the repository root when prompted so the bundle can launch the local auditor MCP server.',
+      'Configure the repository root when prompted so the bundle can launch the local auditor MCP adapter.',
       'Use the project template and prompt asset to kick off `/audit-code` in conversation.',
     ],
     profile: {
@@ -1492,7 +1494,7 @@ const INSTALL_HOST_DEFINITIONS = {
     support_level: 'supported',
     setup_kind: 'global-command+project-mcp',
     summary:
-      'Use the global OpenCode `/audit-code` command installed by npm plus generated project MCP and permission wiring.',
+      'Use the global OpenCode `/audit-code` command installed by npm plus generated project permissions; MCP is compatibility-only.',
     primary_path_key: 'opencodeConfigPath',
     supporting_path_keys: [
       'agentsInstructionsPath',
@@ -1501,7 +1503,7 @@ const INSTALL_HOST_DEFINITIONS = {
     steps: [
       'Open this repository in OpenCode.',
       'Use the global `/audit-code` command installed by `npm install -g auditor-lambda`.',
-      'Let OpenCode load the generated `opencode.json` for the auditor MCP server and project permissions only.',
+      'Let OpenCode load the generated `opencode.json` for project permissions; the global command drives `audit-code next-step` directly.',
     ],
     profile: {
       writeOpenCode: true,
@@ -1519,7 +1521,7 @@ const INSTALL_HOST_DEFINITIONS = {
         assertOpenCodeAuditPermissionConfig(config?.permission, 'permission');
         assertOpenCodeAuditPermissionConfig(config?.agent?.auditor?.permission, 'agent.auditor.permission');
         return {
-          summary: 'OpenCode project config has audit permissions; MCP server and /audit-code command are supplied by the global npm-installed config.',
+          summary: 'OpenCode project config has audit permissions; /audit-code is supplied by the global npm-installed config.',
           path: assetPaths.opencodeConfigPath,
         };
       });
@@ -1531,7 +1533,7 @@ const INSTALL_HOST_DEFINITIONS = {
     support_level: 'supported',
     setup_kind: 'prompt+agent+mcp',
     summary:
-      'Use the generated prompt file, custom agent, and workspace MCP configuration for the cleanest VS Code integration.',
+      'Use the generated prompt file and custom agent for next-step-first VS Code integration; workspace MCP is compatibility-only.',
     primary_path_key: 'vscodePromptPath',
     supporting_path_keys: [
       'vscodeAgentPath',
@@ -1540,8 +1542,8 @@ const INSTALL_HOST_DEFINITIONS = {
     ],
     steps: [
       'Open this repository in VS Code with Copilot.',
-      'Allow VS Code to discover the workspace MCP server from `.vscode/mcp.json`.',
-      'Invoke `/audit-code` in chat and use the custom auditor agent when you want the dedicated orchestration persona.',
+      'Invoke `/audit-code` from the generated prompt or chat so the workflow calls `audit-code next-step` directly.',
+      'Use the workspace MCP adapter only when direct shell access is unavailable.',
     ],
     profile: {
       writeVSCode: true,
@@ -1587,7 +1589,7 @@ const INSTALL_HOST_DEFINITIONS = {
     support_level: 'supported',
     setup_kind: 'agent-skill+gemini-command+planning-guide+mcp-ready',
     summary:
-      'Uses the project-scoped .agent/skills/audit-code/SKILL.md skill, the .gemini/commands/audit-code.toml slash command, the planning guide, and AGENTS instructions. The shared MCP launcher is available for structured tool calls.',
+      'Uses the project-scoped .agent/skills/audit-code/SKILL.md skill, the .gemini/commands/audit-code.toml slash command, the planning guide, and AGENTS instructions. The shared MCP launcher is compatibility-only.',
     primary_path_key: 'antigravitySkillPath',
     supporting_path_keys: [
       'geminiCommandPath',
@@ -1600,7 +1602,7 @@ const INSTALL_HOST_DEFINITIONS = {
       'Open this repository in Antigravity.',
       'The audit-code skill is automatically discovered from .agent/skills/audit-code/SKILL.md.',
       'The /audit-code slash command is also available from .gemini/commands/audit-code.toml.',
-      'Use the shared auditor MCP server when Antigravity needs structured audit state instead of free-form shell guesses.',
+      'Use `audit-code next-step` directly; use the shared auditor MCP launcher only when direct shell access is unavailable.',
     ],
     profile: {
       writeAntigravity: true,

package/dist/cli.d.ts

@@ -2,6 +2,11 @@ import type { SessionConfig } from "./types/sessionConfig.js";
 type UiMode = "visible" | "headless";
 declare function getFlag(argv: string[], name: string, fallback?: string): string | undefined;
 declare function hasFlag(argv: string[], name: string): boolean;
+export declare function resolveHostDispatchCapability(options: {
+    explicit?: boolean;
+    sessionConfig: SessionConfig;
+    env?: NodeJS.ProcessEnv;
+}): boolean;
 declare function getArtifactsDir(argv: string[]): string;
 declare function getRootDir(argv: string[]): string;
 declare function warnIfNotGitRepo(root: string): void;

package/dist/cli.js

@@ -28,11 +28,11 @@ import { buildAuditCodeHandoff, writeAuditCodeHandoffArtifacts, } from "./superv
 import { getSessionConfigPath, loadSessionConfig, readSessionConfigFile, } from "./supervisor/sessionConfig.js";
 import { clearDispatchFiles, buildRunId, ensureSupervisorDirs, getRunPaths, writeDispatchBatchFiles, writeWorkerTaskFiles, } from "./io/runArtifacts.js";
 import { renderWorkerPrompt } from "./prompts/renderWorkerPrompt.js";
-import { buildReviewPackets, orderTasksForPacketReview, } from "./orchestrator/reviewPackets.js";
+import { buildReviewPackets, orderTasksForPacketReview, estimateTaskGroupTokens, } from "./orchestrator/reviewPackets.js";
 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, resolveHostActiveSubagentLimit, probeProvider, computeMaxSafeConcurrency, getQuotaStatePath, } from "./quota/index.js";
+import { scheduleWave, buildProviderModelKey, readQuotaState, recordWaveOutcome, resolveLimits, resolveHostActiveSubagentLimit, probeProvider, computeMaxSafeConcurrency, getQuotaStatePath, detectRateLimitError, computeCooldownUntil, runSlidingWindow, LearnedQuotaSource, CompositeQuotaSource, } 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";
@@ -87,6 +87,22 @@ function getOptionalBooleanFlag(argv, name) {
     }
     throw new Error(`${name} must be either true or false.`);
 }
+function optionalBooleanEnv(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    return undefined;
+}
+export function resolveHostDispatchCapability(options) {
+    if (options.explicit !== undefined) {
+        return options.explicit;
+    }
+    if (options.sessionConfig.host_can_dispatch_subagents !== undefined) {
+        return options.sessionConfig.host_can_dispatch_subagents;
+    }
+    return optionalBooleanEnv((options.env ?? process.env).AUDIT_CODE_HOST_CAN_DISPATCH) ?? true;
+}
 function toBase64Url(value) {
     return Buffer.from(value, "utf8").toString("base64url");
 }
@@ -212,18 +228,6 @@ function getQuotaProbeMode(argv, sessionConfig) {
         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);
 }
@@ -535,50 +539,6 @@ function mergeAndIngestCommand(artifactsDir, runId) {
         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 `task`, Agent, 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 auditor MCP tools are available** (preferred — no shell required):",
-        "",
-        "Call `auditor_report_capability` with:",
-        "- `can_dispatch_subagents: true` if the `task` tool or equivalent subagent dispatch is available",
-        "- `can_dispatch_subagents: false` if not",
-        "- Optionally `can_restrict_subagent_tools: true` and/or `can_select_subagent_model: true`",
-        "- If the host documents or exposes a hard cap on simultaneously active subagents, include `max_active_subagents`.",
-        "",
-        "Read the `prompt_content` field in the tool response and follow it.",
-        "",
-        "**Fallback — if auditor MCP tools are not available:**",
-        "",
-        "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.",
-        "",
-        "If the host has a known active-subagent ceiling, add `--host-max-active-subagents <n>` to the same command. For Codex Desktop, use 6.",
-        "",
-        "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);
@@ -588,32 +548,21 @@ function renderDispatchReviewPrompt(params) {
     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 runId = params.activeReviewRun.run_id;
     const dispatchDataLines = params.dispatchQuotaPath
         ? [
-            "**If auditor MCP tools are available** (preferred):",
+            "Read these generated files unless the current tool response already included equivalent `dispatch_plan_entries` and `dispatch_quota` fields:",
             "",
-            "The dispatch plan entries are in the `dispatch_plan_entries` field of the tool response that returned this step. The wave schedule is in the `dispatch_quota` field.",
+            `  Dispatch plan:  ${params.dispatchPlanPath}`,
+            `  Dispatch quota: ${params.dispatchQuotaPath}`,
             "",
-            "Use the `wave_size` from `dispatch_quota`. If `cooldown_until` is non-null, wait until that timestamp before starting the first wave.",
+            "Use the `wave_size` from the quota data. If `cooldown_until` is non-null, wait until that timestamp before starting the first wave.",
             "",
-            "`dispatch_quota.host_concurrency_limit` records any detected hard host cap that contributed to `wave_size`.",
+            "`host_concurrency_limit` records any detected hard host cap that contributed to `wave_size`.",
             "",
             "For each wave: use the `task` tool (or equivalent subagent dispatch) to launch up to `wave_size` subagents in parallel (one per entry), wait for all to finish, then start the next wave.",
-            "",
-            "**Fallback — if auditor MCP tools are not available:** Read both of these files:",
-            "",
-            `  Dispatch plan:  ${params.dispatchPlanPath}`,
-            `  Dispatch quota: ${params.dispatchQuotaPath}`,
-            "",
-            "Apply the same wave logic from the quota file.",
         ]
         : [
-            "**If auditor MCP tools are available** (preferred):",
-            "",
-            "The dispatch plan entries are in the `dispatch_plan_entries` field of the tool response that returned this step.",
-            "",
-            "**Fallback — if auditor MCP tools are not available:** Read this dispatch plan JSON:",
+            "Read this generated dispatch plan unless the current tool response already included equivalent `dispatch_plan_entries`:",
             "",
             `  ${params.dispatchPlanPath}`,
             "",
@@ -637,9 +586,7 @@ function renderDispatchReviewPrompt(params) {
         "",
         "**After all waves complete:**",
         "",
-        "If auditor MCP tools are available, call `auditor_merge_and_ingest` with `{ run_id: \"" + runId + "\" }`, then call `auditor_continue_audit` and follow the `prompt_content` in the response.",
-        "",
-        "Fallback — if auditor MCP tools are not available, run exactly:",
+        "Run exactly:",
         "",
         `  ${mergeCommand}`,
         "",
@@ -1185,6 +1132,10 @@ async function cmdNextStep(argv) {
         console.log(JSON.stringify(step, null, 2));
         return;
     }
+    const hostCanDispatch = resolveHostDispatchCapability({
+        explicit: hostCanDispatchSubagents,
+        sessionConfig,
+    });
     const result = await runDeterministicForNextStep({
         root,
         artifactsDir,
@@ -1226,35 +1177,7 @@ async function cmdNextStep(argv) {
         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) {
+    if (!hostCanDispatch) {
         const singleTaskPromptPath = join(artifactsDir, "dispatch", "current-single-task-prompt.md");
         const workerCommand = renderCommand(result.activeReviewRun.worker_command);
         const step = await writeCurrentStep({
@@ -1299,7 +1222,7 @@ async function cmdNextStep(argv) {
             mergeCommand,
             continueCommand,
         ],
-        stopCondition: "Dispatch every packet, call auditor_merge_and_ingest once, then call auditor_continue_audit.",
+        stopCondition: "Dispatch every packet, run merge-and-ingest once, then run next-step.",
         repoRoot: root,
         artifactPaths: {
             dispatch_plan: dispatch.dispatch_plan_path,
@@ -1487,11 +1410,15 @@ async function cmdRunToCompletion(argv) {
             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 slotTokenEstimates = candidateGroups.map((g) => estimateTaskGroupTokens(g));
             const waveSchedule = scheduleWave({
                 providerName: resolveFreshSessionProviderName(getExplicitProvider(argv), sessionConfig),
                 sessionConfig,
                 hostModel,
                 requestedConcurrency: parallelWorkers,
+                estimatedSlotTokens: slotTokenEstimates,
                 quotaStateEntry,
             });
             const waveSize = waveSchedule.wave_size;
@@ -1503,8 +1430,7 @@ async function cmdRunToCompletion(argv) {
                     await new Promise((r) => setTimeout(r, cappedWait));
                 }
             }
-            const allPendingTasks = buildPendingAuditTasks(bundle);
-            const taskGroups = chunkArray(allPendingTasks.slice(0, waveSize * agentBatchSize), agentBatchSize);
+            const taskGroups = candidateGroups.slice(0, waveSize);
             const workerSlots = [];
             for (const rawGroup of taskGroups) {
                 const group = await addFileLineCountHints(root, rawGroup);
@@ -1543,7 +1469,7 @@ async function cmdRunToCompletion(argv) {
                 pending_audit_tasks_path: slot.pendingTasksPath,
             })), workerSlots.flatMap((slot) => slot.group));
             const parallelStartedAt = new Date().toISOString();
-            const launchResults = await Promise.allSettled(workerSlots.map((slot) => provider.launch({
+            const { results: launchResults } = await runSlidingWindow(workerSlots.map((slot) => () => provider.launch({
                 repoRoot: root,
                 runId: slot.runId,
                 obligationId,
@@ -1554,7 +1480,7 @@ async function cmdRunToCompletion(argv) {
                 stderrPath: slot.paths.stderrPath,
                 uiMode,
                 timeoutMs,
-            })));
+            })), waveSize);
             const launchErrorsByRunId = new Map();
             for (let index = 0; index < launchResults.length; index++) {
                 const outcome = launchResults[index];
@@ -1666,12 +1592,14 @@ async function cmdRunToCompletion(argv) {
             }
             // Record outcome for adaptive learning (best-effort — never blocks dispatch)
             {
-                const hasRateLimit = batchErrors.some(detectRateLimitError);
+                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: waveSize * agentBatchSize * 900,
-                    outcome: hasRateLimit ? "rate_limited" : batchErrors.length > 0 ? "timeout" : "success",
-                    cooldown_until: hasRateLimit ? defaultCooldownUntil(null) : null,
+                    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);
             }
             if (batchErrors.length > 0) {
@@ -2520,12 +2448,10 @@ async function prepareDispatchArtifacts(params) {
     });
     // 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 perPacketTokens = plan.map((p) => p.complexity.estimated_tokens);
     const quotaProviderName = resolveFreshSessionProviderName(undefined, sessionConfig);
     const quotaProviderKey = buildProviderModelKey(quotaProviderName, hostModel);
-    const quotaState = await readQuotaState().catch(() => ({ version: 1, entries: {} }));
+    const quotaState = await readQuotaState().catch(() => ({ version: 2, entries: {} }));
     const quotaStateEntry = quotaState.entries[quotaProviderKey] ?? null;
     const hostConcurrencyLimit = resolveHostActiveSubagentLimit({
         explicitLimit: params.hostActiveSubagentLimit,
@@ -2536,12 +2462,12 @@ async function prepareDispatchArtifacts(params) {
         sessionConfig,
         hostModel,
         requestedConcurrency: sessionConfig.parallel_workers ?? plan.length,
-        estimatedPacketTokens: avgPacketTokens,
+        estimatedSlotTokens: perPacketTokens,
         quotaStateEntry,
         hostConcurrencyLimit,
     });
     const dispatchQuota = {
-        contract_version: "audit-code-dispatch-quota/v1alpha1",
+        contract_version: "audit-code-dispatch-quota/v1alpha2",
         run_id: runId,
         model: hostModel,
         resolved_limits: waveSchedule.resolved_limits,
@@ -2551,6 +2477,8 @@ async function prepareDispatchArtifacts(params) {
         wave_size: waveSchedule.wave_size,
         estimated_wave_tokens: waveSchedule.estimated_wave_tokens,
         cooldown_until: waveSchedule.cooldown_until,
+        quota_source_snapshot: waveSchedule.quota_source_snapshot ?? null,
+        backoff_state: null,
     };
     const dispatchQuotaPath = join(runDir, "dispatch-quota.json");
     await writeJsonFile(dispatchQuotaPath, dispatchQuota);
@@ -3277,13 +3205,15 @@ async function cmdQuota(argv) {
     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 quotaState = await readQuotaState().catch(() => ({ version: 2, entries: {} }));
     const quotaStateEntry = quotaState.entries[providerModelKey] ?? null;
     const halfLifeHours = sessionConfig.quota?.empirical_half_life_hours ?? 24;
     const hostConcurrencyLimit = resolveHostActiveSubagentLimit({
         explicitLimit: getHostMaxActiveSubagents(argv),
         sessionConfig,
     });
+    const quotaSource = new CompositeQuotaSource([new LearnedQuotaSource(halfLifeHours)]);
+    const quotaSourceSnapshot = await quotaSource.queryCurrentUsage(providerModelKey).catch(() => null);
     const waveSchedule = scheduleWave({
         providerName,
         sessionConfig,
@@ -3291,6 +3221,7 @@ async function cmdQuota(argv) {
         requestedConcurrency: sessionConfig.parallel_workers ?? 1,
         quotaStateEntry,
         hostConcurrencyLimit,
+        quotaSourceSnapshot,
     });
     console.log(JSON.stringify({
         provider: providerName,
@@ -3308,6 +3239,7 @@ async function cmdQuota(argv) {
                 last_429_at: quotaStateEntry.last_429_at,
             }
             : null,
+        quota_source_snapshot: quotaSourceSnapshot,
         wave_schedule: waveSchedule,
         quota_state_path: getQuotaStatePath(),
     }, null, 2));

package/dist/mcp/server.js

@@ -250,16 +250,16 @@ function resourceListPayload() {
 export const promptRegistry = [
     {
         name: "audit-code",
-        description: "Start or continue the autonomous audit loop through the auditor MCP tools.",
+        description: "Start or continue the autonomous audit loop through the next-step machine.",
         arguments: [],
         render() {
             return [
-                "Use the auditor MCP tools as the primary interface to the backend wrapper.",
-                "1. Call `start_audit`.",
-                "2. If the audit is blocked, inspect `audit-code://handoff/current`.",
+                "Use `audit-code next-step` as the canonical interface to the backend wrapper.",
+                "1. Prefer running `audit-code next-step` directly from the repository root.",
+                "2. If this MCP adapter is your only available integration, call `start_audit` or `continue_audit`; both return the same one-step contract.",
+                "3. If the audit is blocked, inspect `audit-code://handoff/current`.",
                 "   Do not read `audit-code://artifacts/current` unless explicitly needed for a specific task; it is massive and consumes your context window.",
-                "3. When the user provides additional evidence, call `import_results` or `import_runtime_updates`.",
-                "4. Call `continue_audit` until the status is complete or explicitly blocked for operator input.",
+                "4. When the user provides additional evidence, call `import_results` or `import_runtime_updates`.",
             ].join("\n");
         },
     },
@@ -306,7 +306,7 @@ function renderPrompt(name, args) {
     }
     return entry.render(args);
 }
-async function runContinueAudit(context, extraArgs = []) {
+async function runContinueAudit(context, extraArgs = ["next-step"]) {
     const step = await parseCliJson(extraArgs, context);
     if (!step || typeof step !== "object" || Array.isArray(step))
         return step;
@@ -410,7 +410,7 @@ function toolDefinitions() {
     return [
         {
             name: "start_audit",
-            description: "Start the audit wrapper and advance until completion or blocked operator handoff.",
+            description: "Compatibility adapter over audit-code next-step; returns one step contract.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -438,7 +438,7 @@ function toolDefinitions() {
         },
         {
             name: "continue_audit",
-            description: "Continue the audit wrapper from the current artifacts directory.",
+            description: "Compatibility adapter over audit-code next-step from the current artifacts directory.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -542,7 +542,7 @@ function toolDefinitions() {
         },
         {
             name: "report_capability",
-            description: "Report host subagent dispatch capability and advance to the next step. Call this instead of running audit-code next-step from the shell during a capability_check step.",
+            description: "Compatibility adapter that calls audit-code next-step with host subagent capability flags.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -632,7 +632,7 @@ export async function dispatchRequest(request, ctx) {
                         name: "audit-code",
                         version: ctx.version,
                     },
-                    instructions: "Use the audit-code MCP tools as the primary interface to the backend wrapper. Prefer start_audit, get_status, continue_audit, and the audit-code resources over ad hoc shell commands.",
+                    instructions: "Use audit-code next-step as the primary backend loop. These MCP tools are compatibility adapters that return the same one-step contract.",
                     capabilities: {
                         tools: { listChanged: false },
                         resources: { subscribe: false, listChanged: false },

package/dist/orchestrator/reviewPackets.d.ts

@@ -1,6 +1,9 @@
 import type { AuditTask } from "../types.js";
 import type { AuditPlanMetrics, ReviewPacket } from "../types/reviewPlanning.js";
 import type { GraphBundle } from "../types/graph.js";
+export declare const ESTIMATED_TOKENS_PER_LINE = 4;
+export declare const ESTIMATED_PACKET_PROMPT_TOKENS = 900;
+export declare function estimateTaskGroupTokens(tasks: AuditTask[]): number;
 export interface BuildReviewPacketOptions {
     graphBundle?: GraphBundle;
     lineIndex?: Record<string, number>;