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/testctl/handlers_dev.go

@@ -0,0 +1,199 @@
+//go:build dev
+
+package testctl
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"yellowjacket/backend/events"
+	"yellowjacket/backend/system"
+)
+
+// handleHealth answers the one question every spec starts with: is the
+// backend up, and is it looking at the library it should be?
+//
+// The frontend can answer parts of this, but only after it has rendered
+// — which is exactly the thing under test.  This answers before a
+// single component has mounted, so it is usable as a gate.
+func handleHealth(d Deps, _ *http.Request) (any, error) {
+	out := map[string]any{
+		"ok":      true,
+		"home":    os.Getenv("YJ_HOME"),
+		"dbPath":  dbPath(),
+		"pid":     os.Getpid(),
+		"context": d.Context() != nil,
+	}
+
+	counts := map[string]int64{}
+
+	for table, query := range map[string]string{
+		"tracks":       "SELECT COUNT(*) FROM audio_files",
+		"libraries":    "SELECT COUNT(*) FROM libraries",
+		"playlists":    "SELECT COUNT(*) FROM playlists",
+		"queueTracks":  "SELECT COUNT(*) FROM queue_tracks",
+		"exploreIndex": "SELECT COUNT(*) FROM explore_index",
+	} {
+		var n int64
+		if err := d.DB.QueryRowWriter(query).Scan(&n); err != nil {
+			counts[table] = -1
+
+			continue
+		}
+
+		counts[table] = n
+	}
+
+	out["counts"] = counts
+
+	libs, err := libraryRows(d)
+	if err != nil {
+		return nil, err
+	}
+
+	out["libraries"] = libs
+
+	return out, nil
+}
+
+// libraryRows lists the configured libraries by name and path, so a
+// spec can assert it is driving the fixture library and not somebody's
+// real music collection.
+func libraryRows(d Deps) ([]map[string]any, error) {
+	rows, err := d.DB.QueryContext(
+		"SELECT id, name, path FROM libraries ORDER BY id",
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	out := []map[string]any{}
+
+	for rows.Next() {
+		var (
+			id         int64
+			name, path string
+		)
+
+		if err := rows.Scan(&id, &name, &path); err != nil {
+			return nil, err
+		}
+
+		out = append(out, map[string]any{
+			"id": id, "name": name, "path": path,
+		})
+	}
+
+	return out, rows.Err()
+}
+
+// handleEmit pushes a backend event into every connected frontend.
+//
+// This is the biggest lever the surface has.  Half this app is
+// push-driven, and several of those events are only produced by work
+// that takes minutes to hours (a full scan, a download, an artifact
+// import).  Emitting one directly renders the view that consumes it
+// without staging the work that would normally produce it.
+//
+//	POST /__test/emit  {"name":"LibraryScanProgress","data":[{"...":1}]}
+func handleEmit(d Deps, r *http.Request) (any, error) {
+	var body struct {
+		Name string `json:"name"`
+		Data []any  `json:"data"`
+	}
+
+	if err := decode(r, &body); err != nil {
+		return nil, err
+	}
+
+	if body.Name == "" {
+		return nil, errNoEventName
+	}
+
+	// events.Deliver rather than events.Emit: an ordinary emitter wants
+	// an event with nowhere to go dropped, but this endpoint exists to
+	// impersonate one, and reporting a 200 for an event that never
+	// reached a frontend would send a caller debugging the wrong half of
+	// the app.
+	if err := events.Deliver(d.Context(), body.Name, body.Data...); err != nil {
+		return nil, fmt.Errorf("emit %s: %w", body.Name, err)
+	}
+
+	return map[string]any{"emitted": body.Name, "args": len(body.Data)}, nil
+}
+
+// handleSQL runs a statement against the writer connection.
+//
+// One general escape hatch rather than a bespoke endpoint per piece of
+// forced state — "mark this track played", "insert a wanted-list row",
+// "age this cache entry" — each of which would otherwise arrive one at
+// a time and never be removed.
+//
+//	POST /__test/sql  {"sql":"UPDATE ...","args":[1,"x"]}
+func handleSQL(d Deps, r *http.Request) (any, error) {
+	var body struct {
+		SQL  string `json:"sql"`
+		Args []any  `json:"args"`
+	}
+
+	if err := decode(r, &body); err != nil {
+		return nil, err
+	}
+
+	if body.SQL == "" {
+		return nil, errNoSQL
+	}
+
+	// Route by statement kind rather than by trying one and falling
+	// back: the read pool is opened query_only, so sending a write
+	// there fails in a way that looks like a bug in the caller's SQL.
+	if isQuery(body.SQL) {
+		rows, err := d.DB.QueryContextWith(r.Context(), body.SQL, body.Args...)
+		if err != nil {
+			return nil, err
+		}
+
+		defer func() { _ = rows.Close() }()
+
+		return scanAll(rows)
+	}
+
+	res, err := d.DB.ExecContext(body.SQL, body.Args...)
+	if err != nil {
+		return nil, err
+	}
+
+	affected, err := res.RowsAffected()
+	if err != nil {
+		return nil, err
+	}
+
+	return map[string]any{"rowsAffected": affected}, nil
+}
+
+// isQuery reports whether a statement returns rows.
+func isQuery(sql string) bool {
+	first, _, _ := strings.Cut(strings.TrimSpace(sql), " ")
+
+	switch strings.ToUpper(first) {
+	case "SELECT", "WITH", "PRAGMA", "EXPLAIN":
+		return true
+	default:
+		return false
+	}
+}
+
+// dbPath reports where the SQLite file lives, mirroring database.NewDB.
+func dbPath() string {
+	dir, err := system.GetUserDataDirPath()
+	if err != nil {
+		return ""
+	}
+
+	return filepath.Join(dir, "yj.db")
+}