[STG-1752] fix(cli): default browse env local to isolated

[shrey150]

Summary

• make browse env local default back to an isolated local browser
• add browse env local --auto-connect as the explicit opt-in path for auto-discovering a debuggable local Chrome
• keep explicit CDP attach via browse env local <port|url> and add tests to lock in the strategy behavior

Why

browse env local was auto-attaching to an existing local Chrome by default. That can trigger Chrome's remote debugging approval dialog unexpectedly and makes isolated local usage less predictable.

Impact

Users now get a clean local browser by default, while still having two explicit ways to reuse an existing browser when they want to:

• browse env local --auto-connect
• browse env local <port|url>

Test Plan

• pnpm --filter @browserbasehq/browse-cli build
• pnpm --filter @browserbasehq/browse-cli test
• pnpm exec prettier --check packages/cli && cd packages/cli && pnpm run eslint && pnpm run typecheck
• e2e smoke test against a disposable Chrome CDP endpoint on 127.0.0.1:9229 using a temporary HOME / user-data-dir so the checks do not touch a real browsing profile
• verified browse env local returns localStrategy: "isolated"
• verified browse status in isolated mode reports localSource: "isolated"
• verified browse env local and browse status both print the hint to use browse env local --auto-connect to reuse local credentials/cookies
• verified browse env local --auto-connect returns localStrategy: "auto"
• verified browse env local --auto-connect prints the hint that plain browse env local switches back to an isolated Chromium browser
• verified open https://example.com succeeds after --auto-connect
• verified browse status after --auto-connect reports localSource: "attached-existing" with the resolved CDP URL and the isolated-browser hint
• verified browse env local 9229 returns localStrategy: "cdp"
• verified browse status after browse env local 9229 reports localSource: "attached-explicit"

Linear: STG-1752

---

Summary by cubic

Defaulted browse env local to a clean, isolated browser. Added --auto-connect to opt into reusing a debuggable Chrome, kept explicit CDP attach via browse env local <port|url>, and added mode hints to guide users. Addresses Linear STG-1752 to make local usage predictable and avoid surprise debugging prompts.

• New Features

  • Isolated local browser is now the default; auto-discovery only with --auto-connect.
  • Mode hints in browse env/browse status suggest when to use --auto-connect or switch back to isolated.
  • browse env local <port|url> remains for explicit CDP targets.
  • Centralized strategy resolution in src/local-strategy.ts with unit tests.
  • Clearer browse env usage and validation; rejects mixing --auto-connect, --isolated, or a target. --isolated is deprecated (accepted; hidden from help).

• Migration

  • To reuse an existing Chrome: browse env local --auto-connect.
  • To attach to a specific target: browse env local <port|url>.
  • No changes if you want a clean isolated browser by default.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: a132cb1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

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

Not sure what this means? Click here to learn what changesets are.

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

[cubic-dev-ai]

No issues found across 8 files

Confidence score: 5/5

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

Architecture diagram

sequenceDiagram
    participant User
    participant CLI as CLI (Commander)
    participant FS as Local Config Store
    participant Resolver as NEW: Local Strategy Resolver
    participant Discovery as CDP Discovery
    participant Browser as Local Chrome / Stagehand

    Note over User,Browser: Environment Configuration Phase

    User->>CLI: browse env local [target] [--auto-connect]
    CLI->>CLI: CHANGED: Validate conflicting flags<br/>(auto-connect vs target vs isolated)
    
    alt Valid configuration
        CLI->>FS: NEW: Save LocalConfig (strategy + cdpTarget)
        CLI->>FS: Trigger Daemon Restart
    else Invalid configuration
        CLI-->>User: Error: Conflicting options
    end

    Note over User,Browser: Runtime Strategy Resolution (Daemon Start)

    CLI->>FS: Read LocalConfig
    FS-->>CLI: strategy (isolated | auto | cdp)

    CLI->>Resolver: NEW: resolveLocalStrategy(config)

    alt strategy == "isolated" (NEW DEFAULT)
        Resolver-->>CLI: Return LaunchOptions (Clean Browser)
    else strategy == "cdp" (Explicit Target)
        Resolver->>Resolver: Resolve WS URL from port/URL
        Resolver-->>CLI: Return LaunchOptions (Attach to Target)
    else strategy == "auto" (--auto-connect)
        Resolver->>Discovery: discoverLocalCdp()
        alt Found existing Chrome
            Discovery-->>Resolver: wsUrl
            Resolver-->>CLI: Return LaunchOptions (Attach to Existing)
        else No Chrome found
            Discovery-->>Resolver: null
            Resolver-->>CLI: CHANGED: Fallback to LaunchOptions (Isolated)
        end
    end

    CLI->>Browser: Start/Connect via Stagehand
    Browser-->>CLI: Session Started
    CLI->>FS: NEW: Save LocalInfo (localSource, resolvedCdpUrl)

    CLI-->>User: Output JSON Status (mode, localStrategy, localSource)

Loading