From a1631cf3fbdbee2439caf0c644eb6b91d83a7c32 Mon Sep 17 00:00:00 2001 From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com> Date: Wed, 1 Jul 2026 18:14:35 +0000 Subject: [PATCH 1/2] 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 --- browsers/pools/faq.mdx | 4 ++++ browsers/pools/overview.mdx | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/browsers/pools/faq.mdx b/browsers/pools/faq.mdx index 9098d83..ebcf26f 100644 --- a/browsers/pools/faq.mdx +++ b/browsers/pools/faq.mdx @@ -24,6 +24,10 @@ 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. 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. It won't pick up the new configuration until it's flushed, either by a later `kernel.browserPools.update()` with `discard_all_idle: true` or by `kernel.browserPools.flush()`. To get every browser onto the new configuration, flush the pool 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. diff --git a/browsers/pools/overview.mdx b/browsers/pools/overview.mdx index 80bfb45..09d9a7d 100644 --- a/browsers/pools/overview.mdx +++ b/browsers/pools/overview.mdx @@ -236,6 +236,10 @@ 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. + +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. It won't pick up the new configuration until it's flushed, either by a later `update()` with `discard_all_idle: true` or by [`flush()`](#flush-idle-browsers). To guarantee every browser runs the new configuration, flush the pool once the in-use browsers have been released. + + ## 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. From 14120cec4d8c8c558abfb843dbf41aec5109f5e1 Mon Sep 17 00:00:00 2001 From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com> Date: Wed, 1 Jul 2026 18:22:52 +0000 Subject: [PATCH 2/2] 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 --- browsers/pools/faq.mdx | 4 +++- browsers/pools/overview.mdx | 8 +++++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/browsers/pools/faq.mdx b/browsers/pools/faq.mdx index ebcf26f..961a641 100644 --- a/browsers/pools/faq.mdx +++ b/browsers/pools/faq.mdx @@ -26,7 +26,9 @@ Yes, use `kernel.browserPools.update()`. By default, idle browsers are discarded ### 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. 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. It won't pick up the new configuration until it's flushed, either by a later `kernel.browserPools.update()` with `discard_all_idle: true` or by `kernel.browserPools.flush()`. To get every browser onto the new configuration, flush the pool once the in-use browsers have been released. +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? diff --git a/browsers/pools/overview.mdx b/browsers/pools/overview.mdx index 09d9a7d..cf6a2ba 100644 --- a/browsers/pools/overview.mdx +++ b/browsers/pools/overview.mdx @@ -237,7 +237,13 @@ 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. -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. It won't pick up the new configuration until it's flushed, either by a later `update()` with `discard_all_idle: true` or by [`flush()`](#flush-idle-browsers). To guarantee every browser runs the new configuration, flush the pool once the in-use browsers have been released. +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. ## Flush idle browsers