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 9db21cd · run

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

Attempt details

• basic (native) attempt 1 — PASS: login evidence: PASS (post-login plan=true, post-login research=true); research: PASS (files=9, wellFormed=true, keywords=7/3); scenarios: PASS (tests=6/5, features=4/3); tests passed: PASS (5 passed, 0 failed (reporter: 5 passed, 0 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

The Issues page filtering and creation flows are functional. All core filtering capabilities (status, search, label, and combined filters) work correctly. The main observation is that some UI interactions required retries, suggesting minor automation reliability concerns rather than product defects.

Coverage

• Pages: /issues
• Features: Create issue, filter by status, search, filter by label, combined filters

What works

• Issue creation — ET-1 Create new issue via toolbar button
• Status filtering — ET-2 Filter issues by status
• Search functionality — ET-3 Search for issues using search box
• Label filtering — ET-4 Filter issues by label using dropdown
• Combined filters — ET-5 Apply multiple filters simultaneously

Execution Issues

• ET-1 Create new issue via toolbar button — initial click on New Issue button failed, required multiple locator attempts
• ET-2 Filter issues by status — Apply filters button click failed initially, succeeded on retry
• ET-4 Filter issues by label using dropdown — label dropdown open click failed initially, succeeded on retry

[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