argus-testing 0.6.0__tar.gz → 0.7.0__tar.gz

argus_testing-0.7.0/.dockerignore

@@ -0,0 +1,19 @@
+.git
+.github
+.codex
+.venv
+**/__pycache__
+*.py[cod]
+.pytest_cache
+.ruff_cache
+.coverage
+build
+dist
+*.egg-info
+argus-reports
+test-reports
+screenshots
+tests
+test-site
+docs
+.DS_Store

{argus_testing-0.6.0 → argus_testing-0.7.0}/.github/workflows/ci.yml

@@ -29,7 +29,16 @@ jobs:
           cache: pip
       - name: Install package
         run: python -m pip install --upgrade pip && python -m pip install -e '.[dev]'
+      - name: Smoke-test package import
+        run: python -c "from argus.mcp_server import mcp; assert mcp is not None"
+      - name: Static checks
+        run: |
+          ruff check argus tests
+          ruff format --check argus tests
+          mypy
       - name: Install Chromium
         run: python -m playwright install --with-deps chromium
       - name: Run tests
+        env:
+          ARGUS_REQUIRE_BROWSER: "1"
         run: python -m pytest

{argus_testing-0.6.0 → argus_testing-0.7.0}/.github/workflows/release.yml

@@ -21,6 +21,8 @@ jobs:
           cache: pip
       - name: Install build and test dependencies
         run: python -m pip install --upgrade pip && python -m pip install build twine -e '.[dev]'
+      - name: Smoke-test package import
+        run: python -c "from argus.mcp_server import mcp; assert mcp is not None"
       - name: Install Chromium
         run: python -m playwright install --with-deps chromium
       - name: Verify release metadata
@@ -40,6 +42,8 @@ jobs:
           assert server["packages"][0]["version"] == version
           PY
       - name: Run tests
+        env:
+          ARGUS_REQUIRE_BROWSER: "1"
         run: python -m pytest
       - name: Build distributions
         run: python -m build

{argus_testing-0.6.0 → argus_testing-0.7.0}/.gitignore

@@ -15,4 +15,8 @@ argus-reports/
 .codex/
 test-reports/
 CLAUDE.md
-docs/
+docs/*
+!docs/architecture.md
+!docs/decisions.md
+!docs/interview-guide.md
+!docs/implementation-0.7.md

{argus_testing-0.6.0 → argus_testing-0.7.0}/AGENTS.md

@@ -53,7 +53,7 @@ the user's broader task. The short version:
 |------|---------|
 | `start_session(url, review_mode=..., goals=[...], constraints=[...], time_budget_minutes=...)` | Launch Playwright, establish the review contract, and return the one-time QA protocol plus initial observation. The budget is advisory; `0` means none. |
 | `observe()` | URL + interactive elements (description-keyed) + visible feedback + counts + ARIA + viewport state. Read this first, after every action. |
-| `coverage_update(goal, status, evidence)` | Update a supplied goal as `untested`, `in_progress`, `exercised`, or `blocked`. Concrete evidence is mandatory for `exercised` and `blocked`; Argus never guesses semantic completion. |
+| `coverage_update(goal, status, evidence)` | Mark a goal `in_progress` before its journey to open a precise evidence window. `exercised` and `blocked` require an explanation and automatically link URLs, value-redacted actions, screenshots, checks, and findings; Argus never guesses semantic completion. |
 | `click_what(description)` | Click the element matching `description`. Returns the top candidates if ambiguous — rephrase rather than guess. |
 | `type_into(description, text)` / `select_into(description, value)` | Inputs and dropdowns by description. |
 | `test_action(target, expect=...)` | Click + before/after diff in one call. Pass `expect` to PREDICT the outcome ({"count":{"label":"tasks","delta":1}}, {"gains":"Buy milk"}, {"removes":...}, {"text_present":...}, {"toast":...}, {"url_changed":true}) and Argus reports MATCH / SURPRISE — a surprise is a bug lead. Also shows CROSS-STACK: which requests the click fired (methods/statuses) and a CHECK nudge when a message appeared without a matching write. |
@@ -88,6 +88,7 @@ the user's broader task. The short version:
 ```
 start_session(url, goals=[...], constraints=[...], time_budget_minutes=15)
                                        # initial result already MAPS the page
+coverage_update(goal, "in_progress")   # opens this goal's evidence window
                                        # USE IT — pick a real goal, walk it
                                        #   end-to-end, carrying state across pages
                                        # HYPOTHESIZE — what could go wrong
@@ -155,6 +156,10 @@ Don't record speculation, polish nits, or static a11y / SEO that
 - `argus-mcp --list-tools` — selected tool profile and exported names.
 - `argus-mcp --tool-profile core|screen|full` — control discovery size.
 - `argus-mcp --unsafe` — turn on `eval_js` (off by default).
+- `argus-mcp --monitor-port 8765` — enable the read-only loopback dashboard,
+  health/readiness endpoints, SSE events and metrics; use `0` for a free port.
+- `argus-cleanup --keep-runs 20` — dry-run report retention; add `--apply`
+  to remove complete old run artifacts without touching journals or capsules.
 - `python -m argus.bench --target all` — reproduce the 34 / 34 matrix.
 - `python -m argus.screen.validate <app names...>` — read-only AX walk
   over running apps, JSON output.
@@ -171,6 +176,23 @@ Don't record speculation, polish nits, or static a11y / SEO that
 - Every `screen_click_what` / `screen_type_into` writes a
   before-and-after screenshot pair to the action trail.
 
+## Runtime boundaries (0.7)
+
+All calls in one runtime are serialized. Defaults are a 5-second queue wait,
+120-second operation deadline and 10-second cleanup deadline per backend.
+Cancellation/timeout closes the backend; do not blindly retry a write because
+the application may already have processed it. Start a new session after a
+failed lifecycle transition. Monitoring contains state/counts only, not inputs.
+
+Input-dependent exported replay steps are marked `requires_input`. Never replay
+redaction placeholders as real values. Capsules contain raw credentials and
+must not be shared. Screenshots and explicit finding evidence can still contain
+application data.
+
+`argus-regression` exits 0 for no reproduced known findings (including no
+journal), 1 for still-present findings, 2 for operational/storage failures and
+3 for inconclusive checks. An empty journal is not proof of app correctness.
+
 ## What changed in 0.5 (if you knew 0.4)
 
 - `get_page_state` → `observe` (no integer indices).

argus_testing-0.7.0/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+## 0.7.0 - 2026-10-19
+
+- Split MCP adaptation from focused application services, domain contracts and
+  adapters; add explicit runtime composition and injectable browser, journal,
+  verification and report extension points.
+- Serialize all session operations; classify operational errors, validate
+  runtime/capture limits, and clean up on failed startup, cancellation, timeout
+  and shutdown. Do not automatically retry browser writes.
+- Add optional loopback monitoring: dashboard, liveness/readiness, versioned
+  status, bounded SSE with reconnect gaps, and Prometheus metrics. Keep all
+  monitoring payloads free of tool arguments and page contents.
+- Keep input values in a session-local vault and omit them from persisted
+  action steps/replay exports, including bulk form filling and paste paths.
+- Share CLI/MCP regression through application services and a verifier registry;
+  use exit 3 for inconclusive checks and exit 2 for corrupted journals.
+- Replace stale-file lock deletion with OS-backed file locking; coordinate
+  report generation and cleanup and split individual report exporters.
+- Add real stdio MCP and HTTP-monitor integration tests, runtime fault tests,
+  architecture boundaries, Ruff checks and scoped core type checking in CI.
+- Add architecture, decision, extension and interview documentation. Existing
+  public MCP tool names and profiles are retained.
+
+### Also included since 0.6
+
+- Bound browser network, error, download, and dialog capture; avoid loading
+  binary or oversized response bodies and redact credentials at capture time.
+- Give every run a unique artifact identity so screenshots and reports cannot
+  overwrite evidence from another session.
+- Add atomic, schema-versioned journal and capsule persistence with visible
+  diagnostics instead of silent write failures.
+- Add the dry-run-first `argus-cleanup` command for removing complete old report
+  runs without touching regression journals or state capsules.
+- Serialize session lifecycle transitions and surface teardown, capture-limit,
+  and secondary-report warnings in the final session summary.
+- Keep the MCP SDK on its supported 1.x API and fail fast on package-import
+  incompatibilities before browser installation in CI and release builds.
+- Link each completed or blocked coverage goal to the URLs, value-redacted
+  actions, screenshots, persistence checks, bugs, and observations produced
+  during its testing window.
+- Render structured goal evidence in HTML reports and preserve the same stable
+  shape in JSON reports.
+
+## 0.6.0 - 2026-07-21
+
+- Move the full QA protocol from the global MCP instruction into the
+  one-time `start_session` response, with a regression budget for the default
+  tool context.
+- Add natural-language testing goals, user constraints, and an advisory time
+  budget to `start_session`.
+- Add `coverage_update` with evidence-required `exercised` and `blocked`
+  states; keep goal and discovered-page coverage visible during observations.
+- Preserve completed, blocked, and unfinished coverage in HTML and JSON
+  reports and in the final session summary.
+
+## 0.5.0 - 2026-07-14
+
+Argus 0.5 replaces the index-keyed MCP interface with a smaller,
+description-keyed workflow and makes evidence preservation part of the
+public contract.
+
+- Add focused `core`, `screen`, and `full` MCP tool profiles.
+- Replace integer-index actions with `observe`, `click_what`, `type_into`,
+  `select_into`, and description-keyed inspection tools.
+- Add independently verified reproduction receipts for text and HTTP-status
+  findings, including cold replay for multi-step journeys.
+- Preserve complete evidence in JSON, HTML, JUnit, and SARIF reports while
+  keeping HTML screenshot previews compact.
+- Correlate console and network symptoms without duplicating root causes.
+- Add native macOS screen-mode permission checks, action limits, abort control,
+  and before/after evidence capture.
+- Improve visual inspection with element crops, screenshot diffs, bounded
+  layout checks, and finite CSS-transition waits.
+- Add packaging, CI, PyPI Trusted Publishing, and official MCP Registry
+  metadata for repeatable releases.
+
+### Breaking changes from 0.4
+
+- `get_page_state` is now `observe`.
+- `click`, `type_text`, and `select_option` are replaced by description-keyed
+  actions.
+- `verify_action` is now `verify_persistence`.
+- `test_crud` is removed; compose journeys from the focused tools instead.
+- Findings must be explicitly recorded with `record_bug` or
+  `record_observation`.

argus_testing-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing
+
+Use Python 3.10 or newer. CI runs 3.10 and 3.12. Browser checks are local and do
+not call a model provider:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+playwright install chromium
+ruff check argus tests
+ruff format --check argus tests
+mypy
+ARGUS_REQUIRE_BROWSER=1 pytest -q
+```
+
+`mypy` covers the contracts, settings and runtime core listed in `pyproject.toml`;
+the whole legacy codebase is not yet strictly typed. CI treats unavailable-browser
+skips as failures. macOS AX permissions and real native-app behavior need a
+separate macOS manual check; Linux CI does not claim to test that integration.
+
+## Where changes belong
+
+- Tool arguments, MCP metadata and profile selection: `entrypoints/mcp/`.
+- A new QA operation: the appropriate `application/` service and `OPERATIONS`
+  registry; add catalog metadata, README documentation and a protocol test.
+- Pure rules and typed data: `domain/`; no browser, MCP or HTTP imports here.
+- New verification: register an async strategy on `runtime.verifiers`. Return
+  an explicit receipt with `attempted` and a three-state `reproduced` result.
+  Automatic regression deliberately permits only read-only built-in checks.
+- New report format: a pure renderer under `adapters/reporting/`, injected via
+  `Reporter(exporters=...)`. HTML remains the primary report.
+- A different journal: implement `JournalPort` and wire it in `bootstrap.py`.
+  The repository owns merge atomicity; callers should not read-then-write.
+- Browser actions: add a public adapter method. Application services must not
+  access `_page`, `_context`, `_locator` or other adapter private state.
+- Monitor additions: `adapters/monitoring.py` and its packaged `assets/`.
+  Never add raw inputs, arbitrary URLs, page contents or credentials to events.
+
+Each runtime is explicit. Use `create_runtime(Settings(...))` and
+`runtime.execute(name, operation, ...)`; do not set global environment variables
+to switch sessions. The context variable is only the invocation-local bridge
+for existing service signatures. `mcp_server` compatibility imports are not the
+application API for new code.
+
+## Verification and releases
+
+Lifecycle tests use fake backends to deterministically force failures and
+cancellation. Browser tests use temporary local fixtures. `test_stdio_protocol.py`
+launches the real entry point and performs initialize/list/call/image/end over
+MCP stdio. Monitoring tests use a real loopback socket and SSE disconnects.
+
+For the scripted benchmark, start `test-site/app.py` and
+`human-eye-fixture/app.py`, then run `python -m argus.bench --target all`. This is
+a capability ceiling, not a real-agent success rate. Model-provider benchmarks
+consume subscription/API usage and must be explicitly authorized.
+
+For release, synchronize `pyproject.toml` and both version fields in
+`server.json`, update `CHANGELOG.md`, build with `python -m build`, check with
+`twine check`, and smoke-test the wheel outside the source directory. JS and
+dashboard assets are package resources and must be present in the wheel.
+Publish only after CI passes. The GitHub release workflow builds/tests again,
+publishes to PyPI through Trusted Publishing, then publishes MCP Registry
+metadata. Do not commit keys, capsules, generated reports or local test data.

argus_testing-0.7.0/Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY . .
+
+RUN pip install --no-cache-dir . \
+    && playwright install --with-deps chromium \
+    && rm -rf /var/lib/apt/lists/*
+
+ENTRYPOINT ["argus-mcp"]

{argus_testing-0.6.0 → argus_testing-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: argus-testing
-Version: 0.6.0
+Version: 0.7.0
 Summary: Autonomous QA MCP that tests apps like a real testing engineer and verifies every certified bug
 Project-URL: Homepage, https://yichenwu.dev/projects/argus
 Project-URL: Documentation, https://github.com/chriswu727/argus#readme
@@ -17,17 +17,24 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Testing
 Requires-Python: >=3.10
 Requires-Dist: click>=8.0.0
+Requires-Dist: filelock<4,>=3.12
 Requires-Dist: jinja2>=3.0.0
 Requires-Dist: litellm>=1.40.0
-Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: mcp[cli]<2.0.0,>=1.0.0
 Requires-Dist: pillow>=10.0.0
 Requires-Dist: playwright>=1.40.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0.0
+Requires-Dist: starlette<2,>=0.27
+Requires-Dist: typing-extensions>=4.9
+Requires-Dist: uvicorn<1,>=0.31
 Provides-Extra: dev
+Requires-Dist: httpx<1,>=0.27; extra == 'dev'
+Requires-Dist: mypy<3,>=2.4; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff<0.18,>=0.17; extra == 'dev'
 Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
 Provides-Extra: mac
 Requires-Dist: pyobjc-framework-applicationservices>=10.0; (sys_platform == 'darwin') and extra == 'mac'
@@ -81,12 +88,17 @@ flowchart LR
     C --> A
     B -->|bug| D["verify_persistence — reload from a clean state"]
     D -->|symptom repeats| E(["VERIFIED"])
-    D -->|symptom gone| F(["dropped — no false positive"])
+    D -->|symptom gone or uncertain| F(["not certified"])
     E --> G[["report: HTML · JSON · JUnit · SARIF"]]
 ```
 
 The agent is the intelligence. Argus supplies concise QA guidance, a description-keyed tool surface (`click_what("Login button")`, not `click(7)`), a goal coverage ledger, and a **reproduction-receipt engine** that turns "the model thinks this is a bug" into "this bug is real, here's the proof."
 
+A receipt confirms the specified observable symptom, not every possible root
+cause. A clean load preserves authentication and browser storage by default;
+replay can repeat real writes. Qualitative observations and inconclusive checks
+remain distinct from verified findings.
+
 ---
 
 ## Quick start
@@ -140,7 +152,7 @@ Then just ask, in your agent session:
 
 That's it. The agent drives; Argus keeps it honest and writes the report.
 
-For a scoped review, the host can give `start_session` explicit `goals`, `constraints`, and an advisory `time_budget_minutes`. Argus returns the full testing protocol once, keeps outstanding goals and discovered pages visible in later observations, and requires concrete evidence before `coverage_update` can mark a goal `exercised` or `blocked`. The final HTML and JSON reports preserve both completed and unfinished coverage instead of implying that an incomplete pass was comprehensive.
+For a scoped review, the host can give `start_session` explicit `goals`, `constraints`, and an advisory `time_budget_minutes`. Argus returns the full testing protocol once and keeps outstanding goals and discovered pages visible in later observations. Mark a goal `in_progress` before its journey; when `coverage_update` marks it `exercised` or `blocked`, Argus requires a concrete explanation and automatically links the URLs, value-redacted actions, screenshots, persistence checks, bugs, and observations produced in that testing window. The final HTML and JSON reports preserve both completed and unfinished coverage instead of implying that an incomplete pass was comprehensive.
 
 <details>
 <summary><b>pip installation</b></summary>
@@ -180,6 +192,95 @@ Same description-keyed tools, but the target is whatever app is foreground on ma
 
 </details>
 
+### Artifact and resource limits
+
+Argus writes each run's screenshots into its own run directory so later tests
+cannot overwrite earlier evidence. Long browser sessions also keep bounded
+in-memory event logs and only read response bodies for inspectable API traffic;
+binary and oversized bodies are skipped before they enter Python memory.
+
+Report cleanup is explicit and dry-run by default. The newest 20 complete runs
+are protected in this example; `.argus` journals and state capsules are never
+deleted:
+
+```bash
+argus-cleanup --output ./argus-reports --keep-runs 20
+argus-cleanup --output ./argus-reports --keep-runs 20 --apply
+```
+
+Use `--older-than-days` and `--max-size-mb` for stricter policies. Advanced
+limits can be adjusted with `ARGUS_MAX_NETWORK_EVENTS`,
+`ARGUS_MAX_ERROR_EVENTS`, `ARGUS_MAX_DOWNLOAD_EVENTS`,
+`ARGUS_MAX_DIALOG_EVENTS`, `ARGUS_MAX_RESPONSE_BODY_BYTES`, and
+`ARGUS_MAX_RESPONSE_READ_BYTES`. Responses without a declared length are skipped
+by default; `ARGUS_CAPTURE_UNKNOWN_LENGTH_BODY=1` opts into reading them. When a
+limit discards old evidence, Argus says so in tool output and the final session
+summary.
+
+### Live monitoring (0.7)
+
+Add a monitor port to the command your MCP client launches:
+
+```bash
+argus-mcp --monitor-port 8765
+# Or choose an available port automatically:
+argus-mcp --monitor-port 0
+```
+
+Open `http://127.0.0.1:8765` for session state, active operation and duration,
+last progress, calls, operational failures, findings and recent events. The
+selected URL is printed to **stderr**, so stdio MCP messages stay intact.
+`ARGUS_MONITOR_PORT` is equivalent; monitoring is off by default.
+
+| Route | Output |
+|---|---|
+| `/` | Local live dashboard |
+| `/healthz` | HTTP process liveness |
+| `/readyz` | Runtime initialized and not shutting down; 503 otherwise |
+| `/api/status` | Versioned state snapshot, counts and capture drops |
+| `/api/events` | Server-Sent Events, `Last-Event-ID` reconnect and gap notices |
+| `/metrics` | Prometheus text counters and operation duration sums/counts |
+
+The monitor binds only to `127.0.0.1`, rejects unrelated Host/Origin headers,
+and has no action endpoints. It emits no page contents, URLs, typed values,
+screenshots or tool arguments. It is **not an authenticated remote service**;
+do not expose it through a public proxy. Event retention is bounded (512 by
+default), with at most 32 simultaneous SSE subscribers.
+
+Runtime settings are validated at startup. Explicit command-line options
+override environment variables, which override defaults:
+
+| Environment variable | Default |
+|---|---:|
+| `ARGUS_OPERATION_TIMEOUT_S` | 120 seconds |
+| `ARGUS_QUEUE_TIMEOUT_S` | 5 seconds |
+| `ARGUS_CLEANUP_TIMEOUT_S` | 10 seconds per backend |
+| `ARGUS_EVENT_CAPACITY` | 512 events |
+| `ARGUS_OUTPUT_DIR` | `./argus-reports` |
+
+One runtime owns one active session. Actions and lifecycle changes are
+serialized; an operation timeout cancels the action and closes the backend.
+Side-effecting actions are never automatically retried. A separate MCP process
+is the supported way to run another independently controlled session.
+
+### Regression gates and evidence privacy
+
+```bash
+argus-regression http://localhost:3000 --output ./argus-reports
+```
+
+Exit codes: `0` no known symptom reproduced (or no journal), `1` a known symptom
+still reproduces, `2` operational/storage failure, `3` inconclusive. An exit of
+zero is not proof of complete application correctness. Automatic regression
+uses built-in text/HTTP checks, never write-performing replay.
+
+Typed, pasted and selected input values are held in a session-local input vault,
+not in action traces or exported replay steps. Exported steps that need input
+are marked `requires_input`; they cannot be replayed as if a redacted value were
+real. Capsules deliberately contain credentials and are saved with owner-only
+file permissions on POSIX. Reports and screenshots can still contain visible
+application data; see [Privacy](PRIVACY.md).
+
 ---
 
 ## Why Argus is different
@@ -278,7 +379,7 @@ uvx --from argus-testing argus-mcp --tool-profile full --list-tools
 |-------|---------|
 | `start_session` | Start an `exploratory`, `visual`, or `regression` browser review; optionally accept `goals`, `constraints`, and `time_budget_minutes`; return the one-time protocol and initial observation. |
 | `observe` | Return URL, title, description-keyed interactive elements, counts, visible feedback, ARIA tree, and viewport state. |
-| `coverage_update` | Mark a supplied goal `untested`, `in_progress`, `exercised`, or `blocked`; exercised and blocked states require concrete evidence. |
+| `coverage_update` | Open a goal evidence window with `in_progress`, then mark it `exercised` or `blocked`; terminal states require an explanation and automatically link session evidence. |
 | `click_what` | Click the element best matching a natural-language description; return candidates instead of guessing when ambiguous. |
 | `type_into` · `select_into` | Resolve a field by description, then type text or select an option. |
 | `hover_what` · `press_key` | Exercise hover states and keyboard interactions against description-keyed targets. |
@@ -298,7 +399,7 @@ uvx --from argus-testing argus-mcp --tool-profile full --list-tools
 
 </details>
 
-Reports keep original screenshots as evidence and, by default, write compact WebP previews under `report-assets/` instead of base64-embedding every full-size PNG into the HTML. Set `ARGUS_PORTABLE_REPORT=1` when a single self-contained HTML file is more important than size. JSON output includes complete reproduction receipts, the coverage contract, constraints, review mode, tool-call and recorded-step counts, screenshot metadata, and qualitative observations. JUnit suite failure totals match the emitted `<failure>` nodes.
+Reports keep original screenshots as evidence and, by default, write compact WebP previews under `report-assets/` instead of base64-embedding every full-size PNG into the HTML. Set `ARGUS_PORTABLE_REPORT=1` when a single self-contained HTML file is more important than size. JSON output includes complete reproduction receipts, the coverage contract and its structured evidence references, constraints, review mode, tool-call and recorded-step counts, screenshot metadata, and qualitative observations. JUnit suite failure totals match the emitted `<failure>` nodes.
 
 <details>
 <summary><b>Screen profile — 14 tools</b></summary>
@@ -388,18 +489,30 @@ The global instruction is intentionally tiny so it does not repeat a long QA pro
 
 ```
 argus/
-├── mcp_server.py     # tool surface + role instructions + reproduction-receipt engine
-├── browser.py        # Playwright backend: DOM/ARIA extraction, capsule/replay
-├── resolver.py       # description → element (web + screen)
-├── reporter.py       # HTML + JSON + JUnit + SARIF
-├── detector.py       # console + network capture (only)
-├── cli.py            # argus (explore) + argus-regression
-├── bench/            # deterministic ceiling + real-LLM recall harness
-└── screen/           # macOS AX backend, permissions, safety
+├── mcp_server.py      # process entry point and compatibility imports
+├── entrypoints/mcp/   # public tool catalog, profiles and MCP adaptation
+├── application/       # session manager and focused QA use cases
+├── domain/            # models, errors, states, replay and verification contracts
+├── adapters/          # monitoring, logs, file journal, report exporters, JS assets
+├── bootstrap.py       # composition root: injected backend/repository factories
+├── ports.py           # narrow lifecycle, observation, verification and storage protocols
+├── settings.py        # validated, per-runtime configuration
+├── browser.py         # Playwright adapter (public operations; private page ownership)
+├── screen/            # macOS AX adapter, permissions, safety
+├── reporter.py        # atomic report orchestration and exporter registry
+├── resolver.py        # description → element (web + screen)
+├── cli.py             # autonomous exploration and shared regression entry point
+└── bench/             # deterministic capability + optional real-LLM harness
 test-site/            # BuggyTasks  (22 mechanical bugs)
 human-eye-fixture/    # DarkShop    (12 human-eye bugs)
 ```
 
+Start with [Architecture](docs/architecture.md), [design decisions](docs/decisions.md)
+and [Contributing](CONTRIBUTING.md). The [interview guide](docs/interview-guide.md)
+maps design claims to implementation, tests and explicit limitations. The
+autonomous LiteLLM exploration loop remains a separate workflow; shared
+regression does not import or mutate the MCP server.
+
 ---
 
 <div align="center">

argus_testing-0.7.0/PRIVACY.md

@@ -0,0 +1,72 @@
+# Privacy
+
+Argus is a local-first testing tool. The project does not operate an Argus
+cloud service, user account system, analytics endpoint, or telemetry collector.
+
+## Data Argus handles
+
+During a test, Argus may process page text, accessibility data, URLs, browser
+console and network events, testing goals and constraints, verification targets,
+cookies or storage when the corresponding tools are called, screenshots,
+downloaded-file metadata, and native macOS accessibility information in screen
+mode. Coverage reports omit typed and pasted input values from action references,
+but goals, constraints, verification targets, finding titles, and screenshots are
+evidence and may contain application data; do not put secrets in those fields.
+
+Reports, screenshots, reproduction receipts, state capsules, and regression
+journals are written locally under `./argus-reports` by default. Set
+`ARGUS_OUTPUT_DIR` to choose another location. `argus-cleanup` can plan and
+remove complete old report runs while leaving journals and state capsules
+untouched; it is a dry run unless `--apply` is passed.
+
+Captured request headers, response headers, request bodies, and inspectable API
+response bodies are redacted for common credential-bearing keys before they are
+retained. Response bodies are bounded, and binary or oversized bodies are not
+loaded for inspection. These safeguards reduce common exposure paths but cannot
+recognize every application-specific secret format.
+
+## Where data can go
+
+- The MCP host and its configured model provider receive the Argus tool inputs
+  and outputs that the host includes in a conversation. Their privacy terms
+  apply independently of Argus.
+- Browser tests connect to the URLs the user or agent chooses to test, along
+  with resources those pages load.
+- CLI mode uses LiteLLM and sends planner context to the model provider selected
+  by the user. MCP mode does not require an Argus API key or an Argus-operated
+  model service.
+- Installing or upgrading through PyPI, `pip`, or `uvx` contacts those package
+  distribution services under their own policies.
+
+Argus does not intentionally transmit test artifacts to the project maintainer.
+Review reports and screenshots before sharing them because they can contain
+sensitive application data.
+
+## Replay inputs and state capsules
+
+Typed, pasted and selected values are stored in a per-session in-memory vault.
+Action traces retain opaque references; exports omit those references and mark
+input-dependent steps `requires_input`. Closing, replacing, cancelling or timing
+out a session clears its vault. This is reference removal, not a guarantee of
+cryptographic erasure from Python memory, swap or process dumps. The host already
+knows the inputs it supplied. Page content, human-authored evidence, prompts,
+console messages and screenshots may independently reveal the same information.
+
+State capsules intentionally contain raw cookies and browser storage. They use
+atomic writes, schema validation, owner-only files on POSIX, and a defensive
+`.gitignore`. They are not encrypted. They persist until explicitly deleted by
+the user; ordinary report cleanup does not remove them. Do not share them.
+
+## Optional local monitor and diagnostic logs
+
+`--monitor-port` enables a read-only HTTP dashboard on `127.0.0.1` only. Status,
+SSE events and metrics contain operation names, timestamps, state, error codes,
+run IDs and counts, not tool arguments, page URLs, page text, input values or
+images. The event ring is bounded and process-local, not durable audit storage.
+Host/Origin validation reduces cross-site access; there is no authentication
+against other local processes. Do not expose the port publicly.
+
+Structured Argus diagnostics go to stderr, never the MCP stdout channel.
+Operation diagnostics use allowlisted metadata rather than raw arguments or
+exception tracebacks. Dependency diagnostics and explicit tool outputs have
+their own formats. Review host logs before sharing them.