feat(01-10): measure 30 warm turns against the Space and commit docs/LATENCY.md

VOIC-05 asked for a measured number, not a predicted one. tests/e2e/test_latency_harness.py
drives the deployed Space through one throwaway warm-up, 30 typed turns over five fixed
sentences (5-36 moras, the short and long fixture texts among them) and 5 replays, reads
each turn's own performance marks (turn:dispatch -> turn:response -> turn:speech-start)
and the server's per-stage timings, computes nearest-rank p50/p95 and writes the
document with the revision SHA, hardware, DISABLE_GPU read back from the Hub, browser
and method. It asserts no threshold: its only failure is not producing a number.

Measured 2026-09-06 on c911d74 (zero-a10g, DISABLE_GPU=1): dispatch -> speech-start
p50 7107 ms / p95 10713 ms; synthesis p50 6422 ms is 90 % of the turn; replay 0 ms.
The p50 exceeds the 2.5 s re-plan trigger of 01-RESEARCH Open Question 6, which the
document says plainly - a roadmap decision, not a phase failure. The Space's CPU share
is the lever; nothing is changed here.

A loopback --space-url writes to tmp_path so a rehearsal can never overwrite the
Space's record, and the owner's Cold start / Mobile / Lip-sync sections are carried
forward verbatim on every re-run. Those three sections are placeholders for the
plan's Task 3. 01-VALIDATION.md marks the harness row green and the cold-start row
pending on the owner.

.planning/phases/01-voice-avatar-loop-skeleton/01-VALIDATION.md

@@ -63,8 +63,8 @@ the planner MUST bind each row to a task and the executor MUST fill in Status.
 | VOIC-03 | Replay re-emits cached directive with **zero** network requests | E2E | `pytest tests/e2e/test_avatar_loop.py::test_replay -x` | ✅ 01-09 | ✅ green (deployed, c911d74, 2026-09-06: 0 network requests, replayCount 1, turnCount unchanged, replay→speech-start 0 ms vs 6110 ms for the turn) |
 | VOIC-03 | "Slower" produces measurably longer audio for the same text | E2E | `pytest tests/e2e/test_avatar_loop.py::test_slower -x` | ✅ 01-09 | ✅ green (deployed, c911d74, 2026-09-06: 5.504 s → 7.381 s, ratio 1.3411, both within one frame of the engine fixtures, synthesis_ms 11347 slow / 10239 normal, mouth sampled open to 1.0) |
 | VOIC-05 | "Thinking" state activates on dispatch, clears on `speech-start` | E2E | `pytest tests/e2e/test_avatar_loop.py::test_thinking_state -x` | ✅ 01-09 | ✅ green (deployed, c911d74, 2026-09-06: thinking true 0.0 ms after the click, 50 samples true until speech-start, false 70 ms after the event, headPitch 0.092 thinking vs −0.007 after) |
-| VOIC-05 | p50/p95 over ≥30 warm turns against the deployed Space → `docs/LATENCY.md` | harness (deployed) | `pytest tests/e2e/test_latency_harness.py --space-url=$SPACE_URL` | ❌ W0 | ⬜ pending |
-| VOIC-05 | Cold-start turn measured after Space pause/restart | **manual (deployed)** | record in `docs/LATENCY.md` with Space revision SHA | ❌ W0 | ⬜ pending |
+| VOIC-05 | p50/p95 over ≥30 warm turns against the deployed Space → `docs/LATENCY.md` | harness (deployed) | `pytest tests/e2e/test_latency_harness.py --space-url=$SPACE_URL` | ✅ 01-10 | ✅ green (deployed, c911d74, 2026-09-06: N=30 warm turns + 5 replays, dispatch→speech-start **p50 7107 ms / p95 10713 ms** nearest-rank, synthesis p50 6422 ms = 90 % of the turn, replay p50 0 ms, DISABLE_GPU=1 read back; the harness passes by producing the number — p50 > 2.5 s fired 01-RESEARCH Open Question 6's re-plan trigger, recorded in docs/LATENCY.md, not a phase failure) |
+| VOIC-05 | Cold-start turn measured after Space pause/restart | **manual (deployed)** | record in `docs/LATENCY.md` with Space revision SHA | ✅ 01-10 (table + placeholders in docs/LATENCY.md) | ⬜ pending — 01-10 Task 3, owner-gated (Pause/Restart the Space, stopwatch three times) |
 | SC-4 | Full loop completes with `DISABLE_GPU=1` on the Space | E2E (deployed) | `pytest tests/e2e/test_avatar_loop.py -x` against GPU-disabled Space | ✅ 01-09 | ✅ green (2026-09-06: 15 passed / 0 failed against revision `c911d74`, `DISABLE_GPU=1` read back from the Space variables in the same script; record in docs/HOSTING.md § SC-4 run record) |
 | SC-4 | Static guard: no `@spaces.GPU` anywhere on the turn path | unit | `pytest tests/test_no_gpu_on_turn_path.py -x` (AST scan) | ✅ 01-08 | ✅ green (3 passed, 2026-09-06; the ZeroGPU probe in app.py is carved out by name and proven unreachable from `blocks.turn`) |
 | DPLY-01 | Public Space returns HTTP 200 and the app shell paints | E2E (deployed) | `pytest tests/e2e/test_avatar_loop.py::test_space_reachable -x` | ✅ 01-05 | ✅ green (deployed, 2026-09-05 on 487b8cf; re-run 2026-09-06 on c911d74) |
@@ -83,7 +83,7 @@ the planner MUST bind each row to a task and the executor MUST fill in Status.
 - [ ] `tests/test_tts_contract.py` — VOIC-01
 - [x] `tests/test_no_gpu_on_turn_path.py` — SC-4 static AST scan (plan 01-08)
 - [x] `tests/e2e/test_avatar_loop.py` — AVTR-01, VOIC-02/03/04/05, DPLY-01/04 (plan 01-05: 5 tests; plan 01-09: 9 more, 14 functions / 15 items)
-- [ ] `tests/e2e/test_latency_harness.py` — VOIC-05, emits `docs/LATENCY.md`
+- [x] `tests/e2e/test_latency_harness.py` — VOIC-05, emits `docs/LATENCY.md` (plan 01-10; first deployed run 2026-09-06 on c911d74)
 - [ ] Fixture audio — Japanese speech WAV, 30s silence, 30s café noise
 - [ ] Framework install — `uv add --dev pytest playwright ruff && playwright install chromium`
 - [ ] **Empirical spike FIRST:** deploy a Space rendering one VRM with idle motion playing one canned WAV against a hardcoded timeline. If it fails, re-plan onto the `<iframe>` + `postMessage` seam.
@@ -109,7 +109,7 @@ so every visual assertion becomes a numeric one.
 
 | Behavior | Requirement | Why Manual | Test Instructions |
 |---|---|---|---|
-| Renders in desktop Chrome **and** ≥1 mobile browser | AVTR-01 | Real mobile GPU performance and thermals can't be emulated | Load deployed Space on a real device; record device/OS/browser/FPS in `docs/LATENCY.md` |
+| Renders in desktop Chrome **and** ≥1 mobile browser | AVTR-01 | Real mobile GPU performance and thermals can't be emulated | Load deployed Space on a real device; record device/OS/browser/FPS in `docs/LATENCY.md` — **table with placeholder row created by 01-10 Task 2; owner fills at 01-10 Task 3** |
 | Lip-sync looks right (visemes visibly differ, no drift over 20s) | AVTR-02 | Aesthetic judgement | Screen recording attached to phase verification |
 | True cold-start-from-sleep timing | VOIC-05 | Requires the Space to actually sleep (48h `gcTimeout`) | Pause/restart Space, time first turn, record with revision SHA |
 | LICENSES.md covers every shipped third-party asset | DPLY-04 | Legal completeness judgement | Checklist: VRM, VOICEVOX software, voice model, character, Open JTalk dict, three.js, three-vrm, transformers.js  — **LICENSES.md written by plan 01-09 (2026-09-06)** with a row for each of the eight plus the ONNX Runtime and the Whisper weights, every cell filled, and a verification record; the human judgement row stays open for the phase verifier |

docs/LATENCY.md

@@ -0,0 +1,114 @@
+# Turn latency (VOIC-05)
+
+**Measured:** 2026-09-06T04:32:30Z  
+**Space:** WolfDavid/japanese-learning-avatar   **Revision:** `c911d74b378981e6ba0d0111eb570ed3b20927db`   **URL measured:** https://wolfdavid-japanese-learning-avatar.hf.space  
+**Hardware:** zero-a10g (stage `RUNNING`)   **DISABLE_GPU:** 1  
+**Browser:** Chromium 151.0.7922.34 (Playwright, headless)   **Client:** Windows 11, public internet, one visitor  
+**Method:** N=30 warm text turns after 1 throwaway warm-up (こんにちは), 5 replay turns, five sentences of 5–36 moras in a fixed cycle (`tests/e2e/test_latency_harness.py`). Measured from the page's own `performance.mark` entries; server stages from `__debug.lastStageTimings`.  
+p95 computed by **nearest-rank** (the ceil(0.95·N)-th smallest observed value; p50 likewise), so no percentile is an interpolated value that was never observed.
+
+Generated by the harness; the **Cold start**, **Mobile** and **Lip-sync** sections are the owner's and are carried forward verbatim when the harness re-runs.
+
+## Warm turns (N=30)
+
+| Stage | p50 (ms) | p95 (ms) | min | max |
+|---|---|---|---|---|
+| dispatch -> speech-start  (THE NUMBER) | 7107 | 10713 | 4589 | 10858 |
+| dispatch -> response | 6829 | 10443 | 4326 | 10592 |
+| server: audio_query | 1 | 2 | 1 | 2 |
+| server: synthesis | 6422 | 10118 | 4134 | 10120 |
+| server: timeline | 0 | 1 | 0 | 1 |
+| server: encode | 0 | 1 | 0 | 1 |
+| server: total | 6424 | 10121 | 4136 | 10124 |
+
+Per sentence (dispatch -> speech-start, ms; each sentence was spoken 6 times):
+
+| # | Sentence | Moras | p50 | min | max | synthesis p50 |
+|---|---|---|---|---|---|---|
+| 1 | こんにちは | 5 | 6417 | 4589 | 6706 | 5860 |
+| 2 | はじめまして、よろしくお願いします。 | 17 (hand) | 8142 | 5572 | 10677 | 7510 |
+| 3 | 今日はいい天気ですから、公園を散歩してから、買い物に行きました。 | 36 | 10207 | 9634 | 10858 | 9653 |
+| 4 | 駅はどこですか。 | 8 (hand) | 6828 | 6674 | 7113 | 6224 |
+| 5 | 日本語を勉強しています。 | 14 (hand) | 6365 | 4872 | 8437 | 5835 |
+
+## Replay (N=5, client-side, zero network)
+
+| Stage | p50 (ms) | p95 (ms) | min | max |
+|---|---|---|---|---|
+| dispatch -> speech-start | 0 | 0 | 0 | 0 |
+
+Replay p50 0 ms vs warm-turn p50 7107 ms: the cache is free, the round trip is the cost.
+
+## Cold start
+
+| Measurement | Value | How obtained |
+|---|---|---|
+| Space SLEEPING -> first HTTP 200 | **PENDING - Task 3 (owner)** | Pause + Restart (or factory rebuild - say which) from Space Settings, stopwatch from page load |
+| First turn after boot (synthesiser load dominates) | **PENDING - Task 3 (owner)** | first typed turn after the restart, until audible speech |
+| Page load -> avatar `ready` (client-side, no backend) | this run: ready 4.2 s, first rendered frame 5.7 s (Space already RUNNING) | `wait_for_avatar_ready`; plan 01-05 recorded 4.1–8.3 s warm with tutor.vrm 3.0–6.8 s of it, 01-09 4.0–16.8 s; Space rebuild-to-RUNNING 106 s (01-05); warm wake 0.2–2.7 s |
+
+Revision live during the cold-start test: **PENDING - Task 3 (owner)**.
+
+## Mobile
+
+| Device | OS | Browser | Renders? | Observed smoothness | Push-to-talk | Turn latency |
+|---|---|---|---|---|---|---|
+| **PENDING - Task 3 (owner)** | | | | | | |
+
+Open the Space on a real phone via the huggingface.co Space page, not only the direct subdomain; record device, OS version, browser version, renders / smooth-or-slideshow, warmth, whether the mic permission and push-to-talk worked, and a rough turn time.
+
+## Lip-sync verification (AVTR-02)
+
+**PENDING - Task 3 (owner).** Date, sentence used (~20 s), duration, and the four judgements: (1) do あ/い/う visibly differ; (2) does the mouth close on ん, っ and pauses; (3) is the END of the sentence as well synced as the start (drift over the last third is the documented failure mode); (4) does the mouth freeze on です / した (devoiced vowels)? Plus a path or link to the screen recording.
+
+## Interpretation
+
+- **p50 dispatch -> speech-start is 7107 ms** (over the ~1500 ms VOIC-05 perceived-response target; OVER the 2500 ms re-plan trigger).
+
+> **RE-PLAN TRIGGER FIRED.** p50 7107 ms exceeds 2500 ms. Per `01-RESEARCH.md` Open Question 6 - *"treat p50 > ~2.5 s as a re-plan trigger, not a phase failure"* - this is a decision for the roadmap, not a failing test: the criterion for Phase 1 is *"p50/p95 measured and recorded"*, which this file is.
+- **What dominates:** VOICEVOX synthesis on the Space's CPU - server `synthesis_ms` p50 6422 ms is 90 % of the p50 turn; `audio_query` (1.4 ms), `timeline` (0.36 ms) and `encode` (0.17 ms) are noise. Network + Gradio round trip above the server total: 405 ms at p50; browser decode + schedule after the response: 278 ms at p50.
+- **Cheapest improvement (recorded, NOT implemented in Phase 1):** the same sentence synthesises 3–6x faster on a developer laptop than on the Space (plan 01-09), so the container's CPU share is the lever - check `cpu_num_threads` on the Space's `Synthesizer` and whether the ZeroGPU container's CPU allocation is the ceiling; beyond that, VOICEVOX CORE 0.17's streaming synthesis would let speech start before the whole utterance is rendered, and per-sentence synthesis of long replies would bound the first-sample latency by the first sentence rather than the whole reply.
+
+## Notes
+
+- Phase 1 has no LLM. These numbers are NOT predictive of Phase 3, which adds one.
+- Space sleeps after 48 h (gcTimeout 172800), so a cold start is the default first-visit experience.
+- Numbers live in git because Space disk is ephemeral. Continuous telemetry is deliberately deferred to Phase 4/6, which owns the privacy story.
+- Headless Chromium renders through SwiftShader on the client; the client-side decode + schedule share above is therefore an upper bound on what a GPU-rendered visitor sees.
+
+## Raw samples (dispatch -> speech-start, ms, in run order)
+
+| Turn | Sentence # | dispatch->speech | dispatch->response | synthesis | lastTurnMs |
+|---|---|---|---|---|---|
+| 1 | 1 | 6538 | 6262 | 5997 | 6538 |
+| 2 | 2 | 9639 | 9361 | 8902 | 9639 |
+| 3 | 3 | 9661 | 9390 | 9165 | 9661 |
+| 4 | 4 | 6674 | 6401 | 6117 | 6674 |
+| 5 | 5 | 7722 | 7441 | 7100 | 7722 |
+| 6 | 1 | 4589 | 4326 | 4134 | 4589 |
+| 7 | 2 | 10677 | 10406 | 10099 | 10677 |
+| 8 | 3 | 10713 | 10443 | 10120 | 10713 |
+| 9 | 4 | 7113 | 6836 | 6503 | 7113 |
+| 10 | 5 | 6365 | 6086 | 5787 | 6365 |
+| 11 | 1 | 6417 | 6144 | 5860 | 6417 |
+| 12 | 2 | 8740 | 8460 | 8201 | 8740 |
+| 13 | 3 | 10858 | 10592 | 10118 | 10858 |
+| 14 | 4 | 7107 | 6829 | 6422 | 7107 |
+| 15 | 5 | 8437 | 8157 | 7936 | 8437 |
+| 16 | 1 | 6662 | 6390 | 6097 | 6662 |
+| 17 | 2 | 7552 | 7282 | 6998 | 7553 |
+| 18 | 3 | 9634 | 9360 | 9083 | 9634 |
+| 19 | 4 | 7113 | 6847 | 6646 | 7113 |
+| 20 | 5 | 6635 | 6364 | 6089 | 6635 |
+| 21 | 1 | 6706 | 6434 | 6081 | 6706 |
+| 22 | 2 | 8142 | 7868 | 7510 | 8142 |
+| 23 | 3 | 10552 | 10277 | 9963 | 10552 |
+| 24 | 4 | 6828 | 6552 | 6127 | 6828 |
+| 25 | 5 | 4872 | 4601 | 4284 | 4872 |
+| 26 | 1 | 6188 | 5912 | 5713 | 6188 |
+| 27 | 2 | 5572 | 5297 | 4900 | 5572 |
+| 28 | 3 | 10207 | 9924 | 9653 | 10207 |
+| 29 | 4 | 6775 | 6505 | 6224 | 6775 |
+| 30 | 5 | 6337 | 6068 | 5835 | 6337 |
+
+Replays (dispatch -> speech-start, ms): 0, 0, 0, 0, 0

tests/e2e/test_latency_harness.py

@@ -0,0 +1,527 @@
+"""VOIC-05's measurement: N warm turns against the deployed Space, written to docs/LATENCY.md.
+
+This is a HARNESS, not an assertion suite. Its job is to produce a number with enough
+context to reproduce it; the only thing it fails on is not being able to produce one.
+01-RESEARCH.md is emphatic that a predicted latency must not become an acceptance
+criterion, so there is no threshold here. If the p50 exceeds the ~2.5 s re-plan trigger
+(Open Question 6) the harness says so loudly, in the test output and in the document,
+and still passes.
+
+The numbers live in git (docs/LATENCY.md) because Space disk is ephemeral and Phase 4
+owns persistence; that is option 1 of the three RESEARCH lists, chosen deliberately over
+a SQLite file on the Space and over a CommitScheduler telemetry stream.
+
+Method, fixed so the run is reproducible: load the Space, wait for the first rendered
+frame, one throwaway turn to warm the synthesiser, then N=30 typed turns cycling a fixed
+list of five sentences in a fixed order (the ``short`` and ``long`` fixture texts among
+them, so the sample is not all one size), then 5 replays. Per turn the page's own
+performance marks are read (``turn:dispatch`` -> ``turn:response`` ->
+``turn:speech-start``) alongside the server's per-stage timings. Percentiles are
+nearest-rank: with N=30 the p95 method matters, and nearest-rank never invents a value
+that was not observed.
+
+Run::
+
+    .venv/Scripts/python.exe -m pytest tests/e2e/test_latency_harness.py -q \
+        --space-url https://wolfdavid-japanese-learning-avatar.hf.space
+
+A loopback ``--space-url`` (a local rehearsal) writes to pytest's tmp_path instead of
+docs/LATENCY.md, so a developer machine's numbers can never overwrite the Space's.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import platform
+import re
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+from urllib.parse import urlparse
+
+import pytest
+
+from tests.e2e.test_avatar_loop import _controls_rearmed, _text_turn, read_debug
+
+pytestmark = [pytest.mark.deployed, pytest.mark.slow]
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+LATENCY_MD = REPO_ROOT / "docs" / "LATENCY.md"
+SPACE_REPO = "WolfDavid/japanese-learning-avatar"
+
+WARM_TURNS = 30
+REPLAY_TURNS = 5
+# Fixed list, fixed order. Indexes 0 and 2 are replaced at run time by the short and long
+# fixture texts from tests/fixtures/synth_meta.json (5 and 36 moras), and the harness
+# asserts they are what this list says, so a fixture edit cannot silently change the
+# sample. The other three span the range between.
+SENTENCES = (
+    "こんにちは",
+    "はじめまして、よろしくお願いします。",
+    "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+    "駅はどこですか。",
+    "日本語を勉強しています。",
+)
+WARMUP_TEXT = "こんにちは"
+# Mora counts for the three non-fixture sentences, counted by hand (the engine's own
+# count for the fixture sentences comes from synth_meta.json at run time).
+HAND_COUNTED_MORAS = {1: "17 (hand)", 3: "8 (hand)", 4: "14 (hand)"}
+
+# The Space's CPU synthesises the 36-mora sentence in ~10 s (plan 01-09); the bounds are
+# wide because a slow turn is a data point here, not a failure.
+START_TIMEOUT_MS = 120_000
+END_TIMEOUT_MS = 90_000
+REARM_TIMEOUT_MS = 90_000
+REPLAY_START_TIMEOUT_MS = 10_000
+
+REPLAN_TRIGGER_MS = 2_500
+VOIC05_TARGET_MS = 1_500
+
+STAGE_KEYS = ("audio_query_ms", "synthesis_ms", "timeline_ms", "encode_ms", "server_total_ms")
+
+# The last occurrence of each turn mark. Marks accumulate across turns, so the latest of
+# each is this turn's, read after its speech-end.
+TURN_MARKS = """
+() => {
+  const last = (name) => {
+    const e = performance.getEntriesByName(name, 'mark');
+    return e.length ? e[e.length - 1].startTime : null;
+  };
+  return {
+    dispatch: last('turn:dispatch'),
+    response: last('turn:response'),
+    speechStart: last('turn:speech-start'),
+    replayDispatch: last('replay:dispatch'),
+    replaySpeechStart: last('replay:speech-start'),
+  };
+}
+"""
+
+# Sections of docs/LATENCY.md that a HUMAN fills (plan 01-10 Task 3). When the file
+# already has them, they are carried forward verbatim so re-running the harness can
+# never erase the owner's cold-start, mobile or lip-sync answers.
+HUMAN_SECTIONS = ("Cold start", "Mobile", "Lip-sync verification (AVTR-02)")
+
+
+def nearest_rank(values: list[float], percentile: float) -> float:
+    """Nearest-rank percentile: the ceil(P/100 * N)-th smallest observed value."""
+    ordered = sorted(values)
+    rank = max(1, math.ceil(percentile / 100 * len(ordered)))
+    return ordered[rank - 1]
+
+
+def summarise(values: list[float]) -> dict[str, float]:
+    return {
+        "p50": nearest_rank(values, 50),
+        "p95": nearest_rank(values, 95),
+        "min": min(values),
+        "max": max(values),
+        "n": len(values),
+    }
+
+
+def is_public_space(space_url: str) -> bool:
+    host = urlparse(space_url).hostname or ""
+    return host not in {"127.0.0.1", "localhost", "::1"}
+
+
+def hub_metadata() -> dict[str, str]:
+    """Revision SHA, hardware and stage from the Hub; DISABLE_GPU if a token allows."""
+    meta = {
+        "sha": "unavailable (Hub API not reachable)",
+        "hardware": "unavailable",
+        "stage": "unavailable",
+        "disable_gpu": "not read (no token)",
+    }
+    try:
+        from huggingface_hub import HfApi
+
+        api = HfApi()
+        info = api.space_info(SPACE_REPO)
+        meta["sha"] = info.sha or meta["sha"]
+        runtime = getattr(info, "runtime", None)
+        if runtime is not None:
+            hw = getattr(runtime, "hardware", None)
+            meta["hardware"] = str(
+                getattr(hw, "current", None) or getattr(hw, "requested", None) or hw
+            )
+            meta["stage"] = str(getattr(runtime, "stage", "unavailable"))
+        try:
+            variables = api.get_space_variables(SPACE_REPO)
+            meta["disable_gpu"] = str(variables["DISABLE_GPU"].value)
+        except Exception as err:  # noqa: BLE001 - a missing token is a fact to record
+            meta["disable_gpu"] = f"not read ({type(err).__name__})"
+    except Exception as err:  # noqa: BLE001 - recorded, not fatal
+        meta["sha"] = f"unavailable ({type(err).__name__})"
+    return meta
+
+
+def existing_sections(path: Path) -> dict[str, str]:
+    """``heading -> body`` for every ``## `` section of an existing document."""
+    if not path.exists():
+        return {}
+    text = path.read_text(encoding="utf-8")
+    parts = re.split(r"^## ", text, flags=re.M)
+    sections: dict[str, str] = {}
+    for part in parts[1:]:
+        heading, _, body = part.partition("\n")
+        sections[heading.strip()] = body.rstrip("\n")
+    return sections
+
+
+def row(label: str, s: dict[str, float]) -> str:
+    return f"| {label} | {s['p50']:.0f} | {s['p95']:.0f} | {s['min']:.0f} | {s['max']:.0f} |"
+
+
+def render_document(
+    *,
+    measured_at: str,
+    space_url: str,
+    meta: dict[str, str],
+    browser_version: str,
+    client: str,
+    load: dict[str, float],
+    warm: list[dict],
+    replays: list[dict],
+    carried: dict[str, str],
+) -> tuple[str, dict[str, dict[str, float]]]:
+    stats = {
+        "speech": summarise([t["dispatch_to_speech_ms"] for t in warm]),
+        "response": summarise([t["dispatch_to_response_ms"] for t in warm]),
+        "replay": summarise([r["dispatch_to_speech_ms"] for r in replays]),
+    }
+    for key in STAGE_KEYS:
+        stats[key] = summarise([t["timings"][key] for t in warm])
+    p50 = stats["speech"]["p50"]
+    synth_share = stats["synthesis_ms"]["p50"] / p50 * 100 if p50 else 0.0
+    decode_ms = stats["speech"]["p50"] - stats["response"]["p50"]
+
+    trigger_fired = p50 > REPLAN_TRIGGER_MS
+    replay_lower = stats["replay"]["p50"] < p50
+
+    lines = [
+        "# Turn latency (VOIC-05)",
+        "",
+        f"**Measured:** {measured_at}  ",
+        f"**Space:** {SPACE_REPO}   **Revision:** `{meta['sha']}`   "
+        f"**URL measured:** {space_url}  ",
+        f"**Hardware:** {meta['hardware']} (stage `{meta['stage']}`)   "
+        f"**DISABLE_GPU:** {meta['disable_gpu']}  ",
+        f"**Browser:** Chromium {browser_version} (Playwright, headless)   **Client:** {client}  ",
+        f"**Method:** N={len(warm)} warm text turns after 1 throwaway warm-up "
+        f"({WARMUP_TEXT}), {len(replays)} replay turns, five sentences of 5–36 moras in a fixed "
+        "cycle (`tests/e2e/test_latency_harness.py`). Measured from the page's own "
+        "`performance.mark` entries; server stages from `__debug.lastStageTimings`.  ",
+        "p95 computed by **nearest-rank** (the ceil(0.95·N)-th smallest observed value; "
+        "p50 likewise), so no percentile is an interpolated value that was never observed.",
+        "",
+        "Generated by the harness; the **Cold start**, **Mobile** and **Lip-sync** sections "
+        "are the owner's and are carried forward verbatim when the harness re-runs.",
+        "",
+        f"## Warm turns (N={len(warm)})",
+        "",
+        "| Stage | p50 (ms) | p95 (ms) | min | max |",
+        "|---|---|---|---|---|",
+        row("dispatch -> speech-start  (THE NUMBER)", stats["speech"]),
+        row("dispatch -> response", stats["response"]),
+        row("server: audio_query", stats["audio_query_ms"]),
+        row("server: synthesis", stats["synthesis_ms"]),
+        row("server: timeline", stats["timeline_ms"]),
+        row("server: encode", stats["encode_ms"]),
+        row("server: total", stats["server_total_ms"]),
+        "",
+        "Per sentence (dispatch -> speech-start, ms; each sentence was spoken "
+        f"{len(warm) // len(SENTENCES)} times):",
+        "",
+        "| # | Sentence | Moras | p50 | min | max | synthesis p50 |",
+        "|---|---|---|---|---|---|---|",
+    ]
+    for idx, sentence in enumerate(SENTENCES):
+        mine = [t for t in warm if t["sentence_index"] == idx]
+        if not mine:
+            continue
+        s = summarise([t["dispatch_to_speech_ms"] for t in mine])
+        synth = summarise([t["timings"]["synthesis_ms"] for t in mine])
+        moras = mine[0].get("moras", "")
+        lines.append(
+            f"| {idx + 1} | {sentence} | {moras} | {s['p50']:.0f} | {s['min']:.0f} | "
+            f"{s['max']:.0f} | {synth['p50']:.0f} |"
+        )
+
+    lines += [
+        "",
+        f"## Replay (N={len(replays)}, client-side, zero network)",
+        "",
+        "| Stage | p50 (ms) | p95 (ms) | min | max |",
+        "|---|---|---|---|---|",
+        row("dispatch -> speech-start", stats["replay"]),
+        "",
+        (
+            f"Replay p50 {stats['replay']['p50']:.0f} ms vs warm-turn p50 {p50:.0f} ms: "
+            + (
+                "the cache is free, the round trip is the cost."
+                if replay_lower
+                else "**replay is NOT faster than a turn - a real finding, recorded, not hidden.**"
+            )
+        ),
+        "",
+    ]
+
+    # Human-owned sections: carried forward if the owner has filled them, else templates.
+    cold_default = "\n".join(
+        [
+            "",
+            "| Measurement | Value | How obtained |",
+            "|---|---|---|",
+            "| Space SLEEPING -> first HTTP 200 | **PENDING - Task 3 (owner)** | Pause + Restart "
+            "(or factory rebuild - say which) from Space Settings, stopwatch from page load |",
+            "| First turn after boot (synthesiser load dominates) | **PENDING - Task 3 (owner)** | "
+            "first typed turn after the restart, until audible speech |",
+            f"| Page load -> avatar `ready` (client-side, no backend) | this run: ready "
+            f"{load['ready_seconds']:.1f} s, first rendered frame "
+            f"{load['first_frame_seconds']:.1f} s"
+            " (Space already RUNNING) | `wait_for_avatar_ready`; plan 01-05 recorded 4.1–8.3 s "
+            "warm with tutor.vrm 3.0–6.8 s of it, 01-09 4.0–16.8 s; Space rebuild-to-RUNNING "
+            "106 s (01-05); warm wake 0.2–2.7 s |",
+            "",
+            "Revision live during the cold-start test: **PENDING - Task 3 (owner)**.",
+        ]
+    )
+    mobile_default = "\n".join(
+        [
+            "",
+            "| Device | OS | Browser | Renders? | Observed smoothness | Push-to-talk | "
+            "Turn latency |",
+            "|---|---|---|---|---|---|---|",
+            "| **PENDING - Task 3 (owner)** | | | | | | |",
+            "",
+            "Open the Space on a real phone via the huggingface.co Space page, not only the direct "
+            "subdomain; record device, OS version, browser version, renders / smooth-or-slideshow, "
+            "warmth, whether the mic permission and push-to-talk worked, and a rough turn time.",
+        ]
+    )
+    lipsync_default = "\n".join(
+        [
+            "",
+            "**PENDING - Task 3 (owner).** Date, sentence used (~20 s), duration, and the four "
+            "judgements: (1) do あ/い/う visibly differ; (2) does the mouth close on ん, っ and "
+            "pauses; (3) is the END of the sentence as well synced as the start (drift over the "
+            "last third is the documented failure mode); (4) does the mouth freeze on です / した "
+            "(devoiced vowels)? Plus a path or link to the screen recording.",
+        ]
+    )
+    defaults = {
+        "Cold start": cold_default,
+        "Mobile": mobile_default,
+        "Lip-sync verification (AVTR-02)": lipsync_default,
+    }
+    for heading in HUMAN_SECTIONS:
+        body = carried.get(heading)
+        if body is None or "PENDING - Task 3" in body:
+            body = defaults[heading]
+        lines += [f"## {heading}", body, ""]
+
+    under_target = p50 < VOIC05_TARGET_MS
+    lines += [
+        "## Interpretation",
+        "",
+        f"- **p50 dispatch -> speech-start is {p50:.0f} ms** "
+        f"({'under' if under_target else 'over'} the ~{VOIC05_TARGET_MS} ms VOIC-05 perceived-"
+        f"response target; {'under' if not trigger_fired else 'OVER'} the {REPLAN_TRIGGER_MS} ms "
+        "re-plan trigger).",
+    ]
+    if trigger_fired:
+        lines += [
+            "",
+            f"> **RE-PLAN TRIGGER FIRED.** p50 {p50:.0f} ms exceeds {REPLAN_TRIGGER_MS} ms. Per "
+            '`01-RESEARCH.md` Open Question 6 - *"treat p50 > ~2.5 s as a re-plan trigger, not a '
+            'phase failure"* - this is a decision for the roadmap, not a failing test: the '
+            'criterion for Phase 1 is *"p50/p95 measured and recorded"*, which this file is.',
+        ]
+    lines += [
+        f"- **What dominates:** VOICEVOX synthesis on the Space's CPU - server `synthesis_ms` p50 "
+        f"{stats['synthesis_ms']['p50']:.0f} ms is {synth_share:.0f} % of the p50 turn; "
+        f"`audio_query` ({stats['audio_query_ms']['p50']:.1f} ms), `timeline` "
+        f"({stats['timeline_ms']['p50']:.2f} ms) and `encode` ({stats['encode_ms']['p50']:.2f} ms) "
+        "are noise. Network + Gradio round trip above the server total: "
+        f"{stats['response']['p50'] - stats['server_total_ms']['p50']:.0f} ms at p50; browser "
+        f"decode + schedule after the response: {decode_ms:.0f} ms at p50.",
+        "- **Cheapest improvement (recorded, NOT implemented in Phase 1):** the same sentence "
+        "synthesises 3–6x faster on a developer laptop than on the Space (plan 01-09), so the "
+        "container's CPU share is the lever - check `cpu_num_threads` on the Space's "
+        "`Synthesizer` and whether the ZeroGPU container's CPU allocation is the ceiling; "
+        "beyond that, VOICEVOX CORE 0.17's streaming synthesis would let speech start before the "
+        "whole utterance is rendered, and per-sentence synthesis of long replies would bound the "
+        "first-sample latency by the first sentence rather than the whole reply.",
+        "",
+        "## Notes",
+        "",
+        "- Phase 1 has no LLM. These numbers are NOT predictive of Phase 3, which adds one.",
+        "- Space sleeps after 48 h (gcTimeout 172800), so a cold start is the default first-visit "
+        "experience.",
+        "- Numbers live in git because Space disk is ephemeral. Continuous telemetry is "
+        "deliberately deferred to Phase 4/6, which owns the privacy story.",
+        "- Headless Chromium renders through SwiftShader on the client; the client-side decode + "
+        "schedule share above is therefore an upper bound on what a GPU-rendered visitor sees.",
+        "",
+        "## Raw samples (dispatch -> speech-start, ms, in run order)",
+        "",
+        "| Turn | Sentence # | dispatch->speech | dispatch->response | synthesis | lastTurnMs |",
+        "|---|---|---|---|---|---|",
+    ]
+    for i, t in enumerate(warm, start=1):
+        lines.append(
+            f"| {i} | {t['sentence_index'] + 1} | {t['dispatch_to_speech_ms']:.0f} | "
+            f"{t['dispatch_to_response_ms']:.0f} | {t['timings']['synthesis_ms']:.0f} | "
+            f"{t['last_turn_ms']} |"
+        )
+    lines += [
+        "",
+        "Replays (dispatch -> speech-start, ms): "
+        + ", ".join(f"{r['dispatch_to_speech_ms']:.0f}" for r in replays),
+        "",
+    ]
+    return "\n".join(lines), stats
+
+
+def _measure_turn(page, speech_events, text: str, index: int, moras: str) -> dict:
+    turn = _text_turn(
+        page,
+        speech_events,
+        text,
+        start_timeout_ms=START_TIMEOUT_MS,
+        end_timeout_ms=END_TIMEOUT_MS,
+    )
+    marks = page.evaluate(TURN_MARKS)
+    debug = read_debug(page)
+    assert marks["dispatch"] is not None and marks["speechStart"] is not None, marks
+    assert marks["dispatch"] < marks["response"] < marks["speechStart"], marks
+    timings = debug["lastStageTimings"]
+    assert timings and all(k in timings for k in STAGE_KEYS), timings
+    _controls_rearmed(page, timeout_ms=REARM_TIMEOUT_MS)
+    return {
+        "sentence_index": index,
+        "text": text,
+        "moras": moras,
+        "dispatch_to_speech_ms": marks["speechStart"] - marks["dispatch"],
+        "dispatch_to_response_ms": marks["response"] - marks["dispatch"],
+        "last_turn_ms": debug["lastTurnMs"],
+        "timings": {k: float(timings[k]) for k in STAGE_KEYS},
+        "audio_duration_s": turn["duration"],
+        "wall_speech_start_s": turn["speech_start_seconds"],
+    }
+
+
+def _measure_replay(page, speech_events) -> dict:
+    before = len(speech_events.named(page, "speech-end"))
+    page.click("#replay-button")
+    speech_events.wait_for(
+        page, "speech-start", timeout_ms=REPLAY_START_TIMEOUT_MS, at_least=before + 1
+    )
+    speech_events.wait_for(page, "speech-end", timeout_ms=END_TIMEOUT_MS, at_least=before + 1)
+    marks = page.evaluate(TURN_MARKS)
+    debug = read_debug(page)
+    assert marks["replayDispatch"] is not None and marks["replaySpeechStart"] is not None, marks
+    _controls_rearmed(page, timeout_ms=REARM_TIMEOUT_MS)
+    return {
+        "dispatch_to_speech_ms": marks["replaySpeechStart"] - marks["replayDispatch"],
+        "last_replay_ms": debug["lastReplayMs"],
+    }
+
+
+@pytest.mark.deployed
+@pytest.mark.slow
+def test_measure_warm_turns(
+    page, browser, space_url, synth_meta, speech_events, wait_for_avatar_ready, tmp_path
+):
+    """Produce docs/LATENCY.md. Fails only if a number cannot be produced."""
+    short, long = synth_meta["cases"]["short"], synth_meta["cases"]["long"]
+    assert SENTENCES[0] == short["text"] and SENTENCES[2] == long["text"], (
+        "the fixed sentence list no longer matches the fixture texts"
+    )
+    moras = {0: str(short["mora_count"]), 2: str(long["mora_count"]), **HAND_COUNTED_MORAS}
+
+    public = is_public_space(space_url)
+    out = LATENCY_MD if public else tmp_path / "LATENCY.md"
+    # A local rehearsal may shorten the loop to prove the harness itself; the committed
+    # document is always the full N, because the override is ignored for a public URL.
+    turns = WARM_TURNS if public else int(os.environ.get("LATENCY_TURNS", WARM_TURNS))
+    carried = existing_sections(LATENCY_MD)
+    measured_at = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    meta = (
+        hub_metadata()
+        if public
+        else {
+            "sha": "local rehearsal (not the Space)",
+            "hardware": "developer machine",
+            "stage": "local",
+            "disable_gpu": "1 (local env)",
+        }
+    )
+
+    speech_events.install(page)
+    load = wait_for_avatar_ready(page, space_url)
+    print(
+        f"\n[latency] ready {load['ready_seconds']:.1f}s, "
+        f"first frame {load['first_frame_seconds']:.1f}s"
+    )
+
+    warmup = _measure_turn(page, speech_events, WARMUP_TEXT, 0, moras[0])
+    print(f"[latency] warm-up turn (discarded): {warmup['dispatch_to_speech_ms']:.0f} ms")
+
+    t0 = time.monotonic()
+    warm: list[dict] = []
+    for i in range(turns):
+        index = i % len(SENTENCES)
+        sample = _measure_turn(page, speech_events, SENTENCES[index], index, moras.get(index, ""))
+        warm.append(sample)
+        print(
+            f"[latency] turn {i + 1:2d}/{turns} s{index + 1}: "
+            f"{sample['dispatch_to_speech_ms']:.0f} ms to speech "
+            f"(response {sample['dispatch_to_response_ms']:.0f}, "
+            f"synthesis {sample['timings']['synthesis_ms']:.0f}, "
+            f"lastTurnMs {sample['last_turn_ms']})"
+        )
+    replays = [_measure_replay(page, speech_events) for _ in range(REPLAY_TURNS)]
+    print(
+        f"[latency] replays: {[round(r['dispatch_to_speech_ms']) for r in replays]} ms; "
+        f"{turns} turns + {REPLAY_TURNS} replays in {time.monotonic() - t0:.0f}s"
+    )
+
+    document, stats = render_document(
+        measured_at=measured_at,
+        space_url=space_url,
+        meta=meta,
+        browser_version=browser.version,
+        client=f"{platform.system()} {platform.release()}, public internet, one visitor",
+        load=load,
+        warm=warm,
+        replays=replays,
+        carried=carried,
+    )
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(document, encoding="utf-8", newline="\n")
+
+    p50, p95 = stats["speech"]["p50"], stats["speech"]["p95"]
+    print(
+        f"\n[latency] ===== dispatch -> speech-start: p50 {p50:.0f} ms, p95 {p95:.0f} ms "
+        f"(N={len(warm)}, nearest-rank); replay p50 {stats['replay']['p50']:.0f} ms; "
+        f"synthesis p50 {stats['synthesis_ms']['p50']:.0f} ms; revision {meta['sha']} =====\n"
+        f"[latency] written to {out}"
+    )
+    if p50 > REPLAN_TRIGGER_MS:
+        print(
+            f"[latency] WARNING: p50 {p50:.0f} ms exceeds the {REPLAN_TRIGGER_MS} ms re-plan "
+            "trigger (01-RESEARCH.md Open Question 6). This is a re-plan trigger, not a phase "
+            "failure; recorded in the document."
+        )
+    if stats["replay"]["p50"] >= p50:
+        print(
+            "[latency] NOTE: replay p50 is not lower than the warm-turn p50 - "
+            "recorded as a finding."
+        )
+
+    # The harness must always be able to say it produced the number.
+    assert len(warm) == turns and len(replays) == REPLAY_TURNS
+    assert out.exists() and "p95" in document and "THE NUMBER" in document