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 Test Matrix

The current remote PR head is af0261ae6ad9b9bf4da5a56fe6edfcd94d76228b. The complete matrix below ran at b69a671a2f792112d7b1ec08027a67d3d86db34a; the only inherited change since then is #2849's test-helper timeout diagnostic, whose focused network tests and Browse lint/typecheck passed at sidecar head 9887732b6. Its product diff is unchanged from proof commit d2bee7e1cb31e53bb5df1cc793e704793b7a8cd3, where the broader live session-persistence flow below ran. Local cache and daemon paths were isolated from the user's normal configuration.

Command / flow	Observed output	Confidence / sufficiency
Fully verified head b69a671a2: pnpm install --frozen-lockfile; pnpm --filter browse build; browse check; browse lint	Frozen install, real Oclif/TypeScript build, typecheck, Prettier check, ESLint, and the lint-owned second typecheck all passed.	Proves the regenerated lockfile and exact current head build cleanly and satisfy package checks.
Fully verified head b69a671a2: built CLI against the fake Browserbase server plus Context-store suite	2 test files / 23 tests passed. The server observed POST /v1/contexts with name, and session create with resolved context ID plus persist: true.	Deterministically proves exact request shapes, managed/legacy resolution, validation, typo/raw-ID paths, atomic cache behavior, and session persistence.
Fully verified head b69a671a2: live contexts create --name <synthetic-name>; contexts get <synthetic-name>	Production Browserbase echoed the managed name and returned a nonempty ID; get-by-name resolved to the same remote Context.	Fresh proof that the current propagated head composes the cache with the production name field.
Fully verified head b69a671a2: contexts add <legacy-alias> <same-id>; get by alias; try managed create under the alias	Alias resolved to the same remote Context while its Browserbase-managed name stayed unchanged; conflicting create was rejected before POST with exit 1.	Fresh proof that legacy aliases remain usable and cannot be silently repointed.
Product proof head d2bee7e1: live sessions create --context-id <synthetic-name> --persist --timeout 60; release session	Session creation succeeded with a nonempty ID and was explicitly released. The deterministic current-head server test proves the exact resolved-ID/persist: true payload.	Real-service proof of the named-context session path plus fresh deterministic current-head request-shape proof. Product code is unchanged.
Fully verified head b69a671a2: live contexts delete <synthetic-name>; list cache	Remote delete succeeded; both names pointing at the ID were pruned; zero local aliases remained.	Fresh proof that delete-by-name reconciles remote and local state.
Fully verified head b69a671a2: inspect isolated contexts.json after atomic writes	File mode was 0600.	Proves the cache does not regress local state permissions.

The fully verified-head temporary Context was deleted. The earlier temporary session was released and its Context deleted. No credentials, project identifiers, Context/session IDs, or private URLs are included here.

[changeset-bot]

🦋 Changeset detected

Latest commit: af0261a

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.20.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.