argusqa-os 9.7.3 → 9.7.4

package/README.md

@@ -1,394 +1,394 @@
-<div align="center">
-
-# Argus — AI-Powered Automated QA
-
-[![npm](https://img.shields.io/npm/v/argusqa-os?color=7C3AED)](https://www.npmjs.com/package/argusqa-os)
-[![MCP Server](https://glama.ai/mcp/servers/ironclawdevs27/Argus/badges/card.svg)](https://glama.ai/mcp/servers/ironclawdevs27/Argus)
-[![Harness](https://img.shields.io/badge/harness-679%2F679-4ADE80)](test-harness/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-
-**Argus catches the bugs your test suite misses — visual regressions, API loops, CSS drift, console noise, accessibility failures, and more — and delivers rich reports to Slack (or a local HTML dashboard).**
-
-[Quick Start](#quick-start) · [Features](#what-argus-catches) · [Setup](#full-setup) · [MCP Tools](#mcp-tools) · [CLI Commands](#cli-commands) · [Troubleshooting](#troubleshooting) · [Full Reference](REFERENCE.md)
-
-</div>
-
----
-
-## Quick Start
-
-> **No install required.** `npx` auto-downloads Argus on first run.
-
-**Step 1 — 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
-claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
-claude mcp add argus -- npx -y argusqa-os
-```
-
-**Step 2 — Start Chrome with remote debugging:**
-
-```bash
-# macOS
-open -a "Google Chrome" --args --remote-debugging-port=9222 --headless=new
-
-# Windows (PowerShell)
-& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --headless=new --no-sandbox --disable-gpu --user-data-dir="$env:TEMP\chrome-argus"
-
-# Linux
-google-chrome --remote-debugging-port=9222 --headless=new --no-sandbox
-```
-
-**Step 3 — Run an audit:**
-
-```
-Run argus_audit on http://localhost:3000
-```
-
-Argus scans your app and either posts findings to Slack or opens a local `report.html`. That's it.
-
----
-
-## What Argus Catches
-
-32 analysis engines, 140 distinct issue types, zero test-file maintenance:
-
-| Category | What it detects |
-|---|---|
-| **JavaScript** | Uncaught exceptions, unhandled promise rejections, `console.error` on critical routes |
-| **Network & API** | HTTP 5xx, 401/403 auth failures, duplicate API calls (infinite loops), 4xx errors, broken links |
-| **Performance** | LCP > 2500ms, CLS > 0.1, TTFB > 800ms, slow APIs > 1s/3s, payloads > 500KB/2MB, JS bundles > 500KB |
-| **Accessibility** | axe-core (80+ WCAG rules), color-blind simulation, missing ARIA, keyboard focus, heading hierarchy |
-| **SEO** | Missing meta description, OG tags, canonical, viewport, h1 |
-| **Security** | Auth tokens in localStorage/URL, `eval()`, missing CSP/X-Frame-Options, CSP violations, missing SRI on external scripts, source map exposure, open redirects, npm CVEs |
-| **CSS** | Cascade overrides, component style leaks, unused rules, React inline style conflicts |
-| **Content** | `null`/`undefined` as visible text, lorem ipsum, broken images, empty data lists |
-| **Responsive** | Horizontal overflow at 375px/768px, touch targets < 44×44px |
-| **Memory** | Detached DOM nodes via V8 heap snapshot, heap growth across navigation |
-| **Visual** | Pixel-level screenshot regression via pixelmatch (≥0.1% warning, ≥5% critical) |
-| **Figma** | Design-to-implementation fidelity — 13 property types (color, spacing, typography, shadows, etc.) |
-| **Forms** | Missing `required`, `autocomplete`, `aria-describedby`; unlabelled inputs |
-| **Fonts** | FOIT, FOUT, missing fallbacks, slow loads > 1s, suboptimal formats |
-| **Motion** | `prefers-reduced-motion` violations, `autoplay` without pause controls |
-| **Network baseline** | New requests, missing requests, status-code regressions vs saved HAR baseline |
-| **Environment diff** | Dev vs staging — screenshot diff, DOM changes, console/network regressions |
-
-And every finding is post-processed with:
-
-| Post-processor | What it adds |
-|---|---|
-| **Intelligent baseline filtering** | Findings that flip-flop across runs are tagged `noisy` and downgraded to info — pure cross-run heuristics, no API calls (`ARGUS_NOISE_FILTER=0` to disable) |
-| **Root cause linking** | New findings are annotated with the recent git commits and files most likely to have caused them (`ARGUS_ROOT_CAUSE=0` to disable) |
-
-> All findings are classified as `critical` / `warning` / `info` and routed to the right Slack channel — or surfaced in the local HTML report. For per-finding severity tables and detection methods, see [REFERENCE.md](REFERENCE.md).
-
----
-
-## MCP Tools
-
-Ask Claude (or any MCP client) — no terminal required:
-
-| Tool | Description |
-|---|---|
-| `argus_audit` | Fast pass — JS, network, accessibility, SEO, security, CSS, content |
-| `argus_audit_full` | Deep pass — adds Lighthouse, responsive checks, memory leak detection, hover-state bugs |
-| `argus_compare` | Diff dev vs staging — screenshots, findings delta, environment regressions |
-| `argus_get_context` | Capture everything broken on the open tab for Claude to diagnose |
-| `argus_watch_snapshot` | Snapshot the open tab without navigating (preserves auth/form state) |
-| `argus_last_report` | Return last JSON report without re-running |
-| `argus_design_audit` | Figma URL → 13 design-token finding types (color, spacing, typography, shadows, etc.) |
-| `argus_visual_diff` | Screenshot baseline comparison. Pass `updateBaseline: true` to reset. |
-| `argus_pr_validate` | Fetch GitHub PR diff → map changed files to affected routes → targeted audit → `{ blocked, findings }` |
-
-**Example prompts:**
-
-```
-Run argus_audit on http://localhost:3000/checkout
-Run argus_audit_full on http://localhost:3000/dashboard
-Run argus_compare
-Run argus_get_context
-```
-
----
-
-## Full Setup
-
-### Prerequisites
-
-| Requirement | Version |
-|---|---|
-| Node.js | v20.19+ |
-| Chrome | Stable (desktop or headless) |
-| Claude Code | Latest (`npm install -g @anthropic-ai/claude-code`) |
-| Slack workspace | **Optional** — omit for local `report.html` mode |
-
----
-
-### Option A — MCP Server *(recommended for Claude Code users)*
-
-No local install needed. Use the [Quick Start](#quick-start) above, then add your target URL:
-
-```env
-# .env in your project root
-TARGET_DEV_URL=http://localhost:3000
-TARGET_STAGING_URL=https://staging.example.com   # optional — enables argus_compare
-```
-
-**Optional — Slack notifications:**
-
-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 the `xoxb-...` token
-4. Create channels `#bugs-critical`, `#bugs-warnings`, `#bugs-digest` and run `/invite @BugBot` in each
-
-```env
-SLACK_BOT_TOKEN=xoxb-...
-SLACK_CHANNEL_CRITICAL=C0000000000
-SLACK_CHANNEL_WARNINGS=C0000000001
-SLACK_CHANNEL_DIGEST=C0000000002
-```
-
-> Without Slack: Argus auto-generates `reports/report.html` and opens it in your browser — zero extra config.
-
----
-
-### Option B — npm Package (CI / dev dependency)
-
-```bash
-npm install --save-dev argusqa-os
-npx argus init   # interactive wizard — detects framework, discovers routes, writes .env
-npm run crawl    # run after Chrome is started
-```
-
----
-
-### Option C — Clone the Repository (contributors / full source)
-
-```bash
-git clone https://github.com/ironclawdevs27/Argus.git
-cd Argus
-npm install
-npm run init     # interactive setup wizard
-```
-
-**Manual setup (skip the wizard):**
-
-```bash
-cp .env.example .env
-# Fill in TARGET_DEV_URL and optional Slack tokens
-```
-
-Then configure your routes in [src/config/targets.js](src/config/targets.js):
-
-```js
-export const routes = [
-  { path: '/',          name: 'Home',      critical: true,  waitFor: 'main' },
-  { path: '/login',     name: 'Login',     critical: true,  waitFor: 'form' },
-  { path: '/dashboard', name: 'Dashboard', critical: true,  waitFor: '[data-testid="dashboard"]' },
-  { path: '/settings',  name: 'Settings',  critical: false, waitFor: null },
-];
-```
-
-- `critical: true` — errors on this route go to `#bugs-critical`
-- `waitFor` — CSS selector Argus waits for before capturing (signals page-ready)
-
----
-
-## CLI Commands
-
-```bash
-npm run chrome         # Launch Chrome with --remote-debugging-port=9222 (auto-detects binary)
-npm run doctor         # Pre-flight check: Chrome reachable, .mcp.json valid, .env has TARGET_DEV_URL
-npm run crawl          # Batch audit of all configured routes
-npm run compare        # Dev vs staging diff (CSS-only if no staging URL)
-npm run watch          # Passive monitor — polls open Chrome tab every 1s
-npm run report:html    # Generate reports/report.html from last JSON audit
-npm run report:pdf     # Export HTML report to A4 PDF (requires: npm install puppeteer)
-npm run server         # Start Slack slash-command server (port 3001)
-npm run init           # Interactive setup wizard
-npm run test:unit          # 61 unit tests — no Chrome required
-npm run test:harness       # 139-block correctness harness — requires Chrome
-npm run test:harness:log   # same, but tees full output to harness-results.txt
-```
-
-**Watch mode** — live monitoring as you develop:
-
-```bash
-# Terminal 1: start your app
-npm run dev
-
-# Terminal 2: start Argus watcher
-npm run watch
-# Ctrl+C → stops monitor and writes reports/report.html
-```
-
-**Slack slash command** (on-demand from any channel):
-
-```
-/argus-retest https://staging.example.com/checkout
-```
-
-To expose the server via tunnel: `cloudflared tunnel --url http://localhost:3001` (free, no account required). Set the resulting URL as the Request URL in Slack App → Slash Commands.
-
----
-
-## GitHub Actions CI
-
-Add to your repo's secrets (Settings → Secrets → Actions):
-
-| Secret | Required | Value |
-|---|---|---|
-| `TARGET_STAGING_URL` | Yes | Your staging base URL |
-| `SLACK_BOT_TOKEN` | No | `xoxb-...` token (omit for HTML-only mode) |
-| `SLACK_CHANNEL_CRITICAL` | No* | Channel ID (needed when Slack is configured) |
-| `SLACK_CHANNEL_WARNINGS` | No* | Channel ID |
-| `SLACK_CHANNEL_DIGEST` | No* | Channel ID |
-| `GITHUB_TOKEN` | No | Auto-injected by Actions for PR comments + Check Runs |
-
-The included [workflow](.github/workflows/argus.yml) runs on push to `main`, daily at 6 AM UTC, and on manual trigger. If critical issues are found, the pipeline fails.
-
----
-
-## Environment Variables
-
-<details>
-<summary>Full reference (click to expand)</summary>
-
-| Variable | Default | Description |
-|---|---|---|
-| `TARGET_DEV_URL` | — | **Required.** Base URL of your dev environment |
-| `TARGET_STAGING_URL` | — | Staging URL — enables `argus_compare`; omit for CSS-only mode |
-| `SLACK_BOT_TOKEN` | — | `xoxb-...` token. Omit for local `report.html` mode |
-| `SLACK_SIGNING_SECRET` | — | For `/argus-retest` slash command verification |
-| `SLACK_CHANNEL_CRITICAL` | — | Channel ID for critical bugs |
-| `SLACK_CHANNEL_WARNINGS` | — | Channel ID for warnings |
-| `SLACK_CHANNEL_DIGEST` | — | Channel ID for info / daily digest |
-| `PORT` | `3001` | Slack slash-command server port |
-| `REPORT_OUTPUT_DIR` | `./reports` | Where to write JSON reports |
-| `ARGUS_CONCURRENCY` | `1` | Parallel MCP clients for route crawling |
-| `ARGUS_LOG_LEVEL` | `info` | `trace` / `debug` / `info` / `warn` / `error` |
-| `ARGUS_LOG_PRETTY` | — | Set `1` for human-readable logs in dev |
-| `ARGUS_RETRY_ATTEMPTS` | `3` | Max retries for `navigate`/`fill` MCP calls |
-| `ARGUS_WATCH_INTERVAL_MS` | `1000` | Watch mode poll interval (ms) |
-| `ARGUS_WATCH_UI_PORT` | `3002` | Watch mode web dashboard port |
-| `ARGUS_SOURCE_DIR` | — | App source path — enables env-var / feature-flag / dead-route analysis |
-| `ARGUS_ENV_FILE` | — | Path to app `.env` for codebase cross-reference |
-| `SCREENSHOT_DIFF_THRESHOLD` | `0.5` | Pixel diff % threshold for environment comparison |
-| `GITHUB_TOKEN` | — | For PR comments + Check Runs |
-| `GITHUB_REPOSITORY` | — | `owner/repo` format |
-| `GITHUB_PR_NUMBER` | — | Auto-injected by Actions from PR context |
-| `ARGUS_CRITICAL_THRESHOLD` | `1` | New criticals before blocking merge (0 = never block) |
-| `ARGUS_DIFF_IMAGE_URL` | — | Visual diff image URL to embed in PR comment |
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP collector for Jaeger / Grafana Tempo |
-| `FIGMA_API_TOKEN` | — | Required for `argus_design_audit` |
-| `FONT_SLOW_MS` | `1000` | Slow web font load threshold (ms) |
-| `A11Y_CONTRAST_AA` | `4.5` | WCAG AA min contrast ratio for CVD simulation |
-
-</details>
-
----
-
-## Troubleshooting
-
-**Chrome DevTools MCP not connecting**
-```bash
-claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
-# Restart Claude Code after adding
-```
-
-**Slack messages not posting**
-- Token must start with `xoxb-` (not `xoxp-`, `xoxe-`, or `xapp-`)
-- Run `/invite @BugBot` in each channel
-- Required scopes: `chat:write`, `files:write`, `files:read`
-
-**Screenshots are blank**
-- Page hasn't settled — increase `pageSettleMs` in `src/config/targets.js` or add a `waitFor` selector for the route
-
-**`/argus-retest` returns "dispatch_failed"**
-- Tunnel URL changed — update the Request URL in Slack App → Slash Commands and reinstall
-
-**CSS analysis returns empty results**
-- Page may be behind auth — ensure you're logged in on the Chrome instance Argus is controlling
-
-**CI pipeline fails immediately**
-- Chrome may not start fast enough — increase `sleep 3` to `sleep 5` in [.github/workflows/argus.yml](.github/workflows/argus.yml)
-
----
-
-## How Argus Differs From Playwright / Cypress
-
-Argus is a **complementary layer**, not a replacement for unit or E2E tests:
-
-| | Playwright / Cypress | Argus |
-|---|---|---|
-| **Purpose** | Test your logic and API contracts | Catch what the user actually sees |
-| **What it catches** | Regressions in behavior | CSS drift, visual regressions, API loops, console noise, perf budgets |
-| **When it runs** | In your test suite | Continuously, on the live running app |
-| **Setup** | Write test files | Configure routes in `targets.js` |
-| **Output** | Pass / fail | Structured Slack reports with screenshots |
-
----
-
-## Known Limitations
-
-All 679 harness assertions pass (`679/679`) — there are currently no known MCP- or Chrome-layer restrictions. Soft assertions (Lighthouse, performance traces) still require non-headless Chrome and are skipped in headless CI.
-
----
-
-## Project Structure
-
-```
-src/
-  argus.js              — single-page audit entry point
-  mcp-server.js         — 9 MCP tools exposed to Claude / any MCP client
-  orchestration/        — crawl loop, Slack/GitHub dispatch, env comparison, watch mode
-  utils/                — 32 analysis engines (accessibility, security, performance, PDF, recording, etc.)
-  adapters/browser.js   — CdpBrowserAdapter — wraps all chrome-devtools-mcp calls
-  config/targets.js     — routes, thresholds, auth steps
-  cli/
-    init.js             — argus init interactive setup wizard
-    chrome-launcher.js  — npm run chrome / argus-chrome — launches Chrome with correct flags
-    doctor.js           — npm run doctor / argus-doctor — pre-flight checks
-    pr-validate.js      — headless CI entry point for GitHub Actions
-test-harness/           — 139-block correctness harness, 664 hard assertions, 62 fixture pages
-test/unit/              — 61 Vitest unit tests (no Chrome required)
-landing/                — Product landing page (React 19 + Vite + Tailwind)
-```
-
-Full source map → [CLAUDE.md](CLAUDE.md) · MCP/DSL reference → [SKILL.md](SKILL.md)
-
----
-
-## Contributing
-
-1. Fork the repo and create a branch
-2. `npm run test:unit` — verify without Chrome (61 tests)
-3. `npm run test:harness` — full integration coverage (requires Chrome on port 9222)
-4. Open a PR — Argus audits itself via the CI workflow
-
----
-
-## License
-
-MIT © [ironclawdevs27](https://github.com/ironclawdevs27)
-
----
-
-<div align="center">
-
-*Argus Panoptes — the all-seeing giant of Greek mythology who never slept.*
-
-[argus-qa.com](https://argus-qa.com) · [npm](https://www.npmjs.com/package/argusqa-os) · [MCP Registry](https://glama.ai/mcp/servers/ironclawdevs27/Argus)
-
-</div>
+<div align="center">
+
+# Argus — AI-Powered Automated QA
+
+[![npm](https://img.shields.io/npm/v/argusqa-os?color=7C3AED)](https://www.npmjs.com/package/argusqa-os)
+[![MCP Server](https://glama.ai/mcp/servers/ironclawdevs27/Argus/badges/card.svg)](https://glama.ai/mcp/servers/ironclawdevs27/Argus)
+[![Harness](https://img.shields.io/badge/harness-688%2F688-4ADE80)](test-harness/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Argus catches the bugs your test suite misses — visual regressions, API loops, CSS drift, console noise, accessibility failures, and more — and delivers rich reports to Slack (or a local HTML dashboard).**
+
+[Quick Start](#quick-start) · [Features](#what-argus-catches) · [Setup](#full-setup) · [MCP Tools](#mcp-tools) · [CLI Commands](#cli-commands) · [Troubleshooting](#troubleshooting) · [Full Reference](REFERENCE.md)
+
+</div>
+
+---
+
+## Quick Start
+
+> **No install required.** `npx` auto-downloads Argus on first run.
+
+**Step 1 — 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
+claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
+claude mcp add argus -- npx -y argusqa-os
+```
+
+**Step 2 — Start Chrome with remote debugging:**
+
+```bash
+# macOS
+open -a "Google Chrome" --args --remote-debugging-port=9222 --headless=new
+
+# Windows (PowerShell)
+& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --headless=new --no-sandbox --disable-gpu --user-data-dir="$env:TEMP\chrome-argus"
+
+# Linux
+google-chrome --remote-debugging-port=9222 --headless=new --no-sandbox
+```
+
+**Step 3 — Run an audit:**
+
+```
+Run argus_audit on http://localhost:3000
+```
+
+Argus scans your app and either posts findings to Slack or opens a local `report.html`. That's it.
+
+---
+
+## What Argus Catches
+
+32 analysis engines, 140 distinct issue types, zero test-file maintenance:
+
+| Category | What it detects |
+|---|---|
+| **JavaScript** | Uncaught exceptions, unhandled promise rejections, `console.error` on critical routes |
+| **Network & API** | HTTP 5xx, 401/403 auth failures, duplicate API calls (infinite loops), 4xx errors, broken links |
+| **Performance** | LCP > 2500ms, CLS > 0.1, TTFB > 800ms, slow APIs > 1s/3s, payloads > 500KB/2MB, JS bundles > 500KB |
+| **Accessibility** | axe-core (80+ WCAG rules), color-blind simulation, missing ARIA, keyboard focus, heading hierarchy |
+| **SEO** | Missing meta description, OG tags, canonical, viewport, h1 |
+| **Security** | Auth tokens in localStorage/URL, `eval()`, missing CSP/X-Frame-Options, CSP violations, missing SRI on external scripts, source map exposure, open redirects, npm CVEs |
+| **CSS** | Cascade overrides, component style leaks, unused rules, React inline style conflicts |
+| **Content** | `null`/`undefined` as visible text, lorem ipsum, broken images, empty data lists |
+| **Responsive** | Horizontal overflow at 375px/768px, touch targets < 44×44px |
+| **Memory** | Detached DOM nodes via V8 heap snapshot, heap growth across navigation |
+| **Visual** | Pixel-level screenshot regression via pixelmatch (≥0.1% warning, ≥5% critical) |
+| **Figma** | Design-to-implementation fidelity — 13 property types (color, spacing, typography, shadows, etc.) |
+| **Forms** | Missing `required`, `autocomplete`, `aria-describedby`; unlabelled inputs |
+| **Fonts** | FOIT, FOUT, missing fallbacks, slow loads > 1s, suboptimal formats |
+| **Motion** | `prefers-reduced-motion` violations, `autoplay` without pause controls |
+| **Network baseline** | New requests, missing requests, status-code regressions vs saved HAR baseline |
+| **Environment diff** | Dev vs staging — screenshot diff, DOM changes, console/network regressions |
+
+And every finding is post-processed with:
+
+| Post-processor | What it adds |
+|---|---|
+| **Intelligent baseline filtering** | Findings that flip-flop across runs are tagged `noisy` and downgraded to info — pure cross-run heuristics, no API calls (`ARGUS_NOISE_FILTER=0` to disable) |
+| **Root cause linking** | New findings are annotated with the recent git commits and files most likely to have caused them (`ARGUS_ROOT_CAUSE=0` to disable) |
+
+> All findings are classified as `critical` / `warning` / `info` and routed to the right Slack channel — or surfaced in the local HTML report. For per-finding severity tables and detection methods, see [REFERENCE.md](REFERENCE.md).
+
+---
+
+## MCP Tools
+
+Ask Claude (or any MCP client) — no terminal required:
+
+| Tool | Description |
+|---|---|
+| `argus_audit` | Fast pass — JS, network, accessibility, SEO, security, CSS, content |
+| `argus_audit_full` | Deep pass — adds Lighthouse, responsive checks, memory leak detection, hover-state bugs |
+| `argus_compare` | Diff dev vs staging — screenshots, findings delta, environment regressions |
+| `argus_get_context` | Capture everything broken on the open tab for Claude to diagnose |
+| `argus_watch_snapshot` | Snapshot the open tab without navigating (preserves auth/form state) |
+| `argus_last_report` | Return last JSON report without re-running |
+| `argus_design_audit` | Figma URL → 13 design-token finding types (color, spacing, typography, shadows, etc.) |
+| `argus_visual_diff` | Screenshot baseline comparison. Pass `updateBaseline: true` to reset. |
+| `argus_pr_validate` | Fetch GitHub PR diff → map changed files to affected routes → targeted audit → `{ blocked, findings }` |
+
+**Example prompts:**
+
+```
+Run argus_audit on http://localhost:3000/checkout
+Run argus_audit_full on http://localhost:3000/dashboard
+Run argus_compare
+Run argus_get_context
+```
+
+---
+
+## Full Setup
+
+### Prerequisites
+
+| Requirement | Version |
+|---|---|
+| Node.js | v20.19+ |
+| Chrome | Stable (desktop or headless) |
+| Claude Code | Latest (`npm install -g @anthropic-ai/claude-code`) |
+| Slack workspace | **Optional** — omit for local `report.html` mode |
+
+---
+
+### Option A — MCP Server *(recommended for Claude Code users)*
+
+No local install needed. Use the [Quick Start](#quick-start) above, then add your target URL:
+
+```env
+# .env in your project root
+TARGET_DEV_URL=http://localhost:3000
+TARGET_STAGING_URL=https://staging.example.com   # optional — enables argus_compare
+```
+
+**Optional — Slack notifications:**
+
+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 the `xoxb-...` token
+4. Create channels `#bugs-critical`, `#bugs-warnings`, `#bugs-digest` and run `/invite @BugBot` in each
+
+```env
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_CHANNEL_CRITICAL=C0000000000
+SLACK_CHANNEL_WARNINGS=C0000000001
+SLACK_CHANNEL_DIGEST=C0000000002
+```
+
+> Without Slack: Argus auto-generates `reports/report.html` and opens it in your browser — zero extra config.
+
+---
+
+### Option B — npm Package (CI / dev dependency)
+
+```bash
+npm install --save-dev argusqa-os
+npx argus init   # interactive wizard — detects framework, discovers routes, writes .env
+npm run crawl    # run after Chrome is started
+```
+
+---
+
+### Option C — Clone the Repository (contributors / full source)
+
+```bash
+git clone https://github.com/ironclawdevs27/Argus.git
+cd Argus
+npm install
+npm run init     # interactive setup wizard
+```
+
+**Manual setup (skip the wizard):**
+
+```bash
+cp .env.example .env
+# Fill in TARGET_DEV_URL and optional Slack tokens
+```
+
+Then configure your routes in [src/config/targets.js](src/config/targets.js):
+
+```js
+export const routes = [
+  { path: '/',          name: 'Home',      critical: true,  waitFor: 'main' },
+  { path: '/login',     name: 'Login',     critical: true,  waitFor: 'form' },
+  { path: '/dashboard', name: 'Dashboard', critical: true,  waitFor: '[data-testid="dashboard"]' },
+  { path: '/settings',  name: 'Settings',  critical: false, waitFor: null },
+];
+```
+
+- `critical: true` — errors on this route go to `#bugs-critical`
+- `waitFor` — CSS selector Argus waits for before capturing (signals page-ready)
+
+---
+
+## CLI Commands
+
+```bash
+npm run chrome         # Launch Chrome with --remote-debugging-port=9222 (auto-detects binary)
+npm run doctor         # Pre-flight check: Chrome reachable, .mcp.json valid, .env has TARGET_DEV_URL
+npm run crawl          # Batch audit of all configured routes
+npm run compare        # Dev vs staging diff (CSS-only if no staging URL)
+npm run watch          # Passive monitor — polls open Chrome tab every 1s
+npm run report:html    # Generate reports/report.html from last JSON audit
+npm run report:pdf     # Export HTML report to A4 PDF (requires: npm install puppeteer)
+npm run server         # Start Slack slash-command server (port 3001)
+npm run init           # Interactive setup wizard
+npm run test:unit          # 61 unit tests — no Chrome required
+npm run test:harness       # 142-block correctness harness — requires Chrome
+npm run test:harness:log   # same, but tees full output to harness-results.txt
+```
+
+**Watch mode** — live monitoring as you develop:
+
+```bash
+# Terminal 1: start your app
+npm run dev
+
+# Terminal 2: start Argus watcher
+npm run watch
+# Ctrl+C → stops monitor and writes reports/report.html
+```
+
+**Slack slash command** (on-demand from any channel):
+
+```
+/argus-retest https://staging.example.com/checkout
+```
+
+To expose the server via tunnel: `cloudflared tunnel --url http://localhost:3001` (free, no account required). Set the resulting URL as the Request URL in Slack App → Slash Commands.
+
+---
+
+## GitHub Actions CI
+
+Add to your repo's secrets (Settings → Secrets → Actions):
+
+| Secret | Required | Value |
+|---|---|---|
+| `TARGET_STAGING_URL` | Yes | Your staging base URL |
+| `SLACK_BOT_TOKEN` | No | `xoxb-...` token (omit for HTML-only mode) |
+| `SLACK_CHANNEL_CRITICAL` | No* | Channel ID (needed when Slack is configured) |
+| `SLACK_CHANNEL_WARNINGS` | No* | Channel ID |
+| `SLACK_CHANNEL_DIGEST` | No* | Channel ID |
+| `GITHUB_TOKEN` | No | Auto-injected by Actions for PR comments + Check Runs |
+
+The included [workflow](.github/workflows/argus.yml) runs on push to `main`, daily at 6 AM UTC, and on manual trigger. If critical issues are found, the pipeline fails.
+
+---
+
+## Environment Variables
+
+<details>
+<summary>Full reference (click to expand)</summary>
+
+| Variable | Default | Description |
+|---|---|---|
+| `TARGET_DEV_URL` | — | **Required.** Base URL of your dev environment |
+| `TARGET_STAGING_URL` | — | Staging URL — enables `argus_compare`; omit for CSS-only mode |
+| `SLACK_BOT_TOKEN` | — | `xoxb-...` token. Omit for local `report.html` mode |
+| `SLACK_SIGNING_SECRET` | — | For `/argus-retest` slash command verification |
+| `SLACK_CHANNEL_CRITICAL` | — | Channel ID for critical bugs |
+| `SLACK_CHANNEL_WARNINGS` | — | Channel ID for warnings |
+| `SLACK_CHANNEL_DIGEST` | — | Channel ID for info / daily digest |
+| `PORT` | `3001` | Slack slash-command server port |
+| `REPORT_OUTPUT_DIR` | `./reports` | Where to write JSON reports |
+| `ARGUS_CONCURRENCY` | `1` | Parallel MCP clients for route crawling |
+| `ARGUS_LOG_LEVEL` | `info` | `trace` / `debug` / `info` / `warn` / `error` |
+| `ARGUS_LOG_PRETTY` | — | Set `1` for human-readable logs in dev |
+| `ARGUS_RETRY_ATTEMPTS` | `3` | Max retries for `navigate`/`fill` MCP calls |
+| `ARGUS_WATCH_INTERVAL_MS` | `1000` | Watch mode poll interval (ms) |
+| `ARGUS_WATCH_UI_PORT` | `3002` | Watch mode web dashboard port |
+| `ARGUS_SOURCE_DIR` | — | App source path — enables env-var / feature-flag / dead-route analysis |
+| `ARGUS_ENV_FILE` | — | Path to app `.env` for codebase cross-reference |
+| `SCREENSHOT_DIFF_THRESHOLD` | `0.5` | Pixel diff % threshold for environment comparison |
+| `GITHUB_TOKEN` | — | For PR comments + Check Runs |
+| `GITHUB_REPOSITORY` | — | `owner/repo` format |
+| `GITHUB_PR_NUMBER` | — | Auto-injected by Actions from PR context |
+| `ARGUS_CRITICAL_THRESHOLD` | `1` | New criticals before blocking merge (0 = never block) |
+| `ARGUS_DIFF_IMAGE_URL` | — | Visual diff image URL to embed in PR comment |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP collector for Jaeger / Grafana Tempo |
+| `FIGMA_API_TOKEN` | — | Required for `argus_design_audit` |
+| `FONT_SLOW_MS` | `1000` | Slow web font load threshold (ms) |
+| `A11Y_CONTRAST_AA` | `4.5` | WCAG AA min contrast ratio for CVD simulation |
+
+</details>
+
+---
+
+## Troubleshooting
+
+**Chrome DevTools MCP not connecting**
+```bash
+claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
+# Restart Claude Code after adding
+```
+
+**Slack messages not posting**
+- Token must start with `xoxb-` (not `xoxp-`, `xoxe-`, or `xapp-`)
+- Run `/invite @BugBot` in each channel
+- Required scopes: `chat:write`, `files:write`, `files:read`
+
+**Screenshots are blank**
+- Page hasn't settled — increase `pageSettleMs` in `src/config/targets.js` or add a `waitFor` selector for the route
+
+**`/argus-retest` returns "dispatch_failed"**
+- Tunnel URL changed — update the Request URL in Slack App → Slash Commands and reinstall
+
+**CSS analysis returns empty results**
+- Page may be behind auth — ensure you're logged in on the Chrome instance Argus is controlling
+
+**CI pipeline fails immediately**
+- Chrome may not start fast enough — increase `sleep 3` to `sleep 5` in [.github/workflows/argus.yml](.github/workflows/argus.yml)
+
+---
+
+## How Argus Differs From Playwright / Cypress
+
+Argus is a **complementary layer**, not a replacement for unit or E2E tests:
+
+| | Playwright / Cypress | Argus |
+|---|---|---|
+| **Purpose** | Test your logic and API contracts | Catch what the user actually sees |
+| **What it catches** | Regressions in behavior | CSS drift, visual regressions, API loops, console noise, perf budgets |
+| **When it runs** | In your test suite | Continuously, on the live running app |
+| **Setup** | Write test files | Configure routes in `targets.js` |
+| **Output** | Pass / fail | Structured Slack reports with screenshots |
+
+---
+
+## Known Limitations
+
+All 688 harness assertions pass (`688/688`) — there are currently no known MCP- or Chrome-layer restrictions. Soft assertions (Lighthouse, performance traces) still require non-headless Chrome and are skipped in headless CI.
+
+---
+
+## Project Structure
+
+```
+src/
+  argus.js              — single-page audit entry point
+  mcp-server.js         — 9 MCP tools exposed to Claude / any MCP client
+  orchestration/        — crawl loop, Slack/GitHub dispatch, env comparison, watch mode
+  utils/                — 32 analysis engines (accessibility, security, performance, PDF, recording, etc.)
+  adapters/browser.js   — CdpBrowserAdapter — wraps all chrome-devtools-mcp calls
+  config/targets.js     — routes, thresholds, auth steps
+  cli/
+    init.js             — argus init interactive setup wizard
+    chrome-launcher.js  — npm run chrome / argus-chrome — launches Chrome with correct flags
+    doctor.js           — npm run doctor / argus-doctor — pre-flight checks
+    pr-validate.js      — headless CI entry point for GitHub Actions
+test-harness/           — 142-block correctness harness, 688 hard assertions, 62 fixture pages
+test/unit/              — 61 Vitest unit tests (no Chrome required)
+landing/                — Product landing page (React 19 + Vite + Tailwind)
+```
+
+Full source map → [CLAUDE.md](CLAUDE.md) · MCP/DSL reference → [SKILL.md](SKILL.md)
+
+---
+
+## Contributing
+
+1. Fork the repo and create a branch
+2. `npm run test:unit` — verify without Chrome (61 tests)
+3. `npm run test:harness` — full integration coverage (requires Chrome on port 9222)
+4. Open a PR — Argus audits itself via the CI workflow
+
+---
+
+## License
+
+MIT © [ironclawdevs27](https://github.com/ironclawdevs27)
+
+---
+
+<div align="center">
+
+*Argus Panoptes — the all-seeing giant of Greek mythology who never slept.*
+
+[argus-qa.com](https://argus-qa.com) · [npm](https://www.npmjs.com/package/argusqa-os) · [MCP Registry](https://glama.ai/mcp/servers/ironclawdevs27/Argus)
+
+</div>

package/glama.json

@@ -1,12 +1,12 @@
 {
   "$schema": "https://glama.ai/mcp/schemas/server.json",
   "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. 9 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), argus_design_audit (Figma design fidelity — 13 finding types), argus_visual_diff (screenshot baseline comparison, updateBaseline flag), argus_pr_validate (PR diff → affected routes → targeted audit → blocked flag). Every finding is post-processed with intelligent baseline filtering (cross-run noise classifier) and root cause linking (recent git commits mapped to new findings). 141 test blocks, 679 hard assertions, 67 detection categories.",
+  "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. 9 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), argus_design_audit (Figma design fidelity — 13 finding types), argus_visual_diff (screenshot baseline comparison, updateBaseline flag), argus_pr_validate (PR diff → affected routes → targeted audit → blocked flag). Every finding is post-processed with intelligent baseline filtering (cross-run noise classifier) and root cause linking (recent git commits mapped to new findings). 142 test blocks, 688 hard assertions, 67 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."
+      "description": "Fast QA audit — JS errors, network failures (4xx/5xx), CORS, API frequency loops, slow/blocking third-party requests, API contract violations, SEO violations, security headers, content quality, DevTools Issues panel, and HTTPS enforcement. Returns { findings, summary }. Supports cache: true to skip re-crawl on repeat calls."
     },
     {
       "name": "argus_audit_full",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argusqa-os",
-  "version": "9.7.3",
+  "version": "9.7.4",
   "mcpName": "io.github.ironclawdevs27/argus",
   "description": "Argus — AI-powered automated dev-testing platform using Chrome DevTools MCP and Claude Code",
   "keywords": [
@@ -48,7 +48,7 @@
     "watch": "node src/orchestration/watch-mode.js",
     "server": "node src/server/index.js",
     "harness": "node test-harness/server.js",
-    "harness:staging": "PORT=3101 node test-harness/server.js",
+    "harness:staging": "node test-harness/server.js --port=3101 --staging",
     "test:harness": "node --env-file=test-harness/.env.harness test-harness/validate.js",
     "test:harness:log": "node test-harness/run-with-log.mjs",
     "test:unit": "vitest run test/unit",

package/src/adapters/browser.js

@@ -52,15 +52,22 @@ export class CdpBrowserAdapter {
   resize(w, h)                   { return this._mcp.resize_page({ width: w, height: h }); }
 
   // ── Network & performance ───────────────────────────────────────────────────
-  getNetworkRequest(reqId) { return this._mcp.get_network_request({ requestId: reqId }); }
+  // chrome-devtools-mcp expects the wire parameter "reqid" (sending "requestId"
+  // is rejected with an Unknown-argument error). Callers still pass the numeric
+  // requestId parsed from list_network_requests.
+  getNetworkRequest(reqId) { return this._mcp.get_network_request({ reqid: reqId }); }
   lighthouse(url, opts = {}) { return this._mcp.lighthouse_audit({ url, ...opts }); }
   startTrace()             { return this._mcp.performance_start_trace({}); }
   stopTrace()              { return this._mcp.performance_stop_trace({}); }
   analyzeInsight(opts)     { return this._mcp.performance_analyze_insight(opts); }
 
   // ── Tab management ─────────────────────────────────────────────────────────
+  // list_pages returns markdown text ("## Pages\n1: <url> [selected]") like all
+  // MCP responses — callers parse with parseListPagesResponse (mcp-parsers.js).
   listPages()              { return this._mcp.list_pages({}); }
-  selectPage(tabId)        { return this._mcp.select_page({ pageId: tabId }); }
+  // select_page validates pageId as a number — coerce so callers may pass the
+  // string tabId they received from an MCP tool argument.
+  selectPage(tabId)        { return this._mcp.select_page({ pageId: Number(tabId) }); }
 
   // ── Lifecycle ───────────────────────────────────────────────────────────────
   close()                  { return this._mcp.close(); }

package/src/cli/doctor.js

@@ -47,7 +47,7 @@ export function checkMcpConfig(filePath = '.mcp.json') {
   if (!fs.existsSync(filePath)) {
     return {
       ok:     false,
-      detail: `${path.basename(filePath)} not found — run \`argus init\` or copy .mcp.json from the Argus repo`,
+      detail: `${path.basename(filePath)} not found — create it with: {"mcpServers":{"chrome-devtools":{"command":"npx","args":["-y","chrome-devtools-mcp@1.1.1"]}}}`,
     };
   }
   let parsed;
@@ -63,7 +63,7 @@ export function checkMcpConfig(filePath = '.mcp.json') {
     return cmd.includes('chrome-devtools') || args.some(a => a.includes('chrome-devtools'));
   });
   if (!hasCdp) {
-    return { ok: false, detail: 'No chrome-devtools MCP server entry found in mcpServers' };
+    return { ok: false, detail: 'No chrome-devtools entry in mcpServers — add: "chrome-devtools": {"command":"npx","args":["-y","chrome-devtools-mcp@1.1.1"]}' };
   }
   return { ok: true, detail: `${Object.keys(servers).length} server(s) configured` };
 }

package/src/cli/pr-validate.js

@@ -230,6 +230,11 @@ async function main() {
     const files = await fetchPrFiles(prUrl, token);
     changedFiles.push(...files);
     console.log(`[argus] ${files.length} changed file(s)`);
+    if (files.length >= 300) {
+      // CI annotation lives here (CLI owns stdout) — fetchPrFiles itself only
+      // logs to stderr so the MCP server's JSON-RPC stdout stays clean.
+      console.log('::warning::PR has 300+ changed files — Argus analyzed the first 300. Routes affected by later files may be missed.');
+    }
 
     // Step 2: Map changed files to affected routes
     const routes   = await loadRoutes();

package/src/mcp-server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Argus MCP Server (v9.6.6)
+ * Argus MCP Server
  *
  * Exposes Argus as an MCP server so Claude (or any MCP client) can call
  * argus_audit, argus_audit_full, argus_compare, argus_last_report, and
@@ -24,8 +24,11 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import fs   from 'fs';
 import path from 'path';
+import { createRequire } from 'module';
 
 import { createMcpClient }                    from './utils/mcp-client.js';
+import { childLogger }                        from './utils/logger.js';
+import { parseListPagesResponse }             from './utils/mcp-parsers.js';
 import { crawlRouteCheap, runCrawl }          from './orchestration/crawl-and-report.js';
 import { runComparison }                      from './orchestration/env-comparison.js';
 import { WatchSession }                       from './orchestration/watch-mode.js';
@@ -35,6 +38,13 @@ import { analyzeDesignFidelity }             from './utils/design-fidelity-analy
 import { analyzeVisualRegression }           from './utils/visual-diff-analyzer.js';
 import { fetchPrFiles, mapFilesToRoutes } from './utils/pr-diff-analyzer.js';
 
+const logger = childLogger('mcp-server');
+
+// Read version from package.json so the MCP server always self-reports the
+// published package version (a hardcoded string here drifted in the past).
+const require_ = createRequire(import.meta.url);
+const pkg = require_('../package.json');
+
 const REPORTS_DIR = path.resolve(process.cwd(), 'reports');
 
 // Fix loop: stores up to 20 snapshots keyed by snapshot_id so argus_get_context
@@ -65,7 +75,7 @@ function cacheAudit(url, result) {
 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. 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.',
+    description: 'Fast QA audit on a URL via Chrome DevTools Protocol. One-pass detection sweep: JS errors, unhandled rejections, network failures (4xx/5xx), CORS errors, API frequency loops, slow APIs and blocking third-party requests, API contract violations, sync XHR, document.write, long tasks, service worker failures, debugger statements, duplicate IDs, SEO violations, security header checks, content quality, Chrome DevTools Issues panel, and HTTPS enforcement. 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, CSS analysis, responsive checks, and memory leak detection, use argus_audit_full. Requires Chrome running with --remote-debugging-port=9222.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -181,6 +191,9 @@ async function withMcp(fn) {
 async function handleAudit({ url, critical = false, cache = false }) {
   if (cache && auditCache.has(url)) {
     const { result, ts } = auditCache.get(url);
+    // Refresh recency on read so eviction is true LRU, not insertion-order FIFO.
+    auditCache.delete(url);
+    auditCache.set(url, { result, ts });
     return { content: [{ type: 'text', text: JSON.stringify({ ...result, _cached: true, _cachedAt: new Date(ts).toISOString() }, null, 2) }] };
   }
   return withMcp(async (mcp) => {
@@ -243,12 +256,13 @@ async function handleGetContext({ url, snapshot_id: prevId, tabId } = {}) {
     const { findings, newConsole, newNetwork } = await session.poll();
 
     // List all open tabs so the caller can target a specific tab on the next call.
+    // list_pages returns markdown text ("## Pages\n1: <url> [selected]") — parse
+    // it like every other MCP response; treating it as a structured array left
+    // open_tabs permanently empty.
     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 }));
-      }
+      const pages = parseListPagesResponse(await browser.listPages());
+      open_tabs = pages.map(p => ({ id: p.id, url: p.url, selected: p.selected }));
     } catch { /* list_pages not available in all Chrome configs — degrade gracefully */ }
 
     const newId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
@@ -397,8 +411,12 @@ async function handlePrValidate({ prUrl, targetUrl, githubToken, blockOn } = {})
   const allFindings = [];
   const perRoute    = [];
 
+  // Preserve any path prefix in the target URL (e.g. http://host/app) — new URL()
+  // with a leading-slash path would drop it. Mirrors src/cli/pr-validate.js.
+  const baseUrl = String(base).replace(/\/$/, '');
   for (const route of affectedRoutes) {
-    const url = new URL(route.path, base).href;
+    const routePath = String(route.path ?? '/').startsWith('/') ? route.path : `/${route.path}`;
+    const url = `${baseUrl}${routePath}`;
     const res = await handleAudit({ url, critical: route.critical ?? false });
     const data = JSON.parse(res.content[0].text);
     allFindings.push(...(data.findings ?? []));
@@ -447,7 +465,7 @@ async function handleLastReport() {
 // ── Server bootstrap ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'argus', version: '9.6.6' },
+  { name: 'argus', version: pkg.version },
   { capabilities: { tools: {} } },
 );
 

package/src/orchestration/watch-mode.js

@@ -298,6 +298,13 @@ function classifyNetworkReq(req, url) {
  * the interval-based runWatchMode() entry point.
  */
 export class WatchSession {
+  // Long-run safety caps: a watch session left running for hours against an app
+  // with cache-busted polling URLs would otherwise grow the dedup sets without
+  // bound. When a set exceeds its cap the oldest fifth is evicted (Sets iterate
+  // in insertion order) — worst case a very old message is re-reported once.
+  static MAX_SEEN_KEYS    = 5000;
+  static MAX_ALL_FINDINGS = 2000;
+
   constructor(browser, baseUrl) {
     this._browser     = browser;
     this._baseUrl     = baseUrl;
@@ -306,6 +313,14 @@ export class WatchSession {
     this._allFindings = [];
   }
 
+  /** Evict the oldest 20% of a dedup set once it exceeds the cap. */
+  static _trimSeen(set) {
+    if (set.size <= WatchSession.MAX_SEEN_KEYS) return;
+    const drop = Math.floor(WatchSession.MAX_SEEN_KEYS / 5);
+    const it = set.values();
+    for (let i = 0; i < drop; i++) set.delete(it.next().value);
+  }
+
   /**
    * Run one poll cycle.
    *
@@ -350,6 +365,11 @@ export class WatchSession {
     findings.push(...analyzeSecurityNetwork(newNetwork, this._baseUrl));
 
     this._allFindings.push(...findings);
+    if (this._allFindings.length > WatchSession.MAX_ALL_FINDINGS) {
+      this._allFindings = this._allFindings.slice(-WatchSession.MAX_ALL_FINDINGS);
+    }
+    WatchSession._trimSeen(this._seenConsole);
+    WatchSession._trimSeen(this._seenNetwork);
     return { findings, newConsole, newNetwork };
   }
 

package/src/utils/contract-validator.js

@@ -125,6 +125,32 @@ function loadSchema(contract) {
   return null;
 }
 
+/**
+ * Extract and JSON-parse the response body from a get_network_request result.
+ *
+ * chrome-devtools-mcp returns the request detail as markdown text with the
+ * body under a "### Response Body" section — the dominant production shape.
+ * Structured shapes ({ responseBody } / { body }) are kept for legacy clients.
+ *
+ * @param {any} raw - Raw value returned by browser.getNetworkRequest()
+ * @returns {any|null} Parsed JSON body, or null when absent
+ * @throws {SyntaxError} when a body section exists but is not valid JSON
+ */
+export function extractResponseBody(raw) {
+  if (raw == null) return null;
+  if (typeof raw === 'object') {
+    const text = raw.responseBody ?? raw.body ?? null;
+    if (text == null) return null;
+    return typeof text === 'string' ? JSON.parse(text) : text;
+  }
+  const text = String(raw);
+  const m = text.match(/### Response Body\s*\n([\s\S]*?)(?=\n###? |$)/);
+  if (!m) return null;
+  const section = m[1].trim();
+  if (!section) return null;
+  return JSON.parse(section);
+}
+
 /**
  * Validate captured network requests against apiContracts[].
  * For each request that matches a contract, fetches the response body via
@@ -153,8 +179,7 @@ export async function validateApiContracts(networkReqs, browser, contracts, page
       let body = null;
       try {
         const raw = await browser.getNetworkRequest(req.id ?? req.requestId);
-        const text = raw?.responseBody ?? raw?.body ?? null;
-        if (text) body = JSON.parse(text);
+        body = extractResponseBody(raw);
       } catch {
         continue; // body unavailable — skip validation for this request
       }

package/src/utils/mcp-parsers.js

@@ -55,3 +55,23 @@ export function parseNetworkReqResponse(raw) {
   }
   return reqs;
 }
+
+/**
+ * Parse the text response from list_pages.
+ * Format: "## Pages\n1: http://host/page.html [selected]\n2: about:blank"
+ * The numeric prefix is the pageId that select_page expects (as a number).
+ * @param {any} raw - Raw value returned by the MCP tool
+ * @returns {Array<{ id: number, url: string, selected: boolean }>}
+ */
+export function parseListPagesResponse(raw) {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw !== 'string') return [];
+  const pages = [];
+  const re = /^(\d+):\s+(\S+)(\s+\[selected\])?\s*$/gm;
+  let m;
+  while ((m = re.exec(raw)) !== null) {
+    pages.push({ id: Number(m[1]), url: m[2], selected: Boolean(m[3]) });
+  }
+  return pages;
+}

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

@@ -7,8 +7,16 @@
  *
  * Pure functions + one async fetch — no Chrome, no MCP, no AI verdict.
  * AI verdict logic ships separately in the private argus-pro repo.
+ *
+ * This module is imported by the MCP server — nothing here may write to
+ * stdout (reserved for JSON-RPC). CI annotations are emitted by the CLI
+ * entry point (src/cli/pr-validate.js), which owns stdout.
  */
 
+import { childLogger } from './logger.js';
+
+const logger = childLogger('pr-diff-analyzer');
+
 /**
  * Parse a GitHub PR URL into its owner/repo/prNumber components.
  *
@@ -59,7 +67,7 @@ export async function fetchPrFiles(prUrl, githubToken) {
   }
 
   if (allFiles.length >= 300) {
-    console.log('::warning::PR has 300+ changed files — Argus analyzed the first 300. Routes affected by later files may be missed.');
+    logger.warn('[ARGUS] PR has 300+ changed files — Argus analyzed the first 300. Routes affected by later files may be missed.');
   }
 
   return allFiles;

package/src/utils/root-cause-linker.js

@@ -56,13 +56,19 @@ export function getRecentChanges(repoDir = process.env.ARGUS_SOURCE_DIR || proce
   const changes = [];
   let current = null;
   for (const line of out.split('\n')) {
-    const trimmed = line.trimEnd();
-    if (!trimmed) continue;
-    if (trimmed.includes('\t')) {
-      const [hash, ...subjectParts] = trimmed.split('\t');
+    // Detect commit lines on the RAW line — an empty commit subject leaves a
+    // trailing tab ("abc1234\t") that trimEnd() would strip, misclassifying
+    // the hash as a file path. File lines never contain raw tabs: git quotes
+    // paths with special characters (core.quotePath octal escapes).
+    if (line.includes('\t')) {
+      const [hash, ...subjectParts] = line.trimEnd().split('\t');
       current = { hash, subject: subjectParts.join('\t'), files: [] };
       changes.push(current);
-    } else if (current) {
+      continue;
+    }
+    const trimmed = line.trimEnd();
+    if (!trimmed) continue;
+    if (current) {
       // Git emits paths with forward slashes on every platform
       current.files.push(trimmed);
     }