feat(gig-up): clear the session's dead references before Ardour opens

The Missing File modal is one dialog per dead source, cannot be suppressed by a
flag, and sits between a click and a playable rig (#136). On 2026-09-06 it cost a
launch outright — and invisibly, because launch_bin throws app output at
/dev/null: Ardour sat for 13 minutes with 0.08s of CPU and no window at all,
while the only thing that could have said why went to the bit bucket.

So gig-up sweeps the session before opening it, never while it is open (Ardour
saves its in-memory session over the edit on quit and would undo it). Idempotent:
a clean session prints "nothing to do" and writes nothing.

The mount check IS the safety story. --allow-archived overrides the tool's "this
survives elsewhere, restore it instead of dropping the reference" refusal — the
right answer for an accident, the wrong one for deliberate archival, and the only
thing telling those apart is whether the archive is actually there. With the
mirror unmounted the tool cannot distinguish a filed take from a lost one, so it
is never handed the flag. A reference is the last breadcrumb pointing at a take;
dropping one blind turns a restore into a forensics job. Neither branch ever
blocks the gig.

Also writes down what tonight cost, in the cheatsheet where it will be reread at
setup rather than in a log nobody opens mid-gig: Ardour's per-port Incoming MIDI
gates the faders no matter how right everything else is; which of the three LCXL
ports is the correct one and why the other two are wrong; that no-sound-no-
highlight is a stale GHCi (tidalcycles:reboot) and not the rig; and that
boot-superdirt would start a second SuperDirt to fight parvagues-sc for :57120.

docs/GIG-CHEATSHEET.md

@@ -105,3 +105,39 @@ and `gF<N>` carrying different numbers on the same orbit is CORRECT.
 An orbit a track does **not** declare is not silent by default — it keeps
 playing whatever the previous track put there. When a transition sounds
 wrong, that is the first thing to suspect.
+
+## When it looks dead — setup gotchas (learned 2026-09-06, mid-setup)
+
+**Faders move nothing in Ardour.** Ardour's *per-port* **Incoming MIDI** must be
+ON for `ParVagues LCXL3`. Everything else can be perfect — right port selected,
+Generic MIDI active, board lit — and the faders still do nothing, because that
+one checkbox gates the port. PLN: "it was incoming midi off, once on parvagues
+lcxl3 its working".
+
+**Which MIDI port Ardour must use: `ParVagues LCXL3`.** That is the driver's
+*translated* v2 stream, and it is the same one SuperCollider reads, so Ardour and
+Tidal hear identical control. Never the other two:
+- `LCXL3 1 DAW In` — the driver owns it in both directions and it speaks the v3
+  DAW protocol. Two apps fighting for the board is what gig-up's ordering exists
+  to prevent.
+- `Midi Through` — fed by the driver *and* the raw board, so it carries a
+  doubled, half-untranslated stream.
+
+**No sound and no highlight in Pulsar.** The GHCi session is stale, not the rig.
+Run **`tidalcycles:reboot`** from the command palette — it respawns GHCi and
+re-feeds `BootTidal.hs`. Check the rig first if you like: `tools/check-boot.sh`
+typechecks the boot file, and `journalctl --user -u parvagues-sc` shows
+"reading soundfile as needed: ..." when SuperDirt is genuinely playing.
+
+> **Never run `tidalcycles:boot-superdirt`.** `parvagues-sc` already owns
+> :57120. That command starts a SECOND SuperDirt to fight it for the port.
+
+**The board went dark after an unplug/replug.** It now heals itself within one
+reconcile tick (~5s) — the driver re-subscribes, re-asserts DAW mode and
+repaints. If it stays dark past ~10s, `systemctl --user restart lcxl3-driver`.
+
+**Ardour's "Missing Plugins" dialog.** Safe to OK through: none of them sit on a
+Tidal orbit. `LSP Spectrum Analyzer x1` is on Master but is *metering*, not
+processing; `ZynAddSubFX` is on **Keys**; `ZynDynamicFilter` and `ZynReverb` are
+on **Mic** and both already bypassed (`active=0`). To get them back:
+`sudo apt install lsp-plugins-lv2 zynaddsubfx-lv2`.

gig-up.sh

@@ -264,6 +264,52 @@ leds(){
 }
 leds
 
+# 2.5) Session hygiene — the jig must open with NO data and NO modal.
+#
+# Ardour's "Missing File" dialog is one modal per dead source, cannot be
+# suppressed by a flag, and stands between a click and a playable rig (#136).
+# On 2026-09-06 it cost a launch outright: Ardour sat there for 13 minutes with
+# 0.08s of CPU and no window at all, because gig-up throws app output at
+# /dev/null and nobody could see it was waiting on a dialog.
+#
+# It runs BEFORE Ardour opens and never while it is open — Ardour saves its
+# in-memory session over the edit on quit and would silently undo the whole
+# thing. Idempotent: with a clean session the tool says "nothing to do" and
+# writes nothing, so this costs one python start per gig.
+#
+# WHY THE MOUNT CHECK IS THE SAFETY STORY. --allow-archived overrides the tool's
+# "this file survives elsewhere, restore it instead of dropping the reference"
+# refusal. That refusal is the RIGHT answer for an accident and the WRONG one
+# for deliberate archival, and the only thing distinguishing the two is whether
+# the archive is actually there to have archived to. With the mirror unmounted
+# the tool cannot tell a filed take from a lost one, so it is never given the
+# flag — a reference is the last breadcrumb pointing at a take, and dropping one
+# blind turns a restore into a forensics job. Never blocks the gig either way.
+MIRROR="${MIRROR:-/mnt/freebox/PLN}"
+sweep_session(){
+  local tool="$DIR/tools/ardour-drop-missing-sources.py"
+  [ -f "$ARDOUR_SESSION" ] && [ -f "$tool" ] || return 0
+  if ardour_up; then
+    info "session sweep: skipped — Ardour is already open (it would overwrite the edit)."
+    return 0
+  fi
+  if [ ! -d "$MIRROR" ]; then
+    warn "session sweep: mirror absent ($MIRROR) — refusing to clear references blind."
+    return 0
+  fi
+  local out
+  if out=$(python3 "$tool" "$ARDOUR_SESSION" --apply --allow-archived 2>&1); then
+    if printf '%s' "$out" | grep -q "nothing to do"; then
+      ok "session sweep: session is already a clean jig — no modal to remove."
+    else
+      ok "session sweep: $(printf '%s' "$out" | grep -E '^(would drop|written)' | tr '\n' ' ')"
+    fi
+  else
+    warn "session sweep: declined — $(printf '%s' "$out" | tail -1)"
+  fi
+}
+sweep_session
+
 # 3) Ardour — now safe to open (SuperDirt already holds the controller)
 if ardour_up; then
   ok "Ardour already running — skipping."