path: root/docs/specs/2026-07-10-audio-doctor-input-side-spec.org

#+TITLE: Audio Doctor, Input Side — a doctor per direction
#+AUTHOR: Craig Jennings
#+DATE: 2026-07-10
#+TODO: TODO | DONE
#+TODO: DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED

* DRAFT Audio Doctor, Input Side
:PROPERTIES:
:ID:       45efdd66-6d22-45c0-a633-ec41079e38ec
:END:
- [2026-07-10 Fri] DRAFT — drafted. Extends the audio doctor ([[file:2026-07-09-audio-doctor-spec.org][2026-07-09-audio-doctor-spec.org]], IMPLEMENTED) to the microphone, and replaces its single DOCTOR header key with one doctor per direction. Grounded in a live survey of ratio, not memory.

* Metadata

| Field    | Value                                                                      |
|----------+----------------------------------------------------------------------------|
| Status   | draft                                                                      |
|----------+----------------------------------------------------------------------------|
| Owner    | Craig Jennings                                                             |
|----------+----------------------------------------------------------------------------|
| Reviewer | Craig Jennings                                                             |
|----------+----------------------------------------------------------------------------|
| Related  | [[file:../../todo.org][todo.org]] : "The audio doctor never checks the microphone"                  |
|----------+----------------------------------------------------------------------------|
| Parent   | [[file:2026-07-09-audio-doctor-spec.org][2026-07-09-audio-doctor-spec.org]] — this supersedes its DOCTOR-key decision |
|----------+----------------------------------------------------------------------------|

* Summary

The audio doctor is output-only. It never examines the microphone, so a muted mic, a default source naming an unplugged device, and a mic the sound server cannot see all classify as =healthy=.

This adds the input side, and in doing so answers a question no probe can: whether a machine with no microphone is broken or merely mic-less. The answer comes from the user's finger. A doctor key on the INPUTS section header means "there should be a mic here", so an empty source list under that press is a failure rather than a shrug.

* Problem / Context

Three separate failures, all currently invisible.

** The classifier does not look at the source

=diag.probe_semantic= already collects =default_source= and =default_source_present=. =classify.py= reads neither. The word "source" appears once in that module, in the graph row that counts how many exist. Every semantic rule the classifier applies to the sink (is a default set, is it present, is it muted, is it at zero volume) has no source counterpart.

So the =healthy= verdict prints "Units are up, the graph answers, the Pulse layer answers, and the default output is present and audible." Output. Only. A user reading "the sound stack is healthy" concludes the mic is fine, and the doctor never checked.

** Nobody can tell an absent microphone from a broken one

A desktop with no microphone is a normal machine. So an empty source list cannot be a fault the way =no-output-devices= is, and the classifier has no way to know which machine it is on. This is not a probe problem. No amount of reading the graph settles it, because the missing fact lives in the user's head.

** The doctor cannot see below PipeWire

When Chrome stopped recognizing the microphone on 2026-07-10, the stack was genuinely healthy: the Shure MV7+ was the default source, unmuted, at 82%, with push-to-talk off. The doctor would have said =healthy= and been right about the stack and useless to the user.

The layer that would have helped is the one the doctor never reads. The kernel's own capture list distinguishes "the sound server lost a microphone the kernel can see" from "nothing is plugged in", and those two faults have nothing in common.

** Live survey (ratio, 2026-07-10)

Facts this spec is built on, verified rather than remembered:

- =/proc/asound/card*/pcm*c= lists capture-capable ALSA devices. On ratio: =Generic_1= (ALC623 analog), =MV7= (Shure), =BRIO= (Logitech). A =pcm*c= node means the card has a capture PCM; =pcm*p= would be playback.
- That path is a kernel filesystem read. It needs no package, spawns no process, and *cannot hang* — unlike every existing probe tier. =arecord -l= reports the same set but is owned by =alsa-utils=, which is a dependency the engine does not otherwise carry.
- =diag= already tags each stream =input= or =output= (=_STREAM_CLASSES=, mapping =Stream/Input/Audio= and =Stream/Output/Audio=). =active_streams()= returns both without distinction.
- Push-to-talk mutes the default source and leaves it muted between holds (=ptt.toggle_plan=). =ptt.read_state()= persists =armed=, so the deliberate mute is already knowable.
- A monitor source is a legitimate default source. =probe_semantic= passes =include_monitors=True= on purpose.

* Goals and Non-Goals

** Goals

- Classify the input side with the same rigor as the output side: default set, default present, muted, at zero volume.
- Never report an armed push-to-talk mic as a fault.
- Distinguish "the sound server does not see a microphone the kernel does" from "no capture hardware is attached", and say which.
- Let the user assert that a microphone should exist, without a dialog.
- One doctor at a time.

** Non-Goals

- Rebuilding push-to-talk. See the decision below; the mute is the safety property, not the bug.
- Per-application capture routing. If Chrome cannot see a source the graph plainly has, that is Chrome's fault, and Helvum and qpwgraph exist. This spec makes the doctor able to *say* the stack is fine, which is the sentence that was missing. It does not chase the client.
- Diagnosing hardware below the kernel. If =/proc/asound= shows no capture device, this spec reports that fact. It does not test cables, USB ports, or drivers.
- Sample-rate, latency, or xrun concerns. Still out, as in the parent spec.
- Silent privileged action. The doctor may use =sudo= for the input and output expansion (see the decision "The doctor may use sudo, resolved by context at run time"), but never silently: every privileged or reboot-tail remedy defaults to Confirm or Arm tier. Auto stays reserved for user-scope, reversible remedies.

** Scope tiers

- *v1:* the kernel capture tier; PTT-aware source classification; input verdicts and their remedies; the two section-header doctor keys with mutual exclusion; explicit =audio doctor --output= / =--input= flags, output aliased as the default.
- *Out of scope:* PTT rebuild; per-application routing; hardware diagnosis.
- *vNext:* per-device correlation between the kernel capture set and graph sources (v1 uses the coarse set-emptiness rule instead); and a third sighting of "the graph is fine and one client cannot use it", which turns into its own design question about whether the doctor should name the application layer. Both logged to =todo.org=, not built here.

* Design

** For the user

The DOCTOR section header we shipped on 2026-07-10 goes away. In its place, the OUTPUTS and INPUTS engraved section headers each grow a doctor key, beside the device counts they already carry. The keys diagnose the direction they sit above, and both write to the same results wall below.

The keys do not repeat the direction words. The CONTROLS section already carries INPUT and OUTPUT keys — the mute toggles that read LIVE / MUTE — so a doctor key labelled OUTPUT a few rows up would read as a fourth mute control. The doctor keys are named for what they examine instead: SPEAKERS on the OUTPUTS header, MICROPHONE on the INPUTS. Each carries a distinct diagnostic treatment so a user reads it as a different kind of key, not a device control. See the decision below; that treatment is the same on every panel's doctor.

Pressing MICROPHONE says something a probe cannot: that this machine is supposed to have a microphone. That single bit resolves the ambiguity the classifier cannot. An empty source list is normal on a desktop; an empty source list *under a press of the MICROPHONE doctor* is a failure, and the doctor now has license to say so.

The wall names which doctor ran, and only one runs at a time. Pressing SPEAKERS while a MICROPHONE run is in flight does nothing, because the wall holds one verdict and a second run would overwrite the first mid-read.

Diagnosis remains free and read-only. The escalation the user asked for — "we tried reloading all the devices and there is still no microphone" — is a *repair*, not a diagnosis, because reloading devices means restarting WirePlumber. So the diagnose verdict names what is wrong, and FIX is what tries the reload and re-probes. The wall then carries a claim the doctor earned rather than one it assumed:

#+begin_example
DOCTOR · MICROPHONE   diagnose · read-only
  ok    pipewire.service         active
  ok    wireplumber.service      active
  ok    pipewire-pulse.service   active
  ok    graph                    4 sinks, 3 sources (via pw-dump)
  ok    pulse compat             answering
  FAIL  capture hardware         kernel sees MV7, BRIO, Generic_1 — the graph has none
  --    default input            not checked (no input devices)

  verdict: The sound server does not see your microphone.
           The kernel has 3 capture devices and PipeWire has none, so the
           hardware is attached and the software lost it. FIX reloads the
           device profiles.
#+end_example

And when the kernel sees nothing either, the doctor stops rather than offering a remedy for a fault that is not there:

#+begin_example
  FAIL  capture hardware         no capture device is attached

  verdict: No microphone is attached.
           The kernel sees no capture hardware at all, so this is a cable, a
           port, or a device that is off. Nothing in the sound stack can fix it.
#+end_example

** For the implementer

*** A tier below the graph

The probe ladder gains a tier at the bottom, and its position is the point. Today's order is =systemctl= (cannot hang), =pw-dump= (alive when Pulse is dead), =pactl= (may hang). The kernel tier reads =/proc/asound=, which is a filesystem read that cannot hang, cannot fail for want of a package, and answers when every other layer is dead. It is the only probe in the doctor that carries no timeout, because it cannot block.

It answers one question: which cards expose a capture PCM. A card directory containing a =pcm*c= entry has one. That set is what separates a lost device from an absent one.

The comparison is deliberately coarse in v1, because the two layers speak different namespaces. The kernel tier names cards by ALSA id (=MV7=, =BRIO=); the graph names sources by PipeWire =node.name=. Mapping one to the other device-by-device is a rabbit hole, and the doctor does not need it. The v1 rule is a set-emptiness test, not a per-device match: =mic-unrecognized= fires when the kernel capture set is non-empty *and* the graph has zero non-monitor hardware sources. A monitor source does not count as a microphone (it is desktop-audio capture), so a graph carrying only monitors still reads as "no real input the kernel's hardware could be feeding." That coarse rule catches the whole-mic-lost case this feature exists for without ever having to prove that card X is the same device as source Y. Per-device correlation is a vNext refinement, logged, not built.

*** The classifier takes a direction

=classify(ctx)= becomes =classify(ctx, side)= where side is =output= or =input=. The terminal-fault ladder is shared and unchanged: PipeWire down, WirePlumber down, Pulse hung, Pulse dead, tooling missing. All of them break both directions, and the first one that fires wins regardless of side.

Below that the ladder forks. The output side keeps its rules exactly as they are. The input side gets, in order: no capture hardware; hardware present but no source in the graph; a default source that names an absent device; a mic muted or at zero. Every input rule is gated on the user having pressed the input doctor, which is what makes an empty source list a fault instead of a fact.

Push-to-talk sits inside that last rule. =diag.gather()= reads =ptt.read_state()= into the context, and a muted default source with PTT armed is not a finding. It is the mic doing exactly what the user asked. The wall reports it as an informational row rather than saying nothing, because a user who has forgotten PTT is armed deserves to be told why the mic is silent.

*** The guard learns direction

=active_streams()= returns running streams of both directions, and =repair.guard()= refuses the audible remedies whenever any of them is running. That is already slightly wrong: a playback remedy is refused today when the only thing running is a recording. Filtering by direction fixes that and is what the mic remedy needs.

Unmuting a microphone is not audible. It is a privacy event. If something is capturing when the remedy lands, the user's voice goes out. So the mic-unmute remedy is guarded against *input* streams with the same press-again override the audible remedies use, and the playback remedies are guarded against *output* streams.

* Failure modes and remedies

The whole point of a doctor is that every fault it can name has a stated fix, and the reader can see the two together. This is that map: what goes wrong at each probe tier, the verdict the classifier reaches, and the remedy FIX runs. The tiers are the probe ladder, top to bottom, so a fault lower in the table is one the doctor reaches only after the tiers above it answered clean.

The first four tiers are shared: a broken unit, a dead graph, or a dead Pulse layer takes out both directions at once, and the same verdict serves whichever doctor the user pressed. The kernel tier and the source-side semantic rules are what this spec adds.

| Tier                      | What goes wrong              | Verdict                    | Remedy                       |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 1 units (=systemctl=)     | =pipewire= not active, or    | =graph-down=               | 5: restart =pipewire= (Arm)  |
|                           | the graph will not answer    |                            |                              |
|                           | though the unit claims up    |                            |                              |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 1 units                   | =wireplumber= not active     | =no-session-manager=       | 1: restart =wireplumber=     |
|                           |                              |                            | (Auto)                       |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 1 units                   | =pipewire-pulse= not active  | =pulse-down=               | 4: restart =pipewire-pulse=  |
|                           |                              |                            | (Confirm)                    |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 2 graph (=pw-dump=)       | the graph is up but has no   | =no-output-devices=        | 1: restart =wireplumber=,    |
|                           | sink                         |                            | which re-creates devices     |
|                           |                              |                            | (Auto)                       |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 3 pulse (=pactl=)         | the socket accepts and never | =pulse-hung=               | 4: restart =pipewire-pulse=  |
|                           | answers                      |                            | (Confirm)                    |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 3 pulse                   | the socket refuses           | =pulse-down=               | 4: restart =pipewire-pulse=  |
|                           |                              |                            | (Confirm)                    |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 3 pulse                   | a probe's own tool is        | =tooling-missing=          | none: the stack is           |
|                           | missing                      |                            | unobserved, not broken       |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 4 semantic, output        | the default sink names a     | =stale-default=            | 2: set a present default     |
|                           | device that is absent        |                            | sink (Auto)                  |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 4 semantic, output        | the default sink is muted or | =silenced=                 | 3: unmute and restore volume |
|                           | at zero volume               |                            | (Confirm)                    |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 4 semantic, input         | the default source names a   | =mic-stale-default=        | 7: set a present default     |
|                           | device that is absent        |                            | source (Auto)                |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 4 semantic, input         | the default source is muted  | =mic-silenced=             | 8: unmute and restore volume |
|                           | or at zero, PTT off          |                            | (Confirm)                    |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 4 semantic, input         | the default source is muted, | healthy, informational row | none                         |
|                           | PTT armed                    |                            |                              |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 5 kernel (=/proc/asound=) | kernel capture set non-      | =mic-unrecognized=         | 6: reload profiles, restart  |
|                           | empty, graph has no non-     |                            | =wireplumber= (Confirm)      |
|                           | monitor hardware source      |                            |                              |
|---------------------------+------------------------------+----------------------------+------------------------------|
| 5 kernel                  | no capture device is         | =no-mic-hardware=          | none: a cable, a port, or a  |
|                           | attached at all              |                            | device that is off           |
|---------------------------+------------------------------+----------------------------+------------------------------|
| all clean                 | nothing is wrong             | =healthy=                  | none                         |
|---------------------------+------------------------------+----------------------------+------------------------------|

Three entries carry no remedy on purpose, and they are not the same kind of no. =tooling-missing= means the doctor could not observe the stack, =no-mic-hardware= means there is nothing in the stack to fix, and =healthy= means there is nothing wrong. A doctor that offered a button for any of the three would teach the user to distrust the wall.

Remedies 1 and 6 both restart WirePlumber, and that is deliberate: =no-output-devices= and =mic-unrecognized= are different diagnoses that happen to share a fix. Collapsing them would couple two faults that should read apart, the same call the parent spec made for =pulse-hung= and =pulse-down=.

* Verdict clusters and remedy classes

The verdicts and remedies above are the v1 core. Their full shape comes from a failure taxonomy built and saturation-tested after the first draft: [[file:../design/2026-07-10-audio-failure-taxonomy.org][docs/design/2026-07-10-audio-failure-taxonomy.org]], a catalogue of 74 input and 77 output real, user-reported failure modes. A blind resample (108 fresh reports through different sources, none shown the structure) forced zero new clusters, so the taxonomy is representative, not an artifact of sampling. It sorts every failure into nine symptom clusters per direction, and those clusters are what the doctor's verdicts name.

** The clusters are the verdict structure, and they map to the probe ladder

The nine input clusters are: (1) no capture device at all, (2) device present but records silence, (3) works but too quiet, (4) works then dies or drops, (5) the server lost a device the hardware has, (6) Bluetooth mic, (7) stack healthy but an app can't hear, (8) hardware/physical, (9) environment/config. Output mirrors this, swapping the mic-specific clusters for speaker-vs-headphone jack routing, HDMI/DisplayPort, and a degraded-audio (crackle/xrun) cluster.

The clusters are not arbitrary. Seven of the nine are the tiers the doctor's probe ladder already separates (units, graph, pulse, semantic, kernel), and the two it cannot fully see (cluster 7 app-layer, and part of cluster 8 hardware) are exactly the ones that resolve to Guide. So the boundary between what the doctor fixes and what it can only guide falls along the tiers it already probes. The v1 verdicts in the table above are the subset of these clusters the current ladder reaches; the rest are staged below.

** Remedy classes come from the privilege decision

Every remedy carries one of four classes, resolved at run time (see the decision "The doctor may use sudo, resolved by context at run time"): Auto, Privileged, Reboot-tail, Guide. The taxonomy tags every entry, so the buildable share is known — a little over half of each direction. The Auto core reduces to five primitives (=set-default=, =set-card-profile=, unmute, restart-services, config-drop-in-plus-restart) applied across roughly fifty diagnoses, so the breadth is in the diagnosis, not the remedies.

** Three new probes the taxonomy implies

Read-only and bounded, in the spirit of the kernel tier:

- *dmesg-pattern hints* (cluster 1). So "no capture hardware" can name the specific cause — firmware-load-fail, NHLT-missing, codec-probe-timeout — instead of a generic verdict, and the Guide can print the right command.
- *the unmute-doesn't-stick signature* (cluster 8). Issue an unmute, re-probe; a mute that will not clear is a hardware switch, not software. This is what tells an Auto (software mute) from a Guide (flip the physical switch).
- *re-probe-after-idle* (cluster 4). The current single-shot probe misses the suspend and autosuspend "works then dies" cases; a second read after an idle window catches them.

* Alternatives Considered

** Rebuild push-to-talk so it does not mute the mic

The idea: keep the source unmuted, and instead unlink its nodes from capturing applications (=pw-link=), or stand up a virtual source that applications connect to and link the real mic into it only while the key is held.

- Good, because the doctor would see an unmuted mic and need no special case, and because an application's own level meter would keep working.
- Bad, because the microphone stays live at the server and silence becomes a property of graph topology. A crash mid-hold, or a link that fails to tear down, is a hot mic while every indicator reads muted. Source-mute is the one state where the server itself guarantees nothing is captured.
- Bad, because the virtual-source variant requires every application to select the virtual device, which breaks per-application device choice — the thing the panel exists to give.
- Neutral, because the doctor does not need it: =ptt.read_state()= already persists the fact that the mute is deliberate.

Rejected. The mute is the safety property.

** One doctor that classifies both directions at once

- Good, because one press and one verdict.
- Bad, because =classify()= returns exactly one verdict, so a machine with a stale sink default and a muted mic forces the classifier to rank two unrelated faults. Any ranking is a guess about what the user came to fix.
- Bad, because it cannot resolve the absent-microphone ambiguity at all. No press means no assertion, and the doctor is back to shrugging.

Rejected in favor of one doctor per direction, which supplies the missing intent as a side effect of where the user pressed.

** Use =arecord -l= for the kernel tier

- Good, because it is the obvious tool and its output is human-readable.
- Bad, because it is owned by =alsa-utils=, a dependency the audio engine does not otherwise carry, so its absence would have to be modelled as a fourth =tooling-missing= case.
- Bad, because it spawns a process, which means a timeout, which means another way for the bottom tier to fail.
- Neutral, because it reads the same kernel data =/proc/asound= exposes directly.

Rejected. The bottom tier should be the one thing in the doctor that cannot fail.

* Review findings [1/10]

Second review pass, 2026-07-10 (four critical lenses: buildability, technical correctness, adversarial failure-modes, internal consistency). The technical foundations checked out — every load-bearing code and =/proc/asound= claim verified against the real tree. These findings are what the passes surfaced beyond that. The mechanical inconsistencies they also found (a "two new remedies" miscount, two stray OUTPUT/INPUT doctor-key labels) are already fixed in place.

** TODO Mic-unmute must fail closed on an unreadable graph :blocking:
The stream-active guard abstains and proceeds when =pw-dump= cannot read the graph. That is right for the *output* remedies, whose whole job is repairing a dark graph. It is wrong for the mic-unmute remedy (8), because unmuting is a privacy event, not an availability one: with the graph unreadable the guard cannot see a running capture stream, so FIX would unmute a live mic mid-recording with no second press and no warning. The mic-unmute remedy must fail *closed* on an unreadable graph — refuse, or fall back to =pactl list source-outputs= — never abstain-and-proceed. Every other finding here produces a wrong verdict; this one produces a wrong action. Folds into the open capture-guard decision. (blocking)

** TODO A non-ALSA microphone classifies as no-mic-hardware :blocking:
A Bluetooth or USB-non-ALSA mic never appears under =/proc/asound/card*=, because bluez runs through PipeWire, not ALSA. The =no-mic-hardware= verdict is gated only on "kernel capture set empty", with no graph clause, so a working BT-headset mic (a real non-monitor source in the graph) reads as "No microphone is attached." The input ladder must consult the graph first: a working non-monitor source in the graph is =healthy= (or routes to the semantic rules) and skips the kernel tier entirely. =no-mic-hardware= fires only when the kernel set is empty *and* the graph has no non-monitor source; =mic-unrecognized= only when the kernel set is non-empty *and* the graph has none. This also resolves the ladder-order contradiction below. Folds into the open input-verdicts decision. (blocking)

** TODO The input ladder's evaluation order is stated two ways :important:
The "For the implementer" prose lists the kernel-tier rules first (no-mic-hardware, mic-unrecognized), then the semantic rules. The failure table orders the semantic-input rows (tier 4) above the kernel rows (tier 5) and says lower rows are reached only after upper tiers answer clean. Those are opposite orders for the same four rules. The finding above settles it: graph-source presence is the top gate, so define one order and make both the prose and the table match it.

** TODO The probe does not yet surface source mute, volume, or a monitor flag :important:
=probe_semantic= produces =default_sink_muted= / =default_sink_volume= but no source equivalents, and neither the graph nor the semantic source dicts carry a monitor flag (=pactl._device= strips =device.class=). The =mic-silenced= rule reads source mute/volume the context never provides, and the "non-monitor hardware source" test cannot be computed. Phase 0 must extend =probe_semantic= to surface the source fields and tag sources monitor-vs-hardware, and the =mic-unrecognized= rule must read the =pw-dump= source population (=Audio/Source=, monitor-excluding), not the =pactl include_monitors=True= one — reading the monitor-inclusive list would mean a monitor is always present and the rule never fires. Neither change is scoped by an open decision; both would stall Phase 0/1.

** TODO The direction must thread through findings() and doctor(), not only classify() :important:
The spec says =classify(ctx)= becomes =classify(ctx, side)= but never that =findings(ctx)= gains =side= too, though the wall shows side-specific rows. =doctor.doctor()= is the sole caller and invokes both =classify= and =findings= twice each (initial and re-probe), plus =final_findings= / =final_verdict=; it must take =side= and thread it to all of them, and =cli.cmd_doctor= must pass the resolved side. Name this in the phase text so it is not left for the implementer to rediscover.

** TODO Remedy 6 restarts WirePlumber unguarded, mid-call :important:
=mic-unrecognized='s remedy (6, restart WirePlumber) is in neither guard set, so a user on a call can press FIX and reload the device profiles with no guard and no second-press consent. A profile reload can re-select the default sink and drop the call's routing. Decide whether remedy 6 is guarded — against streams of *both* directions, since a WirePlumber restart touches the whole graph — as part of the open capture-guard decision.

** TODO A stale armed=true PTT state can mask a genuinely muted mic :important:
The safe-degrade argument covers only an unreadable or missing PTT state file (=read_state= returns disarmed). It does not cover =armed=true= left stale — Hyprland restarted and dropped the binds, or the mic was muted by the CONTROLS toggle for an unrelated reason while PTT happened to be armed. =read_state= cannot detect staleness, so the doctor reports "healthy, PTT armed" on a genuinely dead mic, the exact failure this feature exists to fix. At minimum, name the limitation; better, have the informational row say the mic is muted *and* that PTT is armed, so the user is not told the mic is simply fine.

** TODO Minor build-notes to fold in before Phase 3 :minor:
Three smaller items the passes raised. The =healthy= verdict text is output-worded ("the default output is present and audible") and needs side-aware wording for a clean =MICROPHONE= run. The two keys must clear =doctor_running= on the worker's error path so a raised worker cannot wedge both keys insensitive for the session — the shipped =bg= / =doctor_abort= pattern already does this, so it is a spec-explicitness note, not a code gap. And a USB mic pressed during its ~1s enumeration window (kernel sees the card before WirePlumber creates the source) fires a transient =mic-unrecognized=; self-correcting, worth a line acknowledging the race.

** TODO Open Decisions still gate implementation :blocking:
The workflow treats unresolved decisions as implementation blockers, because a builder would be accepting product and safety tradeoffs mid-build. Partly addressed as of 2026-07-10: Craig closed the push-to-talk and kernel-tier decisions, and the CLI-flag decision closed with his direction, so the cookie is now =[6/9]=. Three decisions remain open — the direction-aware capture guard, the input verdict and remedy table, and the doctor-key naming and cross-panel style. Close or explicitly risk-accept each before implementation starts. (blocking)

** DONE Kernel capture devices are not mapped to graph sources :blocking:
CLOSED: [2026-07-10 Fri]
The finding: the kernel names cards by ALSA id and the graph names sources by PipeWire =node.name=, so "compare the kernel capture set against the graph's source list" was undefined, and monitor sources muddied it further. Resolved 2026-07-10 by adopting the reviewer's coarse rule as the v1 definition: =mic-unrecognized= fires when the kernel capture set is non-empty and the graph has zero non-monitor hardware sources. No per-device correlation, no namespace mapping — that whole-mic-lost case is the one this feature exists for, and per-device matching is logged as vNext. The rule now appears in the "For the implementer" kernel-tier note, the failure table, and the input-verdicts decision.

* Decisions [7/10]

** DONE A doctor key per direction, on the section headers
CLOSED: [2026-07-10 Fri]
Context: an empty source list is normal on a mic-less desktop and a failure on a machine that should have one. No probe can tell them apart.

Decision: we will put a doctor key on each of the OUTPUTS and INPUTS engraved section headers, and retire the standalone DOCTOR header and its DIAGNOSE key. Pressing the input doctor asserts that a microphone should exist.

Consequences: the ambiguity is resolved by the user without a dialog, and the check sits beside the devices it judges. Harder: this supersedes a decision in the parent spec that shipped hours earlier, so the parent's history must say so. The panel also grows a third and fourth console key, and the 400px width has to absorb them.

** DONE One doctor at a time
CLOSED: [2026-07-10 Fri]
Context: the wall holds one verdict, and a run clears the wall when it begins.

Decision: we will allow only one doctor run in flight. SPEAKERS must finish before MICROPHONE can be pressed, and both keys go insensitive for the duration.

Consequences: the wall is never a mix of two runs, and "which verdict is this" never needs asking. Harder: nothing, since the model already clears on begin and locks on =doctor_running=. The keys simply join the lock.

** DONE An absent microphone is not a fault unless the user says so
CLOSED: [2026-07-10 Fri]
Context: =no-output-devices= is a fault because a machine with no way to play sound is broken. The mirror is false: a machine with no way to record is ordinary.

Decision: we will not add a source-side =no-input-devices= fault. The input rules fire only under a press of the input doctor, which supplies the assertion that a mic should exist.

Consequences: the doctor never cries wolf on a mic-less desktop. Harder: the classifier now takes a side parameter, so it is no longer a pure function of the context alone. It stays pure; the side is an input.

** DONE Does push-to-talk get rebuilt?
CLOSED: [2026-07-10 Fri]
Context: PTT mutes the default source and leaves it muted between holds, so a naive mirror of the sink rules would classify an armed mic as "silenced, FIX unmutes it". Pressing FIX would break PTT and leave a hot mic the user believes is muted. Craig asked whether PTT could avoid muting.

Decision: we will not rebuild PTT. =diag.gather()= will read =ptt.read_state()= into the context, and an armed-PTT muted mic will be reported as an informational row rather than a finding.

Consequences: a few lines rather than a rewrite, and the safety property is preserved — source-mute is the only state where the server guarantees no capture. Harder: the doctor now depends on a runtime state file, so a stale or unreadable file must degrade to "not armed" (which =read_state()= already does) and the mic then reads as a genuine finding. That is the safe direction: it over-reports a muted mic rather than under-reporting a hot one.

Craig ratified 2026-07-10: not rebuilding is fine.

*** Discussion
The alternatives are recorded above under "Rebuild push-to-talk so it does not mute the mic". The load-bearing argument is that link-based silence fails open.

** DONE The kernel tier reads =/proc/asound=, not =arecord=
CLOSED: [2026-07-10 Fri]
Context: the doctor needs a layer below PipeWire to tell a lost microphone from an absent one.

Decision: we will read =/proc/asound/card*/pcm*c= directly. A card exposing a capture PCM has capture hardware.

Consequences: the bottom tier cannot hang, cannot be absent, and needs no timeout — the only probe in the doctor with that property. Harder: it is Linux-specific and reads a kernel interface rather than a supported API, so a kernel that reorganizes =/proc/asound= would break it silently. The fallback is that an unreadable =/proc/asound= yields "unknown", never "no hardware", so the doctor abstains rather than lying.

Craig ratified 2026-07-10: all okay.

** TODO The capture guard, and what it refuses
Context: unmuting a microphone is not audible, but it is a privacy event. =active_streams()= currently ignores stream direction, so a playback remedy is refused today when only a recording is running.

Decision (proposed): we will make the guard direction-aware. Playback remedies (3, 4, 5) refuse on running *output* streams; the mic-unmute remedy refuses on running *input* streams. Both take the same press-again override, and both abstain on an unreadable graph, as today.

Consequences: the guard stops over-refusing, and unmuting a mic mid-recording takes deliberate consent. Harder: it changes the behavior of shipped remedies, so the existing guard tests move with it rather than being deleted.

Owner: Craig. By: before Phase 2 lands.

** TODO The input verdicts and their remedies
Context: the input side needs its own verdict vocabulary and its own remedy table entries.

Decision (proposed): four new verdicts, and three new remedies.

| Verdict             | Means                                    | Remedy                                    | Tier    |
|---------------------+------------------------------------------+-------------------------------------------+---------|
| =no-mic-hardware=   | the kernel sees no capture device        | none                                      | —       |
|---------------------+------------------------------------------+-------------------------------------------+---------|
| =mic-unrecognized=  | kernel capture set non-empty, graph has  | 6: reload device profiles (restart        | Confirm |
|                     | no non-monitor hardware source           | WirePlumber)                              |         |
|---------------------+------------------------------------------+-------------------------------------------+---------|
| =mic-stale-default= | the default source names a device that   | 7: set a present default source           | Auto    |
|                     | is absent                                |                                           |         |
|---------------------+------------------------------------------+-------------------------------------------+---------|
| =mic-silenced=      | the default source is muted or at zero,  | 8: unmute and restore the mic volume      | Confirm |
|                     | and PTT is not armed                     |                                           |         |
|---------------------+------------------------------------------+-------------------------------------------+---------|

=no-mic-hardware= carries no remedy for the same reason =tooling-missing= carries none: offering a fix for a fault that is not in the stack teaches the user to distrust the wall.

=mic-unrecognized= uses the coarse set-emptiness rule from the "For the implementer" kernel-tier note, not a per-device match. The kernel names cards by ALSA id and the graph names sources by PipeWire =node.name=; those are different namespaces, and correlating them device-by-device is a vNext refinement. v1 fires =mic-unrecognized= when the kernel capture set is non-empty and the graph has zero non-monitor hardware sources. This resolves the second spec-review finding, which flagged the matching rule as undefined.

Consequences: the verdict table grows from ten to fourteen, and =classify.findings()= grows a capture-hardware row and a default-input row. Harder: remedy 6 restarts WirePlumber, which remedy 1 already does for a different verdict. Two remedies invoking one action is fine; collapsing them would couple two diagnoses that should stay apart.

Owner: Craig. By: before Phase 1 lands.

** DONE The CLI grows explicit =--output= and =--input= flags, output aliased as the default
CLOSED: [2026-07-10 Fri]
Context: =audio doctor= today accepts only =--fix= and =--force=. There is no =--output=, so adding a lone =--input= would read as a special case bolted onto a bare command rather than one of a symmetric pair.

Decision: we will add both =--output= and =--input= as explicit direction flags, and alias bare =audio doctor= to =audio doctor --output=. Both accept =--fix= and =--force=. The two flags are mutually exclusive; passing both is an error.

Consequences: the two directions are named symmetrically, and =--input= has a sibling to pair against rather than standing alone. Bare =audio doctor= keeps its current meaning, so nothing that scripts it breaks, and "output is the default" is now a stated alias a reader can see rather than a convention to infer. Harder: =audio doctor --input --fix --force= is a long line, which is the cost of explicitness over =audio doctor input=; the subcommand form was rejected because it would break every existing call.

Craig's call, 2026-07-10: "alias the command and have =audio doctor --output= be the one that is run by default. That way it's symmetrical, and =audio doctor --input= has a place."

** TODO Name and style the doctor keys, distinct from the device controls
Context: the CONTROLS section already carries INPUT and OUTPUT keys — the mute toggles that read LIVE / MUTE. A doctor key labelled OUTPUT or INPUT on the section header a few rows up would read as a fourth mute control. Craig flagged the collision and asked for a name and a look that mark the doctor keys as a different function, held consistent across every panel.

Decision (proposed): the doctor keys are named for what they diagnose — SPEAKERS on the OUTPUTS header, MICROPHONE on the INPUTS. Craig delegated the naming ("I'll let you choose"); these are the choice. Each key carries a distinct diagnostic treatment: a small health glyph (a stethoscope, =nf-md-stethoscope=) ahead of the word, plus a subtly distinct outline, so the key stays inside the dupré aesthetic while reading as diagnostic rather than a device control. The same treatment applies to the doctor keys already shipped in the other panels — net's DOCTOR, maint's CLEAN UP / REVIEW & FIX — so a doctor key looks like a doctor key everywhere.

Consequences: no word collides with the CONTROLS keys; the two doctor keys carry distinct AT-SPI names the smoke can target; the diagnostic affordance is consistent across the panel family. Harder: it touches every panel's =gui.py= and the shared panel CSS, so the cross-module restyle is its own task rather than part of this build, and it sits beside the already-filed "copy + close on every wall" convergence. The exact glyph and outline are an aesthetic call that wants Craig's eye on a screenshot before it lands — which is why this stays open while the naming is settled.

Owner: Craig (the visual). By: before Phase 3, where the keys are built.

** DONE The doctor may use sudo, resolved by context at run time
CLOSED: [2026-07-10 Fri]
Context: the parent spec decided "no sudo anywhere", correct when the feature was purely user-scope PipeWire. The input and output expansion reaches firmware, ALSA saved state, modprobe overrides, and package management, which genuinely need root. Craig also wants the CLI usable as a generic doctor on machines that are not archsetup installs.

Decision: this supersedes the parent's no-sudo decision. The doctor resolves its privilege at run time from three signals — passwordless sudo available (=sudo -n true=, which succeeds or fails instantly and never hangs), a tty to prompt at, and whether it is the GUI panel. Four remedy classes follow: *Auto* (user-scope, reversible, runs anywhere), *Privileged* (needs sudo — runs silently where passwordless sudo exists, prompts in a CLI with a tty, and degrades to Guide only in a GUI with neither), *Reboot-tail* (the applicable part runs, then the doctor instructs the reboot it cannot complete or verify past), and *Guide* (nothing to run: a physical switch, a BIOS setting, a wait-for-upstream fix). Every archsetup install has passwordless sudo, so on Craig's machines Privileged remedies run; the generic-CLI case prompts.

Consequences: many failure modes that were guide-only (=alsactl store=, a modprobe override, removing a conflicting package) become applicable remedies on archsetup and on any CLI. Harder, and load-bearing: passwordless sudo is not consequence-free, so every Privileged and Reboot-tail remedy defaults to *Confirm or Arm* tier, never silent Auto — a firmware install or a module reload always takes a deliberate second press even when sudo will not prompt. Auto stays reserved for the user-scope, reversible remedies. This model is not audio-specific: the net, bluetooth, and maint doctors adopt the same run-time privilege resolution and the same Confirm/Arm-default for privileged actions, tracked as its own cross-panel task.

Craig agreed 2026-07-10 to both the model and the Confirm/Arm-default safety stance, and to making it a cross-panel standard.

* Implementation phases

Each phase leaves the tree green and independently useful, as the parent spec's phases did.

** TODO Phase 0 — the kernel tier, PTT in the context, direction-aware streams
Pure engine, no classifier changes, no UI. =diag.probe_kernel()= reads =/proc/asound=; =diag.gather()= adds =kernel= and =ptt= to the context; =active_streams(graph, direction=None)= filters. =audio diag --json= shows the new context. Fakes: a temp =/proc/asound=-shaped tree via an injectable root, since the real one cannot be faked on PATH.

** TODO Phase 1 — =classify(ctx, side)= and the input verdicts
Pure, fixture-driven. The shared terminal ladder, then the fork. Pairwise over (kernel capture set × graph sources × default source state × PTT armed). This phase adds the direction flags: =--output= and =--input=, mutually exclusive, with bare =audio doctor= aliased to =--output=. =audio doctor --input= read-only prints findings and a verdict, and =audio doctor= keeps printing exactly what it does today.

** TODO Phase 2 — the input remedies and the direction-aware guard
Remedies 6, 7, 8, each re-probing its own claim. The guard splits by direction. =audio doctor --input --fix=. The existing guard tests move rather than being deleted.

** TODO Phase 3 — two section-header doctor keys
Retire the DOCTOR header row and its DIAGNOSE key. OUTPUTS and INPUTS each gain one. Mutual exclusion on =doctor_running=. The wall header names the run. AT-SPI smoke over both keys and the fix path, on fixtures.

** TODO Phase 4 — flip this spec to IMPLEMENTED
And amend the parent spec's history to record that its DOCTOR-key decision was superseded here.

** Later phases — the taxonomy expansion (vNext)
v1 (phases 0-4) ships the buildable Auto core and the Guide tail for the clusters the current probe ladder already separates, and flips this spec to IMPLEMENTED. The rest of the taxonomy ([[file:../design/2026-07-10-audio-failure-taxonomy.org][the taxonomy]]) is staged as later phases so v1 is not blocked on them. Each is a small, independent addition; the taxonomy is the backlog and this list is the order:

- The dmesg-hint probe and the firmware/driver Guide tail (cluster 1).
- The unmute-doesn't-stick signature probe and the hardware-layer Guide (cluster 8).
- Re-probe-after-idle for the suspend and autosuspend cases (cluster 4).
- The Privileged and Reboot-tail remedy machinery: the run-time privilege resolution (=sudo -n= / tty / GUI detection) and the Confirm/Arm-default floor.
- The app-layer Guide tail (clusters 7 and 9): the tail on a healthy verdict that names the likely app or portal cause and prints the fix.

These grow into their own spec when picked up.

* Acceptance criteria

- A machine with no capture hardware, under a press of the input doctor, reports =no-mic-hardware= and offers nothing to press.
- A machine whose kernel lists a capture device the graph has no source for reports =mic-unrecognized=, and FIX reloads the device profiles and re-probes.
- An armed-PTT muted mic classifies as =healthy=, with an informational row saying push-to-talk is armed.
- A muted mic with PTT disarmed classifies as =mic-silenced= and FIX unmutes it.
- FIX on the mic while something is recording is refused, and a second press proceeds.
- Restarting a playback remedy while only a microphone is recording is no longer refused.
- Pressing SPEAKERS while MICROPHONE is running does nothing.
- =audio doctor= with no flag behaves exactly as it does today.

* Readiness dimensions

- *Data model & ownership* — the context dict gains =kernel= (generated, per-probe) and =ptt= (read from the runtime state file that =ptt.py= owns; the doctor never writes it).
- *Errors, empty states & failure* — an unreadable =/proc/asound= yields =unknown=, never "no hardware". An unreadable PTT state reads as disarmed, which over-reports a muted mic rather than under-reporting a hot one. Both are the safe direction.
- *Security & privacy* — the mic-unmute remedy is the only privacy-relevant action in the feature, and it is guarded against running capture streams with an explicit second-press override. No credentials, no logs.
- *Observability* — the wall is the observability surface, and it names which doctor ran. The =--json= output carries the full context including the kernel tier.
- *Performance & scale* — the kernel tier is a directory listing. Everything else is unchanged.
- *Reuse & lost opportunities* — =classify.findings()= remains the single row-builder for the CLI and the GUI. =ptt.read_state()= is reused rather than reimplemented. =diag.unit_active= stays the single source of truth for unit state.
- *Architecture fit* — the fork lives in =classify()=, which is pure and already fixture-tested. The GUI change is confined to the section-header rows and the model's key-sensitivity logic.
- *Config surface* — none. N/A.
- *Documentation plan* — the module docstrings carry the design, as in the parent. No user docs; the wall is the documentation.
- *Dev tooling* — =make test= and =make test-panel-audio= cover it. The kernel tier needs an injectable root rather than a PATH fake, which is a new fixture shape for this package.
- *Rollout, compatibility & rollback* — =audio doctor= with no flag is unchanged, so nothing that scripts it breaks. The GUI change is not reversible by config; it is a redesign of a key that shipped the same day.
- *External APIs & deps* — =/proc/asound= layout verified live on ratio, 2026-07-10. No new packages.

* Risks, rabbit holes, and drawbacks

The kernel tier reads an interface rather than an API. If a future kernel reorganizes =/proc/asound=, the probe reports =unknown= and the doctor abstains, which is the failure mode we want, but nothing will announce the breakage. A test against a recorded tree pins the shape we expect.

Remedy 6 restarts WirePlumber to reload device profiles, which is what remedy 1 already does. The temptation is to collapse them. Do not: the two verdicts describe different faults, and a shared remedy is not a shared diagnosis. The parent spec made exactly this call for =pulse-hung= and =pulse-down=.

The panel is 400px wide and gains two console keys while losing one row. The layout needs eyes on it before Phase 3 closes, and no automated check will catch an ugly one.

This spec supersedes a decision from a spec that reached IMPLEMENTED the same day. That is a smell worth naming: the DOCTOR-key placement was decided without the input side in view, and one conversation with the user overturned it. The lesson is not that the first decision was careless. It is that the input side should have been in scope from the start, and the parent's Non-Goals never said it was not.

* Review and iteration history

** 2026-07-10 Fri @ 18:52:07 -0500 — Craig Jennings — Reviewer
What changed or was recommended: a second review pass across four critical lenses — buildability, technical correctness, adversarial failure-modes, internal consistency. Verified every load-bearing code and =/proc/asound= claim against the real tree; all held. Recorded eight new findings (two blocking: mic-unmute failing open on an unreadable graph, and a non-ALSA mic mis-classifying as no-mic-hardware) and fixed three mechanical inconsistencies in place (a remedy miscount and two stray OUTPUT/INPUT doctor-key labels).
Why: the design was sound at the tier level, but it had two safety and correctness holes that only surface on real hardware (a webcam or Bluetooth mic, an unreadable graph), plus three build gaps that sit outside the open decisions and would stall Phase 0/1.
Artifacts: [[*Review findings][Review findings]]; code read across =~/.dotfiles/audio/src/audio/= (=diag.py=, =classify.py=, =repair.py=, =doctor.py=, =ptt.py=, =pactl.py=); live =/proc/asound= survey on ratio.

** 2026-07-10 Fri @ 10:55:19 -0500 — Codex — Reviewer
What changed or was recommended: applied the spec-review workflow and recorded two blocking findings: open Decisions still gate implementation, and kernel-capture-to-graph-source matching is undefined.
Why: the current implementation confirms the microphone gap and output-only classifier, but these unresolved choices would force the builder to decide safety and classification behavior during implementation.
Artifacts: [[*Review findings][Review findings]]; current code read in =~/.dotfiles/audio/src/audio/diag.py=, =classify.py=, =repair.py=, =cli.py=; related tracking in [[file:../../todo.org][todo.org]] under "The audio doctor never checks the microphone".

** 2026-07-10 Fri @ 10:38:12 -0500 — Craig Jennings — Author
What: drafted the spec. Four probe tiers become five, the classifier takes a direction, the panel gets a doctor per direction, and push-to-talk stays as it is.
Why: the doctor calls a stack healthy while the microphone is dead, and the ambiguity of an absent mic cannot be resolved by any probe.
Artifacts: live survey of ratio (=/proc/asound= capture nodes, =_STREAM_CLASSES=, =ptt.read_state()=), and the Chrome incident of the same morning.