Robustness: structured nav errors, proxy observability, retries, timeouts, atomic basic-auth

[teodor-georgiev]

Robustness: navigation failures need structure, retries, proxy observability, and timeouts

Found while automating a headed Chromium session on Windows (agent-browser 0.38.1) that repeatedly hung a chat loop. Analysis assisted by design review; filing as one consolidated issue so maintainers can split.

Reproduction evidence

• agent-browser --session directtest --ignore-https-errors --headed --json open https://<verified-live-https-endpoint>/ returns {"success":false,"error":"Navigation failed: net::ERR_CONNECTION_REFUSED"} while the endpoint serves fine via curl from another path (local egress proxy suspected; endpoint also needs basic auth, which would only 401 after connect).
• The browser daemon stays alive holding about:blank; the driving chat hangs waiting and must be forcibly stopped. No timeout surfaces to the caller.

Proposals (ranked)

1. Return structured navigation errors (M). Keep the message, add JSON fields: phase, netError, retryable, sanitized url, attempt, suggested actions. Classify DNS / TCP refusal / proxy tunnel / TLS / timeout / auth / HTTP separately. Today Chromium's errorText is reduced to Navigation failed: …, so agents can't tell a dead endpoint from a proxy or cert problem.
2. Make proxy selection explicit and observable (M). Add --proxy-mode direct|system|env|manual, --no-proxy, and a command reporting effective proxy source (redacted), and bypass-list matching. Today the first available of HTTP_PROXY/HTTPS_PROXY/ALL_PROXY is silently passed to Chrome for all traffic, which explains direct-IP failures and makes ERR_TUNNEL_CONNECTION_FAILED hard to diagnose.
3. Add target-specific diagnostics (L). agent-browser diagnose <url> --json: from the browser machine test DNS, TCP, proxy CONNECT, TLS, and a browser navigation; report where the path failed. doctor checks the install, not the exact target and route.
4. Bounded, error-aware navigation retries (M). open --retries N --retry-delay 500ms --retry-max-delay 5s with jitter + total deadline; retry only transient codes on top-level GET; return attempt history. Retryability should key off proposal 1's classification (never retry auth/policy/cert).
5. Basic auth before the first request (M). Atomic open <url> --http-user USER --http-password-stdin backed by the existing credential handler; keep passwords out of URLs, argv, logs, JSON. Today it takes open (no URL) + set credentials + navigate, inviting accidental unauthenticated first requests.
6. Expose navigation wait/timeout controls (S/M). open <url> --wait-until none|domcontentloaded|load|networkidle --timeout <duration>; reject unknown nav flags instead of ignoring; on lifecycle timeout after commit return committed: true + final URL. Prevents hung chats with no surfacing timeout.
7. Hermetic network failure test matrix (M). Cover delayed listeners, refused/DNS/CONNECT failures, proxy 407, self-signed TLS, protocol mismatch, basic-auth 401/success, retry exhaustion, secret redaction on Windows + Linux.

Effort scale: S ≤1 day, M 2–4 days, L 5–8 days.

Environment: Windows x86_64, agent-browser 0.38.1, local Chrome, headed session via persistent daemon.