docs(archive): ten completed tasks from the 09-05/06 session

Written as long-form learning rather than a list, per the archive's own
convention — these are blog and video source material, and the learnings are
the half worth keeping.

The through-line of the session, visible only once the entries sit together:
five separate failures where a CHECK was the broken thing, not the system it
watched. The delete verifier reporting 0/14 for fourteen successful deletions.
Six test suites green because they ran nothing. An assertion with an
always-true escape clause. A drift guard that had been failing behind an
--ignore flag people were trained to pass. A subagent's ten red tests that were
its own stale checkout.

Nearly committed this append on the wrong base: the shared checkout is on an
older branch whose copy of this file is 162 lines behind master, so appending
there and committing would have DELETED master's most recent entries. Extracted
the block, restored the shared tree byte-identical, re-applied on origin/master
in a worktree. Same lesson as the rest of the session — a stale read makes an
append destructive, and the file being tracked is exactly what hides it.

armada/tasks/completed-archive.md

@@ -1976,3 +1976,210 @@ a number or adding a skip.
 makes every future change verifiable in one command. Leaves one unverified
 follow-up: anything consuming `setlist.entries()` **positionally** was shifted by
 one for a month — `setlist_to_segments.py` is the suspect.
+
+---
+
+# Session 2026-09-05/06 — the OPAL deletes, a closable window, and six hollow suites
+
+*(Board numbering below is that session's local numbering, not continuous with the
+entries above. Commit hashes are the durable handle.)*
+
+## #1 — Consolidate local branches onto master and push
+
+**Description.** Four local branches had accumulated in a shared checkout; PLN asked
+for "no more many branches plz" and a return to master.
+
+**Done.** Four branches → two, master merged with the peer session's rig work. Ended
+the session at two local branches (`master`, `claude/rig-streamline`).
+
+**Learnings.** `git push origin master` from a non-master HEAD is a **silent no-op** —
+it pushes the local `master` ref, which was already current, prints nothing and exits
+0. Four commits landed on a branch instead of master and it went unnoticed for an
+hour. Verify HEAD immediately before every commit in a shared checkout, and verify the
+push moved the remote (`git rev-list --left-right --count origin/master...master` must
+read `0 0`) rather than trusting exit 0. All branch surgery belongs in a temporary
+worktree: the shared tree holds other sessions' and PLN's uncommitted work, and
+`checkout` on a dirty tree is how a repair becomes a clobber.
+
+**Deps.** Precondition for everything else that session.
+
+## #2 — Execute the 14 gated OPAL SoundCloud deletes
+
+**Description.** The private OPAL cuts on SoundCloud were badly trimmed at both ends
+and had to go, with PLN's explicit go: "nothing irreversible but allow all else auto".
+
+**Done.** All 14 deleted and confirmed.
+
+**Learnings.** **SoundCloud deletion is ASYNCHRONOUS.** The DELETE returns 2xx and the
+track stays fetchable for seconds afterwards, so a naive verifier reported
+`0/14 deleted, 0 failed` for fourteen *successful* deletions. Ground truth is counting
+account permalinks: 132 → 118. Also on record: SC will not replace the audio behind an
+existing permalink (a paid feature), which is why re-uploads accumulate generations —
+a tooling problem we own, not a pricing one.
+
+**Deps.** Freed the 8 permalinks that #7 needs.
+
+## #4 — Set the OPAL gig page to as-performed
+
+**Description.** PLN: "opal gig page as performed :)" — 15 tracks, Desire included.
+
+**Done.** `d7dd44c` in www. Added `durationBasis` (performance axis vs release renders)
+and `performedButUnreleased` (Desire).
+
+**Learnings.** **A measurement is a comparison, and an unnamed reference makes it
+wrong.** I called CRIME "2.00 s short" and REVOLUTION "0.65 s short"; both were
+deliberate render padding (`pad_end_s: 2.0`, `reverb_tail_s: 5.0`). The numbers were
+right and the reference was wrong. Name the reference before reporting a delta.
+
+## #5 — Audit setlist_to_segments.py for the positional phantom
+
+**Done.** `7e966a5` — documented that `opal_title_map()` requires tracks.json to be
+as-performed; `segments_v4`'s `perf_track` keys run 1–13 and 15, with a hole at 14.
+Three new tests.
+
+**Learnings.** A **positional** join against a hand-maintained list is a stale binding
+waiting to happen; the hole at 14 is invisible until something enumerates. I also
+mis-attributed a coverage regression (13 → 3) to my own filter change — the real cause
+was **line-number anchors** in `backlog_setlists.py`. A line number into a
+human-edited journal IS a binding, and it rots the moment PLN writes a paragraph.
+
+## #6 — Report the 14 uncatalogued gigs and the mix/ vs tidal-ears overlap
+
+**Done.** Report delivered; 8 of the 14 turned out mechanically catalogueable and
+shipped (`3a7c660` Tidal, `201defc` www): mephisteuf 6, opal-festival-2024 14,
+toplap-solstice-2024 4, 38c3-house-of-tea 12, ensad 9, opal-festival-2025 17,
+39c3-house-of-tea 14, le-vortex 9. Catalogue **25 → 33 gigs**, tracks 81, recorded
+40 → 44. Catalog regenerated in `a4ad075` so the new gigs reach the 36 tracks that
+played them.
+
+**Learnings.** A delegated agent reported **10 test failures** that did not exist — its
+checkout was 26 commits behind, missing the very fixes that made those tests pass. Its
+diagnosis was right in substance and it simply could not see it. Verify a subagent's
+red before acting on it; also verify its *green*. Separately: 13 track names could not
+be resolved mechanically and are flagged `resolved: false, file: null` **in place**
+rather than dropped or guessed — the catalogue must not invent gig metadata.
+
+**Deps.** Fed #11 (the 13 names).
+
+## #8 — Fix the delete verifier's false negative
+
+**Done.** `5d53a1c` in tidal-ears. `confirm_deleted()` polls with exponential backoff
+(0.5 s → 4 s cap) against a timeout, receipts now carry `issued`/`deleted`/
+`unconfirmed`, `--confirm-timeout` flag, exit codes 1=failed / 4=unconfirmed /
+0=confirmed.
+
+**Learnings.** **A broken instrument returns a NUMBER, not an error** — `0/14` looked
+like a result, not a malfunction. State the expected magnitude *before* measuring, so a
+plausible-but-wrong answer is visibly wrong. And a verifier needs a third outcome:
+`INCONCLUSIVE` is not the same as "failed", and collapsing them is what made the tool
+lie. I also guessed the CLI entry point wrong (`tidal_ears.scwrite` exits 0 silently;
+the real path is `tidal_ears.master sc delete`) — an exit 0 with no output is not
+evidence a command exists.
+
+## #9 — midiviz: close X, on-top toggle, stop the stickiness
+
+**Description.** PLN: "ensure i can close midi mon atm it forces on when i want the
+gui/tray to allow run and or close i guess? its too sticky atm ahah"
+
+**Done.** `46709b2`, `fbf3414`, `8e3ef37`, `be61d56`. A close X and on-top pin laid out
+from the right edge with `MIN_TARGET = 18`, `USER_CLOSE_EXIT = 78`, a latch under
+`$XDG_RUNTIME_DIR/parvagues/midiviz.closed`, `launchers.stop()`, a tray `Close ▸`
+submenu, and the reconciler taught to leave a hand-closed unit alone.
+
+**Learnings.** The core insight: **two supervisors were restarting it** — the
+reconciler `rig_units.ensure()` AND systemd `Restart=always` — so informing one
+achieved nothing. Both had to learn the difference between "it crashed" and "the human
+closed it". On the systemd side that is **two keys doing two jobs**:
+`RestartPreventExitStatus=78` stops the restart, and `SuccessExitStatus=78` stops the
+*failure classification* — without the second, a correct close still showed
+`failed (result: exit-code)` in `systemctl`, in `rig --status` and on the Bridge panel,
+which sends the next reader to debug a unit behaving perfectly. I also asserted "a
+clean exit is never restarted", which was true of the old unit and false once the peer
+set `Restart=always`; and my new `_paint_chrome(self, p)` silently shadowed an existing
+`_paint_chrome(self, p, w, h, pulse)`, killing the selftest — renamed `_paint_controls`.
+Hit targets were first laid out 8 px wide, unhittable mid-set.
+
+**Verified on PLN's own close**, not on my tests: journal showed `status=78/CONFIG`
+with no close from me, the latch written the same second, no restart, and
+`rig --ensure` printing *"midiviz inactive because it was CLOSED by hand"*.
+
+**Deps.** Made #10 safe to add (a window you can close is a window you can give an
+audio tap).
+
+## #10 — Spectro layer behind the glyph-rain
+
+**Description.** PLN: "can we overlay behind a basic spectro? that id remove spectro
+VSTs from ardour and wed have our super perf one as overlay on single win?"
+
+**Done.** `504b036` (built as `f1b17c5`, cherry-picked). Default-sink monitor tap via
+`pw-record`, one thread on exact 2560-sample hops, 2048-point rFFT → 40 log bands,
+fast-attack/slow-release, handed to Qt as a **depth-one** latest-frame swap. Painted
+first of eight layers. Off by default twice over: `--spectro`/`s`, and the systemd unit
+deliberately carries no flag. Log `045`.
+
+**Learnings.** Xruns A/B/A, 120 s a window with an identical bed in all three so the
+tap is the only variable: **0 / 0 / 0** added, counters byte-identical. Two corrections
+came back against **my own brief**: the box does *not* have zero cumulative xruns
+(`input.hydra_in` sits at 1965), and SuperCollider was **idle**, so this measures the
+tap on a quiet graph and not under a live set. The A/B/A design survived the wrong
+premise precisely because it compared deltas. The meanest bug: `Popen(bufsize=0)`
+returns a **raw** `FileIO` where `read(n)` is one `os.read` and short reads are normal,
+not exceptional — read as EOF it gave `blocks=0`, **no error recorded**, and a green
+selftest over a backdrop that could never receive a sample.
+
+It cannot retire the Ardour VSTs yet: the matrix cells are opaque over the middle of
+the spectrum, and a backdrop shows the **master bus** so it can never stand in for a
+per-channel analyser mid-chain.
+
+**Deps.** Left #16 (brightness/occlusion, persistence) for PLN's eyes. Gives #14 a
+measured number before the 512-quantum question spends the same headroom twice.
+
+## #12 — Revive test_adversarial.py, and the five suites behind it
+
+**Description.** Twelve tests reporting twelve errors for months. Meant to be one file.
+
+**Done.** tidal-ears `1a5d4f7`: **9 passed / 12 errors → 83 passed / 0 errors**. Tidal
+`7020982`, `8dd2b71`, `f1755c7`: master was **red and unnoticed**, 885 passed / 5
+failed → **892 / 0**. New `tools/tests/test_suite_hygiene.py`. Log `044`.
+
+**Learnings.** Six suites, each hollow differently: `test_*(suite)` requesting a
+nonexistent fixture; 15 assertions at import with no `def test_*` at all; 58 checks
+behind ONE assert; a module-level `sys.exit()` that fires during *collection* and takes
+a whole directory down. The category insight is that **a test suite reports on the
+code and nothing reports on the suite** — hence a guard that walks every test file by
+AST (no imports, so it runs under any interpreter) and floors its own file count,
+because if the glob breaks every rule passes vacuously.
+
+Two sharper edges. **An assertion with an escape clause cannot fail:**
+`assert ranks == sorted(ranks) or len(set(ranks)) == 6` sat in the LED tests for
+months; that ramp has exactly six distinct ranks, so the right clause was always true.
+It was also *concealing something true* — the six-step ramp genuinely doubles back —
+which turned out to be the measured argument for the daylight ramp that replaced it.
+And **an unrunnable check trains people to hide it:** `armada/api` needs its own venv,
+so a root `pytest` gave "Interrupted: 7 errors during collection" and ran *nothing*,
+the habit became `--ignore=armada/api`, and behind that flag the vendored loop grader
+had drifted three fixes behind canonical — the live Fourier API would grade **digital
+silence as tier A**. Re-vendored; a root `conftest.py` now skips with the exact
+command. Root run in the fourier venv: **993 passed**, whole workspace, one command.
+
+Also: **measure counts, never eyeball them.** Three check-counts estimated by eye (18,
+65, 28) were all wrong (15, 58, 22), each caught by the pinned-count guard I had just
+written.
+
+**Deps.** Surfaced #15 (deploy the grader fix) — committed but NOT deployed, since
+Fourier runs on erable and that is PLN's call.
+
+## #13 — Reconcile the stale TODO.md
+
+**Done.** Both "loose ends" verified already satisfied rather than assumed: the tray
+files are tracked, and `/usr/local/sbin/perf-audio` is byte-identical to `perf.sh`.
+Found and pushed 3 unpushed commits on `pulsar-tidalcycles perf/event-highlighter`
+(`ba77c4f..000a183`) to the **pln fork only** — `origin` there is the upstream
+tidalcycles repo.
+
+**Learnings.** Verify a stale doc's claims before acting on them; both items had
+quietly become true. The untracked copy in the shared tree was left alone on purpose —
+it may be another session's notes, and an untracked file that is *tracked on master* is
+exactly what blocked a branch switch earlier the same session.
+
+**Deps.** Remaining items → #14 (needs PLN's eyes on the editor).