peerspeak/docs/screenshare-audio-exclusion-plan.md

# Design v3: whole-desktop screen-share audio without self-echo

**Status:** design complete, **implementation-planning phase — not approved for merge.**
**Date:** 2026-07-21 (v1: 2026-07-19 · v2: 2026-07-20 · Option C adopted 2026-07-20)
**Origin:** Joe's suggestion — "whitelist all audio except audio coming from peerspeak."
**Scope:** a new capture mode in pixelpass (`src/host/pipeline.rs`, `src/host/audio.rs`),
playback tagging + AEC-identity export + teardown-ordering invariants in peerspeak.

**Why v3 is a rewrite, not a patch.** v1 and v2 both described a design that *moves*
desktop streams onto a capture sink. That design is dead. v2's §5.1 adopted **Option C
(copy via a second owned link)** after a measured feasibility spike, and the AEC
identity gate — the one thing both reviewers agreed nothing could go ahead of — has
since passed. Roughly two thirds of v2 described problems Option C does not have.
Carrying that text forward as "retained for the record" made the live plan unreadable.
v1/v2 remain in git history at `88ad5a0` and `10203e1`.

**Review history**
| Round | Artifact | Verdict |
| --- | --- | --- |
| v1 review | `~/Documents/handoff-docs/Codex/peerspeak/review-2026-07-19-audio-exclusion-design.md` | not sound as written; 4 blockers, all verified correct |
| v2 review | `…/review-2026-07-20-audio-exclusion-design-v2.md` | blocked; produced Option C |
| fan-out spike | `~/Documents/handoff-docs/Claude/peerspeak/fanout-spike-results-2026-07-20.md` + Codex rounds 3/4 | **Option C adopted**, ratified |
| AEC identity gate | `~/Documents/handoff-docs/Claude/peerspeak/aec-playback-leg-identity-2026-07-20.md` | **🟢 gate passed**, both models agree after 2 adversarial rounds |

---

## 1. The problem

A sharer using whole-desktop audio sends their entire output mix to viewers. That mix
necessarily includes peerspeak's own playback — remote peers' voices, remote screen-share
audio — so viewers hear themselves.

`--strict-audio` solved this for *per-app* mode by refusing to mirror the desktop at all.
Whole-desktop mode has no equivalent, so a sharer today chooses between echo and sharing
exactly one app's audio. Joe's ask is the missing third option: **share the desktop,
minus peerspeak.**

## 2. Framing

PipeWire has no capture-side filter. A monitor port carries an already-summed signal;
once peerspeak's output is in that mix it cannot be subtracted out. What PipeWire does
provide is **graph topology**: a node's output ports may link to more than one consumer.

So the feature is built by constructing a sink that only *eligible* streams feed, and
capturing that sink's monitor. Same observable behaviour as a filter, entirely different
mechanism.

This is **not** echo cancellation. `src/audio/echo_cancel.rs` addresses the microphone
path, where coupling is acoustic and needs adaptive cancellation. Here the signals never
need to be summed at all.

**Fidelity is not claimed.** The *membership* of the constructed mix is exact — peerspeak's
audio is never summed in. The *delivered audio* is not lossless: pixelpass downmixes to
48 kHz stereo and AAC-encodes at 128 kbps (`pixelpass/src/host/pipeline.rs:303-324`).
Adding a second link also makes the source node participate in a second format/buffer
negotiation, which can perturb it even though the original link survives (§9.3).

## 3. What exists today

`setup_audio` (`pixelpass/src/host/pipeline.rs:123-142`) activates `Routing` **only** when
`--app` is set or `PIXELPASS_AUDIO_VIA_NULL_SINK` is set. peerspeak's no-app argv is
`--host --output json` (`peerspeak/src/screenshare/mod.rs:135-165`), so normal
whole-desktop capture **bypasses `Routing` entirely** and hands the real default monitor
to `pulsesrc`. This feature is therefore a genuinely new mode, not an inverted predicate.

`Routing::start` (`pixelpass/src/host/audio.rs:65-212`) today provides:

| Piece | Condition |
| --- | --- |
| `module-null-sink pixelpass_capture_<pid>` | always, when `Routing` runs at all |
| `module-loopback @DEFAULT_SINK@.monitor → capture` | skipped only when `--app` **and** `--strict-audio` |
| `StreamRouter` (libpipewire thread) | only when `opts.app` is `Some` |
| local-monitor `capture.monitor → @DEFAULT_SINK@` | on `FirstRoutedStream`, unloaded on `LastRoutedStreamGone` |

Under Option C the null sink is reused, the monitor loopback is never loaded in this
mode, the local monitor is not needed at all, and `StreamRouter` is replaced by a
link manager rather than extended. Two existing defects in that file are inherited and
must be dealt with as prerequisites (§10).

## 4. Architecture — Option C: copy, don't move

pixelpass creates a *second*, pixelpass-owned link from each eligible playback stream's
output ports to the capture sink, and leaves the stream's existing route untouched.

```
  app output ──────────────────────► existing hardware / filter path (UNTOUCHED)
       └── pixelpass-owned link ────► pixelpass_capture_<pid> ──► gst pulsesrc ──► viewers

  peerspeak-owned playback ────────► speakers only   (never linked to capture)
  AEC playback leg ────────────────► speakers only   (never linked to capture)
```

### 4.1 Why this beats the move-based design

| Problem under move (Option A) | Under copy |
| --- | --- |
| local-monitor loopback needed to keep the sharer hearing audio | not needed — audio never leaves the speakers |
| added playback latency for the sharer | gone |
| output-device switch mid-share strands the desktop | gone — the app's own route is never touched |
| prior `target.object` capture/restore | gone — nothing is retargeted |
| pavucontrol conflicts | gone |
| two concurrent hosts fight over `target.object` | gone — links are independent per host |
| SIGKILL strands the whole desktop on an orphan sink | gone — see §4.2 |

**The decisive measurement (spike E2): destroying the capture sink mid-share left the
application playing to its speakers undisturbed.** Capture-side failure degrades to "not
captured," never to "the user's audio is broken." That is Option C's entire case, and it
is the reason a broader eligibility predicate is now acceptable (§6).

### 4.2 Ownership of links is the safety mechanism

In the Rust `pipewire` crate, **dropping a `Link` proxy destroys the object.** So:

- Links are created **non-lingering** and their proxies are **retained** for the life of
  the share.
- Process death (including SIGKILL) destroys the connection, which destroys the links.
  Measured: non-lingering links die on SIGKILL of the owner.
- A stream is counted as captured only once **every** required link reaches `ACTIVE`.
- On any link failure: leave the original route alone, report the stream as unsupported.
  Never fall back to "capture the default monitor instead" — that fallback *is* the echo.

⚠️ **Rig gotchas that constrain how this is built and tested** (learned the hard way):
`pw-link --props object.linger=false` and `pw-cli create-link <props>` both **ignore**
linger and force it on; only `pw-link -m` yields a non-lingering link. `pw-cli
create-object` does not exist in 1.6.8 — the verb is `create-link <node> <port> <node>
<port>`. And links do **not** self-restore after a node or sink is recreated: a *live
owner* must re-link. That re-link loop is the pattern pixelpass has to implement, and
it is also what makes the daemon-restart case (§12) untested rather than free.

## 5. Ownership: identifying peerspeak's own audio

Every peerspeak-owned playback path is either a stream peerspeak itself creates, a
`Command::new(…)` spawn, or a pactl-loaded module. Three mechanisms cover all three.

### 5.1 Env-inherited tag, for spawned children — ✅ MEASURED WORKING

| Owner | Mechanism |
| --- | --- |
| native call playback (`src/audio/pipewire_impl.rs:374-388`) | set the tag directly in the stream's property dict |
| mpv / VLC (`src/screenshare/mod.rs:761`) | `.env("PULSE_PROP", …)` / `PIPEWIRE_PROPS` on the `Command` |
| `pw-play` / `paplay` / `aplay` (`src/notify.rs:265`) | same |

Measured 2026-07-20 on this box (PipeWire 1.6.8): `peerspeak.owned=1` reached the graph
node for **paplay ✅, mpv ✅, VLC ✅**. `PULSE_PROP` and `PULSE_PROP_OVERRIDE` are both
present in `/usr/lib/pulseaudio/libpulsecommon-17.0.so`. (Codex asserted this mechanism
did not exist; it was disproved empirically. VLC has no native PipeWire aout on this box,
which is true and irrelevant — its Pulse path honours `PULSE_PROP`.)

**The tag is a correctness mechanism, not a security boundary.** Any same-user client can
set `peerspeak.owned=1` and opt itself out of capture, and a child can sanitize its own
environment. PipeWire is explicit that only `pipewire.*` properties are usable for
security decisions. Acceptable here: the threat model is "don't echo the user's own call
back at them," not "defend against a hostile local process." Stated, not assumed.

⚠️ **Known leak: a stable boolean is inherited by grandchildren.** Anything mpv or VLC
spawns is exempted too. Accepted for now; revisit if it bites.

### 5.2 The AEC playback leg — 🟢 gate passed, with five load-bearing corrections

`module-echo-cancel` is loaded via pactl (`peerspeak/src/audio/echo_cancel.rs:83-94`), so
its playback leg lives inside `pipewire-pulse` and **cannot inherit an env tag.** It is a
`Stream/Output/Audio` node linked straight to the speakers, so a broad selector *will*
pick it up unless explicitly excluded — and that is not a nicety:

> **Measured (3 arms, links verified in-graph before measuring, recorded via
> `parec -d <sink>.monitor` — the production path):** naive fan-out that includes the AEC
> leg copies remote-call audio into the share at **≈desktop level** (−45.0 dB vs the
> −44.5 dB desktop tone). Exact exclusion produces **−83.3 dB, matching the control floor
> to 0.1 dB.**

**What `module-echo-cancel` actually creates (RESULT 1):** four nodes, not two —
`Audio/Sink peerspeak_ec_sink.<pid>`, `Audio/Source peerspeak_ec_source.<pid>`,
`Stream/Output/Audio **echo-cancel-playback**` (passive, virtual), and
`Stream/Input/Audio echo-cancel-capture`. Codex's "Pulse-compat exposes only
`sink_properties`" concern is real about the *module args* and irrelevant to the *graph
props*.

**The identity (RESULT 2):** all four nodes carry `pulse.module.id` equal, byte for byte,
to the module index `pactl load-module` returned — the value peerspeak already stores in
`EchoCancelGuard::module_index` (`echo_cancel.rs:106-112`, a `String` validated as `u64`).
No PID guesswork, no name matching, no leg correlation.

```
exclude every node where pulse.module.id == <the index pactl returned to the live guard>
```

**⚠️ The five corrections. These are the design, not footnotes:**

1. **This is not an "identity contract."** It is an exact correlation *observed on
   PipeWire 1.6.8*, not a documented API. No PipeWire source is installed on this box and
   neither model had network, so whether the property is the *mechanism* pipewire-pulse
   uses to reap module-created objects or a cosmetic mirror is **UNRESOLVED**.
   ⇒ **Runtime-validate and fail closed** (§5.3).
2. **"Has any `pulse.module.id`" is REJECTED as an exclusion rule.** Tunnel, RTP and
   loopback modules may be the *only* carrier of audio the user legitimately wants
   shared. **Exact equality with the owned live index — nothing weaker.**
3. **Module index and `node.link-group` are REUSED verbatim across unload/reload** (both
   came back `536870919` / `echo-cancel-1974-13`), and **node IDs are recycled *and
   reassigned across legs*** — id 136 was the playback leg on load 1 and the capture leg
   on load 2. ⇒ **Never cache a node id. Never assume leg order. Never cache the module
   index across an unload** — it is only trustworthy as "the index for the currently-live
   guard," so pixelpass must be (re)told on every load.
4. **The `echo-cancel-` group prefix is hazard *detection*, not ownership.** Neither it
   nor the fixed node name `echo-cancel-playback` identifies *peerspeak's* instance. A
   foreign or second AEC is a product-policy question (§5.4). The better long-term answer
   is the **native** PipeWire AEC module, which exposes `playback.props` and would let us
   stamp our own random token directly on the playback leg.
5. **`application.process.id` on the AEC client is `1974` = pipewire-pulse** (verified).
   This reconciles two contradictory prior claims: *real* Pulse clients (paplay) report
   their own PID; *module-created* streams report pipewire-pulse's, because
   pipewire-pulse is the client. Both were right about different cases. **PID-based AEC
   exclusion stays unusable**; PID remains a fallback hint, never identity.

Parse defensively: `pulse.module.id` renders as a JSON **number** in `pw-dump` but SPA
props are strings. `536870919 = 0x20000007`; pipewire-pulse indices start at `0x20000000`
so they fit u32 — but this sits right next to the `object.serial` u32-truncation bug
(§10.1), so compare as strings or as `u64`, never as `u32`.

### 5.3 Fail closed — validation and revocation

Because the identity is an observed correlation rather than a contract, pixelpass must
**verify it at runtime and refuse to run the mode when it cannot**:

- **At start:** given `--exclude-pulse-module <idx>`, enumerate the graph and confirm at
  least one node carries that `pulse.module.id`. If peerspeak said the AEC is on and no
  such node exists, **do not start fan-out** — report a capability failure and fall back
  to a mode with no echo risk (no audio, or an explicit user override).
- **On revocation:** if the validated AEC leg **disappears** while sharing, **stop
  fan-out immediately.** Do not keep the numeric index and hope. Disappearance means
  either the AEC unloaded (index may be recycled onto something else) or our model of the
  graph is wrong; both are fail-closed conditions.
- **Never** infer exclusion from `node.name == "echo-cancel-playback"` alone — it is a
  fixed, non-unique, trivially spoofable string. Usable only as belt-and-braces *after*
  the exact match, or as foreign-instance hazard detection.

### 5.4 Foreign or second AEC instances — a product decision

If a node matching `node.link-group` prefix `echo-cancel-` exists that is **not** ours,
peerspeak is not the only echo canceller on the box. Options: (a) fail closed — refuse
the mode; (b) warn and exclude all `echo-cancel-*` groups, accepting that a legitimate
unrelated AEC's output silently won't be shared. **Recommendation: (b) with a visible
warning** — the failure it prevents (echo) is worse than the failure it causes (one
app's audio missing), and it matches §6's overall posture. **Open decision D3 (§13).**

## 6. Eligibility — a broad guarded selector

Under a *move* design, mis-selection rewired the user's desktop, which forced a narrow
allowlist. Under copy, mis-selection costs at most one stream's capture — so the narrow
allowlist is out. But "fan out everything" is still wrong: it recreates self-echo, it
recreates call echo, it can build cycles, and a second link participates in format/buffer
negotiation.

Agreed predicate:

**Start from all `Stream/Output/Audio` nodes, then exclude:**

| Exclusion | Basis |
| --- | --- |
| `peerspeak.owned` present | §5.1 env tag |
| `pulse.module.id` == the live AEC index | §5.2, exact equality only |
| pixelpass-owned objects, and any node with capture-sink ancestry | cycle prevention |
| `port.exclusive` ports, encoded/passthrough streams | fan-out will refuse or corrupt |
| links we already own for that node | idempotence |

Notes:

- `node.dont-move` **drops out of the predicate entirely** — fan-out is not a metadata
  move, so a node's move policy is irrelevant.
- Links are created **per port**, not per node; channel-count and layout mismatches are
  a per-port concern.
- Anything unrecognized is **fanned out** (copy is cheap) *unless* it hits an exclusion —
  the inverse of v2's posture, and a direct consequence of E2.
- Dynamic nodes: the selector must run on registry global-add for the life of the share,
  not once at start. Nodes created *after* enumeration are exactly the case the spike rig
  was blind to.

## 7. Lifecycle and teardown invariants

### 7.1 ⚠️ The invariant

> **The AEC module must not unload while pixelpass is alive and fanning out.**

If it does, the index pixelpass holds becomes stale, and — because indices are reused
(§5.2 correction 3) — it can alias onto an unrelated future module, silently un-excluding
the real hazard or excluding innocent audio.

### 7.2 ⚠️ VERIFIED DEFECT — implicit-drop order is inverted (not yet fixed)

`ActiveSession` (`peerspeak/src/core/mod.rs:668-691`) declares:

```rust
echo_cancel: Option<EchoCancelGuard>,      // :682
screenshare_host: Option<tokio::process::Child>,   // :685   (kill_on_drop)
```

Rust drops fields in **declaration order**. On the **implicit-drop** path — the command
channels close at `core/mod.rs:1512` (`reliable_rx.recv()` returns `None` → `break`), or
the core loop unwinds — `ActiveSession` is dropped **without** `shutdown()` running. So
`echo_cancel` unloads (a blocking `pactl unload`) *before* `screenshare_host`'s
`kill_on_drop` even fires: **the AEC unloads while pixelpass is still alive.** Exactly the
ordering the invariant forbids. Verified in source.

`shutdown()` (`:694-730`) gets it right — it kills `screenshare_host` at `:699` and drops
`echo_cancel` at `:730` — but only as an emergent property of statement order, which any
refactor can silently invert.

**Fix (implementation phase):** move `echo_cancel` to be the **last** declared field, add
a comment naming the invariant, and add a regression guard. A drop-order unit test is
awkward in safe Rust; the cheap version is a compile-time/`#[test]` assertion over field
order via a doc-tested constructor, or a `Drop` impl on a wrapper that records ordering
into a test-visible slot. **Open decision D4 (§13).**

### 7.3 Construction paths

There is exactly **one** `echo_cancel::enable` call site (`core/mod.rs:1850`, at session
join), the guard moves into `ActiveSession`, and there is exactly **one** explicit drop
(`:730`). **No mid-call AEC reload path exists.** This is what downgraded Codex's demanded
QUIESCE/SET_AEC/RESUME two-process epoch protocol to:

> **P1-impact latent hazard, currently unreachable in normal operation.** Required now:
> encode teardown ordering for explicit *and* implicit destruction, prevent or review
> additional AEC construction paths, fail closed if identity is missing or revoked.
> **An epoch protocol becomes required if and only if hot AEC reload is added.**

Anyone adding a second `enable` site, or any hot-reload, re-opens that requirement.

### 7.4 Graceful stop is still owed

**Stop Share is currently SIGKILL** (`peerspeak/src/core/mod.rs:698` + `:3479`, Tokio
`Child::kill()`). Under Option C this no longer strands the user's desktop audio — the
links die with the connection, which is the point. But it still leaks:

- The capture null sink is **pactl-loaded and pipewire-pulse-owned**
  (`pixelpass/src/host/audio.rs:69`), so **Stop Share leaks one null-sink module every
  time.** This is true today, independent of this feature.

Required:
1. A graceful control path in peerspeak: **SIGINT** (not SIGTERM — pixelpass installs
   only `tokio::signal::ctrl_c()`, `pixelpass/src/common/signal.rs:6`), bounded wait,
   SIGKILL fallback.
2. The capture sink should become **connection-owned** rather than pactl-owned, so it
   shares the links' death-with-the-process property.
3. `--repair` (`pixelpass/src/repair.rs:15-63`) extended to this mode, and safe with a
   second live host.

## 8. IPC: getting the index to pixelpass

pixelpass is a **separate process** and cannot learn the module index on its own.
peerspeak spawns it, so:

- New pixelpass flag: `--exclude-pulse-module <idx>` (naming, §11).
- peerspeak passes `EchoCancelGuard`'s index at spawn. The field is currently private
  with only `source_name()` / `sink_name()` accessors — add `module_index()`.
- If the AEC is **off**, the flag is absent and pixelpass must not invent an exclusion.
- If the AEC is **on** but the flag is absent, that is a bug in peerspeak; pixelpass
  cannot detect it. ⇒ peerspeak should pass an explicit `--aec=off|<idx>` rather than
  "flag present or not," so pixelpass can distinguish "no AEC" from "someone forgot."
  **Open decision D5 (§13).**
- Because no hot-reload path exists (§7.3), spawn-time argv is sufficient today. A
  runtime channel is required only alongside hot reload.

## 9. What is proven, and what is not

### 9.1 Proven by measurement on this machine (PipeWire 1.6.8 / WirePlumber 0.5.15)

- Fan-out carries full-level audio (−24.1 dB, matching the speaker monitor) for **paplay,
  mpv, VLC**; the app keeps its speaker link.
- WirePlumber does **not** reap foreign links across default-sink switch, switch-back,
  suspend, resume, or 100 s steady state.
- Non-lingering links die on **SIGKILL** of the owner.
- **E2:** destroying the capture sink mid-share left the app playing to speakers
  undisturbed.
- `peerspeak.owned=1` lands on paplay/mpv/VLC nodes via `PULSE_PROP`.
- `pulse.module.id` on all four AEC nodes == the index pactl returned.
- Naive fan-out of the AEC leg leaks remote audio at ≈desktop level; exact exclusion sits
  at the control floor.

### 9.2 ⚠️ Wording discipline — three overclaims already made, do not make a fourth

The correct statement of the exclusion result is:

> *"No incremental 1500 Hz energy was detectable above the control floor at the analysis
> resolution in this steady-state run."*

**Not** "absent," **not** "conclusive." What survives is the gross-leak distinction: the
naive arm copies the probe at ≈desktop level, exact exclusion does not. Likewise, equal
`mean_volume` on a sine proves **signal presence, not fidelity** (blind to xruns, drift,
dropouts, channel swap, quantum change), and "copy semantics" is a **topology** result —
it shows the tested link operation did not move the tested Pulse stream, and says nothing
about gain, latency, continuity, or native clients.

The rig is additionally blind to: startup/teardown/cork/relink transients (hidden by
whole-file averaging), broadband and out-of-band leakage, level-dependent and nonlinear
products, and nodes created after enumeration.

**Minimum rig upgrade before shipping:** two orthogonal PN/MLS probes + windowed
per-channel normalized cross-correlation, reporting max per-window correlation, plus xrun
telemetry.

### 9.3 Untested — carried forward, each one a real risk

AEC reload mid-share · two concurrent AEC instances · two concurrent capture sinks · the
**native** PipeWire AEC module · a native-PipeWire (non-Pulse) app · pixelpass's own
null-sink + loopback present simultaneously · the full GStreamer/AAC/network path ·
fidelity (needs broadband source + correlation + xrun telemetry) · PipeWire daemon restart
· quantum/latency perturbation from the second link · sample-rate mismatch, surround,
IEC958 passthrough · browser and game stream shapes.

## 10. Prerequisite fixes (split out, land before the feature)

Both reviews agree these are their own tasks, not part of this feature.

1. **`object.serial` u32 truncation** — 64-bit in PipeWire, parsed as `u32` at
   `pixelpass/src/host/audio.rs:534-540`. Global IDs are reused; serial is the recommended
   stable identifier. Must be fixed before the router grows.
2. **`@DEFAULT_SINK@` resolved once at module load** (`audio.rs:139-151`), no
   default-metadata listener — the user's `Ctrl+Meta+F` / `Ctrl+Meta+S` output-switch
   hotkeys strand the local monitor mid-share. **This already hurts per-app mode today.**
   Option C does not need the local monitor, so this is decoupled from the feature — but
   it is a live bug.
3. **`try_flush` records intent, not success** (`audio.rs:642-655`): it ignores
   `Metadata::set_property`'s return and appends every pending ID to `routed_node_ids`.
   Any status surfaced to the user inherits that dishonesty. Option C's link-state
   `ACTIVE` check (§4.2) is the honest replacement for the new mode; the old path should
   be fixed or deleted.
4. **Graceful stop + connection-owned capture sink** (§7.4).
5. **Drop-order fix + regression guard** (§7.2).

## 11. Naming — the user's call

Placeholders throughout. pixelpass mode: `--audio-mode=desktop-shared` /
`--audio-mode=desktop-excluding`. Exclusion flag: `--exclude-pulse-module <idx>` (or
`--aec <idx|off>`, §8). Do **not** surface `--exclude-pid` — it names an unreliable
mechanism and reads like process control.

peerspeak picker wording: something like "System audio except peerspeak," noting that
call and watched-share playback are excluded. Whether "All system audio" stays alongside
it (with a stated echo risk) or is replaced when the capability is present is a product
decision.

## 12. Testing

Pure, unit-testable seams with PipeWire at the edges, per house style:

- `fn eligibility(node_props: &Props, ctx: &ExclusionCtx) -> Eligibility` with
  `NotEligible { reason }` so status can explain itself. Cases: `peerspeak.owned` present;
  `pulse.module.id` == live index; `pulse.module.id` present but **different** (must be
  ELIGIBLE — correction 2); `pulse.module.id` absent; a pixelpass-owned node; capture-sink
  ancestry; `port.exclusive`; passthrough; non-`Stream/Output/Audio`; missing props
  entirely; the capture sink itself; a foreign `echo-cancel-*` group.
- `pulse.module.id` parsing: JSON number **and** string forms, values > `u32::MAX`,
  absent, malformed.
- AEC-identity validation state machine: `NotConfigured` / `Validated` / `Revoked`, and
  the assertion that `Revoked` stops fan-out.
- Pure capability-probe parsing (§13 D2).
- Link bookkeeping: per-port link set, "captured" only at all-`ACTIVE`, idempotent
  re-enumeration, proxy retention/drop.

Field tests — the only thing that can prove a viewer does not hear themselves:

1. Sharer in a call while sharing, **AEC on and AEC off**.
2. Sharer simultaneously *viewing* another share while sharing.
3. Lifecycle, each separately: Stop button, room leave, UI crash, pixelpass panic, SIGINT,
   SIGTERM, SIGKILL, last-viewer disconnect, pipewire-pulse restart, PipeWire daemon
   restart, `pixelpass --repair`.
4. Output-device switch mid-share via the real hotkey scripts.
5. Two concurrent hosts (second pixelpass CLI, second peerspeak instance).
6. A notification sound firing mid-share.
7. An app that **starts playing after** the share began (dynamic node).
8. Sample-rate / channel / passthrough behaviour on real sinks; CPU cost.

⚠️ **Test-rig discipline** (each of these already produced a wrong result once):
filter on `media.class` **first** when selecting nodes with `jq` — `media.name` also
matches the Client object; **never** filter stderr out of a measurement run; **verify the
link exists in the graph** before measuring; reproduce over the transport production
actually uses (`parec -d <sink>.monitor`, not `pw-record --target <sink-node-id>`, which
reads −91 dB silence).

## 13. Open decisions for the reviewer

- **D1** — Is the fail-closed posture of §5.3 (refuse the mode when AEC identity cannot be
  validated; stop fan-out on revocation) the right trade against "share anyway, warn"?
- **D2** — Capability negotiation: detection today is a `pixelpass --help` substring probe
  (`src/screenshare/mod.rs:245-278`, invoked at `src/core/mod.rs:3368`). This mode must
  **not** overload `app_audio_supported: bool` — strict per-app and desktop-excluding are
  independent capabilities. Enum, bitset, or a version handshake?
- **D3** — Foreign/second AEC policy (§5.4): fail closed, or warn + exclude all
  `echo-cancel-*`?
- **D4** — What is the actual regression guard for drop order (§7.2)?
- **D5** — Explicit `--aec off` vs flag-absent (§8)?
- **D6** — Do the §10 prerequisites all land first, or only 1, 4 and 5?
- **D7** — Is there a materially simpler design meeting Joe's ask that three rounds have
  missed?