<feed xmlns='http://www.w3.org/2005/Atom'>
<title>archsetup/docs/specs/2026-07-09-audio-doctor-spec.org, branch main</title>
<subtitle>Builds a full dev workstation from a bare Arch Linux install.
</subtitle>
<id>https://git.cjennings.net/archsetup/atom?h=main</id>
<link rel='self' href='https://git.cjennings.net/archsetup/atom?h=main'/>
<link rel='alternate' type='text/html' href='https://git.cjennings.net/archsetup/'/>
<updated>2026-07-09T22:57:29+00:00</updated>
<entry>
<title>docs: close the audio-doctor decisions, spec is READY</title>
<updated>2026-07-09T22:57:29+00:00</updated>
<author>
<name>Craig Jennings</name>
<email>c@cjennings.net</email>
</author>
<published>2026-07-09T22:57:29+00:00</published>
<link rel='alternate' type='text/html' href='https://git.cjennings.net/archsetup/commit/?id=186b27d3ab10ffa40fff8103f35bf1226e05ab3a'/>
<id>urn:sha1:186b27d3ab10ffa40fff8103f35bf1226e05ab3a</id>
<content type='text'>
All eight decisions resolved. DOCTOR is a section-header key; CLI-first with
the GUI as a face; hung and dead are two verdicts sharing one remedy; the
remedy tiers stand as drafted; a stream-active guard refuses the audible
remedies and is overridable by pressing again; xruns stay out of v1.

Two consequences the questions did not make obvious. Taking the guard is what
lets the pipewire-pulse restart stay at Confirm — the danger lives in the state
of the machine, not the identity of the remedy. And the guard must read stream
state from pw-dump rather than pactl: the remedies it protects are the ones you
reach for when the Pulse layer is dead, so a pactl-fed guard would go blind
exactly when it is needed.

Tier 4 drops its xrun probe to match the decision, rather than leaving the
probe list contradicting the answer.
</content>
</entry>
<entry>
<title>docs: correct the audio-doctor spec's timeout claim, close Phase 0</title>
<updated>2026-07-09T21:29:48+00:00</updated>
<author>
<name>Craig Jennings</name>
<email>c@cjennings.net</email>
</author>
<published>2026-07-09T21:29:48+00:00</published>
<link rel='alternate' type='text/html' href='https://git.cjennings.net/archsetup/commit/?id=05696bb71d4eec5404263ae950426fb199323048'/>
<id>urn:sha1:05696bb71d4eec5404263ae950426fb199323048</id>
<content type='text'>
The draft said build_status had no pactl timeout and froze the panel. Driving
it disproved that: pactl.run defaults to timeout=8 and raises PactlTimeout, so
the panel degrades.

The real defect was narrower and is now fixed. Two of build_status's four reads
sat outside its degrade guard, so a server that answered the device lists and
then stopped answering raised out of a function contracted to return ok:False,
and waybar's audio module died rather than dimming.

Corrected in place with the reasoning, rather than dropped, since a spec that
quietly loses a wrong claim teaches nothing about why it was wrong.
</content>
</entry>
<entry>
<title>docs: spec the audio panel doctor</title>
<updated>2026-07-09T21:09:11+00:00</updated>
<author>
<name>Craig Jennings</name>
<email>c@cjennings.net</email>
</author>
<published>2026-07-09T21:09:11+00:00</published>
<link rel='alternate' type='text/html' href='https://git.cjennings.net/archsetup/commit/?id=3cf92e272426e72a1be7b60fa8d1ad9b2416ece2'/>
<id>urn:sha1:3cf92e272426e72a1be7b60fa8d1ad9b2416ece2</id>
<content type='text'>
Answers the four questions the request asked, from a live survey rather than
from memory. There is no PulseAudio: the stack is pipewire, wireplumber, and
pipewire-pulse, all user-scope, so no remedy in this feature needs sudo — which
is why it mirrors the net panel's doctor rather than the maintenance console's
privileged verb table.

Two findings shape the design. pactl hangs against a server that accepts and
never answers, which is exactly the fault a doctor exists to diagnose, so every
probe is bounded. And the panel cannot diagnose itself, because pactl is the
layer most likely to be down — the probes read systemctl and pw-dump before
they touch it.

Filed the panel's own missing timeout as a separate bug. It freezes the audio
panel today, independently of any doctor.

Seven decisions left open; the spec is DRAFT and nothing gets built until they
close.
</content>
</entry>
</feed>
