@@ -352,6 +352,10 @@ test('a source capture that runs out of budget keeps the timeout reason and name
     assert.equal(error.details?.reason, 'webdriver_request_timeout');
     assert.equal(isWebDriverRequestTimeout(error), true);
     assert.match(String(error.details?.hint), /never goes idle/);
+    // Reviewing #2509 found the advice that failed there was a longer `--timeout`,
+    // which cannot reach this read. The hint says so and offers what does work.
+    assert.match(String(error.details?.hint), /does not grow with --timeout/);
+    assert.match(String(error.details?.hint), /screenshot/);
     return true;
   });
 });
 
@@ -600,7 +600,9 @@ function webDriverOperationForGesture(plan: GesturePlan): CloudWebDriverOperatio
  * driver answers this call by walking the live UI tree, so a screen that never
  * goes idle — looping video, live ticker, continuous animation — gives the walk no
  * reason to settle. The transport's reason code is kept as-is; what the capture
- * adds is what the wait was waiting for.
+ * adds is what the wait was waiting for, and the one thing the caller cannot do,
+ * since this read's budget is the transport's own and no wider than the command's
+ * `--timeout` envelope around it.
  */
 function webDriverSourceTimeoutError(error: AppError): AppError {
   return new AppError(
@@ -610,8 +612,9 @@ function webDriverSourceTimeoutError(error: AppError): AppError {
       ...error.details,
       hint:
         'A screen that never goes idle (looping video, live ticker, continuous animation) ' +
-        'gives the driver no moment to read the UI tree. Retry with a larger --timeout, ' +
-        'or drive the screen from refs an earlier snapshot already captured.',
+        "gives the driver no moment to read the UI tree. This read has the transport's own " +
+        'budget and does not grow with --timeout; take a screenshot, or drive the screen from ' +
+        'refs an earlier snapshot already captured.',
     },
     error,
   );
 
@@ -110,4 +110,4 @@ If `connect` fails, use the reported `aws devicefarm get-*` error to check the c
 
 On hosted WebDriver sessions, `fill` checks that the field received focus before it sends keys. If it cannot confirm focus, it fails without typing. Use `snapshot -i` to confirm the target. If the driver cannot expose focus at all, use `press <target>` followed by `type <text>`. That sends text without confirming the destination.
 
-A screen that never goes still — a looping video, a live ticker, continuous animation — gives the driver no quiet moment to read the UI tree, so `snapshot` can run past its budget and fail with a reason that names the cause. The failed read is cancelled with its request instead of being dropped while it still runs, so it stops occupying the session and later commands are not queued behind a capture nobody is waiting for. A `screenshot` of the same screen keeps working because it never reads the tree. Retry with a larger `--timeout`, or drive the screen from `@refs` an earlier snapshot captured. `--depth` trims a tree after it arrives, so it cannot shorten a read that never returned.
+A screen that never goes still — a looping video, a live ticker, continuous animation — gives the driver no quiet moment to read the UI tree, so `snapshot` can run past its budget and fail with a reason that names the cause. The failed read is cancelled with its request instead of being dropped while it still runs, so it stops occupying the session and later commands are not queued behind a capture nobody is waiting for. That budget belongs to the read itself: a larger `--timeout` widens the command around it and cannot shorten the walk, so it is not the recovery. A `screenshot` of the same screen keeps working because it never reads the tree, and `@refs` an earlier snapshot captured stay valid to drive from. `--depth` trims a tree after it arrives, so it cannot shorten a read that never returned.
Original file line number	Diff line number	Diff line change
@@ -110,4 +110,4 @@ If `connect` fails, use the reported `aws devicefarm get-*` error to check the c
`110`	`110`
`111`	`111`	On hosted WebDriver sessions, `fill` checks that the field received focus before it sends keys. If it cannot confirm focus, it fails without typing. Use `snapshot -i` to confirm the target. If the driver cannot expose focus at all, use `press <target>` followed by `type <text>`. That sends text without confirming the destination.
`112`	`112`
`113`		-A screen that never goes still — a looping video, a live ticker, continuous animation — gives the driver no quiet moment to read the UI tree, so `snapshot` can run past its budget and fail with a reason that names the cause. The failed read is cancelled with its request instead of being dropped while it still runs, so it stops occupying the session and later commands are not queued behind a capture nobody is waiting for. A `screenshot` of the same screen keeps working because it never reads the tree. Retry with a larger `--timeout`, or drive the screen from `@refs` an earlier snapshot captured. `--depth` trims a tree after it arrives, so it cannot shorten a read that never returned.
	`113`	+A screen that never goes still — a looping video, a live ticker, continuous animation — gives the driver no quiet moment to read the UI tree, so `snapshot` can run past its budget and fail with a reason that names the cause. The failed read is cancelled with its request instead of being dropped while it still runs, so it stops occupying the session and later commands are not queued behind a capture nobody is waiting for. That budget belongs to the read itself: a larger `--timeout` widens the command around it and cannot shorten the walk, so it is not the recovery. A `screenshot` of the same screen keeps working because it never reads the tree, and `@refs` an earlier snapshot captured stay valid to drive from. `--depth` trims a tree after it arrives, so it cannot shorten a read that never returned.