docs: record the gate timeout measurement and how to take it

docs/tools.md

@@ -503,6 +503,12 @@ roughly 20 s, so the host gave up before the gate returned its ticket — the ca
 human's decision was recorded, but the agent received neither. Re-measure before targeting a host with
 a different tolerance, and keep the value comfortably under whatever you measure.
 
+Measured from a real agent, this gate returns `pending` at 9,997 ms against 1,642 ms for a tool that
+resolves immediately — about two seconds of host overhead, leaving roughly ten before the ceiling. Use
+a **single** timeout guard when you measure: an agent that races 5 s and then 10 s more reports 15.6 s
+for the same call, because the value surfaces at its next guard boundary rather than when the promise
+settles, and that artefact looks exactly like latency the page is responsible for.
+
 ### 12. `ask_human_visual({ question, choices, hintAtMs?, ticket? })`
 
 ```

traces/src/lib/webmcp/blocking.ts

@@ -30,6 +30,15 @@ import type { Gate, GateResult } from '@/types/domain'
  * 8 s sits far enough under that ceiling to survive a slower host, and costs nothing: a human who is
  * already looking at the screen answers inside it, and one who isn't was always going to arrive by
  * ticket. Raising this back up trades a guaranteed reply for a slightly shorter happy path.
+ *
+ * Confirmed end to end from a real agent: this gate hands back `pending` at 9,997 ms measured from the
+ * agent's side, against 1,642 ms for a tool that resolves immediately — so the host costs about two
+ * seconds and the ceiling leaves roughly ten to spare.
+ *
+ * Measure with a *single* guard. An agent that races 5 s and then 10 s more reports 15.6 s for this
+ * same call, because the value surfaces at its next guard boundary rather than when the promise
+ * settles. That artefact is indistinguishable from latency the page is responsible for, and it will
+ * talk you into shortening a gate that was already fast enough.
  */
 export const GATE_TIMEOUT_MS = 8_000