feat(harness): agent-drivable dev harness and CI that gates

A coding agent could develop this repo's Go packages and could not
develop the application: every path to running YellowJacket ended in a
blocking GTK window, so 265 bound methods, 46 events, 33 component
directories and 13 stores had exactly one form of verification
available — `tsc --noEmit`.

The unlock is that `wails dev`'s dev server on :34115 serves the real
frontend with the real generated bindings against the same Go backend a
desktop window attaches to, so a plain Chromium under Xvfb gets a fully
functional app. Four test tiers now exist, cheapest first:

- `make ui-test` — 313 Vitest tests in a real browser in ~2 s, no app,
  no backend, no display. Works because `frontend/wailsjs/` is a pure
  passthrough to `window.go`/`window.runtime`, so faking just those two
  globals runs the real bindings and the real store code.
- `make test` — services in-process, asserting on the payload the
  frontend would receive, via a new `events.Emit` wrapper.
- `make dev-headless` + `playwright-cli` — the real app, driven
  interactively, with an event bridge on `window.__yjEvents` and a
  dev-only control surface at `/__test/`.
- `make e2e` — 19 of those flows frozen as Playwright specs.

`events.Emit(ctx, …)` replaces all 35 direct `runtime.EventsEmit` call
sites: wails' `getEvents` `log.Fatalf`s on any context without its
runtime, so those paths could not run under test and a background
worker could take the app down. Four packages had each hand-rolled the
same guard; nine more guarded on `ctx != nil`, which does not help.
`TestNoDirectRuntimeEmits` fails the build on a new one.

Fixtures are generated, not committed (`make testdata`), and seeds are
built by *running the app* — never by hand-writing config and DB rows,
which would be a second description of a valid YJ_HOME.

`.gitea/workflows/ci.yml` is the first workflow here that tests
anything; the other three only package, so `gitea_ci` reported only
packaging jobs and misled anyone asking whether a push was healthy.
Both jobs were prototyped to green in a bare ubuntu:24.04 container
before the YAML was written, which immediately caught `make lint`
linting three configurations that nothing builds: all three passes
omitted `webkit2_41`, so wails resolved webkit2gtk-4.0 — which Arch
still ships and Ubuntu 24.04 dropped.

Operational instructions live in `.pi/skills/yellowjacket-dev/`,
measured discoveries in `.planning/NOTES.md`, and architecture in
`CLAUDE.md` — split by tense, not by topic, because a topical split
gives every new fact two plausible homes. `make skill-check` fails a
commit if the skill cites a make target that does not exist.

backend/events/emit.go

@@ -0,0 +1,90 @@
+package events
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+
+	"github.com/wailsapp/wails/v2/pkg/runtime"
+)
+
+// ErrNoRuntime is returned by Deliver when the context carries neither
+// a test Sink nor a live Wails runtime, so the event went nowhere.
+var ErrNoRuntime = errors.New(
+	"no Wails runtime or event sink in context",
+)
+
+// Sink receives events in place of the Wails runtime.
+//
+// Installing one with WithSink is what makes a service that emits
+// events testable in-process: see Deliver for why the real runtime
+// cannot be used there.
+type Sink interface {
+	Emit(name string, data ...any)
+}
+
+// sinkKey is the private context key an installed Sink is stored under.
+type sinkKey struct{}
+
+// WithSink returns a context whose events are recorded by sink rather
+// than pushed to the frontend.
+//
+// The sink travels in the context rather than in a package-level
+// variable so that parallel tests cannot observe each other's events
+// and so that production emits pay no synchronisation cost.
+func WithSink(ctx context.Context, sink Sink) context.Context {
+	return context.WithValue(ctx, sinkKey{}, sink)
+}
+
+// sinkFrom returns the Sink installed in ctx, or nil.
+func sinkFrom(ctx context.Context) Sink {
+	sink, _ := ctx.Value(sinkKey{}).(Sink)
+
+	return sink
+}
+
+// Emit publishes a Wails event, tolerating any context.
+//
+// This is the only supported way to emit an event: nothing outside this
+// package may call runtime.EventsEmit, which TestNoDirectEventsEmit
+// enforces.
+//
+// runtime.EventsEmit calls log.Fatalf when the context is nil or lacks
+// the runtime's "events" value, terminating the process rather than
+// returning an error.  Background workers that outlive a context, and
+// any test that constructs a service directly, both hit that path — so
+// an event with nowhere to go is dropped and logged here instead.
+func Emit(ctx context.Context, name string, data ...any) {
+	if err := Deliver(ctx, name, data...); err != nil {
+		slog.Default().Debug(
+			"dropping event, no Wails runtime in context",
+			"event", name,
+		)
+	}
+}
+
+// Deliver is Emit for the one caller that must know whether delivery
+// happened: the dev control surface (backend/testctl), whose whole
+// purpose is to impersonate a backend emit and which would otherwise
+// report success for an event that went nowhere.
+//
+// Ordinary emitters want Emit.
+func Deliver(ctx context.Context, name string, data ...any) error {
+	if ctx == nil {
+		return ErrNoRuntime
+	}
+
+	if sink := sinkFrom(ctx); sink != nil {
+		sink.Emit(name, data...)
+
+		return nil
+	}
+
+	if ctx.Value("events") == nil {
+		return ErrNoRuntime
+	}
+
+	runtime.EventsEmit(ctx, name, data...)
+
+	return nil
+}

backend/events/emit_test.go

@@ -0,0 +1,186 @@
+package events_test
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	"yellowjacket/backend/events"
+)
+
+func TestEmitDropsWithoutRuntimeOrSink(t *testing.T) {
+	t.Parallel()
+
+	// The point of the wrapper: neither of these may reach
+	// runtime.EventsEmit, which would log.Fatalf and take the test
+	// binary down with it.
+	events.Emit(context.Background(), events.QueueChanged, "payload")
+
+	//nolint:staticcheck // a nil context is the case under test.
+	events.Emit(nil, events.QueueChanged, "payload")
+}
+
+func TestDeliverReportsMissingRuntime(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		ctx  context.Context
+	}{
+		{name: "nil context", ctx: nil},
+		{name: "no runtime", ctx: context.Background()},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := events.Deliver(tt.ctx, events.QueueChanged)
+			if !errors.Is(err, events.ErrNoRuntime) {
+				t.Fatalf("got %v, want ErrNoRuntime", err)
+			}
+		})
+	}
+}
+
+func TestSinkReceivesEmittedEvents(t *testing.T) {
+	t.Parallel()
+
+	rec := events.NewRecorder()
+	ctx := events.WithSink(context.Background(), rec)
+
+	events.Emit(ctx, events.QueueChanged, "one")
+	events.Emit(ctx, events.VolumeChanged, 42)
+
+	if err := events.Deliver(ctx, events.TrackChanged); err != nil {
+		t.Fatalf("Deliver with a sink installed: %v", err)
+	}
+
+	want := []string{
+		events.QueueChanged,
+		events.VolumeChanged,
+		events.TrackChanged,
+	}
+
+	got := rec.Names()
+	if len(got) != len(want) {
+		t.Fatalf("recorded %v, want %v", got, want)
+	}
+
+	for i := range want {
+		if got[i] != want[i] {
+			t.Errorf("event %d = %q, want %q", i, got[i], want[i])
+		}
+	}
+
+	ev, ok := rec.Last(events.VolumeChanged)
+	if !ok {
+		t.Fatal("VolumeChanged not recorded")
+	}
+
+	if ev.Payload() != 42 {
+		t.Errorf("VolumeChanged payload = %v, want 42", ev.Payload())
+	}
+}
+
+func TestRecorderPayloadOfArgumentlessEvent(t *testing.T) {
+	t.Parallel()
+
+	rec := events.NewRecorder()
+	rec.Emit(events.SeekFailed)
+
+	ev, ok := rec.Last(events.SeekFailed)
+	if !ok {
+		t.Fatal("SeekFailed not recorded")
+	}
+
+	if ev.Payload() != nil {
+		t.Errorf("payload = %v, want nil", ev.Payload())
+	}
+}
+
+func TestRecorderWaitSeesEventsAlreadyRecorded(t *testing.T) {
+	t.Parallel()
+
+	rec := events.NewRecorder()
+	rec.Emit(events.LibraryScanComplete, 31)
+
+	ev, ok := rec.Wait(events.LibraryScanComplete, time.Second)
+	if !ok {
+		t.Fatal("Wait missed an event recorded before the call")
+	}
+
+	if ev.Payload() != 31 {
+		t.Errorf("payload = %v, want 31", ev.Payload())
+	}
+}
+
+func TestRecorderWaitBlocksForBackgroundEmit(t *testing.T) {
+	t.Parallel()
+
+	rec := events.NewRecorder()
+	ctx := events.WithSink(context.Background(), rec)
+
+	go func() {
+		time.Sleep(10 * time.Millisecond)
+		events.Emit(ctx, events.LibraryScanProgress, 1)
+		events.Emit(ctx, events.LibraryScanComplete, 2)
+	}()
+
+	if _, ok := rec.Wait(events.LibraryScanComplete, 2*time.Second); !ok {
+		t.Fatal("Wait timed out on a background emit")
+	}
+}
+
+func TestRecorderWaitTimesOut(t *testing.T) {
+	t.Parallel()
+
+	rec := events.NewRecorder()
+
+	if _, ok := rec.Wait(events.QueueChanged, 20*time.Millisecond); ok {
+		t.Fatal("Wait returned an event that was never emitted")
+	}
+}
+
+func TestRecorderIsConcurrencySafe(t *testing.T) {
+	t.Parallel()
+
+	rec := events.NewRecorder()
+	ctx := events.WithSink(context.Background(), rec)
+
+	const emitters, each = 8, 25
+
+	var wg sync.WaitGroup
+
+	wg.Add(emitters)
+
+	for range emitters {
+		go func() {
+			defer wg.Done()
+
+			for range each {
+				events.Emit(ctx, events.QueueChanged, 1)
+			}
+		}()
+	}
+
+	wg.Wait()
+
+	if got := rec.Count(events.QueueChanged); got != emitters*each {
+		t.Errorf("recorded %d events, want %d", got, emitters*each)
+	}
+}
+
+func TestRecorderReset(t *testing.T) {
+	t.Parallel()
+
+	rec := events.NewRecorder()
+	rec.Emit(events.QueueChanged)
+	rec.Reset()
+
+	if got := rec.Events(); len(got) != 0 {
+		t.Errorf("after Reset: %v, want empty", got)
+	}
+}

backend/events/noemit_test.go

@@ -0,0 +1,85 @@
+package events_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// allowedEmitters are the only files permitted to call the Wails
+// runtime's event emitter directly.
+var allowedEmitters = map[string]bool{
+	filepath.Join("backend", "events", "emit.go"): true,
+}
+
+// TestNoDirectRuntimeEmits fails if anything outside backend/events
+// calls the Wails runtime's event emitter directly.
+//
+// This is a text walk rather than a golangci-lint rule because
+// golangci-lint runs once per build configuration, so a call in an
+// indexbuild- or dev-tagged file is only seen by the pass that compiles
+// it.  Walking the tree sees all three, plus anything tagged out
+// entirely.
+func TestNoDirectRuntimeEmits(t *testing.T) {
+	// A selector, not a bare name: built at runtime so this file does
+	// not match itself, and qualified so it catches every import alias
+	// the tree uses (plain runtime., and wailsruntime.) without also
+	// matching an identifier that merely ends in the same letters.
+	needle := ".Events" + "Emit("
+
+	root := filepath.Join("..", "..")
+
+	skipDirs := map[string]bool{
+		".git":         true,
+		"node_modules": true,
+		"frontend":     true,
+		"build":        true,
+	}
+
+	err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+
+		if d.IsDir() {
+			if skipDirs[d.Name()] {
+				return filepath.SkipDir
+			}
+
+			return nil
+		}
+
+		if filepath.Ext(path) != ".go" {
+			return nil
+		}
+
+		rel, relErr := filepath.Rel(root, path)
+		if relErr != nil {
+			return relErr
+		}
+
+		if allowedEmitters[rel] {
+			return nil
+		}
+
+		src, readErr := os.ReadFile(path)
+		if readErr != nil {
+			return readErr
+		}
+
+		for i, line := range strings.Split(string(src), "\n") {
+			if strings.Contains(line, needle) {
+				t.Errorf(
+					"%s:%d calls the Wails emitter directly; use events.Emit\n\t%s",
+					rel, i+1, strings.TrimSpace(line),
+				)
+			}
+		}
+
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("walking %s: %v", root, err)
+	}
+}

backend/events/recorder.go

@@ -0,0 +1,153 @@
+package events
+
+import (
+	"sync"
+	"time"
+)
+
+// Event is one recorded emission.
+type Event struct {
+	Name string
+	Data []any
+}
+
+// Payload returns the single data argument almost every event carries,
+// or nil for the handful emitted with none.
+func (e Event) Payload() any {
+	if len(e.Data) == 0 {
+		return nil
+	}
+
+	return e.Data[0]
+}
+
+// Recorder is a Sink that buffers events for later assertion.
+//
+// It is safe for concurrent use: several services emit from background
+// goroutines, and Wait exists so a test can block on one of those
+// rather than sleep.
+type Recorder struct {
+	mu     sync.Mutex
+	events []Event
+
+	// notify is closed and replaced on every emit, so waiters wake
+	// without the Recorder having to track them individually.
+	notify chan struct{}
+}
+
+// NewRecorder returns an empty Recorder.
+func NewRecorder() *Recorder {
+	return &Recorder{notify: make(chan struct{})}
+}
+
+// Emit implements Sink.
+func (r *Recorder) Emit(name string, data ...any) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.events = append(r.events, Event{Name: name, Data: data})
+
+	close(r.notify)
+	r.notify = make(chan struct{})
+}
+
+// Events returns every event recorded so far, in order.
+func (r *Recorder) Events() []Event {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	return append([]Event(nil), r.events...)
+}
+
+// Named returns every recorded event with the given name, in order.
+func (r *Recorder) Named(name string) []Event {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	var out []Event
+
+	for _, ev := range r.events {
+		if ev.Name == name {
+			out = append(out, ev)
+		}
+	}
+
+	return out
+}
+
+// Names returns the name of every recorded event, in order.
+//
+// Assertions read better against this than against Events when what
+// matters is which events fired and in what order.
+func (r *Recorder) Names() []string {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	out := make([]string, 0, len(r.events))
+	for _, ev := range r.events {
+		out = append(out, ev.Name)
+	}
+
+	return out
+}
+
+// Count returns how many times the named event was recorded.
+func (r *Recorder) Count(name string) int {
+	return len(r.Named(name))
+}
+
+// Last returns the most recent event with the given name.
+func (r *Recorder) Last(name string) (Event, bool) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	for i := len(r.events) - 1; i >= 0; i-- {
+		if r.events[i].Name == name {
+			return r.events[i], true
+		}
+	}
+
+	return Event{}, false
+}
+
+// Reset discards everything recorded so far.
+func (r *Recorder) Reset() {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.events = nil
+}
+
+// Wait blocks until an event with the given name is recorded, and
+// returns it.  It returns false if timeout elapses first.
+//
+// Events already recorded count, so a test cannot lose a race by
+// calling Wait after the emit it is waiting for.
+func (r *Recorder) Wait(name string, timeout time.Duration) (Event, bool) {
+	deadline := time.After(timeout)
+	from := 0
+
+	for {
+		r.mu.Lock()
+
+		for i := from; i < len(r.events); i++ {
+			if r.events[i].Name == name {
+				ev := r.events[i]
+				r.mu.Unlock()
+
+				return ev, true
+			}
+		}
+
+		from = len(r.events)
+		notify := r.notify
+
+		r.mu.Unlock()
+
+		select {
+		case <-notify:
+		case <-deadline:
+			return Event{}, false
+		}
+	}
+}