docs(archive): #29 and #17 — the portable rig proved on a second box

Long-form entries for the two tasks the XPS24 session closed. Written for a
reader months from now with no memory of it, because these are the source
material for the blog post (#22) that was deliberately blocked on this outcome
so its ending could be 'it played' rather than 'it should'.

The through-line worth keeping: six blockers on the second machine and not one
of them produced an error message. A hijacking startup.scd, a quark cloned but
unregistered, tidal built against the wrong ghc, a 644 installer, no pip at all,
and a Pulsar package whose documented install command silently downgrades the
rig. Every one of them was invisible on the box the setup was written on, which
is the actual lesson: config that has only ever run on one machine has been
observed working, not tested.

Also recorded, because they are about the measuring instruments rather than the
rig: the doctor's coverage check counts bank names and so reported all 281 banks
present while 15 GB was still copying, and its fix text for missing units named a
tool that cannot install them. And the tilde traps -- File.exists('~/x') is
false, nowExecutingPath is nil inside waitForBoot -- each of which would have
turned a portability fix into a permanently-false guard.

armada/tasks/completed-archive.md

@@ -2334,3 +2334,123 @@ the literal `/home/pln` paths in `start_and_midi.scd` and `sample_watch.scd`
 silently missing. A stranger hitting that with no warning is the worst outcome.
 
 **Deps.** Blocked by #19 + #20. Blocks #22 (blog post from the outcome) and #29.
+
+## #29 — XPS24: prove it can play
+
+**Description.** Everything for the portable rig was built on 2026-09-06 and none
+of it had ever run on another machine. The task was to sit at the XPS24 and confirm
+a track plays.
+
+**Done.** Executed remotely from XPS22 over the peer SSH link PLN set up that
+afternoon, ~90 minutes. The rig plays. Proof taken from `scsynth`'s own `/status`
+counters rather than by ear, since the box was unattended and the test pattern ran
+at `gain 0.15`: 3519 ugens / 71 synths / 17 groups at rest → 3573 / 73 / 18 while
+`d1 $ sound "bd*4"` plays → back to baseline on `hush`. Boot log shows
+`SuperDirt: listening to Tidal on port 57120`,
+`sample watcher responder armed — 1203 banks`, `109 SynthDefs available`, and
+`BootTidal.hs` loads clean. `rig-doctor.py` went 9 fail / 20 pass → 4 fail / 30
+pass → 2 fail after PLN's sudo round. Commits: `b130508` (#84 phases 1+2),
+`51f1189` (exec bits + ratchet + doctor fix-text); SRE `0aa403b`, `7be0bd8`,
+`ce94788` (runbook `TODO.d/100`, and `101` for the sampling stack).
+
+**Learnings.** Six blockers, and the through-line is that **not one of them
+produced an error message.**
+
+* The clone's remote was `git.plnech.fr`, which no longer resolves, and XPS24's key
+  is not registered at `git.nech.pl` either. The 141-commit catch-up and all four
+  private repos came **peer-to-peer**:
+  `git fetch ssh://pln@xps22.local/home/pln/Work/Sound/Tidal master`.
+* A 47-line **ansible-generated `~/.config/SuperCollider/startup.scd`** hijacked
+  every `sclang` launch: `loadSoundFiles` with no arguments (stock samples only,
+  all three real roots ignored), `~dirt.start(57120, 0 ! 12)` (twelve orbits to
+  channel 0, orbit map discarded), and a **second SuperDirt on the rig's own port**.
+  XPS22 has no such file, so nothing in the repo, doctor or installer knew to look.
+  **Ask what the other box has that yours doesn't**, not only the reverse.
+* **BatLib was cloned but absent from `sclang_conf.yaml`** — that file, not the
+  `downloaded-quarks/` directory, is the registry. With mi-UGens also missing (no
+  `cmake`; the 11 prebuilt `.so` were copied from XPS22 and load fine on SC 3.13
+  against 3.14's build), three `Class not defined` errors aborted the block
+  **before `s.waitForBoot` ever ran**. The symptom was an **empty journal** — no
+  boot, no error, no output. This cost the most time of anything here.
+* **Tidal was installed against ghc-8.8.4 while the default `ghc` is 9.4.7**, so
+  `ghci` could not find `Sound.Tidal.Context`: Pulsar would have opened and
+  Ctrl+Enter would simply never have booted. `cabal update` then failed on a **dead
+  hackage mirror baked into cabal 3.8.1** (403 from `objects-us-east-1.dream.io`),
+  so the install ran off the cached index.
+* **`pip` does not exist on that box** (no `pip`, no `ensurepip`) on a PEP-668
+  distro. `mido` + `python-rtmidi` went in as PyPI **wheels unzipped into user
+  site-packages** with stdlib only.
+* **`pulsar -p install tidalcycles` would have silently downgraded the rig.** The
+  working install is `~/.pulsar/packages/*` **symlinked into clones**; the fork is
+  47 commits ahead and carries `000a183`, which routes Pulsar's "Boot SuperDirt"
+  through the systemd unit. XPS24 had vanilla **v3.16.38** installed. And the copy
+  of the HUD vendored *inside* the Tidal repo is stale (missing six `lib/` files),
+  so "copy the vendored one" is a trap with a green look to it.
+
+Two things the session found about **the instruments themselves**: the doctor's
+sample-coverage check counts bank *names*, so it reported "all 281 banks present"
+while 15 GB was still in flight — the real verification is file-level (281/281
+banks, 9385 files, 0 short); and the doctor's fix text for missing units pointed at
+`rig_units.py --ensure --apply`, which only enables units already symlinked, so on
+a fresh box it emits fifteen "Unit file does not exist" lines and reads like a
+broken reconciler.
+
+The **jack** finding arrived last and is the most transferable: installing
+`pipewire-jack` changed nothing, because Ubuntu keeps its shim off the loader path
+on purpose and XPS24 has jack2 (via qjackctl) winning the `libjack.so.0` lookup.
+XPS22 has **no jack2 at all**, which is the sole reason its plain `sclang` always
+used PipeWire. Two boxes that looked identically configured, weren't. Fixed with a
+machine-local systemd drop-in rather than a repo change — **a per-box difference
+belongs in a per-box file.**
+
+**Deps.** Blocked #28 and #22. Superseded in practice by SRE `TODO.d/100`, which is
+the cross-laptop source of truth and survives a session switch.
+
+## #17 — Portable ParVagues: play the rig from any laptop
+
+**Description.** PLN travels with a different laptop, then moves permanently to an
+XPS24, and a friend who bought his LCXL2 should be able to play too. The rig had to
+stop assuming one machine.
+
+**Done.** Shipped `sample-pack.py`, `rig-doctor.py` (44 checks), `rig-install.sh`,
+`SETUP.md`, a committed `sample-manifest.json`, the `parvagues-synths` repo, and a
+verified 15.11 GB carry-on bundle — then **proved the whole thing on a second box**
+(see #29). `#84` phases 1+2 landed: three sample roots and two same-repo loads made
+location-independent, and the two outlier LCXL units converted to `%h`.
+
+**Learnings.** The path work turned on three traps, each verified in `sclang`
+**before** a line was written, and each of which would have produced a silent
+failure rather than an error:
+
+* `"~/x".standardizePath` keeps a trailing glob intact — so the `loadSoundFiles`
+  calls stay one-liners.
+* **`File.exists("~/x")` returns false.** A naive tilde substitution would have left
+  the preload and sample-watcher guards syntactically perfect and permanently
+  false — a dead preload with no error, strictly worse than the hardcoded path.
+* **`thisProcess.nowExecutingPath` is nil inside `s.waitForBoot`'s closure.** The
+  two same-repo loads live in there, so the repo root is captured at top level into
+  `~pvRepoRoot`. Reading it in place would have produced exactly the same dead-guard
+  failure. Deriving the root from the file's own location also beats a home-relative
+  guess: the rig now runs from any clone path, not merely any username.
+
+Then the fix broke the check that guards the fix: `rig-doctor`'s
+`check_scd_sample_roots` reads the roots **out of** `start_and_midi.scd` rather than
+hardcoding them — the right design, and the only reason this class of bug was ever
+caught — but it called `Path.is_dir()` on the extracted literal, and **Python does
+not expand a tilde either**. Three PASSes became three false FAILs on the box where
+all three roots exist. **A checker that derives its expectations from the source it
+checks is strictly better than one with hardcoded copies, and it still shares that
+source's bugs, one runtime removed.**
+
+Separately, `tools/rig-install.sh` had shipped as mode **100644** for its entire
+life. It worked on the authoring laptop because the author had chmod'd it there and
+never committed that, so the first command of `SETUP.md`'s fast path died
+"permission denied" on the one machine the script exists to serve. Five other
+tracked `.sh` files had the same mode. Fixing six without a guard just waits for the
+seventh, so `tools/tests/test_scripts_are_executable.py` reads modes from
+`git ls-files -s` — **the index, the only mode that travels** — pins the five named
+entrypoints so a rename cannot quietly drop one, and guards itself against an empty
+listing reading as success. Mutation-verified in both directions.
+
+**Deps.** Blocked #16 and #29. The remaining portability work for a **non-`pln`
+account** — which is the friend-with-the-LCXL2 case — is SRE `#84` phases 3-6.