@odavl/guardian 0.1.0-rc1 → 1.0.0

package/src/guardian/verdict.js

@@ -0,0 +1,320 @@
+/**
+ * Unified Verdict Builder
+ * Deterministic, explainable verdict and confidence scoring
+ */
+
+function clamp01(x) { return Math.max(0, Math.min(1, x)); }
+
+const isExecutedAttempt = (attempt) => attempt && attempt.outcome !== 'SKIPPED';
+
+function mapRunResultToVerdict(runResult) {
+  const r = (runResult || '').toUpperCase();
+  if (r === 'PASSED') return 'READY';
+  if (r === 'FAILED') return 'DO_NOT_LAUNCH';
+  if (r === 'INSUFFICIENT_EVIDENCE') return 'INSUFFICIENT_EVIDENCE';
+  return 'FRICTION'; // WARN or anything else
+}
+
+function computeCoverageScore(snapshot) {
+  const disc = snapshot.discovery || {};
+  if (disc.interactionsDiscovered && disc.interactionsDiscovered > 0) {
+    return clamp01((disc.interactionsExecuted || 0) / (disc.interactionsDiscovered || 1));
+  }
+  const attempts = snapshot.attempts || [];
+  const executedAttempts = attempts.filter(isExecutedAttempt);
+  const executed = executedAttempts.length;
+  return executed > 0 ? 1 : 0; // if we have executed attempts, consider coverage adequate
+}
+
+function computeEvidenceScore(snapshot) {
+  const e = snapshot.evidence || {};
+  const features = [
+    !!e.marketReportJson,
+    !!e.marketReportHtml,
+    !!e.traceZip,
+    !!(e.attemptArtifacts && Object.keys(e.attemptArtifacts).length > 0)
+  ];
+  const present = features.filter(Boolean).length;
+  return clamp01(present / features.length);
+}
+
+function computePenalty(snapshot) {
+  const attempts = snapshot.attempts || [];
+  const failures = attempts.filter(a => a.outcome === 'FAILURE').length;
+  const frictions = attempts.filter(a => a.outcome === 'FRICTION').length;
+  const perFailure = 0.15;
+  const perFriction = 0.1;
+  const raw = failures * perFailure + frictions * perFriction;
+  return Math.min(0.5, raw);
+}
+
+function levelFromScore(score) {
+  if (score >= 0.66) return 'high';
+  if (score >= 0.33) return 'medium';
+  return 'low';
+}
+
+function collectKeyFindings(snapshot) {
+  const findings = [];
+  const attempts = snapshot.attempts || [];
+  const executedAttempts = attempts.filter(a => a.outcome !== 'SKIPPED');
+  const skippedAttempts = attempts.filter(a => a.outcome === 'SKIPPED');
+  const successful = executedAttempts.filter(a => a.outcome === 'SUCCESS').length;
+  const failed = executedAttempts.filter(a => a.outcome === 'FAILURE').length;
+  const friction = executedAttempts.filter(a => a.outcome === 'FRICTION').length;
+
+  // Attempt outcomes
+  if (executedAttempts.length > 0) {
+    findings.push(`${successful} of ${executedAttempts.length} executed attempts completed`);
+    if (failed > 0) findings.push(`${failed} attempt did not complete`);
+    if (friction > 0) findings.push(`${friction} attempt showed friction (slower or rougher than baseline)`);
+    if (skippedAttempts.length > 0) {
+      findings.push(`${skippedAttempts.length} attempt was not executed`);
+    }
+  }
+
+  // Market impact
+  const mi = snapshot.marketImpactSummary || {};
+  const counts = mi.countsBySeverity || { CRITICAL: 0, WARNING: 0, INFO: 0 };
+  if (counts.CRITICAL > 0 || counts.WARNING > 0) {
+    findings.push(`${counts.CRITICAL} critical risk and ${counts.WARNING} warning risk identified`);
+  } else {
+    findings.push(`No critical or warning risks identified`);
+  }
+
+  // Discovery coverage
+  const disc = snapshot.discovery || {};
+  if ((disc.interactionsExecuted || 0) > 0) {
+    findings.push(`${disc.interactionsExecuted}/${disc.interactionsDiscovered || 0} discovered interactions executed`);
+  }
+
+  // Evidence
+  const e = snapshot.evidence || {};
+  const hasReports = !!(e.marketReportJson && e.marketReportHtml);
+  const hasTraces = !!e.traceZip;
+  const hasScreenshots = !!(e.attemptArtifacts && Object.keys(e.attemptArtifacts).length > 0);
+  const evidenceCount = [hasReports, hasTraces, hasScreenshots].filter(Boolean).length;
+  if (evidenceCount === 3) {
+    findings.push(`Complete evidence: reports, traces, and screenshots captured`);
+  } else if (evidenceCount > 0) {
+    findings.push(`Partial evidence: ${[hasReports && 'reports', hasTraces && 'traces', hasScreenshots && 'screenshots'].filter(Boolean).join(', ')}`);
+  }
+
+  return findings.slice(0, 7);
+}
+
+function collectEvidenceRefs(snapshot) {
+  const e = snapshot.evidence || {};
+  const reportPaths = [];
+  if (e.marketReportJson) reportPaths.push(e.marketReportJson);
+  if (e.marketReportHtml) reportPaths.push(e.marketReportHtml);
+  const traces = e.traceZip ? [e.traceZip] : [];
+  const screenshots = [];
+  if (e.attemptArtifacts) {
+    Object.values(e.attemptArtifacts).forEach(a => {
+      if (a.screenshotDir) screenshots.push(a.screenshotDir);
+    });
+  }
+  const affectedPages = (snapshot.discovery?.pagesVisited || []).slice(0, 10);
+  return { reportPaths, traces, screenshots, affectedPages };
+}
+
+function defaultLimits() {
+  return [
+    'Live-site variability may affect signals',
+    'Browser/viewport differences can change outcomes',
+    'Coverage limited to configured attempts and discovered interactions'
+  ];
+}
+
+function situationalLimits(snapshot) {
+  const limits = [];
+  const attempts = snapshot.attempts || [];
+  const skippedCount = attempts.filter(a => a.outcome === 'SKIPPED').length;
+  const disc = snapshot.discovery || {};
+
+  // Skipped attempts
+  if (skippedCount > 0) {
+    limits.push(`${skippedCount} additional attempt was not executed; verdict is therefore limited to fewer paths`);
+  }
+
+  // Discovery coverage gaps
+  const discovered = disc.interactionsDiscovered || 0;
+  const executed = disc.interactionsExecuted || 0;
+  if (discovered > 0 && executed < discovered) {
+    limits.push(`${discovered - executed} of ${discovered} discovered interactions were not tested`);
+  }
+
+  // Evidence gaps
+  const e = snapshot.evidence || {};
+  if (!e.traceZip) {
+    limits.push(`Detailed timing traces were not captured; timing-related issues may not be visible`);
+  }
+  if (!e.marketReportJson) {
+    limits.push(`Market risk analysis was not run; business impact is unassessed`);
+  }
+
+  // Environment variability
+  limits.push(`Live site behavior shifts over time; this verdict reflects this moment`);
+
+  // Browser/environment
+  limits.push(`Results are specific to this browser and viewport; other browsers may differ`);
+
+  return limits.slice(0, 6);
+}
+
+/**
+ * Build unified verdict from snapshot
+ */
+function deriveRunResult(snapshot) {
+  const meta = snapshot.meta || {};
+  if (meta.result) return meta.result;
+  const attempts = snapshot.attempts || [];
+  
+  // Count different outcome types
+  const executedAttempts = attempts.filter(a => a.outcome !== 'SKIPPED' && a.outcome !== 'NOT_APPLICABLE');
+  const discoveryFailedAttempts = attempts.filter(a => a.outcome === 'DISCOVERY_FAILED');
+  const notApplicableAttempts = attempts.filter(a => a.outcome === 'NOT_APPLICABLE');
+  const skippedCount = attempts.filter(a => a.outcome === 'SKIPPED').length;
+  
+  const executed = executedAttempts.length;
+  const successful = executedAttempts.filter(a => a.outcome === 'SUCCESS').length;
+  const failed = executedAttempts.filter(a => a.outcome === 'FAILURE').length;
+  
+  // If NOTHING executed (all skipped, not applicable, or discovery failed), it's insufficient
+  if (executed === 0 && (discoveryFailedAttempts.length > 0 || skippedCount > 0)) {
+    return 'INSUFFICIENT_EVIDENCE';
+  }
+  
+  if (executed === 0) return 'WARN';
+  if (failed === 0 && successful === executed) return 'PASSED';
+  if (failed === executed) return 'FAILED';
+  return 'WARN';
+}
+
+function buildVerdictExplanation(snapshot, verdictStr, executedCount, successCount, failureCount, skippedCount, evidenceScore, penaltyApplied) {
+  let why = '';
+  
+  if (verdictStr === 'READY') {
+    why = `All ${executedCount} executed attempts completed successfully without critical issues. `;
+    if (skippedCount > 0) {
+      why += `${skippedCount} additional attempt was not executed. `;
+    }
+    why += `Evidence is ${evidenceScore >= 0.75 ? 'complete' : 'sufficient'}. `;
+    why += `This differs from FRICTION because all attempts succeeded, and from DO_NOT_LAUNCH because no critical issues were found.`;
+  } else if (verdictStr === 'DO_NOT_LAUNCH') {
+    why = `${failureCount} critical issue was found, preventing safe launch. `;
+    why += `This differs from READY because critical issues must be resolved, and from FRICTION because severity exceeds acceptable limits.`;
+  } else if (verdictStr === 'INSUFFICIENT_EVIDENCE') {
+    why = `No meaningful attempts executed on this site. Most attempts were skipped (not applicable to site) or element discovery failed. `;
+    why += `This site may not match the tested user journeys, or it may be uninstrumented (missing expected UI elements/patterns). `;
+    why += `Verdict cannot be determined without successful execution of at least one relevant journey.`;
+  } else {
+    why = `Results show ${successCount} of ${executedCount} attempted success with some roughness. `;
+    if (failureCount > 0) {
+      why += `${failureCount} attempt did not complete. `;
+    }
+    why += `This differs from READY because outcomes were mixed, and from DO_NOT_LAUNCH because no critical failure was found.`;
+  }
+  
+  return why;
+}
+
+function deriveNextRunHint(snapshot, confidenceLevel) {
+  // Non-intrusive guard: suppress when confidence is high and limits are empty
+  const limits = situationalLimits(snapshot) || [];
+  if (confidenceLevel === 'high' && limits.length === 0) {
+    return null;
+  }
+
+  // (a) Evidence completeness
+  const e = snapshot.evidence || {};
+  const hasReports = !!(e.marketReportJson && e.marketReportHtml);
+  const hasTrace = !!e.traceZip;
+  const hasScreenshots = !!(e.attemptArtifacts && Object.keys(e.attemptArtifacts).length > 0);
+  if (!hasTrace || !hasScreenshots) {
+    return 'Capture additional evidence (e.g., traces) to strengthen timing and flow visibility.';
+  }
+
+  // (b) Coverage completeness
+  const disc = snapshot.discovery || {};
+  const discovered = disc.interactionsDiscovered || 0;
+  const executed = disc.interactionsExecuted || 0;
+  if (discovered > 0 && executed < discovered) {
+    return 'Expand coverage to include additional discovered interactions.';
+  }
+
+  // (c) Recurring timeouts/flakiness within this run
+  const attempts = snapshot.attempts || [];
+  const flows = snapshot.flows || [];
+  const timeoutRegex = /(timeout|timed out)/i;
+  const timeoutCount = (
+    attempts.filter(a => typeof a.error === 'string' && timeoutRegex.test(a.error)).length +
+    flows.filter(f => typeof f.error === 'string' && timeoutRegex.test(f.error)).length
+  );
+  const frictionCount = attempts.filter(a => a.friction && a.friction.isFriction).length;
+  if (timeoutCount >= 2 || frictionCount >= 2) {
+    return 'Use a conservative timeout profile to reduce flakiness.';
+  }
+
+  // (d) Otherwise: no hint
+  return null;
+}
+
+function buildVerdict(snapshot) {
+  const runRes = deriveRunResult(snapshot);
+  const verdictStr = mapRunResultToVerdict(runRes || 'WARN');
+
+  const outcomeScore = verdictStr === 'READY' ? 1 : verdictStr === 'DO_NOT_LAUNCH' ? 0.2 : 0.5;
+  const coverageScore = computeCoverageScore(snapshot); // 0..1
+  const evidenceScore = computeEvidenceScore(snapshot); // 0..1
+  const penalty = computePenalty(snapshot); // 0..0.5
+
+  const raw = 0.5 * outcomeScore + 0.2 * coverageScore + 0.3 * evidenceScore - penalty;
+  const score = clamp01(raw);
+  const level = levelFromScore(score);
+
+  // Detailed metrics for explanation
+  const attempts = snapshot.attempts || [];
+  const executedAttempts = attempts.filter(a => a.outcome !== 'SKIPPED');
+  const executedCount = executedAttempts.length;
+  const successCount = executedAttempts.filter(a => a.outcome === 'SUCCESS').length;
+  const failureCount = executedAttempts.filter(a => a.outcome === 'FAILURE').length;
+  const skippedCount = attempts.filter(a => a.outcome === 'SKIPPED').length;
+
+  const reasons = [];
+  if (successCount === executedCount && executedCount > 0) {
+    reasons.push(`All ${executedCount} executed attempts completed`);
+  } else if (successCount > 0) {
+    reasons.push(`${successCount} of ${executedCount} executed attempts completed`);
+  }
+  if (coverageScore > 0.66) reasons.push('Good coverage from discovered interactions');
+  if (evidenceScore >= 0.75) reasons.push('Complete evidence captured (reports, traces, screenshots)');
+  if (penalty > 0) reasons.push(`${failureCount > 0 ? 'Incomplete attempts' : 'Friction signals'} observed (${(penalty * 100).toFixed(0)}% impact)`);
+  // Do not include 'not executed' in drivers; it appears in findings/limits
+
+  const why = buildVerdictExplanation(
+    snapshot,
+    verdictStr,
+    executedCount,
+    successCount,
+    failureCount,
+    skippedCount,
+    evidenceScore,
+    penalty > 0
+  );
+
+  const nextRunHint = deriveNextRunHint(snapshot, level);
+
+  return {
+    verdict: verdictStr,
+    confidence: { level, score, reasons },
+    why,
+    keyFindings: collectKeyFindings(snapshot),
+    evidence: collectEvidenceRefs(snapshot),
+    limits: situationalLimits(snapshot),
+    nextRunHint
+  };
+}
+
+module.exports = { buildVerdict };

package/src/guardian/verdicts.js

@@ -0,0 +1,74 @@
+/**
+ * Verdict mapping utilities
+ * Canonical user-facing verdicts: READY, FRICTION, DO_NOT_LAUNCH
+ * Internal engine verdicts (legacy): OBSERVED, PARTIAL, INSUFFICIENT_DATA
+ */
+
+function toCanonicalVerdict(internalVerdict) {
+  switch (String(internalVerdict || '').toUpperCase()) {
+    // Internal engine verdicts
+    case 'OBSERVED':
+      return 'READY';
+    case 'PARTIAL':
+      return 'FRICTION';
+    case 'INSUFFICIENT_DATA':
+      return 'DO_NOT_LAUNCH';
+    // Synonyms from other components
+    case 'PASS':
+    case 'SUCCESS':
+      return 'READY';
+    case 'WARN':
+    case 'WARNING':
+    case 'FRICTION':
+      return 'FRICTION';
+    case 'FAIL':
+    case 'FAILURE':
+    case 'DO_NOT_LAUNCH':
+      return 'DO_NOT_LAUNCH';
+    default:
+      return 'DO_NOT_LAUNCH';
+  }
+}
+
+function toInternalVerdict(canonicalVerdict) {
+  switch (String(canonicalVerdict || '').toUpperCase()) {
+    case 'READY':
+      return 'OBSERVED';
+    case 'FRICTION':
+      return 'PARTIAL';
+    case 'DO_NOT_LAUNCH':
+      return 'INSUFFICIENT_DATA';
+    default:
+      return 'INSUFFICIENT_DATA';
+  }
+}
+
+function mapExitCodeFromCanonical(canonicalVerdict) {
+  switch (String(canonicalVerdict || '').toUpperCase()) {
+    case 'READY':
+      return 0;
+    case 'FRICTION':
+      return 1;
+    case 'DO_NOT_LAUNCH':
+    default:
+      return 2;
+  }
+}
+
+module.exports = { toCanonicalVerdict, toInternalVerdict, mapExitCodeFromCanonical };
+
+// Journey scan mapping (SAFE/RISK/DO_NOT_LAUNCH → canonical)
+function toCanonicalJourneyVerdict(journeyVerdict) {
+  switch (String(journeyVerdict || '').toUpperCase()) {
+    case 'SAFE':
+      return 'READY';
+    case 'RISK':
+      return 'FRICTION';
+    case 'DO_NOT_LAUNCH':
+      return 'DO_NOT_LAUNCH';
+    default:
+      return 'DO_NOT_LAUNCH';
+  }
+}
+
+module.exports.toCanonicalJourneyVerdict = toCanonicalJourneyVerdict;

package/src/guardian/wait-for-outcome.js

@@ -0,0 +1,120 @@
+/**
+ * Signal-based wait helper for actions.
+ * Prefers navigation/network/DOM quiet signals; falls back to bounded timeout.
+ */
+
+const DEFAULT_MAX_WAIT = 3500; // bounded cap
+const QUIET_WINDOW_MS = 300; // DOM must be quiet for this window
+
+async function waitForOutcome(page, options = {}) {
+  const {
+    actionType = 'click',
+    baseOrigin = null,
+    initialUrl = null,
+    expectNavigation = false,
+    includeUrlChange = true,
+    maxWait = DEFAULT_MAX_WAIT,
+  } = options;
+
+  let resolved = false;
+  const cleanupFns = [];
+
+  const resolveWith = (reason, details = {}) => {
+    if (resolved) return;
+    resolved = true;
+    cleanupFns.forEach((fn) => {
+      try { fn(); } catch {}
+    });
+    return { reason, details };
+  };
+
+  const tasks = [];
+  const start = Date.now();
+
+  // Navigation signal
+  if (expectNavigation) {
+    const navPromise = page.waitForNavigation({ timeout: maxWait }).then(() => resolveWith('navigation')).catch(() => {});
+    tasks.push(navPromise);
+  }
+
+  // URL change signal (even without full nav event)
+  if (expectNavigation && includeUrlChange && initialUrl) {
+    const urlPromise = page.waitForURL((u) => u !== initialUrl, { timeout: maxWait }).then(() => resolveWith('url-change')).catch(() => {});
+    tasks.push(urlPromise);
+  }
+
+  // Network signal: watch for POST/PUT same-origin
+  const networkPromise = new Promise((res) => {
+    const handler = (response) => {
+      try {
+        const req = response.request();
+        const method = (req.method() || '').toUpperCase();
+        const url = req.url();
+        const status = response.status();
+        const originOk = baseOrigin ? new URL(url).origin === baseOrigin : true;
+        if ((method === 'POST' || method === 'PUT') && originOk) {
+          const out = resolveWith('network', { method, status, url });
+          if (out) res(out);
+        }
+      } catch {}
+    };
+    page.on('response', handler);
+    cleanupFns.push(() => page.off('response', handler));
+  });
+  tasks.push(networkPromise);
+
+  // DOM quiet signal via MutationObserver
+  const domPromise = new Promise((res) => {
+    let lastMutation = Date.now();
+    let hasMutated = false;
+    const quietCheck = () => {
+      if (!hasMutated) return;
+      if (Date.now() - lastMutation >= QUIET_WINDOW_MS) {
+        const out = resolveWith('dom-quiet');
+        if (out) res(out);
+      }
+    };
+    const interval = setInterval(quietCheck, 80);
+    cleanupFns.push(() => clearInterval(interval));
+    page.evaluate(() => {
+      window.__guardianLastMutation = Date.now();
+      window.__guardianHasMutated = false;
+      if (window.__guardianDomObserver) {
+        try { window.__guardianDomObserver.disconnect(); } catch (e) {}
+      }
+      const obs = new MutationObserver(() => {
+        window.__guardianLastMutation = Date.now();
+        window.__guardianHasMutated = true;
+      });
+      obs.observe(document.documentElement || document.body, { childList: true, subtree: true, attributes: true, characterData: true });
+      window.__guardianDomObserver = obs;
+    }).catch(() => {});
+    const pollMutation = setInterval(async () => {
+      try {
+        const data = await page.evaluate(() => ({
+          last: window.__guardianLastMutation || Date.now(),
+          mutated: !!window.__guardianHasMutated
+        }));
+        lastMutation = data.last;
+        if (data.mutated) hasMutated = true;
+      } catch {}
+    }, 120);
+    cleanupFns.push(() => clearInterval(pollMutation));
+  });
+  tasks.push(domPromise);
+
+  // Bounded fallback
+  const timeoutPromise = new Promise((res) => {
+    const t = setTimeout(() => {
+      const out = resolveWith('timeout', { elapsedMs: Date.now() - start });
+      if (out) res(out);
+    }, maxWait);
+    cleanupFns.push(() => clearTimeout(t));
+  });
+  tasks.push(timeoutPromise);
+
+  const first = await Promise.race(tasks);
+  return first || { reason: 'timeout', details: { elapsedMs: maxWait } };
+}
+
+module.exports = { waitForOutcome };

package/src/guardian/watch-runner.js

@@ -0,0 +1,181 @@
+const fs = require('fs');
+const path = require('path');
+const { isCiMode } = require('./ci-mode');
+const { formatRunSummary } = require('./run-summary');
+
+const DEFAULT_DEBOUNCE_MS = 400;
+const DEFAULT_MAX_FILES = 5;
+
+function isIgnored(filePath, artifactsDir = './artifacts') {
+  const normalized = path.normalize(filePath);
+  const parts = normalized.split(path.sep).filter(Boolean);
+  const ignorePrefixes = [
+    'node_modules',
+    '.git',
+    '.odavl-guardian',
+    'dist',
+    'build'
+  ];
+  if (artifactsDir) {
+    ignorePrefixes.push(path.normalize(artifactsDir));
+  }
+  // Ignore any changes within artifacts directory (run outputs)
+  return parts.some(p => ignorePrefixes.includes(p));
+}
+
+function collectWatchPaths(config) {
+  const roots = [
+    'config',
+    'flows',
+    'policies',
+    'data',
+    'scripts',
+    'test'
+  ];
+
+  const seen = new Set();
+  const paths = [];
+  roots.forEach(p => {
+    const full = path.resolve(p);
+    if (seen.has(full)) return;
+    if (fs.existsSync(full)) {
+      seen.add(full);
+      paths.push(full);
+    }
+  });
+
+  return paths;
+}
+
+function formatChangedFiles(changed) {
+  if (!changed.length) return 'unknown';
+  const unique = Array.from(new Set(changed));
+  const shown = unique.slice(0, DEFAULT_MAX_FILES).map(f => path.relative(process.cwd(), f));
+  const more = unique.length - shown.length;
+  if (more > 0) {
+    shown.push(`… ${more} more`);
+  }
+  return shown.join(', ');
+}
+
+async function startWatchMode(config, deps = {}) {
+  const runReality = deps.runReality || require('./reality').executeReality;
+  const watchFactory = deps.watchFactory || fs.watch;
+  const debounceMs = deps.debounceMs || config.watchDebounceMs || DEFAULT_DEBOUNCE_MS;
+  const log = deps.log || console.log;
+  const warn = deps.warn || console.warn;
+  const exitFn = deps.exit || process.exit.bind(process);
+  const isCi = deps.isCi != null ? deps.isCi : isCiMode();
+  const onRunComplete = deps.onRunComplete || null;
+  const onWatcher = deps.onWatcher || null;
+  const bindSignal = deps.bindSignal || process.on.bind(process);
+
+  const quietConfig = {
+    ...config,
+    quiet: true,
+    flowOptions: { ...(config.flowOptions || {}), quiet: true }
+  };
+
+  if (isCi) {
+    warn('CI detected; --watch ignored');
+    const once = await runReality({ ...config, watch: false });
+    return { watchStarted: false, exitCode: once.exitCode };
+  }
+
+  let running = false;
+  let pending = false;
+  let stopped = false;
+  let debounceTimer = null;
+  let changedFiles = [];
+  let lastExitCode = 0;
+  const watchers = [];
+
+  const watchPaths = collectWatchPaths(config);
+
+  const runOnce = async (label) => {
+    if (stopped) return { exitCode: lastExitCode };
+    running = true;
+    const result = await runReality(quietConfig);
+    lastExitCode = result.exitCode || 0;
+    log(formatRunSummary({
+      flowResults: result.flowResults || [],
+      diffResult: result.diffResult || null,
+      baselineCreated: result.baselineCreated || false,
+      exitCode: lastExitCode
+    }, { label: 'Summary' }));
+    running = false;
+    if (onRunComplete) {
+      onRunComplete(result);
+    }
+    if (pending && !stopped) {
+      pending = false;
+      scheduleRun();
+    }
+    return result;
+  };
+
+  const scheduleRun = () => {
+    if (running) {
+      pending = true;
+      return;
+    }
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(() => {
+      const filesLabel = formatChangedFiles(changedFiles);
+      changedFiles = [];
+      log(`Change detected: ${filesLabel}`);
+      runOnce('change');
+    }, debounceMs);
+  };
+
+  const handleFsEvent = (basePath) => (event, filename) => {
+    if (stopped) return;
+    const candidate = filename ? path.join(basePath, filename) : basePath;
+    if (isIgnored(candidate, config.artifactsDir)) return;
+    changedFiles.push(candidate);
+    scheduleRun();
+  };
+
+  for (const p of watchPaths) {
+    try {
+      const watcher = watchFactory(p, { recursive: true }, handleFsEvent(p));
+      watchers.push(watcher);
+      if (onWatcher) onWatcher(watcher);
+    } catch (err) {
+      warn(`Watch attach failed for ${p}: ${err.message}`);
+    }
+  }
+
+  log('WATCH MODE: ON');
+  runOnce('initial').catch(err => {
+    warn(`Watch run failed: ${err.message}`);
+    running = false;
+  });
+
+  const stop = () => {
+    stopped = true;
+    if (debounceTimer) clearTimeout(debounceTimer);
+    watchers.forEach(w => {
+      try { if (w && typeof w.close === 'function') w.close(); } catch {}
+    });
+    return lastExitCode;
+  };
+
+  bindSignal('SIGINT', () => {
+    const code = stop();
+    exitFn(code);
+  });
+
+  return {
+    watchStarted: true,
+    stop,
+    getLastExitCode: () => lastExitCode,
+    simulateChange: (filePath) => handleFsEvent(path.dirname(filePath) || '.')("change", path.basename(filePath)),
+    isRunning: () => running,
+    hasPending: () => pending
+  };
+}
+
+module.exports = { startWatchMode, collectWatchPaths, isIgnored };