auditor-lambda 0.9.2 → 0.10.0

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/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.0",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",

package/schemas/audit_findings.schema.json

@@ -26,6 +26,7 @@
         },
         "audited_file_count": { "type": "integer", "minimum": 0 },
         "excluded_file_count": { "type": "integer", "minimum": 0 },
+        "budget_deferred_task_count": { "type": "integer", "minimum": 0 },
         "runtime_validation_status_breakdown": {
           "type": "object",
           "additionalProperties": { "type": "integer", "minimum": 0 }