auditor-lambda 0.9.2 → 0.10.1

package/dist/io/artifacts.d.ts

@@ -12,6 +12,7 @@ import type { DesignAssessment } from "../types/designAssessment.js";
 import type { AnalyzerCapabilityRecord } from "../types/analyzerCapability.js";
 import type { AuditScopeManifest } from "../types/auditScope.js";
 import type { ToolingManifest } from "../types/toolingManifest.js";
+import type { ActiveDispatchState } from "../cli/dispatch.js";
 type ArtifactPayloadMap = {
     repo_manifest: RepoManifest;
     file_disposition: FileDisposition;
@@ -45,8 +46,15 @@ type ArtifactPayloadMap = {
 /**
  * Audit artifacts accumulate phase-by-phase as the orchestrator advances.
  * Missing keys mean the corresponding artifact has not been produced yet.
+ *
+ * `active_dispatch` is loaded specially (like `tooling_manifest`): it lives at
+ * the artifacts root rather than as a standard pruned artifact, and carries the
+ * in-flight dispatch phase plus any budget-deferred task ids the completion
+ * obligation must exclude.
  */
-export type ArtifactBundle = Partial<ArtifactPayloadMap>;
+export type ArtifactBundle = Partial<ArtifactPayloadMap> & {
+    active_dispatch?: ActiveDispatchState;
+};
 export type ArtifactBundleKey = keyof ArtifactPayloadMap;
 type ArtifactPhase = "intake" | "analysis" | "execution" | "reporting" | "supervisor";
 interface ArtifactDefinition<K extends ArtifactBundleKey = ArtifactBundleKey> {

package/dist/io/artifacts.js

@@ -77,6 +77,13 @@ export async function loadArtifactBundle(root) {
         }
     }
     bundle.tooling_manifest = await buildToolingManifest();
+    // active-dispatch.json is written by prepare-dispatch at the artifacts root
+    // (not a standard ARTIFACT_DEFINITIONS entry). Load it so the completion
+    // obligation can exclude budget-deferred tasks. Absent on a fresh run.
+    const activeDispatch = await readOptionalJsonFile(join(root, "active-dispatch.json"));
+    if (activeDispatch !== undefined) {
+        bundle.active_dispatch = activeDispatch;
+    }
     return bundle;
 }
 export async function writeCoreArtifacts(root, bundle, options = {}) {

package/dist/io/runArtifacts.d.ts

@@ -2,6 +2,20 @@ import type { AuditTask } from "../types.js";
 import type { WorkerTask } from "../types/workerSession.js";
 import type { RunPaths, DispatchBatchRun } from "./runArtifactTypes.js";
 export type { RunPaths, DispatchBatchRun } from "./runArtifactTypes.js";
+/**
+ * Schema files copied into a dispatch run's `task-results/` directory so packet
+ * workers can optionally self-validate before submit. `audit_result.schema.json`
+ * `$ref`s the other two by relative filename, so all three must sit side-by-side
+ * for a validator to resolve them. Exported so merge-and-ingest can recognize
+ * them as legitimate (not stray) files in `task-results/`.
+ */
+export declare const PACKET_SCHEMA_FILENAMES: readonly ["audit_result.schema.json", "finding.schema.json", "audit_task.schema.json"];
+/**
+ * Copy {@link PACKET_SCHEMA_FILENAMES} into `targetDir` under their canonical
+ * filenames, making the AuditResult schema reachable from a dispatch run's
+ * `task-results/` directory.
+ */
+export declare function writePacketSchemaFiles(targetDir: string, pkgRoot: string): Promise<void>;
 export declare function buildRunId(obligationId: string | null, index: number, now?: Date): string;
 export declare function getRunPaths(artifactsDir: string, runId: string): RunPaths;
 export declare function ensureSupervisorDirs(artifactsDir: string): Promise<void>;

package/dist/io/runArtifacts.js

@@ -7,6 +7,29 @@ const packageRoot = resolve(moduleDir, "..", "..");
 const auditResultSchemaPath = join(packageRoot, "schemas", "audit_result.schema.json");
 const auditResultsSchemaPath = join(packageRoot, "schemas", "audit_results.schema.json");
 const findingSchemaPath = join(packageRoot, "schemas", "finding.schema.json");
+/**
+ * Schema files copied into a dispatch run's `task-results/` directory so packet
+ * workers can optionally self-validate before submit. `audit_result.schema.json`
+ * `$ref`s the other two by relative filename, so all three must sit side-by-side
+ * for a validator to resolve them. Exported so merge-and-ingest can recognize
+ * them as legitimate (not stray) files in `task-results/`.
+ */
+export const PACKET_SCHEMA_FILENAMES = [
+    "audit_result.schema.json",
+    "finding.schema.json",
+    "audit_task.schema.json",
+];
+/**
+ * Copy {@link PACKET_SCHEMA_FILENAMES} into `targetDir` under their canonical
+ * filenames, making the AuditResult schema reachable from a dispatch run's
+ * `task-results/` directory.
+ */
+export async function writePacketSchemaFiles(targetDir, pkgRoot) {
+    await mkdir(targetDir, { recursive: true });
+    for (const name of PACKET_SCHEMA_FILENAMES) {
+        await writeFile(join(targetDir, name), await readFile(join(pkgRoot, "schemas", name), "utf8"), "utf8");
+    }
+}
 const CURRENT_TASK_FILENAME = "current-task.json";
 const CURRENT_PROMPT_FILENAME = "current-prompt.md";
 const CURRENT_TASKS_FILENAME = "current-tasks.json";

package/dist/orchestrator/designReviewPrompt.d.ts

@@ -1,2 +1,5 @@
 import type { ArtifactBundle } from "../io/artifacts.js";
-export declare function renderDesignReviewPrompt(bundle: ArtifactBundle): string;
+export interface DesignReviewOptions {
+    max_units?: number;
+}
+export declare function renderDesignReviewPrompt(bundle: ArtifactBundle, options?: DesignReviewOptions): string;

package/dist/orchestrator/designReviewPrompt.js

@@ -45,6 +45,39 @@ function summarizeRisk(bundle) {
         ...lines,
     ].join("\n");
 }
+function buildPrioritizedReadingList(bundle, maxUnits) {
+    const items = bundle.risk_register?.items ?? [];
+    const units = bundle.unit_manifest?.units ?? [];
+    if (items.length === 0 && units.length === 0) {
+        return "No risk or unit data available; read the repository root files to orient yourself.";
+    }
+    // Build a map from unit_id → file list for fast lookup
+    const unitFiles = new Map();
+    for (const unit of units) {
+        unitFiles.set(unit.unit_id, unit.files);
+    }
+    // Sort risk items by score descending, then take the top-N
+    const sorted = [...items].sort((a, b) => b.risk_score - a.risk_score);
+    const top = sorted.slice(0, maxUnits);
+    if (top.length === 0) {
+        // Fall back to listing all units if no risk data
+        const allUnits = units.slice(0, maxUnits);
+        const lines = allUnits.map((u) => `- **${u.unit_id}** — ${u.files.join(", ")}`);
+        return [
+            `Top ${allUnits.length} unit(s) (no risk scores available):`,
+            ...lines,
+        ].join("\n");
+    }
+    const lines = top.map((item) => {
+        const files = unitFiles.get(item.unit_id);
+        const fileList = files && files.length > 0 ? files.join(", ") : "(files unknown)";
+        return `- **${item.unit_id}** (risk score: ${item.risk_score}) — ${fileList}`;
+    });
+    return [
+        `Top ${top.length} highest-risk unit(s) by risk score (out of ${items.length} total):`,
+        ...lines,
+    ].join("\n");
+}
 function summarizeSurfaces(bundle) {
     const surfaces = bundle.surface_manifest?.surfaces ?? [];
     if (surfaces.length === 0)
@@ -76,8 +109,12 @@ function formatDeterministicFindings(findings) {
         ...lines,
     ].join("\n");
 }
-export function renderDesignReviewPrompt(bundle) {
+export function renderDesignReviewPrompt(bundle, options = {}) {
     const deterministicFindings = bundle.design_assessment?.findings ?? [];
+    const unitCount = bundle.unit_manifest?.units.length ?? 0;
+    const defaultMaxUnits = Math.max(5, Math.min(20, Math.ceil(unitCount / 5)));
+    const maxUnits = options.max_units ?? defaultMaxUnits;
+    const prioritizedReadingList = buildPrioritizedReadingList(bundle, maxUnits);
     return [
         "# Project design review",
         "",
@@ -117,7 +154,11 @@ export function renderDesignReviewPrompt(bundle) {
         "",
         "## What to assess",
         "",
-        "Read the project source to understand what it does and how it works, then produce findings about:",
+        `Focus on the ${maxUnits} highest-risk units listed below; you need not read the entire repository, though you may follow any thread that demands more context. Produce findings about:`,
+        "",
+        "### Prioritised reading list",
+        "",
+        prioritizedReadingList,
         "",
         "- **Tool and library opportunities**: third-party tools, libraries, or frameworks that would improve the project. Concrete suggestions with rationale, not generic advice.",
         "- **Architecture pattern improvements**: structural changes that would improve extensibility, testability, or maintainability. Consider whether the current abstractions match the problem domain.",

package/dist/orchestrator/executorResult.d.ts

@@ -1,4 +1,23 @@
 import type { ArtifactBundle } from "../io/artifacts.js";
+/**
+ * Resolved audit scope, emitted by the intake executor so the conversation-first
+ * loader can echo what is about to be audited (and gate on confirmation when a
+ * mis-scope smell suggests the user targeted the wrong directory).
+ */
+export interface ScopeSummary {
+    /** Absolute path of the resolved repository root being audited. */
+    repo_root: string;
+    /** Count of files that will actually be audited (after disposition filtering). */
+    auditable_file_count: number;
+    /** Whether `repo_root` sits inside a git working tree. */
+    git_available: boolean;
+    /**
+     * Zero or more human-readable warnings that the resolved root may be the wrong
+     * target (e.g. a non-git subdirectory whose ancestor is a repo, or a workspace
+     * member of a parent monorepo). Empty when the scope looks correct.
+     */
+    mis_scope_smells: string[];
+}
 /**
  * Uniform result of running one audit executor: the updated artifact bundle, the
  * artifact filenames it wrote (which drive metadata/staleness bookkeeping in
@@ -9,4 +28,10 @@ export interface ExecutorRunResult {
     updated: ArtifactBundle;
     artifacts_written: string[];
     progress_summary: string;
+    /**
+     * Optional resolved-scope summary. Only the intake executor sets this; it lets
+     * the loader echo the audit target and gate on confirmation when
+     * `mis_scope_smells` is non-empty.
+     */
+    scope_summary?: ScopeSummary;
 }

package/dist/orchestrator/intakeExecutors.d.ts

@@ -1,3 +1,21 @@
 import type { ArtifactBundle } from "../io/artifacts.js";
 import type { ExecutorRunResult } from "./executorResult.js";
-export declare function runIntakeExecutor(bundle: ArtifactBundle, root: string): Promise<ExecutorRunResult>;
+/** Prefix used to carry the scope summary inside `progress_summary` for hosts
+ *  that read the step's progress text rather than the `scope_summary.json`
+ *  artifact. The loader extracts everything after this marker as JSON. */
+export declare const SCOPE_SUMMARY_PREFIX = "SCOPE_SUMMARY:";
+/**
+ * Detect signals that the resolved audit root may be the *wrong* directory.
+ * Two heuristics, returned as zero or more human-readable warnings:
+ *
+ *  a. No-git-but-ancestor-is-repo — `root` is not a git repo but some ancestor
+ *     directory is (you probably targeted a subdirectory instead of the repo
+ *     root).
+ *  b. Workspace-member — `root` has a `package.json` with a `name`, and its
+ *     parent has a `package.json` declaring `workspaces` (you probably want to
+ *     audit from the monorepo root).
+ *
+ * Returns an empty array when the scope looks correct. Never throws.
+ */
+export declare function detectMisScopeSmells(root: string): string[];
+export declare function runIntakeExecutor(bundle: ArtifactBundle, root: string, artifactsDir?: string): Promise<ExecutorRunResult>;

package/dist/orchestrator/intakeExecutors.js

@@ -1,7 +1,70 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isGitRepo, writeJsonFile } from "@audit-tools/shared";
 import { buildFileDisposition, isAuditExcludedStatus, } from "../extractors/disposition.js";
 import { buildRepoManifestFromFs } from "../extractors/fsIntake.js";
 import { loadIgnoreFile } from "../extractors/ignore.js";
-export async function runIntakeExecutor(bundle, root) {
+/** Prefix used to carry the scope summary inside `progress_summary` for hosts
+ *  that read the step's progress text rather than the `scope_summary.json`
+ *  artifact. The loader extracts everything after this marker as JSON. */
+export const SCOPE_SUMMARY_PREFIX = "SCOPE_SUMMARY:";
+/**
+ * Detect signals that the resolved audit root may be the *wrong* directory.
+ * Two heuristics, returned as zero or more human-readable warnings:
+ *
+ *  a. No-git-but-ancestor-is-repo — `root` is not a git repo but some ancestor
+ *     directory is (you probably targeted a subdirectory instead of the repo
+ *     root).
+ *  b. Workspace-member — `root` has a `package.json` with a `name`, and its
+ *     parent has a `package.json` declaring `workspaces` (you probably want to
+ *     audit from the monorepo root).
+ *
+ * Returns an empty array when the scope looks correct. Never throws.
+ */
+export function detectMisScopeSmells(root) {
+    const smells = [];
+    // (a) No .git here, but an ancestor is a git repository.
+    if (!isGitRepo(root)) {
+        let current = dirname(root);
+        let previous = root;
+        while (current && current !== previous) {
+            if (existsSync(join(current, ".git"))) {
+                smells.push(`root has no .git but ancestor '${current}' is a git repository — you may have targeted a subdirectory instead of the repo root`);
+                break;
+            }
+            previous = current;
+            current = dirname(current);
+        }
+    }
+    // (b) Workspace member of a parent monorepo.
+    const rootPkg = readPackageJson(root);
+    if (rootPkg && rootPkg.name !== undefined) {
+        const parent = dirname(root);
+        if (parent && parent !== root) {
+            const parentPkg = readPackageJson(parent);
+            if (parentPkg && parentPkg.workspaces !== undefined) {
+                smells.push(`root appears to be a workspace member of a parent monorepo at '${parent}' — consider auditing from the monorepo root instead`);
+            }
+        }
+    }
+    return smells;
+}
+function readPackageJson(dir) {
+    const path = join(dir, "package.json");
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed && typeof parsed === "object"
+            ? parsed
+            : undefined;
+    }
+    catch {
+        // Missing or malformed package.json — treat as absent for smell purposes.
+        return undefined;
+    }
+}
+export async function runIntakeExecutor(bundle, root, artifactsDir) {
     const ignore = await loadIgnoreFile(root);
     const repoManifest = await buildRepoManifestFromFs({
         root,
@@ -13,13 +76,36 @@ export async function runIntakeExecutor(bundle, root) {
     if (auditableCount === 0) {
         throw new Error(`No auditable files found in ${root}. The repository may be empty, generated-only, documentation-only, or filtered by .auditorignore.`);
     }
+    const scopeSummary = {
+        repo_root: root,
+        auditable_file_count: auditableCount,
+        git_available: isGitRepo(root),
+        mis_scope_smells: detectMisScopeSmells(root),
+    };
+    const artifactsWritten = ["repo_manifest.json", "file_disposition.json"];
+    // Persist the scope summary alongside the other intake artifacts when we know
+    // where the artifacts directory is. The typed `scope_summary` field and the
+    // progress_summary marker below carry the same data for hosts that don't read
+    // the file directly.
+    if (artifactsDir) {
+        await writeJsonFile(join(artifactsDir, "scope_summary.json"), scopeSummary);
+        artifactsWritten.push("scope_summary.json");
+    }
+    const progressSummary = `${SCOPE_SUMMARY_PREFIX}${JSON.stringify(scopeSummary)}\n` +
+        `Created intake artifacts for ${repoManifest.files.length} files ` +
+        `(${auditableCount} auditable). Scope: ${root}, git: ${scopeSummary.git_available ? "yes" : "no"}` +
+        (scopeSummary.mis_scope_smells.length > 0
+            ? `; ${scopeSummary.mis_scope_smells.length} mis-scope warning(s)`
+            : "") +
+        ".";
     return {
         updated: {
             ...bundle,
             repo_manifest: repoManifest,
             file_disposition: disposition,
         },
-        artifacts_written: ["repo_manifest.json", "file_disposition.json"],
-        progress_summary: `Created intake artifacts for ${repoManifest.files.length} files.`,
+        artifacts_written: artifactsWritten,
+        progress_summary: progressSummary,
+        scope_summary: scopeSummary,
     };
 }

package/dist/orchestrator/nextStep.d.ts

@@ -6,5 +6,6 @@ export interface NextStepDecision {
     selected_executor: string | null;
     reason: string;
 }
+export declare const PRIORITY: string[];
 export declare function findObligation(obligations: AuditObligation[]): AuditObligation | undefined;
 export declare function decideNextStep(bundle: ArtifactBundle): NextStepDecision;

package/dist/orchestrator/nextStep.js

@@ -1,6 +1,6 @@
 import { EXECUTOR_REGISTRY } from "./executors.js";
 import { deriveAuditState } from "./state.js";
-const PRIORITY = [
+export const PRIORITY = [
     "repo_manifest",
     "file_disposition",
     "auto_fixes_applied",

package/dist/orchestrator/state.js

@@ -46,7 +46,14 @@ export function deriveAuditState(bundle) {
         "requeue_tasks.json",
     ], planningReady)));
     const completedTaskIds = new Set((bundle.audit_results ?? []).map((result) => result.task_id));
-    const hasPendingAuditTasks = bundle.audit_tasks?.some((task) => task.status !== "complete" && !completedTaskIds.has(task.task_id)) ?? false;
+    // Tasks deferred by a budget cap (FINDING-013) will never have results, so
+    // they must be excluded from the completion check — otherwise the obligation
+    // loops forever under a budget. Absent active_dispatch => empty set => the
+    // logic is unchanged (all tasks must be complete).
+    const deferredTaskIds = new Set(bundle.active_dispatch?.deferred_task_ids ?? []);
+    const hasPendingAuditTasks = bundle.audit_tasks?.some((task) => task.status !== "complete" &&
+        !completedTaskIds.has(task.task_id) &&
+        !deferredTaskIds.has(task.task_id)) ?? false;
     if (hasPendingAuditTasks) {
         obligations.push(obligation("audit_tasks_completed", "missing"));
     }

package/dist/providers/constants.d.ts

@@ -1 +1 @@
-export { LOCAL_SUBPROCESS_PROVIDER_NAME } from "@audit-tools/shared";
+export { LOCAL_SUBPROCESS_PROVIDER_NAME, CODEX_PROVIDER_NAME, ANTIGRAVITY_PROVIDER_NAME, } from "@audit-tools/shared";

package/dist/providers/constants.js

@@ -1 +1 @@
-export { LOCAL_SUBPROCESS_PROVIDER_NAME } from "@audit-tools/shared";
+export { LOCAL_SUBPROCESS_PROVIDER_NAME, CODEX_PROVIDER_NAME, ANTIGRAVITY_PROVIDER_NAME, } from "@audit-tools/shared";

package/dist/quota/index.d.ts

@@ -3,6 +3,8 @@ export { resolveLimits, lookupKnownModel, classifyProvider, readQuotaState, writ
 export type { LimitResolutionResult, ResolveLimitsOptions, ProviderType, ResolvedLimits, LimitSource, LimitConfidence, HostConcurrencyLimit, HostConcurrencyLimitSource, QuotaState, QuotaStateEntry, ConcurrencyBucket, WaveSchedule, BackoffState, ObservedWaveOutcome, RateLimitDetectionResult, SlidingWindowResult, QuotaSource, QuotaUsageSnapshot, ErrorParser, } from "@audit-tools/shared";
 export { scheduleWave, buildProviderModelKey, resolveHostModel } from "@audit-tools/shared";
 export type { ScheduleWaveOptions } from "@audit-tools/shared";
+export { computeDispatchCapacity } from "@audit-tools/shared";
+export type { CapacityPool, PoolDispatchAllocation, DispatchCapacity, } from "@audit-tools/shared";
 export { detectHostActiveSubagentLimit, resolveHostActiveSubagentLimit, } from "./hostLimits.js";
 export { lookupDiscoveredLimits, updateDiscoveredLimits, mergeDiscoveredLimits, readDiscoveredLimitsCache, writeDiscoveredLimitsCache, } from "./discoveredLimits.js";
 export type { DiscoveredRateLimits, DiscoveredLimitsCache, DiscoveredLimitsCacheEntry } from "./discoveredLimits.js";

package/dist/quota/index.js

@@ -4,6 +4,10 @@ export { resolveLimits, lookupKnownModel, classifyProvider, readQuotaState, writ
 // both orchestrators). Auditor passes its discovered-limits via the structural
 // DiscoveredRateLimitsInput the shared scheduler accepts.
 export { scheduleWave, buildProviderModelKey, resolveHostModel } from "@audit-tools/shared";
+// Capacity model: the JIT, multi-pool-capable layer both orchestrators size
+// dispatch with. Single host pool today; heterogeneous provider pools slot in
+// without changing call sites.
+export { computeDispatchCapacity } from "@audit-tools/shared";
 // Auditor-specific: discovered limits, header extraction
 export { detectHostActiveSubagentLimit, resolveHostActiveSubagentLimit, } from "./hostLimits.js";
 export { lookupDiscoveredLimits, updateDiscoveredLimits, mergeDiscoveredLimits, readDiscoveredLimitsCache, writeDiscoveredLimitsCache, } from "./discoveredLimits.js";

package/dist/reporting/synthesis.d.ts

@@ -28,6 +28,14 @@ export interface AuditReportSummary {
     audited_file_count: number;
     excluded_file_count: number;
     runtime_validation_status_breakdown: Record<string, number>;
+    /**
+     * Distinct count of tasks/files NOT audited because a packet budget cap
+     * (FINDING-013) deferred them — kept separate from `excluded_file_count`
+     * (non-auditable files), since a budget skip is an honest partial-coverage
+     * signal, not an exclusion. Optional so the shared `AuditFindingsSummary`
+     * (which omits it) stays assignable to this render shape; defaults to 0.
+     */
+    budget_deferred_task_count?: number;
 }
 export interface AuditReportModel {
     summary: AuditReportSummary;

package/dist/reporting/synthesis.js

@@ -25,6 +25,8 @@ function coverageSummary(coverage) {
     return {
         audited_file_count: files.filter((file) => file.audit_status === "complete").length,
         excluded_file_count: files.filter((file) => file.audit_status === "excluded").length,
+        // Distinct from excluded: files a budget cap deferred (status set by scope).
+        budget_deferred_task_count: files.filter((file) => file.audit_status === "budget_deferred").length,
     };
 }
 function formatSeverityList(summary) {
@@ -50,6 +52,7 @@ export function buildAuditReportModel(params) {
             severity_breakdown: severityBreakdown(findings),
             audited_file_count: coverage.audited_file_count,
             excluded_file_count: coverage.excluded_file_count,
+            budget_deferred_task_count: coverage.budget_deferred_task_count,
             runtime_validation_status_breakdown: runtimeStatusBreakdown(params.runtimeValidationReport),
         },
         findings,
@@ -117,7 +120,11 @@ export function renderAuditReportMarkdown(report, options = {}) {
     if (report.executive_summary && report.executive_summary.trim().length > 0) {
         lines.push("## Executive Summary", "", report.executive_summary.trim(), "");
     }
-    lines.push("## Summary", "", `- Findings: ${report.summary.finding_count}`, `- Work blocks: ${report.summary.work_block_count}`, `- Severity breakdown: ${formatSeverityList(report.summary.severity_breakdown)}`, `- Fully audited files: ${report.summary.audited_file_count}`, `- Excluded non-auditable files: ${report.summary.excluded_file_count}`, "");
+    lines.push("## Summary", "", `- Findings: ${report.summary.finding_count}`, `- Work blocks: ${report.summary.work_block_count}`, `- Severity breakdown: ${formatSeverityList(report.summary.severity_breakdown)}`, `- Fully audited files: ${report.summary.audited_file_count}`, `- Excluded non-auditable files: ${report.summary.excluded_file_count}`, ...((report.summary.budget_deferred_task_count ?? 0) > 0
+        ? [
+            `- Not audited (budget): ${report.summary.budget_deferred_task_count} task(s) skipped by packet budget cap`,
+        ]
+        : []), "");
     if (report.top_risks && report.top_risks.length > 0) {
         lines.push("## Top Risks", "");
         for (const risk of report.top_risks) {
@@ -186,6 +193,14 @@ export function renderAuditReportMarkdown(report, options = {}) {
             lines.push("", scope.dropped_note);
         }
     }
+    else if (scope && scope.mode === "budget") {
+        lines.push(`**Partial audit (budget cap).** This run dispatched only the top-${scope.budget?.max_files ?? "K"} packet(s); ` +
+            `${scope.deferred_packet_count ?? 0} packet(s) covering ${scope.deferred_task_ids?.length ?? 0} task(s) were deferred and NOT audited. ` +
+            `Findings above reflect only the audited subset. **A full audit is advised before release.**`);
+        if (scope.dropped_note) {
+            lines.push("", scope.dropped_note);
+        }
+    }
     else {
         lines.push("This report is deterministic output from the completed audit. Non-auditable files were excluded from scope before task generation.");
     }

package/dist/supervisor/operatorHandoff.js

@@ -24,9 +24,11 @@ const NON_PENDING_OBLIGATION_STATES = new Set([
 const INTERACTIVE_PROVIDER_OPTIONS = [
     "auto",
     "claude-code",
+    "codex",
     "opencode",
     "subprocess-template",
     "vscode-task",
+    "antigravity",
 ];
 function quoteShellPath(filePath) {
     // The handoff renders a single shell argument, so the snippet only needs

package/dist/types/auditScope.d.ts

@@ -19,8 +19,12 @@ export interface AuditScopeBudget {
     max_files: number;
 }
 export interface AuditScopeManifest {
-    /** `full` audits every auditable file; `delta` scopes to a changed neighbourhood. */
-    mode: "full" | "delta";
+    /**
+     * `full` audits every auditable file; `delta` scopes to a changed
+     * neighbourhood; `budget` dispatches only the top-K review packets under a
+     * `max_packets` cap and defers the rest.
+     */
+    mode: "full" | "delta" | "budget";
     /** Git ref/SHA the delta was measured against; `null` in full mode. */
     since: string | null;
     /**
@@ -40,4 +44,14 @@ export interface AuditScopeManifest {
      * requested `--since` could not be honoured and the run fell back to full.
      */
     dropped_note?: string;
+    /**
+     * When `mode === 'budget'`: the number of review packets that were NOT
+     * dispatched due to the `max_packets` cap. Present only in budget mode.
+     */
+    deferred_packet_count?: number;
+    /**
+     * When `mode === 'budget'`: the task_ids skipped due to the budget cap.
+     * Present only in budget mode.
+     */
+    deferred_task_ids?: string[];
 }

package/dist/validation/sessionConfig.js

@@ -164,7 +164,9 @@ export function validateSessionConfig(value) {
     }
     validateTemplateProviderSection(value.subprocess_template, "subprocess_template", issues, provider === "subprocess-template");
     validateTemplateProviderSection(value.vscode_task, "vscode_task", issues, provider === "vscode-task");
+    validateTemplateProviderSection(value.antigravity, "antigravity", issues, provider === "antigravity");
     validateAgentProviderSection(value.claude_code, "claude_code", issues);
+    validateAgentProviderSection(value.codex, "codex", issues);
     validateAgentProviderSection(value.opencode, "opencode", issues);
     if (value.synthesis !== undefined) {
         if (!isRecord(value.synthesis)) {
@@ -175,6 +177,27 @@ export function validateSessionConfig(value) {
             pushIssue(issues, "synthesis.narrative", "synthesis.narrative must be a boolean when provided.");
         }
     }
+    if (value.dispatch !== undefined) {
+        if (!isRecord(value.dispatch)) {
+            pushIssue(issues, "dispatch", "dispatch must be a JSON object.");
+        }
+        else {
+            if (value.dispatch.canary !== undefined &&
+                typeof value.dispatch.canary !== "boolean") {
+                pushIssue(issues, "dispatch.canary", "dispatch.canary must be a boolean when provided.");
+            }
+            if (value.dispatch.confirm_threshold !== undefined &&
+                (!Number.isInteger(value.dispatch.confirm_threshold) ||
+                    Number(value.dispatch.confirm_threshold) < 0)) {
+                pushIssue(issues, "dispatch.confirm_threshold", "dispatch.confirm_threshold must be a non-negative integer when provided.");
+            }
+            if (value.dispatch.max_packets !== undefined &&
+                (!Number.isInteger(value.dispatch.max_packets) ||
+                    Number(value.dispatch.max_packets) < 0)) {
+                pushIssue(issues, "dispatch.max_packets", "dispatch.max_packets must be a non-negative integer when provided.");
+            }
+        }
+    }
     if (value.analyzers !== undefined) {
         if (!isRecord(value.analyzers)) {
             pushIssue(issues, "analyzers", "analyzers must be a JSON object mapping analyzer id to a setting.");
@@ -219,6 +242,18 @@ export async function validateConfiguredProviderEnvironment(sessionConfig, optio
             pushIssue(issues, "opencode.command", "Configured opencode command must be a bare executable name or direct path. Put CLI flags in extra_args.");
         }
     }
+    if (provider === "codex") {
+        const command = sessionConfig.codex?.command ?? "codex";
+        if (isBareExecutableName(command) && !(await lookupCommand(command))) {
+            pushIssue(issues, "codex.command", `Configured codex executable was not found on PATH: ${command}.`);
+        }
+        else if (isDirectExecutablePath(command) && !lookupPath(command)) {
+            pushIssue(issues, "codex.command", `Configured codex executable path does not exist: ${command}.`);
+        }
+        else if (!isSupportedConfiguredCommand(command)) {
+            pushIssue(issues, "codex.command", "Configured codex command must be a bare executable name or direct path. Put CLI flags in extra_args.");
+        }
+    }
     return issues;
 }
 export { formatValidationIssues } from "@audit-tools/shared";

package/docs/contracts.md

@@ -214,22 +214,6 @@ Review packets may expose graph-derived context for workers:
 - `quality` metrics for cohesion, internal edges, boundary edges, and
   unexplained files
 
-## MCP contract
-
-The local MCP server exposes:
-
-- `start_audit`
-- `get_status`
-- `continue_audit`
-- `explain_task`
-- `validate_artifacts`
-- `import_results`
-- `import_runtime_updates`
-
-It also exposes resources for current artifacts, operator handoff, install
-guidance, and the current report. MCP consumers should prefer the tool and
-resource contracts over reading internal files directly.
-
 ## Guided recovery
 
 Failure responses should distinguish:

package/docs/operator-guide.md

@@ -43,9 +43,9 @@ Host-specific files may include:
 
 - Codex: managed `AGENTS.md` fallback guidance
 - Claude Desktop: project template, remote MCP connector, local MCP bundle
-- OpenCode: `opencode.json` with auditor MCP server and permission wiring; the `/audit-code` command is global npm-installed state
+- OpenCode: `opencode.json` with auditor agent and permission wiring; the `/audit-code` command is global npm-installed state
 - VS Code/Copilot: prompt, custom agent, instructions, and `.vscode/mcp.json`
-- Antigravity: planning-mode and MCP-oriented guidance
+- Antigravity: planning-mode guidance
 
 Use `.audit-code/install/GETTING-STARTED.md` as the repo-local handoff after
 bootstrap.
@@ -61,18 +61,17 @@ repo-local `AGENTS.md` fallback guidance. The installed skill includes
 `agents/openai.yaml` metadata so Codex can keep the slash-list display aligned
 with the canonical `/audit-code` spelling.
 
-Claude Desktop is treated as an MCP-first host. Use the generated project
+Claude Desktop is treated as a bundle-install host. Use the generated project
 template and local bundle artifacts when installing the integration.
 
 OpenCode uses the global command seeded by `npm install -g auditor-lambda`.
 The generated project `opencode.json` should not define `command["audit-code"]`;
-it only wires the auditor MCP server and project permissions. VS Code uses
+it only wires the auditor agent and project permissions. VS Code uses
 repo-local prompt and MCP configuration files.
 
 Antigravity should be treated as a workflow-and-artifacts host until it has a
-stable project-local config surface. Use generated planning-mode guidance,
-MCP tools/resources, or the backend fallback from an Antigravity-managed
-terminal when needed.
+stable project-local config surface. Use generated planning-mode guidance
+or the backend fallback from an Antigravity-managed terminal when needed.
 
 Manual prompt-import hosts can use:
 
@@ -110,7 +109,6 @@ audit-code --external-analyzer-results /path/to/external_analyzer_results.json
 audit-code explain-task <task_id>
 audit-code validate
 audit-code cleanup
-audit-code mcp
 ```
 
 `audit-code next-step` is the backend-rendered step engine used by the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",