@delegance/claude-autopilot 2.4.0 → 5.0.0-alpha.1

package/src/core/fix/generator.ts

@@ -0,0 +1,149 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { Finding } from '../findings/types.ts';
+import type { ReviewEngine } from '../../adapters/review-engine/types.ts';
+
+export const CONTEXT_LINES = 20;
+
+// LLM error / refusal phrases that indicate a bad output
+const REFUSAL_PHRASES = [
+  'i cannot', "i can't", 'i am unable', 'as an ai', 'as a language model',
+  'i apologize', "i'm sorry", 'cannot safely', 'would require', 'error:',
+];
+
+export interface GenerateResult {
+  status: 'ok' | 'cannot_fix' | 'rejected' | 'error';
+  reason?: string;
+  originalLines?: string[];
+  replacementLines?: string[];
+  startLine?: number;
+  endLine?: number;
+}
+
+export function validateReplacement(original: string[], replacement: string[], _finding: Finding): string | null {
+  if (replacement.length === 0) return 'LLM returned empty output';
+
+  // Reject obvious LLM refusals
+  const joined = replacement.join(' ').toLowerCase();
+  for (const phrase of REFUSAL_PHRASES) {
+    if (joined.includes(phrase)) return `LLM refused: "${replacement[0]?.slice(0, 60)}"`;
+  }
+
+  // Reject if line count ballooned more than 3x (likely hallucination)
+  if (replacement.length > original.length * 3 + 10) {
+    return `Suspicious: replacement is ${replacement.length} lines vs original ${original.length}`;
+  }
+
+  // Reject if the replacement is identical (LLM made no change)
+  if (replacement.join('\n') === original.join('\n')) {
+    return 'LLM returned identical code — no change made';
+  }
+
+  return null;
+}
+
+export function buildUnifiedDiff(
+  original: string[],
+  replacement: string[],
+  filePath: string,
+  startLine: number,
+  opts: { color?: boolean } = {},
+): string {
+  // Colors default on for CLI ergonomics; MCP callers pass color:false so ANSI
+  // escapes don't leak into JSON responses that machine clients must parse.
+  const useColor = opts.color !== false;
+  const C = {
+    reset: '\x1b[0m', green: '\x1b[32m', red: '\x1b[31m',
+  };
+  const fmt = (c: keyof typeof C, t: string) => useColor ? `${C[c]}${t}${C.reset}` : t;
+  const lines: string[] = [`--- ${filePath}`, `+++ ${filePath} (proposed fix)`, `@@ -${startLine},${original.length} +${startLine},${replacement.length} @@`];
+  for (const l of original) lines.push(fmt('red', `- ${l}`));
+  for (const l of replacement) lines.push(fmt('green', `+ ${l}`));
+  return lines.join('\n');
+}
+
+export async function generateFix(finding: Finding, engine: ReviewEngine, cwd: string): Promise<GenerateResult> {
+  // MCP handlers can pass through findings loaded from disk — validate required
+  // fields rather than trusting the CLI pre-filter path.
+  if (!finding.file || typeof finding.file !== 'string') {
+    return { status: 'cannot_fix', reason: 'finding.file missing' };
+  }
+  if (typeof finding.line !== 'number' || !Number.isFinite(finding.line) || finding.line < 1) {
+    return { status: 'cannot_fix', reason: 'finding.line missing or invalid' };
+  }
+
+  const absPath = path.resolve(cwd, finding.file);
+  let fileLines: string[];
+  try {
+    fileLines = fs.readFileSync(absPath, 'utf8').split('\n');
+  } catch {
+    return { status: 'cannot_fix', reason: 'file not readable' };
+  }
+
+  const lineIdx = finding.line - 1;
+  if (lineIdx < 0 || lineIdx >= fileLines.length) {
+    return { status: 'cannot_fix', reason: 'line out of range' };
+  }
+
+  const startIdx = Math.max(0, lineIdx - CONTEXT_LINES);
+  const endIdx   = Math.min(fileLines.length - 1, lineIdx + CONTEXT_LINES);
+  const contextLines = fileLines.slice(startIdx, endIdx + 1);
+  const startLine = startIdx + 1;
+
+  const numbered = contextLines.map((l, i) => {
+    const n = startLine + i;
+    return `${n === finding.line ? '>>>' : '   '} ${String(n).padStart(4)}: ${l}`;
+  }).join('\n');
+
+  const prompt = [
+    `File: ${finding.file}`,
+    `Finding (line ${finding.line}): [${finding.severity.toUpperCase()}] ${finding.message}`,
+    finding.suggestion ? `Suggestion: ${finding.suggestion}` : '',
+    '',
+    'Relevant lines (>>> marks the finding):',
+    '```',
+    numbered,
+    '```',
+    '',
+    `Rewrite ONLY lines ${startLine}–${endIdx + 1} to fix this finding.`,
+    'Rules:',
+    '- Output ONLY the replacement lines with no explanation, no markdown fences, no line numbers',
+    '- Preserve indentation exactly',
+    '- Make the minimal change needed — do not refactor unrelated code',
+    '- If the fix cannot be done safely in this context, output exactly: CANNOT_FIX',
+  ].filter(Boolean).join('\n');
+
+  let rawOutput: string;
+  try {
+    const output = await engine.review({ content: prompt, kind: 'file-batch' });
+    rawOutput = output.rawOutput.trim();
+  } catch (err) {
+    return { status: 'error', reason: `LLM error: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  if (rawOutput === 'CANNOT_FIX' || rawOutput.startsWith('CANNOT_FIX')) {
+    return { status: 'cannot_fix', reason: 'LLM: cannot fix safely in this context' };
+  }
+
+  // Strip markdown fences if the model added them despite instructions
+  const cleaned = rawOutput
+    .replace(/^```[a-zA-Z]*\n?/, '')
+    .replace(/\n?```$/, '')
+    .trimEnd();
+
+  const replacementLines = cleaned.split('\n');
+  const originalLines = contextLines;
+
+  const validationError = validateReplacement(originalLines, replacementLines, finding);
+  if (validationError) {
+    return { status: 'rejected', reason: validationError };
+  }
+
+  return {
+    status: 'ok',
+    originalLines,
+    replacementLines,
+    startLine,
+    endLine: endIdx + 1,
+  };
+}

package/src/core/ignore/index.ts

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { minimatch } from 'minimatch';
 import type { Finding } from '../findings/types.ts';
-import type { AutopilotConfig } from '../config/types.ts';
+import type { GuardrailConfig } from '../config/types.ts';
 
 export interface IgnoreRule {
   ruleId: string | '*';  // finding id prefix or '*' for any
@@ -10,7 +10,7 @@ export interface IgnoreRule {
 }
 
 export function loadIgnoreRules(cwd: string): IgnoreRule[] {
-  const filePath = path.join(cwd, '.autopilot-ignore');
+  const filePath = path.join(cwd, '.guardrail-ignore');
   if (!fs.existsSync(filePath)) return [];
 
   const rules: IgnoreRule[] = [];
@@ -37,8 +37,8 @@ function matchesRule(finding: Finding, rule: IgnoreRule): boolean {
   return minimatch(finding.file.replace(/\\/g, '/'), rule.pathGlob, { matchBase: true });
 }
 
-/** Convert `ignore:` entries from autopilot.config.yaml into IgnoreRules. */
-export function parseConfigIgnore(entries: AutopilotConfig['ignore']): IgnoreRule[] {
+/** Convert `ignore:` entries from guardrail.config.yaml into IgnoreRules. */
+export function parseConfigIgnore(entries: GuardrailConfig['ignore']): IgnoreRule[] {
   if (!entries || entries.length === 0) return [];
   return entries.map(entry => {
     if (typeof entry === 'string') {

package/src/core/mcp/concurrency.ts

@@ -0,0 +1,16 @@
+const mutexes = new Map<string, Promise<void>>();
+
+export async function withWriteLock<T>(workspace: string, fn: () => Promise<T>): Promise<T> {
+  let unlock!: () => void;
+  const current = new Promise<void>(resolve => { unlock = resolve; });
+  const prev = mutexes.get(workspace) ?? Promise.resolve();
+  mutexes.set(workspace, current);
+
+  await prev;
+  try {
+    return await fn();
+  } finally {
+    unlock();
+    if (mutexes.get(workspace) === current) mutexes.delete(workspace);
+  }
+}

package/src/core/mcp/handlers/fix-finding.ts

@@ -0,0 +1,126 @@
+// src/core/mcp/handlers/fix-finding.ts
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveWorkspace, assertInWorkspace } from '../workspace.ts';
+import { loadRun, checksumFile } from '../run-store.ts';
+import { withWriteLock } from '../concurrency.ts';
+import { generateFix, buildUnifiedDiff } from '../../fix/generator.ts';
+import type { ReviewEngine } from '../../../adapters/review-engine/types.ts';
+import type { GuardrailConfig } from '../../config/types.ts';
+
+export interface FixFindingResult {
+  schema_version: 1;
+  status: 'fixed' | 'reverted' | 'human_required' | 'skipped';
+  reason?: string;
+  patch?: string;
+  commitSha?: string;
+  appliedFiles: string[];
+}
+
+export async function handleFixFinding(
+  input: { run_id: string; finding_id: string; cwd?: string; dry_run?: boolean },
+  config: GuardrailConfig,
+  engine: ReviewEngine,
+): Promise<FixFindingResult> {
+  const workspace = resolveWorkspace(input.cwd);
+
+  const record = loadRun(workspace, input.run_id);
+  if (!record) {
+    throw Object.assign(
+      new Error(`run_not_found: no run with id "${input.run_id}"`),
+      { code: 'run_not_found' },
+    );
+  }
+
+  const finding = record.findings.find(f => f.id === input.finding_id);
+  if (!finding) {
+    throw Object.assign(
+      new Error(`finding_not_found: no finding with id "${input.finding_id}"`),
+      { code: 'finding_not_found' },
+    );
+  }
+
+  // Protected path check
+  if (finding.protectedPath) {
+    return { schema_version: 1, status: 'human_required', reason: 'protected_path', appliedFiles: [] };
+  }
+
+  // Validate finding.file against workspace boundary (run records could be tampered)
+  const absFile = assertInWorkspace(workspace, finding.file);
+
+  // Look up checksum under both the raw finding.file and its relative form,
+  // so the drift check works whether older runs stored absolute or relative keys.
+  const relKey = path.relative(workspace, absFile);
+  const savedChecksum = record.fileChecksums[finding.file] ?? record.fileChecksums[relKey] ?? '';
+
+  // Dry-run path: generate fix, return patch, no mutations
+  if (input.dry_run) {
+    const currentChecksum = checksumFile(absFile);
+    if (savedChecksum && currentChecksum !== savedChecksum) {
+      return { schema_version: 1, status: 'human_required', reason: 'file_changed', appliedFiles: [] };
+    }
+    const genResult = await generateFix(finding, engine, workspace);
+    if (genResult.status !== 'ok') {
+      return { schema_version: 1, status: 'human_required', reason: genResult.reason, appliedFiles: [] };
+    }
+    const patch = buildUnifiedDiff(
+      genResult.originalLines!,
+      genResult.replacementLines!,
+      finding.file,
+      genResult.startLine!,
+      { color: false }, // MCP clients parse patch text — no ANSI
+    );
+    return { schema_version: 1, status: 'skipped', reason: 'dry_run', patch, appliedFiles: [] };
+  }
+
+  // Apply path: checksum validation + fix generation run INSIDE the lock to
+  // prevent TOCTOU between two concurrent fix_finding calls on the same file.
+  return withWriteLock(workspace, async () => {
+    const currentChecksum = checksumFile(absFile);
+    if (savedChecksum && currentChecksum !== savedChecksum) {
+      return { schema_version: 1 as const, status: 'human_required' as const, reason: 'file_changed', appliedFiles: [] };
+    }
+
+    const genResult = await generateFix(finding, engine, workspace);
+    if (genResult.status !== 'ok') {
+      return { schema_version: 1 as const, status: 'human_required' as const, reason: genResult.reason, appliedFiles: [] };
+    }
+
+    const patch = buildUnifiedDiff(
+      genResult.originalLines!,
+      genResult.replacementLines!,
+      finding.file,
+      genResult.startLine!,
+      { color: false },
+    );
+
+    const originalContent = fs.readFileSync(absFile, 'utf8');
+    const allLines = originalContent.split('\n');
+    const newLines = [
+      ...allLines.slice(0, genResult.startLine! - 1),
+      ...genResult.replacementLines!,
+      ...allLines.slice(genResult.endLine!),
+    ];
+
+    const tmpFile = absFile + '.guardrail.tmp';
+    fs.writeFileSync(tmpFile, newLines.join('\n'), 'utf8');
+    fs.renameSync(tmpFile, absFile);
+
+    // Test verification
+    if (config.testCommand) {
+      const { spawnSync } = await import('node:child_process');
+      const testResult = spawnSync('/bin/sh', ['-c', config.testCommand], {
+        cwd: workspace,
+        shell: false,
+        timeout: 120_000,
+        encoding: 'utf8',
+      });
+      if (testResult.status !== 0) {
+        fs.writeFileSync(absFile, originalContent, 'utf8');
+        return { schema_version: 1 as const, status: 'reverted' as const, patch, appliedFiles: [] };
+      }
+    }
+
+    return { schema_version: 1 as const, status: 'fixed' as const, patch, appliedFiles: [finding.file] };
+  });
+}

package/src/core/mcp/handlers/get-capabilities.ts

@@ -0,0 +1,62 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as child_process from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolveWorkspace } from '../workspace.ts';
+import type { GuardrailConfig, StaticRuleReference } from '../../config/types.ts';
+
+export interface CapabilitiesResult {
+  schema_version: 1;
+  adapter: string;
+  enabledRules: string[];
+  writeable: boolean;
+  gitAvailable: boolean;
+  testCommandConfigured: boolean;
+  guardrailVersion: string;
+}
+
+function readVersion(): string {
+  try {
+    const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '../../../../package.json');
+    return (JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version: string }).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+function isGitAvailable(workspace: string): boolean {
+  try {
+    // Safe: no user input, static arguments only
+    child_process.execFileSync('git', ['rev-parse', '--git-dir'], {
+      cwd: workspace,
+      stdio: 'ignore',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function extractRuleName(rule: StaticRuleReference): string {
+  return typeof rule === 'string' ? rule : rule.adapter;
+}
+
+export async function handleGetCapabilities(
+  input: { cwd?: string },
+  config: GuardrailConfig,
+  adapterName: string,
+): Promise<CapabilitiesResult> {
+  const workspace = resolveWorkspace(input.cwd);
+  const staticRules = config.staticRules ?? [];
+  const enabledRules = staticRules.map(extractRuleName);
+
+  return {
+    schema_version: 1,
+    adapter: adapterName,
+    enabledRules,
+    writeable: true,
+    gitAvailable: isGitAvailable(workspace),
+    testCommandConfigured: !!config.testCommand,
+    guardrailVersion: readVersion(),
+  };
+}

package/src/core/mcp/handlers/get-findings.ts

@@ -0,0 +1,36 @@
+import { resolveWorkspace } from '../workspace.ts';
+import { loadRun } from '../run-store.ts';
+import type { Finding, Severity } from '../../findings/types.ts';
+
+export interface GetFindingsResult {
+  schema_version: 1;
+  run_id: string;
+  findings: Finding[];
+  cachedAt: string;
+}
+
+// Severity order: index 0 = highest priority
+const SEVERITY_ORDER = ['critical', 'warning', 'note'] as const;
+
+export async function handleGetFindings(input: {
+  run_id: string;
+  severity?: Severity;
+  cwd?: string;
+}): Promise<GetFindingsResult> {
+  const workspace = resolveWorkspace(input.cwd);
+  const record = loadRun(workspace, input.run_id);
+  if (!record) {
+    throw Object.assign(
+      new Error(`run_not_found: no run with id "${input.run_id}"`),
+      { code: 'run_not_found' }
+    );
+  }
+
+  let findings = record.findings;
+  if (input.severity) {
+    const minIdx = SEVERITY_ORDER.indexOf(input.severity);
+    findings = findings.filter(f => SEVERITY_ORDER.indexOf(f.severity) <= minIdx);
+  }
+
+  return { schema_version: 1, run_id: input.run_id, findings, cachedAt: record.createdAt };
+}

package/src/core/mcp/handlers/review-diff.ts

@@ -0,0 +1,65 @@
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+import { resolveWorkspace } from '../workspace.ts';
+import { saveRun, checksumFile, pruneOldRuns } from '../run-store.ts';
+import { runGuardrail } from '../../pipeline/run.ts';
+import { resolveGitTouchedFiles } from '../../git/touched-files.ts';
+import { loadRulesFromConfig } from '../../static-rules/registry.ts';
+import { detectGitContext } from '../../detect/git-context.ts';
+import type { ReviewEngine } from '../../../adapters/review-engine/types.ts';
+import type { GuardrailConfig } from '../../config/types.ts';
+import type { Finding } from '../../findings/types.ts';
+
+export interface ReviewDiffResult {
+  schema_version: 1;
+  run_id: string;
+  findings: Finding[];
+  human_summary: string;
+  usage?: { costUSD?: number };
+}
+
+export async function handleReviewDiff(
+  input: { base?: string; cwd?: string; static_only?: boolean },
+  config: GuardrailConfig,
+  engine: ReviewEngine,
+): Promise<ReviewDiffResult> {
+  const workspace = resolveWorkspace(input.cwd);
+  pruneOldRuns(workspace, 24 * 60 * 60 * 1000);
+
+  const touchedFiles = resolveGitTouchedFiles({ cwd: workspace, base: input.base });
+  const staticRules = config.staticRules ? await loadRulesFromConfig(config.staticRules) : [];
+  const gitCtx = detectGitContext(workspace);
+
+  const result = await runGuardrail({
+    touchedFiles,
+    config,
+    reviewEngine: engine,
+    staticRules,
+    cwd: workspace,
+    gitSummary: gitCtx.summary ?? undefined,
+    base: input.base,
+    skipReview: input.static_only ?? false,
+  });
+
+  const run_id = crypto.randomUUID();
+  const fileChecksums: Record<string, string> = {};
+  for (const f of touchedFiles) {
+    const abs = path.isAbsolute(f) ? f : path.resolve(workspace, f);
+    fileChecksums[f] = checksumFile(abs);
+  }
+  saveRun(workspace, run_id, result.allFindings, fileChecksums);
+
+  const critCount = result.allFindings.filter(f => f.severity === 'critical').length;
+  const warnCount = result.allFindings.filter(f => f.severity === 'warning').length;
+  const human_summary = result.allFindings.length === 0
+    ? 'No findings — looks clean.'
+    : `${result.allFindings.length} finding${result.allFindings.length !== 1 ? 's' : ''}: ${critCount} critical, ${warnCount} warning.`;
+
+  return {
+    schema_version: 1,
+    run_id,
+    findings: result.allFindings,
+    human_summary,
+    usage: result.totalCostUSD !== undefined ? { costUSD: result.totalCostUSD } : undefined,
+  };
+}

package/src/core/mcp/handlers/scan-files.ts

@@ -0,0 +1,65 @@
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+import { resolveWorkspace, assertInWorkspace } from '../workspace.ts';
+import { saveRun, checksumFile, pruneOldRuns } from '../run-store.ts';
+import { runReviewPhase } from '../../pipeline/review-phase.ts';
+import { detectStack } from '../../detect/stack.ts';
+import type { ReviewEngine } from '../../../adapters/review-engine/types.ts';
+import type { GuardrailConfig } from '../../config/types.ts';
+import type { Finding } from '../../findings/types.ts';
+
+export interface ScanFilesResult {
+  schema_version: 1;
+  run_id: string;
+  findings: Finding[];
+  human_summary: string;
+}
+
+export async function handleScanFiles(
+  input: { files: string[]; cwd?: string; ask?: string },
+  config: GuardrailConfig,
+  engine: ReviewEngine,
+): Promise<ScanFilesResult> {
+  const workspace = resolveWorkspace(input.cwd);
+  pruneOldRuns(workspace, 24 * 60 * 60 * 1000);
+
+  // Validate all paths before any I/O
+  const resolvedFiles = input.files.map(f => assertInWorkspace(workspace, f));
+
+  const stack = detectStack(workspace) ?? config.stack;
+  const effectiveConfig: GuardrailConfig = input.ask
+    ? { ...config, stack: `${stack ?? 'unknown'}\n\nFocus: ${input.ask}` }
+    : config;
+
+  const result = await runReviewPhase({
+    touchedFiles: resolvedFiles,
+    config: effectiveConfig,
+    engine,
+    cwd: workspace,
+  });
+
+  const run_id = crypto.randomUUID();
+  const fileChecksums: Record<string, string> = {};
+  for (const f of resolvedFiles) {
+    // Store relative key so fix_finding's finding.file lookup matches
+    const relKey = path.relative(workspace, f);
+    fileChecksums[relKey] = checksumFile(f);
+  }
+  // Normalize finding.file to relative paths so downstream lookups against
+  // fileChecksums (keyed by relative paths) work regardless of whether the
+  // review engine echoed absolute or relative paths.
+  const normalizedFindings = result.findings.map(f => {
+    if (!f.file) return f;
+    const rel = path.isAbsolute(f.file) ? path.relative(workspace, f.file) : f.file;
+    return rel === f.file ? f : { ...f, file: rel };
+  });
+  saveRun(workspace, run_id, normalizedFindings, fileChecksums);
+
+  const critCount = result.findings.filter(f => f.severity === 'critical').length;
+  const warnCount = result.findings.filter(f => f.severity === 'warning').length;
+  const human_summary = result.findings.length === 0
+    ? 'No findings.'
+    : `${result.findings.length} finding${result.findings.length !== 1 ? 's' : ''}: ${critCount} critical, ${warnCount} warning.`;
+
+  return { schema_version: 1, run_id, findings: normalizedFindings, human_summary };
+}

package/src/core/mcp/handlers/validate-fix.ts

@@ -0,0 +1,41 @@
+import { spawnSync } from 'node:child_process';
+import { resolveWorkspace } from '../workspace.ts';
+import { withWriteLock } from '../concurrency.ts';
+import type { GuardrailConfig } from '../../config/types.ts';
+
+export interface ValidateFixResult {
+  schema_version: 1;
+  passed: boolean;
+  output: string;
+  durationMs: number;
+}
+
+export async function handleValidateFix(
+  input: { cwd?: string; files?: string[] },
+  config: GuardrailConfig,
+): Promise<ValidateFixResult> {
+  const workspace = resolveWorkspace(input.cwd);
+
+  if (!config.testCommand) {
+    return { schema_version: 1, passed: true, output: '', durationMs: 0 };
+  }
+
+  return withWriteLock(workspace, async () => {
+    const start = Date.now();
+    const result = spawnSync('/bin/sh', ['-c', config.testCommand!], {
+      cwd: workspace,
+      shell: false,
+      timeout: 120_000,
+      encoding: 'utf8',
+    });
+    const durationMs = Date.now() - start;
+    const raw = ((result.stdout ?? '') + (result.stderr ?? '')).slice(0, 4000);
+
+    return {
+      schema_version: 1 as const,
+      passed: result.status === 0,
+      output: raw,
+      durationMs,
+    };
+  });
+}

package/src/core/mcp/run-store.ts

@@ -0,0 +1,85 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import type { Finding } from '../findings/types.ts';
+
+const RUNS_DIR = '.guardrail-cache/runs';
+
+export interface RunRecord {
+  run_id: string;
+  createdAt: string;
+  findings: Finding[];
+  fileChecksums: Record<string, string>;
+}
+
+function runsDir(cwd: string): string {
+  return path.join(cwd, RUNS_DIR);
+}
+
+// Reject any run_id that isn't a safe filename component — path separators,
+// relative segments, hidden files, or empty strings.
+// run_ids are generated server-side as UUIDs (crypto.randomUUID) so strict
+// validation here is safe. MCP clients that fabricate run_ids get a clear
+// rejection instead of silently reading outside RUNS_DIR.
+const VALID_RUN_ID = /^[A-Za-z0-9_-]+$/;
+
+function assertValidRunId(runId: string): void {
+  if (!runId || typeof runId !== 'string' || !VALID_RUN_ID.test(runId)) {
+    throw Object.assign(
+      new Error(`invalid run_id: "${runId}" (expected alphanumeric + dash/underscore)`),
+      { code: 'invalid_run_id' },
+    );
+  }
+}
+
+function runFilePath(cwd: string, runId: string): string {
+  assertValidRunId(runId);
+  return path.join(runsDir(cwd), `${runId}.json`);
+}
+
+export function saveRun(
+  cwd: string,
+  runId: string,
+  findings: Finding[],
+  fileChecksums: Record<string, string>,
+): void {
+  const dir = runsDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  const record: RunRecord = { run_id: runId, createdAt: new Date().toISOString(), findings, fileChecksums };
+  const tmp = runFilePath(cwd, runId) + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(record, null, 2), 'utf8');
+  fs.renameSync(tmp, runFilePath(cwd, runId));
+}
+
+export function loadRun(cwd: string, runId: string): RunRecord | null {
+  const p = runFilePath(cwd, runId);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as RunRecord;
+  } catch {
+    return null;
+  }
+}
+
+export function checksumFile(filePath: string): string {
+  try {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash('sha256').update(content).digest('hex');
+  } catch {
+    return '';
+  }
+}
+
+export function pruneOldRuns(cwd: string, maxAgeMs: number): void {
+  const dir = runsDir(cwd);
+  if (!fs.existsSync(dir)) return;
+  const cutoff = Date.now() - maxAgeMs;
+  for (const entry of fs.readdirSync(dir)) {
+    if (!entry.endsWith('.json')) continue;
+    const full = path.join(dir, entry);
+    try {
+      const stat = fs.statSync(full);
+      if (stat.mtimeMs < cutoff) fs.unlinkSync(full);
+    } catch { /* ignore */ }
+  }
+}