fix: respect connectTimeoutMs when waiting for first top-level page

[octo-patch]

Fixes #1287

Problem

On slow machines, Chrome may still be setting up the first tab by the time
the CDP WebSocket handshake completes. V3Context.create() previously
waited a fixed 5 seconds (DEFAULT_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS) for
the first top-level page to register, regardless of any user-supplied
timeout, causing a TimeoutError: waitForFirstTopLevelPage (no top-level Page) timed out after 5000ms on slow hardware.

Solution

Take the maximum of localBrowserLaunchOptions.connectTimeoutMs and the
existing env-var / CI-derived default. This means users who already bump
connectTimeoutMs to accommodate a slow environment automatically get the
same patience when waiting for the initial page—no new API surface needed.

// Before
await ctx.ensureFirstTopLevelPage(getFirstTopLevelPageTimeoutMs());

// After
const firstPageTimeoutMs = Math.max(
  opts?.localBrowserLaunchOptions?.connectTimeoutMs ?? 0,
  getFirstTopLevelPageTimeoutMs(),
);
await ctx.ensureFirstTopLevelPage(firstPageTimeoutMs);

Existing escape hatches (STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS env
var, CI auto-bump to 30 s) are unchanged—this change only applies a
floor when the user has explicitly set a higher connectTimeoutMs.

Testing

• Existing unit and integration tests continue to pass (no change to default behaviour).
• Users on slow machines / WSL2 can now set connectTimeoutMs: 30000 in
  localBrowserLaunchOptions and the first-page wait will scale with it.

---

Summary by cubic

Respect connectTimeoutMs when waiting for the first top‑level page to avoid startup timeouts on slow machines. Fixes #1287.

• Bug Fixes
  • V3Context.create() now waits up to max(localBrowserLaunchOptions.connectTimeoutMs, getFirstTopLevelPageTimeoutMs()) for the first page.
  • Keeps STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS and CI defaults unchanged; no API changes.

^{Written for commit fd9ed12. Summary will update on new commits. Review in cubic}

[changeset-bot]

⚠️ No Changeset found

Latest commit: fd9ed12

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[cubic-dev-ai]

No issues found across 1 file

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

[github-actions]

This PR was approved by @pirate and mirrored to #2025. All further discussion should happen on that PR.

[github-actions]

The mirrored PR #2025 has been merged into main. This original external contributor PR will stay closed as completed.