Browser Verifier

Browser Verifier

Visibility

This is a verification helper for runtime and browser checks. Prefer running it behind the verification flow unless the user explicitly requests browser verification. When used as a read-only verifier, prefer a forked verification session and return only the structured verdict needed by the caller.

Role

Validate that a web app is reachable and working at runtime after implementation, with optional browser-flow checks layered on top of the existing URL/E2E harness.

Prerequisites

• Running local dev server or staging URL
• Optional E2E command configured in project
• Recommended npm scripts:
  • test:e2e:agent-browser (preferred for feature-flow checks)
  • test:e2e (fallback / existing runner)

Usage

/browser-verifier --url=http://localhost:3000
/browser-verifier --url=http://localhost:3000                         # default browser-flow=smoke + auto-detect E2E script
/browser-verifier --url=http://localhost:3000 --no-auto-e2e           # URL only
/browser-verifier --url=http://localhost:3000 --browser-flow=smoke
/browser-verifier --url=http://localhost:3000 --browser-flow=smoke --browser-only
/browser-verifier --url=https://staging.example.com --e2e="npm run test:e2e:agent-browser"
/browser-verifier --url=https://staging.example.com --e2e="npm run test:e2e"

Runtime Adapter Policy

• claude-code: execute runtime checks through Claude tool routing while preserving forked verifier semantics.
• codex: prefer a fresh forked verification session or equivalent isolated attempt; keep the main session as coordinator and merge back summary results only.
• If the active runtime cannot preserve isolated verifier execution, degrade explicitly to current-session execution and record that isolation was degraded.
• Canonical verifier source is agents/verification/verify-runtime.sh.
• Installed/local profile entrypoint is .claude/agents/verification/verify-runtime.sh when a project-local Claude profile is materialized.

Execution

1. Resolve target URL from --url or APP_BASE_URL (default: http://localhost:3000).
2. If --browser-flow is set, ask the harness to run the configured browser flow runner with browserctl on PATH or <MOONSHOT_RELAY_HOME>/bin/browserctl; use BROWSER_FLOW_RUNNER_PATH only when a project installs a custom runner.
3. If browser runtime is available and the caller did not explicitly choose another flow, treat smoke as the default browser-flow for the standard verification path.
4. Run the installed/local profile entrypoint .claude/agents/verification/verify-runtime.sh with URL and optional browser-flow/E2E arguments from the isolated verifier boundary when available.
5. If --e2e is omitted, the script auto-detects npm scripts in this order:
   • test:e2e:agent-browser
   • test:e2e
6. Classify runtime evidence depth:
   • smoke: URL reachable, page loaded, or a shallow browser smoke check ran.
   • open-act-mutate-persist-recover: a critical scenario opened the flow, acted, changed state, persisted it, and recovered/re-entered successfully.
7. Treat smoke-only evidence for critical SCN-* as warning; it cannot support clean finish by itself.
8. If browser runtime is unavailable and browser-only mode was not requested, return a setup-gap warning and continue through the existing URL/E2E path.
9. If runtime check fails, stop and report environment readiness issue.
10. If browser flow or E2E fails, return failure details and the failing mode.

Output Contract

• pass/fail status
• target URL and HTTP response summary
• optional browser-flow status
• optional browser-flow verdict file at .moonshot-relay/browser-flow-verdict-<runId>.json
• optional E2E result
• runtime evidence depth: smoke, open-act, or open-act-mutate-persist-recover
• critical scenario smoke-only warnings
• next actions (restart server, fix route, rerun tests)
• structured summary suitable for merge-back into the caller session

Browser Flow Artifacts

• Runner verdicts are written to .moonshot-relay/browser-flow-verdict-<runId>.json.
• Screenshots, console events, and network events are written under .moonshot-relay/browser-artifacts/ when the flow requests those artifacts.
• Browser trace metadata is normalized with scripts/verification-plane.mjs normalize-browser-trace --run-id <runId> --goal-id <goalId> --url <url> --flow <flow> --json.
• Normalized trace metadata lives under .moonshot-relay/browser-artifacts/<runId>/<goalId>/<flow>/trace-metadata.json and is linked from the browser verification plane evidence.
• Missing browser runtime or missing flow declarations should produce a setup-gap verdict instead of a hand-written pass.
• Critical SCN-* flows need interaction evidence beyond smoke before clean finish.

Installed/local Profile Script

.claude/agents/verification/verify-runtime.sh --url=<url> [--browser-flow=<name>] [--browser-only] [--browserctl=<path>] [--e2e="<command>"] [--no-auto-e2e]