Host origin allowlist on start

[yashranaway]

What an agent cannot do today

visit and in-page navigation accept any http(s) URL that passes the existing scheme, credential, and dangerous-extension checks. A prompt-injected agent can leave the app under test and open an arbitrary site. The host has no origin allowlist.

Proposed surface

headless start --allow localhost --allow '*.staging.example.com'
headless start --allow localhost,127.0.0.1
headless status   # ping includes navigationAllowlist

Repeatable --allow. Comma-separated values in one flag are also accepted. No --allow keeps today's behavior: any otherwise-legal http(s) URL.

When the list is set, a visit or top-frame navigation whose host does not match fails with UNSAFE_NAVIGATION. status / ping report the active list. Changing the list on an already-running host is rejected; stop first.

Engines

Both. Same matcher in agentMayNavigate, WKWebView decidePolicyFor, Linux frame-event enforcement, and the in-page click guard.

Contract

This is a host-enforced boundary, not a prompt rule. Record an architecture-decision entry in the same PR.

• Still http/https only. --allow cannot add file:, javascript:, credentials, or blocked extensions.
• Empty list after parsing --allow with no patterns is invalid.
• Patterns are hosts, optional :port, optional leading *.. * alone is rejected. Non-ASCII / unexpected characters fail closed.
• *.example.com matches subdomains of example.com, not example.com itself, and not example.com.evil.test.
• localhost matches any port on localhost. localhost:3000 matches only that port.
• Cap at 32 patterns. Unknown flags still fail closed.
• Page JS cannot read or change the list. The click guard gets it from the host-injected runtime.
• Capabilities / ping show the active list so agents can see the restriction.
• If start --allow hits a host that is already running with a different list, fail. Do not silently keep the old policy.

Tests

Protocol suite: parse, reject *, reject file: hosts, wildcard non-matches, port exactness, visit denied, ping reports the list.

Linux E2E and macOS E2E: start with --allow for the fixture host, visit the fixture, deny example.com, deny a click that would leave the allowlist.

Docs

COMMANDS.md, agentHelp, AGENTS.md / skill safety notes, capabilities. Web lint provenance if command tables are generated from help.