phase: 03_audio_share

**Phase 03 final verification pass — complete, 100% green.**

- Verified all 4 tasks done in `complete/03_audio_share/`; confirmed implementation in `watch.js` (one composed `MediaStream` per tile, staged-only `setMuted()` policy, `data-audio` state), `share.js` (precise `NotAllowedError` rethrow, 3 honest `#stat-audio` states, mid-share audio republish), conftest flags, and the new `tests/e2e/test_audio_share.py` (11 tests, all **passed** — none skipped).
- **Criteria:** (1) viewer inbound audio `bytesReceived` strictly increases + composed stream 1 video/1 audio track while frames still decode — **passed**; (2) staged-only audio via keyboard `m`, mouse button, and `unstage()` re-mute — **passed**; (3) `shared`/`silent`/`not offered` + mid-share audio loss updates panel, roster and tiles — **passed**; (4) cancelled picker reports cancellation, single attempt — **passed**; (5) SECURITY.md §4 Audio, README platform notes, kiosk doc all describe shipped behaviour incl. Linux/PipeWire reality — **verified**; (6) full gate — **passed** (below).
- **Gates:** `uv run ruff check . && uv run ruff format --check .` → clean; `uv run pyright` → 0 errors; `uv run pytest` → 245 passed, 4 skipped (only the `MIRROR_REALDISPLAY`-gated X11 tests); `MIRROR_REALDISPLAY=1 uv run pytest -m realdisplay` → 3 passed, 1 skipped (real-capture audio: documented skip naming the exact host/flag reason, per task 04).
- **Docs:** README.md reviewed in full against code (env table, CLI flags, routes, kiosk key table, quickstart, audio notes) — consistent, no changes needed. AGENTS.md — all commands/paths/coverage claims verified accurate, no stale statements, no changes needed.
- **Defect fixed (pre-existing):** `docs/kiosk-silverblue.md` + `install-kiosk.sh`, `kiosk.conf`, `gnome-kiosk-script` used `mirror.reeselink.com` while README/SECURITY.md use `mirror.reeseapps.com` (the deployment domain, consistent with the fleet); corrected 7 occurrences in 4 files.
- No live-infrastructure changes; realdisplay suite ran on private Xvfb only.
- **Next pending phase:** `04_reachable_share_cta`.

README.md

@@ -93,6 +93,16 @@ each share**, which mirror neither controls nor tries to bypass. Chrome's picker
 offers whole screens and individual windows; on Wayland what the portal will
 agree to depends on the compositor.
 
+**Audio.** A share carries audio when the browser's picker offers it (Chrome's
+"share audio" tickbox, or a tab's own audio); the sharer's panel says
+`shared` / `silent` / `not offered`, and the wall shows an audio button only
+when one exists. On the wall, only the staged mirror can be audible — **press
+`m` on the wall to hear the staged mirror** (unmuting it mutes the others,
+leaving the stage re-mutes it). What *system* audio a browser can capture is
+a browser/platform fact, not a mirror one: Chrome on Linux gets it where
+PipeWire offers it, Firefox's desktop capture does not offer it at all. See
+[SECURITY.md](SECURITY.md) §4 "Audio".
+
 ## Deployment
 
 The internal deployment is `https://mirror.reeseapps.com`, described and automated
@@ -144,10 +154,15 @@ in. On `/watch`:
 | `g` | Back to the wall. |
 | `n` / `p` | Stage the next / previous mirror. |
 | `1`–`9` | Stage the Nth mirror. |
-| `m` | Mute / unmute the staged mirror. |
+| `m` | Mute / unmute the staged mirror — on the selected mirror it stages it first. |
 | `?` | Show / hide this list on screen. |
 | `Esc` | Close the key list, then leave the stage. |
 
+A mirror's audio is only heard while it is on the stage: every mirror starts
+muted, unmuting one (the tile's audio button or `m`) mutes the others, and
+leaving the stage re-mutes it. Sound never starts without a click or a
+keypress.
+
 On `/mirror`: `s` starts a share, `x` stops one, `Esc` stops while live. Keys
 with `Ctrl`/`Cmd`/`Alt` are never intercepted, and a key typed in the display-
 name field is text, not a command. `?` is the only key that needs Shift, and it