fix(cli): persist context names in Browserbase

[shrey150]

Summary

Move new CLI-created Context names onto the production Browserbase Contexts API while preserving existing local aliases.

• Send --name to the Context create API; Browserbase owns the canonical project-scoped name.
• Keep the local name-to-ID file as a device cache because Context/session operations still require IDs and the public API has no list or lookup-by-name endpoint.
• Preserve arbitrary aliases created by older CLI versions.
• Reject a managed-name create that would silently repoint an existing alias; offer explicit contexts add ... --force reconciliation.
• Label list output as Local name so cache aliases are not mistaken for an authoritative server list.

Stack (#2872)

1. chore(cli): import Browse V3 baseline #2833 — exact Browse V3 baseline import
2. refactor(cli): migrate Browse runtime and commands to Stagehand V4 #2834 — Stagehand V4 runtime and standard command parity
3. feat(cli): restore cursor overlay through page.evaluate #2869 — CLI-owned cursor overlay
4. fix(cli): restore V3 network capture through a CDP sidecar #2849 — CLI-private CDP sidecar; V3 network parity
5. refactor(cli): remove coordinate XPath return flag #2835 — remove --return-xpath; supported V3 parity/release checkpoint
6. test(evals): exercise the workspace V4 CLI #2838 — eval and packaging integration
7. fix(cli): persist context names in Browserbase #2839 — managed Context names (fast-follow)
8. refactor(cli): consume shared Functions core #2701 — shared Functions core consumer (fast-follow)

Why the cache remains

The production API stores an optional name, but current Context and Session calls still address Contexts by opaque ID. Removing the cache would regress get <name>, sessions create --context-id <name>, and delete <name> without a server-side replacement. contexts add therefore remains explicitly a local alias, not a Browserbase rename operation.

E2E verification

Flow	Observed result
Live contexts create --name	Browserbase returned the same managed name and a Context ID
Live contexts get <local-name>	Device cache resolved the ID; API returned the managed name
Live contexts list --json	Cached name-to-ID entry was present
Duplicate legacy alias fixture	Rejected before POST with reconciliation guidance; original alias unchanged
Live delete then get-by-ID	Remote Context and local alias removed; get returned not found
Context feature proof-commit lint/build/typecheck	Passed on a6771d3374
Context feature proof-commit full Browse suite	27 files / 384 tests passed

The temporary Context was deleted. No credentials, project identifiers, or Context IDs are included here.

[changeset-bot]

🦋 Changeset detected

Latest commit: 82ba9d7

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

This PR includes changesets to release 1 package

Name	Type
browse	Patch

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

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​browserbasehq/​sdk@​2.19.0

View full report

[shrey150]

Have we thought about how this affects existing CLI users that have their context names saved locally, and what happens if they don't match the managed name on the Browserbase platform?

[shrey150]

Re: the comment by @shrey150 — Addressed in 659d327f1. Existing cached names remain valid local aliases and keep resolving to their saved Context IDs even when the Browserbase-managed name differs. The CLI does not auto-remap them. A colliding contexts create --name now fails before making an API request, so it cannot silently overwrite a legacy mapping; help/docs and an end-to-end mismatch regression cover the migration behavior.