argusqa-os 9.2.9 → 9.3.1

package/README.md

@@ -52,14 +52,16 @@ Then ask Claude (or any MCP client):
 Run argus_audit on http://localhost:3000
 ```
 
-**Four tools are exposed:**
+**Six tools are exposed:**
 
 | Tool | What it does |
 | --- | --- |
 | `argus_audit` | Fast QA pass — JS errors, network failures, accessibility, SEO, security, CSS, content |
-| `argus_audit_full` | Deep QA pass — adds Lighthouse scoring, responsive layout checks across 4 viewports, memory leak detection via heap snapshot, hover-state bug detection, and accessibility tree snapshot |
+| `argus_audit_full` | Deep QA pass — adds Lighthouse scoring, responsive layout checks across 4 viewports, memory leak detection, hover-state bug detection, and accessibility tree snapshot |
 | `argus_compare` | Diff dev vs staging side-by-side — screenshots, findings delta, environment regressions |
-| `argus_last_report` | Return the last saved report JSON from the most recent audit |
+| `argus_last_report` | Return the last saved JSON report without re-running a scan |
+| `argus_watch_snapshot` | Snapshot the currently open Chrome tab without navigating — raw console + network capture |
+| `argus_get_context` | Capture everything broken on the open tab, formatted as a diagnostic context for Claude to diagnose and suggest fixes |
 
 > **Requires**: Node.js ≥ 20.19, Chrome (desktop or headless), and the `chrome-devtools-mcp` server registered alongside Argus (shown above).
 
@@ -77,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** | **360 test assertions** | **83 test blocks** |
 
 </div>
 
@@ -339,13 +341,13 @@ 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 3 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` |
 | **Slash Command** | `/argus-retest <url>` triggers an on-demand test from any Slack channel |
 | **CI Integration** | GitHub Actions workflow runs daily at 6 AM UTC and on every push to `main` |
-| **MCP Server (AI-callable Argus)** | Register Argus as an MCP server via `.mcp.json`; Claude (or any MCP client) can call `argus_audit`, `argus_audit_full`, `argus_compare`, `argus_last_report` directly from a conversation — no CLI, no terminal required. Published to npm as **[argusqa-os](https://www.npmjs.com/package/argusqa-os)** — add via `{ "command": "npx", "args": ["-y", "argusqa-os"] }` in `.mcp.json` |
+| **MCP Server (AI-callable Argus)** | Register Argus as an MCP server via `.mcp.json`; Claude (or any MCP client) can call `argus_audit`, `argus_audit_full`, `argus_compare`, `argus_last_report`, `argus_watch_snapshot`, and `argus_get_context` directly from a conversation — no CLI, no terminal required. Published to npm as **[argusqa-os](https://www.npmjs.com/package/argusqa-os)** — add via `{ "command": "npx", "args": ["-y", "argusqa-os"] }` in `.mcp.json` |
 
 Works with **React + SCSS**, CSS Modules, CSS-in-JS (styled-components / emotion), and plain HTML/CSS apps.
 
@@ -382,26 +384,126 @@ In interactive mode (running from Claude Code), MCP tools are called natively. I
 
 ## One-Time Setup
 
-### 1. Clone and install
+### Option A — MCP Server (Claude Code / any MCP client)
+
+No local install required. `npx` auto-downloads `argusqa-os` on first use.
+
+#### 1. Register both MCP servers
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
+    },
+    "argus": {
+      "command": "npx",
+      "args": ["-y", "argusqa-os"]
+    }
+  }
+}
+```
+
+Or via Claude Code CLI:
 
 ```bash
-git clone <your-repo-url>
-cd argus
+claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
+claude mcp add argus -- npx -y argusqa-os
+```
+
+#### 2. Environment variables
+
+Create a `.env` file in your project root:
+
+```env
+TARGET_DEV_URL=http://localhost:3000
+TARGET_STAGING_URL=https://staging.yourapp.com   # optional — enables argus_compare
+```
+
+#### 3. Start Chrome with remote debugging
+
+```bash
+# macOS
+open -a "Google Chrome" --args --remote-debugging-port=9222 --headless=new
+
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --headless=new --no-sandbox --disable-gpu
+
+# Linux
+google-chrome --remote-debugging-port=9222 --headless=new --no-sandbox
+```
+
+#### 4. Slack notifications (optional)
+
+> Skip to use local `report.html` mode — Argus generates a self-contained HTML report when Slack is not configured.
+
+1. [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → name it **BugBot**
+2. **OAuth & Permissions** → Bot Token Scopes: `chat:write`, `files:write`, `files:read`
+3. Install to workspace → copy **Bot User OAuth Token** (`xoxb-...`) to `.env` as `SLACK_BOT_TOKEN`
+4. Create `#bugs-critical`, `#bugs-warnings`, `#bugs-digest` and `/invite @BugBot` in each
+
+```env
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_CHANNEL_CRITICAL=C0000000000
+SLACK_CHANNEL_WARNINGS=C0000000001
+SLACK_CHANNEL_DIGEST=C0000000002
+```
+
+---
+
+### Option B — npm Package (dev dependency / CI/CD)
+
+#### 1. Install
+
+```bash
+npm install --save-dev argusqa-os
+```
+
+#### 2. Environment variables
+
+Run the interactive wizard to auto-generate `.env` and `src/config/targets.js`:
+
+```bash
+npx argus
+```
+
+The wizard detects your framework (Next.js / React Router), discovers routes from `sitemap.xml` and your file structure, and optionally collects Slack and GitHub credentials.
+
+**Alternative — manual setup:** Create a `.env` with `TARGET_DEV_URL` and optionally `TARGET_STAGING_URL`.
+
+#### 3. Start Chrome with remote debugging
+
+Same as Option A — see above.
+
+#### 4. Slack notifications (optional)
+
+Same as Option A — see above.
+
+---
+
+### Option C — Clone the Repository (full source / contributors)
+
+#### 1. Clone and install
+
+```bash
+git clone https://github.com/ironclawdevs27/Argus.git
+cd Argus
 npm install
 npm run setup   # creates reports/ directory
 ```
 
-### 2. Configure environment variables
+#### 2. Environment variables
 
-**Recommended: use the interactive setup wizard**
+**Recommended — use the interactive setup wizard:**
 
 ```bash
 npm run init
 ```
 
-The wizard prompts for your dev and staging URLs, detects your framework (Next.js / React Router), auto-discovers routes from `sitemap.xml` and your file structure, and optionally collects Slack and GitHub credentials. It writes a populated `.env` and a pre-filled `src/config/targets.js` — no manual editing required.
-
-**Alternative: manual setup**
+**Alternative — manual setup:**
 
 ```bash
 cp .env.example .env
@@ -410,26 +512,22 @@ cp .env.example .env
 Open `.env` and fill in:
 
 ```env
-# Your app URLs (required)
 TARGET_DEV_URL=http://localhost:3000
 TARGET_STAGING_URL=https://staging.yourapp.com   # leave blank → CSS-only analysis mode
 
-# Slack — OPTIONAL. Omit to get a local report.html instead of Slack messages.
-# Get from: api.slack.com/apps → BugBot → OAuth & Permissions
+# Slack — OPTIONAL. Omit to get a local report.html instead.
 # SLACK_BOT_TOKEN=xoxb-...
 # SLACK_SIGNING_SECRET=...
-
-# Channel IDs — only needed when SLACK_BOT_TOKEN is set
 # SLACK_CHANNEL_CRITICAL=C0000000000
 # SLACK_CHANNEL_WARNINGS=C0000000001
 # SLACK_CHANNEL_DIGEST=C0000000002
 ```
 
-### 3. Configure your routes
+#### 3. Configure routes
 
-If you used `npm run init` in Step 2, this file was generated for you — skip to Step 4.
+If you ran `npm run init` — skip this step.
 
-Otherwise, edit [src/config/targets.js](src/config/targets.js) — add every key page of your app:
+Otherwise, edit [src/config/targets.js](src/config/targets.js):
 
 ```js
 export const routes = [
@@ -440,111 +538,160 @@ export const routes = [
 ];
 ```
 
-- `critical: true` — any error on this route goes to `#bugs-critical`
+- `critical: true` — errors on this route go to `#bugs-critical`
 - `waitFor` — CSS selector Argus waits for before capturing (signals the page is ready)
 
-### 4. Connect Chrome DevTools MCP to Claude Code
+#### 4. Connect Chrome DevTools MCP to Claude Code
 
 ```bash
 claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
 ```
 
-Verify it's working — in Claude Code, ask:
-> "List all open Chrome pages"
+Verify — ask Claude: *"List all open Chrome pages"* — you should see your tabs.
 
-You should see a list of tabs. If you do, the MCP connection is live.
+#### 5. Start Chrome with remote debugging
 
-### 5. Set up the Slack App (BugBot) *(optional)*
+Same as Option A — see above.
 
-> Skip this step if you don't need Slack notifications. Argus will generate a local `report.html` and open it in the browser instead.
+#### 6. Slack notifications (optional)
 
-1. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → From scratch → name it **BugBot**
-2. **OAuth & Permissions** → Bot Token Scopes: add `chat:write`, `files:write`, `files:read`
-3. Click **Install to Workspace** → Authorize
-4. Copy the **Bot User OAuth Token** (`xoxb-...`) into `.env` as `SLACK_BOT_TOKEN`
-5. **Basic Information** → copy **Signing Secret** into `.env` as `SLACK_SIGNING_SECRET`
-6. Create channels: `#bugs-critical`, `#bugs-warnings`, `#bugs-digest`
-7. In each channel: `/invite @BugBot`
+Same as Option A — see above.
 
 ---
 
 ## Running Argus
 
-### Option A: From Claude Code (interactive — recommended)
+### Option A — Via MCP (Claude Code / any MCP client)
+
+Ask Claude directly — no terminal needed.
+
+**Available tools:**
+
+| Tool | What it does |
+| --- | --- |
+| `argus_audit` | Fast QA pass — JS errors, network failures, accessibility, SEO, security, CSS, content |
+| `argus_audit_full` | Deep QA pass — adds Lighthouse, responsive layout checks across 4 viewports, memory leak detection, hover-state bug detection, and accessibility tree snapshot |
+| `argus_compare` | Diff dev vs staging — screenshots, findings delta, environment regressions |
+| `argus_last_report` | Return the last saved JSON report without re-running a scan |
+| `argus_watch_snapshot` | Snapshot the currently open Chrome tab without navigating — raw console + network capture |
+| `argus_get_context` | Capture everything broken on the open tab, formatted as a diagnostic context for Claude to diagnose and suggest fixes |
+
+**`argus_audit`** — fast audit of any URL:
 
-Open Claude Code in this project directory. With Chrome DevTools MCP connected, ask:
+```text
+Run argus_audit on http://localhost:3000/checkout
+Run argus_audit on http://localhost:3000/login with critical: true
+```
+
+**`argus_audit_full`** — deep audit with Lighthouse + memory + responsive checks:
 
 ```text
-Run the Argus error detection crawl on localhost:3000
+Run argus_audit_full on http://localhost:3000/dashboard
 ```
 
-Claude calls `runCrawl(mcp)` with live MCP tools — navigates pages, captures errors, posts to Slack.
+**`argus_compare`** — dev vs staging diff (reads `TARGET_DEV_URL` and `TARGET_STAGING_URL` from `.env`):
 
 ```text
-Run the Argus environment comparison between localhost:3000 and staging
+Run argus_compare
 ```
 
-Claude calls `runComparison(mcp)` — screenshots both, diffs them, posts results.
+**`argus_last_report`** — retrieve last audit without re-running Chrome:
 
-### Option B: From the terminal (CI / headless)
+```text
+Run argus_last_report
+```
 
-```bash
-# Error detection crawl
-npm run crawl
+**`argus_watch_snapshot`** — snapshot the currently open tab without navigating. Useful when the page is in an authenticated or post-interaction state that navigation would reset:
 
-# Generate a self-contained HTML report from the latest JSON (offline-friendly)
-npm run report:html
+```text
+Run argus_watch_snapshot
+Run argus_watch_snapshot with url: http://localhost:3000
+```
 
-# Environment comparison (or CSS analysis if no staging URL)
-npm run compare
+**`argus_get_context`** — when your app is stuck or throwing errors, run this to capture everything that's broken and feed it to Claude for diagnosis:
 
-# Start the Slack interaction server
-npm run server
+```text
+Run argus_get_context
 ```
 
-Reports are saved to `reports/` as JSON files. Screenshots saved alongside. Run `npm run report:html` after any crawl to get a portable `reports/report.html` with all screenshots inlined — useful for sharing with designers, PMs, or reviewing offline.
+Then follow with: *"Here's the context — what's causing these errors and how do I fix them?"*
 
-### Option C: Watch Mode (passive monitoring)
+---
 
-Watch mode attaches to whatever page Chrome already has open and polls for new issues at a 3-second interval — without navigating anywhere. Use this for real-time reporting while you develop.
+### Option B & C — Via CLI / npm scripts
 
-**Requires 2 terminals:**
+**Available commands:**
 
-| Terminal | Command | Purpose |
-| --- | --- | --- |
-| 1 | `npm start` *(or your app's dev command)* | Your application |
-| 2 | `npm run watch` | Argus passive monitor |
+| Command | What it does |
+| --- | --- |
+| `npm run crawl` | Multi-page batch audit of all routes in `targets.js` |
+| `npm run compare` | Dev vs staging diff (or CSS analysis if no `TARGET_STAGING_URL`) |
+| `npm run watch` | Passive monitor — polls the open Chrome tab every 1s, no navigation |
+| `npm run report:html` | Generate `reports/report.html` from the latest JSON audit |
+| `npm run server` | Start the Slack slash command + interaction server (port 3001) |
+| `npm run init` | Interactive setup wizard — generates `.env` + `targets.js` |
+| `npm run test:unit` | Run 61 unit tests (no Chrome required) |
+| `npm run test:harness` | Run 82-block correctness harness (requires Chrome) |
+
+**`npm run crawl`** — full audit of all configured routes:
+
+```bash
+npm run crawl
+```
+
+Reports are saved to `reports/` as JSON files. Run `npm run report:html` after any crawl for a portable `reports/report.html` with all screenshots inlined — useful for sharing with designers or reviewing offline.
+
+**`npm run compare`** — dev vs staging diff:
+
+```bash
+npm run compare
+```
+
+When `TARGET_STAGING_URL` is not set, automatically switches to **CSS analysis mode** — cascade overrides, component style leaks, unused rules, and React inline style conflicts on the dev environment only.
 
-**Sequential steps:**
+**`npm run watch`** — passive monitoring (polls every 1s, no navigation):
 
-1. Open Chrome and navigate to your app's local URL
+Attaches to whatever Chrome tab is open and reports new issues in real time without navigating anywhere. Use this while developing.
+
+```text
+Requires 2 terminals:
+  Terminal 1 — your app (npm start / npm run dev)
+  Terminal 2 — npm run watch
+```
+
+Steps:
+1. Open Chrome and navigate to your app
 2. Terminal 1: start your application
 3. Terminal 2: `npm run watch` — Argus begins polling
-4. Develop normally — any new console errors, network failures (4xx/5xx), CORS blocks, or auth failures are printed in Terminal 2 in real time
-5. `Ctrl+C` in Terminal 2 — stops the monitor and writes `reports/report.html` if any issues were found
-
-**To target a specific URL:**
+4. Develop normally — console errors, network failures (4xx/5xx), CORS blocks, and auth failures print in real time
+5. `Ctrl+C` — stops the monitor and writes `reports/report.html`
 
 ```bash
+# Attribute findings to a specific URL:
 npm run watch http://localhost:4000
 ```
 
-**Environment variables:**
-
 | Variable | Default | Description |
 | --- | --- | --- |
-| `ARGUS_WATCH_INTERVAL_MS` | `3000` | Poll interval in milliseconds |
-| `TARGET_DEV_URL` | `http://localhost:3000` | URL attributed to findings when none passed as argument |
+| `ARGUS_WATCH_INTERVAL_MS` | `1000` | Poll interval in milliseconds |
+| `TARGET_DEV_URL` | `http://localhost:3000` | URL attributed to findings when none passed |
+
+**`npm run report:html`** — generate HTML dashboard from last audit:
 
-Watch mode uses the same Slack integration as `npm run crawl` — if `SLACK_BOT_TOKEN` is configured, new findings are posted to Slack in real time. On `Ctrl+C`, the HTML report is generated from all accumulated findings for the session.
+```bash
+npm run report:html
+# → reports/report.html (all findings + inline screenshots, portable, no server needed)
+```
+
+---
 
-### Option D: From Slack (on-demand)
+### Option D — From Slack (on-demand)
 
 ```text
 /argus-retest https://staging.yourapp.com/checkout
 ```
 
-BugBot responds immediately, runs the test, and posts results back to the channel. Detailed bug reports go to `#bugs-critical`.
+BugBot responds immediately, runs the test, and posts results back. Detailed bug reports go to `#bugs-critical`. See [Slack Slash Command Setup](#slack-slash-command-setup) for configuration.
 
 ---
 
@@ -796,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 (83 blocks, 360 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)
@@ -841,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 (`357/360` pass). These are MCP-layer restrictions — they cannot be fixed in Argus code.
 
 > **`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.
 
@@ -874,7 +1021,7 @@ These constraints are documented with workarounds in [SKILL.md §10](SKILL.md).
 | `ARGUS_RETRY_ATTEMPTS` | No | Max retry attempts for `navigate`/`fill` MCP calls (default: `3`) |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | No | OTLP collector endpoint — enables span/metric export to Jaeger, Grafana Tempo, Datadog, etc. |
 | `ARGUS_OTEL_CONSOLE` | No | Set to `1` to print OTel spans to stdout without an OTLP endpoint (dev tracing) |
-| `ARGUS_WATCH_INTERVAL_MS` | No | Watch mode poll interval in milliseconds (default: `3000`) |
+| `ARGUS_WATCH_INTERVAL_MS` | No | Watch mode poll interval in milliseconds (default: `1000`) |
 | `ARGUS_SOURCE_DIR` | No | Path to your app's source directory — enables codebase cross-reference (env var detection, feature flag leakage, dead routes) |
 | `ARGUS_ENV_FILE` | No | Path to your app's `.env` file — C1 cross-references env vars used in source code against this file to detect missing declarations |
 | `GITHUB_TOKEN` | No | GitHub personal access token — required for PR comment + commit status integration |

package/package.json

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

package/src/mcp-server.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 /**
- * Argus MCP Server (v9.2.9)
+ * Argus MCP Server (v9.3.1)
  *
  * 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,6 +33,18 @@ 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;
+
+function storeSnapshot(id, findings) {
+  snapshotStore.set(id, findings);
+  if (snapshotStore.size > MAX_SNAPSHOTS) {
+    snapshotStore.delete(snapshotStore.keys().next().value);
+  }
+}
+
 // ── Tool definitions ─────────────────────────────────────────────────────────
 
 const TOOLS = [
@@ -82,11 +94,12 @@ const TOOLS = [
   },
   {
     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 }. 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). 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.' },
+        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.' },
       },
     },
   },
@@ -143,26 +156,56 @@ async function handleWatchSnapshot({ url } = {}) {
   });
 }
 
-async function handleGetContext({ url } = {}) {
+async function handleGetContext({ url, snapshot_id: prevId } = {}) {
   return withMcp(async (mcp) => {
     const browser = new CdpBrowserAdapter(mcp);
     const baseUrl = url ?? process.env.TARGET_DEV_URL ?? 'http://localhost:3000';
     const session = new WatchSession(browser, baseUrl);
     const { findings, newConsole, newNetwork } = await session.poll();
 
+    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 +215,7 @@ 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),
+      ...(isDiff ? { resolved, new_issues, persisting } : {}),
     };
 
     return { content: [{ type: 'text', text: JSON.stringify(context, null, 2) }] };
@@ -196,7 +240,7 @@ async function handleLastReport() {
 // ── Server bootstrap ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'argus', version: '9.2.9' },
+  { name: 'argus', version: '9.3.1' },
   { capabilities: { tools: {} } },
 );
 

package/src/orchestration/watch-mode.js

@@ -13,12 +13,14 @@
  * individual poll() calls without running the interval loop.
  *
  * Environment variables:
- *   ARGUS_WATCH_INTERVAL_MS  — poll interval in ms (default: 3000)
+ *   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.
@@ -217,7 +374,7 @@ export class WatchSession {
  */
 export async function runWatchMode(baseUrl) {
   const target          = baseUrl ?? process.env.TARGET_DEV_URL ?? 'http://localhost:3000';
-  const pollIntervalMs  = parseInt(process.env.ARGUS_WATCH_INTERVAL_MS ?? '3000', 10);
+  const pollIntervalMs  = parseInt(process.env.ARGUS_WATCH_INTERVAL_MS ?? '1000', 10);
 
   const mcp     = await createMcpClient();
   const browser = new CdpBrowserAdapter(mcp);
@@ -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}`);