[clangd] Narrow and document a loophole in blockUntilIdle

[clangd] Narrow and document a loophole in blockUntilIdle

blockUntilIdle of a parent can't always be correctly implemented as
  return ChildA.blockUntilIdle() && ChildB.blockUntilIdle()
The problem is that B can schedule work on A while we're waiting on it.

I believe this is theoretically possible today between CDB and background index.
Modules open more possibilities and it's hard to reason about all of them.

I don't have a perfect fix, and the abstraction is too good to lose. this patch:
 - calls out why we block on workscheduler first, and asserts correctness
 - documents the issue
 - reduces the practical possibility of spuriously returning true significantly

This function is ultimately only for testing, so we're driving down flake rate.

Differential Revision: https://reviews.llvm.org/D96856