agent-gauntlet 0.2.2 → 0.4.0

package/src/commands/run.ts

@@ -6,8 +6,19 @@ import { EntryPointExpander } from "../core/entry-point.js";
 import { JobGenerator } from "../core/job.js";
 import { Runner } from "../core/runner.js";
 import { ConsoleReporter } from "../output/console.js";
+import { startConsoleLog } from "../output/console-log.js";
 import { Logger } from "../output/logger.js";
-import { rotateLogs } from "./shared.js";
+import {
+	findPreviousFailures,
+	type PreviousViolation,
+} from "../utils/log-parser.js";
+import { readSessionRef, writeSessionRef } from "../utils/session-ref.js";
+import {
+	acquireLock,
+	cleanLogs,
+	hasExistingLogs,
+	releaseLock,
+} from "./shared.js";
 
 export function registerRunCommand(program: Command): void {
 	program
@@ -24,14 +35,16 @@ export function registerRunCommand(program: Command): void {
 			"Use diff for current uncommitted changes (staged and unstaged)",
 		)
 		.action(async (options) => {
+			let config: Awaited<ReturnType<typeof loadConfig>> | undefined;
+			let lockAcquired = false;
+			let restoreConsole: (() => void) | undefined;
 			try {
-				const config = await loadConfig();
-
-				// Rotate logs before starting
-				await rotateLogs(config.project.log_dir);
+				config = await loadConfig();
+				restoreConsole = await startConsoleLog(config.project.log_dir);
+				await acquireLock(config.project.log_dir);
+				lockAcquired = true;
 
 				// Determine effective base branch
-				// Priority: CLI override > CI env var > config
 				const effectiveBaseBranch =
 					options.baseBranch ||
 					(process.env.GITHUB_BASE_REF &&
@@ -40,10 +53,77 @@ export function registerRunCommand(program: Command): void {
 						: null) ||
 					config.project.base_branch;
 
-				const changeDetector = new ChangeDetector(effectiveBaseBranch, {
-					commit: options.commit,
-					uncommitted: options.uncommitted,
-				});
+				// Detect rerun mode: if logs exist and not targeting a specific commit, enter verification mode
+				const logsExist = await hasExistingLogs(config.project.log_dir);
+				const isRerun = logsExist && !options.commit;
+
+				let failuresMap:
+					| Map<string, Map<string, PreviousViolation[]>>
+					| undefined;
+				let changeOptions:
+					| { commit?: string; uncommitted?: boolean; fixBase?: string }
+					| undefined;
+
+				if (isRerun) {
+					console.log(
+						chalk.dim(
+							"Existing logs detected — running in verification mode...",
+						),
+					);
+					const previousFailures = await findPreviousFailures(
+						config.project.log_dir,
+						options.gate,
+					);
+
+					failuresMap = new Map();
+					for (const gateFailure of previousFailures) {
+						const adapterMap = new Map<string, PreviousViolation[]>();
+						for (const af of gateFailure.adapterFailures) {
+							// Use review index as key if available (new @index pattern)
+							const key = af.reviewIndex
+								? String(af.reviewIndex)
+								: af.adapterName;
+							adapterMap.set(key, af.violations);
+						}
+						failuresMap.set(gateFailure.jobId, adapterMap);
+					}
+
+					if (previousFailures.length > 0) {
+						const totalViolations = previousFailures.reduce(
+							(sum, gf) =>
+								sum +
+								gf.adapterFailures.reduce(
+									(s, af) => s + af.violations.length,
+									0,
+								),
+							0,
+						);
+						console.log(
+							chalk.yellow(
+								`Found ${previousFailures.length} gate(s) with ${totalViolations} previous violation(s)`,
+							),
+						);
+					}
+
+					changeOptions = { uncommitted: true };
+					const fixBase = await readSessionRef(config.project.log_dir);
+					if (fixBase) {
+						changeOptions.fixBase = fixBase;
+					}
+				} else if (options.commit || options.uncommitted) {
+					changeOptions = {
+						commit: options.commit,
+						uncommitted: options.uncommitted,
+					};
+				}
+
+				const changeDetector = new ChangeDetector(
+					effectiveBaseBranch,
+					changeOptions || {
+						commit: options.commit,
+						uncommitted: options.uncommitted,
+					},
+				);
 				const expander = new EntryPointExpander();
 				const jobGen = new JobGenerator(config);
 
@@ -52,6 +132,8 @@ export function registerRunCommand(program: Command): void {
 
 				if (changes.length === 0) {
 					console.log(chalk.green("No changes detected."));
+					await releaseLock(config.project.log_dir);
+					restoreConsole?.();
 					process.exit(0);
 				}
 
@@ -69,6 +151,8 @@ export function registerRunCommand(program: Command): void {
 
 				if (jobs.length === 0) {
 					console.log(chalk.yellow("No applicable gates for these changes."));
+					await releaseLock(config.project.log_dir);
+					restoreConsole?.();
 					process.exit(0);
 				}
 
@@ -80,16 +164,29 @@ export function registerRunCommand(program: Command): void {
 					config,
 					logger,
 					reporter,
-					undefined,
-					undefined,
+					failuresMap,
+					changeOptions,
 					effectiveBaseBranch,
 				);
 
 				const success = await runner.run(jobs);
+
+				if (success) {
+					await cleanLogs(config.project.log_dir);
+				} else {
+					await writeSessionRef(config.project.log_dir);
+				}
+
+				await releaseLock(config.project.log_dir);
+				restoreConsole?.();
 				process.exit(success ? 0 : 1);
 			} catch (error: unknown) {
+				if (config && lockAcquired) {
+					await releaseLock(config.project.log_dir);
+				}
 				const err = error as { message?: string };
 				console.error(chalk.red("Error:"), err.message);
+				restoreConsole?.();
 				process.exit(1);
 			}
 		});

package/src/commands/shared.ts

@@ -1,26 +1,71 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { clearSessionRef } from "../utils/session-ref";
 
-export async function exists(path: string): Promise<boolean> {
+const LOCK_FILENAME = ".gauntlet-run.lock";
+
+export async function exists(filePath: string): Promise<boolean> {
 	try {
-		await fs.stat(path);
+		await fs.stat(filePath);
 		return true;
 	} catch {
 		return false;
 	}
 }
 
-export async function rotateLogs(logDir: string): Promise<void> {
+export async function acquireLock(logDir: string): Promise<void> {
+	await fs.mkdir(logDir, { recursive: true });
+	const lockPath = path.resolve(logDir, LOCK_FILENAME);
+	try {
+		await fs.writeFile(lockPath, String(process.pid), { flag: "wx" });
+	} catch (err: unknown) {
+		if (
+			typeof err === "object" &&
+			err !== null &&
+			"code" in err &&
+			(err as { code: string }).code === "EEXIST"
+		) {
+			console.error(
+				`Error: A gauntlet run is already in progress (lock file: ${lockPath}).`,
+			);
+			console.error(
+				"If no run is actually in progress, delete the lock file manually.",
+			);
+			process.exit(1);
+		}
+		throw err;
+	}
+}
+
+export async function releaseLock(logDir: string): Promise<void> {
+	const lockPath = path.resolve(logDir, LOCK_FILENAME);
+	try {
+		await fs.rm(lockPath, { force: true });
+	} catch {
+		// no-op if missing
+	}
+}
+
+export async function hasExistingLogs(logDir: string): Promise<boolean> {
+	try {
+		const entries = await fs.readdir(logDir);
+		return entries.some(
+			(f) => (f.endsWith(".log") || f.endsWith(".json")) && f !== "previous",
+		);
+	} catch {
+		return false;
+	}
+}
+
+export async function cleanLogs(logDir: string): Promise<void> {
 	const previousDir = path.join(logDir, "previous");
 
 	try {
-		// 1. Ensure logDir exists (if not, nothing to rotate, but we should create it for future use if needed,
-		//    though usually the logger creates it. If it doesn't exist, we can just return).
 		if (!(await exists(logDir))) {
 			return;
 		}
 
-		// 2. Clear gauntlet_logs/previous if it exists
+		// 1. Delete all files in previous/
 		if (await exists(previousDir)) {
 			const previousFiles = await fs.readdir(previousDir);
 			await Promise.all(
@@ -32,19 +77,20 @@ export async function rotateLogs(logDir: string): Promise<void> {
 			await fs.mkdir(previousDir, { recursive: true });
 		}
 
-		// 3. Move all existing files in gauntlet_logs/ to gauntlet_logs/previous
+		// 2. Move all .log and .json files from logDir root into previous/
 		const files = await fs.readdir(logDir);
 		await Promise.all(
 			files
-				.filter((file) => file !== "previous")
+				.filter((file) => file.endsWith(".log") || file.endsWith(".json"))
 				.map((file) =>
 					fs.rename(path.join(logDir, file), path.join(previousDir, file)),
 				),
 		);
+
+		await clearSessionRef(logDir);
 	} catch (error) {
-		// Log warning but don't crash the run as log rotation failure isn't critical
 		console.warn(
-			"Failed to rotate logs in",
+			"Failed to clean logs in",
 			logDir,
 			":",
 			error instanceof Error ? error.message : error,

package/src/commands/validate.ts

@@ -0,0 +1,20 @@
+import chalk from "chalk";
+import type { Command } from "commander";
+import { loadConfig } from "../config/loader.js";
+
+export function registerValidateCommand(program: Command): void {
+	program
+		.command("validate")
+		.description("Validate .gauntlet/ config files against schemas")
+		.action(async () => {
+			try {
+				await loadConfig();
+				console.log(chalk.green("All config files are valid."));
+				process.exitCode = 0;
+			} catch (error: unknown) {
+				const message = error instanceof Error ? error.message : String(error);
+				console.error(chalk.red("Validation failed:"), message);
+				process.exitCode = 1;
+			}
+		});
+}

package/src/config/schema.ts

@@ -51,6 +51,7 @@ export const reviewPromptFrontmatterSchema = z.object({
 
 export const entryPointSchema = z.object({
 	path: z.string().min(1),
+	exclude: z.array(z.string().min(1)).optional(),
 	checks: z.array(z.string().min(1)).optional(),
 	reviews: z.array(z.string().min(1)).optional(),
 });
@@ -59,6 +60,10 @@ export const gauntletConfigSchema = z.object({
 	base_branch: z.string().min(1).default("origin/main"),
 	log_dir: z.string().min(1).default("gauntlet_logs"),
 	allow_parallel: z.boolean().default(true),
+	max_retries: z.number().default(3),
+	rerun_new_issue_threshold: z
+		.enum(["critical", "high", "medium", "low"])
+		.default("high"),
 	cli: cliConfigSchema,
 	entry_points: z.array(entryPointSchema).min(1),
 });

package/src/config/validator.ts

@@ -108,12 +108,13 @@ export async function validateConfig(
 				if (file.endsWith(".yml") || file.endsWith(".yaml")) {
 					const filePath = path.join(checksPath, file);
 					filesChecked.push(filePath);
+					const name = path.basename(file, path.extname(file));
 					try {
 						const content = await fs.readFile(filePath, "utf-8");
 						const raw = YAML.parse(content);
 						const parsed = checkGateSchema.parse(raw);
-						existingCheckNames.add(parsed.name); // Track that this check exists
-						checks[parsed.name] = parsed;
+						existingCheckNames.add(name); // Track that this check exists
+						checks[name] = parsed;
 
 						// Semantic validation
 						if (!parsed.command || parsed.command.trim() === "") {
@@ -125,17 +126,9 @@ export async function validateConfig(
 							});
 						}
 					} catch (error: unknown) {
-						// Try to extract check name from raw YAML even if parsing failed
-						try {
-							const content = await fs.readFile(filePath, "utf-8");
-							const raw = YAML.parse(content);
-							if (raw.name && typeof raw.name === "string") {
-								existingCheckNames.add(raw.name); // Track that this check file exists
-							}
-						} catch {
-							// If we can't even parse the name, that's okay - we'll just skip tracking it
-						}
-
+						// Track that this check file exists even if parsing failed
+						// Use filename-based name since name is no longer in YAML
+						existingCheckNames.add(name);
 						if (error instanceof ZodError) {
 							error.errors.forEach((err) => {
 								issues.push({

package/src/core/change-detector.ts

@@ -6,6 +6,7 @@ const execAsync = promisify(exec);
 export interface ChangeDetectorOptions {
 	commit?: string; // If provided, get diff for this commit vs its parent
 	uncommitted?: boolean; // If true, only get uncommitted changes (staged + unstaged)
+	fixBase?: string; // If provided, get diff from this ref to current working tree
 }
 
 export class ChangeDetector {

package/src/core/entry-point.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { Glob } from "bun";
 import type { EntryPointConfig } from "../config/types.js";
 
 export interface ExpandedEntryPoint {
@@ -16,24 +17,37 @@ export class EntryPointExpander {
 		const rootEntryPoint = entryPoints.find((ep) => ep.path === ".");
 
 		// Always include root entry point if configured and there are ANY changes
-		// Or should it only run if files match root patterns?
-		// Spec says: "A root entry point always exists and applies to repository-wide gates."
-		// Usually root gates run on any change or specific files in root.
-		// For simplicity, if root is configured, we'll include it if there are any changed files.
 		if (changedFiles.length > 0) {
 			const rootConfig = rootEntryPoint ?? { path: "." };
-			results.push({ path: ".", config: rootConfig });
+			// Apply exclusion filtering for root if configured
+			const filteredRootChanges = this.filterExcludedFiles(
+				changedFiles,
+				rootConfig.exclude,
+			);
+
+			if (filteredRootChanges.length > 0) {
+				results.push({ path: ".", config: rootConfig });
+			}
 		}
 
 		for (const ep of entryPoints) {
 			if (ep.path === ".") continue; // Handled above
 
+			// Apply exclusion filtering first!
+			const filteredChanges = this.filterExcludedFiles(
+				changedFiles,
+				ep.exclude,
+			);
+
+			// If no relevant files remain, skip this entry point
+			if (filteredChanges.length === 0) continue;
+
 			if (ep.path.endsWith("*")) {
 				// Wildcard directory (e.g., "engines/*")
 				const parentDir = ep.path.slice(0, -2); // "engines"
 				const expandedPaths = await this.expandWildcard(
 					parentDir,
-					changedFiles,
+					filteredChanges,
 				);
 
 				for (const subDir of expandedPaths) {
@@ -44,7 +58,7 @@ export class EntryPointExpander {
 				}
 			} else {
 				// Fixed directory (e.g., "apps/api")
-				if (this.hasChangesInDir(ep.path, changedFiles)) {
+				if (this.hasChangesInDir(ep.path, filteredChanges)) {
 					results.push({
 						path: ep.path,
 						config: ep,
@@ -81,6 +95,33 @@ export class EntryPointExpander {
 		return results;
 	}
 
+	private filterExcludedFiles(files: string[], patterns?: string[]): string[] {
+		if (!patterns || patterns.length === 0) {
+			return files;
+		}
+
+		// Pre-compile globs
+		const globs: Glob[] = [];
+		const prefixes: string[] = [];
+
+		for (const pattern of patterns) {
+			if (pattern.match(/[*?[{]/)) {
+				globs.push(new Glob(pattern));
+			} else {
+				prefixes.push(pattern);
+			}
+		}
+
+		return files.filter((file) => {
+			// If matches ANY pattern, exclude it
+			const isExcluded =
+				prefixes.some((p) => file === p || file.startsWith(`${p}/`)) ||
+				globs.some((g) => g.match(file));
+
+			return !isExcluded;
+		});
+	}
+
 	private async expandWildcard(
 		parentDir: string,
 		changedFiles: string[],

package/src/core/runner.ts

@@ -39,6 +39,19 @@ export class Runner {
 	async run(jobs: Job[]): Promise<boolean> {
 		await this.logger.init();
 
+		// Enforce retry limit before executing gates
+		const maxRetries = this.config.project.max_retries ?? 3;
+		const currentRunNumber = this.logger.getRunNumber();
+		const maxAllowedRuns = maxRetries + 1;
+
+		if (currentRunNumber > maxAllowedRuns) {
+			console.error(
+				`Retry limit exceeded: run ${currentRunNumber} exceeds max allowed ${maxAllowedRuns} (max_retries: ${maxRetries}). Run \`agent-gauntlet clean\` to reset.`,
+			);
+			process.exitCode = 1;
+			return false;
+		}
+
 		const { runnableJobs, preflightResults } = await this.preflight(jobs);
 		this.results.push(...preflightResults);
 
@@ -54,7 +67,6 @@ export class Runner {
 		const parallelPromises = parallelJobs.map((job) => this.executeJob(job));
 
 		// Start sequential jobs
-		// We run them one by one, but concurrently with the parallel batch
 		const sequentialPromise = (async () => {
 			for (const job of sequentialJobs) {
 				if (this.shouldStop) break;
@@ -64,9 +76,21 @@ export class Runner {
 
 		await Promise.all([...parallelPromises, sequentialPromise]);
 
-		await this.reporter.printSummary(this.results);
+		const allPassed = this.results.every((r) => r.status === "pass");
 
-		return this.results.every((r) => r.status === "pass");
+		// If on the final allowed run and gates failed, report "Retry limit exceeded"
+		if (!allPassed && currentRunNumber === maxAllowedRuns) {
+			await this.reporter.printSummary(
+				this.results,
+				this.config.project.log_dir,
+				"Retry limit exceeded",
+			);
+			return false;
+		}
+
+		await this.reporter.printSummary(this.results, this.config.project.log_dir);
+
+		return allPassed;
 	}
 
 	private async executeJob(job: Job): Promise<void> {
@@ -76,43 +100,53 @@ export class Runner {
 
 		let result: GateResult;
 
-		if (job.type === "check") {
-			const logPath = this.logger.getLogPath(job.id);
-			const jobLogger = await this.logger.createJobLogger(job.id);
-			const effectiveBaseBranch =
-				this.baseBranchOverride || this.config.project.base_branch;
-			result = await this.checkExecutor.execute(
-				job.id,
-				job.gateConfig as LoadedCheckGateConfig,
-				job.workingDirectory,
-				jobLogger,
-				effectiveBaseBranch,
-			);
-			result.logPath = logPath;
-		} else {
-			// Use sanitized Job ID for lookup because that's what log-parser uses (based on filenames)
-			const safeJobId = sanitizeJobId(job.id);
-			const previousFailures = this.previousFailuresMap?.get(safeJobId);
-			const loggerFactory = this.logger.createLoggerFactory(job.id);
-			const effectiveBaseBranch =
-				this.baseBranchOverride || this.config.project.base_branch;
-			result = await this.reviewExecutor.execute(
-				job.id,
-				job.gateConfig as ReviewGateConfig & ReviewPromptFrontmatter,
-				job.entryPoint,
-				loggerFactory,
-				effectiveBaseBranch,
-				previousFailures,
-				this.changeOptions,
-				this.config.project.cli.check_usage_limit,
-			);
+		try {
+			if (job.type === "check") {
+				const logPath = await this.logger.getLogPath(job.id);
+				const jobLogger = await this.logger.createJobLogger(job.id);
+				const effectiveBaseBranch =
+					this.baseBranchOverride || this.config.project.base_branch;
+				result = await this.checkExecutor.execute(
+					job.id,
+					job.gateConfig as LoadedCheckGateConfig,
+					job.workingDirectory,
+					jobLogger,
+					effectiveBaseBranch,
+				);
+				result.logPath = logPath;
+			} else {
+				// Use sanitized Job ID for lookup because that's what log-parser uses (based on filenames)
+				const safeJobId = sanitizeJobId(job.id);
+				const previousFailures = this.previousFailuresMap?.get(safeJobId);
+				const loggerFactory = this.logger.createLoggerFactory(job.id);
+				const effectiveBaseBranch =
+					this.baseBranchOverride || this.config.project.base_branch;
+				result = await this.reviewExecutor.execute(
+					job.id,
+					job.gateConfig as ReviewGateConfig & ReviewPromptFrontmatter,
+					job.entryPoint,
+					loggerFactory,
+					effectiveBaseBranch,
+					previousFailures,
+					this.changeOptions,
+					this.config.project.cli.check_usage_limit,
+					this.config.project.rerun_new_issue_threshold,
+				);
+			}
+		} catch (err) {
+			console.error("[ERROR] Execution failed for", job.id, ":", err);
+			result = {
+				jobId: job.id,
+				status: "error",
+				duration: 0,
+				message: err instanceof Error ? err.message : String(err),
+			};
 		}
 
 		this.results.push(result);
 		this.reporter.onJobComplete(job, result);
 
 		// Handle Fail Fast (only for checks, and only when parallel is false)
-		// fail_fast can only be set on checks when parallel is false (enforced by schema)
 		if (
 			result.status !== "pass" &&
 			job.type === "check" &&
@@ -136,9 +170,9 @@ export class Runner {
 					(job.gateConfig as LoadedCheckGateConfig).command,
 				);
 				if (!commandName) {
-					preflightResults.push(
-						await this.recordPreflightFailure(job, "Unable to parse command"),
-					);
+					const msg = "Unable to parse command";
+					console.error(`[PREFLIGHT] ${job.id}: ${msg}`);
+					preflightResults.push(await this.recordPreflightFailure(job, msg));
 					if (this.shouldFailFast(job)) this.shouldStop = true;
 					continue;
 				}
@@ -148,36 +182,32 @@ export class Runner {
 					job.workingDirectory,
 				);
 				if (!available) {
-					preflightResults.push(
-						await this.recordPreflightFailure(
-							job,
-							`Missing command: ${commandName}`,
-						),
-					);
+					const msg = `Missing command: ${commandName}`;
+					console.error(`[PREFLIGHT] ${job.id}: ${msg}`);
+					preflightResults.push(await this.recordPreflightFailure(job, msg));
 					if (this.shouldFailFast(job)) this.shouldStop = true;
 					continue;
 				}
 			} else {
 				const reviewConfig = job.gateConfig as ReviewGateConfig &
 					ReviewPromptFrontmatter;
-				const required = reviewConfig.num_reviews ?? 1;
-				const availableTools: string[] = [];
 
+				// Only need at least 1 healthy adapter (round-robin handles the rest)
+				let hasHealthy = false;
 				for (const toolName of reviewConfig.cli_preference || []) {
-					if (availableTools.length >= required) break;
 					const cached = cliCache.get(toolName);
 					const isAvailable = cached ?? (await this.checkAdapter(toolName));
 					cliCache.set(toolName, isAvailable);
-					if (isAvailable) availableTools.push(toolName);
+					if (isAvailable) {
+						hasHealthy = true;
+						break;
+					}
 				}
 
-				if (availableTools.length < required) {
-					preflightResults.push(
-						await this.recordPreflightFailure(
-							job,
-							`Missing CLI tools: need ${required}, found ${availableTools.length}`,
-						),
-					);
+				if (!hasHealthy) {
+					const msg = "Preflight failed: no healthy adapters available";
+					console.error(`[PREFLIGHT] ${job.id}: ${msg}`);
+					preflightResults.push(await this.recordPreflightFailure(job, msg));
 					if (this.shouldFailFast(job)) this.shouldStop = true;
 					continue;
 				}
@@ -194,7 +224,7 @@ export class Runner {
 		message: string,
 	): Promise<GateResult> {
 		if (job.type === "check") {
-			const logPath = this.logger.getLogPath(job.id);
+			const logPath = await this.logger.getLogPath(job.id);
 			const jobLogger = await this.logger.createJobLogger(job.id);
 			await jobLogger(
 				`[${new Date().toISOString()}] Health check failed\n${message}\n`,
@@ -222,6 +252,11 @@ export class Runner {
 		const health = await adapter.checkHealth({
 			checkUsageLimit: this.config.project.cli.check_usage_limit,
 		});
+		if (health.status !== "healthy") {
+			console.log(
+				`[DEBUG] Adapter ${name} check failed: ${health.status} - ${health.message}`,
+			);
+		}
 		return health.status === "healthy";
 	}
 
@@ -267,7 +302,6 @@ export class Runner {
 	}
 
 	private shouldFailFast(job: Job): boolean {
-		// Only checks can have fail_fast, and only when parallel is false
 		return Boolean(job.type === "check" && job.gateConfig.fail_fast);
 	}
 }