argusqa-os 9.3.0 → 9.4.0

package/README.md

@@ -79,7 +79,7 @@ The `landing/` directory contains the product landing page (React + Vite + Tailw
 
 | 🔴 Critical / 🟡 Warning / 🔵 Info | ⚙️ | 🧪 | 📋 |
 | :---: | :---: | :---: | :---: |
-| **114 distinct issue types detected** | **24 analysis engines** | **348 test assertions** | **82 test blocks** |
+| **114 distinct issue types detected** | **24 analysis engines** | **367 test assertions** | **84 test blocks** |
 
 </div>
 
@@ -341,7 +341,7 @@ Argus watches your running application and automatically surfaces issues that te
 | **GitHub PR Integration** | Posts a structured Markdown findings table as a PR comment (updates in-place — one comment per PR, no spam); sets an `argus-qa` commit status check (`failure` when new criticals exist, `success` otherwise) — blocks merge via branch protection when regressions are introduced. Requires `GITHUB_TOKEN` + `GITHUB_REPOSITORY` env vars |
 | **Auto Route Discovery** | Augments manual `routes[]` with paths from three sources: fetches `/sitemap.xml` (follows one sitemap-index level, 10s timeout), scans Next.js `pages/` (Next 12) and `app/` (Next 13+) directories stripping route groups `(auth)`, and greps JS/TS source for React Router `<Route path>` declarations. Dynamic `[param]` segments are skipped — no concrete URL to crawl. Manual route config (`critical`, `waitFor`) always takes precedence. |
 | **`argus init` Setup Wizard** | `npm run init` (or `npx argus init`) guides first-time setup: collects target URLs, detects the app framework (Next.js / React Router / unknown) from the source directory's `package.json`, runs C3 route discovery against the dev URL, prompts for optional Slack tokens and GitHub credentials, then writes a populated `.env` and a pre-filled `src/config/targets.js` — zero manual config editing required. |
-| **Watch Mode** | `npm run watch` attaches to whatever Chrome tab is open and polls `list_console_messages` + `list_network_requests` every 1 s (configurable via `ARGUS_WATCH_INTERVAL_MS`). Reports new console errors, network failures (4xx/5xx), CORS blocks, and auth failures in real time — without navigating. On `Ctrl+C`, generates a final `reports/report.html`. No route config needed. |
+| **Watch Mode** | `npm run watch` attaches to whatever Chrome tab is open and polls `list_console_messages` + `list_network_requests` every 1 s (configurable via `ARGUS_WATCH_INTERVAL_MS`). Reports new console errors, network failures (4xx/5xx), CORS blocks, and auth failures in real time — without navigating. Starts a live web dashboard at `http://localhost:3002` (configurable via `ARGUS_WATCH_UI_PORT`). On `Ctrl+C`, generates a final `reports/report.html`. No route config needed. |
 | **Full Lighthouse Suite** | All 4 Lighthouse categories (performance, SEO, best-practices, accessibility) with per-audit items |
 | **Performance Budgets** | Enforces LCP < 2500ms, CLS < 0.1, FID < 100ms, TTFB < 800ms per route |
 | **Slack Notifications** | Rich Block Kit reports with inline screenshots routed to `#bugs-critical`, `#bugs-warnings`, `#bugs-digest` |
@@ -943,11 +943,11 @@ argus/
 │   └── README.md                     # Setup guide, Supabase SQL schema, env vars, deployment
 ├── scripts/
 │   └── dispatch-report.js            # Standalone Slack re-dispatch script (re-posts last report.json to Slack)
-├── test-harness/                     # Fixture server + test runner (82 blocks, 348 hard assertions, 54 fixture pages)
+├── test-harness/                     # Fixture server + test runner (84 blocks, 367 hard assertions, 54 fixture pages)
 │   ├── README.md
 │   ├── server.js                     # Express fixture server (ports 3100 dev / 3101 staging)
 │   ├── harness-config.js             # Route definitions + expected findings
-│   ├── validate.js                   # Test runner — 82 numbered blocks ([80] MCP server, [81] createFinding, [82] withRetry)
+│   ├── validate.js                   # Test runner — 83 numbered blocks ([80] MCP server, [81] createFinding, [82] withRetry, [83] watch dashboard)
 │   ├── pages/                        # 54 fixture pages (one per detection category)
 │   ├── nextjs-fixture/               # Next.js app structure for C3 discovery tests (10 files)
 │   ├── source-fixture/               # Minimal app.js for C1 codebase-analyzer tests (env var audit)
@@ -988,7 +988,7 @@ argus/
 
 ## Known MCP Tool Limitations
 
-The Chrome DevTools MCP behavioral constraints below cause **3 permanent test failures** in the harness (`345/348` pass). These are MCP-layer restrictions — they cannot be fixed in Argus code.
+The Chrome DevTools MCP behavioral constraints below cause **3 permanent test failures** in the harness (`364/367` pass). These are MCP-layer restrictions — they cannot be fixed in Argus code. `validate.js` now exits with code 0 when only these 3 failures remain, making the CI harness gate reliable.
 
 > **`type_text` clarification**: `type_text` does fire DOM `input` events when the element is properly focused first with `mcp.click({ uid })`. Always use uid-based focus — passing `{ selector }` to `mcp.click` silently does nothing.
 

package/glama.json

@@ -1,4 +1,32 @@
 {
   "$schema": "https://glama.ai/mcp/schemas/server.json",
-  "maintainers": ["ironclawdevs27"]
+  "name": "argus",
+  "description": "AI-powered QA harness that audits web apps via Chrome DevTools Protocol. Catches JS errors, network failures, a11y violations, SEO issues, security headers, CSS regressions, and more — directly from Claude conversations. 6 MCP tools: argus_audit (fast 8-analyzer pass), argus_audit_full (Lighthouse + memory + responsive), argus_compare (dev vs staging diff), argus_last_report (retrieve last JSON report), argus_watch_snapshot (live tab snapshot without navigating), argus_get_context (LLM-optimized context + fix loop with snapshot_id diff). 84 test blocks, 367 hard assertions, 54 detection categories.",
+  "maintainers": ["ironclawdevs27"],
+  "tools": [
+    {
+      "name": "argus_audit",
+      "description": "Fast QA audit — JS errors, network failures (4xx/5xx), API frequency loops, CSS cascade issues, SEO violations, security headers, accessibility, and content. Returns { findings, summary }. Supports cache: true to skip re-crawl on repeat calls."
+    },
+    {
+      "name": "argus_audit_full",
+      "description": "Deep QA audit — extends argus_audit with Lighthouse performance/accessibility scoring, responsive layout checks at 4 viewports, memory leak detection via heap snapshot, and accessibility tree analysis."
+    },
+    {
+      "name": "argus_compare",
+      "description": "Diffs dev vs staging environments side-by-side. Captures screenshots, runs all analyzers on each, and surfaces regressions — findings present in staging but not dev, or with changed severity."
+    },
+    {
+      "name": "argus_last_report",
+      "description": "Returns the most recent Argus JSON report from the reports/ directory without re-running a scan."
+    },
+    {
+      "name": "argus_watch_snapshot",
+      "description": "Snapshots the currently open Chrome tab without navigating — captures console errors, network failures, CORS blocks, and auth failures in one poll. Accepts optional tabId to inspect a specific tab."
+    },
+    {
+      "name": "argus_get_context",
+      "description": "LLM-optimized diagnostic context for the open Chrome tab. Returns snapshot_id for fix-loop diffing: pass it back on the next call to get resolved/new_issues/persisting arrays. Accepts optional tabId for multi-tab workflows."
+    }
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argusqa-os",
-  "version": "9.3.0",
+  "version": "9.4.0",
   "mcpName": "io.github.ironclawdevs27/argus",
   "description": "Argus — AI-powered automated dev-testing platform using Chrome DevTools MCP and Claude Code",
   "keywords": [

package/src/adapters/browser.js

@@ -56,6 +56,10 @@ export class CdpBrowserAdapter {
   stopTrace()              { return this._mcp.performance_stop_trace({}); }
   analyzeInsight(opts)     { return this._mcp.performance_analyze_insight(opts); }
 
+  // ── Tab management ─────────────────────────────────────────────────────────
+  listPages()              { return this._mcp.list_pages({}); }
+  selectPage(tabId)        { return this._mcp.select_page({ pageId: tabId }); }
+
   // ── Lifecycle ───────────────────────────────────────────────────────────────
   close()                  { return this._mcp.close(); }
 

package/src/mcp-server.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 /**
- * Argus MCP Server (v9.2.9)
+ * Argus MCP Server (v9.4.0)
  *
  * Exposes Argus as an MCP server so Claude (or any MCP client) can call
- * argus_audit, argus_audit_full, argus_compare, and argus_last_report
- * directly from a conversation without using the CLI.
+ * argus_audit, argus_audit_full, argus_compare, argus_last_report, and
+ * argus_get_context (fix loop) directly from a conversation without using the CLI.
  *
  * Architecture: MCP-inside-MCP
  *   Claude (MCP client)
@@ -33,17 +33,41 @@ import { CdpBrowserAdapter }                  from './adapters/browser.js';
 
 const REPORTS_DIR = path.resolve(process.cwd(), 'reports');
 
+// Fix loop: stores up to 20 snapshots keyed by snapshot_id so argus_get_context
+// can diff before/after a fix. Keys are evicted oldest-first when the limit is hit.
+const snapshotStore = new Map();
+const MAX_SNAPSHOTS = 20;
+
+// Audit cache: stores argus_audit results keyed by URL so cache:true skips re-crawl.
+const auditCache = new Map();
+const MAX_AUDIT_CACHE = 20;
+
+function storeSnapshot(id, findings) {
+  snapshotStore.set(id, findings);
+  if (snapshotStore.size > MAX_SNAPSHOTS) {
+    snapshotStore.delete(snapshotStore.keys().next().value);
+  }
+}
+
+function cacheAudit(url, result) {
+  auditCache.set(url, { result, ts: Date.now() });
+  if (auditCache.size > MAX_AUDIT_CACHE) {
+    auditCache.delete(auditCache.keys().next().value);
+  }
+}
+
 // ── Tool definitions ─────────────────────────────────────────────────────────
 
 const TOOLS = [
   {
     name: 'argus_audit',
-    description: 'Fast QA audit on a URL via Chrome DevTools Protocol. Runs 8 analyzers in one pass: JS errors, unhandled rejections, network failures (4xx/5xx), API frequency loops, CSS cascade issues, SEO violations, security header checks, and accessibility. Returns { findings: [{severity, type, message, url}], summary: {critical, warning, info} }. Use for CI smoke tests and pre-deploy gates. For Lighthouse scoring and memory leak detection, use argus_audit_full. Requires Chrome running with --remote-debugging-port=9222.',
+    description: 'Fast QA audit on a URL via Chrome DevTools Protocol. Runs 8 analyzers in one pass: JS errors, unhandled rejections, network failures (4xx/5xx), API frequency loops, CSS cascade issues, SEO violations, security header checks, and accessibility. Returns { findings: [{severity, type, message, url}], summary: {critical, warning, info} }. Use for CI smoke tests and pre-deploy gates. Pass cache: true to skip re-crawl on repeat calls to the same URL within a session — useful in tight fix loops. For Lighthouse scoring and memory leak detection, use argus_audit_full. Requires Chrome running with --remote-debugging-port=9222.',
     inputSchema: {
       type: 'object',
       properties: {
         url:      { type: 'string',  description: 'Full URL to audit, including protocol and path (e.g. http://localhost:3000/checkout). Must be reachable by the running Chrome instance.' },
         critical: { type: 'boolean', description: 'When true, console.error calls are escalated to critical severity. Set true for business-critical routes (login, checkout, dashboard) where any error is a blocker.', default: false },
+        cache:    { type: 'boolean', description: 'When true, returns the cached result for this URL if one exists (from a previous argus_audit call in this session) without re-crawling. Use in fix loops to cheaply re-read the last audit while iterating on a fix. Cache is per-session, max 20 entries, LRU eviction.', default: false },
       },
       required: ['url'],
     },
@@ -72,21 +96,24 @@ const TOOLS = [
   },
   {
     name: 'argus_watch_snapshot',
-    description: 'Snapshots the currently open Chrome tab without navigating — captures console errors, network failures (4xx/5xx), CORS blocks, and auth failures in one poll. Returns { findings: [{severity, type, message, url}], newConsole, newNetwork }. Use during active development to inspect what is happening on the current page without running a full audit. Requires Chrome on --remote-debugging-port=9222 with a page already open.',
+    description: 'Snapshots the currently open Chrome tab without navigating — captures console errors, network failures (4xx/5xx), CORS blocks, and auth failures in one poll. Returns { findings: [{severity, type, message, url}], newConsole, newNetwork }. Use during active development to inspect what is happening on the current page without running a full audit. Pass tabId to inspect a specific tab (get IDs from argus_get_context or list_pages). Without tabId, reads the active tab. Requires Chrome on --remote-debugging-port=9222 with a page already open.',
     inputSchema: {
       type: 'object',
       properties: {
-        url: { type: 'string', description: 'Optional base URL to attribute findings to (default: TARGET_DEV_URL env var). Does not navigate — reads the currently open Chrome tab.' },
+        url:   { type: 'string', description: 'Optional base URL to attribute findings to (default: TARGET_DEV_URL env var). Does not navigate — reads the currently open Chrome tab.' },
+        tabId: { type: 'string', description: 'Optional Chrome page/tab ID (e.g. from a prior argus_get_context response). When provided, switches focus to that tab before snapshotting — useful for SPAs that spawn new windows or multi-tab flows.' },
       },
     },
   },
   {
     name: 'argus_get_context',
-    description: 'Captures everything currently broken on the open Chrome tab and formats it as a diagnostic context for Claude to read and suggest fixes. Does NOT navigate — reads the live tab state after user interactions, in authenticated sessions, or mid-flow. Returns { summary, url, timestamp, critical_issues, warnings, js_errors, network_failures, console_errors, recent_requests } where summary is a plain-English description of what is broken. Use when the app is stuck, throwing errors, or behaving unexpectedly — run this, then paste the output to Claude and ask for fixes. Requires Chrome on --remote-debugging-port=9222.',
+    description: 'Captures everything currently broken on the open Chrome tab and formats it as a diagnostic context for Claude to read and suggest fixes. Does NOT navigate — reads the live tab state after user interactions, in authenticated sessions, or mid-flow. Returns { snapshot_id, summary, url, timestamp, critical_issues, warnings, js_errors, network_failures, console_errors, recent_requests, open_tabs }. Fix loop: pass the snapshot_id from a previous call as snapshot_id to get a diff — the response will include resolved (cleared since last snapshot), new_issues (appeared since last snapshot), and persisting (unchanged). Multi-tab: pass tabId to inspect a specific tab, or omit to read the active tab. The open_tabs array always lists all currently open Chrome tabs. Workflow: call argus_get_context → Claude suggests fix → apply fix → call argus_get_context with snapshot_id → verify resolved array is non-empty. Requires Chrome on --remote-debugging-port=9222.',
     inputSchema: {
       type: 'object',
       properties: {
-        url: { type: 'string', description: 'Optional base URL to attribute findings to (default: TARGET_DEV_URL env var). Does not navigate — inspects the currently open Chrome tab.' },
+        url:         { type: 'string', description: 'Optional base URL to attribute findings to (default: TARGET_DEV_URL env var). Does not navigate — inspects the currently open Chrome tab.' },
+        snapshot_id: { type: 'string', description: 'Optional snapshot_id from a previous argus_get_context call. When provided, the response includes resolved/new_issues/persisting arrays showing what changed since that snapshot.' },
+        tabId:       { type: 'string', description: 'Optional Chrome page/tab ID. When provided, switches focus to that specific tab before capturing context — useful for SPAs that spawn new windows (e.g. OAuth popups, checkout flows). Get tab IDs from the open_tabs array in a prior argus_get_context response.' },
       },
     },
   },
@@ -105,11 +132,16 @@ async function withMcp(fn) {
 
 // ── Tool handlers ─────────────────────────────────────────────────────────────
 
-async function handleAudit({ url, critical = false }) {
+async function handleAudit({ url, critical = false, cache = false }) {
+  if (cache && auditCache.has(url)) {
+    const { result, ts } = auditCache.get(url);
+    return { content: [{ type: 'text', text: JSON.stringify({ ...result, _cached: true, _cachedAt: new Date(ts).toISOString() }, null, 2) }] };
+  }
   return withMcp(async (mcp) => {
     const parsed  = new URL(url);
     const route   = { path: parsed.pathname + parsed.search + parsed.hash, name: 'audit', critical };
     const findings = await crawlRouteCheap(route, parsed.origin, mcp);
+    if (cache) cacheAudit(url, findings);
     return { content: [{ type: 'text', text: JSON.stringify(findings, null, 2) }] };
   });
 }
@@ -133,9 +165,10 @@ async function handleCompare() {
   });
 }
 
-async function handleWatchSnapshot({ url } = {}) {
+async function handleWatchSnapshot({ url, tabId } = {}) {
   return withMcp(async (mcp) => {
     const browser = new CdpBrowserAdapter(mcp);
+    if (tabId) await browser.selectPage(tabId);
     const baseUrl = url ?? process.env.TARGET_DEV_URL ?? 'http://localhost:3000';
     const session = new WatchSession(browser, baseUrl);
     const result  = await session.poll();
@@ -143,26 +176,66 @@ async function handleWatchSnapshot({ url } = {}) {
   });
 }
 
-async function handleGetContext({ url } = {}) {
+async function handleGetContext({ url, snapshot_id: prevId, tabId } = {}) {
   return withMcp(async (mcp) => {
     const browser = new CdpBrowserAdapter(mcp);
+    if (tabId) await browser.selectPage(tabId);
     const baseUrl = url ?? process.env.TARGET_DEV_URL ?? 'http://localhost:3000';
     const session = new WatchSession(browser, baseUrl);
     const { findings, newConsole, newNetwork } = await session.poll();
 
+    // List all open tabs so the caller can target a specific tab on the next call.
+    let open_tabs = [];
+    try {
+      const pages = await browser.listPages();
+      if (Array.isArray(pages)) {
+        open_tabs = pages.map(p => ({ id: p.id ?? p.pageId, url: p.url, title: p.title }));
+      }
+    } catch { /* list_pages not available in all Chrome configs — degrade gracefully */ }
+
+    const newId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+    storeSnapshot(newId, findings);
+
     const critical = findings.filter(f => f.severity === 'critical');
     const warnings  = findings.filter(f => f.severity === 'warning');
 
+    const findingKey = (f) => `${f.type}::${(f.message ?? '').slice(0, 120)}`;
+
+    let resolved = [];
+    let persisting = [];
+    let new_issues = findings;
+    const isDiff = prevId && snapshotStore.has(prevId);
+
+    if (isDiff) {
+      const prev     = snapshotStore.get(prevId);
+      const prevKeys = new Set(prev.map(findingKey));
+      const curKeys  = new Set(findings.map(findingKey));
+      resolved   = prev.filter(f => !curKeys.has(findingKey(f)));
+      persisting = findings.filter(f => prevKeys.has(findingKey(f)));
+      new_issues = findings.filter(f => !prevKeys.has(findingKey(f)));
+    }
+
     let summary;
-    if (critical.length === 0 && warnings.length === 0) {
+    if (isDiff) {
+      if (resolved.length > 0 && critical.length === 0 && warnings.length === 0) {
+        summary = `All issues resolved on ${baseUrl}. ${resolved.length} finding${resolved.length > 1 ? 's' : ''} cleared since last snapshot.`;
+      } else if (resolved.length > 0) {
+        summary = `${resolved.length} issue${resolved.length > 1 ? 's' : ''} resolved on ${baseUrl}. ${new_issues.length} new + ${persisting.length} persisting (${critical.length} critical). Pass the new snapshot_id to continue the fix loop.`;
+      } else if (critical.length === 0 && warnings.length === 0) {
+        summary = `No issues on ${baseUrl} — console and network are clean.`;
+      } else {
+        summary = `No change on ${baseUrl}: ${critical.length} critical + ${warnings.length} warning${warnings.length !== 1 ? 's' : ''} still present. Check the persisting array for what hasn't been fixed.`;
+      }
+    } else if (critical.length === 0 && warnings.length === 0) {
       summary = `No issues detected on ${baseUrl} — console and network are clean.`;
     } else if (critical.length > 0) {
-      summary = `${critical.length} critical issue${critical.length > 1 ? 's' : ''} + ${warnings.length} warning${warnings.length !== 1 ? 's' : ''} detected on ${baseUrl}. Focus on critical issues first.`;
+      summary = `${critical.length} critical issue${critical.length > 1 ? 's' : ''} + ${warnings.length} warning${warnings.length !== 1 ? 's' : ''} detected on ${baseUrl}. Focus on critical issues first. Pass snapshot_id to the next argus_get_context call after applying a fix to see what changed.`;
     } else {
-      summary = `${warnings.length} warning${warnings.length !== 1 ? 's' : ''} detected on ${baseUrl}. No critical errors.`;
+      summary = `${warnings.length} warning${warnings.length !== 1 ? 's' : ''} detected on ${baseUrl}. No critical errors. Pass snapshot_id to the next call to verify fixes.`;
     }
 
     const context = {
+      snapshot_id:      newId,
       summary,
       url:              baseUrl,
       timestamp:        new Date().toISOString(),
@@ -172,6 +245,8 @@ async function handleGetContext({ url } = {}) {
       network_failures: findings.filter(f => f.type === 'network-error' || f.type === 'cors-error' || f.type === 'auth-error'),
       console_errors:   newConsole.filter(m => m.level === 'error' || m.level === 'warning'),
       recent_requests:  newNetwork.slice(-20),
+      open_tabs,
+      ...(isDiff ? { resolved, new_issues, persisting } : {}),
     };
 
     return { content: [{ type: 'text', text: JSON.stringify(context, null, 2) }] };
@@ -196,7 +271,7 @@ async function handleLastReport() {
 // ── Server bootstrap ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'argus', version: '9.3.0' },
+  { name: 'argus', version: '9.4.0' },
   { capabilities: { tools: {} } },
 );
 

package/src/orchestration/watch-mode.js

@@ -15,10 +15,12 @@
  * Environment variables:
  *   ARGUS_WATCH_INTERVAL_MS  — poll interval in ms (default: 1000)
  *   TARGET_DEV_URL           — base URL to monitor (default: http://localhost:3000)
+ *   ARGUS_WATCH_UI_PORT      — port for the live web dashboard (default: 3002)
  */
 
 import fs   from 'fs';
 import path from 'path';
+import http from 'http';
 import { fileURLToPath } from 'url';
 import 'dotenv/config';
 import { createMcpClient } from '../utils/mcp-client.js';
@@ -41,6 +43,161 @@ import {
 const __dirname   = path.dirname(fileURLToPath(import.meta.url));
 const REPORTS_DIR = path.resolve(__dirname, '../../reports');
 
+// ── Live dashboard ─────────────────────────────────────────────────────────────
+
+const DASHBOARD_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Argus Watch Dashboard</title>
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  body { background: #0d0d0d; color: #e0e0e0; font-family: 'Segoe UI', system-ui, sans-serif; min-height: 100vh; }
+  header { background: #111; border-bottom: 1px solid #1e1e1e; padding: 14px 24px; display: flex; align-items: center; gap: 12px; }
+  .pulse-dot { width: 10px; height: 10px; border-radius: 50%; background: #5E0ED7; flex-shrink: 0;
+    animation: pulse 1.8s ease-in-out infinite; }
+  @keyframes pulse { 0%,100%{opacity:1;transform:scale(1)} 50%{opacity:.4;transform:scale(1.3)} }
+  .header-text { flex: 1; }
+  .header-text h1 { font-size: 15px; font-weight: 600; color: #fff; letter-spacing: .02em; }
+  .header-text small { font-size: 11px; color: #666; }
+  .pills { display: flex; gap: 8px; flex-wrap: wrap; padding: 16px 24px; }
+  .pill { font-size: 12px; font-weight: 600; padding: 4px 12px; border-radius: 999px; letter-spacing: .04em; }
+  .pill-critical { background: #3a0e0e; color: #f87171; border: 1px solid #7f1d1d; }
+  .pill-warning  { background: #2e2200; color: #fbbf24; border: 1px solid #78350f; }
+  .pill-info     { background: #1a0b33; color: #a78bfa; border: 1px solid #4c1d95; }
+  .pill-clear    { background: #0b2718; color: #34d399; border: 1px solid #064e3b; }
+  .status-bar { font-size: 11px; padding: 4px 24px 12px; color: #555; }
+  .status-bar.error { color: #f87171; }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  thead th { background: #161616; color: #888; font-weight: 600; text-align: left;
+    padding: 10px 16px; border-bottom: 1px solid #222; font-size: 11px; text-transform: uppercase; letter-spacing: .06em; }
+  tbody tr { border-bottom: 1px solid #181818; transition: background .15s; }
+  tbody tr:hover { background: #151515; }
+  td { padding: 10px 16px; vertical-align: top; }
+  .sev { font-size: 11px; font-weight: 700; padding: 2px 8px; border-radius: 4px; white-space: nowrap; }
+  .sev-critical { background: #3a0e0e; color: #f87171; }
+  .sev-warning  { background: #2e2200; color: #fbbf24; }
+  .sev-info     { background: #1a0b33; color: #a78bfa; }
+  .type-cell { color: #9ca3af; font-size: 12px; font-family: monospace; white-space: nowrap; }
+  .msg-cell  { color: #d1d5db; word-break: break-word; max-width: 480px; }
+  .empty-row td { text-align: center; color: #444; padding: 40px; font-size: 13px; }
+  .table-wrap { padding: 0 24px 24px; overflow-x: auto; }
+</style>
+</head>
+<body>
+<header>
+  <div class="pulse-dot" id="dot"></div>
+  <div class="header-text">
+    <h1 id="target">Argus Watch</h1>
+    <small id="lastPoll">Connecting…</small>
+  </div>
+</header>
+<div class="pills" id="pills"></div>
+<div class="status-bar" id="status"></div>
+<div class="table-wrap">
+  <table>
+    <thead><tr><th>Severity</th><th>Type</th><th>Message</th></tr></thead>
+    <tbody id="tbody"></tbody>
+  </table>
+</div>
+<script>
+  const SEV_ORDER = { critical: 0, warning: 1, info: 2 };
+
+  function renderPills(findings) {
+    const counts = { critical: 0, warning: 0, info: 0 };
+    for (const f of findings) counts[f.severity] = (counts[f.severity] || 0) + 1;
+    const pills = document.getElementById('pills');
+    if (findings.length === 0) {
+      pills.innerHTML = '<span class="pill pill-clear">All clear</span>';
+      return;
+    }
+    let html = '';
+    if (counts.critical) html += \`<span class="pill pill-critical">\${counts.critical} Critical</span>\`;
+    if (counts.warning)  html += \`<span class="pill pill-warning">\${counts.warning} Warning</span>\`;
+    if (counts.info)     html += \`<span class="pill pill-info">\${counts.info} Info</span>\`;
+    pills.innerHTML = html;
+  }
+
+  function renderTable(findings) {
+    const sorted = [...findings].sort((a, b) =>
+      (SEV_ORDER[a.severity] ?? 3) - (SEV_ORDER[b.severity] ?? 3));
+    const tbody = document.getElementById('tbody');
+    if (sorted.length === 0) {
+      tbody.innerHTML = '<tr class="empty-row"><td colspan="3">No findings yet</td></tr>';
+      return;
+    }
+    tbody.innerHTML = sorted.map(f => {
+      const sc = 'sev-' + (f.severity || 'info');
+      const msg = (f.message || '').replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+      const typ = (f.type || '').replace(/&/g,'&amp;');
+      return \`<tr>
+        <td><span class="sev \${sc}">\${f.severity ?? 'info'}</span></td>
+        <td class="type-cell">\${typ}</td>
+        <td class="msg-cell">\${msg}</td>
+      </tr>\`;
+    }).join('');
+  }
+
+  async function poll() {
+    try {
+      const res = await fetch('/data');
+      if (!res.ok) throw new Error('HTTP ' + res.status);
+      const data = await res.json();
+      document.getElementById('target').textContent = 'Argus Watch — ' + (data.target || '');
+      document.getElementById('lastPoll').textContent = 'Last poll: ' + new Date(data.lastPoll).toLocaleTimeString();
+      document.getElementById('dot').style.background = '#5E0ED7';
+      document.getElementById('status').textContent = '';
+      document.getElementById('status').className = 'status-bar';
+      renderPills(data.findings || []);
+      renderTable(data.findings || []);
+    } catch (e) {
+      document.getElementById('status').textContent = 'Connection lost — ' + e.message;
+      document.getElementById('status').className = 'status-bar error';
+      document.getElementById('dot').style.background = '#555';
+    }
+  }
+
+  poll();
+  setInterval(poll, 2000);
+</script>
+</body>
+</html>`;
+
+/**
+ * Start the live web dashboard HTTP server.
+ *
+ * @param {() => object[]} getFindings  — callback that returns current findings array
+ * @param {string}         target       — the URL being monitored (shown in header)
+ * @param {number}         port         — TCP port to listen on (default 3002)
+ * @returns {http.Server}
+ */
+function startDashboard(getFindings, target, port) {
+  const server = http.createServer((req, res) => {
+    if (req.url === '/data' || req.url?.startsWith('/data?')) {
+      const payload = JSON.stringify({
+        target,
+        lastPoll: new Date().toISOString(),
+        findings: getFindings(),
+      });
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+      });
+      res.end(payload);
+    } else {
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(DASHBOARD_HTML);
+    }
+  });
+
+  server.listen(port, '127.0.0.1', () => {
+    logger.info(`[ARGUS WATCH] Dashboard → http://localhost:${port}`);
+  });
+
+  return server;
+}
+
 // ── Deduplication key generators ───────────────────────────────────────────────
 // Two messages/requests are considered "the same" if their keys match. This
 // prevents re-reporting errors that were already captured in a previous poll.
@@ -228,6 +385,9 @@ export async function runWatchMode(baseUrl) {
   logger.info(`[ARGUS WATCH] Polling every ${pollIntervalMs}ms. Press Ctrl+C to stop.`);
   logger.info('[ARGUS WATCH] ─────────────────────────────────────────────────\n');
 
+  const uiPort   = parseInt(process.env.ARGUS_WATCH_UI_PORT ?? '3002', 10);
+  const dashServer = startDashboard(() => session.getAllFindings(), target, uiPort);
+
   const badge = (severity) =>
     severity === 'critical' ? '✗ CRIT' :
     severity === 'warning'  ? '! WARN' : 'i INFO';
@@ -270,6 +430,7 @@ export async function runWatchMode(baseUrl) {
 
   process.on('SIGINT', async () => {
     clearInterval(interval);
+    try { dashServer.close(); } catch { /* ignore */ }
     const all = session.getAllFindings();
 
     logger.info(`\n[ARGUS WATCH] Stopped. Total findings: ${all.length}`);