diff --git a/README.md b/README.md
index c801da8..448c4a1 100644
--- a/README.md
+++ b/README.md
@@ -60,7 +60,8 @@ impossible without it. (Infura notably does not.)
 |---|---|
 | `configure(config)` | Validate and store config. Synchronous; starts nothing. |
 | `getConfig()` | Effective config, credentials redacted. |
-| `start()` / `stop()` | Blocking, bounded by `startTimeoutMs` / `drainTimeoutMs`. |
+| `start()` | Blocks until the light client initialises, bounded by `startTimeoutMs`. |
+| `stop()` | Drains, then releases. See the note on `drainTimeoutMs` below — it is not a tight bound. |
 | `ok()` / `status()` | Health probe and full state. `status()` never blocks on the proxy thread. |
 | `rpc(method, params)` | Any method the proxy supports. `params` is a JSON-RPC array. |
 | `ethBlockNumber()`, `ethGetBalance(...)`, `ethCall(...)`, … | Typed wrappers over the same path. |
@@ -87,7 +88,8 @@ is enabled by setting `opExecutionApiUrls` (there is no `op-*` network name in
 the library's JSON config — that is a CLI-only option on the standalone binary).
 
 Module-side knobs: `callTimeoutMs` (30000), `startTimeoutMs` (120000),
-`drainTimeoutMs` (2000), `pumpIntervalMs` (50), `maxInFlight` (64),
+`drainTimeoutMs` (2000 — a polling bound, see below), `pumpIntervalMs` (50),
+`maxInFlight` (64),
 `keepAlive` (`off` | `interval` | `continuous`), `keepAliveIntervalMs` (1000),
 `autoStart` (false). Upstream tuning lives under `tuning`.
 
diff --git a/src/verified_proxy_impl.h b/src/verified_proxy_impl.h
index a4e75b0..06142b1 100644
--- a/src/verified_proxy_impl.h
+++ b/src/verified_proxy_impl.h
@@ -74,7 +74,17 @@ public:
     StdLogosResult start();
 
     /// Stop the proxy: drain in-flight calls, then release the context.
-    /// Blocks up to `drainTimeoutMs`. Also emits `proxyStopped`.
+    ///
+    /// `drainTimeoutMs` (default 2000) bounds when the drain stops STARTING new
+    /// turns of the library's task pump — not when this returns. The deadline is
+    /// checked between calls into the library, and one such call was measured
+    /// blocking for up to 3.3s, so budget `drainTimeoutMs` plus up to one pump
+    /// duration. Bounded, but not tight: a measured stop() took 1102ms.
+    ///
+    /// Callers still blocked in an RPC call are released with
+    /// "proxy shutting down" rather than waiting out their own timeout.
+    ///
+    /// Also emits `proxyStopped`.
     StdLogosResult stop();
 
     /// True when the proxy is running and its last heartbeat succeeded.