[GRO-1908] Make missing daemon errors actionable

[Kylejeong2]

Summary

• translate daemon socket ECONNREFUSED and ENOENT failures into a human-readable error
• print the exact browse open command that restarts the requested session
• document that API keys are forwarded to an already-running daemon and that browse stop is idempotent
• preserve regression coverage for late environment variables and exit-code-zero cleanup

Root cause

The daemon client passed raw Unix socket errors through to users when the daemon disappeared between the readiness check and the request. Agents received ECONNREFUSED without a recovery command.

Impact

Agents now get an actionable daemon_not_running failure with the exact command needed to restart the session. The bundled SKILL.md also makes the already-fixed env timing and stop behavior explicit.

Validation

• pnpm turbo run build --filter=browse...
• pnpm --dir packages/cli exec vitest run tests/driver-foundation.test.ts tests/daemon-forwarded-env-drift.test.ts (36 tests)
• pnpm --dir packages/cli check
• pnpm --dir packages/cli format:check
• pnpm --dir packages/cli eslint

Linear: GRO-1908

---

Summary by cubic

Make missing daemon errors actionable by replacing raw socket failures with a clear daemon_not_running message that includes the exact browse open command for the session. Addresses Linear: https://linear.app/browserbase/issue/GRO-1908/cli-namespace-2027-dev-suggested-docs-updates.

• Bug Fixes
  • Map ECONNREFUSED/ENOENT to daemon_not_running and print the exact browse open command (session-aware, preserves URL quoting).
  • Document that BROWSERBASE_API_KEY is forwarded on every command and that browse stop is idempotent (exit code 0 when nothing to stop).
  • Add tests for the new error message and keep coverage for env forwarding and cleanup behavior.

^{Written for commit b1d217f. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: b1d217f

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