docs: clarify reused pool browsers keep stale config until flushed

[AnnaXWang]

Summary

Clarifies a subtle but important browser-pool behavior that wasn't documented: a browser released with reuse: true (the default) re-enters the pool carrying the configuration it was created with. A pool update only rebuilds the browsers that are idle at the time of the update (the default discard_all_idle: true behavior), so a browser that's acquired during an update keeps its old config and, once released with reuse: true, keeps getting handed out that way. It won't pick up the new configuration until it's flushed (a later update() with discard_all_idle: true, or flush()).

Changes

• browsers/pools/overview.mdx — added a <Warning> in the "Update a pool" section explaining reused browsers retain their original config and how to force them onto the new config.
• browsers/pools/faq.mdx — added a matching FAQ entry ("If I update a pool, do browsers that are currently in use pick up the new configuration?"), mirroring the existing profile-staleness entry.

Test plan

• Run mintlify dev and confirm both pages render, the <Warning> callout displays, and the in-page flush() anchor link resolves.

---

Note

Low Risk
Documentation-only changes to pool FAQ and overview; no runtime or API behavior changes.

Overview
Documents that kernel.browserPools.update() only rebuilds idle browsers (default discard_all_idle: true). Browsers acquired during an update keep their original config, and releasing with default reuse: true puts them back in the pool still on the old config.

Adds a <Warning> in the pools overview Update a pool section and a matching FAQ entry (aligned with the existing profile-staleness FAQ). Both explain three remediation paths: reuse: false on release, idle timeout_seconds, or flush() / a later update() with discard_all_idle: true after releases.

^{Reviewed by Cursor Bugbot for commit 14120ce. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Kernel	🟢 Ready	View Preview	Jul 1, 2026, 6:15 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[masnwilliams]

One addition worth folding in: alongside flushing after the fact, it's worth naming the two ways to avoid a stale browser upfront — release with reuse: false (destroys and rebuilds on release instead of returning the old config), or let the acquired browser die via timeout_seconds (the pool refills with the new config automatically). That gives readers both the "prevent it" and "clean it up" paths. Otherwise this reads great — the <Warning> and the flush anchor are the right call.

[masnwilliams]

One addition worth folding in: alongside flushing after the fact, it's worth naming the two ways to avoid a stale browser upfront — release with reuse: false (destroys and rebuilds on release instead of returning the old config), or let the acquired browser die via timeout_seconds (the pool refills with the new config automatically). That gives readers both the "prevent it" and "clean it up" paths. Otherwise this reads great — the <Warning> and the flush anchor are the right call.

[cursor]

Risk assessment: Very Low

Evidence from the current diff: this PR only adds explanatory MDX documentation in browsers/pools/faq.mdx and browsers/pools/overview.mdx (16 added lines total). It doesn't modify runtime code, API behavior, build configuration, infrastructure, prompts, auth, permissions, or shared libraries. I also didn't find a CODEOWNERS file in the repository, so I didn't identify a code-owner review requirement from the repo contents.

The PR is already approved, including by this automation on an earlier revision, so I did not submit another approval. The synchronized changes do not increase the risk level.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 14120ce. Configure here.}

[cursor]

FAQ duplicates overview warning

Low Severity

The new FAQ entry repeats the full <Warning> on browsers/pools/overview (same idle-only update behavior and three remediation paths) instead of a short answer with a link to the canonical “Update a pool” section, unlike patterns such as auth/faq.mdx linking to lifecycle pages.

 

^{Triggered by learned rule: Single source of truth — no deep content duplication across pages}

^{Reviewed by Cursor Bugbot for commit 14120ce. Configure here.}