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/resources/browser-pools.ts

@@ -581,8 +581,12 @@ export interface BrowserPoolUpdateParams {
   chrome_policy?: { [key: string]: unknown };
 
   /**
-   * 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).
    */
   discard_all_idle?: boolean;
 
@@ -752,7 +756,10 @@ export interface BrowserPoolReleaseParams {
 
   /**
    * 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.
    */
   reuse?: boolean;
 }