sentinelayer-cli 0.8.0 → 0.8.2

package/src/review/investor-dd-orchestrator.js

@@ -0,0 +1,405 @@
+/**
+ * Investor-DD top-level orchestrator (#investor-dd-5 / -16 / -18).
+ *
+ * Wires the file router, per-persona runner, and streaming event sink
+ * into a single entry point that the CLI `investor-dd` subcommand can
+ * call. Produces an artifact bundle under `<outputDir>/investor-dd/`:
+ *
+ *   plan.json          — router output: { personaId: filesInScope[] }
+ *   stream.ndjson      — full event stream from the run
+ *   persona-<id>.json  — per-persona findings + coverage proof
+ *   findings.json      — flat list across all personas (dedup in PR-29)
+ *   summary.json       — run metadata (timings, cost, terminationReason)
+ *   report.md          — human-readable summary
+ *   manifest.json      — SHA-256 chain of every artifact
+ *
+ * The orchestrator is reproducible: given the same repo state + routing
+ * rules, it produces the same artifacts and finding IDs. The LLM-driven
+ * layer (PR-IDD-<TBD>) sits on top and only activates when --ai is passed.
+ */
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+
+import { routeFilesToPersonas, summarizeRouting } from "./investor-dd-file-router.js";
+import { runAllPersonas } from "./investor-dd-persona-runner.js";
+import { createBudgetState } from "./investor-dd-file-loop.js";
+import { resolveInvestorDdBudget, INVESTOR_DD_ARTIFACT_SUBDIR } from "./investor-dd-config.js";
+import { runFullCompliancePack, COMPLIANCE_PACK_CATALOG } from "./compliance-pack.js";
+import { reconcileFindings, applyReportPolicy } from "./reconciliation-rules.js";
+import {
+  discoverInteractiveElements,
+  runLiveValidator,
+  buildObservationIndex,
+  createFindingObservationPair,
+} from "./live-validator.js";
+import { notifyRunCompleted } from "./investor-dd-notification.js";
+import { attachReproducibilityChain } from "./reproducibility-chain.js";
+import { renderInvestorDdHtml } from "./investor-dd-html-report.js";
+
+const INVESTOR_DD_PERSONAS = Object.freeze([
+  "security",
+  "backend",
+  "code-quality",
+  "testing",
+  "data-layer",
+  "reliability",
+  "release",
+  "observability",
+  "infrastructure",
+  "supply-chain",
+  "documentation",
+  "ai-governance",
+]);
+
+/**
+ * Walk the target repo and return a list of relative POSIX file paths.
+ * Skips common noise directories.
+ */
+async function walkRepoFiles(rootPath) {
+  const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "coverage",
+    ".sentinelayer",
+    ".next",
+    ".turbo",
+    "__pycache__",
+    ".pytest_cache",
+    ".venv",
+    "venv",
+  ]);
+  const SKIP_EXT = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".ico",
+    ".svg",
+    ".pdf",
+    ".zip",
+    ".tar",
+    ".gz",
+    ".mp4",
+    ".webm",
+    ".woff",
+    ".woff2",
+    ".ttf",
+  ]);
+
+  const results = [];
+  async function walk(absDir, relDir) {
+    let entries;
+    try {
+      entries = await fsp.readdir(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") && !entry.name.startsWith(".github")) {
+        if (entry.name !== ".gitignore" && entry.name !== ".env.example") continue;
+      }
+      const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
+      const absPath = path.join(absDir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await walk(absPath, relPath);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        if (SKIP_EXT.has(ext)) continue;
+        results.push(relPath);
+      }
+    }
+  }
+  await walk(rootPath, "");
+  return results;
+}
+
+async function writeJson(filePath, obj) {
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  await fsp.writeFile(filePath, JSON.stringify(obj, null, 2), "utf-8");
+}
+
+function sha256(text) {
+  return crypto.createHash("sha256").update(text).digest("hex");
+}
+
+/**
+ * Emit a summary markdown report. The detailed HTML/PDF variants are
+ * separate PRs (PR-IDD-18 follow-ups).
+ */
+function buildSummaryMarkdown({ runId, summary, routing, byPersona }) {
+  const lines = [];
+  lines.push(`# Investor-DD Report — ${runId}`);
+  lines.push("");
+  lines.push(`Generated: ${summary.startedAt}`);
+  lines.push(`Duration: ${summary.durationSeconds.toFixed(1)}s`);
+  lines.push(`Status: ${summary.terminationReason}`);
+  lines.push("");
+  lines.push("## Coverage");
+  lines.push("");
+  lines.push("| Persona | Files routed | Files visited | Findings |");
+  lines.push("|---|---:|---:|---:|");
+  for (const personaId of INVESTOR_DD_PERSONAS) {
+    const record = byPersona[personaId] || {};
+    const routed = (routing[personaId] || []).length;
+    const visited = Array.isArray(record.visited) ? record.visited.length : 0;
+    const findings = Array.isArray(record.findings) ? record.findings.length : 0;
+    lines.push(`| ${personaId} | ${routed} | ${visited} | ${findings} |`);
+  }
+  lines.push("");
+  lines.push("## Findings summary");
+  lines.push("");
+  const allFindings = Object.values(byPersona).flatMap((r) => r.findings || []);
+  const bySev = {};
+  for (const f of allFindings) {
+    const sev = f.severity || "UNKNOWN";
+    bySev[sev] = (bySev[sev] || 0) + 1;
+  }
+  for (const [sev, count] of Object.entries(bySev)) {
+    lines.push(`- **${sev}**: ${count}`);
+  }
+  lines.push("");
+  lines.push(`Total: ${allFindings.length}`);
+  return lines.join("\n");
+}
+
+/**
+ * Run the investor-DD orchestration end to end.
+ *
+ * @param {object} params
+ * @param {string} params.rootPath
+ * @param {string} [params.outputDir]            - Defaults to `<rootPath>/.sentinelayer/runs/<runId>`.
+ * @param {object} [params.budgetOptions]        - Overrides from CLI: { maxUsd, maxRuntimeMinutes, maxParallel }.
+ * @param {string[]} [params.personas]           - Override persona list; defaults to all 12.
+ * @param {Function} [params.onEvent]            - Extra event sink (NDJSON stream is always written).
+ * @param {boolean} [params.dryRun]              - If true, skip tool execution, emit plan.json + stub report only.
+ * @param {string[]|null} [params.compliancePacks]  - Compliance pack IDs to run (default: all seven).
+ * @param {object} [params.liveValidator]        - Optional live-web validator config.
+ * @param {object} [params.liveValidator.devTestBot]    - DevTestBot client.
+ * @param {object} [params.liveValidator.aidenid]       - AIdenID client.
+ * @param {number} [params.liveValidator.maxInteractions]
+ * @param {object} [params.notification]         - Optional notification config.
+ * @param {string} [params.notification.notifyEmail]
+ * @param {object} [params.notification.emailClient]
+ * @param {object} [params.notification.dashboardClient]
+ * @returns {Promise<{runId: string, artifactDir: string, summary: object}>}
+ */
+export async function runInvestorDd({
+  rootPath,
+  outputDir = "",
+  budgetOptions = {},
+  personas = INVESTOR_DD_PERSONAS,
+  onEvent = () => {},
+  dryRun = false,
+  compliancePacks = COMPLIANCE_PACK_CATALOG,
+  liveValidator = null,
+  notification = null,
+} = {}) {
+  if (!rootPath) throw new TypeError("runInvestorDd requires rootPath");
+
+  const runId = `investor-dd-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
+  const resolvedBudget = resolveInvestorDdBudget(budgetOptions);
+  const artifactBase = outputDir
+    ? path.resolve(outputDir, runId, INVESTOR_DD_ARTIFACT_SUBDIR)
+    : path.resolve(rootPath, ".sentinelayer", "runs", runId, INVESTOR_DD_ARTIFACT_SUBDIR);
+  await fsp.mkdir(artifactBase, { recursive: true });
+
+  const streamPath = path.join(artifactBase, "stream.ndjson");
+  const streamHandle = await fsp.open(streamPath, "w");
+
+  const emit = (event) => {
+    const enriched = { ...event, at: new Date().toISOString(), runId };
+    streamHandle.write(`${JSON.stringify(enriched)}\n`).catch(() => {});
+    try {
+      onEvent(enriched);
+    } catch {
+      // external sinks never break the run
+    }
+  };
+
+  const startTime = Date.now();
+  emit({ type: "investor_dd_start", rootPath, personas });
+
+  const files = await walkRepoFiles(rootPath);
+  emit({ type: "investor_dd_files_discovered", totalFiles: files.length });
+
+  const routing = routeFilesToPersonas({ files, personas });
+  const routingSummary = summarizeRouting(routing);
+  await writeJson(path.join(artifactBase, "plan.json"), {
+    runId,
+    rootPath,
+    personas,
+    routing,
+    routingSummary,
+    budget: resolvedBudget,
+  });
+
+  let byPersona = {};
+  let findings = [];
+  let terminationReason = "ok";
+  let reconciliationAvailable = false;
+  let compliance = null;
+
+  if (!dryRun) {
+    const budgetState = createBudgetState({
+      maxUsd: resolvedBudget.maxCostUsd,
+      maxRuntimeMs: resolvedBudget.maxRuntimeMinutes * 60_000,
+    });
+    const runResult = await runAllPersonas({
+      routing,
+      rootPath,
+      budget: budgetState,
+      onEvent: emit,
+    });
+    byPersona = runResult.byPersona;
+    findings = runResult.findings;
+    terminationReason = runResult.terminationReason;
+
+    // Compliance pack (Leila Farouk persona-adjacent dispatch). Deterministic,
+    // no LLM — an acquirer's auditor can re-run and get the same gap table.
+    emit({ type: "investor_dd_compliance_start" });
+    compliance = await runFullCompliancePack({
+      rootPath,
+      packs: Array.isArray(compliancePacks) ? compliancePacks : COMPLIANCE_PACK_CATALOG,
+    });
+    await writeJson(path.join(artifactBase, "compliance.json"), compliance);
+    emit({
+      type: "investor_dd_compliance_complete",
+      totalCovered: compliance.totalCovered,
+      totalGaps: compliance.totalGaps,
+    });
+
+    // Live-web validation (Jules): optional; only runs when both
+    // devTestBot + aidenid clients are supplied (pluggable contracts).
+    if (
+      liveValidator &&
+      liveValidator.devTestBot &&
+      liveValidator.aidenid
+    ) {
+      emit({ type: "investor_dd_live_start" });
+      const elements = await discoverInteractiveElements(rootPath);
+      await writeJson(path.join(artifactBase, "interaction-plan.json"), elements);
+      const live = await runLiveValidator({
+        runId,
+        elements,
+        devTestBot: liveValidator.devTestBot,
+        aidenid: liveValidator.aidenid,
+        maxInteractions: liveValidator.maxInteractions,
+        onEvent: emit,
+      });
+      await writeJson(path.join(artifactBase, "live-observations.json"), live);
+
+      // Reconciliation — pair each finding with a live observation and emit
+      // a verdict per finding. FALSE_POSITIVE findings are suppressed in
+      // the final finding list unless the caller keeps them for HITL.
+      const observationIndex = buildObservationIndex(live.observations);
+      const pairFn = createFindingObservationPair(observationIndex);
+      findings = reconcileFindings(findings, pairFn);
+      findings = findings.filter(
+        (f) => applyReportPolicy(f) !== "suppress",
+      );
+      reconciliationAvailable = true;
+      emit({
+        type: "investor_dd_live_complete",
+        observations: live.observations.length,
+        verdicts: findings.reduce((acc, f) => {
+          const v = f.reconciliation?.verdict || "UNVERIFIABLE";
+          acc[v] = (acc[v] || 0) + 1;
+          return acc;
+        }, {}),
+      });
+    }
+
+    // Reproducibility chain — attach a per-finding replay block + file
+    // SHA at finding time so each line in the report is re-verifiable.
+    findings = await attachReproducibilityChain({
+      findings,
+      rootPath,
+      runId,
+    });
+
+    await writeJson(path.join(artifactBase, "findings.json"), findings);
+    for (const [personaId, record] of Object.entries(byPersona)) {
+      await writeJson(path.join(artifactBase, `persona-${personaId}.json`), record);
+    }
+  } else {
+    emit({ type: "investor_dd_dry_run" });
+  }
+
+  const durationSeconds = (Date.now() - startTime) / 1000;
+  const summary = {
+    runId,
+    startedAt: new Date(startTime).toISOString(),
+    durationSeconds,
+    terminationReason,
+    totalFiles: files.length,
+    totalFindings: findings.length,
+    personas,
+    budget: resolvedBudget,
+    dryRun,
+    compliance: compliance
+      ? { totalCovered: compliance.totalCovered, totalGaps: compliance.totalGaps }
+      : null,
+    reconciliation: reconciliationAvailable,
+  };
+  await writeJson(path.join(artifactBase, "summary.json"), summary);
+
+  const markdown = buildSummaryMarkdown({ runId, summary, routing, byPersona });
+  const reportPath = path.join(artifactBase, "report.md");
+  await fsp.writeFile(reportPath, markdown, "utf-8");
+
+  const htmlReport = renderInvestorDdHtml({
+    runId,
+    summary,
+    routing,
+    byPersona,
+    findings,
+    compliance: compliance ? compliance.packs : null,
+  });
+  await fsp.writeFile(path.join(artifactBase, "report.html"), htmlReport, "utf-8");
+
+  emit({
+    type: "investor_dd_complete",
+    totalFindings: findings.length,
+    durationSeconds,
+    terminationReason,
+  });
+  await streamHandle.close();
+
+  const artifactFiles = await fsp.readdir(artifactBase);
+  const manifest = {};
+  for (const file of artifactFiles) {
+    const abs = path.join(artifactBase, file);
+    const stat = await fsp.stat(abs);
+    if (!stat.isFile()) continue;
+    const contents = await fsp.readFile(abs);
+    manifest[file] = {
+      sha256: sha256(contents),
+      bytes: stat.size,
+    };
+  }
+  await writeJson(path.join(artifactBase, "manifest.json"), manifest);
+
+  const runResult = { runId, artifactDir: artifactBase, summary, findings };
+
+  // Fire-and-forget notification dispatch (email + dashboard). Failures
+  // are non-fatal — the report is already persisted to disk + manifest.
+  if (notification && (notification.emailClient || notification.dashboardClient)) {
+    await notifyRunCompleted({
+      run: runResult,
+      notifyEmail: notification.notifyEmail,
+      emailClient: notification.emailClient,
+      dashboardClient: notification.dashboardClient,
+      emailEnabled: notification.emailEnabled !== false,
+      dashboardEnabled: notification.dashboardEnabled !== false,
+      onEvent: emit,
+    });
+  }
+
+  return runResult;
+}

package/src/review/investor-dd-persona-runner.js

@@ -0,0 +1,275 @@
+/**
+ * Unified per-persona runner for investor-DD (#investor-dd-4..15).
+ *
+ * Wires the 12 domain personas (security, backend, code-quality, testing,
+ * data-layer, reliability, release, observability, infrastructure,
+ * supply-chain, documentation, ai-governance) into the per-file review
+ * loop. Each persona dispatches its declared domain tools against every
+ * file the router assigns to it, collects findings, and returns a
+ * per-persona coverage proof.
+ *
+ * This runner runs the tool registries DETERMINISTICALLY — the agentic
+ * (LLM-driven) layer sits on top in a later PR. Determinism is the
+ * investor-DD ground-truth floor; the LLM layer is additive.
+ *
+ * Frontend (Jules) is excluded here because Jules has its own bespoke
+ * envelope with live-web validation; PR-25 routes Jules into investor-DD
+ * via a dedicated live-validator dispatcher.
+ */
+
+import { AI_GOVERNANCE_TOOLS } from "../agents/ai-governance/tools/index.js";
+import { BACKEND_TOOLS } from "../agents/backend/tools/index.js";
+import { CODE_QUALITY_TOOLS } from "../agents/code-quality/tools/index.js";
+import { DATA_LAYER_TOOLS } from "../agents/data-layer/tools/index.js";
+import { DOCUMENTATION_TOOLS } from "../agents/documentation/tools/index.js";
+import { INFRASTRUCTURE_TOOLS } from "../agents/infrastructure/tools/index.js";
+import { OBSERVABILITY_TOOLS } from "../agents/observability/tools/index.js";
+import { RELEASE_TOOLS } from "../agents/release/tools/index.js";
+import { RELIABILITY_TOOLS } from "../agents/reliability/tools/index.js";
+import { SECURITY_TOOLS } from "../agents/security/tools/index.js";
+import { SUPPLY_CHAIN_TOOLS } from "../agents/supply-chain/tools/index.js";
+import { TESTING_TOOLS } from "../agents/testing/tools/index.js";
+
+import { checkBudget, createBudgetState } from "./investor-dd-file-loop.js";
+
+/**
+ * Registry of persona → tool map. Frontend handled separately via Jules.
+ */
+export const INVESTOR_DD_PERSONA_TOOL_REGISTRY = Object.freeze({
+  security: SECURITY_TOOLS,
+  backend: BACKEND_TOOLS,
+  "code-quality": CODE_QUALITY_TOOLS,
+  testing: TESTING_TOOLS,
+  "data-layer": DATA_LAYER_TOOLS,
+  reliability: RELIABILITY_TOOLS,
+  release: RELEASE_TOOLS,
+  observability: OBSERVABILITY_TOOLS,
+  infrastructure: INFRASTRUCTURE_TOOLS,
+  "supply-chain": SUPPLY_CHAIN_TOOLS,
+  documentation: DOCUMENTATION_TOOLS,
+  "ai-governance": AI_GOVERNANCE_TOOLS,
+});
+
+export const INVESTOR_DD_PERSONA_IDS = Object.freeze(
+  Object.keys(INVESTOR_DD_PERSONA_TOOL_REGISTRY),
+);
+
+/**
+ * Resolve the tool list for a given persona.
+ *
+ * @param {string} personaId
+ * @returns {Array<{id: string, handler: Function, description: string}>}
+ */
+export function getPersonaTools(personaId) {
+  const map = INVESTOR_DD_PERSONA_TOOL_REGISTRY[personaId];
+  if (!map) return [];
+  return Object.values(map);
+}
+
+/**
+ * Dispatch every tool for the persona against a single file scope. Each
+ * tool handler is invoked with `{ rootPath, files: [file] }` because
+ * every persona's tool contract accepts this shape (see #A13-#A22).
+ *
+ * @param {object} params
+ * @param {string} params.personaId
+ * @param {string} params.file            - Single file (relative to rootPath).
+ * @param {string} params.rootPath        - Repo root.
+ * @param {object} params.budget          - Shared budget state.
+ * @param {Function} [params.onEvent]
+ * @returns {Promise<{findings: Array, toolInvocations: Array, stoppedEarly: boolean}>}
+ */
+export async function runPersonaOnFile({
+  personaId,
+  file,
+  rootPath,
+  budget,
+  onEvent = () => {},
+} = {}) {
+  if (!personaId) throw new TypeError("runPersonaOnFile requires personaId");
+  if (!file) throw new TypeError("runPersonaOnFile requires file");
+  if (!rootPath) throw new TypeError("runPersonaOnFile requires rootPath");
+
+  const tools = getPersonaTools(personaId);
+  const findings = [];
+  const toolInvocations = [];
+  let stoppedEarly = false;
+
+  for (const tool of tools) {
+    const budgetCheck = checkBudget(budget);
+    if (!budgetCheck.ok) {
+      stoppedEarly = true;
+      onEvent({
+        type: "persona_tool_skipped",
+        personaId,
+        file,
+        tool: tool.id,
+        stopReason: budgetCheck.reason,
+      });
+      continue;
+    }
+
+    onEvent({ type: "persona_file_tool_call", personaId, file, tool: tool.id });
+
+    try {
+      const results = await tool.handler({ rootPath, files: [file] });
+      if (budget) budget.toolCalls = (budget.toolCalls || 0) + 1;
+      const normalized = Array.isArray(results) ? results : [];
+      for (const f of normalized) {
+        const decorated = {
+          ...f,
+          personaId,
+          tool: tool.id,
+          file: f.file || file,
+        };
+        findings.push(decorated);
+        onEvent({ type: "persona_finding", personaId, file, tool: tool.id, finding: decorated });
+      }
+      toolInvocations.push({ tool: tool.id, findings: normalized.length });
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      onEvent({
+        type: "persona_tool_error",
+        personaId,
+        file,
+        tool: tool.id,
+        stopReason: errorMessage,
+      });
+      toolInvocations.push({ tool: tool.id, error: errorMessage });
+    }
+  }
+
+  return { findings, toolInvocations, stoppedEarly };
+}
+
+/**
+ * Run a single persona across its assigned files in the router output.
+ *
+ * @param {object} params
+ * @param {string} params.personaId
+ * @param {string[]} params.files
+ * @param {string} params.rootPath
+ * @param {object} params.budget
+ * @param {Function} [params.onEvent]
+ * @returns {Promise<{personaId: string, perFile: Array, findings: Array, visited: string[], skipped: string[], terminationReason: string}>}
+ */
+export async function runPersonaAcrossFiles({
+  personaId,
+  files,
+  rootPath,
+  budget,
+  onEvent = () => {},
+} = {}) {
+  if (!Array.isArray(files)) throw new TypeError("runPersonaAcrossFiles requires files array");
+  const safeBudget = budget || createBudgetState();
+  const perFile = [];
+  const allFindings = [];
+  const visited = [];
+  const skipped = [];
+  let terminationReason = "ok";
+
+  for (const file of files) {
+    const budgetCheck = checkBudget(safeBudget);
+    if (!budgetCheck.ok) {
+      terminationReason = budgetCheck.reason;
+      skipped.push(file);
+      onEvent({ type: "persona_file_skipped", personaId, file, stopReason: budgetCheck.reason });
+      continue;
+    }
+
+    onEvent({ type: "persona_file_start", personaId, file });
+    const { findings, toolInvocations, stoppedEarly } = await runPersonaOnFile({
+      personaId,
+      file,
+      rootPath,
+      budget: safeBudget,
+      onEvent,
+    });
+    perFile.push({ file, findings, toolInvocations, stoppedEarly });
+    allFindings.push(...findings);
+    visited.push(file);
+    onEvent({
+      type: "persona_file_complete",
+      personaId,
+      file,
+      findingCount: findings.length,
+      toolCount: toolInvocations.length,
+    });
+  }
+
+  return {
+    personaId,
+    perFile,
+    findings: allFindings,
+    visited,
+    skipped,
+    terminationReason,
+  };
+}
+
+/**
+ * Run every persona in the supplied routing table in sequence. Each
+ * persona's runtime is bounded by the shared budget; when the budget
+ * trips, remaining personas (and remaining files within the current
+ * persona) are marked `skipped` so the partial-report generator can
+ * still emit what finished.
+ *
+ * @param {object} params
+ * @param {Record<string, string[]>} params.routing - { personaId: filesInScope[] }
+ * @param {string} params.rootPath
+ * @param {object} params.budget
+ * @param {Function} [params.onEvent]
+ * @returns {Promise<{byPersona: Record<string, object>, findings: Array, terminationReason: string}>}
+ */
+export async function runAllPersonas({
+  routing = {},
+  rootPath,
+  budget,
+  onEvent = () => {},
+} = {}) {
+  if (!rootPath) throw new TypeError("runAllPersonas requires rootPath");
+  const safeBudget = budget || createBudgetState();
+  const byPersona = {};
+  const allFindings = [];
+  let terminationReason = "ok";
+
+  for (const [personaId, files] of Object.entries(routing)) {
+    const budgetCheck = checkBudget(safeBudget);
+    if (!budgetCheck.ok) {
+      terminationReason = budgetCheck.reason;
+      byPersona[personaId] = {
+        personaId,
+        perFile: [],
+        findings: [],
+        visited: [],
+        skipped: [...files],
+        terminationReason: budgetCheck.reason,
+      };
+      onEvent({ type: "persona_skipped", personaId, stopReason: budgetCheck.reason });
+      continue;
+    }
+
+    onEvent({ type: "persona_start", personaId, fileCount: files.length });
+    const result = await runPersonaAcrossFiles({
+      personaId,
+      files,
+      rootPath,
+      budget: safeBudget,
+      onEvent,
+    });
+    byPersona[personaId] = result;
+    allFindings.push(...result.findings);
+    if (result.terminationReason !== "ok" && terminationReason === "ok") {
+      terminationReason = result.terminationReason;
+    }
+    onEvent({
+      type: "persona_complete",
+      personaId,
+      findingCount: result.findings.length,
+      visitedCount: result.visited.length,
+      skippedCount: result.skipped.length,
+    });
+  }
+
+  return { byPersona, findings: allFindings, terminationReason };
+}