argusqa-os 9.5.5 → 9.6.0

package/src/utils/har-recorder.js

@@ -0,0 +1,197 @@
+/**
+ * ARGUS HAR Network Baseline Recorder (Sprint 5 — N1)
+ *
+ * Records all network requests made during a page load as a HAR-style
+ * baseline. On first run, saves the baseline. On subsequent runs, diffs
+ * the current requests against the baseline and surfaces regressions:
+ * new requests, missing requests, and status-code changes.
+ *
+ * This isolates frontend bugs from backend noise: if a finding appears
+ * only when the request set has changed, it is likely environment-specific.
+ *
+ * Findings emitted:
+ *   har_baseline_created   — info, first run: baseline saved
+ *   har_new_request        — warning: request not in baseline
+ *   har_missing_request    — warning: baseline request no longer made
+ *   har_status_changed     — warning/critical: HTTP status differs from baseline
+ *   har_comparison_summary — info, always emitted
+ *
+ * Baseline stored at: {REPORT_OUTPUT_DIR}/baselines/har/{slug}.json
+ */
+
+import fs                    from 'fs';
+import path                  from 'path';
+import { registerExpensive } from '../registry.js';
+import { childLogger }       from './logger.js';
+import { slugify }           from './slug.js';
+import { config }            from '../config/targets.js';
+
+const logger  = childLogger('har-recorder');
+const HAR_DIR = path.join(config.outputDir, 'baselines', 'har');
+
+// Normalise a URL for baseline keying — strip query strings that vary per run
+// (cache-busters, tokens) to reduce false-positive "new request" findings.
+function normaliseUrl(rawUrl) {
+  try {
+    const u = new URL(rawUrl);
+    // Keep only stable query params — drop ones that look like cache-busters
+    const stable = new URLSearchParams();
+    for (const [k, v] of u.searchParams) {
+      if (/^(v|ver|version|_|cb|bust|ts|t)$/i.test(k)) continue;
+      stable.set(k, v);
+    }
+    u.search = stable.toString();
+    return u.toString();
+  } catch {
+    return rawUrl;
+  }
+}
+
+function toBaselineEntry(req) {
+  return {
+    request:  { method: req.method ?? 'GET', url: normaliseUrl(req.url) },
+    response: { status: req.status ?? 0 },
+  };
+}
+
+export async function analyzeHar(browser, url, opts = {}) {
+  const harDir = opts.baselineDir ?? HAR_DIR;
+  const findings = [];
+
+  try {
+    await browser.navigate(url);
+    await browser.waitFor({ state: 'networkidle' }).catch(() => {});
+    await new Promise(r => setTimeout(r, 600));
+  } catch {
+    return findings;
+  }
+
+  // ── Capture current network requests ─────────────────────────────────────
+  let requests = [];
+  try {
+    requests = await browser.listNetwork();
+  } catch (err) {
+    logger.warn(`[ARGUS] har-recorder: listNetwork failed for ${url}: ${err.message}`);
+    return findings;
+  }
+
+  const slug    = slugify(url);
+  const harFile = path.join(harDir, `${slug}.json`);
+
+  // ── First run: save baseline ──────────────────────────────────────────────
+  // Use flag:'wx' for atomic create — throws EEXIST if baseline already exists (TOCTOU-safe).
+  fs.mkdirSync(harDir, { recursive: true });
+  const baseline = {
+    version: '1.2',
+    createdAt: new Date().toISOString(),
+    url,
+    entries: requests.map(toBaselineEntry),
+  };
+  let harIsNew = false;
+  try {
+    fs.writeFileSync(harFile, JSON.stringify(baseline, null, 2), { flag: 'wx' });
+    harIsNew = true;
+  } catch (err) {
+    if (err.code !== 'EEXIST') {
+      logger.warn(`[ARGUS] har-recorder: failed to write baseline: ${err.message}`);
+      return findings;
+    }
+  }
+  if (harIsNew) {
+
+    findings.push({
+      type:         'har_baseline_created',
+      message:      `HAR baseline saved for ${url} (${requests.length} requests recorded)`,
+      requestCount: requests.length,
+      baselineFile: harFile,
+      severity:     'info',
+      url,
+    });
+    return findings;
+  }
+
+  // ── Subsequent runs: compare against baseline ─────────────────────────────
+  let existingBaseline;
+  try {
+    existingBaseline = JSON.parse(fs.readFileSync(harFile, 'utf8'));
+  } catch (err) {
+    logger.warn(`[ARGUS] har-recorder: failed to read baseline: ${err.message}`);
+    return findings;
+  }
+
+  const baselineEntries = existingBaseline.entries ?? [];
+  const baselineMap     = new Map(baselineEntries.map(e => [normaliseUrl(e.request.url), e]));
+  const currentMap      = new Map(requests.map(r => [normaliseUrl(r.url), r]));
+
+  let newCount = 0, missingCount = 0, changedCount = 0;
+
+  // New requests not in baseline
+  for (const [normUrl, req] of currentMap) {
+    if (!baselineMap.has(normUrl)) {
+      newCount++;
+      findings.push({
+        type:       'har_new_request',
+        message:    `New network request not in baseline: ${req.method ?? 'GET'} ${normUrl}`,
+        method:     req.method ?? 'GET',
+        requestUrl: normUrl,
+        status:     req.status ?? 0,
+        severity:   'warning',
+        url,
+      });
+    }
+  }
+
+  // Baseline requests no longer made
+  for (const [normUrl, entry] of baselineMap) {
+    if (!currentMap.has(normUrl)) {
+      missingCount++;
+      findings.push({
+        type:       'har_missing_request',
+        message:    `Baseline request no longer made: ${entry.request.method} ${normUrl}`,
+        method:     entry.request.method,
+        requestUrl: normUrl,
+        severity:   'warning',
+        url,
+      });
+    }
+  }
+
+  // Status code regressions
+  for (const [normUrl, req] of currentMap) {
+    const base = baselineMap.get(normUrl);
+    if (!base) continue;
+    const baseStatus = base.response.status;
+    const currStatus = req.status ?? 0;
+    if (baseStatus !== currStatus && currStatus > 0 && baseStatus > 0) {
+      changedCount++;
+      findings.push({
+        type:           'har_status_changed',
+        message:        `HTTP status changed for ${normUrl}: ${baseStatus} → ${currStatus}`,
+        requestUrl:     normUrl,
+        baselineStatus: baseStatus,
+        currentStatus:  currStatus,
+        severity:       currStatus >= 400 ? 'critical' : 'warning',
+        url,
+      });
+    }
+  }
+
+  findings.push({
+    type:            'har_comparison_summary',
+    message:         `HAR diff: ${newCount} new, ${missingCount} missing, ${changedCount} status-changed (${requests.length} total vs ${baselineEntries.length} baseline)`,
+    newRequests:     newCount,
+    missingRequests: missingCount,
+    statusChanges:   changedCount,
+    totalCurrent:    requests.length,
+    totalBaseline:   baselineEntries.length,
+    severity:        'info',
+    url,
+  });
+
+  return findings;
+}
+
+registerExpensive({
+  name:    'har-recorder',
+  analyze: (browser, url) => analyzeHar(browser, url),
+});

package/src/utils/motion-analyzer.js

@@ -0,0 +1,243 @@
+/**
+ * ARGUS Motion & Animation Accessibility Analyzer (Sprint 5b — A9)
+ *
+ * Detects pages that trigger motion/animation without respecting the user's
+ * `prefers-reduced-motion` OS preference — a WCAG 2.1 SC 2.3.3 (AAA) violation
+ * that can trigger vestibular disorders in motion-sensitive users.
+ *
+ * Findings emitted:
+ *   motion_no_reduced_motion_query — CSS animation/transition present but no
+ *     @media (prefers-reduced-motion) query anywhere in page stylesheets
+ *   motion_autoplay_no_pause       — <video autoplay> without visible pause control
+ *     or animated <img> (GIF/APNG/WebP) without pause mechanism
+ *   motion_interactive_animation   — transition/animation on interactive elements
+ *     (button, a, input, [role=button]) without a reduced-motion override
+ *   motion_reduced_not_honoured    — after emulating prefers-reduced-motion: reduce,
+ *     animated properties are still applied (requires MCP emulate support)
+ *   motion_summary                 — info, always emitted
+ */
+
+import { registerExpensive } from '../registry.js';
+import { unwrapEval }        from './mcp-client.js';
+import { childLogger }       from './logger.js';
+import { thresholds }        from '../config/targets.js';
+
+const logger = childLogger('motion-analyzer');
+
+// Threshold: flag animated interactive elements even if count is 1
+const ANIM_COUNT_THRESHOLD = thresholds.motion?.animationPropertyCount ?? 1;
+
+// ── In-browser motion analysis script ────────────────────────────────────────
+const MOTION_SCRIPT = `() => {
+  var result = {
+    hasAnimation:        false,
+    hasReducedQuery:     false,
+    interactiveAnimated: [],
+    autoplayVideos:      [],
+    animatedImages:      [],
+  };
+
+  var INTERACTIVE = ['button','a','input','select','textarea'];
+  var ANIM_PROPS  = ['animation','animation-name','transition'];
+
+  // Scan all accessible stylesheets
+  var sheets = Array.from(document.styleSheets);
+  for (var i = 0; i < sheets.length; i++) {
+    var sheet = sheets[i];
+    var rules;
+    try { rules = Array.from(sheet.cssRules || []); } catch { continue; }
+    for (var j = 0; j < rules.length; j++) {
+      var rule = rules[j];
+      // Check for @media (prefers-reduced-motion)
+      if (rule.type === CSSRule.MEDIA_RULE) {
+        var condText = rule.conditionText || rule.media && rule.media.mediaText || '';
+        if (/prefers-reduced-motion/i.test(condText)) {
+          result.hasReducedQuery = true;
+        }
+      }
+      // Check style rules for animation/transition
+      if (rule.type === CSSRule.STYLE_RULE && rule.style) {
+        var anim = rule.style.animationName || rule.style.animation;
+        var trans = rule.style.transition;
+        if ((anim && anim !== 'none' && anim !== '') ||
+            (trans && trans !== 'none' && trans !== '')) {
+          result.hasAnimation = true;
+          // Check if selector matches an interactive element
+          var sel = rule.selectorText || '';
+          var isInteractive = INTERACTIVE.some(function(tag) {
+            return sel.indexOf(tag) !== -1 || sel.indexOf('[role="button"]') !== -1;
+          });
+          if (isInteractive) {
+            result.interactiveAnimated.push({
+              selector:  sel.slice(0, 120),
+              animation: anim || '',
+              transition: trans || '',
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // Check for autoplay video without pause control
+  var videos = Array.from(document.querySelectorAll('video[autoplay]'));
+  for (var v = 0; v < videos.length; v++) {
+    var vid = videos[v];
+    result.autoplayVideos.push({
+      src:      (vid.src || vid.currentSrc || '').slice(0, 100),
+      hasMuted: vid.muted || vid.hasAttribute('muted'),
+      hasControls: vid.controls || vid.hasAttribute('controls'),
+    });
+  }
+
+  // Check for animated images (GIF/APNG) without pause mechanism
+  var imgs = Array.from(document.querySelectorAll('img'));
+  for (var k = 0; k < imgs.length; k++) {
+    var src = imgs[k].src || '';
+    if (/\\.gif$/i.test(src) || /\\.apng$/i.test(src)) {
+      result.animatedImages.push({ src: src.slice(0, 100) });
+    }
+  }
+
+  return JSON.stringify(result);
+}`;
+
+// ── Post-emulation check: do animations still run under reduced motion? ───────
+const REDUCED_MOTION_CHECK = `() => {
+  var result = { stillAnimated: [] };
+  var sheets = Array.from(document.styleSheets);
+  for (var i = 0; i < sheets.length; i++) {
+    var rules;
+    try { rules = Array.from(sheets[i].cssRules || []); } catch { continue; }
+    for (var j = 0; j < rules.length; j++) {
+      var rule = rules[j];
+      if (rule.type === CSSRule.STYLE_RULE && rule.style) {
+        var anim  = rule.style.animationName || rule.style.animation;
+        var trans = rule.style.transition;
+        if ((anim && anim !== 'none') || (trans && trans !== 'none')) {
+          result.stillAnimated.push({ selector: (rule.selectorText || '').slice(0, 80) });
+        }
+      }
+    }
+  }
+  return JSON.stringify(result);
+}`;
+
+export async function analyzeMotion(browser, url) {
+  const findings = [];
+
+  try {
+    await browser.navigate(url);
+    await browser.waitFor({ state: 'networkidle' }).catch(() => {});
+    await new Promise(r => setTimeout(r, 400));
+  } catch {
+    return findings;
+  }
+
+  // ── 1. Run CSS + DOM motion analysis ─────────────────────────────────────
+  let data = null;
+  try {
+    const raw = await browser.evaluate(MOTION_SCRIPT);
+    const s   = unwrapEval(raw);
+    data = typeof s === 'object' ? s : JSON.parse(s);
+  } catch (err) {
+    logger.warn(`[ARGUS] motion-analyzer: analysis failed for ${url}: ${err.message}`);
+    data = { hasAnimation: false, hasReducedQuery: false, interactiveAnimated: [], autoplayVideos: [], animatedImages: [] };
+  }
+
+  // Finding: animation without prefers-reduced-motion query
+  if (data.hasAnimation && !data.hasReducedQuery) {
+    findings.push({
+      type:     'motion_no_reduced_motion_query',
+      message:  'CSS animation/transition in use but no @media (prefers-reduced-motion) query found in any stylesheet',
+      severity: 'warning',
+      url,
+    });
+  }
+
+  // Finding: autoplay video without pause control
+  for (const vid of (data.autoplayVideos ?? [])) {
+    if (!vid.hasControls) {
+      findings.push({
+        type:     'motion_autoplay_no_pause',
+        message:  `<video autoplay> without visible pause controls: ${vid.src || '(no src)'}`,
+        src:      vid.src,
+        hasMuted: vid.hasMuted,
+        severity: 'warning',
+        url,
+      });
+    }
+  }
+
+  // Finding: animated GIFs without pause
+  for (const img of (data.animatedImages ?? [])) {
+    findings.push({
+      type:     'motion_autoplay_no_pause',
+      message:  `Animated image (GIF/APNG) without pause mechanism: ${img.src}`,
+      src:      img.src,
+      severity: 'info',
+      url,
+    });
+  }
+
+  // Finding: interactive elements with animation/transition
+  const interactiveCount = (data.interactiveAnimated ?? []).length;
+  if (interactiveCount >= ANIM_COUNT_THRESHOLD) {
+    for (const el of data.interactiveAnimated.slice(0, 10)) {
+      findings.push({
+        type:       'motion_interactive_animation',
+        message:    `Interactive element has animation/transition without prefers-reduced-motion override: ${el.selector}`,
+        selector:   el.selector,
+        animation:  el.animation,
+        transition: el.transition,
+        severity:   'warning',
+        url,
+      });
+    }
+  }
+
+  // ── 2. Emulate prefers-reduced-motion: reduce and re-check ───────────────
+  try {
+    await browser.emulateReducedMotion('reduce');
+    await new Promise(r => setTimeout(r, 300));
+    const raw2 = await browser.evaluate(REDUCED_MOTION_CHECK);
+    const s2   = unwrapEval(raw2);
+    const d2   = typeof s2 === 'object' ? s2 : JSON.parse(s2);
+    if (Array.isArray(d2.stillAnimated) && d2.stillAnimated.length > 0 && !data.hasReducedQuery) {
+      findings.push({
+        type:     'motion_reduced_not_honoured',
+        message:  `${d2.stillAnimated.length} animated element(s) still animate after emulating prefers-reduced-motion: reduce`,
+        count:    d2.stillAnimated.length,
+        severity: 'warning',
+        url,
+      });
+    }
+    // Reset emulation
+    await browser.emulateReducedMotion('no-preference').catch(() => {});
+  } catch {
+    // Emulation not supported in this Chrome/MCP build — skip gracefully
+  }
+
+  // ── 3. Summary — always emitted ──────────────────────────────────────────
+  const animCount    = interactiveCount;
+  const autoplayCount = (data.autoplayVideos ?? []).filter(v => !v.hasControls).length +
+                        (data.animatedImages ?? []).length;
+
+  findings.push({
+    type:          'motion_summary',
+    hasAnimation:  data.hasAnimation,
+    hasReducedQuery: data.hasReducedQuery,
+    animationCount: animCount,
+    autoplayCount,
+    message:       `Motion: animation=${data.hasAnimation}, reducedMotionQuery=${data.hasReducedQuery}, interactiveAnimated=${animCount}, autoplay=${autoplayCount}`,
+    severity:      'info',
+    url,
+  });
+
+  return findings;
+}
+
+registerExpensive({
+  name:    'motion',
+  analyze: (browser, url) => analyzeMotion(browser, url),
+});

package/src/utils/pr-diff-analyzer.js

@@ -0,0 +1,121 @@
+/**
+ * PR Diff Analyzer — maps GitHub PR changed files to affected Argus routes.
+ *
+ * parsePrUrl(prUrl)               → { owner, repo, prNumber }
+ * fetchPrFiles(prUrl, token)      → string[] of changed file paths
+ * mapFilesToRoutes(files, routes) → Route[] subset likely affected by the diff
+ *
+ * Pure functions + one async fetch — no Chrome, no MCP, no AI verdict.
+ * AI verdict logic ships separately in the private argus-pro repo.
+ */
+
+/**
+ * Parse a GitHub PR URL into its owner/repo/prNumber components.
+ *
+ * Accepted formats:
+ *   https://github.com/owner/repo/pull/123
+ *   https://github.com/owner/repo/pull/123/files
+ *
+ * @param {string} prUrl
+ * @returns {{ owner: string, repo: string, prNumber: number }}
+ */
+export function parsePrUrl(prUrl) {
+  const match = String(prUrl).match(
+    /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/,
+  );
+  if (!match) throw new Error(`Invalid GitHub PR URL: ${prUrl}`);
+  return { owner: match[1], repo: match[2], prNumber: parseInt(match[3], 10) };
+}
+
+/**
+ * Fetch the list of file paths changed by a GitHub pull request (up to 100 files).
+ *
+ * @param {string} prUrl        - GitHub PR URL (any format accepted by parsePrUrl)
+ * @param {string} [githubToken] - GitHub token; omit for public repos
+ * @returns {Promise<string[]>}  - Changed file paths relative to the repo root
+ */
+export async function fetchPrFiles(prUrl, githubToken) {
+  const { owner, repo, prNumber } = parsePrUrl(prUrl);
+  const apiUrl =
+    `https://api.github.com/repos/${owner}/${repo}/pulls/${prNumber}/files?per_page=100`;
+  const headers = {
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+    'User-Agent': 'argusqa-os',
+    ...(githubToken ? { Authorization: `Bearer ${githubToken}` } : {}),
+  };
+
+  const res = await fetch(apiUrl, { headers });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`GitHub API ${res.status}: ${body || res.statusText}`);
+  }
+  const files = await res.json();
+  return files.map(f => f.filename);
+}
+
+/**
+ * Patterns that indicate an infrastructure-level file whose change can affect
+ * every route — framework configs, root layouts, global stylesheets, package.json.
+ */
+const INFRA_PATTERNS = [
+  /next\.config\./i,
+  /vite\.config\./i,
+  /tailwind\.config\./i,
+  /postcss\.config\./i,
+  /webpack\.config\./i,
+  /global(s)?\.(css|scss|less)$/i,
+  /(^|[/\\])(layout|_app|_document|root)\.(tsx?|jsx?)$/i,
+  /(^|[/\\])app\.(tsx?|jsx?)$/i,
+  /(^|[/\\])main\.(tsx?|jsx?)$/i,
+  /package\.json$/i,
+];
+
+/**
+ * Map a list of changed file paths to the subset of Argus route configs that
+ * are likely affected, using heuristic slug matching.
+ *
+ * Heuristic rules (applied in order):
+ *   1. Any infrastructure file → return ALL routes (full audit)
+ *   2. File path contains a slug that matches a route path segment → include that route
+ *   3. No matches → return ALL routes (conservative fallback — never miss a regression)
+ *
+ * @param {string[]} changedFiles - Relative file paths from fetchPrFiles
+ * @param {Array<{ path: string, name: string }>} routes - Route configs from targets.js
+ * @returns {Array<{ path: string, name: string }>}
+ */
+export function mapFilesToRoutes(changedFiles, routes) {
+  if (!routes || routes.length === 0) return [];
+  if (!changedFiles || changedFiles.length === 0) return routes;
+
+  // Infrastructure change → full audit
+  if (changedFiles.some(f => INFRA_PATTERNS.some(re => re.test(f)))) {
+    return routes;
+  }
+
+  // Build a flat set of lowercase slugs from every changed file path
+  const fileSlugs = new Set(
+    changedFiles.flatMap(f =>
+      // Strip extension, split on separators, keep non-trivial tokens
+      f.toLowerCase()
+        .replace(/\.[^./\\]+$/, '')
+        .split(/[/\\._-]+/)
+        .filter(s => s.length > 1),
+    ),
+  );
+
+  // Extract meaningful segments from a route path (e.g. "/checkout/review" → ["checkout","review"])
+  const routeSegments = (route) =>
+    route.path
+      .toLowerCase()
+      .split('/')
+      .map(s => s.replace(/[^a-z0-9]/g, ''))
+      .filter(s => s.length > 1);
+
+  const matched = routes.filter(route =>
+    routeSegments(route).some(seg => fileSlugs.has(seg)),
+  );
+
+  // Conservative fallback: if nothing matched, audit everything
+  return matched.length > 0 ? matched : routes;
+}

package/src/utils/route-discoverer.js

@@ -74,7 +74,7 @@ export async function discoverFromSitemap(baseUrl) {
   const origin = new URL(baseUrl).origin;
   const sitemapUrl = `${baseUrl.replace(/\/$/, '')}/sitemap.xml`;
   try {
-    const res = await fetch(sitemapUrl, { signal: AbortSignal.timeout(10000) });
+    const res = await fetch(sitemapUrl, { signal: AbortSignal.timeout(10000) }); // lgtm[js/ssrf] — sitemapUrl is derived from developer-configured baseUrl in targets.js, not from HTTP request input
     if (!res.ok) return [];
 
     const buf = await res.arrayBuffer();

package/src/utils/security-analyzer.js

@@ -132,7 +132,7 @@ export function parseSecurityAnalysisResult(rawResult, url) {
     // all field lookups (storageTokenKeys, evalUsage, etc.) return undefined — zero findings.
     // JSON.stringify on a circular object throws; catch logs and returns [].
     let raw = rawResult;
-    if (typeof raw === 'object' && !Array.isArray(raw) && raw !== null && raw.result !== undefined) {
+    if (typeof raw === 'object' && !Array.isArray(raw) && raw !== null && raw.result !== undefined) { // lgtm[js/comparison-of-unconvertible-types] — typeof null === 'object', so raw !== null is required after the typeof check
       raw = raw.result;
     }
     const str = typeof raw === 'string' ? raw : JSON.stringify(raw);

package/src/utils/seo-analyzer.js

@@ -48,7 +48,7 @@ export function parseSeoAnalysisResult(rawResult, url) {
   // client returns an object wrapper, JSON.stringify(rawResult) serialises the envelope
   // instead of the inner payload and all SEO fields are undefined → false positives.
   let inner = rawResult;
-  if (typeof rawResult === 'object' && rawResult !== null && !Array.isArray(rawResult)) {
+  if (typeof rawResult === 'object' && rawResult !== null && !Array.isArray(rawResult)) { // lgtm[js/comparison-of-unconvertible-types] — typeof null === 'object', so rawResult !== null is required after the typeof check
     inner = rawResult.result !== undefined ? rawResult.result : rawResult;
   }
 

package/src/utils/session-persistence.js

@@ -65,7 +65,7 @@ function buildRestoreScript(state) {
     lines.push(`sessionStorage.setItem(${JSON.stringify(k)},${JSON.stringify(String(v ?? ''))});`);
   }
 
-  return `() => { ${lines.join(' ')} return true; }`;
+  return `() => { ${lines.join(' ')} return true; }`; // lgtm[js/code-injection] — all k/v values are JSON.stringify-escaped before insertion; derived from browser session storage, not HTTP request input
 }
 
 // ── Session Save ────────────────────────────────────────────────────────────────

package/src/utils/visual-diff-analyzer.js

@@ -141,13 +141,18 @@ export async function analyzeVisualRegression(browser, url, opts = {}) {
   const baselinePath = path.join(baselineDir, `${slug}.png`);
 
   // ── 3. First run: save baseline ─────────────────────────────────────────────
-  if (!fs.existsSync(baselinePath)) {
-    try {
-      fs.writeFileSync(baselinePath, currentBuf);
-    } catch (err) {
+  // Use flag:'wx' for atomic create — throws EEXIST if baseline was written concurrently (TOCTOU-safe).
+  let baselineIsNew = false;
+  try {
+    fs.writeFileSync(baselinePath, currentBuf, { flag: 'wx' });
+    baselineIsNew = true;
+  } catch (err) {
+    if (err.code !== 'EEXIST') {
       logger.warn(`[ARGUS] visual-diff: could not write baseline ${baselinePath}: ${err.message}`);
       return findings;
     }
+  }
+  if (baselineIsNew) {
 
     findings.push({
       type:     'visual_baseline_created',