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

# Implementation plan: whole-desktop screen-share audio without self-echo

**Status:** 🟢 **v4 — three review rounds applied.** *Progress as of 2026-08-07:* phases 0a, 0b,
0c step 1, 1, 2, 3, 3r, 4 and 5 are merged, and the **phase-5 major gate PASSED on 2026-07-26**
(§1). The current front is **0c step 2**, sliced S1–S5: S1 and S2 merged, **S3a built but
unmerged** (pixelpass `s3a-module-ledger`), S3b/S4/S5 not started. **0d and phases 6–9 are not
built** — nothing merged to date mutates the graph, so the feature has no user-visible behaviour
yet. Phase 6 is the first mutation.
**Date:** 2026-07-21 (v4); status line refreshed 2026-08-07
**Design of record:** [`screenshare-audio-exclusion-plan.md`](screenshare-audio-exclusion-plan.md) v3.4 (`8768cd2`), converged round 7.
**Scope:** *ordering, gates and acceptance criteria only.*

**Reference convention.** `v3.4 §N` = the design doc. `plan §N` = this document. The two
numbering schemes collide (both have a §11 and a §12) and an unqualified reference in v2 sent
Phase 6's most important gate to a section that does not exist. Every cross-reference below is
qualified.

**Review history**
| Round | Findings | Outcome |
| --- | --- | --- |
| 1 | 7 P1 + 5 P2 | 12 accepted, 1 half-rejected → v2. `~/Documents/handoff-docs/Codex/peerspeak/review-2026-07-21-impl-plan-round1.md` |
| 2 | 3 P1 + 7 P2 + 1 P3 | all accepted → v3. `…/review-2026-07-21-impl-plan-round2.md` |
| 3 | verification pass: 4 of 7 edits landed, 3 partial; 2 P1 + 2 P2 + 1 P3 | all accepted → v4. Approved to start Phase 0a. `…/review-2026-07-21-impl-plan-round3.md` |

Adjudication in plan §10. Two of my own claims were refuted by Codex with source evidence and
two of its claims were refuted or narrowed by mine; both are recorded there rather than
quietly dropped.

---

## 0. What this plan is optimising for

The design is converged; the risk has moved from "is it right?" to "will it be built in an
order where each mistake is caught while it is still cheap." Three properties drive every
ordering decision:

1. **Nothing that can create an echo runs before the thing that decides eligibility has been
   validated against a real graph.** The taint engine is the hull. It is built, unit-tested,
   and floated empty (Phase 5, dry-run) before a single link is created.
2. **Every path to unsafe audio is closed structurally before the machinery that could take
   it is written.** There are **two** such paths, not one — the capture *source* and the
   capture sink's *inputs*. Both are closed in Phase 0d.
3. **Every phase ends in a state that is shippable or trivially revertible**, and every gate
   is one a broken implementation can *fail*. A gate that cannot fail is not a gate; where a
   gate asserts only that bad things are absent, it must also assert that good things are
   present, or "captures nothing at all" passes it.

The corollary, stated plainly because it is the most likely way this goes wrong: **the
temptation will be to write the link manager early**, because it is the visible feature.
Fan-out is roughly 400 lines and demos beautifully with a hand-picked node. It is also the
component that, shipped ahead of a validated engine, produces exactly the bug this feature
exists to prevent — in front of Joe.

## 0.1 Cross-repo reality

Two repos, no Cargo dependency; the contract is pixelpass's CLI plus its `--output json`
event stream (`peerspeak/src/screenshare/mod.rs:1-14`). The bulk of the work — graph engine,
link manager, AEC state machine — is **pixelpass**. peerspeak's share is tagging, argv,
capability gating, teardown ordering and the user-visible status surface.

**Hard ship-order constraint.** peerspeak spawns whatever `pixelpass` resolves on `PATH`. If
peerspeak passes `--aec=…` to a pixelpass that predates the flag, clap rejects it and **the
share hard-fails** — the documented A23 / audit-P2 skew failure that already governs
`--strict-audio` (`screenshare/mod.rs:249-262`).

> **pixelpass ships the capability first (Phase 7), including the old-peerspeak/new-pixelpass
> golden test. peerspeak only passes the new flags to a binary that advertised support
> (Phase 8), which owns the new-peerspeak/old-pixelpass golden test. Never "flag present or
> absent" as the protocol — v3.4 D5.**

⚠️ **Capability is resolved twice, against two independently-resolved binaries.**
`ListAudioApps` resolves pixelpass and probes it at `core/mod.rs:3375-3378`; `StartScreenShare`
resolves it *again* at `:3409-3419`. Between those moments `PATH` or the override can change.
Verified in source. Phase 8 must bind the capability result to the resolved path and re-probe
if it differs, failing closed.

---

## 1. Phase map and dependency DAG

| # | Phase | Repo | Mutates graph? | Exit gate |
| --- | --- | --- | --- | --- |
| 0a | `object.serial` u64 fix | pixelpass | no | boundary parse tests |
| 0b | Explicit teardown + drop ordering | peerspeak | no | **four independent mutations** (plan §2; revised from five, §10 r14) ✅ built |
| 0c | Graceful stop + connection-owned capture sink | both | sink ownership | two-host SIGKILL live gate **+ SIGINT-first gate** |
| 0d | **Typed capture plan + internal mode input** | pixelpass | no | mode matrix; neither unsafe source nor unsafe sink input constructible |
| 1 | peerspeak ownership tagging | peerspeak | no | tag on live nodes; literal pinned in plan §3 |
| 2 | Graph model + taint engine (pure) | pixelpass | **no PipeWire at all** | v3.4 §12 fixture matrix + degenerate-snapshot case |
| 3 | Registry observer + readiness epoch | pixelpass | read-only | six-part gate incl. **PID derivation** |
| **3r** | **Observer revision — bind every Node/Device (v3.5 §6.7)** | pixelpass | read-only | **four-part gate (plan §4 "Phase 3 revision")** |
| 4 | AEC identity validation state machine | pixelpass | read-only | fake-clock transition matrix |
| 5 | **Dry-run audit mode** | pixelpass | read-only | 🚦 **MAJOR GATE** — exact decision partitions (plan §5) |
| 6 | Link manager + status events, driven through the real host path | pixelpass | **yes — first mutation** | link-manager matrix (plan §6.1) + live dynamic matrix |
| 7 | **Public mode selector** + capability advertisement | pixelpass | no | old-peerspeak/new-pixelpass golden test |
| 8 | peerspeak integration (mode flag, argv, picker, UI, status) | peerspeak | no | new/new argv golden (mode **and** `--aec`); new-peerspeak/old-pixelpass golden; causal status delivery |
| 9 | Rig upgrade + field matrix | both | yes | 🚦 **SHIP GATE** — plan §7 |

**Landing DAG** (development may be concurrent; *landing* order may not):

```
0a ──────────────────► 2 ──► 3 ──► 4 ──► 5 ──► 3r ──► 5 (re-run) ──► 6 ──► 7 ──► 8 ──► 9
                                                                     ▲
0b ──────────────────────────────────────────────────────────────────┤
0c ──► 0d ───────────────────────────────────────────────────────────┘
1 (r8 carriers) ──────────────────────────────────────► 5 (re-run)
```

✅ **Status 2026-07-26: the phase-5 gate PASSED on run 2 — all 13 §5.1 rows completed.**
Record: [`screenshare-audio-exclusion-phase5-results.md`](screenshare-audio-exclusion-phase5-results.md)
(audit build pixelpass `main` @ `91c4ded`, release profile). Phase 1 was the hard prerequisite
of the re-run for both carriers (plan §3) and was satisfied — rows 4 and 5 passed at the real
tagging sites. **Phase 6 is no longer blocked by this gate.** What still blocks it is the rest
of the DAG: `0b → 6` is satisfied and merged, but `0c → 0d → 6` is not — **0c step 2 remains
open** (S1 and S2 merged; S3a built but UNMERGED on pixelpass `s3a-module-ledger`; S3b, S4 and
S5 not started), and **0d has not been built at all**.

⚠️ **Superseded, kept for the trail — status 2026-07-25 (evening): "3r is BUILT AND MERGED; the
re-run has not happened yet."** The phase-5 gate failed on its first live run and put 3r into
the DAG; 3r's own four-part gate then passed, including the live prop-recovery row on this host.
Phase 5's machinery was built and correct throughout — it is the audit that found the defect,
twice — so "5 (re-run)" was a *re-run of the matrix*, not a rebuild. Run 2 is that re-run.

⚠️ **A smoke run of the audit against the fixed observer immediately found a second defect
(design v3.6 §6.8): a fail-closed `unresolved-ancestry` mark was being promoted to permanent
sticky taint.** Fixed in the taint engine (evidence-only sticky pass, 3 new tests,
mutation-verified) and merged. Decisions were unaffected — all 57 phase-2 tests passed
untouched — so this is a change to what stickiness *remembers*, not to what it *decides*.
Note the pattern for the re-run: the matrix rows assert exact partitions, and a stale sticky
entry from enumeration would have contaminated every one of them.

- **0b strictly precedes 6.** v2/v3 drew 0b with no continuing edge. Phase 6 is the first phase
  that creates objects whose lifetime is tied to pixelpass being alive, so the teardown-ordering
  guarantee must exist before it: without it, the AEC can unload while a fanning-out pixelpass
  still holds link proxies and a stale module index (v3.4 §7.1).
- **0a strictly precedes 2**: the taint engine's lifetime-awareness (v3.4 §6.1.3) is keyed on
  `object.serial`; building the model against the current lossy `u32`
  (`pixelpass/src/host/audio.rs:534-540`; `RouterState::sink_serial` at `:594-598`) means a
  cross-cutting migration later.
- **0c strictly precedes 0d** (round-2): 0d's types must be built around the *final*
  connection-owned bare sink, not today's `Routing`. Building the type boundary against the
  legacy pactl sink means rebuilding it when 0c lands.
- **1 strictly precedes 5**: without tags the taint engine has no roots and the dry-run can
  only exercise the forwarder half of the problem.

---

## 2. Phase 0 — prerequisites

### 0a. `object.serial` u32 truncation — pixelpass
Parse as `u64` throughout; audit the other `parse::<u32>` at `:369` (determine whether it is a
serial or a genuinely-32-bit value before changing it). Tests: value > `u32::MAX`, and the
boundary.

### 0b. Explicit teardown + drop ordering — peerspeak
v3.4 §7.2, decision D4. All **three** of v3.4's fixes:

1. Replace the implicit-drop path at both channel-close sites. **Citation correction:** v3.4
   says `core/mod.rs:1516`; the actual `None => break` arms are at **`:1514`** and **`:1532`**.
   Take the session and `shutdown().await` it.
2. Move `echo_cancel` (currently `:682`) to the last declared field, after `screenshare_host`
   (`:685`), with a comment naming the invariant.
3. **Last-ditch drop wrapper**: `start_kill` + a bounded `try_wait` reap on the host before the
   AEC guard unloads. This is the *only* protection on the panic/unwind path, and unwind is
   reachable — the core has numerous `unwrap()` sites and no `panic=abort` profile.

> ✅ **0b IMPLEMENTED 2026-07-26** (peerspeak branch `phase-0b-teardown`). The ordering
> defect was live: `echo_cancel` was declared *ahead* of `screenshare_host`, so any unwind
> unloaded the AEC while the host was still fanning out. Fields moved into
> `src/core/teardown.rs` with `echo_cancel` declared last, and `ReapOnDrop` added because
> `kill_on_drop(true)` only *signals* — it hands the child to the runtime's orphan queue,
> which an unwinding runtime may never drain. Matrix revised to four mutations; see §10
> round 14, and round 15 for the two blocking review findings that followed.
>
> **Owed to phase 9:** an explicit lifecycle row — *drop the controller / close the command
> channel while sharing* — which is the live proof for the hoisted teardown call site.

⚠️ **Mutation testing: five mutations, each independently breaking a named test.**
⚠️ **SUPERSEDED by §10 round 14 — mutation 2 is vacuous and the matrix is now four.** v1 demanded
a mutation that targeted the wrong defense; v2 fixed that but bundled two defenses into one
combined mutant, which proves neither. Final form:

| # | Mutation | Must break |
| --- | --- | --- |
| 1 | remove `shutdown().await` at `:1514` | close-arm-A teardown test |
| 2 | remove `shutdown().await` at `:1532` | close-arm-B teardown test |
| 3 | remove the explicit **wait** after host kill | explicit-ordering test (host kill+wait strictly precedes AEC unload) |
| 4 | reverse the field order | panic/unwind ordering test |
| 5 | remove the wrapper reap | panic/unwind ordering test (distinct assertion from #4) |

Both channel-close arms get their own test; a single "closes the command channel" test can
exercise one arm and leave the other unsafe.

### 0c. Graceful stop + connection-owned capture sink — both

> ✅ **MECHANISM PROBE PASSED on this host, 2026-07-26** (PipeWire 1.6.8). Run *before* any
> structural work, on the reviewer's insistence, because a single unverified assumption could
> have invalidated the entire approach: whether a hand-created adapter is visible to
> pipewire-pulse under the name pixelpass's capture path depends on. It is.
>
> ```
> pw-cli> create-node adapter factory.name=support.null-audio-sink \
>           node.name=pixelpass_probe_<pid> media.class=Audio/Sink \
>           audio.channels=2 audio.position=[FL,FR] node.virtual=true \
>           monitor.channel-volumes=true object.linger=false
> ```
>
> Five gates, all green:
> 1. `pactl list short sinks` shows the sink under the **exact** `node.name`.
> 2. `pactl list short sources` shows **`<node.name>.monitor`** — the derived monitor name is
>    a pipewire-pulse contract, not a property of Pulse-created sinks. This was the one that
>    could have sunk the approach.
> 3. `gst-launch-1.0 pulsesrc device=<node.name>.monitor num-buffers=40 ! fakesink` pulled its
>    buffers and exited clean, and a real recording stream attached — so the pixelpass capture
>    path works against it unchanged.
> 4. **No null-sink module was loaded** (`pactl list short modules | grep -c null-sink` stayed
>    at its baseline of 3). It is genuinely not a Pulse module.
> 5. **SIGKILL of the owning connection removed both Pulse-visible names**, with zero residue
>    anywhere in `pw-dump`. That is the entire point of 0c, demonstrated on the real graph.
>
> The default sink never moved, so this is also safe to run on a live desktop.
> **Every O1 stop condition listed for 0c is retired.** `object.linger=false` is load-bearing:
> the bundled pipewire-rs example sets `linger=1` for the opposite behaviour.
>
> ⚠️ **`--repair`'s job does not shrink — it BREAKS.** Discovery derives dead host PIDs
> **only** from `module-null-sink` entries (`pixelpass/src/repair.rs`), and only then matches
> loopbacks against that PID set. The native sink is scoped to **every mode that owns a
> capture sink**, not just `DesktopExcluding`, so legacy Pulse loopbacks will coexist with a
> connection-owned sink; when that host dies the sink vanishes automatically and its loopbacks
> become **undiscoverable orphans**. Candidate PIDs must be derived independently from all
> three module shapes (`null-sink sink_name=`, `loopback sink=`, `loopback source=…monitor`),
> with a liveness recheck immediately before each destructive unload. This makes the repair
> rework **load-bearing, not defensive**.
v3.4 §7.4. The **largest hidden cost in Phase 0**: moving the null sink off `pactl load-module`
(`pixelpass/src/host/audio.rs:69`, cleaned up only in `Routing::cleanup` at `:259-260`, which
SIGKILL skips) onto a connection-owned PipeWire object.

- peerspeak: SIGINT (**not** SIGTERM — pixelpass installs only `ctrl_c()`,
  `pixelpass/src/common/signal.rs:6`), bounded wait, SIGKILL fallback, at `core/mod.rs:699`
  and `:3480`.
- pixelpass: connection-owned sink; `--repair` (`src/repair.rs:15-63`) extended and proven safe
  with a second live host.

**Exit gate — two halves. The round-2 finding was that v2 gated only the first.**

*(i) Ownership,* a live two-host test — connection-ownership is a runtime property no unit test
can establish:

```bash
pactl list short sinks | rg 'pixelpass_capture_'
pw-dump | jq -r '.[] | select(.type=="PipeWire:Interface:Node") | .info.props as $p
  | select(($p["node.name"] // "") | startswith("pixelpass_capture_"))
  | [$p["object.serial"], $p["node.name"]] | @tsv'
kill -KILL <first-pixelpass-pid>
# re-run both: the killed host's object GONE, the second host's REMAINS
pixelpass --repair    # the live host must be untouched
```

*(ii) Graceful stop,* which the above does not touch at all — it exercises only external
SIGKILL, so Stop Share could remain `child.kill().await` (`core/mod.rs:3480`, still true today)
and every command above would pass:
- a fake-child signal-order test: SIGINT first, SIGKILL only after the bound expires;
- a live Stop Share run: SIGINT sent, child exits within the declared bound, **no fallback
  kill on the normal path**.

**O1 is closed: no demotion path.** v1 pre-authorised moving 0c after Phase 6 if it ballooned.
That is a waiver of settled decision v3.4 D6 hidden in a sequencing document, which is how a
converged design quietly decays. If 0c balloons, **stop and reopen D6 as design round 8.**

### 0d. Typed capture plan + internal mode input — pixelpass

Today `setup_audio` returns `(Option<Routing>, String)` (`pipeline.rs:123-142`) and the `String`
flows untyped into `build_args` (`:151-157`). There are **two** unsafe paths into the capture,
and v2 closed only the first:

**Path 1 — the source string.** `default_audio_monitor()` has exactly one call site,
`pipeline.rs:138`. That single line hands `pulsesrc` the real default monitor.

**Path 2 — the sink's inputs (round-2 P1, the defect v2 missed).** Even with a type-safe source,
`Routing::start` loads `module-loopback source=@DEFAULT_SINK@.monitor → pixelpass_capture_*`
whenever it runs outside strict-app mode (`audio.rs:80-92`), and it runs whenever
`PIXELPASS_AUDIO_VIA_NULL_SINK` is set (`pipeline.rs:124-125`). So `DesktopExcluding` could
correctly read *its own* sink's monitor while the legacy loopback has already filled that sink
with the whole-desktop mix — **full echo, with no source switch anywhere.** v3.4 §3 states this
loopback must never load in the new mode; nothing structurally enforced it.

Both are closed by construction:

- `LegacyDesktop` — the only variant that can produce `DefaultMonitor`.
- `PerApp { routing }` — legacy `Routing`, unchanged.
- `DesktopExcluding { capture_sink }` — owns a **bare** connection-owned sink type (0c) whose
  API **cannot construct the legacy loopback at all**. Not "does not call it": the constructor
  is not reachable from this variant.
- **Conflict policy, pinned here rather than discovered later:** the new mode combined with
  `--app` or `PIXELPASS_AUDIO_VIA_NULL_SINK` **rejects at CLI parse time**. It must never fall
  through to legacy `Routing`, and it must never silently ignore an input the user set.
- **Internal mode input lands here too** (round-2 P1): a non-advertised `HostOpts` field plus a
  hidden trigger, so the variant is reachable through the real host/spawn path before Phase 6
  needs to measure through it. `HostOpts` has no mode field today and `setup_audio` selects
  solely on `app` + the env override.

**Why 0d is a prerequisite rather than a Phase 6 deliverable** (my divergence from Codex's
round-1 suggestion; it agreed in round 2): this is a pure non-mutating refactor of one function,
and landing it in Phase 6 means the link manager is written against the untyped API and then
refactored underneath itself, while the two most dangerous paths in the codebase stay unguarded
through four phases of active work around them. Guardrails go up before the scaffolding.

**Exit gate:**
- mode matrix over every `(app, strict_audio, mode, env-override)` combination asserting the
  resulting capture plan, including every conflict combination rejecting;
- type-level: `DesktopExcluding` can name neither the default monitor nor the legacy loopback;
- **graph assertion**: with the new mode active, no default-monitor link or module feeds the
  capture sink;
- legacy behaviour byte-identical.

A constructible-but-not-yet-public variant is acceptable for the interval between 0d and Phase
6 provided it is unit-tested and reachable by the hidden trigger.

---

## 3. Phase 1 — peerspeak ownership tagging (v3.4 §5.1)

Zero behaviour change; it is what makes Phase 5 observable.

- Native playback: prop on the stream dict, `src/audio/pipewire_impl.rs:374-388`.
- mpv/VLC spawn (`src/screenshare/mod.rs:768-775`), notification spawn (`src/notify.rs:265-272`):
  `PULSE_PROP` + `PIPEWIRE_PROPS` on the `Command`.

⚠️ **The literal is a cross-repo wire contract and is pinned HERE, before Phase 1 starts** — not
deferred with the v3.4 §11 product naming, which is a separate and genuinely user-facing question.

```
key:   peerspeak.owned
value: 1
```

⚠️ **Round 8 — a SECOND carrier is required, and its literal is pinned here too** (v3.5 §5.1).
`peerspeak.owned` is invisible to the registry `global` event and readable only via a node
bind (v3.5 §6.7); the prefix below is announced by the registry and needs no bind, so the
primary taint root no longer rests on a single observation mechanism.

```
key:    node.name
format: peerspeak_owned_<role>_<pid>        e.g. peerspeak_owned_mpv_31284
prefix: peerspeak_owned_                    ← the matched literal
```

- **Both carriers are set at every tagging site.** A node is owned if **either** matches —
  union, the fail-closed direction. The engine's tag root is `peerspeak.owned == 1` **OR**
  `node.name` starts with `peerspeak_owned_`.
- **`node.description` is NOT touched**, so mixers still show "mpv". Only `node.name`, which
  is the internal identifier, carries the prefix.
- The prefix mechanism is already proven here: `pixelpass_capture_*` is matched on
  `node.name` and was the only root that kept working under the F1 defect.
- Same three requirements as the property literal: one named constant per repo, the
  black-box cross-repo test driven from a shared fixture, and phase 5 as the real proof.
- ⚠️ Native call playback sets both on its own stream dict. The child spawns set the prefix
  through the same `PULSE_PROP` / `PIPEWIRE_PROPS` env that carries the property —
  `node.name` is settable there, and **the phase-1 exit gate must show it landing on a live
  mpv node**, not just in the env.

**A per-repo literal test is not a contract test.** Two tests, one per repo, each maintained
beside its own implementation, get updated in lockstep with a rename and prove nothing. Required:

1. The literal appears **once** per repo as a named constant, commented with a pointer to this
   section and to the other repo's constant.
2. A **black-box cross-repo test**: peerspeak constructs the child `Command`, the test reads the
   env it would set, and asserts it produces the exact property string pixelpass's engine
   matches on — driven from a single shared fixture string committed in both repos.
3. The real proof is the **Phase 5 dry-run**, which requires pixelpass to classify all three
   live peerspeak playback paths as `NotEligible` *for the tag reason*. Emission alone proves
   only that peerspeak talks, not that pixelpass listens.

**Exit gate:** `pw-dump` shows the tag on a native call playback node, an mpv node and a
notification node on this box. (Consumption is gated in Phase 5.)

**Non-goal:** the known grandchild-inheritance leak (v3.4 §5.1) stays accepted in v1.

---

## 4. Phases 2–4 — the engine (pixelpass)

### Phase 2 — graph model + taint engine, pure
All of v3.4 §6.1–§6.1.3, **with no PipeWire types in any signature**:

```
fn evaluate(snapshot: &GraphSnapshot, ctx: &ExclusionCtx, prior: &StickyState)
    -> (Decisions, StickyState)
```

- `GraphSnapshot` = plain owned Node/Port/Link/Client structs keyed on `u64` serial, with the
  recyclable id retained only as a lookup key, never as identity (v3.4 §6.1.3).
- `Decisions` carries `Eligibility::NotEligible { reason }` with **stable reason codes**, not
  prose. That code is the Phase 5 dry-run output, the Phase 6 JSON status event, and the
  eventual "why isn't this app shared" answer. Design it once, here.
- `StickyState` threaded explicitly, so stickiness is testable as a snapshot sequence.

**Every row of the v3.4 §12 taint-engine table is a required deliverable**, plus one addition:
an **empty/degenerate snapshot must yield "nothing eligible", not "everything eligible"** — the
fail-closed default asserted at the boundary.

**Exit gate:** fixture matrix green; the engine has never been linked against libpipewire.

### Phase 3 — registry observer + readiness epoch, read-only
v3.4 §6.3 and §6.4. Replaces (not extends) the existing router, which watches Node and Metadata
adds, forwards raw removals, and binds no graph (`src/host/audio.rs:523-585`).

> ⚠️ **Built and merged, then superseded in part by "Phase 3 revision (round 8)" below.** This
> section's node-property requirements assume the registry `global` event carries them. It does
> not (v3.5 §6.7). Everything here about removals, the readiness epoch, PID derivation and the
> Link path is unaffected and still holds.

- Node, Port, Link **and Client** globals; adds **and removes**.
- Link endpoint props from the global are the **optimisation**; the bind-`LinkInfoRef` fallback
  is the correctness path.
- Readiness = `core.sync()`/`done` **plus** no outstanding required observations, fail-closed
  timeout. Log which condition released the epoch.
- pipewire-pulse PID derivation (v3.4 §6.1.2): consistent `pipewire.sec.pid` across Pulse
  clients, validated against `/proc/<pid>/comm`.

**Exit gate — six parts.** A one-time `pw-dump` diff passes while Port observation is absent,
removals are ignored, the fallback is dead code, and readiness releases early:

| gate | proves |
| --- | --- |
| adapter tests: add **and remove** of all four object types | removal handling exists |
| forced-absent Link endpoint props | the bind fallback is live, not decorative |
| unresolved-observer timeout test | readiness fails closed |
| readiness does not release with an observation outstanding | the epoch means something |
| **PID derivation matrix** (round-2): consistent valid PID · inconsistent PIDs · missing client property · `/proc` entry missing · `comm` mismatch · PID reuse — **every failure makes owner-bridge key 4 unusable** | the pure engine can be correct on a wrong context; this is where the context is built |
| **live**: create and destroy a controlled node/link topology; diff Nodes, **Ports**, Links and Clients before/during/after | the adapter tracks a *changing* graph, not a static one |

### Phase 3 revision (round 8) — bind every Node and Device ✅ BUILT AND MERGED 2026-07-25
v3.5 §6.7. Phase 3 shipped reading node properties off the registry `global` event, where
**eight of them are never announced**. This is the fix. Scope is the observer only — phases 2
and 4 are unaffected, and the phase-5 audit machinery is already correct.

> **🟢 Done.** Pure core + adapter, split-seam with mutual review as in phase 3 (mine and
> Codex's respectively, each reviewing the other). All four gate rows below pass, the live
> row on this host. Codex's review of the core found no certain P1; two findings taken and
> mutation-verified (a `device_props` ambiguity test that checked for one live *Device*
> rather than one live *global*, and `device.api` corroborating by presence). Two findings
> left open as design items, both pre-existing — hardware playback-to-capture paths and the
> readiness-budget calibration, both recorded in design §6.8.
>
> **Added beyond the spec: a second live gate for the Device-side path.** Row 1's
> `session_device` assertion is satisfied by a union, and WirePlumber 0.5.15 copies
> `device.api`/`alsa.driver_name` onto ALSA nodes on this host — so row 1 passes through the
> node fallback and would keep passing if the Device bind delivered nothing at all, leaving
> §6.7 decision 4 ungated on the development machine. Verified by mutation: breaking the
> Device-side driver read fails the new test while row 1 still passes.

**Requirements.**

1. **Bind every `Node` global**, unconditionally, no `media.class` filter. Retain the proxy
   and its `info` listener in that global's slot in the existing per-id FIFO
   (`LiveGlobal.bound_link` generalises to a bound-proxy slot).
   ⚠️ The phase-3 review's finding 3 — record the id and apply the add as **one** step, so
   the proxy FIFO stays lockstep with the model's `live_ids` — now applies on the **hottest**
   path in the observer. A recycled Node id must not pop another generation's proxy.
2. **The global is an index; `info` is the source of truth.** Read from the global only what
   must exist before the bind resolves: `object.serial` (identity), the object's id, and
   `device.id`/`node.id` linkage. **Every** taint-relevant property — including `node.name`
   and `media.class`, so there is exactly one source — comes from the bound `info` props.
3. **A node with no `info` yet is WITHHELD from the snapshot and is a readiness obligation**
   (`pending_nodes`, beside `withheld` and `pending_links`). `graph_ready` false while any is
   outstanding; the existing bounded deadline makes an unresolvable bind sticky-`TimedOut`,
   fail closed. No provisional-ownership admission, ever (v3.4 §6.1.3).
4. **Track props for the node's lifetime.** On a later `info` with `PROPS` in `change_mask`,
   re-read, re-classify, and apply a `NodePropsUpdated` event.
   ⚠️ **Suppression rule:** a prop update may be dropped **only** when the resulting
   `Projection` is identical to the current one. Anything looser breaks phase 4's
   no-coalescing contract; anything stricter (emitting on every `info`, including
   state-only changes) inflates the O5 event rate with non-events.
5. **Bind every `Device` global** and read `device.api` **and** `alsa.driver_name` from its
   `info` props — authoritative, and the phase-3 review's owed fix (on PipeWire ≥ 1.2.6 with
   WirePlumber < 0.5.13 the driver name is not copied to the node, and the fail-closed
   absent-driver rule would over-exclude real cards). `factory.name` exists only on the node.
   `classify` takes both sides; node values are the fallback, Device values win.
6. **Ports are NOT bound in v1 — an explicit accepted limitation.** `port.exclusive` is the
   only port property missing from the global, and it guards a *mutation* (don't fan out into
   an exclusive port), not echo: an exclusive port rejects the second link, so phase 6 sees a
   clean link-create failure it must handle correctly anyway. Binding ~21 more objects at
   rest to pre-empt an error that surfaces safely is not worth the obligation surface in v1.
   **Revisit trigger:** any phase-6 link-matrix row where an exclusive-port link failure is
   not cleanly recoverable. (`node.passthrough`, the *other* half of that §6.2 row, is a node
   property and **is** recovered by this revision.)

**Exit gate — four parts.** The first is the direct inverse of the F1 finding.

| gate | proves |
| --- | --- |
| **live prop recovery**: a `module-null-sink` tagged `peerspeak.owned=true` plus a `module-loopback` reading its monitor — assert the projection carries `peerspeak.owned`, `pulse.module.id`, `node.link-group` **and** `factory.name`/`device.api`/`alsa.driver_name` on a real ALSA node | the eight properties actually arrive — F1 cannot recur silently |
| **pure-model prop-update matrix**: props-changed → re-classified; identical props → suppressed; a `session_device`-relevant change flips classification. (A *live* prop mutation has no reliable CLI trigger — the pure test is the gate, a live sighting is opportunistic) | the lifetime-tracking path exists and its suppression rule is exact |
| **readiness with node binds**: no projection reports `graph_ready` while a node bind is outstanding; an `info` that never arrives ends in sticky `TimedOut` | withholding and fail-closed timeout still hold with the new obligation class |
| **recycled Node id under churn**: repeated add/remove of the same id; no proxy leak, no cross-generation misattribution | the FIFO lockstep rule survives being moved to the hot path |

**Then re-run the whole phase-5 §5.1 matrix and re-measure O5** with bind I/O included — the
existing numbers were taken on the degraded graph and inherit nothing.

### Phase 4 — AEC identity validation state machine, read-only
v3.4 §5.3 verbatim: `NotConfigured / Validating / Validated / Failed / Revoked`;
`--aec=off|pulse-module:<idx>` parsing (D5); bounded deadline; **no fan-out while `Validating`**;
revocation = loss of *all* nodes bearing the index, never one leg corking. Foreign
`echo-cancel-*` groups: warn and exclude (D3).

**Moved ahead of the dry-run gate (round-1 P1).** v1 put this after the dry-run while the
dry-run checklist required AEC validation and revocation semantics — a circular dependency that
made the major gate uncompletable as written.

**Exit gate — a fake-clock/event-sequence transition matrix**, because these are timing
semantics a live poke cannot cover: `Validating → Failed` on deadline expiry; `Validating →
Validated` on first matching node; partial-node disappearance ⇒ **stays `Validated`**; all
nodes gone ⇒ `Revoked`; `Revoked` stops fan-out and drops proxies; a retained stale index does
not alias onto a reloaded module (v3.4 §5.2 correction 3 — indices *are* reused). Parsing: JSON
number and string forms, `> u32::MAX`, absent, malformed.

Then wire the state machine's output into the dry-run so `Validating`/`Failed`/`Revoked` are
observable in Phase 5 before they gate anything real.

---

## 5. Phase 5 — dry-run audit mode 🚦 MAJOR GATE

> **🚦 STATUS 2026-07-26: GATE PASSED on run 2.** Results:
> `docs/screenshare-audio-exclusion-phase5-results.md`. All 13 rows completed, the eligible
> half of every row is non-empty, and O5 is re-measured on the fixed graph (worst recompute
> 67 µs; readiness 1–2 ms with 18 binds). Three rows carry recorded substitutions (8, 9, 13)
> and three findings are recorded as non-blocking.
>
> **Run 2 found and fixed a third defect of the F2 class, F13-1:** pipewire-pulse's PID was
> unresolvable on this host *permanently*, because stage 1 of the derivation required exactly
> one repeated `sec_pid` and **WirePlumber repeats one too** (two Clients, one PID). Key 4's
> suppression therefore never fired and every Pulse-emulated node fused into one owner. Fixed
> in pixelpass `91c4ded`: probe every distinct `sec_pid` and let `/proc/<pid>/comm` decide.
> **The eligible half of row 1 is the only thing that exposed it** — the verdict was
> fail-closed and silent.
>
> ⚠️ **Phase 6 is NOT unblocked by this file alone.** F11-1 was the other gate and is now
> **closed** (2026-07-26, pixelpass `c78eb2d`: key 4 bounds an owner only when the node's
> Client resolves; measured cost on the live graph, zero — see the results file). Phases
> 0b/0c/0d and the "Stereo Mix" design call still precede phase 6.
>
> Two things to keep when re-running: **every partition row must run with `AEC=off`** (a
> configured-but-unvalidated AEC shuts the fan-out gate and empties the eligible half of every
> row, which reads as a failure that is really a harness error), and **start the audit BEFORE
> building the fixture**. Fixture-first makes the whole graph arrive as one enumeration burst,
> so every node is first tainted while `graph_ready` is false; that partial-graph taint enters
> sticky state and the keyless sticky reason then wins over the evidence-derived one, so a row
> cannot assert its own key. Read keys at *derivation* (first non-sticky appearance).

**Adds no capability. Its entire purpose is to be wrong loudly and safely.**

A hidden trigger (`PIXELPASS_AUDIO_AUDIT=1`) running Phases 2–4 against the live graph on every
graph event, emitting per `Stream/Output/Audio` node: serial, name, decision, stable reason
code, graph epoch. It creates **no links**. Output goes to **stderr or a defined JSON event** —
never unstructured prose into `--output json`, which peerspeak parses
(`screenshare/mod.rs:92`).

Why this is the gate: the C2/C3-class defects are graph-*reasoning* defects. A fixture proves
the code matches my model of PipeWire; only a live run proves my model matches PipeWire. A wrong
answer here costs a log line; the same wrong answer in Phase 6 costs an echo.

### 5.1 Every row asserts an exact partition, not a spot check

Round 2's sharpest structural point: checking only named targets constrains nothing about
everything else, so **each row must assert the complete candidate universe partitioned into
exact eligible and excluded sets, with reason codes on the excluded side.** That single
requirement is also the answer to O7 — it is the over-exclusion gate, because an
exclude-everything implementation fails the eligible half of every row.

| # | Scenario | Excluded (with reason code) | Eligible |
| --- | --- | --- | --- |
| 1 | `module-null-sink` + `module-loopback` forwarder (the v3.4 §6.1 measured shape) | output leg, reason = **owner bridge**, naming the key — *not* a Link walk | same forwarder shape with **no** tainted input |
| 1b | *opportunistic, non-gating:* Sunshine's null-sink topology while it is routing desktop audio | its forwarder leg, if a re-emitting leg exists | — |
| 2 | `gst-launch pulsesrc ! pulsesink` split clients, input **explicitly rooted on a tainted monitor** | output leg via key 4 | the same process reading an **untainted** source |
| 3 | **two** Pulse modules; **one** tainted input | the tainted module's output only | **the other module's output must be ELIGIBLE** — this is what makes wrong pipewire-pulse-PID fusion observable |
| 4 | peerspeak native call playback | that node, reason = tag | — |
| 5 | peerspeak-spawned **mpv** (watched share) | that node, reason = tag | mpv launched by hand |
| 6 | peerspeak **notification** sound | that node, reason = tag | — |
| 7 | a **second** pixelpass host's capture sink, **plus a controlled forwarder reading that sink's monitor** | the forwarder's **named output serial** (cycle prevention, v3.4 §6.2) | — |
| 8 | EasyEffects running | combined output leg | EasyEffects stopped ⇒ ordinary streams |
| 9 | Firefox: music only / mic on untainted source / capturing a tainted monitor | the third only (v3.4 §6.1.1) | the first two |
| 10 | sticky taint: tainted input leg removed, output leg lives | still excluded | after full owner teardown + restart |
| 11 | recycled serial/index/link-group after teardown | — | must **not** inherit taint |
| 12 | AEC loaded, then unloaded | four nodes; then `Revoked` | — |
| 13 | `Audio/Duplex` device | over-taints, recorded as **known accepted** (v3.4 §6.1 caveat) | — |

Rows 3 and 7 were vacuous in v2: row 3 had no tainted module, so incorrect fusion of all
pipewire-pulse modules changed no emitted decision; row 7 observed a capture sink without naming
a downstream candidate, so recognising `pixelpass_capture_*` as a mere sink name would pass
without any transitive propagation.

### 5.2 Also record, per O5
Graph-event rate, recompute duration **distribution and maximum**, and whether events queue
behind recompute/logging. v3.4 §6.4's "full recompute is fine for v1" then rests on measured
headroom and epoch lag rather than on a node count.

### 5.3 ⚠️ Do not build a gate on a transient topology
v1 leaned on v3.4 §6.1.0's "the hazard is LIVE on this machine right now." **Measured
2026-07-21 ~14:55 — no longer true**, six hours after it was written: `Default Sink` is
`alsa_output.pci-0000_10_00.6.analog-stereo` (IDLE), all three `sink-sunshine-*` null sinks
SUSPENDED. Sunshine is still running (pid 4104) and still reads a monitor — but the hardware
sink's, via active link `56 → 95`, not a null sink's. So Sunshine running is **not** sufficient
for the topology to be present; see plan §11.

The **controlled fixture (row 1) is authoritative** — deterministic and always available. But
the wild sample is not therefore unnecessary: a fixture I build tests my model against my own
assumptions, whereas Sunshine is an uncontrived third-party forwarder nobody designed for this
test. It stays as row 1b, **opportunistic and non-gating**, because it cannot be relied on to
be present.

**Any surprise here goes back to the design doc as round 8. Phase 6 does not start until this
results file exists.**

---

## 6. Phases 6–8 — mutation, capability, integration

### Phase 6 — link manager + status events, driven through the real host path
v3.4 §4.2 + §6.2 + §6.3 items 3–4. Non-lingering links (rig gotcha: `object.linger=false` is
*ignored* by `pw-link --props` and `pw-cli create-link`; only `pw-link -m` yields one), proxies
retained for the life of the share, per-port link sets, "captured" only when **every** required
link is `ACTIVE`, same-epoch revalidation immediately before each creation, proxy drop on
ancestry becoming unsafe.

Failure ⇒ report the stream unsupported. **Never** fall back to the default monitor — and after
0d that fallback is unconstructible in this mode, by either path.

**Everything here is measured through the real selector → sink → link manager → `pulsesrc`
path**, using 0d's hidden trigger. A harness-only measurement would pass while the production
CLI still reaches only legacy branches.

**Status events land here** (round-1/2: no phase owned them). pixelpass's event enum
(`src/common/output.rs:36-66`) has nothing for exclusion status, and capture-spawn failure
(`host/mod.rs:309-312`) replies to the viewer while emitting no event at all. Required as
**versioned wire-shaped events**, not stderr lines. Without them the safe failure mode is
unexplained silence after the first viewer connects — and a sharer who cannot see why will
switch back to unsafe whole-desktop audio.

There are **four** production causes, and each needs an **exact JSON golden plus a cause →
emission test** — not a shared "an event is emitted" assertion, which passes while three of the
four remain unwired:

| cause | event | trigger under test |
| --- | --- | --- |
| per-stream link failure | `stream_unsupported` | link-matrix row 8c |
| AEC validation deadline | `aec_failed` | Phase 4 `Validating → Failed` |
| AEC identity lost mid-share | `aec_revoked` | Phase 4 `Validated → Revoked` |
| foreign `echo-cancel-*` present (D3) | `foreign_aec_warning` | a second AEC module loaded |

Phase 8 owns the other half of each: parse, traverse the **new mode's** notice channel, and
reach the intended UI state. The channel is currently created only for `audio_app`
(`core/mod.rs:3424`) and only the two `AppAudio` events are translated (`:3431-3434`).

#### 6.1 Link-manager matrix (local anchor — v3.4 §12 has only a one-line bullet)

v2 pointed its most important gate at a "v3.4 §12 bookkeeping matrix" that does not exist.
Here it is. Each row is a deterministic test with an injected graph, not a live observation:

| # | Case | Assertion |
| --- | --- | --- |
| 1 | graph mutated to tainted **between evaluation and `create_link`** | **zero unsafe `create_link` calls** — not "eventually cleaned up" |
| 2 | per-port enumeration | exact set of attempted links and their states |
| 3 | partial activation (FL `ACTIVE`, FR not) | **not** reported captured |
| 4 | duplicate enumeration of the same node | idempotent; no second link set |
| 5 | ancestry becomes unsafe after `ACTIVE` | owned proxies dropped |
| 6a | `port.exclusive` port | refused, reason code emitted |
| 6b | encoded stream | refused, reason code emitted |
| 6c | passthrough (IEC958) stream | refused, reason code emitted |
| 7 | capture sink replaced | relink **succeeds** — every required port back to `ACTIVE` and the node reported captured again; stale proxies dropped |
| 8a | AEC `Failed` (validation deadline) | plan stays `DesktopExcluding`; no capture |
| 8b | AEC `Revoked` mid-share | plan stays `DesktopExcluding`; fan-out stops |
| 8c | link creation error | plan stays `DesktopExcluding`; that stream reported unsupported |
| 8d | capture-sink creation failure | plan stays `DesktopExcluding`; mode fails, does not degrade |
| 8e | readiness-epoch timeout | plan stays `DesktopExcluding`; fail closed |
| 9 | an **eligible** late-arriving node | **positively captured** — the over-exclusion counterpart to row 1 |

Rows 6a–6c were one combined fixture in v3: a single working refusal predicate would have
masked two missing ones. Row 7 required only "relink attempted", which a permanently-failing
attempt satisfies while v3.4 §4.2 requires a live owner to actually restore links after sink
recreation. Rows 8a–8e replace an unenumerated "any failure path", under which testing one
handler passes while another silently swaps the plan to `LegacyDesktop`.

Row 1 is the one v2 could not falsify: "clean → tainted mid-share ⇒ links dropped" can pass by
observing eventual removal, while an unsafe link genuinely existed for a window. Row 8 is O8's
answer: 0d's enum prevents a `DesktopExcluding` value from *containing* `DefaultMonitor`, but
not a failure handler from replacing the whole plan with `LegacyDesktop`, so this needs a
release-mode integration test per failure transition. A `debug_assert!` is cheap and worth
adding, but it is not a gate.

Plus the live dynamic matrix (SIGKILL removes owned links; node appearing after share start;
sink recreation) and the three-arm leak measurement re-run through the production path with
v3.4 §12's rig discipline (`media.class` filter first, never drop stderr, verify the link is
in-graph, `parec -d <sink>.monitor`). The deliberately-naive predicate used as that
measurement's positive control lives in a **test-only injected implementation**, never a
shippable runtime override.

### Phase 7 — public mode selector + capability advertisement (pixelpass ships first)

⚠️ **Round-3 P1: nothing in v3 ever promoted the hidden trigger to a public flag.** 0d added an
internal mode input; Phase 7 advertised capability and naming; Phase 8 added `--aec`, the picker
and status. No phase required the actual **mode selector** to exist publicly or to be passed.
The result would be a capability-gated picker entry that, when chosen, still spawns legacy
whole-desktop capture — the feature appearing to ship while doing nothing. Reachable: peerspeak's
host argv has no mode parameter (`screenshare/mod.rs:152`) and pixelpass's `HostOpts` has no mode
field (`cli.rs:153`); v3.4 §11 requires a distinct mode selector.

So Phase 7 lands **both**:
1. the public mode flag (naming per v3.4 §11), replacing the 0d hidden trigger as the production
   entry point — the hidden trigger may remain for testing;
2. D2's **versioned machine-readable** capability response or bitset. Must **not** overload
   `app_audio_supported: bool` — per-app-strict and desktop-excluding are independent
   capabilities. `--help` substring probing survives only as the legacy fallback.

**Old-peerspeak + new-pixelpass golden test lands here, before pixelpass ships**: behaviour
byte-identical, absent `--aec` still accepted.

v3.4 §11 public naming is a **blocking user input at the start of this phase**. Internal typed
variant names (0d) do not block on it.

### Phase 8 — peerspeak integration
- `EchoCancelGuard::module_index()` accessor (currently private; only `source_name()` /
  `sink_name()` exist).
- **Emit the public mode flag** when the new picker choice is selected. Gated by an **exact
  new/new argv golden** that requires *both* the mode flag and `--aec=…` to be present — the
  round-3 P1. An argv test that checks only `--aec` passes while the mode flag is never sent and
  pixelpass silently runs legacy capture.
- Always pass `--aec=off|pulse-module:<idx>` — absence is not a protocol state (D5).
- **Bind capability to the resolved binary path**; re-probe immediately before constructing
  new-mode argv if resolution differs from the probe's; fail closed. Closes the `:3375-3378`
  vs `:3409-3419` double-resolution gap.
- **New-peerspeak + old-pixelpass golden test** (round-2: the phase map promised "both
  directions" and only one was specified) — against an old-capability response and an old fake
  binary: the new picker entry stays absent and **no new flags are emitted**. Path rebinding
  alone does not test the failure policy.
- Parse and surface the Phase 6 status events, with a **causal** test: an event emitted by
  pixelpass must reach the UI. Matching enums defined independently in both repos would
  otherwise pass. The notice channel is currently created only when `audio_app` is set
  (`core/mod.rs:3424`) and only the two `AppAudio` events are translated (`:3431-3434`);
  everything else is logged and lost — so the new mode needs its own channel creation path.
- Capability-gated picker entry; wording per v3.4 §11.
- Regression: existing `--app` / `--strict-audio` argv byte-identical to today.

---

## 7. Phase 9 — rig upgrade and field tests 🚦 SHIP GATE

v3.4 §9.2's rig upgrade is **owed before any exclusion claim is published**: two orthogonal
PN/MLS probes, windowed per-channel normalised cross-correlation reporting max per-window
correlation, plus xrun telemetry. Until it exists the only defensible claim is the gross-leak
distinction, in v3.4 §9.2's exact wording.

**Every row gets a declared pass/fail threshold before the run, not after.** Baseline for all
rows: excluded probe ≤ the declared rig criterion; **eligible control audio present**; original
playback routes intact; zero surviving owned links or capture sinks after teardown; xrun and CPU
within recorded bounds.

The **full** v3.4 §12 matrix — v1 silently dropped rows 2 and 7:

1. Sharer in a call while sharing, AEC on **and** off.
2. **Sharer simultaneously viewing another share while sharing** (restored). Highest-value test
   of the child-tag path: mpv playing a watched share while hosting. Reachable —
   `StartScreenShare` stores a host at `core/mod.rs:3458`, `ViewShare` stores viewer children at
   `:3525`, no mutual exclusion.
3. Lifecycle, each separately: Stop, room leave, UI crash, pixelpass panic, SIGINT, SIGTERM,
   SIGKILL, last viewer, pipewire-pulse restart, PipeWire daemon restart, `--repair`.
4. EasyEffects running for the whole share.
5. Output-device switch mid-share via the real `Ctrl+Meta+F` / `Ctrl+Meta+S` scripts.
6. Two concurrent hosts; notification mid-share; app that starts playing after the share.
7. **Sample-rate / channel / passthrough behaviour on real sinks, and CPU cost** (restored).

⚠️ **Mid-share taint-root arrival — v3.4 §6.1.4 names an unreachable case, and so did my first
replacement.** v3.4 says "AEC-load-mid-share is the case to test": unreachable, because there is
exactly one `echo_cancel::enable` site at session join (`core/mod.rs:1850`), the guard moves
into `ActiveSession` at `:2729`, and `StartScreenShare` rejects `active_session == None` at
`:3397-3404` ("Join a call before sharing your screen") — so the AEC always predates the share.
My proposed replacement, "a peer joining creates their playback node," is **also wrong**:
peerspeak starts **one mixed playback stream** at session construction (the sole core
`start_playback`, `core/mod.rs:1900`), and `PeerJoined` (`:2396-2409`) only admits and connects
the sender. No per-peer node is ever created.

The reachable newly-created mid-share taint roots are: **a notification sound played mid-share**
(`notify.rs:265-272`), and **starting to view another share mid-share**, which spawns a tagged
mpv/VLC (`screenshare/mod.rs:768-775`). Those are the transition-window field tests. Owned-AEC
mid-share load stays a **synthetic** test until a second `enable` site or hot reload arms it.

---

## 8. Open questions — final status

| # | Question | Status |
| --- | --- | --- |
| O1 | Is 0c a true blocker? | **CLOSED — yes, no demotion path.** The *echo* argument for demoting it is sound and irrelevant: D6 settled it. Balloon ⇒ round 8. |
| O2 | Ship the dry-run mode? | **CLOSED — keep**, env-gated, stable reason codes + epoch + serial, stderr or defined JSON event so `--output json` stays clean. |
| O3 | Naming | **SPLIT.** The `peerspeak.owned` wire literal is pinned in plan §3 now (a contract, not product wording). Public mode/picker wording remains the **user's call**, blocking at the start of Phase 7 only. |
| O4 | Sticky state: engine or observer? | **CLOSED — pure engine.** Observer supplies lifetime-bearing membership/removal facts; the engine decides. |
| O5 | Is full recompute really fine? | **CLOSED — measure it in Phase 5**: duration distribution, maximum, and queueing, not a recompute count. |
| O6 | Can the default-monitor fallback be made structurally impossible? | **CLOSED — yes, but it took two closures, not one.** Source path *and* sink-input path, both in 0d. Placement 0d rather than Phase 6 was my divergence; Codex agreed in round 2 with the added constraint `0c → 0d`. |
| O7 | Does over-exclusion need its own gate? | **CLOSED — subsumed.** Codex correctly narrowed my premise: an exclude-everything build already fails the eligible controls in six Phase 5 rows *provided they are asserted*. Fix is the exact-partition requirement (plan §5.1) plus link-matrix row 9's positive capture assertion. |
| O8 | Runtime assertion for "no source switch on failure"? | **CLOSED — 0d's enum is insufficient.** It stops a `DesktopExcluding` value containing `DefaultMonitor`, not a failure handler swapping the whole plan for `LegacyDesktop`. Release-mode integration test per failure transition (link-matrix row 8); `debug_assert!` in addition, but it is not the gate. |

---

## 9. Risk register

| Risk | Where it bites | Mitigation |
| --- | --- | --- |
| Engine correct, **source** wrong | full echo, engine bypassed | 0d path 1 — typed capture plan |
| Engine correct, **sink inputs** poisoned | full echo, no source switch anywhere | 0d path 2 — bare sink type + conflict rejection + graph assertion |
| Taint engine subtly wrong about real PipeWire | Phase 6 leaks the call into the share | Phase 5 exact-partition gate with negative controls |
| Unsafe link exists briefly, then is cleaned up | a real leak that "eventual cleanup" tests score as a pass | link-matrix row 1: zero unsafe `create_link` calls |
| Link manager built before the engine is validated | same, discovered in front of a viewer | strict DAG; plan §0's stated temptation |
| Tag literal mismatch across repos | v3.4 §5.1 silently does nothing, *quietly* | literal pinned in plan §3; cross-repo black-box test; consumption gated in Phase 5 rows 4–6 |
| Cross-repo skew | share hard-fails on spawn | pixelpass-first; a golden test in **each** direction; capability bound to resolved path |
| Fail-closed with no explanation | user switches back to unsafe whole-desktop audio | causal status-delivery test, Phase 6 → Phase 8 |
| Over-exclusion ships as "working" | mode captures silence, all gates pass | exact partitions (plan §5.1) + link-matrix row 9 — **🟢 FIRED 2026-07-25 and worked**: the build *was* the exclude-everything degenerate case, and the empty eligible half is what exposed it |
| **A property the engine reads is silently absent at the observation boundary** | engine correct, context permanently `None`; fails in *both* directions at once (F1: no taint root ⇒ echo; F2: no owner key ⇒ exclude everything) | **v3.5 §6.7 — never read node/device props off a registry global.** Phase 3r's live prop-recovery gate asserts each one arrives. General form: `pw-dump` is a **bound** view; the registry is not, and the difference is silent |
| Wrong pipewire-pulse PID | mass over-exclusion from a correct engine on a wrong context | Phase 3 PID-derivation matrix |
| 0c balloons | prerequisites eat the schedule | reopen D6 as round 8 — no silent waiver |
| "It works on my box" | the only box is this box | two-machine field test is the ship gate |

## 10. Adjudication record

**Round 14 (2026-07-26) — 0b's five-mutation matrix is revised to four, and one pinned
mutation is retired as vacuous.** Reached independently by both reviewers, then agreed.

- **Mutation 2 cannot be killed by any test, because its site cannot execute.** The
  best-effort wake arm (`core/mod.rs`, the `besteffort_wake_rx` close arm) is unreachable
  **by construction, twice over**: (i) `run_core_loop` owns a clone of `besteffort_wake_tx`
  — created at `CoreController::new` and used for the `has_more` re-arm inside the loop —
  and a tokio `Receiver::recv()` yields `None` only once *every* sender is dropped; (ii)
  even without that clone, both `CoreController` and `CoreCommandSender` hold `reliable_tx`
  alongside the wake sender, and the `select!` is `biased` with the reliable arm first, so
  the reliable arm always wins the race to exit. Writing teardown there would be code that
  provably never runs, dressed as a tested path.
- **Mutation 1's site is reachable but not unit-testable.** It sits inside `run_core_loop`,
  which builds a real iroh endpoint and loads identity; no unit test can drive it.
- **Decision: (b) + (c).** Teardown is **hoisted to one unconditional site after the loop**,
  so every `break` is covered structurally, including any added later — strictly better than
  duplicating teardown across one live arm and one dead one. The **seam-level mutation gates
  are the real ordering proof**, and the call site's live proof is owed to **phase 9**, which
  gains an explicit row: *drop the controller / close the command channel while sharing*.
  "UI crash" is not precise enough to serve as that row.
- **Rejected: an integration test built to preserve the number five.** It would pay for a
  full iroh core plus test-only observability and prove only that a method was called — not
  the ordering invariant, which is the thing that actually breaks.
- The 0b gate is therefore **four mutations**, enumerated exactly (round 16 P3-5 — the earlier
  wording said "three plus the 0c pair", which reads as five and blurred what 0b owns):

  | # | mutation | killed by | status |
  |---|----------|-----------|--------|
  | 1 (old gate 3) | remove the wait after the host kill | `explicit_shutdown_reaps_the_host_before_the_aec_can_unload` | killed now |
  | 2 (old gate 4) | reverse `ScreenshareTeardown`'s field declaration order | `the_aec_unloads_after_the_children_on_the_drop_path` | killed now |
  | 3 (old gate 5) | remove the reap loop from `ReapOnDrop::drop` | `dropping_a_guard_kills_and_then_reaps_the_child` | killed now |
  | 4 (old 1) | remove the teardown at the hoisted post-loop call site | — | **deferred to the phase-9 row** *drop the controller / close the command channel while sharing* |

  4-vs-5 separation verified: reversing the field order leaves the reap test green, and
  removing the reap loop leaves the ordering test green. **0c's own pair (no SIGINT · no
  SIGKILL fallback) is counted under 0c, not here**, along with the round-15/16 additions
  (disarm the wrapper at entry · disarm it between the waits · treat a wait error as a reap ·
  report an unconfirmed stop as clean · zero the grace).

**Round 15 (2026-07-26) — review of the 0b/0c-peerspeak implementation returned two blocking
findings, both accepted.** Recorded because both are the same shape: a defence that existed
but was disarmed exactly when it was needed.

- **The drop fallback was disarmed across its own wait.** `shutdown` took the child out of
  the wrapper before the first `.await`; a cancellation or unwind during the wait left the
  raw child to drop with `kill_on_drop` (which signals without reaping) while `Drop` found
  `None`. The child now stays owned until the reap is **confirmed**.
- **A failed wait was reported as a reap, and the hard-kill wait was unbounded.** The
  `io::Result` was discarded, so a wait error returned "reaped"; and a process in
  uninterruptible sleep after SIGKILL could wedge the core loop forever. Both waits are now
  bounded and the conflict case has a written policy: availability wins, the child stays
  owned so the bounded `Drop` retry stays armed, and the residual risk is logged.
- **A gate of mine was vacuous and the review's fourth test-double point caught it.** The
  elapsed-time assertion compared against `STOP_GRACE` itself, so zeroing the constant left
  it trivially true. `the_grace_is_a_real_interval` now pins the constant to a band.

**Round 16 (2026-07-26) — the re-review of the 0b/0c-peerspeak fixes returned *approve with
follow-ups*: no blocking findings, five P3s, all five applied before the merge.** The two that
carry design content:

- **An unconfirmed stop was reported to the user as a clean one.** `stop_host` returned a bare
  "was sharing" bool, so the one case where availability-first gives up (SIGKILL queued, reap
  never confirmed) still emitted `ScreenShareStopped` with no warning — the UI would say
  sharing ended while pixelpass might still be fanning out. `ReapOnDrop::shutdown` now returns
  `StopOutcome`, `stop_host` returns `Option<StopOutcome>`, and an `Unconfirmed` user-initiated
  stop raises a UI error naming the stray process. Session/viewer teardown discards the outcome
  on purpose: no user is waiting on an answer there and the risk is already logged.
- **Cancellation coverage only reached the graceful wait.** The mid-wait test could not kill a
  mutant that disarmed the wrapper *between* the two waits. Verified: the naive form of that
  mutant does not compile (the child is borrowed from `self`), but the restructured form —
  `self.child.take()` once cooperation has failed — compiles, and the pre-existing test passes
  it. `cancelling_shutdown_after_the_kill_leaves_the_fallback_armed` kills it.

**Deferred item — aggregate teardown latency (round 16 P3-4).** Bounds are per child, not per
teardown. Sequential drain gives `2 × STOP_GRACE` per unconfirmed child inline (≈4 s), plus
`REAP_BUDGET` (250 ms) per child on the `Drop` path: three wedged children ≈6 s of command-loop
stall, ≈12.75 s worst case including drop retries. Accepted as-is for 0b — one host plus one or
two viewers is the real shape, and concurrency here would mean detaching children from the
session that owns the AEC's lifetime. **Trigger to revisit: a fourth tracked child becomes
routine, or a measured teardown exceeds 5 s.** The fix, when triggered, is to drain viewers
concurrently while still owned by `shutdown_children` — not to detach them.

**Round 17 (2026-07-26 night) — two reviews: the repair planner (changes-requested, all applied)
and the 0c actor design (four blocking issues, all accepted).** 0c is now sliced, because the
fault-handling surface — not the design — is what grew.

*The repair planner: no P1s, four reachable P2s and a P3, all applied in `9145b2a`.*

- **Only the canonical forms are ours.** `classify` recognised any loopback with one
  pixelpass-looking endpoint, so a third party's `module-loopback source=some_mic
  sink=pixelpass_capture_4242` was ours to unload once that pid died; and a `sink=` token nested
  inside a quoted `sink_input_properties` value could be read as a top-level argument. The whole
  recorded argument string must now equal what pixelpass itself writes.
- **The matcher's templates are generated from the loader's own renderers.** Hard-coding
  `latency_msec=20` beside a matcher means a loader change silently blinds repair to every module
  the new build loads — the fail-closed-and-silent class this project has now been bitten by
  three times (F2, F13-1, the sticky-uncertainty inversion). `host/audio.rs` loads through the
  same renderers, so drift is a compile-time question. Blindness is also *reported*:
  `unrecognised_pixelpass_modules` names anything matching `pixelpass_capture_*` that no
  canonical form recognises, so a newer pixelpass's shapes cannot make an older `--repair`
  quietly clean up nothing.
- **Ordering is not a licence either.** Planning loopbacks before the sink is necessary and
  insufficient: an unload can fail or be skipped, and a loopback can appear after planning. The
  sink unload is now gated on `sink_still_referenced` against the fresh snapshot — any other
  module naming that sink blocks it, ours or not, because the question is what would break rather
  than who owns it.
- **Undecidable is not dead.** `Path::exists()` maps a permission error, a missing `/proc` and a
  foreign pid namespace all to `false`, which read here as "dead, unload it". Liveness is now
  `Alive | Dead | Unknown` via `try_exists()` behind a `/proc/self/stat` preflight, `Unknown`
  behaves exactly like `Alive`, and it is reported separately so holding back is visible.
- **⚠️ One prescribed fix was not implementable as written, and measuring first is what caught
  it.** The reviewer's fix for fingerprint fidelity was "use `pactl -f json list modules` and
  deserialize the complete `argument`". **On pactl 17.0 those records carry no module index at
  all** (`"index": null`), and `unload-module` accepts only an index — JSON alone cannot drive
  repair. Replacement: **two listings, correlated positionally and checked** (ids and names from
  the short listing, exact arguments from JSON; equal counts and equal names at every position or
  the run refuses, with retries for a concurrent load). Verified on this host: both listings
  return the same 17 modules in an identical name sequence, from 41 physical lines. The check
  also turns the reviewer's fabricated-row attack from exploitable into harmless — a crafted
  short-listing line has no JSON counterpart, so the sequences misalign and repair stops instead
  of unloading an index inferred from text. *This is the reachability rule applied to a
  prescription rather than a finding: the chain was valid, the API it assumed did not exist.*
- **Measured before relying on it (pactl 17.0, live server):** recorded arguments come back
  byte-for-byte as passed, joined with single spaces, in order, and **`@DEFAULT_SINK@` is not
  resolved** to the concrete device. Both facts are load-bearing for exact matching — had either
  been false, the P2 fix would itself have been a silent blinding — so both carry a test.
- Normalisation deleted (P3): within one invocation every snapshot comes from one server, so
  re-rendering does not happen and normalising only made different arguments compare equal. The
  residual ABA window (planned module vanishes, a byte-identical one takes its index) cannot be
  closed through an index-only unload API, and is now stated as a limitation in `Fingerprint`'s
  own doc comment instead of implied away.
- Five vacuity gaps closed: a raw-pactl-text-to-plan test (the whole planner suite survived a
  parser that dropped every argument), per-pid liveness counters over two pids, non-canonical and
  nested-quote cases, and a reference-gate test. **One gap deliberately left open and declared:**
  a comparator using only `id + args` cannot be killed by a non-vacuous test, because the module
  *name* determines which argument grammar can match at all — that field is enforced structurally
  by `classify`, and a test appearing to cover it would be the self-satisfying kind.
- **Field-verified twice on the live graph:** the A/B orphan test still removes exactly the two
  orphans with the module table otherwise byte-identical, and a new fixture — a dead pid's legacy
  sink plus a *non-canonical* loopback naming it — unloads nothing, reports the unrecognised
  module, and reports the sink as still referenced.

*The 0c actor design: four blocking issues, all accepted; the epoch requirement conceded.*

- **A bounded join must not move the OS handle into `spawn_blocking`.** My ladder would have
  taken the thread handle out of the guard to poll it; if the close future is then cancelled or
  unwinds, `Drop` finds no handle and can neither poison nor fail-stop, while the blocking task
  stays wedged forever and can pin runtime shutdown. This is the **same defect shape as round
  15's** — a defence disarmed exactly when needed. The handle stays owned across every await;
  `is_finished()` is polled and `join()` called only once it reports finished. Same rule for the
  event task's handle (`await` through `&mut JoinHandle`).
- **`Commit::UnloadNow(id)` cannot forget the id.** An immediate unload can time out or be
  cancelled, and a ledger that never recorded the module cannot retry or reconcile it. Slots
  become a state machine — `Vacant | Loading { token, expected } | Loaded { fp } | Unloading
  { fp }` — with **affine** permits carrying a unique token, so two permitted loads for one slot
  cannot both commit.
- **`kill_on_drop` does not roll back a server-side mutation.** A bounded `pactl load-module`
  killed after the server created the module but before its id was read leaves a module with no
  id anywhere. So an ambiguous load requires **bounded reconciliation by fingerprint** — reusing
  repair's classification idea inside the live session, never its dead-pid policy — before any
  further capture may start. Related: cancellation must never be `select!`ed against
  `Command::output()`, or a completed load's id is dropped on the floor.
- **`_exit` is right, but the pre-exit sequence must not be able to block.** Event emission,
  stdio flushing and tracing all take locks a wedged thread may hold, so the watchdog able to
  `_exit` past a stalled diagnostic has to be **armed before** the wedge is detected, not created
  in response to it. And `_exit` skips `CaptureHandle::Drop`, so `gst-launch-1.0` and any
  in-flight `pactl` need parent-death/process-group containment or they outlive the host that
  reported its own death — with gst still holding screen-capture resources.
- **Epoch conceded, and my vacuity instinct was right.** `object.serial` is unique and never
  reused while global ids are, so "the object at this id still has the serial I recorded" is
  complete proof of identity; there is no same-core interleaving that serial equality misses.
  Epoch is carried for diagnostics and explicitly **not** a gate. It would only become
  load-bearing across a daemon incarnation or an actor reconnect, and the design makes core
  failure terminal with no reconnect — if that changes, the right answer is a core-incarnation
  nonce, not a "something churned" counter that invalidates observations on unrelated traffic.
- **"Unjoinability, not slowness" is not literally implementable** and the wording is corrected:
  no bounded observation distinguishes "returns one millisecond later" from "never returns", so
  the death condition is *failure to terminate within the post-cancellation policy deadline*.
  Two budgets, not one — a running MainLoop quitting is a different question from an
  initialisation call returning after cancellation, and the second is normally longer.
- **`GraphCmd::Route(Vec<u32>)` is deleted rather than fixed.** Matching and routing stay inside
  the actor's registry callback, where removals are already ordered against routes in-thread, so
  the privacy race is not introduced at all. For phase 6 the rule is structural: the only
  addressable type is an `ObservedNode { global_id, serial, epoch }` constructible solely from
  the actor's own observation, kept private and non-`Copy`, revalidated on serial immediately
  before any mutation. A bare id is not addressable.
- **An unacked `ClearRoutes` is not a wedge** (agreed), with one qualification taken: a stream
  setting `node.dont-reconnect`/`node.dont-fallback` may be left silent rather than moved back to
  the default, so the outcome is surfaced as `ClearRoutesUnconfirmed` rather than treated as
  benign. Separately, blindly clearing `target.object` can erase a target the user set manually —
  the prior value must be recorded and restored only while it is still pixelpass-owned.
- **One terminal fault needs a coordinator, not an emitter.** If the actor emits `CoreError`
  immediately and the subsequent teardown then fails to join, peerspeak never learns the process
  is fail-stopping. Actor faults are internal *candidates*; the tokio-side coordinator emits
  exactly one final fault, and `Wedged` overrides any earlier candidate. Because a callback panic
  can cross `extern "C"` and abort before any event is produced, **peerspeak must treat
  unexpected stdout EOF as a synthetic terminal fault** rather than trusting that a JSON line
  arrives.

*Measured for the actor argument (3 of 3 trials, live graph):* pipewire-pulse accepts **two sinks
with an identical `node.name`** — no rename, no suffix, no refusal, both visible as `<name>` and
`<name>.monitor` — and `pulsesrc device=<name>.monitor` attached to the **older** one every time.
So a surviving wedged owner does not merely risk a collision: it **silently steals the next
session's capture** while the loopbacks feed the new sink. That retires "detach and carry on" as
an option, and it is the evidence behind rejecting session-unique sink names (which would trade a
fail-stop ownership fault for silent accumulation, and re-open the discovery grammar 0c step 1
just closed and field-proved).

**0c step 2 is therefore sliced, and the slices land and are reviewed independently.** Nothing
here reopens D6 — the connection-owned-sink design is unchanged; what grew is the process-
lifecycle and fault surface, and a material part of it is pre-existing debt 0c forced into the
light (the `abort()` orphan race, the unbounded join, peerspeak advertising a dead share):

| slice | scope | why it can land alone |
|-------|-------|-----------------------|
| S1 | repair planner (`919d5bd` + `9145b2a`) | done; awaiting re-review, then merge |
| S2 | peerspeak host-fault path: always-on notice channel, EOF synthesis, session-scoped fault, clear `is_sharing` + presence ticket, `ScreenShareStopped` then error | fixes a defect **today** — a dead share stays advertised — and is independent of the actor |
| S3 | pixelpass ledger transactions + ambiguous-load reconciliation + child containment + pre-armed watchdog + poison state machine + supervisor health arm | fixes the `abort()` orphan race **today**; no libpipewire work |
| S4 | the `AudioGraphOwner` actor itself, the readiness handshake, and both measured budgets | the only slice that needs new PipeWire mechanism |
| S5 | the two live exit gates: two-host ownership, and the never-yet-run Stop Share SIGINT gate | needs S4 on the graph |

**Round 18 (2026-07-26 night) — two more repair review rounds. `--repair` now reads and unloads
through libpulse, and one of the review's own prescriptions had to be replaced after measuring.**

*Round 17c — the re-review of my round-17a fixes found two more blocking P2s. Two of the four
fixes I had applied were themselves defective; this is the third time the "audit your own fixes"
rule has paid.*

- **My two-listing correlation was unsound.** Pairing short-listing indices with JSON arguments by
  position breaks whenever module names repeat: another client loading one module and unloading
  another *between the two calls* leaves counts and names aligned while every argument has shifted
  by one, so a foreign module inherits a canonical fingerprint. The name check cannot see it and
  the retry never fires, because correlation "succeeded".
- **My liveness fix still converted invisible-but-alive into dead.** A `/proc/self` preflight
  proves nothing: inside a pid namespace — a container, a distrobox — `self` stays visible while
  every process in the parent namespace is invisible, and `hidepid` has the same shape.

*Round 18 (round 4) — the fix for both, and a third defect neither of us had reached.*

- **Record boundaries in `pactl list short modules` are unprovable, and this needs no adversary.**
  A genuine module whose argument contains a newline renders a first line that is byte-exactly one
  of our canonical forms, with the rest dropped as an unparseable continuation — no forged index,
  so no duplicate-index check can see it. **Field-confirmed on the live server** with
  `…latency_msec=20\nremix=false`, `remix` being a real loopback option. A tab in the same position
  is worse: it hides a sink reference from the gate that protects a still-referenced sink.
- **Locality was a guess.** `PULSE_SERVER` is a fallback *list*, so `unix:/missing tcp:remote:4713`
  passes any "starts with unix:" test and then connects to another machine, where local pids mean
  nothing and a live remote host's modules look dead.
- **Resolution: `src/repair/introspect.rs`, one verified-local connection.** `pa_module_info`
  carries index, name and exact argument in a single record; `pa_context_is_local()` answers
  locality about the connection actually established; and unloading goes back through that same
  connection, so listing and destruction cannot disagree about which server they mean. Bounded
  throughout (3 s connect, 3 s per request, non-blocking iteration plus a 2 ms sleep). The layer
  holds no policy but "refuse the wrong server" — every decision stays in the pure planner.
- **The dependency was the user's call, taken with sign-off after vetting.** libpulse-binding
  2.30.1: MIT/Apache-2.0, 5.5M downloads, 3 new crates total, a build script that only probes
  pkg-config, no network or subprocess use in any source, and all three historical RustSec
  advisories (2018-0020/0021, 2019-0038) fixed by 2.6.0. Reasoning recorded beside the dep.
- ⚠️ **REUSABLE — a prescription can fail reachability, not just a finding.** The reviewer's
  fidelity fix was "use `pactl -f json list modules`". On pactl 17 those records carry **no module
  index at all** (`"index": null`) while `unload-module` accepts only an index, so it can never
  stand alone. Measuring first is what caught it.
- ⚠️ **REUSABLE — the field test found a bug no unit test could reach, and it was 0b's bug again.**
  The first introspection version did its work correctly and then aborted on the way out:
  `Assertion '!e->dead' failed at mainloop.c:207, function mainloop_io_free()` — SIGABRT, core
  dumped, **exit 134, so a fully successful repair reported failure to its caller**. Rust drops
  fields in declaration order and the context's teardown frees IO events living in the mainloop,
  which I had declared first. Fixed, then hardened past the fix: `Drop` explicitly takes and
  destroys the context before the mainloop, so the ordering no longer depends on where the fields
  are written. **Field-order drop hazards are not a peerspeak-specific lesson; they recur wherever
  one object's teardown reaches into another's.**
- **Still open, deliberately, and recorded rather than guessed:** closing the namespace hole needs
  modules to carry an **owner token** (machine/boot identity plus pid-namespace identity), with
  token-less modules treated as `Unknown`. That changes what pixelpass writes into the graph *and
  how far back `--repair` can clean up* — orphans from any older build would become uncleanable,
  which is a regression in the tool's entire purpose. `NSpid > 1` remains a sound negative signal;
  `NSpid == 1` is explicitly **not** proof, since its leftmost value is relative to the procfs that
  was mounted.
- **Deferred, now cheap to reconsider:** `host/audio.rs` still loads modules via `pactl` and parses
  the index off stdout, which is part of why S3's ambiguous-load problem exists. With libpulse in
  the tree, `pa_context_load_module` returns the index through an observable operation.

**Round 1 — 13 items, 12 accepted.** Phase reorder (AEC machine before dry-run); typed capture
plan (accepted, moved *earlier* than proposed); Phase 3 five-part gate; tag-consumption gating;
Phase 6 matrix mandatory; 0b unwind backstop restored **and my mutation test corrected — it
targeted the wrong mutation**; Phase 9 rows restored with pre-declared thresholds; DAG stated;
O1 demotion language removed; 0c two-host gate; skew tests moved to Phase 7; status events
assigned. **Half-rejected:** "the Sunshine topology is unverified and unnecessary" — *unverified*
was right and it has since flipped; *unnecessary* rejected, retained as non-gating row 1b.

**Round 2 — 11 items, all accepted.** The three that mattered:

- **P1, the sink-input path.** My 0d closed the source and left the capture sink's inputs open;
  `PIXELPASS_AUDIO_VIA_NULL_SINK` + `Routing::start` would have filled the owned sink with the
  whole-desktop mix and produced full echo with no source switch. This is the "at least one
  comparable error" I asked round 2 to find, and it was in the fix for round 1's headline P1.
- **P2, my v3.4 §6.1.4 replacement was also unreachable.** I claimed a peer joining creates their
  playback node; verified false — one mixed playback stream at session construction
  (`core/mod.rs:1900`), `PeerJoined` only admits the sender. Replaced with notification sound and
  watched-share start, both reachable.
- **P1, no invocable production selector**, so Phase 6's "production path" measurement would have
  run through a harness. Internal mode input moved into 0d.

**Round 3 — verification pass, 5 items, all accepted.** It confirmed 4 of the 7 round-2 edits
landed and 3 were partial, which is the reason to run a verification round at all rather than
declaring the fixes done. The one that mattered:

- **P1, the public mode selector was never assigned to any phase.** 0d added a hidden trigger,
  Phase 7 added capability + naming, Phase 8 added `--aec` — and nothing required the mode flag
  itself to exist publicly or be passed. A capability-gated picker entry would have appeared and,
  when chosen, spawned legacy whole-desktop capture: the feature shipping while doing nothing,
  with the echo intact. Fixed in Phase 7 (flag) and Phase 8 (emission + new/new argv golden).
- Three link-matrix rows I had just written were insufficiently falsifiable — a combined
  exclusive/encoded/passthrough fixture (one working predicate masks two missing), "relink
  attempted" (a permanently-failing attempt passes), and an unenumerated "any failure path".
  Split into 6a–6c, a success assertion, and 8a–8e.
- Status delivery was gated by one generic causal test that passes while three of the four
  events stay unwired. Now four exact JSON goldens with named triggers.
- `0b` was drawn in the DAG with no outgoing edge; it now explicitly precedes Phase 6.

**Codex's positions I narrowed:** it agreed the Sunshine sample is worth keeping as non-gating,
and corrected my wording — the topology appears when Sunshine *routes desktop audio through its
null-sink topology*, not merely whenever Sunshine is running, since I measured it running
without that topology. It also correctly narrowed O7's premise (an exclude-everything build does
already fail six rows' eligible controls, *if* asserted) while agreeing the exact-partition fix
is right.

**Verified by me before accepting:** the single `default_audio_monitor` call site
(`pipeline.rs:138`); the double binary resolution (`core/mod.rs:3375-3378` vs `:3409-3419`); the
no-session guard on `StartScreenShare` (`:3397-3404`); the sole core `start_playback` (`:1900`)
and `PeerJoined`'s scope (`:2396-2409`); and the current default-sink/Sunshine graph state.

## 11. Corrections owed to the design doc — ✅ APPLIED in v3.5 (round 8, 2026-07-25)

Both are now in the design doc (§6.1.0 and §6.1.4 respectively), alongside round 8's own
finding (§6.7, the observation boundary). Kept here as the record of what was owed and why:

1. **v3.4 §6.1.0's "🔴 the hazard is LIVE on this machine right now" is time-dependent and has
   already flipped.** Measured 2026-07-21 ~14:55 (details in plan §5.3). The reachability
   argument is unaffected — the topology appears **when Sunshine routes desktop audio through
   its null-sink topology**, which is narrower than "whenever Sunshine is running," since it was
   measured running without it. Nothing should gate on its presence.
2. **v3.4 §6.1.4's nominated test case is unreachable, and so was my first replacement.**
   Details in plan §7. The conclusion (the transition window exists only for newly-created
   roots) stands; the example must become the notification sound or watched-share start.

## 12. Not in this plan

**Round 8 additions:** **port binding** (so `port.exclusive` is never observed — plan §4 "Phase
3 revision" item 6, with its revisit trigger), **per-node quarantine** (an unresolvable node
bind fails the whole readiness epoch closed instead of isolating that one node — v3.5 §6.7
decision 3), and the **serial-continuity signal** for the AEC validator's no-coalescing
contract (phase 4's owed F4 hardening).

Everything v3.4 §14 lists as out of v1 — port-granular taint, timed drain, hot-AEC-reload epoch
protocol, native PipeWire AEC, incremental dirty-set, seamless daemon-restart recovery — plus
v3.4 §10 items 2 and 3 (per-app debt; D6 says they do not block Option C), the v3.4 §5.1
grandchild leak, and the general "AEC binds to the default sink when no device is pinned" defect
(v3.4 §6.1.0, resolved for this user, own task).