@phantomagent/browser-executor

Homed in phantom/integrations/packages/browser-executor (WSL).
Formerly lab-only @phantom/browser-executor on Windows Repos.
≠ Nest-wired · ≠ M4 PASS · feature flag default OFF

≠ Nest-wired / Steel-seam proven · ≠ readyForRealSite · ≠ Proven Hydrate Session Plane
Gate C · M2.2 park · Slice 3 PASS are platform prereqs — not Track B integration proof.
Founder decision #6 (2026-08-04): flag-only parallel build.
Lab board CLOSED → see docs/TRACK_B_READINESS_REPORT.md · next M4 Attested Steel Attachment.

Track B never discovers browsers.
Nest decides. Track B enforces.

Isolated upstream-Playwright browser executor with a Phantom security wrapper.

Caller (test harness today; Nest later)
  → AuthorizedBrowserContext
  → Phantom Browser Executor (this package)
  → upstream Playwright
  → existing Chromium session (CDP attach)

The executor never decides whether a user/agent is authorized. It only enforces a short-lived context supplied by a trusted caller.

Nest production imports

Nest production code must import @phantom/browser-executor/nest-seam only for GovernedBrowserSession, resolver mocks, and seam types.

| Subpath | Use | |---------|-----| | @phantom/browser-executor/nest-seam | Nest transplant seam (production shape) | | @phantom/browser-executor/lab | CDP launch / lab attach (tests & local harness) | | @phantom/browser-executor (root) | Contracts, executor core, Track B lab/tests only — not Nest runtime |

Workers must never receive raw CDP or import /lab from product paths.

Feature flag

PHANTOM_BROWSER_GENERAL_EXECUTOR_ENABLED=false   # default / required for product

All public entrypoints refuse to run when the flag is not explicitly true.

Quick start (Windows / PowerShell)

cd C:\Users\Ben\Repos\phantom-browser-executor
npm install
npx playwright install chromium
npm run verify

Package entrypoints (Nest transplant hygiene)

| Import | Use | |--------|-----| | @phantom/browser-executor/nest-seam | Only Nest production import — GovernedBrowserSession, synthetic lab builders | | @phantom/browser-executor/lab | Local CDP launch/attach harness — not Nest product | | @phantom/browser-executor (root) | Track B tests / contracts — do not use as Nest transplant surface (re-exports lab helpers) |

Hard restrictions

Do not:

• modify Gate C / browser_navigate_read_title / HydrationGrant spend / Paperclip #206
• enable this in hosted environments
• expose raw Playwright, CDP endpoints, cookies, or storageState to workers
• claim Gate C PASS or general executor wired
• collide with Slice 3 / VAN-94 content-read dogfood

Docs

| Doc | Purpose | |-----|---------| | docs/SEMANTIC_BROWSER_ACTIONS.md | Product contract (phantom.browser.*) | | docs/PLAYWRIGHT_SURFACE_MAPPING.md | Implementation inventory (Playwright → semantics) | | docs/BROWSER_ACTION_V1_CONTRACT.md | Action / result TypeScript schemas | | docs/BROWSER_EXECUTOR_SPIKE_REPORT.md | What was proven | | docs/BROWSER_EXECUTOR_THREAT_MODEL.md | Threat model | | docs/BROWSER_EXECUTOR_TEST_MATRIX.md | Test coverage | | docs/M2_2_TRACK_B_INTEGRATION_CONTRACT.md | Nest/M2.2 seam contract | | docs/STEEL_ATTACH_DOGFOOD_RUNBOOK.md | Post–Slice 3 Steel attach dogfood (docs only) | | docs/TRACK_B_SLICE3_SAFE_BOARD.md | Parallel board vs Slice 3 | | docs/BROWSER_EXECUTOR_INTEGRATION_GAP.md | Nest/Steel seam gap |

Authority

Canonical Phantom docs: docs/engineering/BROWSER_EXECUTOR_INTEGRATION_GAP.md · docs/engineering/M2_2_TRACK_B_INTEGRATION_CONTRACT.md · SEC-DEC-710 / SURF-BROWSER-SEMANTIC-ACTIONS