launcher: a clean exit is not a launch, so stop letting one look like the other

The only thing ~/.cache/parvagues/gig-up.log has ever contained is gig-up's own
usage text. --help prints the options and exits 0, the window script saw a zero
and closed itself, and the result was indistinguishable from a successful boot:
a terminal that flashes and vanishes. Nothing had been started, which is how it
was noticed at all -- the LCXL stayed dark, because no launch ever reached the
paint step.

The exit code cannot carry this; --help exiting 0 is correct. So the fence is
whether the launcher reached its own last line: every real path prints
'gig-up done', while usage, an unknown option and any early exit do not. On a
zero with no marker the window now holds, names the symptom (no SuperDirt, no
Ardour, no colours on the LCXL) and exits 2.

--quiet is exempt by construction: ok() is a no-op there, because that mode
exists so the Bridge captures only WARN/FAIL. The test suite holds both ends of
the coupling, so rewording gig-up's last line fails loudly instead of turning
every real launch into a held window.

tools/gig-up-window.sh

@@ -37,9 +37,49 @@ mkdir -p "$LOG_DIR"
 # almost always "what did the launch BEFORE this one say".
 [ -f "$LOG" ] && mv -f "$LOG" "$LOG.1"
 
+# Does this invocation promise a completion line? `ok "gig-up done"` is
+# suppressed under --quiet (that mode exists so the Bridge captures only
+# WARN/FAIL), so the marker below is only a fair test when the launcher was
+# asked to speak. The desktop icon never passes --quiet; the Bridge always does.
+expect_done=1
+for a in "$@"; do
+  case "$a" in --quiet|-q) expect_done=0 ;; esac
+done
+
 "$DIR/gig-up.sh" "$@" 2>&1 | tee "$LOG"
 rc=${PIPESTATUS[0]}
 
+# A CLEAN EXIT IS NOT A LAUNCH.
+#
+# 2026-09-22: this log's entire contents were gig-up's own usage text. `--help`
+# prints the options and exits 0, the window saw a zero and closed itself, and
+# the result was indistinguishable from a successful boot -- except that nothing
+# had been started. PLN found it from the surface being dark: "why still no
+# parvagues lcxl colors i see i played gig up and didnt do?". The rig had never
+# been touched, so of course the LCXL was never painted.
+#
+# The fence is therefore not the exit code, it is whether the launcher reached
+# its own last line. Every real path prints `gig-up done` -- stage, headphones
+# and converge alike -- while usage, an unknown option and any early exit do
+# not. Holding the window on that is what turns "it flashed and closed" from a
+# thing you interpret into a thing you read.
+launched=1
+if [ "$expect_done" = 1 ] && ! grep -q 'gig-up done' "$LOG"; then
+  launched=0
+fi
+
+if [ "$rc" -eq 0 ] && [ "$launched" = 0 ]; then
+  printf '\n\033[1;33m● gig-up exited 0 WITHOUT LAUNCHING\033[0m — it printed its usage\n'
+  printf '  and stopped. The rig was NOT started: no SuperDirt, no Ardour, and\n'
+  printf '  no colours on the LCXL.  log: %s\n' "$LOG"
+  printf '  Launch it for real with no arguments:  %s/gig-up.sh\n' "$DIR"
+  if [ -t 0 ]; then
+    printf '  press any key to close this window…\n'
+    read -rsn1 || true
+  fi
+  exit 2
+fi
+
 if [ "$rc" -ne 0 ]; then
   printf '\n\033[1;31m● gig-up exited %s\033[0m — log: %s\n' "$rc" "$LOG"
   # `[ -t 0 ]` so this never wedges a systemd unit or a CI run that happens to

tools/tests/test_launcher_window.py

+"""The launcher window must never let a NON-LAUNCH look like a launch.
+
+2026-09-22, found from the surface being dark rather than from any log: the only
+thing `~/.cache/parvagues/gig-up.log` had ever contained was gig-up's own usage
+text. `--help` prints the options and exits 0; the window saw a zero and closed
+itself; and the result was pixel-for-pixel the same experience as a successful
+boot — a terminal that flashes and vanishes. Nothing had been started, so the
+LCXL was never painted, which is how PLN noticed: "why still no parvagues lcxl
+colors i see i played gig up and didnt do?".
+
+The exit code cannot carry this. `--help` exiting 0 is correct. So the fence is
+"did the launcher reach its own last line", and these tests hold both ends of
+that coupling: the window looks for a marker, and the launcher still prints one.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+WINDOW = os.path.join(ROOT, "tools", "gig-up-window.sh")
+LAUNCHER = os.path.join(ROOT, "gig-up.sh")
+MARKER = "gig-up done"
+
+
+def _run(args, tmp_path):
+    """Run the window script with its log redirected into a tmp dir.
+
+    XDG_CACHE_HOME, not HOME: the script honours it, and pointing HOME at a tmp
+    dir would change what gig-up itself resolves. Nothing here starts a rig —
+    every argument used below makes gig-up exit before it touches anything.
+    """
+    env = dict(os.environ, XDG_CACHE_HOME=str(tmp_path))
+    return subprocess.run(["bash", WINDOW] + args, capture_output=True,
+                          text=True, env=env, timeout=60, stdin=subprocess.DEVNULL)
+
+
+def test_the_launcher_still_prints_the_marker_the_window_looks_for():
+    """The coupling, asserted from both sides. If someone rewords the last line
+    of gig-up.sh, every real launch starts holding a window that says the rig
+    was not started — the failure this test exists to make loud and early."""
+    src = open(LAUNCHER).read()
+    assert src.count(MARKER) >= 1, (
+        f"gig-up.sh no longer prints {MARKER!r}; tools/gig-up-window.sh greps "
+        "for it to tell a launch from a usage print")
+    assert MARKER in open(WINDOW).read()
+
+
+def test_printing_usage_is_reported_as_a_non_launch(tmp_path):
+    r = _run(["--help"], tmp_path)
+    assert r.returncode == 2, "a usage print still exits 0 and closes silently"
+    assert "WITHOUT LAUNCHING" in r.stdout
+    assert "no colours on the LCXL" in r.stdout, (
+        "the message should name the symptom he'd actually see")
+
+
+def test_an_unknown_option_still_fails_loudly(tmp_path):
+    """This path already worked (gig-up exits 2). Kept so the new branch cannot
+    swallow it — an early `exit 0` check that also caught exit 2 would report
+    the wrong reason."""
+    r = _run(["--nonsense"], tmp_path)
+    assert r.returncode == 2
+    assert "unknown option" in (r.stdout + r.stderr)
+
+
+def test_quiet_is_exempt_because_it_silences_the_marker(tmp_path):
+    """`ok()` is a no-op under --quiet — that mode exists so the Bridge captures
+    only WARN/FAIL — so the marker cannot be required there. Asserted on the
+    source rather than by running a real launch, which this suite must not do."""
+    src = open(LAUNCHER).read()
+    assert 'ok(){ [ "$QUIET" = 1 ] ||' in src, (
+        "ok() no longer depends on QUIET; re-check whether the window's "
+        "--quiet exemption is still needed")
+    win = open(WINDOW).read()
+    assert "expect_done=0" in win and "--quiet|-q" in win
+
+
+def test_the_log_is_still_written_for_a_non_launch(tmp_path):
+    """The whole reason this was diagnosable at all. A run that does nothing is
+    exactly the run whose log you want tomorrow."""
+    _run(["--help"], tmp_path)
+    log = tmp_path / "parvagues" / "gig-up.log"
+    assert log.exists() and "gig-up" in log.read_text()