Skip to content

capture: the e2e runs on a PipeWire of its own, no hardware in it - #796

Merged
napkinstack-agent[bot] merged 7 commits into
mainfrom
capture/e2e-private-graph
Nov 14, 2026
Merged

napkinstack-agent[bot] merged 7 commits into
mainfrom
capture/e2e-private-graph

Conversation

@kitokey-marc

@kitokey-marc kitokey-marc Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

capture: the e2e runs on a PipeWire of its own, no hardware in it


Module

modules/capture — exactly one.

  • This pull request touches a single module
  • ⚠️ Cross-module — the cross-module label is required, justification below

Deliverable

Out of cycle: during the attest of #787 (2026-11-13, 13:55–14:03), AirPods connected at 13:59 became the default input of the desktop's graph, and scenarios J, K, L and O started capture on them ("me":"AirPods Pro"): a real microphone opened by the e2e, against ADR-0015 and D66. The audio was not kept (temporary folder removed). Capture's e2e runs are frozen until this is merged.

What it changes

Cause. scripts/e2e.sh ran on the desktop's graph and moved its defaults to devices of its own. It checked them once, at the start: a device that connects during the run, and that the desktop makes the default, is taken by every scenario that follows the default (D31, D41, D66), and by a microphone named and missing (D74, Auto).

Why not the other remedies. Naming the virtual microphone to capture does not hold: capture has no option for the output, a named microphone that is missing falls back on the default (D74), and J, K, L, M and P test following the default itself. Watching the defaults on the desktop's graph narrows the window without closing it: capture follows a new default before a watcher can stop it.

Fix: the established one, a hermetic test graph. The module already runs scenario N this way (scripts/private_graph.sh). The whole e2e now starts its own PipeWire, WirePlumber and pipewire-pulse (for pactl), in a runtime folder of its own, WirePlumber's ALSA, Bluetooth, camera and MIDI monitors off, no session bus. Nothing of the computer's is in that graph, so nothing can connect into it; the desktop's graph is never spoken to, its defaults never moved, nothing to put back. The checks that read the desktop (a microphone in use, sound playing, devices of an earlier run left behind) go: they guarded a graph the run no longer touches.

Sealed off the sound cards (after sam's review). A graph of its own does not keep ALSA from the cards: cpal's ALSA backend may probe hw: or open /dev/snd without PipeWire. The script now re-runs itself in a bubblewrap (bwrap, Flatpak's sandbox, packaged on Fedora, no root): --dev /dev (a /dev of its own, no /dev/snd), --unshare-pid --proc /proc --die-with-parent (its own processes, all ended with it), and --tmpfs over the desktop's runtime folder and /run/dbus (neither the desktop's PipeWire and pulse nor the system bus, so not Bluetooth). Inside, before anything starts: no /dev/snd, aplay -l finds no card, or NOT RUN. A system that refuses the namespace: NOT RUN, exit 77, before anything starts — seen in this session's sandbox. ALSA_CONFIG_PATH is left alone: with no card node, ALSA has nothing to open, and another configuration would change how cpal names the default, which the scenarios judge.

The guard, the whole run long, failing closed: every half second, pw-dump answers within 3 s and not empty (else the run stops), the run's graph holds no device and no source or sink but the run's own kitokey_e2e_*, and no process of the seal (every process there is the run's) holds anything under /dev/snd/ (pcm*, control*). One seen: every capture and the graph's daemon are killed at once; the script itself ends at its next step — a scenario's sleep runs out first, the sound already cut (accepted) — and says e2e: NOT RUN — a real device appeared: <what>, exit 77, as .nstack/handbook/09-platform.md names a run that cannot run here. E2E_INTRUDER=<sink|source|device>:<seconds> brings one not the run's that long after the start: a null sink, a virtual source, and a Device, named intruder_sink, intruder_source, intruder_device. No Device factory runs in the seal without hardware or a bus — the installed SPA ones are api.alsa.{pcm,acp,compress.offload}.device, api.bluez5.device, api.libcamera.device, and api.alsa.enum.udev made none at c78430f — so the device trial's intruder is a PipeWire:Interface:Device added to the guard's own pw-dump answer (a shim first on the guard's PATH, the graph's real dump plus that object once the trial brings it): it tests the guard's :Device branch, not PipeWire's. The trial judges itself: stopped by anything but its intruder, or not stopped, it fails (exit 1) — and at once: its intruder not in the guard's pw-dump within 3 s, the trial's intruder did not appear; there and the run not stopped 3 s later, the guard let intruder_<kind> through. pipewire-pulse's fallback sink auto_null (module-always-sink, loaded by default) is off in the run's graph by pulse.cmd.always-sink = false, the condition its own configuration puts on it: at cb3d698 it stopped every run, the trial included, at the guard's first look.

The desktop's defaults are read before and after the run, outside the seal, and must be the same (none where there is no desktop).

The machine-wide lock stays as it is, outside the script.

Oracle

  • The success criterion was written before the implementation
  • It was seen failing, for the right reason — E2E_INTRUDER=sink:20, source:20, device:20 bash scripts/e2e.sh: each e2e: NOT RUN — a real device appeared: intruder_sink (Audio/Sink), intruder_source (Audio/Source/Virtual), intruder_device (PipeWire:Interface:Device); exit 77, no kitokey-capture left running; a NOT RUN naming anything else fails the trial, exit 1
  • Inside the seal, no card in sight — the run's line Sealed: /dev holds … lists no snd
  • It passes now — nstack e2e capture with nothing intruding: passed, the guard silent, the desktop's defaults the same before and after; a headset connected during that run changes nothing in it

Kind of oracle: end-to-end — the module's own e2e. Not run here: this session's sandbox refuses Unix sockets (socket(): Operation not permitted), so no PipeWire starts in it. The coordinator runs it. Run here, at b660923: the device shim and the guard on a hand-written pw-dump (no intruder: nothing seen; flagged: intruder_device (PipeWire:Interface:Device); without E2E_INTRUDER: no shim); the trial's two quick failures with the script's own restore (sink:1, the intruder never there: FAIL the trial's intruder did not appear: intruder_sink, exit 1 after 4 s; there and not stopped: FAIL the guard let intruder_sink through, exit 1 after 4 s). Earlier: the guard's reading of the graph, on pw-dump outputs written by hand (the run's sink, a capture stream and the dummy driver: nothing seen; a Bluetooth source and card: both named, exit 1; an empty answer and one 5 s late: stopped, exit 1); the stop's path (a marker and TERM during a wait: NOT RUN said, exit 77, in a second); the seal refused by this sandbox's kernel (max_user_namespaces 0): e2e: NOT RUN — this system refuses the run a namespace of its own (bwrap), exit 77, on a copy cut before the scenarios. The test sheet's S1 still names the first head's intruder: its rows are the verifier's.


Review budget

  • Lines changed (excluding generated): 138
  • Files touched: 2
  • Within budget

Contracts

  • No contract affected

Definition of Done

  • Oracle green — see above
  • Lint, format, types — bash -n scripts/e2e.sh; pre-commit's hooks
  • Unit tests — not affected: no Rust changed
  • Affected documentation updated — README.md's e2e paragraph
  • Diff self-reviewed line by line

Test sheet

Verifier: session bfdb23f1-1199-4cda-ab11-22e178326643

# Given · when · then Kind Result Evidence Commit Confirmed
S1 Given this head, when E2E_INTRUDER=sink:20, source:20, then device:20 bash scripts/e2e.sh each runs, then each ends e2e: NOT RUN — a real device appeared: intruder_<kind> (…), exit 77: the expected result, the guard's oracle, not a skip — exit 1 or 0 is a failure — and no kitokey-capture runs after it automated passed The coordinator's three runs at dbd1287 on this machine, one at a time under the lock, its worktree clean at dbd1287 (logs 796-S1{sink,source,device}.log, read by me): each ends e2e: NOT RUN — a real device appeared: intruder_sink (Audio/Sink), intruder_source (Audio/Source/Virtual), intruder_device (PipeWire:Interface:Device), exit=77; the runner's block after each: defaults the same, source-outputs: [], left of the run: [] new /tmp dirs: []. dbd1287 —
S2 Given this head and nothing intruding, when nstack e2e capture runs, then every scenario passes, the guard says nothing, and the desktop's defaults line is the same before and after automated passed The coordinator's run at dbd1287 (796-S2.log, read by me): A to P, 172 ok, 0 FAIL, private graph: passed, e2e: passed, exit=0; no line of the guard (NOT RUN, intruder_); defaults the same before and after, source-outputs: [], nothing left, no new /tmp folder. dbd1287 —
S3 Given a run of S2, when a Bluetooth headset connects to the computer during it, then no "me" nor "device" of the run names it, and the run's result is S2's human only — a real Bluetooth headset connected during a run, on a person's machine not verified —
S4 Given this head, when a run is cut — timeout (exit 124), TERM or INT — then none of its pipewire, wireplumber or pipewire-pulse survives it (pgrep -P on the script before and after), no source-output is left, and its $work (/tmp/tmp.*) and $graph (/tmp/wh-*) are gone automated passed The coordinator's three runs at dbd1287, timeout --preserve-status -k 30 -s <SIG> 90, each cut in E (796-S4{term,int,hup}.log, read by me): TERM exit=143, INT exit=130, HUP exit=129 — the script's own codes, no -k kill (137); after each: defaults the same, source-outputs: [], left of the run: [], new /tmp dirs: []. At 154f34d, timeout left $work and $graph (the finding fixed here). dbd1287 —

Verifier's remarks: The logs are the coordinator's, on this machine, not attested: quoted here, nowhere the team reads them. S1's « no kitokey-capture runs after it » is the runner's left of the run: [], not the script's own check; in each S1 run the guard's stop ends pipewire and record by Killed (SIGKILL), so what record would have kept on TERM is not looked at. The signallers' status swallowed by wait … || true predates this change (#814). S3 is by a person, and no acceptance issue asks it of one.


Summary

DONE
The e2e runs in a bubblewrap without /dev/snd, the desktop's runtime folder or the system bus, on a PipeWire, WirePlumber and pipewire-pulse of its own without hardware; a guard failing closed stops the run, NOT RUN, at a device, a stranger source or sink, anything under /dev/snd held, or a graph that does not answer; the desktop's defaults are compared outside the seal; the README says it.

VERIFIED
bash -n; pre-commit's hooks; the guard's reading on hand-written graphs, an empty and a late answer included; the stop's path in a stripped-down script; the outer wrapper refused a namespace: NOT RUN, 77.

At 92ba771, the cleanup in a stripped-down script under timeout -s TERM|INT|HUP 2: rc 124 each time, a daemon deaf to TERM killed by KILL, none left alive, $work and $graph gone; E2 waits on its signallers' PIDs, not on the daemons (S2 hung an hour in its bare wait at b660923).

ASSUMED

  • WirePlumber on a graph without hardware behaves for L and M as on the desktop's: the same programs, its configuration the packaged one plus the monitors off, as N already runs.
  • pactl set-default-source <sink>.monitor holds under that pipewire-pulse as under the desktop's: the same program.
  • The graph's dummy and freewheel drivers carry no media.class Audio/*; if one does, the guard stops the first run and names it.
  • bwrap --dev /dev gives PipeWire what it needs (/dev/shm added as a tmpfs; memfd needs no node), as Flatpak's runtimes run PipeWire clients; the host allows unprivileged user namespaces (Fedora's default).
  • pw-dump prints a device's type as PipeWire:Interface:Device, as the guard's shim writes it (PW_TYPE_INTERFACE_Device).

NOT VERIFIED
Any run on PipeWire or inside bwrap: neither starts in this sandbox (no Unix sockets, no user namespaces). The coordinator's run is the oracle.

RISKS

  • The guard reads pw-dump twice a second, beside the clock scenarios (G: 5 ms): a busier machine. If G turns flaky, a slower guard is the trade-off — never none.
  • A guard that sees something of the graph's own, not a device, stops every run NOT RUN, naming it: loud, never silent.
  • The desktop's defaults compared after the run fail it if a person changes them meanwhile (a headset connecting may): the line names them.
  • Failing closed, a machine loaded enough that pw-dump takes 3 s (E2's three FLAC encodings) ends the run NOT RUN: loud, never a pass.
  • The guard reads /proc twice a second for every process of the seal: cheap, but beside G as above.

Signals to report

  • I had to look at another module's implementation
  • A kernel or playbook rule got in my way for no good reason
  • A quality gate blocked without improving quality
  • A rule applied by hand would be worth automating

🤖 Generated with Claude Code

On the desktop's graph, AirPods connected during the attest of #787 became
the default input and scenarios J, K, L and O recorded from them. The e2e
now starts its own PipeWire, WirePlumber (no ALSA, no Bluetooth monitor) and
pipewire-pulse, as private_graph.sh does, and never speaks to the desktop's.
A guard reads the graph every half second: a device, or a source or sink not
the run's own, or a sound card held by the run's capture, kills capture and
the graph at once; the run ends NOT RUN, exit 77. The desktop's defaults are
read before and after: the same.

Agent-Session: 14f73956-90b9-46a3-9fcc-52dc45c43948
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kitokey-marc kitokey-marc Bot added the out-of-cycle Work outside the current cycle: an incident, a production defect; justified in the PR label Nov 13, 2026
kitokey-marc Bot and others added 5 commits November 13, 2026 15:32
…ails closed

A graph of its own does not keep ALSA from the sound cards: the run now
starts in bwrap with a /dev of its own (no /dev/snd), its own processes,
and neither the desktop's runtime folder nor the system bus. Inside, no
card must be in sight before anything starts. The guard stops the run
when pw-dump is late or empty, reads every process of the seal for
anything under /dev/snd, and is tried with a sink, a source and a device
(E2E_INTRUDER=<kind>:<seconds>). The desktop's defaults are compared
outside the seal.

Agent-Session: 14f73956-90b9-46a3-9fcc-52dc45c43948
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…guard's trial judged by its intruder

pipewire-pulse loads module-always-sink by default: its `auto_null` sink, in a graph with no
sink yet, stopped every run at the guard's first look, the trial included (S1 at cb3d698
named `auto_null`, not `intruder_sink`). Off by pulse.cmd.always-sink = false, the condition
pipewire-pulse.conf puts on it. With E2E_INTRUDER set, a run stopped by anything but
intruder_<kind>, or not stopped, now fails; the device intruder is named intruder_device.

Agent-Session: 14f73956-90b9-46a3-9fcc-52dc45c43948
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hat proves nothing ends at once

No Device factory runs in the seal without hardware or a bus: `api.alsa.enum.udev`
made none, and the trial went on through the whole run. The device intruder is
now a Device added to the guard's own pw-dump answer. The trial fails within
3 s when its intruder does not appear, or appears and the run is not stopped.

Agent-Session: 14f73956-90b9-46a3-9fcc-52dc45c43948
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… a cut run

E2's bare `wait` waited on every child: the run's graph daemons are the
script's children now, and never end — S2 hung an hour in E2. It waits
on the three signallers by their PIDs.

The cleanup kills pipewire, wireplumber and pipewire-pulse by their PIDs,
with KILL after two seconds, and ignores further signals while it runs:
`timeout` signals the script and then its group, and a second TERM in the
EXIT trap ended the shell before `rm -rf`. INT and HUP end the run through
the same cleanup.

Agent-Session: 14f73956-90b9-46a3-9fcc-52dc45c43948
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The guard's own stop still says NOT RUN, exit 77: it writes "$work.real"
before its TERM, and the cleanup reads it there. Any other TERM — a
runner's timeout, a person — now exits 143, so nothing running e2e.sh
directly reads a cut run as a skip.

Agent-Session: 14f73956-90b9-46a3-9fcc-52dc45c43948
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n leaves none

A run cut by `timeout` ended the outer script by TERM; the sealed one, --die-with-parent,
went by SIGKILL before its restore, and $work and $graph stayed in /tmp (#796, S4). The
outer part now makes both, passes them in (KITOKEY_E2E_WORK, KITOKEY_E2E_GRAPH) and removes
them on its own exit, with the guard's files beside $work. The sealed restore still reads
them first, as before, when it runs.

Agent-Session: 14f73956-90b9-46a3-9fcc-52dc45c43948
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kitokey-marc
kitokey-marc Bot marked this pull request as ready for review November 14, 2026 15:32
@kitokey-marc
kitokey-marc Bot requested a review from a team as a code owner November 14, 2026 15:32

@napkinstack-admin napkinstack-admin left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Capture : l'e2e tourne sur un PipeWire à lui, sans matériel ; garde vérifiée (S1), e2e vert (S2),run coupé propre (S4).

@napkinstack-agent
napkinstack-agent Bot merged commit 3bdac68 into main Nov 14, 2026
15 of 17 checks passed
@napkinstack-agent
napkinstack-agent Bot deleted the capture/e2e-private-graph branch November 14, 2026 16:33
kitokey-sam Bot added a commit that referenced this pull request Nov 14, 2026
e2e.sh's conflicts settled with main's #796 (the run's folders made and
removed outside the seal); E2's signallers judged one by one, as this
branch has it.

Agent-Session: 92ded11e-58ef-492d-ba56-c820b9011de8
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
kitokey-marc Bot added a commit that referenced this pull request Nov 14, 2026
The capture e2e sealed from main: this branch's runs no longer touch the computer's sound.

Agent-Session: 14f73956-90b9-46a3-9fcc-52dc45c43948
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
kitokey-marc Bot added a commit that referenced this pull request Nov 14, 2026
The capture e2e sealed from main: this branch's runs no longer touch the computer's sound.

Agent-Session: 14f73956-90b9-46a3-9fcc-52dc45c43948
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
napkinstack-agent Bot added a commit that referenced this pull request Nov 15, 2026
…r transcription (#832)

Both link C or C++ into their programs under +crt-static — libFLAC, whisper.cpp —, which
windows.yml does not build with: #794's LNK2019 was seen only by a run asked by hand, twice,
and #787, #796, #810, #829 had no run of it. Shell and summary are Rust alone, compiled by
windows.yml on every change, and keep out of it.

Agent-Session: 14f73956-90b9-46a3-9fcc-52dc45c43948

Co-authored-by: kitokey-marc[bot] <356215105+kitokey-marc[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: napkinstack-agent[bot] <330339777+napkinstack-agent[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

out-of-cycle Work outside the current cycle: an incident, a production defect; justified in the PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant