internal/router: priority queues so batch jobs yield to interactive requests

The GPU is a size-1 resource, so a single long job monopolises the box for its
whole duration and every interactive request queues behind it. Callers can now
declare intent with an X-LlamaSwap-Priority header and the serial scheduler
dispatches by score instead of by arrival.

- X-LlamaSwap-Priority: signed integer, 0 default, absent/unparseable means 0.
  interactive/normal/batch aliases resolve to +100/0/-100. Values are not
  clamped: the caller composes band and any per-user offset itself.
- serial dispatch score = priority + swap affinity + aging. Bands sit 100 apart
  so a small caller offset orders work inside a band without crossing one;
  aging is unbounded so low-priority work cannot starve.
- routing.scheduler.settings.serial.{agingDivisor,swapAffinityBonus}, defaulting
  to 60s/point and +10. swapAffinityBonus is capped at 99 so it can never
  promote a request into the next band.
- fifo adds the header to its per-model priority, so the header is not silently
  ignored under that scheduler.
- /metrics exports per-band queue depth, oldest wait and dispatch counts, plus
  counters for how often aging or swap affinity changed the pick. Each request
  records its priority, band, score and queue wait in the activity log.

Note swapAffinityBonus defaults to 10, so equal-priority requests for the
already-loaded model now run before older requests that need a swap. Set it to
0 for the previous strict arrival order.

fixes #9

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WUyhZBgv8BBCC5MduX88gE

internal/router/base_test.go

@@ -5,6 +5,7 @@ import (
 	"io"
 	"net/http"
 	"net/http/httptest"
+	"sync"
 	"testing"
 	"time"
 
@@ -12,6 +13,7 @@ import (
 	"github.com/mostlygeek/llama-swap/internal/logmon"
 	"github.com/mostlygeek/llama-swap/internal/process"
 	"github.com/mostlygeek/llama-swap/internal/router/scheduler"
+	"github.com/mostlygeek/llama-swap/internal/shared"
 )
 
 // These tests cover baseRouter's own machinery — the run loop, process
@@ -218,6 +220,76 @@ func TestBaseRouter_ContextCancel(t *testing.T) {
 	}
 }
 
+// TestBaseRouter_SerialPriorityHeader is the end-to-end path for issue #9: the
+// X-LlamaSwap-Priority header on an HTTP request reaches the serial scheduler
+// and changes which queued request runs next.
+//
+// "hold" occupies the single slot. batch and urgent queue behind it in that
+// order; when the slot frees, urgent must go first despite arriving later.
+// urgent blocks inside its handler, so observing urgent's handler entry proves
+// the scheduler chose it — if batch had won, batch's (unblocked) handler would
+// already have run by then.
+func TestBaseRouter_SerialPriorityHeader(t *testing.T) {
+	hold := newFakeProcess("hold")
+	hold.autoReady = true
+	hold.serveBlock = make(chan struct{})
+	batch := newFakeProcess("batch")
+	batch.autoReady = true
+	urgent := newFakeProcess("urgent")
+	urgent.autoReady = true
+	urgent.serveBlock = make(chan struct{})
+
+	conf := config.Config{HealthCheckTimeout: 5}
+	conf.Routing.Scheduler.Use = "serial"
+	b, err := newBaseRouter("test", conf, map[string]process.Process{
+		"hold": hold, "batch": batch, "urgent": urgent,
+	}, logmon.NewWriter(io.Discard), &stubPlanner{})
+	if err != nil {
+		t.Fatalf("newBaseRouter: %v", err)
+	}
+	b.testProcessed = make(chan struct{}, 64)
+	go b.run()
+
+	releaseHold := sync.OnceFunc(func() { close(hold.serveBlock) })
+	releaseUrgent := sync.OnceFunc(func() { close(urgent.serveBlock) })
+	t.Cleanup(func() {
+		releaseHold()
+		releaseUrgent()
+		if !b.shuttingDown.Load() {
+			_ = b.Shutdown(time.Second)
+		}
+	})
+
+	serve := func(model, priority string) {
+		r := newRequest(model)
+		if priority != "" {
+			r.Header.Set(shared.PriorityHeader, priority)
+		}
+		go b.ServeHTTP(httptest.NewRecorder(), r)
+	}
+
+	serve("hold", "")
+	waitProcessed(t, b.testProcessed, 2) // OnRequest, then the swap completing
+	<-hold.serveStarted
+
+	// Both queue behind hold; batch arrives first.
+	serve("batch", "batch")
+	waitProcessed(t, b.testProcessed, 1)
+	serve("urgent", "interactive")
+	waitProcessed(t, b.testProcessed, 1)
+
+	releaseHold()
+
+	select {
+	case <-urgent.serveStarted:
+	case <-time.After(2 * time.Second):
+		t.Fatal("interactive request never started")
+	}
+	if got := batch.serveCalls.Load(); got != 0 {
+		t.Errorf("batch serveCalls=%d want 0 — the batch job ran before the interactive request", got)
+	}
+}
+
 func TestBaseRouter_ModelNotFound(t *testing.T) {
 	a := newFakeProcess("a")
 	b := newTestBase(t, map[string]process.Process{"a": a}, &stubPlanner{})