refactor: redesign Explorer API to a minimal, recovery-ambient interface

[DavertMik]

Summary

Explorer had grown into a god-module: ~42 public members mixing six concerns, four inconsistent error policies for the same failure, seven service-locator getters, and a public playwrightHelper that let 18 call sites reach raw Playwright internals — which in turn forced the whole recovery machinery to be public. This PR reshapes it into a deep module with a 13-member interface.

The new interface

class Explorer {
  get actor()                                 // CodeceptJS I, for user hooks
  get page(): Page | null                     // raw peek, null-safe, NO recovery (background consumers)
  get activeTest(): Test | null
  start() / stop()                            // idempotent
  action(): Action                            // recovery-aware
  visit(url, { screenshot? }): ActionResult   // navigate + observe in one call
  capture({ screenshot? }): ActionResult
  withPage(fn)                                // THE page seam — recovery-wrapped
  exitIframe()                                // no-op outside a frame
  recover(error?)                             // single recovery entry point
  beginTest(test): TestRun                    // { started, stop(meta) } handle
  openFreshTab()
}

Key changes

• Recovery is ambient, not opt-in. Every page-touching member passes through one internal recovery ladder (readiness-wait → page reattach → browser restart → retry once). The five public recovery entry points collapse into recover(error?). This also fixes a real bug: Actions created via bare createAction() silently bypassed recovery while executeAction got it.
• playwrightHelper is private. withPage(fn) replaces all 18 external raw-page reaches and the 5 caller-side runWithBrowserRecovery wraps; the page getter covers the three background peek-only consumers (axe scans, screencast) where triggering recovery would race the main flow.
• Explorer stops being a service locator. Agents receive an AgentDeps object (src/ai/agent.ts); TaskAgent owns the shared fields and getters. ExplorBot now truly owns StateManager, Reporter, RequestStore, and PlaywrightRecorder via lazy accessors and injects them downward.
• Test lifecycle is a handle. beginTest(test) returns TestRun { started, stop(meta) }, making the old startTest(a)/stopTest(b) mismatch unrepresentable; page watchers are fully internal.
• Element annotation moved to web- utils. utils/web-annotate.ts (annotatePageElements) and utils/web-eidx.ts (eidxInContainer, eidxByLocator) are page-taking functions called through withPage.
• Tabs are observed state. stateManager.otherTabs replaces the hasOtherTabs/getOtherTabsInfo/clearOtherTabsInfo trio.

User-visible behavior

• Browser crash recovery now applies uniformly to every operation — sessions self-heal where some paths previously failed permanently.
• Captain's browser tool: the restart action merged into recover (recovery escalates to restart automatically).

Verification

• 872/872 unit + integration tests pass against the committed tree in isolation
• biome check clean; scoped tsc shows no new errors beyond pre-existing ones
• Net −56 lines despite the new DI wiring and two extracted util modules

Not run: tests/regression (real-AI harness) — recommend one live session before merging.

Follow-up (out of scope)

Action still exposes its own playwrightHelper (single read at navigator.ts:357) — same leak one layer down, worth a companion cleanup.

🤖 Generated with Claude Code

[github-actions]

Explorbot Self-Regression

Commit 2437774 · run

Scenario	Result	Attempts	Duration
basic (native)	PASS	1/3	10m
experience: control	OK — failed as expected	1/1	1m
experience: seeded	PASS	1/3	1m

Attempt details

• basic (native) attempt 1 — PASS: login evidence: PASS (post-login plan=true, post-login research=true); research: PASS (files=6, wellFormed=true, keywords=7/3); scenarios: PASS (tests=6/5, features=5/3); tests passed: PASS (5 passed, 0 failed (reporter: 4 passed, 1 failed))
• experience: control attempt 1 — PASS: control: OK — failed as expected (0 passed, 1 failed)
• experience: seeded attempt 1 — PASS: seeded: PASS (1 passed, 0 failed)

---

Session analysis — basic (native):

Session Analysis

Issue tracking functionality was exercised across creation, labeling, filtering, and search flows. All five tests passed with core functionality verified, though success toast visibility was not reliably confirmed.

Coverage

• Pages: /issues, /issues?new=1, /issues?q=, /issues?label=1, /issues?status=open
• Features: Issue creation, label assignment, status filtering, label filtering, keyword search

What works

• Issue creation — ET-1 Create new issue with basic fields, ET-2 Create issue with label assignment
• Status filtering — ET-3 Filter issues by status
• Label filtering — ET-4 Filter issues by label
• Keyword search — ET-5 Search for existing issue by keyword

Execution Issues

• ET-1 Create new issue with basic fields — success toast not detectable by automation despite issue created successfully
• ET-2 Create issue with label assignment — success toast not visible after creation, label applied and persisted correctly

[DenysKuchma]

This no-op stop leaves the already started test lifecycle unfinished because test.start() and reportTestStart() were called above. Defer them until recovery succeeds or finalize the failed test

[DenysKuchma]

Remove from docs playwrightLocatorCount