@oh-my-pi/pi-coding-agent 13.19.0 → 14.0.2

package/src/autoresearch/tools/log-experiment.ts

@@ -8,14 +8,15 @@ import type { ToolDefinition } from "../../extensibility/extensions";
 import type { Theme } from "../../modes/theme/theme";
 import { replaceTabs, truncateToWidth } from "../../tools/render-utils";
 import * as git from "../../utils/git";
-import { getAutoresearchFingerprintMismatchError, pathMatchesContractPath } from "../contract";
-import { getCurrentAutoresearchBranch, parseWorkDirDirtyPaths } from "../git";
+import { applyAutoresearchContractToExperimentState } from "../apply-contract-to-state";
+import { loadAutoresearchScriptSnapshot, pathMatchesContractPath, readAutoresearchContract } from "../contract";
+import { computeRunModifiedPaths, getCurrentAutoresearchBranch, parseWorkDirDirtyPathsWithStatus } from "../git";
 import {
-	AUTORESEARCH_COMMITTABLE_FILES,
 	formatNum,
 	inferMetricUnitFromName,
 	isAutoresearchCommittableFile,
 	isAutoresearchLocalStatePath,
+	isAutoresearchShCommand,
 	isBetter,
 	mergeAsi,
 	readPendingRunSummary,
@@ -61,7 +62,14 @@ const logExperimentSchema = Type.Object({
 	),
 	force: Type.Optional(
 		Type.Boolean({
-			description: "Allow introducing new secondary metrics.",
+			description:
+				"When true: skip ASI field requirements and allow keeping a run whose primary metric regressed versus the best kept run.",
+		}),
+	),
+	skip_restore: Type.Optional(
+		Type.Boolean({
+			description:
+				"When true and status is discard/crash/checks_failed: skip reverting the working tree to HEAD. Useful when the experiment did not modify tracked files or you want to preserve the current state.",
 		}),
 	),
 	asi: Type.Optional(
@@ -71,11 +79,6 @@ const logExperimentSchema = Type.Object({
 	),
 });
 
-interface PreservedFile {
-	content: Buffer;
-	path: string;
-}
-
 interface KeepCommitResult {
 	error?: string;
 	note?: string;
@@ -102,10 +105,26 @@ export function createLogExperimentTool(
 			const runtime = options.getRuntime(ctx);
 			const state = runtime.state;
 			const workDir = resolveWorkDir(ctx.cwd);
-			const fingerprintError = getAutoresearchFingerprintMismatchError(state.segmentFingerprint, workDir);
-			if (fingerprintError) {
+
+			const contractResult = readAutoresearchContract(workDir);
+			const scriptSnapshot = loadAutoresearchScriptSnapshot(workDir);
+			const contractErrors = [...contractResult.errors, ...scriptSnapshot.errors];
+			if (contractErrors.length > 0) {
 				return {
-					content: [{ type: "text", text: `Error: ${fingerprintError}` }],
+					content: [{ type: "text", text: `Error: ${contractErrors.join(" ")}` }],
+				};
+			}
+			const benchmarkForSync = contractResult.contract.benchmark;
+			if (benchmarkForSync.command && !isAutoresearchShCommand(benchmarkForSync.command)) {
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								"Error: Benchmark.command in autoresearch.md must invoke `autoresearch.sh` directly before logging. " +
+								"Fix autoresearch.md or move the workload into autoresearch.sh.",
+						},
+					],
 				};
 			}
 
@@ -116,6 +135,10 @@ export function createLogExperimentTool(
 					content: [{ type: "text", text: "Error: no unlogged run is available. Run run_experiment first." }],
 				};
 			}
+
+			applyAutoresearchContractToExperimentState(contractResult.contract, state);
+			const logPreamble =
+				"Refreshed session fields from autoresearch.md before logging (benchmark, scope, constraints).\n\n";
 			runtime.lastRunSummary = pendingRun;
 			runtime.lastRunAsi = pendingRun.parsedAsi;
 			runtime.lastRunChecks =
@@ -170,22 +193,20 @@ export function createLogExperimentTool(
 				};
 			}
 
+			const forceLoose = params.force === true;
 			const secondaryMetrics = buildSecondaryMetrics(params.metrics, pendingRun.parsedMetrics, state.metricName);
-			const validationError = validateSecondaryMetrics(state, secondaryMetrics, params.force ?? false);
-			if (validationError) {
-				return {
-					content: [{ type: "text", text: `Error: ${validationError}` }],
-				};
-			}
 
 			const mergedAsi = mergeAsi(runtime.lastRunAsi, sanitizeAsi(params.asi));
-			const asiValidationError = validateAsiRequirements(mergedAsi, params.status);
-			if (asiValidationError) {
-				return {
-					content: [{ type: "text", text: `Error: ${asiValidationError}` }],
-				};
+			if (!forceLoose) {
+				const asiValidationError = validateAsiRequirements(mergedAsi, params.status);
+				if (asiValidationError) {
+					return {
+						content: [{ type: "text", text: `Error: ${asiValidationError}` }],
+					};
+				}
 			}
 
+			const preRunDirtyPaths = pendingRun.preRunDirtyPaths;
 			let keepScopeValidation: { committablePaths: string[] } | undefined;
 			if (params.status === "keep") {
 				const scopeValidation = await validateKeepPaths(options, workDir, state);
@@ -196,6 +217,7 @@ export function createLogExperimentTool(
 				}
 				const currentBestMetric = findBestKeptMetric(state.results, state.currentSegment, state.bestDirection);
 				if (
+					!forceLoose &&
 					currentBestMetric !== null &&
 					params.metric !== currentBestMetric &&
 					!isBetter(params.metric, currentBestMetric, state.bestDirection)
@@ -250,8 +272,8 @@ export function createLogExperimentTool(
 					};
 				}
 				gitNote = commitResult.note ?? null;
-			} else {
-				const revertResult = await revertFailedExperiment(options, workDir);
+			} else if (!params.skip_restore) {
+				const revertResult = await revertFailedExperiment(options, workDir, preRunDirtyPaths);
 				if (revertResult.error) {
 					return {
 						content: [{ type: "text", text: `Error: ${revertResult.error}` }],
@@ -309,7 +331,7 @@ export function createLogExperimentTool(
 			runtime.lastAutoResumePendingRunNumber = null;
 
 			const currentSegmentRuns = currentResults(state.results, state.currentSegment).length;
-			const text = buildLogText(state, experiment, currentSegmentRuns, wallClockSeconds, gitNote);
+			const text = logPreamble + buildLogText(state, experiment, currentSegmentRuns, wallClockSeconds, gitNote);
 			if (state.maxExperiments !== null && currentSegmentRuns >= state.maxExperiments) {
 				runtime.autoresearchMode = false;
 				options.pi.appendEntry(
@@ -432,23 +454,6 @@ export function validateAsiRequirements(asi: ASIData | undefined, status: Experi
 	return null;
 }
 
-function validateSecondaryMetrics(state: ExperimentState, metrics: NumericMetricMap, force: boolean): string | null {
-	if (state.secondaryMetrics.length === 0) return null;
-	const knownNames = new Set(state.secondaryMetrics.map(metric => metric.name));
-	const providedNames = new Set(Object.keys(metrics));
-
-	const missing = [...knownNames].filter(name => !providedNames.has(name));
-	if (missing.length > 0) {
-		return `missing secondary metrics: ${missing.join(", ")}`;
-	}
-
-	const newMetrics = [...providedNames].filter(name => !knownNames.has(name));
-	if (newMetrics.length > 0 && !force) {
-		return `new secondary metrics require force=true: ${newMetrics.join(", ")}`;
-	}
-	return null;
-}
-
 function registerSecondaryMetrics(state: ExperimentState, metrics: NumericMetricMap): void {
 	for (const name of Object.keys(metrics)) {
 		if (state.secondaryMetrics.some(metric => metric.name === name)) continue;
@@ -547,36 +552,11 @@ async function commitKeptExperiment(
 async function revertFailedExperiment(
 	options: AutoresearchToolFactoryOptions,
 	workDir: string,
+	preRunDirtyPaths: string[],
 ): Promise<KeepCommitResult> {
-	const preservedFiles = preserveAutoresearchFiles(workDir);
-	try {
-		await git.restore(workDir, { files: ["."], source: "HEAD", staged: true, worktree: true });
-	} catch (err) {
-		restoreAutoresearchFiles(preservedFiles);
-		return {
-			error: `git restore failed: ${err instanceof Error ? err.message : String(err)}`,
-		};
-	}
-	try {
-		await git.clean(workDir, { paths: ["."] });
-	} catch (err) {
-		restoreAutoresearchFiles(preservedFiles);
-		return {
-			error: `git clean failed: ${err instanceof Error ? err.message : String(err)}`,
-		};
-	}
-	try {
-		await git.clean(workDir, { ignoredOnly: true, paths: ["."] });
-	} catch (err) {
-		restoreAutoresearchFiles(preservedFiles);
-		return {
-			error: `git clean -X failed: ${err instanceof Error ? err.message : String(err)}`,
-		};
-	}
-	restoreAutoresearchFiles(preservedFiles);
-	let dirtyStatus = "";
+	let statusText: string;
 	try {
-		dirtyStatus = await git.status(workDir, {
+		statusText = await git.status(workDir, {
 			pathspecs: ["."],
 			porcelainV1: true,
 			untrackedFiles: "all",
@@ -584,45 +564,37 @@ async function revertFailedExperiment(
 		});
 	} catch (err) {
 		return {
-			error: `git status failed after cleanup: ${err instanceof Error ? err.message : String(err)}`,
+			error: `git status failed: ${err instanceof Error ? err.message : String(err)}`,
 		};
 	}
+
 	const workDirPrefix = await readGitWorkDirPrefix(options, workDir);
-	const remainingDirtyPaths = parseWorkDirDirtyPaths(dirtyStatus, workDirPrefix).filter(
-		relativePath => !isAutoresearchLocalStatePath(relativePath),
-	);
-	if (remainingDirtyPaths.length > 0) {
-		return {
-			error:
-				"Autoresearch cleanup left the worktree dirty. Resolve these paths before continuing: " +
-				remainingDirtyPaths.join(", "),
-		};
+	const { tracked, untracked } = computeRunModifiedPaths(preRunDirtyPaths, statusText, workDirPrefix);
+	const totalReverted = tracked.length + untracked.length;
+	if (totalReverted === 0) {
+		return { note: "nothing to revert" };
 	}
-	return { note: "reverted changes" };
-}
 
-function preserveAutoresearchFiles(workDir: string): PreservedFile[] {
-	const files: PreservedFile[] = [];
-	for (const relativePath of [...AUTORESEARCH_COMMITTABLE_FILES, "autoresearch.jsonl"]) {
-		const absolutePath = path.join(workDir, relativePath);
-		if (!fs.existsSync(absolutePath)) continue;
-		files.push({
-			content: fs.readFileSync(absolutePath),
-			path: absolutePath,
-		});
-	}
-	const localStateDir = path.join(workDir, ".autoresearch");
-	if (fs.existsSync(localStateDir)) {
-		collectDirectoryFiles(localStateDir, files);
+	if (tracked.length > 0) {
+		try {
+			await git.restore(workDir, { files: tracked, source: "HEAD", staged: true, worktree: true });
+		} catch (err) {
+			return {
+				error: `git restore failed: ${err instanceof Error ? err.message : String(err)}`,
+			};
+		}
 	}
-	return files;
-}
 
-function restoreAutoresearchFiles(files: PreservedFile[]): void {
-	for (const file of files) {
-		fs.mkdirSync(path.dirname(file.path), { recursive: true });
-		fs.writeFileSync(file.path, file.content);
+	for (const filePath of untracked) {
+		const absolutePath = path.join(workDir, filePath);
+		try {
+			fs.rmSync(absolutePath, { force: true, recursive: true });
+		} catch {
+			// Best-effort removal of untracked files
+		}
 	}
+
+	return { note: `reverted ${totalReverted} file${totalReverted === 1 ? "" : "s"}` };
 }
 
 function mergeStdoutStderr(result: { stderr: string; stdout: string }): string {
@@ -652,40 +624,26 @@ async function validateKeepPaths(
 
 	const workDirPrefix = await readGitWorkDirPrefix(options, workDir);
 	const committablePaths: string[] = [];
-	for (const normalizedPath of parseWorkDirDirtyPaths(statusText, workDirPrefix)) {
-		if (isAutoresearchLocalStatePath(normalizedPath)) {
+	for (const entry of parseWorkDirDirtyPathsWithStatus(statusText, workDirPrefix)) {
+		if (isAutoresearchLocalStatePath(entry.path)) {
 			continue;
 		}
-		if (isAutoresearchCommittableFile(normalizedPath)) {
-			committablePaths.push(normalizedPath);
+		if (isAutoresearchCommittableFile(entry.path)) {
+			committablePaths.push(entry.path);
 			continue;
 		}
-		if (state.offLimits.some(spec => pathMatchesContractPath(normalizedPath, spec))) {
-			return `cannot keep this run because ${normalizedPath} is listed under Off Limits in autoresearch.md`;
+		if (state.offLimits.some(spec => pathMatchesContractPath(entry.path, spec))) {
+			return `cannot keep this run because ${entry.path} is listed under Off Limits in autoresearch.md`;
 		}
-		if (!state.scopePaths.some(spec => pathMatchesContractPath(normalizedPath, spec))) {
-			return `cannot keep this run because ${normalizedPath} is outside Files in Scope`;
+		if (!state.scopePaths.some(spec => pathMatchesContractPath(entry.path, spec))) {
+			return `cannot keep this run because ${entry.path} is outside Files in Scope`;
 		}
-		committablePaths.push(normalizedPath);
+		committablePaths.push(entry.path);
 	}
 
 	return { committablePaths };
 }
 
-function collectDirectoryFiles(directory: string, files: PreservedFile[]): void {
-	for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-		const absolutePath = path.join(directory, entry.name);
-		if (entry.isDirectory()) {
-			collectDirectoryFiles(absolutePath, files);
-			continue;
-		}
-		files.push({
-			content: fs.readFileSync(absolutePath),
-			path: absolutePath,
-		});
-	}
-}
-
 async function updateRunMetadata(
 	runDirectory: string | null,
 	metadata: {

package/src/autoresearch/tools/run-experiment.ts

@@ -8,7 +8,8 @@ import type { ToolDefinition } from "../../extensibility/extensions";
 import type { Theme } from "../../modes/theme/theme";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, truncateTail } from "../../session/streaming-output";
 import { replaceTabs, shortenPath, truncateToWidth } from "../../tools/render-utils";
-import { getAutoresearchFingerprintMismatchError } from "../contract";
+import * as git from "../../utils/git";
+import { parseWorkDirDirtyPaths } from "../git";
 import {
 	EXPERIMENT_MAX_BYTES,
 	EXPERIMENT_MAX_LINES,
@@ -16,6 +17,7 @@ import {
 	formatNum,
 	getAutoresearchRunDirectory,
 	getNextAutoresearchRunNumber,
+	isAutoresearchLocalStatePath,
 	isAutoresearchShCommand,
 	killTree,
 	parseAsiLines,
@@ -40,6 +42,12 @@ const runExperimentSchema = Type.Object({
 			description: "Timeout in seconds for autoresearch.checks.sh. Defaults to 300.",
 		}),
 	),
+	force: Type.Optional(
+		Type.Boolean({
+			description:
+				"When true, allow a command that differs from the segment benchmark command and skip the rule that autoresearch.sh must be invoked directly when that script exists.",
+		}),
+	),
 });
 
 interface ProcessExecutionResult {
@@ -87,14 +95,9 @@ export function createRunExperimentTool(
 			const workDir = resolveWorkDir(ctx.cwd);
 			const checksPath = path.join(workDir, "autoresearch.checks.sh");
 			const autoresearchScriptPath = path.join(workDir, "autoresearch.sh");
-			const fingerprintError = getAutoresearchFingerprintMismatchError(state.segmentFingerprint, workDir);
-			if (fingerprintError) {
-				return {
-					content: [{ type: "text", text: `Error: ${fingerprintError}` }],
-				};
-			}
 
-			if (state.benchmarkCommand && params.command.trim() !== state.benchmarkCommand) {
+			const forceCommand = params.force === true;
+			if (!forceCommand && state.benchmarkCommand && params.command.trim() !== state.benchmarkCommand) {
 				return {
 					content: [
 						{
@@ -107,7 +110,7 @@ export function createRunExperimentTool(
 				};
 			}
 
-			if (fs.existsSync(autoresearchScriptPath) && !isAutoresearchShCommand(params.command)) {
+			if (!forceCommand && fs.existsSync(autoresearchScriptPath) && !isAutoresearchShCommand(params.command)) {
 				return {
 					content: [
 						{
@@ -156,6 +159,17 @@ export function createRunExperimentTool(
 			const checksLogPath = path.join(runDirectory, "checks.log");
 			const runJsonPath = path.join(runDirectory, "run.json");
 			await fs.promises.mkdir(runDirectory, { recursive: true });
+
+			const preRunStatus = await git.status(workDir, {
+				porcelainV1: true,
+				untrackedFiles: "all",
+				z: true,
+			});
+			const workDirPrefix = await git.show.prefix(workDir);
+			const preRunDirtyPaths = parseWorkDirDirtyPaths(preRunStatus, workDirPrefix).filter(
+				p => !isAutoresearchLocalStatePath(p),
+			);
+
 			runtime.lastRunChecks = null;
 			runtime.lastRunDuration = null;
 			runtime.lastRunAsi = null;
@@ -171,6 +185,7 @@ export function createRunExperimentTool(
 						benchmarkLogPath,
 						checksLogPath,
 						command: params.command,
+						preRunDirtyPaths,
 						startedAt: new Date().toISOString(),
 					},
 					null,
@@ -287,6 +302,7 @@ export function createRunExperimentTool(
 				parsedAsi,
 				metricName: state.metricName,
 				metricUnit: state.metricUnit,
+				preRunDirtyPaths,
 				truncation: llmTruncation.truncated ? llmTruncation : undefined,
 				fullOutputPath: execution.logPath,
 			};
@@ -300,6 +316,7 @@ export function createRunExperimentTool(
 				parsedMetrics,
 				parsedPrimary,
 				passed: resultDetails.passed,
+				preRunDirtyPaths,
 				runDirectory,
 				runNumber,
 			};
@@ -329,6 +346,7 @@ export function createRunExperimentTool(
 						parsedMetrics,
 						parsedPrimary,
 						parsedAsi,
+						preRunDirtyPaths,
 						truncation: resultDetails.truncation,
 						fullOutputPath: resultDetails.fullOutputPath,
 					},
@@ -337,8 +355,28 @@ export function createRunExperimentTool(
 				),
 			);
 
+			const commandWarnings: string[] = [];
+			if (forceCommand) {
+				if (state.benchmarkCommand && params.command.trim() !== state.benchmarkCommand) {
+					commandWarnings.push(
+						`Warning: command override (force=true). Segment benchmark is ${state.benchmarkCommand}; ran ${params.command}.`,
+					);
+				}
+				if (fs.existsSync(autoresearchScriptPath) && !isAutoresearchShCommand(params.command)) {
+					commandWarnings.push(
+						"Warning: autoresearch.sh exists but the command was not a direct autoresearch.sh invocation (force=true).",
+					);
+				}
+			}
+			const warningPrefix = commandWarnings.length > 0 ? `${commandWarnings.join("\n")}\n\n` : "";
+
 			return {
-				content: [{ type: "text", text: buildRunText(resultDetails, llmTruncation.content, state.bestMetric) }],
+				content: [
+					{
+						type: "text",
+						text: warningPrefix + buildRunText(resultDetails, llmTruncation.content, state.bestMetric),
+					},
+				],
 				details: resultDetails,
 			};
 		},

package/src/autoresearch/types.ts

@@ -64,7 +64,6 @@ export interface ExperimentState {
 	scopePaths: string[];
 	offLimits: string[];
 	constraints: string[];
-	segmentFingerprint: string | null;
 }
 
 export interface RunExperimentProgressDetails {
@@ -96,6 +95,7 @@ export interface RunDetails {
 	parsedAsi: ASIData | null;
 	metricName: string;
 	metricUnit: string;
+	preRunDirtyPaths: string[];
 	truncation?: TruncationResult;
 	fullOutputPath?: string;
 }
@@ -122,6 +122,7 @@ export interface PendingRunSummary {
 	parsedMetrics: NumericMetricMap | null;
 	parsedPrimary: number | null;
 	passed: boolean;
+	preRunDirtyPaths: string[];
 	runDirectory: string;
 	runNumber: number;
 }
@@ -165,7 +166,6 @@ export interface AutoresearchJsonConfigEntry {
 	scopePaths?: string[];
 	offLimits?: string[];
 	constraints?: string[];
-	segmentFingerprint?: string;
 }
 
 export interface AutoresearchJsonRunEntry {

package/src/capability/index.ts

@@ -114,8 +114,10 @@ async function loadImpl<T>(
 	const results = await Promise.all(
 		providers.map(async provider => {
 			try {
-				const result = await logger.timeAsync(`capability:${capability.id}:${provider.id}`, () =>
-					provider.load(ctx),
+				const result = await logger.time(
+					`capability:${capability.id}:${provider.id}`,
+					provider.load.bind(provider),
+					ctx,
 				);
 				return { provider, result };
 			} catch (error) {

package/src/cli/file-processor.ts

@@ -4,12 +4,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ImageContent } from "@oh-my-pi/pi-ai";
-import { getProjectDir, isEnoent } from "@oh-my-pi/pi-utils";
+import { getProjectDir, isEnoent, readImageMetadata } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { resolveReadPath } from "../tools/path-utils";
 import { formatBytes } from "../tools/render-utils";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
-import { detectSupportedImageMimeTypeFromFile } from "../utils/mime";
 
 // Keep CLI startup responsive and avoid OOM when users pass huge files.
 // If a file exceeds these limits, we include it as a path-only <file/> block.
@@ -42,7 +41,8 @@ export async function processFileArguments(fileArgs: string[], options?: Process
 			process.exit(1);
 		}
 
-		const mimeType = await detectSupportedImageMimeTypeFromFile(absolutePath);
+		const imageMetadata = await readImageMetadata(absolutePath);
+		const mimeType = imageMetadata?.mimeType;
 		const maxBytes = mimeType ? MAX_CLI_IMAGE_BYTES : MAX_CLI_TEXT_BYTES;
 		if (stat.size > maxBytes) {
 			console.error(

package/src/cli/grep-cli.ts

@@ -4,7 +4,7 @@
  * Handles `omp grep` subcommand for testing grep tool on Windows.
  */
 import * as path from "node:path";
-import { grep } from "@oh-my-pi/pi-natives";
+import { GrepOutputMode, grep } from "@oh-my-pi/pi-natives";
 import { APP_NAME } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 
@@ -14,7 +14,7 @@ export interface GrepCommandArgs {
 	glob?: string;
 	limit: number;
 	context: number;
-	mode: "content" | "filesWithMatches" | "count";
+	mode: GrepOutputMode;
 	gitignore: boolean;
 }
 
@@ -32,7 +32,7 @@ export function parseGrepArgs(args: string[]): GrepCommandArgs | undefined {
 		path: ".",
 		limit: 20,
 		context: 2,
-		mode: "content",
+		mode: GrepOutputMode.Content,
 		gitignore: true,
 	};
 
@@ -47,9 +47,9 @@ export function parseGrepArgs(args: string[]): GrepCommandArgs | undefined {
 		} else if (arg === "--context" || arg === "-C") {
 			result.context = parseInt(args[++i], 10);
 		} else if (arg === "--files" || arg === "-f") {
-			result.mode = "filesWithMatches";
+			result.mode = GrepOutputMode.FilesWithMatches;
 		} else if (arg === "--count" || arg === "-c") {
-			result.mode = "count";
+			result.mode = GrepOutputMode.Count;
 		} else if (arg === "--no-gitignore") {
 			result.gitignore = false;
 		} else if (!arg.startsWith("-")) {
@@ -89,7 +89,7 @@ export async function runGrepCommand(cmd: GrepCommandArgs): Promise<void> {
 			glob: cmd.glob,
 			mode: cmd.mode,
 			maxCount: cmd.limit,
-			context: cmd.mode === "content" ? cmd.context : undefined,
+			context: cmd.mode === GrepOutputMode.Content ? cmd.context : undefined,
 			hidden: true,
 			gitignore: cmd.gitignore,
 		});
@@ -105,7 +105,7 @@ export async function runGrepCommand(cmd: GrepCommandArgs): Promise<void> {
 		for (const match of result.matches) {
 			const displayPath = match.path.replace(/\\/g, "/");
 
-			if (cmd.mode === "content") {
+			if (cmd.mode === GrepOutputMode.Content) {
 				if (match.contextBefore) {
 					for (const ctx of match.contextBefore) {
 						console.log(chalk.dim(`${displayPath}-${ctx.lineNumber}- ${ctx.line}`));
@@ -118,7 +118,7 @@ export async function runGrepCommand(cmd: GrepCommandArgs): Promise<void> {
 					}
 				}
 				console.log("");
-			} else if (cmd.mode === "count") {
+			} else if (cmd.mode === GrepOutputMode.Count) {
 				console.log(`${chalk.cyan(displayPath)}: ${match.matchCount ?? 0} matches`);
 			} else {
 				console.log(chalk.cyan(displayPath));

package/src/cli/grievances-cli.ts

@@ -0,0 +1,78 @@
+/**
+ * CLI handler for `omp grievances` — view reported tool issues from auto-QA.
+ */
+import { Database } from "bun:sqlite";
+import chalk from "chalk";
+import { getAutoQaDbPath } from "../tools/report-tool-issue";
+
+interface GrievanceRow {
+	id: number;
+	model: string;
+	version: string;
+	tool: string;
+	report: string;
+}
+
+export interface ListGrievancesOptions {
+	limit: number;
+	tool?: string;
+	json: boolean;
+}
+
+function openDb(): Database | null {
+	try {
+		const db = new Database(getAutoQaDbPath(), { readonly: true });
+		return db;
+	} catch {
+		return null;
+	}
+}
+
+export async function listGrievances(options: ListGrievancesOptions): Promise<void> {
+	const db = openDb();
+	if (!db) {
+		if (options.json) {
+			console.log("[]");
+		} else {
+			console.log(
+				chalk.dim("No grievances database found. Enable auto-QA with PI_AUTO_QA=1 or the dev.autoqa setting."),
+			);
+		}
+		return;
+	}
+
+	try {
+		let rows: GrievanceRow[];
+		if (options.tool) {
+			rows = db
+				.prepare("SELECT id, model, version, tool, report FROM grievances WHERE tool = ? ORDER BY id DESC LIMIT ?")
+				.all(options.tool, options.limit) as GrievanceRow[];
+		} else {
+			rows = db
+				.prepare("SELECT id, model, version, tool, report FROM grievances ORDER BY id DESC LIMIT ?")
+				.all(options.limit) as GrievanceRow[];
+		}
+
+		if (options.json) {
+			console.log(JSON.stringify(rows, null, 2));
+			return;
+		}
+
+		if (rows.length === 0) {
+			console.log(chalk.dim("No grievances recorded yet."));
+			return;
+		}
+
+		for (const row of rows) {
+			console.log(
+				`${chalk.dim(`#${row.id}`)} ${chalk.cyan(row.tool)} ${chalk.dim(`(${row.model} v${row.version})`)}`,
+			);
+			console.log(`  ${row.report}`);
+			console.log();
+		}
+
+		console.log(chalk.dim(`Showing ${rows.length} most recent${options.tool ? ` for ${options.tool}` : ""}`));
+	} finally {
+		db.close();
+	}
+}