docs: clarify reused pool browsers keep stale config until flushed (#431)

* docs: clarify reused pool browsers keep stale config until flushed

Reused browsers (release with reuse: true) re-enter the pool carrying
the configuration they were created with. A pool update only rebuilds
browsers that are idle at update time, so a browser acquired during an
update keeps its old config and, once reused, is handed out that way
until it's flushed. Document this in the pools overview and FAQ.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs: add reuse:false and timeout paths for avoiding stale pool config

Give readers both the prevent-it-upfront paths (release with reuse:
false, or let the acquired browser hit timeout_seconds) alongside the
after-the-fact flush.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: AnnaXWang

browsers/pools/faq.mdx

@@ -24,6 +24,12 @@ When a browser from a pool is set to be destroyed (by reaching its specified `ti
 
 Yes, use `kernel.browserPools.update()`. By default, idle browsers are discarded and rebuilt with new configuration. Set `discard_all_idle: false` to only apply changes to newly created browsers.
 
+### If I update a pool, do browsers that are currently in use pick up the new configuration?
+
+No. A pool update only rebuilds the browsers that are idle at the time of the update (the default `discard_all_idle: true` behavior). A browser that's acquired during the update keeps its original configuration, and if you release it with `reuse: true` (the default) it returns to the pool still running the old configuration and keeps getting handed out that way.
+
+You have three ways to get it onto the new configuration: release it with `reuse: false` so it's destroyed and rebuilt on release instead of the old one returning to the pool; let the acquired browser reach its `timeout_seconds` while idle so it's destroyed and the pool refills automatically; or flush it after the fact with `kernel.browserPools.flush()` (or a later `kernel.browserPools.update()` with `discard_all_idle: true`) once the in-use browsers have been released.
+
 ### If I update a profile's contents, will my pool's idle browsers pick up the change?
 
 No. Idle browsers in a pool are pre-loaded with the profile's contents at the time they were filled. Updating the profile (for example, re-saving auth state to the same `profile_id`) does not propagate to already-warmed browsers — only newly-filled browsers will use the updated profile.

browsers/pools/overview.mdx

@@ -236,6 +236,16 @@ The `size` parameter is always required when updating a pool, even if you only w
 
 By default, updating a pool discards all idle browsers and rebuilds them with the new configuration. Set `discard_all_idle: false` to keep existing idle browsers and only apply the new configuration to newly created browsers.
 
+<Warning>
+Reused browsers keep the configuration they were 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). A browser that's acquired during an update keeps its original configuration, and if you then release it with `reuse: true` (the default) it re-enters the pool still carrying that stale configuration and keeps getting handed out that way.
+
+You have three ways to get an in-use browser onto the new configuration:
+
+- **Prevent it on release:** release with `reuse: false`. The browser is destroyed and rebuilt with the current pool configuration instead of the old one returning to the pool.
+- **Let it expire:** don't release the acquired browser for reuse. Let it reach its `timeout_seconds` while idle, at which point it's destroyed and the pool refills automatically with the new configuration.
+- **Clean it up after the fact:** [`flush()`](#flush-idle-browsers) the pool, or run a later `update()` with `discard_all_idle: true`, once the in-use browsers have been released.
+</Warning>
+
 ## Flush idle browsers
 
 Destroy all idle browsers in the pool. Acquired browsers are not affected. The pool will automatically refill with the pool's specified configuration.