comber 0.1.0

package/README.md

@@ -0,0 +1,732 @@
+# 🦞 Comber
+
+**Every-click AI QA agent.** Point it at a URL and it walks the app like a real user,
+clicks what's safe, watches for breakage, and writes a self-contained HTML report —
+leaving cheap deterministic replays behind so the expensive every-click run happens once.
+
+**Comber** by RADLAB — product site **[codecomber.io](https://codecomber.io)**. CLI/package: `comber`.
+
+> **Status: Phase 0 scaffold (2026-06-24).** Runnable DOM-first web crawler with breakage
+> detection, optional Claude action-picker + judge, and an HTML report. Four drivers now sit
+> behind the universal contract — **web** (Playwright), **api** (OpenAPI), **native**
+> (iOS/Android over a pluggable Maestro runner), and **desktop** (Windows UI Automation
+> or macOS Accessibility).
+> The rest (Stagehand selector-cache replay polish, GitHub Action on Vercel preview deploys) is
+> staged — see **Roadmap** below.
+
+## Why DOM-first
+
+The accessibility/DOM snapshot is ~200–400 tokens per step with stable element refs; a
+screenshot is ~1,000–1,800 image tokens per step. So Comber drives the browser off the DOM
+(Playwright today, Stagehand selector-cache next) and reserves Claude **vision/computer-use**
+for the few surfaces the DOM can't describe (canvas, file-preview, drag-drop, visual diff).
+That keeps a full crawl in the cents, deterministic, and CI-safe.
+
+## Install
+
+Comber ships as the **`comber`** package (CLI + reusable GitHub Action). The published
+tarball carries a prebuilt `dist/` plus `action.yml`, so no build step is needed on a normal
+npm/bun install.
+
+```bash
+# As a project dependency (bun or npm):
+bun add comber
+npm i -g comber            # or install globally for a `comber` on your PATH
+
+# One-off, no install (downloads + runs):
+bunx comber https://example.com
+
+# Web crawls need a Chromium for Playwright (once per machine / CI runner):
+bunx playwright install chromium
+
+# Then run:
+comber https://example.com               # heuristic crawl, no API key needed
+comber https://example.com --max-states=30 --llm   # Claude action-picker + judge
+```
+
+**Pre-publish / private install (no npm release yet).** Until `comber` is published to npm
+(see the **Publish gate** under *CI integration*), install straight from the repo — the
+package's `prepare` script builds `dist/` on install, so a git ref works the same as the
+published package:
+
+```bash
+bun add github:RADLABtech/comber#<ref>   # <ref> = a tag (v0.1.0), branch, or commit SHA
+```
+
+## Run from source
+
+```bash
+cd ~/repos/comber
+bun install
+bunx playwright install chromium
+
+# Heuristic crawl (no API key needed):
+bun run dev https://example.com
+
+# LLM-driven (Haiku picks actions, Opus judges findings):
+cp .env.example .env && echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
+bun run dev https://example.com --max-states=30 --llm
+
+# Authenticated crawl against a SYNTHETIC account:
+#   COMBER_STORAGE_STATE=./auth.json bun run dev https://example.com
+```
+
+### Generating a synthetic session
+
+An authenticated crawl needs a Playwright `storageState` (cookies + localStorage)
+for a **synthetic / throwaway** account — never a real user's. Two helpers produce it:
+
+```bash
+# Interactive: opens a browser, you log in, press ENTER to capture.
+bun run save-session https://example.com/login auth.json
+
+# Headless (CI-friendly): credentials from the environment, never the CLI.
+SYNTH_EMAIL=you@synthetic.example SYNTH_PW=… bun run login https://example.com/login auth.json
+#   …or read the password from a file instead of $SYNTH_PW:
+SYNTH_EMAIL=you@synthetic.example bun run login https://example.com/login auth.json ./pw.txt
+
+# Then crawl with it:
+COMBER_STORAGE_STATE=auth.json bun run dev https://example.com
+```
+
+The saved file holds live session tokens — `.gitignore` already covers
+`auth*.json` / `*-auth.json` / `auth/`. Keep it there.
+
+
+Flags: `--max-states=N` `--max-actions=N` `--max-ms=N` `--max-tokens=N` `--headed`
+`--llm` `--cross-origin` `--external-links` `--allow-writes` `--baseline=PATH`
+`--pr-comment=PATH` `--config=PATH` `--profile=NAME` `--strict` (exit 1 on any
+fail-severity finding; default is soft).
+
+API target (`comber api …`): `--openapi=PATH|URL` (JSON or YAML) `--api-base=URL`
+`--graphql=URL` `--har=PATH` `--seed=PATH` `--allow-writes`. Credentials are env-only:
+`COMBER_API_TOKEN` (single Bearer) and `COMBER_API_AUTH_PROFILES` (a JSON `{role:token}`
+map for the multi-role IDOR/broken-auth harness). See **API driver** below.
+
+## Profiles, baselines, and PR comments
+
+Profiles keep per-app crawl settings out of CI YAML:
+
+```bash
+cp comber.config.example.json comber.config.json
+bun run dev --profile local --config comber.config.json
+```
+
+`comber.config.json` can be either one direct config object or a named `profiles` object
+with `defaultProfile`. Supported aliases include `url`/`startUrl`, `maxMs`/`maxWallClockMs`,
+`maxTokens`/`maxTokenBudget`, `maxPerState`/`maxActionsPerState`, `maxRegotos`/
+`maxRegotosPerState`, `nearDup`/`nearDupThreshold`, `storageState`/`storageStatePath`,
+`baseline`/`baselinePath`, and `prComment`/`prCommentPath`.
+
+Baseline diffing compares current findings by stable `signature` against a prior
+`result.json`:
+
+```bash
+bun run dev https://preview.example.com --baseline baselines/preview-result.json
+```
+
+When no baseline exists, Comber treats all current findings as new and keeps running. To
+produce a Markdown body for a non-blocking pull-request comment:
+
+```bash
+bun run dev https://preview.example.com --baseline baselines/preview-result.json --pr-comment runs/pr-comment.md
+```
+
+### Informational findings
+
+Comber reports `fail`, `warn`, and `info` severities. Strict gates and baseline headline
+counts use only `fail` and `warn`; `info` findings are visible context that should not block
+a run.
+
+The web crawler normalizes crawler-caused noise before dedupe:
+
+- Comber-blocked egress fan-out (`egress-blocked` plus matching request/console/fetch errors)
+  becomes one `crawler-suppressed` info finding.
+- Known telemetry infrastructure such as Cloudflare Insights, Statsig, Sentry ingest, and
+  Microsoft browser events becomes `third-party-telemetry` info.
+- Turnstile, hCaptcha, and Cloudflare challenge endpoints or widget errors become
+  `bot-challenge` info findings.
+- `.ico` images are not marked `broken-image` solely because browser decode reports
+  `naturalWidth === 0`.
+
+The bundled manual workflow (`.github/workflows/comber.yml`) runs Comber from source. It
+uploads `runs/` as an artifact and can optionally post `runs/pr-comment.md` to a PR when
+`pr_number` is supplied. For dropping Comber into *another* repo, use the reusable Action
+below.
+
+## CI integration (reusable Action)
+
+`action.yml` at the repo root is a **composite GitHub Action** so any repo can run Comber on
+a preview deploy. It sets up bun → installs comber → runs it → uploads the `runs/` report
+artifact → posts a non-blocking PR comment → and gates the job only when `strict` and
+fail-severity findings are present.
+
+```yaml
+# .github/workflows/comber-pr.yml in the consumer repo
+name: comber
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  comber:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: RADLABtech/comber@v1 # see the publish gate below
+        with:
+          url: https://your-preview-deploy.example.com
+          max-states: "20"
+          strict: "false" # non-blocking PR comment first; flip to "true" to fail on defects
+          pr-comment: "true"
+        env: {}
+        # secrets:
+        #   anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }} # only when llm: "true"
+```
+
+For an **API target**, swap `url` for `openapi` + `api-base`:
+
+```yaml
+      - uses: RADLABtech/comber@v1
+        with:
+          openapi: ./openapi.json # file path or http(s) URL
+          api-base: https://api-preview.example.com
+          strict: "true"
+```
+
+### Inputs
+
+| Input | Default | Purpose |
+|---|---|---|
+| `url` | `""` | Web target URL to crawl (use this **or** `openapi`). |
+| `openapi` | `""` | OpenAPI 3.x source (path/URL); selects the API driver. |
+| `api-base` | `""` | API base URL (required with `openapi`). |
+| `seed` | `""` | API seed-data JSON path (per-operation overrides). |
+| `max-states` | `""` | Max states to exercise (blank = Comber default). |
+| `llm` | `"false"` | Use the Claude action-picker + judge (needs `anthropic-api-key`). |
+| `external-links` | `"false"` | Check external links (egress to private/metadata hosts stays blocked). |
+| `allow-writes` | `"false"` | Allow mutating HTTP methods — **synthetic environments only**. |
+| `strict` | `"false"` | Exit non-zero (fail the job) when fail-severity findings exist. |
+| `pr-comment` | `"true"` | Post a non-blocking comment on the PR. |
+| `baseline` | `""` | Prior `result.json` for baseline diffing. |
+| `config` / `profile` | `""` | `comber.config.json` path / profile name. |
+| `install-spec` | `"comber"` | Spec passed to `bun add` (see the publish gate). |
+| `comber-version` | `""` | Version pin when `install-spec` is the default (→ `comber@<version>`). |
+| `bun-version` | `"latest"` | Bun version for `oven-sh/setup-bun`. |
+| `anthropic-api-key` | `""` | `ANTHROPIC_API_KEY` pass-through (LLM mode). |
+| `storage-state` | `""` | Absolute path to a synthetic Playwright `storageState` (`COMBER_STORAGE_STATE`). |
+| `api-token` | `""` | Bearer for the API target (`COMBER_API_TOKEN`). |
+| `sink-file` / `sink-dir` / `sink-url` / `sink-token` | `""` | `COMBER_SINK_*` persistence pass-through. |
+| `github-token` | `${{ github.token }}` | Token for `gh pr comment` (needs `pull-requests: write`). |
+| `pr-number` | `""` | PR to comment on (defaults to the triggering `pull_request`). |
+
+The job's only output, `exit-code`, is Comber's process code (`0` clean/soft · `1` strict + fails · `2` crash).
+
+### Script-injection safety
+
+Every consumer-supplied value (`url`, `openapi`, `api-base`, …) is forwarded to the run step
+through **`env:`** and read inside a **quoted bash array** as `"$VAR"` — it is *never*
+interpolated into a `run:` script via `${{ … }}`. That is the GitHub Actions untrusted-input
+rule: a `url` like `"; rm -rf / #` cannot break out of an env var into the shell. The action
+follows the same pattern as `.github/workflows/comber.yml`, and pins every third-party action
+to a commit SHA.
+
+### Synthetic session + secrets
+
+An authenticated crawl needs a Playwright `storageState` for a **synthetic / throwaway**
+account (never a real user). Generate it once (see *Generating a synthetic session* above),
+store it as a CI secret, write it to a file in a prior step, and pass its **absolute** path:
+
+```yaml
+      - name: Materialize synthetic session
+        run: printf '%s' "$STATE" > "$GITHUB_WORKSPACE/auth.json"
+        env: { STATE: ${{ secrets.COMBER_STORAGE_STATE }} }
+      - uses: RADLABtech/comber@v1
+        with:
+          url: https://your-preview-deploy.example.com
+          storage-state: ${{ github.workspace }}/auth.json
+          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
+          llm: "true"
+```
+
+Secrets are pass-through only — they reach Comber as env (`ANTHROPIC_API_KEY`,
+`COMBER_STORAGE_STATE`, `COMBER_API_TOKEN`, `COMBER_SINK_*`) and never appear in a `run:`
+script, the report, the PR comment, or logs. Every **text** artifact (report, `result.json`,
+PR comment, sink records, logs) is redacted before it leaves the process. The one exception is
+**per-state screenshots** (`state-*.png`): those are raw pixels of the target and can carry
+on-screen secrets/PII that text redaction can't reach — pass `--no-screenshots` for sensitive
+targets or restricted CI artifact retention. See [`docs/DATA_HANDLING.md`](docs/DATA_HANDLING.md).
+
+### Publish gate
+
+**Packaging is ready.** The package is public (`"private": false`), ships a prebuilt `dist/`
++ `action.yml` in its tarball, and builds `dist/` on a git install via its `prepare` script.
+The only thing left before `bun add comber` resolves from npm is the actual publish:
+
+1. Set the **`NPM_TOKEN`** repo/org secret (an npm automation token with publish rights).
+   Search the workflows for `# TODO: set NPM_TOKEN secret`.
+2. Push a version tag: `git tag v0.1.0 && git push origin v0.1.0`. The
+   [`release.yml`](.github/workflows/release.yml) workflow runs build + tests and then
+   `npm publish --access public` — but **only** when `NPM_TOKEN` is set (otherwise the
+   publish step is skipped and the job is a green no-op). No tag + no secret = nothing publishes.
+
+Meanwhile, the action's `install-spec` input bridges the gap for either state:
+
+- **Once published** — `uses: RADLABtech/comber@v1`, default `install-spec: comber`
+  (optionally pin with `comber-version: <ver>` → `bun add comber@<ver>`).
+- **Same-org / private today** — point `install-spec` at a git ref:
+  `install-spec: github:RADLABtech/comber#<ref>` (`<ref>` = tag, branch, or commit SHA). The
+  `prepare` script builds `dist/` on install, so this works with no published tarball.
+
+## API driver — OpenAPI / GraphQL / HAR + multi-role
+
+The API target discovers an API's operation set, exercises what's safe, and classifies breakage
+into its own signal set — the same `discover → exercise → classify → dedupe → report` contract as
+web/native. It read-only by default (only `GET/HEAD/OPTIONS` for REST, queries for GraphQL, the
+recorded reads for HAR); writes/mutations are surfaced as a counted coverage skip and never fired
+unless `--allow-writes`. Four spec sources feed the same pipeline:
+
+```bash
+comber api --openapi ./openapi.json --api-base https://api-preview.example.com   # OpenAPI (JSON)
+comber api --openapi ./openapi.yaml --api-base https://api-preview.example.com   # OpenAPI (YAML; sniffed)
+comber api --graphql https://api-preview.example.com/graphql                     # GraphQL introspection
+comber api --har ./recorded-traffic.har                                          # recorded HAR capture
+```
+
+| Source | Discover | Exercise | Breakage signal(s) |
+|---|---|---|---|
+| **OpenAPI** (JSON/YAML) | parse paths → operations (`$ref`s resolved) | build a concrete request per operation | `http-5xx`, `undocumented-status`, `content-type-mismatch`, **`response-schema-violation`** (full ajv JSON-Schema validation, carrying the offending paths), `response-shape-mismatch` (light fallback), `broken-auth`, `broken-object-authorization` |
+| **GraphQL** | send the standard introspection query → query/mutation fields | POST a minimal valid operation document | `graphql-error` (non-empty `errors[]`), `graphql-http-status` (non-200), `request-failed` |
+| **HAR** | recorded request entries, deduped by route template | re-send and diff against the recorded response | `contract-drift` (status or body-shape divergence), `request-failed` |
+
+**Response-schema validation (ajv).** OpenAPI 2xx bodies are validated against the operation's
+declared response schema with [ajv](https://ajv.js.org) + ajv-formats (`$ref`s resolved, cycles
+broken, OpenAPI `nullable` honored). A violation emits `response-schema-violation` carrying only
+the ajv error **paths** (`/items/0/id must be integer`) — never the body's values, so it stays
+redaction-safe. When no compilable schema is declared, the light required-property check
+(`response-shape-mismatch`) is the fallback.
+
+**Multi-role auth → broken-auth + IDOR.** Supply named credential sets (role → token) via config
+or `$COMBER_API_AUTH_PROFILES` (a JSON `{ "role": "token" }` map — **never a CLI flag**, env wins
+over config). With ≥ 2 roles plus seed data tying a resource to its owning role, operations marked
+`ownerScoped` get a cross-role object-access check: Comber confirms role B can read B's resource,
+then re-issues the same request with role A's token — a 2xx for A is **`broken-object-authorization`**
+(a classic IDOR). The no-credential `broken-auth` check (auth-required op returns 2xx without a
+credential) is unchanged. Opt-in + sandbox-only.
+
+```jsonc
+// comber.config.json (api profile)
+{
+  "target": "api",
+  "openapi": "./openapi.json",
+  "apiBase": "https://api-sandbox.example.com",
+  "apiAuthProfiles": { "alice": "", "bob": "" }, // tokens via $COMBER_API_AUTH_PROFILES
+  "ownerScoped": ["GET /users/{id}"],
+  "roleSeed": "./role-seed.json"                  // { "alice": { "GET /users/{id}": { "path": { "id": 1 } } }, "bob": { … } }
+}
+```
+
+**Deferred (honest):** the IDOR harness checks operator-declared `ownerScoped` operations against
+operator-supplied per-role seed data. Full automatic resource-ownership *discovery* — creating a
+resource under role B at runtime and tracking its id across operations to test every read path — is
+deferred; today the operator declares which operations are owner-scoped and which resource each role
+owns. GraphQL argument synthesis covers scalars/enums/required-input-objects with minimal literals;
+exotic custom scalars fall back to a string sample.
+
+## Native (mobile) driver — Maestro
+
+Comber's **third** target is a native iOS/Android app, driven over [Maestro](https://maestro.dev).
+It proves the `Driver` abstraction holds for a non-page, non-API surface: the core's
+frontier / dedupe / caps / report / baseline / redact / triage / coverage run **unchanged** against
+the screens, controls, and breakage signals the native driver emits.
+
+```bash
+# Android app already installed on a booted emulator (default platform = android):
+comber native --app com.example.app
+
+# iOS bundle on a booted simulator, a specific device, and declared deeplinks:
+comber native --app com.example.app --platform ios --device "iPhone 15" \
+  --deeplink "myapp://settings" --deeplink "myapp://profile"
+```
+
+Flags: `--app <appId|apk|path>` (required) · `--platform android|ios` (default `android`) ·
+`--device <id>` · `--deeplink <uri>` (repeatable). The same `--profile` / `--config` / `--strict`
+machinery applies; a profile can set `target: "native"`, `app`, `platform`, `device`, `deeplinks`.
+
+Evidence flags for native/OEM runs: `--provider <name>`, `--device-class phone|tablet|foldable|emulator|simulator|unknown`,
+`--device-model <model>`, `--os-version <version>`, `--android-version <version>`,
+`--app-version <version>`, `--samsung`, `--one-ui <version>`, and
+`--build-fingerprint <fingerprint>`. Evidence artifact flags are repeatable:
+`--evidence-screenshot <path>`, `--evidence-video <path>`, `--evidence-log <path>`,
+and `--evidence-crash-log <path>`. Provider audit fields include `--provider-run-id <id>`
+and `--verification-command <command>`. These populate `result.json.extra.deviceEvidence`.
+
+Comber validates native evidence at runtime. Blank artifact paths, unknown artifact kinds,
+provider run ids without providers, and incomplete verified proxy evidence are surfaced in
+`result.json.extra.deviceEvidence.validationErrors` and block exhaustive claims through the typed
+`native-evidence-invalid` blind spot. Every native run also includes
+`result.json.extra.nativeReadiness`, a provider-neutral preflight summary for device id, provider,
+verification command, evidence artifacts, and Samsung/OEM claim readiness.
+
+Native network egress remains a blocker unless the run declares complete verified proxy evidence:
+`--egress-proxy-verified`, `--egress-proxy-provider <name>`, `--egress-proxy-command <command>`,
+and `--egress-proxy-artifact <path>`. All three support fields are required; an incomplete proxy
+claim is still reported as `native-egress-unenforced`.
+
+Mac/iOS runs can produce that evidence through the bundled provider-neutral proof helper. It does
+not install or configure a proxy service; it runs an operator-supplied local proof command with
+`execFile` argv semantics, requires expected output markers, writes a JSON proof artifact, and
+prints the `--egress-proxy-proof <path>` flag for the native run:
+
+```bash
+bunx tsx scripts/native-ios-proxy-verify.ts \
+  --device CAE50036-EF58-4880-B368-67CBD2EF0728 \
+  --provider local-mac-proxy \
+  --proxy-command "mitmproxy/Proxyman profile active for simulator CAE50036-EF58-4880-B368-67CBD2EF0728" \
+  --proof-command-json '["xcrun","simctl","spawn","CAE50036-EF58-4880-B368-67CBD2EF0728","log","show","--last","2m"]' \
+  --expect-output comber-proxy-marker \
+  --artifact runs/native/ios-proxy-proof.json
+
+comber native --app com.example.ios --platform ios \
+  --device CAE50036-EF58-4880-B368-67CBD2EF0728 \
+  --egress-proxy-proof runs/native/ios-proxy-proof.json
+```
+
+The proof command must be the real local check that demonstrates the app/device traffic is flowing
+through the device-level proxy. A host-only `curl --proxy ...` can show that a proxy listener works,
+but by itself it is not proof that an iOS simulator or device is routed through that proxy. If the
+proof command fails, the expected marker is absent, the proof file is missing, or the proof file is
+malformed, Comber keeps `egressProxy.verified: false` and continues to report
+`native-egress-unenforced`.
+
+## Desktop drivers — Windows UIA and macOS Accessibility
+
+Comber's desktop target ships adapter-owned native desktop runners behind the same `Driver`
+contract as web, API, and mobile. The Windows path uses UI Automation and replays discovered
+branch paths through `uiapath:` addresses. The macOS path uses Accessibility and replays discovered
+branch paths through `axpath:` addresses. Neither path changes core traversal semantics.
+
+```bash
+# Windows: launch an app by executable path:
+comber desktop --platform windows --app-path "C:\Apps\Example\Example.exe"
+
+# Windows: attach to an already-running process:
+comber desktop --platform windows --process-name Example.exe
+
+# Prefer PID/window-title disambiguation before live action runs:
+comber desktop --platform windows --process-id 4242 --window-title "Example"
+
+# Optional local smoke, outside default CI, that performs real safe fixture actions:
+bun run smoke:windows-uia -- --fixture --max-states 4 --max-actions 12
+
+# Generic dry-run smoke against an app you provide:
+bun run smoke:windows-uia -- --app-path "C:\Windows\System32\notepad.exe" --max-states 1 --dry-run
+
+# macOS: launch by .app path or bundle id:
+comber desktop --platform macos --app-path /Applications/Example.app --process-name Example \
+  --automation-backend accessibility \
+  --provider local-mac \
+  --verification-command "osascript -l JavaScript runtime/macos-accessibility-runner.js snapshot" \
+  --accessibility-permission-verified
+
+comber desktop --platform macos --bundle-id com.example.Example --process-name Example \
+  --automation-backend accessibility
+
+# macOS controlled dry-run smoke. Without --app-path it creates a temporary fixture app.
+bun run smoke:macos-accessibility
+
+# macOS desktop proxy proof from already-configured system proxy settings.
+# This inspects networksetup state and does not modify macOS proxy configuration.
+bun run verify:desktop-macos-proxy -- \
+  --app-identity Example \
+  --artifact runs/desktop/macos-proxy-proof.json
+
+comber desktop --platform macos --app-path /Applications/Example.app --process-name Example \
+  --egress-proxy-proof runs/desktop/macos-proxy-proof.json
+```
+
+Windows controls are identified by AutomationId first, then Name plus tree path, then RuntimeId/path.
+Buttons, menu items, hyperlinks, tabs, list/data rows, and tree items are treated as branch-capable
+controls; edits, toggles, radio buttons, combo boxes, and sliders are exercised in place with
+synthetic input only. Custom, owner-drawn, canvas, DirectX, or otherwise opaque UIA subtrees are
+reported as `desktop-opaque-subtree` blind spots.
+
+macOS controls are identified by Accessibility identifier first, then title plus tree path, then
+role/path. AX buttons, links, tabs, rows, menu items, and tree items are branch-capable; text fields,
+text areas, toggles, radio buttons, pop-up buttons, and sliders are exercised in place with synthetic
+input only. Custom, canvas, Metal, WebView, and otherwise opaque Accessibility regions are reported
+as `desktop-opaque-subtree` blind spots. If the terminal or Codex host process lacks macOS
+Accessibility permission, the runner fails closed and Comber reports `desktop-accessibility-unavailable`.
+
+Desktop evidence lands in `result.json.extra.desktopEvidence`; readiness lands in
+`result.json.extra.desktopReadiness`. Windows readiness requires app identity, the `uia` backend,
+provider/source metadata for complete proof, launch command, verification command, and UIA
+automation-tree evidence. macOS readiness requires app identity, the `accessibility` backend,
+provider/source metadata, launch command, verification command, verified Accessibility permission,
+and an accessibility-tree artifact. Desktop network egress is still reported as
+`desktop-egress-unenforced` unless verified OS-level proxy evidence includes provider, command,
+and artifact path. `bun run verify:desktop-macos-proxy` can create that proof only for an already
+configured macOS system proxy; if no active proxy is found, it writes an unverified artifact and the
+desktop egress blocker remains. The macOS XCTest backend is reserved in the evidence contract but is
+not a live default runner yet.
+
+Process-name-only attachment is allowed for inspection, but it can be ambiguous when multiple
+windows share the same executable. For non-dry-run desktop checks, prefer `--process-id` and
+`--window-title`; the Windows helper refuses missing or ambiguous declared targets instead of
+falling back to an arbitrary desktop window.
+
+### Exhaustive action-tree traversal
+
+Comber treats every discovered surface as an action tree:
+
+- `exercise`: safe in-place controls are clicked, tapped, typed into, or nudged.
+- `follow`: known destinations such as safe web links are enqueued without clicking through.
+- `branch`: route-less controls such as tabs, accordions, dialogs, menus, SPA buttons,
+  Android/iOS tabs, native links, list cells, Windows UIA branch controls, and macOS AX branch
+  controls are activated; any
+  child state they reveal is added to the frontier.
+
+A clean report is only an exhaustive claim when the frontier drains without caps and without
+unreported blind spots. Capped runs, native/desktop egress limitations, desktop opaque UIA subtrees,
+closed shadow roots, cross-origin iframes, unavailable devices, and skipped destructive controls are
+reported as gaps.
+
+Samsung support is Android-plus-OEM validation. Future Samsung profiles must record the exact
+Galaxy model, Android version, One UI version, provider or device source, command,
+screenshots/video, logcat crash buffer, and unavailable device classes. A generic Android
+emulator is not Samsung coverage.
+
+Every run also writes an `exhaustivenessLedger` into `result.json`. It records each discovered
+unit as `exercised`, `followed`, `branched`, `skipped`, `blocked`, or `blind-spot`, with the reason
+and child-state count when applicable. This is the machine-readable audit trail behind the
+headline coverage percentage.
+
+For machines with a working Playwright browser install, `bun run smoke:web-branch` runs a local
+route-less web branch fixture and verifies from the exhaustiveness ledger that Comber creates a
+replayable `webaction:` address and exercises the child control it reveals.
+
+### How a phone maps onto the universal contract
+
+| Contract | Native meaning |
+|---|---|
+| `Surface` | one **screen** (the current accessibility/view hierarchy) |
+| `SurfaceNode` | one **control** - `kind` = control type (`button`/`text-input`/`toggle`/`tab`/`link`/`cell`), `id` = the stable test id (Android resource-id / iOS accessibilityIdentifier / testTag, else text+path), `label` = visible text, `handle` = the raw native node, `disabled`, `intent` (`exercise`/`follow`/`branch`) |
+| `Address` | screen identity — **`id` is the goto handle** (`launch` · `deeplink:<uri>` · `tappath:<base>::<tap>…`), `scope` = screen name/route, `dedupeKey` = destination-screen fingerprint for a tap-path. Frontier de-dups by the goto handle; *structural* "seen this screen?" is the core's `stateFingerprint` — two distinct layers |
+| `entryAddress()` | the launch screen (relaunch, no deeplink) |
+| `goto(addr)` | relaunch + optional deeplink, **or** relaunch-base + replay-taps (tap-path) |
+| `snapshot()` | `viewHierarchy()` → `Surface` |
+| `exercise(node)` | **tap** (default) or **input** (text fields); a tap that reaches a new screen returns it as `ExerciseResult.discovered` (frontier expansion from acting) |
+| probes | `session` (after-goto) · `dom` (after-snapshot) · `crash` (after-exercise) · `logs` (finalize) — each registered with its lifecycle slot |
+
+**Native breakage signals:** `crash` (fail — app left the foreground / a `FATAL EXCEPTION` after an
+action or launch), `anr` (warn — an "Application Not Responding" log line), `frozen` (warn — a tap or
+`viewHierarchy()` that times out), `error-text` (warn — an on-screen error/canary string),
+`assertion-fail` (warn — a declared Maestro flow assertion). All dedupe on a signature keyed by
+**screen scope + kind**.
+
+### The pluggable `MaestroRunner` transport
+
+The driver depends **only** on a `MaestroRunner` interface — the exact same pattern as the API
+driver's pluggable `ApiTransport` — so the whole driver is tested hermetically by injecting a stub
+(no device, no maestro binary). The seam:
+
+```ts
+interface MaestroRunner {
+  launch(appId, deeplink?): Promise<void>;      // the goto reset point
+  viewHierarchy(): Promise<NativeView>;          // the current screen's view tree
+  tap(selector): Promise<void>;
+  input(selector, text): Promise<void>;
+  back(): Promise<void>;                          // softReset — dismiss a dialog / pop a screen
+  foregroundApp(): Promise<string>;              // crash detection (≠ appId ⇒ died)
+  logsSince(sinceMs): Promise<string[]>;         // crash / ANR log scan
+  runFlow?(yaml): Promise<void>;                 // optional — declared-flow assertions
+  screenshot?(): Promise<Buffer>;                // optional — report evidence
+}
+```
+
+The bundled `DefaultMaestroRunner` shells out to `maestro` (ephemeral one-command flows for
+launch/tap/input/back, `maestro hierarchy` for the view tree) and to `adb logcat` / `dumpsys` for
+crash/ANR detection on Android.
+
+### What a LIVE run needs (and what was verified here)
+
+The driver and its mapping/signal logic are covered by a **hermetic** test suite that stubs the
+`MaestroRunner` — **no live device crawl was run** (none was available). A real run requires, none
+of which ship with Comber:
+
+- **Maestro CLI** on `PATH` (`maestro`), plus **`adb`** for Android crash/ANR logs.
+- A **booted emulator / simulator** (or a **Maestro Cloud** session) with the app installed.
+- The exact `DefaultMaestroRunner` command strings reconciled against your installed maestro
+  version — they are a best-effort starting point, marked in `src/native/maestro.ts`, **not** a
+  CI-verified contract.
+- For iOS egress proof, a configured device-level proxy plus a proof command that produces a
+  durable artifact through `scripts/native-ios-proxy-verify.ts`.
+
+### Known gaps (honest, not silent)
+
+- **Network-egress safety is NOT enforced on native v1.** The web driver's SSRF / write-egress gate
+  works by intercepting browser requests; **Maestro cannot proxy traffic**, so there is no
+  equivalent wire-level guard here. The only write protection is the **name-denylist** (destructive
+  controls are observed, never tapped — the core's `deniedName` over the control label). The
+  egress-hardening path is a **device-level proxy** (e.g. mitmproxy) the runner routes through.
+  Comber clears the native egress blocker only when complete verified proxy evidence is provided
+  with provider, command, and artifact path, or when a verified `--egress-proxy-proof` artifact
+  provides those fields. The CLI banner and `nativeAudit.egressEnforced: false` still surface the
+  Maestro transport limitation on every run.
+- **Network-egress safety is NOT enforced on desktop v1.** Windows UI Automation drives the UI tree;
+  it does not intercept process network traffic. Complete verified OS-level proxy evidence is still
+  required to clear `desktop-egress-unenforced`.
+
+### Abstraction limits the native driver surfaced — RESOLVED in contract v2
+
+Building the third driver stress-tested the fixed `Driver` contract. Three seams that web + API
+never exercised showed their edges. Rather than bend the core per-target, the contract was evolved
+(v2) so all three drivers conform and web + API stay **byte-identical** (same findings, coverage,
+dedupe, ordering; the full suite stays green):
+
+1. **`Address.id` conflated "dedupe key" with "goto handle"** — *resolved.* For web a URL is both;
+   for API an operation is both. A native screen's *structural* identity (for dedupe) and its
+   *re-reachability* (for `goto`) are different things. The contract now states the two **distinct
+   dedup layers** explicitly: **FRONTIER de-dup is by the goto handle** (`Address.dedupeKey ?? id`,
+   the `queued` set), while **"have I processed this screen?" is the core's `stateFingerprint`** over
+   the `Surface` (the `visited` set). `id` is documented as the goto handle; the optional
+   `dedupeKey` lets a driver whose handle ≠ structural identity (native tap-paths) collapse distinct
+   handles that reach the same screen. Web/API leave `dedupeKey` unset → unchanged.
+2. **`DriverCapabilities.probes` was a *closed* phase set** the orchestrator hard-coded
+   (`session`/`dom`/`axe`/`links`/`forms`) — *resolved.* Probes are now **driver-registered with a
+   lifecycle slot** (`{ name, slot }`); the orchestrator iterates each driver's probes at the
+   matching slot. The slot set is fixed and reproduces web's exact order — `after-goto` (session),
+   `after-snapshot` (axe, dom, links), `after-exercise` (forms), `finalize` — but *which* probes run
+   is open, so native now registers its own **`crash` (after-exercise)** + **`logs` (finalize)**
+   phases the closed vocabulary forbade.
+3. **The frontier grew only by FOLLOWING links** (`outboundAddresses`), stranding screens reachable
+   *only* by tapping — *resolved.* `exercise()` may now return **`ExerciseResult.discovered`**:
+   Addresses a tap/click navigated to. The orchestrator enqueues them (inScope + caps/dedup), so a
+   native tap-only screen is crawled — returned as a **replayable tap-path** `Address` whose `goto`
+   relaunches the base anchor and re-taps the recorded sequence. Web/API navigate via links
+   (followed, never clicked) and return none. Declaring `--deeplink` is now an *optional* seed for
+   depth, no longer the only way past the launch screen.
+
+## Sinks / Persistence
+
+By default a run writes only the local HTML report + `result.json` under `./runs/`. Opt-in
+**sinks** persist or forward each run's results to any backend — the substrate a hosted tier
+consumes. The baseline ships two generic, dependency-light adapters (no new dependencies; both
+use only the Node stdlib). Each is configured purely by environment variables, fans out via a
+`MultiSink`, **never breaks a run** (a sink failure is caught + logged, the run still passes),
+and is a **no-op when unconfigured** (nothing set = unchanged local-only behavior).
+
+Every record a sink emits is **redacted** (`redactResult`) before it leaves the process, so a
+crawled target's secrets — finding URLs/messages, signed-URL params, OAuth fragments — never
+reach a file or cross the wire.
+
+| Env var | Sink | Effect |
+|---|---|---|
+| `COMBER_SINK_FILE` | **FileSink** | Append one redacted run-summary record (a JSON line) per run to this JSONL file. |
+| `COMBER_SINK_DIR` | **FileSink** | Copy the run's screenshots into this directory, under a per-run `runId` subfolder. |
+| `COMBER_SINK_URL` | **HttpSink** | POST the redacted run record (JSON) to this webhook URL. Covers backend ingest + Sentry-style error-tracking collectors. |
+| `COMBER_SINK_TOKEN` | **HttpSink** | Optional Bearer token for the webhook — sent as an `Authorization` header only, never logged and never in the body. |
+
+```bash
+# Local persistence: a growing JSONL log + a screenshot archive.
+COMBER_SINK_FILE=./comber-runs.jsonl COMBER_SINK_DIR=./comber-shots bun run dev https://example.com
+
+# Forward each run to a webhook / collector with auth.
+COMBER_SINK_URL=https://hooks.example.com/comber COMBER_SINK_TOKEN=… bun run dev https://example.com
+```
+
+Configured sink paths are path-traversal-guarded, and every copied screenshot filename is
+constrained to stay within the target directory.
+
+> **Vendor neutrality.** The baseline carries only these generic adapters. A vendor-specific
+> backend (a database, object store, or hosted error tracker) belongs in an overlay as its own
+> `Sink` implementation against the same interface — it is never added to `src/` here.
+
+## Connectors & marketplace
+
+Where a sink persists the raw record, a **connector** delivers a finished run to where developers
+already work — Slack, Discord, a GitHub PR check, a Linear issue, a JUnit report, or any webhook.
+Connectors are opt-in, declared in the `connectors: [...]` array of `comber.config.json`, and each
+consumes the same **redacted** `RunRecord` a sink does — a third-party connector physically cannot
+receive a crawled-app secret. Six connectors ship built-in; the marketplace is any npm package that
+satisfies the contract, loaded by module specifier.
+
+```jsonc
+{
+  "url": "https://preview.example.com",
+  "connectors": [
+    { "use": "slack", "on": "fail", "mentionOnFail": "<!here>" },
+    { "use": "junit", "outFile": "runs/comber-junit.xml" },
+    { "use": "@acme/comber-teams", "on": "warn" }
+  ]
+}
+```
+
+`use` names a built-in (`slack`, `discord`, `github`, `junit`, `linear`, `webhook`) or an installed
+package; `on` gates delivery by severity (`always` | `warn` | `fail`); all other keys are non-secret
+settings. **Secrets come from the environment, never from config** (e.g. `COMBER_SLACK_WEBHOOK_URL`).
+List the built-ins with `comber connectors`. Full guide — the built-in table, the `RunRecord` shape,
+authoring an external connector, and publishing to the catalog — in
+**[docs/CONNECTORS.md](docs/CONNECTORS.md)**.
+
+## Architecture
+
+```
+cli.ts → crawl.ts ─ drives ─▶ Driver (driver.ts: WebDriver over Playwright)
+            │                     │
+            │  pickActions()      └─ breakage.ts (CDP listeners, console canaries, axe, signatures)
+            │  (Haiku, DOM-first)
+            ▼
+        triage.ts (Opus "genuine defect?" judge) ──▶ report.ts (self-contained HTML)
+```
+
+- **Driver adapter** (`core/contract.ts`) is the seam that makes a surface pluggable. `WebDriver`
+  (Playwright), `ApiDriver` (OpenAPI), and `NativeDriver` (native iOS/Android over a pluggable
+  `MaestroRunner`) all implement the *same shape* — so crawl/breakage/report never change.
+- **Breakage** (`breakage.ts`): deterministic auto-fail (uncaught exceptions, 5xx, failed
+  assets, Next.js regression canaries) + judged tier (axe-core criticals, console noise).
+  Every signal carries a normalized `signature` so a broken shared footer across 50 pages
+  collapses to one finding.
+- **Signal normalization** (`signal-normalize.ts`): removes crawler-caused egress fan-out
+  from warn/fail gates while keeping a transparent `info` finding in the report.
+- **Frontier crawl** (`crawl.ts`): BFS over same-origin states with fingerprint dedupe and
+  hard caps (states / actions / wall-clock / token budget) — the runaway-cost backstops.
+
+## Safety rails (non-negotiable)
+
+- **Destructive-action denylist** (`config.ts`): elements named delete/remove/pay/checkout/
+  cancel/etc. are *observed, never clicked*.
+- **Write blocking is on by default**: mutating HTTP verbs are aborted unless `--allow-writes`
+  is passed for a reviewed synthetic environment.
+- **Private-network egress is always blocked**: browser requests and optional external link
+  checks cannot hit localhost, private IP ranges, link-local metadata, or hosts resolving there.
+- **External link checking is opt-in** via `--external-links`.
+- **Synthetic accounts only** via `COMBER_STORAGE_STATE` — never point an authed crawl at real
+  user data. Use a dedicated throwaway/test account (e.g. `synthetic+comber@yourdomain.test`).
+- Hard caps abort runaway loops; same-origin confinement by default.
+- (Planned) per-app convert-flow guard: upload a 1 KB dummy and STOP before the GPU worker.
+
+## Roadmap
+
+Comber's through-line is one contract — *discover a target's surface → exercise it → classify
+breakage → dedupe → report / baseline / gate* — so new targets land as new **drivers** behind it,
+not core rewrites. See [`PRODUCT.md`](PRODUCT.md) for the model.
+
+- **Now** — web MVP: DOM-first crawler, breakage detection, optional Claude action-picker + judge,
+  self-contained HTML report, baseline diffing, PR comment. ✅
+- **Next** — deterministic selector-cache replay (run the expensive every-click pass once, cheap
+  replays after) ✅; generic persistence sinks (JSONL + screenshot dir, webhook/collector POST)
+  ✅; CI integration on preview deploys — reusable composite **GitHub Action** (`action.yml`),
+  non-blocking PR comment first ✅ (gated on npm publish — see **CI integration** above).
+- **Native** — a `NativeDriver` driving native iOS/Android over a pluggable `MaestroRunner` behind the
+  same contract ✅ (hermetic; a live run needs `maestro` + a booted device — see **Native driver** above).
+- **Desktop native** — Windows UI Automation and macOS Accessibility now ship as desktop adapters
+  behind the same contract ✅. macOS XCTest remains a reserved optional backend, not a default live
+  runner. Desktop evidence/readiness is in place for platform, app identity, automation backend, provider/source, launch command,
+  verification command, screenshots/video/logs/crash logs, accessibility-tree or automation-tree
+  artifacts, and verified OS-level proxy evidence when desktop network egress is claimed controlled.
+- **API / bot** — request/response contract checks as their own breakage-signal set, same pipeline ✅.
+- **Hosted** — multi-tenant dashboard, bring-your-own-key, and billing — the path toward
+  marketplace integrations with CI/deploy platforms.