[STG-2501] docs(cli): make unique named sessions the default in bundled browse skill

[shrey150]

Summary

Two agents running the browse CLI in parallel clobber each other when they share a browser session — reported on browse 0.9.4: two Claude Code sessions mixed up each other's pages until one agent noticed the shared default session "got hijacked" and recovered by improvising a named session.

Reproduced with parallel Claude subagents against the shipped skill text. Two distinct failure modes, one root cause — session identity is not unique per agent:

1. Bare default sharing. Quick one-off tasks run session-less commands (browse open <url> --local) because the skill's guidance is conditional ("named sessions for any non-trivial work… when multiple agents or parallel tasks may run at once" — a condition an agent cannot evaluate, since sibling sessions are invisible to it) and the first seven example commands in the file carry no --session. Repro: two parallel subagents given trivial tasks both landed on "session": "default" and both ran bare browse stop at the end — each stop tears down the other's browser.
2. Colliding names. Even when agents follow the "use a named session" guidance, nothing says the name must be unique. Repro: two parallel subagents with similar prompts independently chose --session example-task; one agent's click showed up in the other's snapshots (the victim interpreted it as "the site silently redirected"), and the first finisher's browse stop --session example-task killed the sibling's browser mid-task, forcing a doctor → stop → re-open recovery cycle.

Amplifier: after a sibling's stop tears down the shared daemon, the victim's next command auto-starts a fresh daemon — which defaults to remote mode when BROWSERBASE_API_KEY is set (existing documented behavior), silently spinning up a paid cloud session for what the agent thinks is local work.

Fix (docs-only, bundled skill text)

Make unique task-derived session names the modeled default in packages/cli/skills/browse/SKILL.md:

• --session research-a7f added to the anchor examples in Browser Target Selection (the block agents copy verbatim)
• the conditional named-session paragraph is now unconditional, requires a task-derived name plus a unique suffix, and explains what sharing actually does (active page replaced, refs invalidated, sibling stop kills your browser)
• Parallel Browser Work: uniqueness matters as much as naming; when spawning subagents, assign each one its session name (or set BROWSE_SESSION per subagent) instead of letting them choose
• Best Practices rule 6 strengthened to match
• new Troubleshooting bullet: how to recognize a hijacked session (page you never navigated to, refs stop matching, session dies mid-task) and recover by moving to a fresh unique name

No changeset: skill-text-only change, no runtime/package behavior change (same treatment as #2235, #2245).

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
Baseline: 2 parallel Claude subagents, trivial one-off task framing, shipped skill text (browse 0.9.1 local install; identical skill text to 0.9.4/main)	Both ran bare browse open <url> --local → "session": "default" in JSON output; both ran bare browse stop on the shared session	Reproduces failure mode 1: agents default to the shared default session on quick tasks
Baseline: 2 parallel Claude subagents, multi-step tasks with similar prompts	Both independently picked --session example-task; arm B's snapshot showed the IANA page arm A had clicked into (urlMap → https://www.iana.org/help/example-domains on a task that never navigated there); arm A's browse stop --session example-task killed arm B mid-task (about:blank, then "already running in remote mode" on re-open)	Reproduces failure mode 2: named-but-colliding sessions clobber exactly like default sharing
Post-fix: same 2 trivial prompts, agents pointed at the updated SKILL.md	--session check-ex1a and --session httpbin-a1b — unique task-derived names, correct title/heading/URL output, each stopped only its own session	Fixes mode 1: trivial tasks now start unique named sessions
Post-fix: same 2 multi-step prompts, agents pointed at the updated SKILL.md	--session iana-check-x7q and --session research-ex01 — distinct names, no literal copy of the research-a7f example suffix, no foreign pages in any snapshot, clean isolated stops	Fixes mode 2: derived names no longer collide; the concrete example suffix is not copied verbatim
pnpm turbo run build --filter=browse then pnpm vitest run tests/skills.test.ts tests/skills-install.test.ts in packages/cli ()	Test Files 2 passed (2) / Tests 33 passed (33)	Skill install/catalog tests unaffected by the text change
npx prettier skills/browse/SKILL.md --check	All matched files use Prettier code style!	Formatting gate clean

Post-fix rows point agents at the updated file explicitly (installed copies keep the old text until the next release picks this up); baseline multi-step agents read the shipped text. n=2 per arm — behavioral evidence, not a statistical guarantee.

Linear: STG-2501

🤖 Generated with Claude Code

---

Summary by cubic

Make unique named sessions the default in the bundled browse skill so parallel agents don’t share the default session or collide on the same name. Updates packages/cli/skills/browse/SKILL.md to add --session to anchor examples, require task‑derived names with a unique suffix (and use them in the parallel‑work example), add guidance for subagents and a troubleshooting tip, and clarify BROWSE_SESSION; no runtime changes (Linear STG‑2501).

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3f1e607

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

[cubic-dev-ai]

1 issue found across 1 file

Confidence score: 5/5

• In packages/cli/skills/browse/SKILL.md, the example under the parallel-work rule still uses collidable names (search-a/search-b), which could confuse contributors and lead to occasional branch/worktree naming collisions if copied as-is; update the example to task-derived names with unique suffixes before merging to fully align guidance.

Architecture diagram

sequenceDiagram
    participant A as Agent A
    participant B as Agent B
    participant CLI as browse CLI
    participant DM as Daemon (Session Manager)

    Note over A,DM: CHANGED: Docs now enforce unique session names
    alt BEFORE: No --session → shared "default" session
        A->>CLI: browse open url --local
        B->>CLI: browse open url --local
        CLI->>DM: session "default" (shared)
        A->>CLI: browse stop
        CLI->>DM: kill session "default" (kills B)
    else AFTER CHANGED: Unique session names per task
        A->>CLI: browse open url --session research-a7f --local
        B->>CLI: browse open url --session data-b3c --local
        CLI->>DM: sessions "research-a7f" & "data-b3c"
        A->>CLI: browse stop --session research-a7f
        CLI->>DM: stop session research-a7f only
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[shrey150]

Parking this as draft deliberately: we prototyped and validated a CLI-side fix (auto-generated session names, branch shrey/browse-auto-session-prototype) that would supersede most of this guidance. Holding to avoid shipping skill text we immediately rewrite. Context: STG-2501.