docs(api): clarify reuse/discard_all_idle pool config staleness

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 125
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-ebbe079bb2542625826422afd876a3e8b499c579cf45efc5fd50e7982d34df7d.yml
-openapi_spec_hash: db850b61a0d71fe9f4b642df8782d7ae
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-83323f87ab825547b6cd11caa46e2643ebb0a68bbd326d4e07ccab970638fc03.yml
+openapi_spec_hash: 69ed04a66b4ef68e97f7bdc07dfe6df2
 config_hash: 06186eb40e0058a2a87ac251fc07415d

src/kernel/resources/browser_pools.py

@@ -249,8 +249,12 @@ def update(
               Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See
               https://chromeenterprise.google/policies/
 
-          discard_all_idle: Whether to discard all idle browsers and rebuild the pool immediately. Defaults
-              to false.
+          discard_all_idle: Whether to discard all idle browsers and rebuild them immediately with the new
+              configuration. Defaults to false. Only browsers that are idle when the update
+              runs are rebuilt. A browser that is in use during the update keeps its original
+              configuration, and if it is later released with `reuse: true` it returns to the
+              pool with that stale configuration until it is discarded (by this flag on a
+              later update, or by flushing the pool).
 
           extensions: List of browser extensions to load into the session. Provide each by id or name.
 
@@ -554,7 +558,10 @@ def release(
           session_id: Browser session ID to release back to the pool
 
           reuse: Whether to reuse the browser instance or destroy it and create a new one.
-              Defaults to true.
+              Defaults to true. A reused browser keeps the configuration it was created with,
+              so it does not pick up pool configuration changes made while it was in use.
+              Release with `reuse: false`, or flush the pool afterward, to rebuild it with the
+              current configuration.
 
           extra_headers: Send extra headers
 
@@ -797,8 +804,12 @@ async def update(
               Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See
               https://chromeenterprise.google/policies/
 
-          discard_all_idle: Whether to discard all idle browsers and rebuild the pool immediately. Defaults
-              to false.
+          discard_all_idle: Whether to discard all idle browsers and rebuild them immediately with the new
+              configuration. Defaults to false. Only browsers that are idle when the update
+              runs are rebuilt. A browser that is in use during the update keeps its original
+              configuration, and if it is later released with `reuse: true` it returns to the
+              pool with that stale configuration until it is discarded (by this flag on a
+              later update, or by flushing the pool).
 
           extensions: List of browser extensions to load into the session. Provide each by id or name.
 
@@ -1102,7 +1113,10 @@ async def release(
           session_id: Browser session ID to release back to the pool
 
           reuse: Whether to reuse the browser instance or destroy it and create a new one.
-              Defaults to true.
+              Defaults to true. A reused browser keeps the configuration it was created with,
+              so it does not pick up pool configuration changes made while it was in use.
+              Release with `reuse: false`, or flush the pool afterward, to rebuild it with the
+              current configuration.
 
           extra_headers: Send extra headers
 

src/kernel/types/browser_pool_release_params.py

@@ -14,5 +14,8 @@ class BrowserPoolReleaseParams(TypedDict, total=False):
     reuse: bool
     """Whether to reuse the browser instance or destroy it and create a new one.
 
-    Defaults to true.
+    Defaults to true. A reused browser keeps the configuration it was created with,
+    so it does not pick up pool configuration changes made while it was in use.
+    Release with `reuse: false`, or flush the pool afterward, to rebuild it with the
+    current configuration.
     """

src/kernel/types/browser_pool_update_params.py

@@ -21,9 +21,13 @@ class BrowserPoolUpdateParams(TypedDict, total=False):
     """
 
     discard_all_idle: bool
-    """Whether to discard all idle browsers and rebuild the pool immediately.
-
-    Defaults to false.
+    """
+    Whether to discard all idle browsers and rebuild them immediately with the new
+    configuration. Defaults to false. Only browsers that are idle when the update
+    runs are rebuilt. A browser that is in use during the update keeps its original
+    configuration, and if it is later released with `reuse: true` it returns to the
+    pool with that stale configuration until it is discarded (by this flag on a
+    later update, or by flushing the pool).
     """
 
     extensions: Iterable[BrowserExtension]