docs(gig): archive the audio-path rescue — three tasks, one recurring failure shape

Archives #38, #39, #40 with full learnings, per the document-as-you-go discipline.

The thread: the onboard SOF codec stopped answering IPC mid-session and took the
whole audio stack down with it — WirePlumber wedged in uninterruptible D-state
inside ipc3_tx_msg_unlocked, unkillable by SIGKILL, scsynth dead, reboot the only
exit. That escalated the UMC202HD from "nice upgrade" to "resilience fix", and the
move onto it is now done: default sink switched, the SOF internal DMIC (card3
pcm4c, the exact PCM that hung) disabled by a scoped WirePlumber rule that leaves
all five SOF playback sinks alone.

The archive's real value is the pattern that runs through all three entries. Every
failure this session had the same shape: a binding resolved once at startup,
invalidated by a device event, failing with NO error surfaced. Ardour's master port
(twice — it restores its own saved ports and ignores the default sink, then loses
the link entirely on a wireplumber restart). SuperCollider's cached MIDIOut after a
replug moved the LCXL 20:0 -> 24:0. The HUD's aseqdump, still ALIVE on the dead
port, which is why its respawn-on-death recovery never fired — liveness is not
health. And the session layer itself: after an overnight suspend the UMC
re-enumerated 118 times, came back healthy at the hardware level, and WirePlumber
simply never rebuilt its node.

Also recorded: a wireplumber restart resets sink volume to the device default (87%),
which turned a routine verification tone into a painfully loud one. Attenuate before
making sound, always.

Corrected doctrine while here — commits belong on master by default. PLN is a lone
dev who reviews his own work; branches are for cloud agents, parallel sessions and
genuine prototypes. The memory claiming otherwise was wrong and cost real time.

docs/opal2026-task-archive.md

@@ -9,6 +9,62 @@ L'Armada (the media/marketing toolbox). Same discipline, different thread. Newes
 
 ---
 
+## #39 — Move the rig off the onboard SOF codec onto the UMC202HD
+- **Description:** the XPS's `sof-soundwire` codec was a tracked glitch source, and on
+  2026-07-26 it escalated from "suspected" to "took the whole stack down": the SOF DSP stopped
+  answering IPC (`ipc tx timed out for 0x30100000`, ASoC -110) while probing capture `pcm4`
+  (Microphone), and WirePlumber went to **uninterruptible D-state in `ipc3_tx_msg_unlocked`** —
+  unkillable even by SIGKILL. It took scsynth with it, mid-session. Only a reboot cleared it.
+- **Done:** UMC202HD made the default sink; SOF internal DMIC disabled via
+  `~/.config/wireplumber/wireplumber.conf.d/51-disable-sof-dmic.conf` (`node.disabled` on
+  `HiFi__Mic__source` = card3 `pcm4c`, the exact PCM that hung). Capture-only — 5 SOF playback
+  sinks left intact. Verified 0 IPC errors after restart. `tools/gig_record.sh` needed no change
+  at all: it captures `$(default sink).monitor`, so it auto-followed onto the UMC bus.
+- **Learnings:**
+  - **Card profile: keep `HiFi: Default`, not `pro-audio`.** Only two exist. HiFi gives one
+    stereo sink + 2 mono sources, which is what ordinary apps expect; `pro-audio` strips the UCM
+    mapping for raw channel access — a real win on a big desk, worthless on a 2-in/2-out box.
+  - **Ardour does NOT follow the PipeWire default sink** — it restores its own saved ports. The
+    rig kept playing out the laptop jack after the "switch", with no warning. Spawned #41.
+  - **The ALSA card number is not stable** across resume/replug (UMC was card 0, later card 1).
+    Match by name, never index.
+  - **Suspend/resume breaks it at the session layer, not the hardware layer:** 118 re-enumerations
+    on resume, card healthy afterwards, but WirePlumber never rebuilt the node → no sink, silent
+    fallback to SOF. Diagnose by whether events are *ongoing*, not by their count.
+  - A wireplumber restart **resets sink volume to the device default (87%)** — which is how a
+    routine verification tone became painfully loud. Set a safe level *before* making sound.
+- **Deps:** unblocked by #40; spawned #41; feeds #16 (balanced outs for FOH), #17 (gain must be
+  re-measured on balanced TRS — the 3.5mm numbers do not carry over).
+
+## #38 — Verify BootTidal.hs boots clean on a fresh SuperCollider start
+- **Description:** commit `98d073f` baked the live-validated prelude (the gF mute-bomb fix) into
+  `BootTidal.hs`. It had only ever been proven as a live shadow-eval, never from cold.
+- **Done:** verified by a real cold boot after the reboot (`bash gig-up.sh`, exit 0): perf mode
+  applied, **65 sample folders preloaded** from the last 20 tracks, SuperDirt ready with scsynth
+  up + `:57120` listening + MIDI claimed, Ardour and Pulsar launched. No fallback to the stale
+  `main_fairbanks`. Routing confirmed: `SuperCollider:out_1..N` land on Ardour's `Tidal NN` stems.
+- **Learnings:** the gap between "live-confirmed" and "durable" is exactly where the gF bug hid
+  (#21) — this closed it for real. Also: a cold boot is the cheapest moment to change audio
+  routing, because nothing is loaded yet and there are no warm samples to lose.
+- **Deps:** closed out the #21/#13 thread; prerequisite for #14 rehearsals.
+
+## #40 — Conclude the SOF hang / UMC audio-path decision with PLN
+- **Description:** a deliberately-written "START HERE" task, created before a forced reboot, so
+  the next session would open by asking PLN to decide rather than re-deriving the context.
+- **Done:** post-reboot state verified (UMC card 0, live sink, 6 enumerations / 2 disconnects =
+  normal boot churn not the 1 Hz loop, **0 SOF IPC errors**, WirePlumber in `S` not `D`), then
+  all four decisions put to PLN and executed the same turn.
+- **Learnings:**
+  - **A resume task written for a cold reader works.** It carried the kernel signatures, the
+    verification commands and the open decisions, and the session resumed with zero re-derivation.
+    Worth repeating for any hand-off across a reboot or a compact.
+  - **One decision in it was based on a wrong premise of mine:** I flagged the branch-vs-master
+    question as a convention violation. PLN corrected the doctrine — *"my convention is
+    master-by-default-no-branching-hell im a lone dev… i am the one who reviews"*. Branch only for
+    cloud agents, parallel sessions, or genuine prototypes. The memory that said otherwise was
+    wrong and cost real deliberation; corrected in `feedback_commit_often`.
+- **Deps:** blocked #39; both closed together.
+
 ## #15 — Mid-set recovery runbook ("when it breaks")
 - **Description:** PLN needed a playbook for the gig going wrong on stage, where the failure
   mode is panic as much as it is technical.