ai-spec-dev 0.33.0 → 0.35.0

package/core/project-index.ts

@@ -0,0 +1,301 @@
+/**
+ * project-index.ts — Persistent project discovery & index.
+ *
+ * Scans a root directory for sub-projects (any dir with a recognisable
+ * project manifest), and maintains an incremental JSON index file at
+ * .ai-spec-index.json in the scan root.
+ *
+ * Incremental rules:
+ *  - New project found   → added with firstSeen = now
+ *  - Existing project    → techStack / type / role / hasConstitution refreshed, lastSeen = now
+ *  - Previously indexed but directory gone → marked missing:true, NOT deleted
+ *
+ * The index is intentionally lightweight — no AI calls, pure filesystem scan.
+ */
+
+import * as fs from "fs-extra";
+import * as path from "path";
+import { detectRepoType, RepoType, RepoRole, WORKSPACE_CONFIG_FILE } from "./workspace-loader";
+import { CONSTITUTION_FILE } from "./constitution-generator";
+
+export const INDEX_FILE = ".ai-spec-index.json";
+
+// ─── Key dependency lists for tech-stack extraction ──────────────────────────
+
+const KEY_DEPS: string[] = [
+  // Frameworks
+  "express", "fastify", "koa", "@nestjs/core", "hapi",
+  "next", "react", "vue", "nuxt", "svelte",
+  "react-native", "expo",
+  // DB / ORM
+  "prisma", "@prisma/client", "mongoose", "typeorm", "sequelize", "drizzle-orm",
+  // Auth
+  "jsonwebtoken", "passport", "next-auth", "@clerk/nextjs",
+  // Build / Lang
+  "typescript", "vite", "webpack", "esbuild", "turbo",
+  // Testing
+  "jest", "vitest", "mocha", "cypress", "playwright",
+  // Infra
+  "redis", "bull", "socket.io", "graphql", "@trpc/server",
+];
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface ProjectEntry {
+  /** Directory name */
+  name: string;
+  /** Path relative to scanRoot */
+  path: string;
+  type: RepoType;
+  role: RepoRole;
+  /** Key dependencies detected (subset of package.json deps or language markers) */
+  techStack: string[];
+  /** Whether .ai-spec-constitution.md exists */
+  hasConstitution: boolean;
+  /** Whether .ai-spec-workspace.json exists (this repo is a workspace root) */
+  hasWorkspace: boolean;
+  /** ISO timestamp of first discovery */
+  firstSeen: string;
+  /** ISO timestamp of last successful scan */
+  lastSeen: string;
+  /** true when the directory no longer exists on disk */
+  missing?: boolean;
+}
+
+export interface ProjectIndex {
+  /** Absolute path of the directory that was scanned */
+  scanRoot: string;
+  /** ISO timestamp of last scan */
+  lastScanned: string;
+  projects: ProjectEntry[];
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Directories to always skip during scan */
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", ".svn", "dist", "build", "out", ".next",
+  ".nuxt", "coverage", ".turbo", ".cache", "__pycache__", "vendor",
+  ".ai-spec-vcr", ".ai-spec-logs", "specs",
+]);
+
+/** Manifest files that identify a directory as a project root */
+const MANIFEST_FILES = [
+  "package.json",
+  "go.mod",
+  "Cargo.toml",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "requirements.txt",
+  "pyproject.toml",
+  "setup.py",
+  "composer.json",
+];
+
+async function isProjectRoot(absPath: string): Promise<boolean> {
+  for (const manifest of MANIFEST_FILES) {
+    if (await fs.pathExists(path.join(absPath, manifest))) return true;
+  }
+  return false;
+}
+
+async function extractTechStack(absPath: string, type: RepoType): Promise<string[]> {
+  const stack: string[] = [];
+
+  // Language marker for non-Node projects
+  if (type === "go")     stack.push("go");
+  if (type === "rust")   stack.push("rust");
+  if (type === "java")   stack.push("java");
+  if (type === "python") stack.push("python");
+  if (type === "php")    stack.push("php");
+
+  const pkgPath = path.join(absPath, "package.json");
+  if (!(await fs.pathExists(pkgPath))) return stack;
+
+  let pkg: Record<string, unknown> = {};
+  try { pkg = await fs.readJson(pkgPath); } catch { return stack; }
+
+  const allDeps = {
+    ...((pkg.dependencies as Record<string, string>) ?? {}),
+    ...((pkg.devDependencies as Record<string, string>) ?? {}),
+  };
+  const depKeys = new Set(Object.keys(allDeps));
+
+  for (const dep of KEY_DEPS) {
+    if (depKeys.has(dep)) stack.push(dep);
+  }
+
+  return stack;
+}
+
+// ─── Scan ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Discover all project roots under `rootDir` up to `maxDepth` levels deep.
+ * Returns paths relative to rootDir.
+ */
+async function discoverProjects(
+  rootDir: string,
+  maxDepth: number
+): Promise<string[]> {
+  const found: string[] = [];
+
+  async function walk(absDir: string, depth: number): Promise<void> {
+    if (depth > maxDepth) return;
+
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.readdir(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+
+      const childAbs = path.join(absDir, entry.name);
+
+      // Skip git worktrees — they have a .git *file* (not directory)
+      const gitPath = path.join(childAbs, ".git");
+      if (await fs.pathExists(gitPath)) {
+        const gitStat = await fs.stat(gitPath);
+        if (gitStat.isFile()) continue; // git worktree — skip
+      }
+
+      if (await isProjectRoot(childAbs)) {
+        found.push(path.relative(rootDir, childAbs));
+        // Don't recurse into a project root — avoids picking up nested node_modules etc.
+      } else {
+        await walk(childAbs, depth + 1);
+      }
+    }
+  }
+
+  await walk(rootDir, 0);
+  return found;
+}
+
+// ─── Index load / save ────────────────────────────────────────────────────────
+
+export async function loadIndex(scanRoot: string): Promise<ProjectIndex | null> {
+  const filePath = path.join(scanRoot, INDEX_FILE);
+  try {
+    return await fs.readJson(filePath);
+  } catch {
+    return null;
+  }
+}
+
+export async function saveIndex(scanRoot: string, index: ProjectIndex): Promise<string> {
+  const filePath = path.join(scanRoot, INDEX_FILE);
+  await fs.writeJson(filePath, index, { spaces: 2 });
+  return filePath;
+}
+
+// ─── Incremental merge ────────────────────────────────────────────────────────
+
+export interface ScanResult {
+  index: ProjectIndex;
+  added: ProjectEntry[];
+  updated: ProjectEntry[];
+  unchanged: ProjectEntry[];
+  nowMissing: ProjectEntry[];
+}
+
+/**
+ * Run an incremental scan of `scanRoot`, merge with the existing index, and
+ * return the updated index along with a change summary.
+ */
+export async function runScan(
+  scanRoot: string,
+  maxDepth = 2
+): Promise<ScanResult> {
+  const now = new Date().toISOString();
+  const existing = await loadIndex(scanRoot);
+  const existingMap = new Map<string, ProjectEntry>(
+    (existing?.projects ?? []).map((p) => [p.path, p])
+  );
+
+  const discoveredPaths = await discoverProjects(scanRoot, maxDepth);
+
+  const added: ProjectEntry[] = [];
+  const updated: ProjectEntry[] = [];
+  const unchanged: ProjectEntry[] = [];
+  const seenPaths = new Set<string>();
+
+  for (const relPath of discoveredPaths) {
+    const absPath = path.join(scanRoot, relPath);
+    seenPaths.add(relPath);
+
+    const { type, role } = await detectRepoType(absPath);
+    const techStack = await extractTechStack(absPath, type);
+    const hasConstitution = await fs.pathExists(path.join(absPath, CONSTITUTION_FILE));
+    const hasWorkspace = await fs.pathExists(path.join(absPath, WORKSPACE_CONFIG_FILE));
+    const name = path.basename(relPath);
+
+    const prev = existingMap.get(relPath);
+    if (!prev) {
+      const entry: ProjectEntry = {
+        name,
+        path: relPath,
+        type,
+        role,
+        techStack,
+        hasConstitution,
+        hasWorkspace,
+        firstSeen: now,
+        lastSeen: now,
+      };
+      added.push(entry);
+      existingMap.set(relPath, entry);
+    } else {
+      // Check if anything changed
+      const changed =
+        prev.type !== type ||
+        prev.role !== role ||
+        prev.hasConstitution !== hasConstitution ||
+        prev.hasWorkspace !== hasWorkspace ||
+        JSON.stringify(prev.techStack.sort()) !== JSON.stringify(techStack.sort());
+
+      const entry: ProjectEntry = {
+        ...prev,
+        type,
+        role,
+        techStack,
+        hasConstitution,
+        hasWorkspace,
+        lastSeen: now,
+        missing: undefined, // clear missing flag if it came back
+      };
+      existingMap.set(relPath, entry);
+
+      if (changed) {
+        updated.push(entry);
+      } else {
+        unchanged.push(entry);
+      }
+    }
+  }
+
+  // Mark previously known projects as missing if their directory is gone
+  const nowMissing: ProjectEntry[] = [];
+  for (const [relPath, entry] of existingMap) {
+    if (!seenPaths.has(relPath) && !entry.missing) {
+      const gone: ProjectEntry = { ...entry, missing: true };
+      existingMap.set(relPath, gone);
+      nowMissing.push(gone);
+    }
+  }
+
+  const projects = [...existingMap.values()].sort((a, b) => a.path.localeCompare(b.path));
+
+  const index: ProjectIndex = {
+    scanRoot,
+    lastScanned: now,
+    projects,
+  };
+
+  return { index, added, updated, unchanged, nowMissing };
+}

package/core/reviewer.ts

@@ -4,10 +4,37 @@ import * as path from "path";
 import * as fs from "fs-extra";
 import { AIProvider } from "./spec-generator";
 import {
+  specComplianceSystemPrompt,
   reviewArchitectureSystemPrompt,
   reviewImplementationSystemPrompt,
   reviewImpactComplexitySystemPrompt,
 } from "../prompts/codegen.prompt";
+import { CONSTITUTION_FILE } from "./constitution-generator";
+
+// ─── Constitution Lessons Helper ──────────────────────────────────────────────
+
+/**
+ * Extract the §9 accumulated lessons section from a constitution file.
+ * Returns null if the section is absent or the file cannot be read.
+ */
+async function loadAccumulatedLessons(projectRoot: string): Promise<string | null> {
+  const constitutionPath = path.join(projectRoot, CONSTITUTION_FILE);
+  let content: string;
+  try {
+    content = await fs.readFile(constitutionPath, "utf-8");
+  } catch {
+    return null;
+  }
+  const marker = "## 9. 积累教训";
+  const idx = content.indexOf(marker);
+  if (idx === -1) return null;
+  // Extract from §9 header to end of file (or next top-level section)
+  const section = content.slice(idx);
+  const nextSection = section.slice(marker.length).match(/\n## \d/);
+  return nextSection
+    ? section.slice(0, marker.length + nextSection.index!)
+    : section;
+}
 
 // ─── Review History ────────────────────────────────────────────────────────────
 
@@ -15,6 +42,7 @@ interface ReviewHistoryEntry {
   date: string;
   specFile: string;
   score: number;
+  complianceScore?: number;
   topIssues: string[];
   impactLevel?: "低" | "中" | "高";
   complexityLevel?: "低" | "中" | "高";
@@ -55,6 +83,18 @@ function extractScore(reviewText: string): number {
   return match ? parseFloat(match[1]) : 0;
 }
 
+/** Extract compliance score from Pass 0 output (looks for "ComplianceScore: X/10") */
+export function extractComplianceScore(complianceText: string): number {
+  const match = complianceText.match(/ComplianceScore:\s*(\d+(?:\.\d+)?)\s*\/\s*10/i);
+  return match ? parseFloat(match[1]) : 0;
+}
+
+/** Count missing requirements from Pass 0 output */
+export function extractMissingCount(complianceText: string): number {
+  const summaryMatch = complianceText.match(/Missing:\s*(\d+)/i);
+  return summaryMatch ? parseInt(summaryMatch[1], 10) : 0;
+}
+
 /** Extract impact level from Pass 3 review ("影响等级：低/中/高") */
 function extractImpactLevel(reviewText: string): "低" | "中" | "高" | undefined {
   const match = reviewText.match(/影响等级[：:]\s*(低|中|高)/);
@@ -126,8 +166,9 @@ export class CodeReviewer {
   }
 
   /**
-   * Three-pass review:
-   *   Pass 1 — architecture (spec compliance, layer separation, auth)
+   * Four-pass review:
+   *   Pass 0 — spec compliance (exhaustive requirement coverage audit)
+   *   Pass 1 — architecture (layer separation, contract design, auth posture)
    *   Pass 2 — implementation details (validation, error handling, edge cases)
    *             + historical issue recurrence check
    *   Pass 3 — impact assessment + code complexity
@@ -137,11 +178,43 @@ export class CodeReviewer {
     codeContext: string,
     specFile?: string
   ): Promise<string> {
-    console.log(chalk.gray("  Pass 1/3: Architecture review..."));
+    // ── Pass 0: Spec Compliance (skip if no spec provided) ───────────────────
+    let complianceReview = "";
+    if (specContent && specContent.trim() && specContent !== "(No spec — review for general code quality)") {
+      console.log(chalk.gray("  Pass 0/3: Spec compliance check..."));
+      const compliancePrompt = `Check whether the implementation covers every requirement in the spec.
 
-    // ── Pass 1: Architecture ──────────────────────────────────────────────────
-    const archPrompt = `Review the architecture of this change.
+=== Feature Spec ===
+${specContent}
+
+=== Code ===
+${codeContext}`;
+      complianceReview = await this.provider.generate(compliancePrompt, specComplianceSystemPrompt);
+
+      // Surface compliance score immediately
+      const complianceScore = extractComplianceScore(complianceReview);
+      const missingCount = extractMissingCount(complianceReview);
+      if (complianceScore > 0) {
+        const scoreColor = complianceScore >= 8 ? chalk.green : complianceScore >= 6 ? chalk.yellow : chalk.red;
+        console.log(
+          chalk.gray("  Pass 0 result: ") +
+          scoreColor(`ComplianceScore ${complianceScore}/10`) +
+          (missingCount > 0 ? chalk.red(` · ${missingCount} missing requirement(s)`) : chalk.green(" · all requirements covered"))
+        );
+      }
+    }
 
+    console.log(chalk.gray(`  Pass 1/3: Architecture review...`));
+
+    // ── Pass 1: Architecture (+ §9 lessons cross-check) ──────────────────────
+    const accumulatedLessons = await loadAccumulatedLessons(this.projectRoot);
+    const archPrompt = `Review the architecture of this change.
+${complianceReview
+  ? `\n=== Spec Compliance Report (Pass 0 — already audited, do NOT re-audit missing requirements) ===\n${complianceReview}\n`
+  : ""}
+${accumulatedLessons
+  ? `\n=== §9 历史积累教训 (Accumulated Lessons — check if any are repeated in this code) ===\n${accumulatedLessons}\n`
+  : ""}
 === Feature Spec ===
 ${specContent || "(No spec — review for general code quality)"}
 
@@ -189,10 +262,14 @@ ${implReview}`;
 
     // ── Combine ───────────────────────────────────────────────────────────────
     const sep = "─".repeat(52);
-    const combined = `${archReview}\n\n${sep}\n\n${implReview}\n\n${sep}\n\n${impactReview}`;
+    const parts = complianceReview
+      ? [complianceReview, archReview, implReview, impactReview]
+      : [archReview, implReview, impactReview];
+    const combined = parts.join(`\n\n${sep}\n\n`);
 
     // ── Persist history ───────────────────────────────────────────────────────
     const score = extractScore(implReview) || extractScore(archReview);
+    const complianceScore = extractComplianceScore(complianceReview);
     const topIssues = extractTopIssues(implReview);
     const impactLevel = extractImpactLevel(impactReview);
     const complexityLevel = extractComplexityLevel(impactReview);
@@ -201,6 +278,7 @@ ${implReview}`;
         date: new Date().toISOString().slice(0, 10),
         specFile: path.relative(this.projectRoot, specFile),
         score,
+        ...(complianceScore > 0 ? { complianceScore } : {}),
         topIssues,
         ...(impactLevel ? { impactLevel } : {}),
         ...(complexityLevel ? { complexityLevel } : {}),

package/core/run-logger.ts

@@ -4,6 +4,86 @@ import chalk from "chalk";
 
 const LOG_DIR = ".ai-spec-logs";
 
+// ─── JSONL helpers ────────────────────────────────────────────────────────────
+// Each event is synchronously appended as one JSON line to a `.jsonl` shadow
+// file alongside the full `.json`. If the process crashes mid-run the `.json`
+// may be empty or stale, but every line written to the `.jsonl` is durable.
+// `loadRunLogs` (run-trend.ts) can reconstruct a RunLog from orphan `.jsonl`
+// files for crash recovery.
+
+function appendJsonlLine(filePath: string, record: Record<string, unknown>): void {
+  try {
+    fs.appendFileSync(filePath, JSON.stringify(record) + "\n");
+  } catch {
+    // JSONL write must never crash the pipeline
+  }
+}
+
+/** Reconstruct a RunLog from a `.jsonl` file (crash recovery path). */
+export function reconstructRunLogFromJsonl(jsonlPath: string): RunLog | null {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(jsonlPath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const log: Partial<RunLog> & { entries: LogEntry[]; filesWritten: string[]; errors: string[] } = {
+    entries: [],
+    filesWritten: [],
+    errors: [],
+    runId: "",
+    startedAt: "",
+    workingDir: "",
+  };
+
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const rec = JSON.parse(trimmed) as Record<string, unknown>;
+      switch (rec["type"]) {
+        case "header":
+          log.runId      = rec["runId"]      as string;
+          log.startedAt  = rec["startedAt"]  as string;
+          log.workingDir = rec["workingDir"] as string;
+          if (rec["provider"]) log.provider = rec["provider"] as string;
+          if (rec["model"])    log.model    = rec["model"]    as string;
+          if (rec["specPath"]) log.specPath  = rec["specPath"] as string;
+          break;
+        case "meta":
+          if (rec["key"] === "promptHash")  log.promptHash  = rec["value"] as string;
+          if (rec["key"] === "harnessScore") log.harnessScore = rec["value"] as number;
+          break;
+        case "entry":
+          log.entries.push({
+            ts: rec["ts"] as string,
+            event: rec["event"] as string,
+            ...(rec["durationMs"] !== undefined ? { durationMs: rec["durationMs"] as number } : {}),
+            ...(rec["data"] ? { data: rec["data"] as Record<string, unknown> } : {}),
+          });
+          break;
+        case "file":
+          if (rec["path"]) log.filesWritten.push(rec["path"] as string);
+          break;
+        case "error":
+          if (rec["message"]) log.errors.push(rec["message"] as string);
+          break;
+        case "footer":
+          if (rec["endedAt"])        log.endedAt        = rec["endedAt"]        as string;
+          if (rec["totalDurationMs"]) log.totalDurationMs = rec["totalDurationMs"] as number;
+          if (rec["harnessScore"])   log.harnessScore   = rec["harnessScore"]   as number;
+          break;
+      }
+    } catch {
+      // corrupt line — skip
+    }
+  }
+
+  if (!log.runId || !log.startedAt) return null;
+  return log as RunLog;
+}
+
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 export interface LogEntry {
@@ -42,6 +122,7 @@ export class RunLogger {
   private log: RunLog;
   private readonly startMs: number;
   private readonly logPath: string;
+  private readonly jsonlPath: string;
   private readonly stageStartMs = new Map<string, number>();
 
   constructor(
@@ -50,7 +131,8 @@ export class RunLogger {
     meta?: { provider?: string; model?: string; specPath?: string }
   ) {
     this.startMs = Date.now();
-    this.logPath = path.join(workingDir, LOG_DIR, `${runId}.json`);
+    this.logPath  = path.join(workingDir, LOG_DIR, `${runId}.json`);
+    this.jsonlPath = path.join(workingDir, LOG_DIR, `${runId}.jsonl`);
     this.log = {
       runId,
       startedAt: new Date().toISOString(),
@@ -60,6 +142,16 @@ export class RunLogger {
       filesWritten: [],
       errors: [],
     };
+    // Write JSONL header immediately — ensures the file exists even on early crash
+    fs.ensureDir(path.dirname(this.jsonlPath)).then(() => {
+      appendJsonlLine(this.jsonlPath, {
+        type: "header",
+        runId,
+        startedAt: this.log.startedAt,
+        workingDir,
+        ...meta,
+      });
+    }).catch(() => {});
     this.flush();
   }
 
@@ -78,25 +170,30 @@ export class RunLogger {
     const start = this.stageStartMs.get(event);
     const durationMs = start !== undefined ? Date.now() - start : undefined;
     this.push(`${event}:failed`, { ...data, error, durationMs });
-    this.log.errors.push(`[${event}] ${error}`);
+    const errorMsg = `[${event}] ${error}`;
+    this.log.errors.push(errorMsg);
+    appendJsonlLine(this.jsonlPath, { type: "error", message: errorMsg });
     this.flush();
   }
 
   /** Record the prompt hash for this run (call once at run start). */
   setPromptHash(hash: string): void {
     this.log.promptHash = hash;
+    appendJsonlLine(this.jsonlPath, { type: "meta", key: "promptHash", value: hash });
     this.flush();
   }
 
   /** Record the harness self-eval score (call once at run end). */
   setHarnessScore(score: number): void {
     this.log.harnessScore = score;
+    appendJsonlLine(this.jsonlPath, { type: "meta", key: "harnessScore", value: score });
     this.flush();
   }
 
   fileWritten(filePath: string): void {
     if (!this.log.filesWritten.includes(filePath)) {
       this.log.filesWritten.push(filePath);
+      appendJsonlLine(this.jsonlPath, { type: "file", path: filePath });
       this.flush();
     }
   }
@@ -104,6 +201,12 @@ export class RunLogger {
   finish(): void {
     this.log.endedAt = new Date().toISOString();
     this.log.totalDurationMs = Date.now() - this.startMs;
+    appendJsonlLine(this.jsonlPath, {
+      type: "footer",
+      endedAt: this.log.endedAt,
+      totalDurationMs: this.log.totalDurationMs,
+      harnessScore: this.log.harnessScore,
+    });
     this.flush();
   }
 
@@ -123,7 +226,10 @@ export class RunLogger {
   }
 
   private push(event: string, data?: Record<string, unknown>): void {
-    this.log.entries.push({ ts: new Date().toISOString(), event, ...( data ? { data } : {}) });
+    const entry: LogEntry = { ts: new Date().toISOString(), event, ...(data ? { data } : {}) };
+    this.log.entries.push(entry);
+    // Append to JSONL synchronously — durable even on crash
+    appendJsonlLine(this.jsonlPath, { type: "entry", ...entry });
     this.flush();
   }
 

package/core/run-trend.ts

@@ -1,7 +1,7 @@
 import * as fs from "fs-extra";
 import * as path from "path";
 import chalk from "chalk";
-import { RunLog } from "./run-logger";
+import { RunLog, reconstructRunLogFromJsonl } from "./run-logger";
 
 const LOG_DIR = ".ai-spec-logs";
 
@@ -49,20 +49,40 @@ export async function loadRunLogs(workingDir: string): Promise<RunLog[]> {
   if (!(await fs.pathExists(logDir))) return [];
 
   const files = await fs.readdir(logDir);
-  const jsonFiles = files.filter((f) => f.endsWith(".json")).sort().reverse();
+  const jsonFiles  = new Set(files.filter((f) => f.endsWith(".json")));
+  const jsonlFiles = files.filter((f) => f.endsWith(".jsonl")).sort().reverse();
 
   const logs: RunLog[] = [];
-  for (const file of jsonFiles) {
+  const seenRunIds = new Set<string>();
+
+  // Primary path: read complete .json files (newest-first)
+  for (const file of [...jsonFiles].sort().reverse()) {
     try {
       const log: RunLog = await fs.readJson(path.join(logDir, file));
-      // only include runs that have a startedAt (minimal validity check)
       if (log.runId && log.startedAt) {
         logs.push(log);
+        seenRunIds.add(log.runId);
       }
     } catch {
       // corrupt file — skip silently
     }
   }
+
+  // Crash-recovery path: reconstruct from orphan .jsonl files (no matching .json)
+  for (const file of jsonlFiles) {
+    const runId = file.replace(/\.jsonl$/, "");
+    if (seenRunIds.has(runId)) continue; // already loaded via .json
+    const correspondingJson = `${runId}.json`;
+    if (jsonFiles.has(correspondingJson)) continue; // .json exists, prefer it
+    const log = reconstructRunLogFromJsonl(path.join(logDir, file));
+    if (log) {
+      logs.push(log);
+      seenRunIds.add(log.runId);
+    }
+  }
+
+  // Sort newest-first by startedAt
+  logs.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
   return logs;
 }