<feed xmlns='http://www.w3.org/2005/Atom'>
<title>archsetup/docs/specs/2026-07-09-audio-doctor-spec.org, branch claude/hungry-franklin-09fffc</title>
<subtitle>Builds a full dev workstation from a bare Arch Linux install.
</subtitle>
<id>https://git.cjennings.net/archsetup/atom?h=claude%2Fhungry-franklin-09fffc</id>
<link rel='self' href='https://git.cjennings.net/archsetup/atom?h=claude%2Fhungry-franklin-09fffc'/>
<link rel='alternate' type='text/html' href='https://git.cjennings.net/archsetup/'/>
<updated>2026-07-10T15:42:58+00:00</updated>
<entry>
<title>docs: spec the audio doctor's input side, one doctor per direction</title>
<updated>2026-07-10T15:42:58+00:00</updated>
<author>
<name>Craig Jennings</name>
<email>c@cjennings.net</email>
</author>
<published>2026-07-10T15:42:58+00:00</published>
<link rel='alternate' type='text/html' href='https://git.cjennings.net/archsetup/commit/?id=ab22b2c935c3679296d86f740fdb09cf9e367670'/>
<id>urn:sha1:ab22b2c935c3679296d86f740fdb09cf9e367670</id>
<content type='text'>
The doctor never examines the microphone. diag collects default_source and default_source_present, the classifier reads neither, so a muted mic, a stale default source, and a mic the sound server can't see all classify as healthy. Chrome losing the mic this morning surfaced it: the stack was genuinely fine and the doctor had nothing useful to say.

The design grew past the gap in one conversation. An empty source list is normal on a mic-less desktop and a failure on a machine that should have one, and no probe can tell those apart. The missing fact comes from the user's finger: a doctor key on each of the OUTPUTS and INPUTS section headers, where pressing the input one asserts a mic should exist. That retires the DOCTOR header key I shipped hours earlier, and it dissolves the precedence question a single classifier would have faced.

A new probe tier sits below PipeWire. /proc/asound lists capture-capable cards, needs no package, spawns no process, and can't hang, so it separates "the software lost a microphone the kernel sees" from "nothing is plugged in".

Push-to-talk stays as it is. It mutes the source, the one state where the server guarantees nothing is captured. A link-based push-to-talk fails open, and a crash mid-hold is a hot mic reading as muted. The doctor reads ptt.read_state() instead of guessing.

Four decisions are open. Three are closed.
</content>
</entry>
<entry>
<title>docs: close the audio-doctor spec and its task</title>
<updated>2026-07-10T12:12:16+00:00</updated>
<author>
<name>Craig Jennings</name>
<email>c@cjennings.net</email>
</author>
<published>2026-07-10T12:12:16+00:00</published>
<link rel='alternate' type='text/html' href='https://git.cjennings.net/archsetup/commit/?id=8f27ba2a64362501a0ef3b7e986dfd98acc5de69'/>
<id>urn:sha1:8f27ba2a64362501a0ef3b7e986dfd98acc5de69</id>
<content type='text'>
The doctor shipped end to end, so the spec goes to IMPLEMENTED and the task closes with a dated record of what landed.

Three things the Decisions did not anticipate are written into the history rather than left for a reader to infer. A tenth verdict for missing tooling, because an absent pactl is an unobserved stack and not a broken one. A re-probed marker between a fix run's two row blocks. And DIAGNOSE as the read-only key's name, which Craig settled after asking why this panel carries two keys where the net panel carries one.

I filed the wall-controls convergence as its own task. Craig wants the net panel's copy and close pair on every output wall, and today no two of the four agree.
</content>
</entry>
<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=be7ceb55016932d9672984aff973ffad06c67a30'/>
<id>urn:sha1:be7ceb55016932d9672984aff973ffad06c67a30</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=590fc00ead35d1d61ea9dfea6c1905b2516c6953'/>
<id>urn:sha1:590fc00ead35d1d61ea9dfea6c1905b2516c6953</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=7917d0262b56a5f5f38b8cfb784e34369787e5a1'/>
<id>urn:sha1:7917d0262b56a5f5f38b8cfb784e34369787e5a1</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>
