v1.1 review: checklist, probes, three findings

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

AGENTS.md

@@ -21,8 +21,11 @@ implementing it one task at a time.
 ## Files you must never edit
 
 - `PLAN.md`, `docs/plans/`, `AGENTS.md`
-- Anything a task told you to copy from `docs/plans/**/_files/`: tests, testdata, `Makefile`,
-  scripts, `example.toml`, `cmd/fakeupstream`. If a copied test fails, your code is wrong.
+- Anything a task told you to copy from `docs/plans/**/_files/` — in this plan **or any earlier
+  one** — stays protected: tests, testdata, `Makefile`,
+  scripts, `example.toml`, `cmd/fakeupstream`. If a copied test fails, your code is wrong. If a
+  copied test can no longer be right because the new task changes what it tested, that is the
+  owner's error: stop and report it; the owner hands over the replacement.
 
 ## Code rules
 
@@ -41,6 +44,22 @@ implementing it one task at a time.
   compile against them.
 - Comments say why, not what. `gofmt` decides layout; run it before the gate.
 
+## Lessons from earlier reviews
+
+These come from defects found in review; the evidence is in `docs/implementer-log.md`.
+
+- A type assertion on a value that came from outside your package (`w.(http.Flusher)`, a decoded
+  JSON field) uses the two-value form and handles the `false` case. An unchecked assertion is a
+  panic waiting for a caller you did not think of.
+- When a rule says "every" or "everywhere", finish by listing each place it applies and checking
+  them one by one. The task shows one place; the rule covers all of them.
+- Never end a turn by describing what you are about to do. Do it, then report.
+- Work only inside this repository. Scratch programs under `/tmp` or anywhere else are refused
+  by the sandbox, and **a refused tool call is not a reason to end the turn**: write the
+  experiment as a `_test.go` file inside the repository (delete it before committing), or reason
+  it out. Two sessions have ended with a plan and no tool call right after a refusal; that
+  leaves the owner with no commit and no `stopped` row, the worst outcome.
+
 ## The gate
 
 `make gate` must print `gate: ok` before a task is done. It runs offline: `gofmt -l`, `go vet`,
@@ -67,6 +86,6 @@ the commit. Be honest: the log is how the owner judges the process.
 | Status | `done` or `stopped` |
 | Gate runs | How many times you ran `make gate` |
 | First gate | `pass` or `fail` for the first run |
-| Deviations | Anything you did that the task did not say, or `none` |
+| Deviations | Anything you did that the task did not say, or `none`. If your Notes describe a change you made, it belongs here as well — a row that says `none` next to Notes that describe a change is wrong. |
 | Notes | Problems you hit and how you solved them, in one or two sentences |
 | Model | Write `?`. The owner fills this in. |

README.md

@@ -1,8 +1,10 @@
 # crossbar
 
 crossbar is an affinity router in front of several `llama-server` routers. A client's identity is
-the first path segment of its base URL; v0 routes each request to the first healthy host on that
-route's list and streams the answer back unbuffered.
+the first path segment of its base URL — its route. Each conversation takes a sticky lease on one
+host, chosen for the most free slots for its model times weight, and streams the answer back
+incrementally with the usage chunk intact. Pins, drains, queueing, leases and accounting are all
+new in v1.
 
 ## Build
 
@@ -16,22 +18,26 @@ streaming over real HTTP.
 crossbar reads one TOML file. This is `example.toml`:
 
 ```toml
-# crossbar example configuration. Replace <tailnet> and the addresses with your own.
+# crossbar example configuration (v1). Replace <tailnet> and the addresses with your own.
 listen        = "127.0.0.1:17777"   # never 0.0.0.0 — bind the tailnet address in production
+db            = "crossbar.db"       # SQLite: leases + accounting (WAL). /var/lib/crossbar/crossbar.db under systemd
 poll_interval = "1s"                # 60s in production; 1s makes the smoke run quick
-queue_max     = 8
+lease_idle    = "30m"               # a conversation idle this long loses its host
+retention     = "180d"              # per-request rows older than this are rolled up daily
+queue_max     = 1                   # waiting places per (host, model) beyond `parallel`; 503 past that
 
 [hosts.alpha]
 base_url = "http://127.0.0.1:18081"    # e.g. http://straylight.<tailnet>:11434
 weight   = 1.0
-models   = { "ornith-1.5-35b-a3b" = { parallel = 4 }, "small-9b" = { parallel = 6 } }
+models   = { "ornith-1.5-35b-a3b" = { parallel = 1 }, "small-9b" = { parallel = 6 } }
 
 [hosts.beta]
 base_url = "http://127.0.0.1:18082"    # e.g. http://titan.<tailnet>:8081
 weight   = 2.0
-models   = { "ornith-1.5-35b-a3b" = { parallel = 4 } }
+models   = { "ornith-1.5-35b-a3b" = { parallel = 2 } }
 
-# v0: a route is a preference list; the first healthy host that has the model wins.
+# v1: a route is a set of candidate hosts; each conversation gets a sticky lease on the host with
+# the most free slots × weight at the time it starts. Pins and drains come from the admin API.
 [routes.opencode-a]
 hosts         = ["alpha", "beta"]
 default_model = "ornith-1.5-35b-a3b"
@@ -43,12 +49,15 @@ hosts = ["beta", "alpha"]
 | Key | Meaning |
 | --- | --- |
 | `listen` | Where crossbar binds. A tailnet address, never `0.0.0.0`. |
+| `db` | SQLite file holding leases and the accounting rows. |
+| `lease_idle` | A conversation idle this long loses its host. |
+| `retention` | Per-request rows older than this are rolled up daily. |
 | `poll_interval` | How often each host is health-checked. 60s in production; 1s makes the smoke run quick. |
-| `queue_max` | Reserved for v1 queueing; no effect in v0. |
+| `queue_max` | Waiting places per (host, model) beyond `parallel`; a full queue returns 503. |
 | `hosts.<name>.base_url` | The llama-server base URL this host serves. |
-| `hosts.<name>.weight` | Relative share of new routes this host receives. |
+| `hosts.<name>.weight` | Relative share of new requests this host receives. |
 | `hosts.<name>.models` | The models this host serves, with per-model parallel tuning. |
-| `routes.<name>.hosts` | Preference order: the first healthy host that serves the model wins. |
+| `routes.<name>.hosts` | Candidate hosts, tried in order until one is healthy; a conversation leases one of them. |
 | `routes.<name>.default_model` | Model used when a request omits one; must be served by a host in the route. |
 
 ## Run
@@ -84,23 +93,73 @@ custom_providers:
     models: { ornith-1.5-35b-a3b: {} }
 ```
 
-The route name in the URL must exist in `[routes]`; unknown routes are 404.
+The route name in the URL must exist in `[routes]`; unknown routes are 404. A client may instead
+name the route on an `X-Crossbar-Route` header and point at the bare `/v1` base:
 
-## Inspect
-
-`GET /_crossbar/hosts` reports every host's health and loaded models:
-
-```json
-{"alpha":{"healthy":true,"loaded":["ornith-1.5-35b-a3b","small-9b"],"last_ok":"2026-09-25T09:34:18Z","last_err":""},"beta":{"healthy":true,"loaded":["ornith-1.5-35b-a3b"],"last_ok":"2026-09-25T09:34:18Z","last_err":""}}
+```sh
+curl -H 'X-Crossbar-Route: opencode-a' \
+  https://crossbar.<tailnet>:7777/v1/chat/completions
 ```
 
-`GET /_crossbar/routes` reports each route's preference order and default model:
+## Operate
+
+The operator's API lives under `/_crossbar/`. Every call returns 200 with a small JSON body unless
+stated otherwise.
+
+`GET /_crossbar/hosts` reports every host's health, loaded models, live concurrency from the
+limiter and drain state:
 
 ```json
-{"hermes-x":{"hosts":["beta","alpha"],"default_model":""},"opencode-a":{"hosts":["alpha","beta"],"default_model":"ornith-1.5-35b-a3b"}}
+{"alpha":{"healthy":true,"loaded":["ornith-1.5-35b-a3b","small-9b"],"last_ok":"2026-09-25T13:53:25Z","last_err":"","free_slots":7,"in_flight":0,"queued":0,"draining":false},"beta":{"healthy":true,"loaded":["ornith-1.5-35b-a3b"],"last_ok":"2026-09-25T13:53:25Z","last_err":"","free_slots":2,"in_flight":0,"queued":0,"draining":false}}
 ```
 
-## What v0 does not do
+`GET /_crossbar/routes` reports each route's candidate hosts, default model, any pin and its live
+leases:
 
-Leases and stickiness, SQLite, `/slots`, queueing and wake-on-LAN are out of scope for v0; see
-`PLAN.md`.
+```json
+{"hermes-x":{"hosts":["beta","alpha"],"default_model":"","pinned":"","leases":[]},"opencode-a":{"hosts":["alpha","beta"],"default_model":"ornith-1.5-35b-a3b","pinned":"","leases":[]}}
+```
+
+`POST /_crossbar/routes/{route}` pins a route to a host (`{"host":"alpha","pin":true}`) or releases
+it and clears the pin (`{"release":true}`):
+
+```json
+{"ok":true}
+```
+
+`POST /_crossbar/hosts/{host}` sets or clears drain (`{"drain":true}`); a draining host takes no
+new conversations but keeps its existing leases:
+
+```json
+{"ok":true}
+```
+
+`GET /_crossbar/usage` summarizes the accounting rows, grouped by `by=host`, `by=model` or
+`by=route` (the default). Ask for JSON, or a fixed-width table with `Accept: text/plain`:
+
+```json
+[{"key":"beta","requests":2,"errors":0,"busy_ms":4,"queued_ms":0,"prompt_tokens":200,"cached_tokens":180,"completion_tokens":20}]
+```
+
+```
+key        requests errors busy_ms queued_ms prompt cached completion cache_hit
+hermes-x   1        0      1       0         100    90     10         0.90
+opencode-a 1        0      3       0         100    90     10         0.90
+```
+
+`GET /_crossbar/metrics` emits the Prometheus text exposition for request counts, token totals,
+queue wait, host health and live slots:
+
+```
+# TYPE crossbar_requests_total counter
+crossbar_requests_total{route="hermes-x",host="beta",status="200"} 1
+crossbar_requests_total{route="opencode-a",host="beta",status="200"} 1
+# TYPE crossbar_host_healthy gauge
+crossbar_host_healthy{host="alpha"} 1
+crossbar_host_healthy{host="beta"} 1
+```
+
+## What v1 does not do
+
+The context-size guard, wake-on-LAN, Tailscale identity and `/slots` are out of scope for v1; see
+`PLAN.md` v2.

cmd/crossbar/main.go

@@ -17,7 +17,10 @@ import (
 	"git.wntrmute.dev/kyle/crossbar/internal/admin"
 	"git.wntrmute.dev/kyle/crossbar/internal/config"
 	"git.wntrmute.dev/kyle/crossbar/internal/health"
+	"git.wntrmute.dev/kyle/crossbar/internal/lease"
+	"git.wntrmute.dev/kyle/crossbar/internal/limiter"
 	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
 )
 
 func main() {
@@ -38,6 +41,12 @@ func run() error {
 
 	log := slog.New(slog.NewTextHandler(os.Stderr, nil))
 
+	st, err := store.Open(cfg.DB)
+	if err != nil {
+		return err
+	}
+	defer st.Close()
+
 	baseURLs := make(map[string]string, len(cfg.Hosts))
 	for name, host := range cfg.Hosts {
 		baseURLs[name] = host.BaseURL
@@ -48,9 +57,79 @@ func run() error {
 	defer stop()
 	go table.Run(ctx)
 
+	hosts := proxy.HostView(table, cfg)
+	lim := limiter.New()
+	for name, h := range cfg.Hosts {
+		for model, m := range h.Models {
+			lim.Configure(name, model, m.Parallel, cfg.QueueMax)
+		}
+	}
+
+	leases, err := lease.New(st, hosts, proxy.Chooser(cfg, table, lim), cfg.LeaseIdle.Duration)
+	if err != nil {
+		return err
+	}
+	for name, rt := range cfg.Routes {
+		leases.Candidates(name, rt.Hosts)
+	}
+
 	mux := http.NewServeMux()
-	mux.Handle("/_crossbar/", admin.Handler(cfg, table))
-	mux.Handle("/", proxy.New(cfg, table, log))
+	mux.Handle("/_crossbar/", admin.Handler(cfg, table, leases, lim, st, hosts))
+	mux.Handle("/", proxy.New(cfg, table, leases, lim, st, log))
+
+	// Background maintenance until ctx is done. Errors are logged, never fatal.
+	go func() {
+		ticker := time.NewTicker(time.Minute)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				leases.ExpireIdle(time.Now())
+			}
+		}
+	}()
+
+	go func() {
+		ticker := time.NewTicker(time.Hour)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				n, err := st.Prune(time.Now(), cfg.Retention.Duration)
+				if err != nil {
+					log.Error("prune", "err", err)
+					continue
+				}
+				log.Info("pruned request rows", "rows", n)
+			}
+		}
+	}()
+
+	go func() {
+		ticker := time.NewTicker(cfg.PollInterval.Duration)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				for name, s := range table.All() {
+					if err := st.RecordHostHealth(store.HostHealth{
+						TS:      time.Now(),
+						Host:    name,
+						Healthy: s.Healthy,
+						Loaded:  s.Loaded,
+					}); err != nil {
+						log.Error("record host health", "host", name, "err", err)
+					}
+				}
+			}
+		}
+	}()
 
 	srv := &http.Server{
 		Addr:              cfg.Listen,

cmd/fakeupstream/main.go

@@ -1,11 +1,13 @@
 // fakeupstream stands in for a llama-server router in tests and the smoke run. Do not edit.
 //
-//	fakeupstream -listen 127.0.0.1:18081 -name alpha -models a,b -down-file /tmp/alpha.down
+//	fakeupstream -listen 127.0.0.1:18081 -name alpha -models a,b -down-file /tmp/alpha.down -slow 0
 //
 // /health answers 503 while the down file exists, 200 otherwise. /v1/models lists -models.
 // /props answers a small JSON object. /v1/chat/completions echoes: a streamed answer of five
-// SSE chunks 200 ms apart when the body has "stream": true, one JSON answer otherwise. Every
-// response carries X-Upstream: <name>.
+// SSE chunks 200 ms apart when the body has "stream": true, then a final chunk carrying
+// "usage" and llama-server style "timings", then [DONE]; one JSON answer with usage and
+// timings otherwise. -slow adds that many milliseconds before answering (for queue tests).
+// Every response carries X-Upstream: <name>.
 package main
 
 import (
@@ -25,11 +27,14 @@ func main() {
 	name := flag.String("name", "fake", "name reported in X-Upstream and answers")
 	models := flag.String("models", "m", "comma-separated model ids for /v1/models")
 	downFile := flag.String("down-file", "", "while this file exists, /health answers 503")
+	slow := flag.Int("slow", 0, "milliseconds to wait before answering a completion")
 	flag.Parse()
 
 	ids := strings.Split(*models, ",")
 	mux := http.NewServeMux()
 	stamp := func(w http.ResponseWriter) { w.Header().Set("X-Upstream", *name) }
+	usage := map[string]any{"prompt_tokens": 100, "completion_tokens": 10, "total_tokens": 110}
+	timings := map[string]any{"prompt_n": 100, "cache_n": 90, "predicted_n": 10, "predicted_ms": 50.0}
 
 	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
 		stamp(w)
@@ -61,11 +66,12 @@ func main() {
 			Stream bool   `json:"stream"`
 		}
 		_ = json.Unmarshal(body, &req)
+		time.Sleep(time.Duration(*slow) * time.Millisecond)
 		if !req.Stream {
 			writeJSON(w, map[string]any{
 				"id": "chatcmpl-fake", "object": "chat.completion", "model": req.Model,
 				"choices": []map[string]any{{"index": 0, "message": map[string]string{"role": "assistant", "content": "hello from " + *name}, "finish_reason": "stop"}},
-				"usage":   map[string]int{"prompt_tokens": 3, "completion_tokens": 3, "total_tokens": 6},
+				"usage":   usage, "timings": timings,
 			})
 			return
 		}
@@ -73,16 +79,24 @@ func main() {
 		w.Header().Set("Cache-Control", "no-cache")
 		w.WriteHeader(http.StatusOK)
 		fl, _ := w.(http.Flusher)
+		flush := func() {
+			if fl != nil {
+				fl.Flush()
+			}
+		}
 		for i := 1; i <= 5; i++ {
 			chunk := map[string]any{"id": "chatcmpl-fake", "object": "chat.completion.chunk", "model": req.Model,
 				"choices": []map[string]any{{"index": 0, "delta": map[string]string{"content": fmt.Sprintf("%s chunk %d ", *name, i)}}}}
 			b, _ := json.Marshal(chunk)
 			fmt.Fprintf(w, "data: %s\n\n", b)
-			if fl != nil {
-				fl.Flush()
-			}
+			flush()
 			time.Sleep(200 * time.Millisecond)
 		}
+		final := map[string]any{"id": "chatcmpl-fake", "object": "chat.completion.chunk", "model": req.Model,
+			"choices": []map[string]any{}, "usage": usage, "timings": timings}
+		b, _ := json.Marshal(final)
+		fmt.Fprintf(w, "data: %s\n\n", b)
+		flush()
 		fmt.Fprint(w, "data: [DONE]\n\n")
 	})
 	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
@@ -90,7 +104,7 @@ func main() {
 		http.Error(w, `{"error":"not found"}`, http.StatusNotFound)
 	})
 
-	log.Printf("fakeupstream %s listening on %s models=%v", *name, *listen, ids)
+	log.Printf("fakeupstream %s listening on %s models=%v slow=%dms", *name, *listen, ids, *slow)
 	srv := &http.Server{Addr: *listen, Handler: mux, ReadHeaderTimeout: 5 * time.Second}
 	log.Fatal(srv.ListenAndServe())
 }

docs/implementer-log.md

@@ -5,11 +5,22 @@ owner fills in the Model column. The reviewer adds findings under "Reviews" once
 
 | Task | Date | Status | Gate runs | First gate | Deviations | Notes | Model |
 |---|---|---|---|---|---|---|---|
+| v1.1/01-review-fixes | 2026-09-25 | done | 1 | pass | none | Copied `cancel_test.go` and `usage_empty_test.go` byte-identical from `docs/plans/v1.1/_files/`; the earlier session's fixes in `internal/proxy/proxy.go`, `internal/proxy/forward.go` and `internal/admin/admin_ops.go` were already in the working tree. `make gate` printed `gate: ok` on the first run. | llama.cpp/ornith-1.5-35b-a3b |
+| v1/08-smoke-readme | 2026-09-25 | done | 1 | pass | owner-directed fix to `Free` in `proxy.Chooser` | Changed `Free` from `c.lim.FreeSlots(host)` (sum over every model) to per-model free slots, `freeForModel(cfg.Hosts[host], model, c.lim.InFlight(host, model))`, floored at 0 and 0 when the host does not list the model (new helper in hosts.go); the one code change the task directs. `go test -race ./internal/proxy/` and `make gate` pass on the first run; `make smoke` → `smoke: ok (stream spread 1006 ms)`. README intro, `## Configure` (added db/lease_idle/retention, rewrote queue_max and hosts.<name>.hosts) and `## Inspect`→`## Operate` (all six endpoints, examples taken from the smoke run) updated. | llama.cpp/ornith-1.5-35b-a3b |
+| v1/07-main | 2026-09-25 | done | 1 | pass | none | Wired store, limiter and lease table into `cmd/crossbar/main.go`: `store.Open` before the health table, `limiter.Configure` per (host, model) from `cfg.Hosts`, `lease.New` with `proxy.Chooser`, `Candidates` for every route, three background goroutines (idle expiry per minute, prune per hour logging the count, host-health recording per `poll_interval`), and `st.Close` via `defer`. The 3s SIGTERM run exits 0 with `listening`/`shutting down`; the missing-config run exits 1. | llama.cpp/ornith-1.5-35b-a3b |
+| v1/06-admin | 2026-09-25 | done | 2 | fail | Split `internal/admin/admin.go` (196 lines) + `admin_ops.go` (366 lines) to stay under 400. Updated `cmd/crossbar/main.go`'s `admin.Handler` call from the committed 2-arg `(cfg, table)` to the task's 6-arg signature, passing the health table for `hosts` and `nil` for the not-yet-wired `leases`/`limiter`/`store`/`drainer` (task 07 wires them); this was a compile fix required for `go vet`/`go test ./...` on `cmd/crossbar` to pass — the full wiring is task 07. | First `make gate` failed on `go vet` (`admin.Handler` called with 2 args in `main.go` after the signature changed); fixed `main.go` and the gate passed on the second run. `admin_test.go` and `example.toml` verified byte-identical to `docs/plans/v1/_files/`; `internal/lease` and `internal/store` left untouched except the already-present `Candidates`/`StatusCounts`. | llama.cpp/ornith-1.5-35b-a3b |
+| v1/05-proxy | 2026-09-25 | done | 2 | fail | Split `internal/proxy/proxy.go` (411 lines) into `proxy.go` + `forward.go` by moving `forward`, `newReverseProxy`, `forwardState`, `statusRecorder`, `leaseState`, `ttfbMs` and the `writeError`/`writeRecord` helpers to `forward.go`; the one `recorder_test.go` `proxy.New` call changed to `proxy.New(cfg, h, nil, nil, nil, nil)` per the task; `cmd/crossbar/main.go` passes `nil, nil, nil` for the new `leases`/`lim`/`rec` args (task 06 wires them). | The tee in `tee.go` already read the final SSE chunk's (streamed) and the JSON body's (non-streamed) usage/timings, so `TestAccountingRowsFromUsageAndTimings` passed on the first run — the only gate blocker was `proxy.go` at 411 lines. | llama.cpp/ornith-1.5-35b-a3b |
+| v1/04-lease | 2026-09-25 | done | 1 | pass | The given `TestPinAndUnpin` was wrong and replaced by the owner mid-task; the corrected `internal/lease/lease_test.go` is byte-identical to `docs/plans/v1/_files/internal/lease/lease_test.go`. A `fmt.Printf("DEBUG …")` line the prior session left in `event` was removed before the gate. | `Acquire` order (pinned, existing, inherit, choose) with memory rolled back only after a successful save; `Pin` writes a pin event, then the pin row, then deletes other-host leases, so the pin event always precedes the unpin's release event in the log. | llama.cpp/ornith-1.5-35b-a3b |
+| v1/02-fingerprint-config | 2026-09-25 | done | 1 | pass | Switched the existing `TestBadFiles` unknown-key example from `lease_idle` to `bogus_key`, and updated `testdata/bad-unknown-key.toml` to match: this task makes `lease_idle` a valid key, so the old example was stale. `config_test.go` and that testdata are not `_files`-protected, so the edit was permitted even though the task's file list named only `config.go` and `implementer-log.md`; the unknown-key rejection is still covered. | fingerprint.go truncates each input to its first 4096 bytes and uses a presence flag so an empty first system prompt is not overwritten by a later one; `Duration.UnmarshalText` matches `^[0-9]+d$` (regexp) before falling to `time.ParseDuration`. | llama.cpp/ornith-1.5-35b-a3b |
+| v1/01-store | 2026-09-25 | done | 1 | pass | none | Gate passed on the first run once the owner gofmt'd the three previously-un-clean _files plan-tests under docs/plans/v1/_files/; the blocker in the stopped row no longer applies. | llama.cpp/ornith-1.5-35b-a3b |
+| v1/01-store | 2026-09-25 | stopped | 2 | fail | none | Store implemented in `internal/store/store.go` + `schema.go`; `go test -race -count=1 ./internal/store/` is ok and `go vet`/`check-lines` pass. `make gate` cannot print `gate: ok` here: its `gofmt -l .` step flags three committed plan-tests under `docs/plans/v1/_files/` (admin, choose, proxy) that are not gofmt-clean under Go 1.26.7 (formatted by a gofmt that aligns one-line function bodies two columns wider; same diff on a pristine master). They live under `docs/plans/` (must not edit) and the gate covers them; the check cannot be scoped down without weakening it. Code left uncommitted for review. | llama.cpp/ornith-1.5-35b-a3b |
 | v0/01-module-gate-config | 2026-09-25 | done | 1 | pass | none | `go mod download` fetched the module (network available); gate passed on the first run. | llama.cpp/ornith-1.5-35b-a3b |
 | v0/02-health | 2026-09-25 | done | 1 | pass | none | First gate run passed. `MarkDown` initially forgot to write the entry back; caught by `TestMarkDown`. | llama.cpp/ornith-1.5-35b-a3b |
 | v0/03-proxy | 2026-09-25 | done | 1 | pass | none | `SplitRoute` must reject an empty first segment (`/`, `//x`) as `ok=false`; the model peek restores the body and leaves non-JSON/empty as `""`. | llama.cpp/ornith-1.5-35b-a3b |
 | v0/04-admin-main | 2026-09-25 | done | 1 | pass | none | `timeout --signal=TERM 3` exits 124 on a timed-out child on this GNU system, so the task's `exit=0` is not observable through it; sent SIGTERM directly and confirmed crossbar's own exit code is 0 with both log lines. | llama.cpp/ornith-1.5-35b-a3b |
 | v0/05-smoke-readme-deploy | 2026-09-25 | done | 1 | pass | none | `README.md` `## Run` uses `install -m` instead of `cp` and adds `systemctl daemon-reload` before `enable --now`, which is required for systemd to see the new unit; the task said only "copy … then enable --now". | llama.cpp/ornith-1.5-35b-a3b |
+| v0/01-review-fixes | 2026-09-25 | done | 1 | pass | none | `Flush` now two-value. Assertion inventory (`grep -n '\.(' internal/*/*.go`): proxy.go:150 fixed to two-value; proxy_test.go:274 net/http guarantees the server writer is a Flusher. No other unchecked outside assertion. Recorder test panicked before the fix, passed after; config tests passed as-is. | llama.cpp/ornith-1.5-35b-a3b |
+| v1/03-limiter-choose | 2026-09-25 | done | 1 | pass | none | One mutex, a per-(host,model) pair with a FIFO waiter slice; release hands the slot to the head waiter by closing its channel without decrementing inflight, else frees it. A waiter whose ctx ends removes itself and, if the slot was handed in that same instant, gives it back so neither a slot nor a queue place leaks. FreeSlots counts only configured models so an unconfigured pair created by an Acquire does not add a phantom slot. | llama.cpp/ornith-1.5-35b-a3b |
 
 ## Reviews
 
@@ -40,3 +51,50 @@ Follow-ups for a `v0.1` task: fix 1 (`if f, ok := …; ok { f.Flush() }`), add t
 test for 6, and make the log-row rule in `AGENTS.md` say that anything the Notes describe as a
 change belongs in Deviations (finding 3).
 
+### v1 review — 2026-09-25 (reviewer: claude, as owner for the night)
+
+Checked: eight task commits `816614d`, `463cea1`, `7e0dbb4`, `9133240`, `97f7cdf`, `32ac7f5`,
+`d82bfba`, `cf2aa24` with the trailer (plus one `stopped` commit and the owner's merges); every
+given file byte-identical to its plan copy (v1 set, v0.1 set, and the v0 files not replaced;
+`recorder_test.go` against the one owner-permitted edit); protected files untouched against the
+merge base; `make gate` → `gate: ok`; `make smoke` → `smoke: ok (stream spread 1006 ms)`.
+Probed outside the tests: a body whose `messages` is a string → 200 on the route lease; a leased
+host drained *and* killed → 502 once with the host marked down, next turn moves with `lease=new`;
+a second crossbar on the same `db` file → serves the same conversation on the leased host
+(`lease=reused`) with no error; metrics carry the 502; SIGTERM mid-stream lets the stream finish
+(7 SSE lines) and exits 0.
+
+Tally: 8 tasks, 8 committed; first-run gate on 6 of the 8 sessions that reached the gate; 1
+correct `stopped` (task 01, owner's gofmt fault); 3 owner-caused resumes (tasks 01, 04, 05) and 3
+owner-caused restarts (tasks 05, 06 split, 08); 2 model-side process findings (below).
+Wall time ~4 h including the owner's turnaround.
+
+| # | Finding | Severity | Fault |
+|---|---|---|---|
+| 1 | A request whose client disconnects mid-stream writes **no accounting row** (`/usage` stays empty after a cut stream). Task rule 5 said the `ErrorHandler` does nothing on `context.Canceled`; rule 6 said "record what you have when `ServeHTTP` returns" — the second was not applied on that path. Cancelled requests are invisible to usage and error rate. | medium | task (ambiguous) + model (rule not applied everywhere) |
+| 2 | `GET /_crossbar/usage` with no rows answers `null`, not `[]` (spec: a JSON array). | low | model |
+| 3 | Task 02 edited two protected v0 files (fixture invalidated by the new key) with an honest deviation row instead of stopping. Content right, process wrong; the conflict itself was the owner's. | process | model + task |
+| 4 | Task 05's first session ended its turn with a plan and no tool call after the sandbox refused a `/tmp` write (I9). | process | model |
+| 5 | Owner faults, all recorded under "Changes during the run" in the plan README: given files not gofmt-clean; v0 fixture invalidated; pin-event positions; spread tie-break; queue-test read race; dropped test helper; unrecorded `/v1/models`; 433-line given test; task 06 oversized; task 06 text on the gate; chooser free slots summed across models. | — | task/test |
+
+Follow-ups for `v1.1`: fix 1 (record the row on the cancel path with status 499 and `err`), fix 2
+(`[]`), and an acceptance test for each; consider `lease_idle` expiry while a request is in flight
+and `Prune` under concurrent writes, which this review did not probe.
+
+### v1.1 review — 2026-09-25 (reviewer: claude, as owner)
+
+Checked: one task commit `9f5b50a` with the trailer; both given tests byte-identical; protected
+files untouched; `make gate` → `gate: ok`; `make smoke` → `smoke: ok (stream spread 1006 ms)`.
+Probed: `/_crossbar/usage` on an empty store answers `[]`; a stream cut by the client after
+0.4 s appears in `/_crossbar/metrics` as `crossbar_requests_total{…,status="499"} 1`.
+
+Process: four sessions for one task. Sessions 1–3 each ended their turn right after the sandbox
+refused a write or read outside the repository (the I9 pattern) — after the fix was already
+correct, in sessions 2 and 3. Session 3 also chased test flakes caused by its own inference
+loading the host (the owner measured 12/12 passes idle). Findings: (a) model — five
+refusal-endings tonight in total; `AGENTS.md` now names the rule, and the fourth session obeyed
+it; (b) task — the task text did not state that `httputil.ReverseProxy` aborts the handler with
+`http.ErrAbortHandler` on client disconnect, the fact the fix depends on (added mid-run); (c)
+test design — timing-based tests (limiter, queue, spread, cancel) have margins tuned for an idle
+host; widen or retry in a later plan.
+

docs/plans/v0.1/01-review-fixes.md

@@ -0,0 +1,79 @@
+# v0.1 task 01: review fixes — a writer without `Flush`, an unreadable config file
+
+**Branch:** `v0.1` (create it from `master`: `git switch master && git switch -c v0.1`; `git status --short` must be empty first, otherwise stop)
+**Commit subject:** `Review fixes: recorder Flush without panic; unreadable config file is an error`
+
+## What the reviewer observed
+
+1. `internal/proxy/proxy.go`, `statusRecorder.Flush`:
+   ```go
+   func (r *statusRecorder) Flush() {
+       r.ResponseWriter.(http.Flusher).Flush()
+   }
+   ```
+   The assertion is unchecked. Every `http.ResponseWriter` the standard server hands out is a
+   Flusher, but wrappers written by middleware or tests often are not, and then a streamed
+   response **panics inside the reverse proxy** instead of falling back to buffering. The rule
+   "library code never panics on input" applies to every type assertion, including this one.
+   The task text said "forwarding to the underlying `http.Flusher`" and did not say "if it
+   implements it" — that half is the task's fault; the panic is still a defect.
+2. The given `config_test.go` never covered a file that exists but cannot be read. `Load` already
+   handles it (an `open` error wrapped as `config: …`); the suite just did not say so.
+
+## Files
+
+- Copy (never edit afterwards): `internal/proxy/recorder_test.go`,
+  `internal/config/unreadable_test.go`
+- Modify: `internal/proxy/proxy.go`, `docs/implementer-log.md`
+
+## Rules
+
+1. `statusRecorder.Flush` becomes: assert with the two-value form, and call `Flush` only when it
+   is there. Nothing else in the recorder changes.
+   ```go
+   if f, ok := r.ResponseWriter.(http.Flusher); ok {
+       f.Flush()
+   }
+   ```
+2. Then **list every other type assertion in `internal/`** (`grep -n '\.(' internal/*/*.go`) and
+   check each is either the two-value form or on a value you constructed yourself. Put the list,
+   with one word per line saying why it is safe, in your log row's Notes. If you find another
+   unchecked assertion on a value that came from outside the package, fix it the same way and
+   say so in Deviations.
+3. No change to `internal/config`: the two new tests must pass against the code as it is. If one
+   does not, stop and report — that is a finding about `Load`, not something to patch around.
+
+## Steps
+
+- [ ] **1. Branch and copy.**
+
+```sh
+git switch master && git switch -c v0.1
+cp docs/plans/v0.1/_files/internal/proxy/recorder_test.go internal/proxy/
+cp docs/plans/v0.1/_files/internal/config/unreadable_test.go internal/config/
+```
+
+- [ ] **2. See the recorder test fail.** `go test -run WithoutFlusher ./internal/proxy/`.
+  Expected: `FAIL`, with `ServeHTTP panicked on a writer without Flush` (or a panic trace naming
+  `statusRecorder.Flush`). If it passes already, stop and report.
+- [ ] **3. See the config tests pass as they are.** `go test -run 'Unreadable|Directory' ./internal/config/`.
+  Expected: `ok`.
+- [ ] **4. Fix `Flush`** as in rule 1, then do the assertion inventory of rule 2. `gofmt -w internal/proxy/`.
+- [ ] **5. See everything pass.** `go test -race -count=1 ./...`. Expected: all `ok`.
+- [ ] **6. Run the gate.** `make gate`. Expected last line: `gate: ok`.
+- [ ] **7. Log and commit.** Row `v0.1/01-review-fixes`. Anything you changed that these rules
+  did not name goes in **Deviations**, not only in Notes.
+
+```sh
+git add internal/proxy internal/config/unreadable_test.go docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- Step 2 failed before the fix and `go test -race -count=1 ./...` passes after it; `make gate` prints `gate: ok`.
+- `cmp` of both copied tests against `docs/plans/v0.1/_files/…` prints nothing.
+
+## Stop and report if
+
+- Step 2 passes before any change, or step 3 fails: the plan's premise is wrong, and the owner needs to know before code moves.

docs/plans/v0.1/README.md

@@ -0,0 +1,28 @@
+# v0.1 implementation plan: review follow-ups
+
+> **For the implementing model:** do not work from this file. The owner gives you one task file at
+> a time. This file is the index for the owner and the reviewer.
+
+**Goal:** close the findings of the v0 review (`docs/implementer-log.md`, "v0 review"): the
+proxy's status recorder must never panic on a writer without `Flush`, and the acceptance suite
+must cover a configuration file that exists but cannot be read.
+
+**How this plan was made:** acceptance tests first, from the review findings and `PLAN.md`; no
+reference implementation. Both given tests were compiled and run against `master` at the merge of
+`v0`: the recorder test **fails** there (it panics, which is the finding), the config tests pass
+(finding 6 was a gap in the suite, not in the code).
+
+## Tasks
+
+| # | File | Delivers | Tests that define it |
+|---|---|---|---|
+| 01 | `01-review-fixes.md` | `Flush` that degrades instead of panicking; the two config tests | `internal/proxy/recorder_test.go`, `internal/config/unreadable_test.go` |
+
+Branch `v0.1`. One task, one fresh OpenCode session, one commit.
+
+## For the reviewer
+
+1. `git log --oneline master..v0.1`: one commit with the trailer.
+2. `cmp` both copied tests against `_files/`; `git diff master..v0.1 --stat -- PLAN.md AGENTS.md docs/plans` empty.
+3. `make gate`, `make smoke`.
+4. `grep -rn '\.(http\.' internal/` — every type assertion on a writer is checked (`v, ok :=`).

docs/plans/v0.1/_files/internal/config/unreadable_test.go

@@ -0,0 +1,47 @@
+package config_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+)
+
+// A file that exists but cannot be read is an error, and not a validation error: nothing about
+// the configuration has been judged. Only a missing file is "absent" (and that is an error too).
+func TestUnreadableFileIsAnError(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root can read a 000 file")
+	}
+	dir := t.TempDir()
+	path := filepath.Join(dir, "crossbar.toml")
+	good, err := os.ReadFile(filepath.Join("testdata", "good.toml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, good, 0o000); err != nil {
+		t.Fatal(err)
+	}
+	_, err = config.Load(path)
+	if err == nil {
+		t.Fatal("Load on an unreadable file must fail")
+	}
+	if _, ok := config.IsError(err); ok {
+		t.Errorf("an unreadable file is not a validation *Error: %v", err)
+	}
+	if !strings.HasPrefix(err.Error(), "config: ") {
+		t.Errorf("Error() = %q, want the config: prefix", err.Error())
+	}
+}
+
+func TestDirectoryIsAnError(t *testing.T) {
+	_, err := config.Load(t.TempDir())
+	if err == nil {
+		t.Fatal("Load on a directory must fail")
+	}
+	if _, ok := config.IsError(err); ok {
+		t.Errorf("a directory is not a validation *Error: %v", err)
+	}
+}

docs/plans/v0.1/_files/internal/proxy/recorder_test.go

@@ -0,0 +1,66 @@
+package proxy_test
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+	"git.wntrmute.dev/kyle/crossbar/internal/health"
+	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+)
+
+// noFlush is a ResponseWriter that does not implement http.Flusher. Middleware and test
+// recorders like this exist in the wild; the proxy must degrade to buffering, never panic.
+type noFlush struct{ w http.ResponseWriter }
+
+func (n noFlush) Header() http.Header         { return n.w.Header() }
+func (n noFlush) Write(b []byte) (int, error) { return n.w.Write(b) }
+func (n noFlush) WriteHeader(code int)        { n.w.WriteHeader(code) }
+
+func TestStreamingWriterWithoutFlusherDoesNotPanic(t *testing.T) {
+	up := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/event-stream")
+		w.WriteHeader(200)
+		for i := 0; i < 3; i++ {
+			fmt.Fprintf(w, "data: chunk %d\n\n", i)
+			w.(http.Flusher).Flush()
+		}
+	}))
+	t.Cleanup(up.Close)
+	cfg, err := config.Parse(strings.NewReader(fmt.Sprintf(`
+listen = "127.0.0.1:1"
+[hosts.alpha]
+base_url = %q
+models = { "m" = { } }
+[routes.r]
+hosts = ["alpha"]
+`, up.URL)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	h := &fakeHealth{st: map[string]health.Status{"alpha": {Healthy: true, Loaded: []string{"m"}}}}
+	p := proxy.New(cfg, h, nil)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/r/v1/chat/completions", strings.NewReader(`{"model":"m","stream":true}`))
+	func() {
+		defer func() {
+			if r := recover(); r != nil {
+				t.Fatalf("ServeHTTP panicked on a writer without Flush: %v", r)
+			}
+		}()
+		p.ServeHTTP(noFlush{rec}, req)
+	}()
+	if rec.Code != 200 {
+		t.Fatalf("status %d", rec.Code)
+	}
+	if got := rec.Body.String(); !strings.Contains(got, "chunk 0") || !strings.Contains(got, "chunk 2") {
+		t.Errorf("body = %q, want all three chunks", got)
+	}
+	if rec.Header().Get(proxy.HostHeader) != "alpha" {
+		t.Errorf("host header %q", rec.Header().Get(proxy.HostHeader))
+	}
+}

docs/plans/v0/04-admin-main.md

@@ -94,11 +94,11 @@ cp docs/plans/v0/_files/internal/admin/admin_test.go internal/admin/
 
 ```sh
 make build
-timeout --signal=TERM 3 bin/crossbar -config example.toml; echo "exit=$?"
+timeout --preserve-status --signal=TERM 3 bin/crossbar -config example.toml; echo "exit=$?"
 ```
 
 Expected on stderr: a line containing `listening` and `addr=127.0.0.1:17777`, then
-`shutting down`; then `exit=0`. (`example.toml` names two upstreams that are not running; the
+`shutting down`; then `exit=0` (`--preserve-status` makes `timeout` report crossbar's own exit code; without it GNU `timeout` prints 124 for any child it had to signal). (`example.toml` names two upstreams that are not running; the
 health table simply records them unhealthy — that is fine here.)
 
 ```sh

docs/plans/v0/README.md

@@ -69,3 +69,8 @@ stops at the first task that does not end with a commit, a clean tree and a `don
   investigating instead of editing the Makefile. Fixed by moving the directory to `_files/`
   (directories starting with `_` are ignored by the go tool); every task file updated. Task 01
   restarted from a clean tree.
+- 2026-09-25, task 04: the step-5 check `timeout --signal=TERM 3 bin/crossbar …; echo $?` expected
+  `exit=0`, but GNU `timeout` reports 124 whenever it had to signal the child, whatever the child's
+  own exit status. Ornith noticed, sent SIGTERM directly, confirmed exit 0 that way, logged the
+  deviation and finished. Task-text fault (case: my task, not the model); fixed with
+  `--preserve-status`.

docs/plans/v1.1/01-review-fixes.md

@@ -0,0 +1,66 @@
+# v1.1 task 01: review fixes — cancelled clients are recorded; empty usage is `[]`
+
+**Branch:** `v1.1` (create it from `master`: `git switch master && git switch -c v1.1`; `git status --short` must be empty first, otherwise stop)
+**Commit subject:** `Review fixes: record cancelled requests as 499; empty usage is an array`
+
+## What the reviewer observed
+
+1. A client that disconnects mid-stream leaves **no accounting row**: after `curl -m 0.4 -N …`
+   against a streaming completion, `/_crossbar/usage` stayed empty. Task 05's rule 5 said the
+   reverse proxy's `ErrorHandler` does nothing on `context.Canceled`; rule 6 said "record what
+   you have when `ServeHTTP` returns". The second rule was not applied on that path, and the
+   same gap exists for a client that gives up while waiting in the limiter queue (rule 4 said
+   "just return, log 499"). Cancelled requests held a slot and cost prefill; usage and error
+   rate must see them. The task text was ambiguous (owner's fault); the fix is still needed.
+2. `GET /_crossbar/usage` with no rows answers `null`. The spec said a JSON array. Clients iterate
+   the result; `null` is not iterable.
+
+## Files
+
+- Copy (never edit afterwards): `internal/proxy/cancel_test.go`, `internal/admin/usage_empty_test.go`
+- Modify: files under `internal/proxy/` as needed (`forward.go`, `proxy.go`), `internal/admin/admin_ops.go` (or wherever the usage handler lives), `docs/implementer-log.md`
+
+## Rules
+
+1. **Every request that reached step 3 of `ServeHTTP` (a lease was acquired) writes exactly one
+   `store.Request` row**, on every exit path: normal completion, upstream error (502), queue full
+   (503), client cancelled while queued (**499**, `Err: "client cancelled while queued"`), client
+   cancelled during the forward (**499**, `Err: "client cancelled"`, with whatever tokens the tee
+   had seen). Detect the forward case with `r.Context().Err() != nil` after `rp.ServeHTTP`
+   returns, or in the `ErrorHandler` when `errors.Is(err, context.Canceled)`; do not write to the
+   client in that case, do not mark the host down, but do record. Status 499 is not an HTTP
+   status the client sees; it is the row's status (and the log line's), as nginx does.
+2. **`/_crossbar/usage` JSON** encodes an empty result as `[]`: initialise the slice
+   (`rows := []store.UsageRow{}` / `make(..., 0)`) before encoding, on every `by` value and with
+   or without `since`. The text form prints its header line even with no rows.
+3. Nothing else changes. Existing tests must keep passing; the two new ones must pass.
+
+## Steps
+
+- [ ] **1. Branch and copy.**
+
+```sh
+git switch master && git switch -c v1.1
+cp docs/plans/v1.1/_files/internal/proxy/cancel_test.go internal/proxy/
+cp docs/plans/v1.1/_files/internal/admin/usage_empty_test.go internal/admin/
+```
+
+- [ ] **2. See them fail.** `go test -run 'Cancel|UsageEmpty' ./internal/proxy/ ./internal/admin/`.
+  Expected: all three tests fail (`no 499 row`, `body "null"`). If one passes already, stop and report.
+- [ ] **3. Fix.** `gofmt -w internal/`.
+- [ ] **4. See everything pass.** `go test -race -count=2 ./...`. The cancel tests are timing-based with generous margins.
+- [ ] **5. Run the gate.** `make gate`. Expected last line: `gate: ok`.
+- [ ] **6. Log and commit.** Row `v1.1/01-review-fixes`.
+
+```sh
+git add internal/proxy internal/admin docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- Step 2 failed before the fix and `go test -race -count=2 ./...` passes after; `make gate` prints `gate: ok`; both copied tests byte-identical to `_files/`.
+
+## Stop and report if
+
+- Step 2 passes before any change, or the cancel tests fail intermittently after the fix (report the failure text).

docs/plans/v1.1/README.md

@@ -0,0 +1,34 @@
+# v1.1 implementation plan: review follow-ups
+
+> **For the implementing model:** do not work from this file. The owner gives you one task file at
+> a time. This file is the index for the owner and the reviewer.
+
+**Goal:** close findings 1 and 2 of the v1 review (`docs/implementer-log.md`): a request whose
+client disconnects — mid-stream or while queued — must still write its accounting row (status
+499), and `/_crossbar/usage` with no rows must answer `[]`, not `null`.
+
+**How this plan was made:** acceptance tests first, from the findings; no reference
+implementation. Both given tests were run against `master` at the merge of `v1`: all three fail
+there (the two cancel tests find no 499 row; the empty-usage test gets `null`).
+
+## Tasks
+
+| # | File | Delivers | Tests that define it |
+|---|---|---|---|
+| 01 | `01-review-fixes.md` | 499 rows on both cancel paths; `[]` for empty usage | `internal/proxy/cancel_test.go`, `internal/admin/usage_empty_test.go` |
+
+Branch `v1.1`. One task, one fresh OpenCode session, one commit.
+
+## For the reviewer
+
+1. `git log --oneline master..v1.1`: one commit with the trailer.
+2. `cmp` both copied tests; `git diff master..v1.1 --stat -- PLAN.md AGENTS.md docs/plans` empty.
+3. `make gate`, `make smoke`.
+4. Probe: cut a stream with `curl -m 0.4 -N …` against the smoke rig and confirm one `status="499"` line in `/_crossbar/metrics`.
+
+## Changes during the run
+
+- 2026-09-25, task 01, first session: ended after ~8 min with no commit and no row, right after
+  the sandbox refused a `/tmp` scratch program (the I9 pattern, third time tonight). The rule
+  against ending a turn on a refusal lived only in v1's task 05; it is now in `AGENTS.md`, so every
+  task carries it. Resumed from the working tree.

docs/plans/v1.1/_files/internal/admin/usage_empty_test.go

@@ -0,0 +1,31 @@
+package admin_test
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+// An empty usage table is an empty JSON array, not null: clients iterate it.
+func TestUsageEmptyIsAnArray(t *testing.T) {
+	r := newRig(t)
+	for _, q := range []string{"/_crossbar/usage", "/_crossbar/usage?by=host", "/_crossbar/usage?by=model&since=1h"} {
+		rec := r.do(t, "GET", q, "")
+		if rec.Code != 200 {
+			t.Fatalf("%s: %d", q, rec.Code)
+		}
+		if strings.TrimSpace(rec.Body.String()) != "[]" {
+			t.Errorf("%s: body %q, want []", q, rec.Body.String())
+		}
+		var rows []store.UsageRow
+		if err := json.Unmarshal(rec.Body.Bytes(), &rows); err != nil || rows == nil || len(rows) != 0 {
+			t.Errorf("%s: decoded %v %v, want an empty non-nil slice", q, rows, err)
+		}
+	}
+	rec := r.do(t, "GET", "/_crossbar/usage?by=route", "", "Accept", "text/plain")
+	if rec.Code != 200 || !strings.Contains(rec.Body.String(), "key") {
+		t.Errorf("text form with no rows must still print the header: %d %q", rec.Code, rec.Body.String())
+	}
+}

docs/plans/v1.1/_files/internal/proxy/cancel_test.go

@@ -0,0 +1,109 @@
+package proxy_test
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+// A client that goes away mid-stream is still a request that happened: it held a slot, it cost
+// prefill, and it belongs in the accounting. The row records status 499 and a non-empty err.
+func TestClientCancelMidStreamIsRecorded(t *testing.T) {
+	slow := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/health":
+			fmt.Fprint(w, `{"status":"ok"}`)
+		case "/v1/models":
+			fmt.Fprint(w, `{"object":"list","data":[{"id":"shared"}]}`)
+		default:
+			w.Header().Set("Content-Type", "text/event-stream")
+			w.WriteHeader(200)
+			fmt.Fprint(w, "data: {\"choices\":[{\"delta\":{\"content\":\"first\"}}]}\n\n")
+			w.(http.Flusher).Flush()
+			select {
+			case <-r.Context().Done():
+			case <-time.After(3 * time.Second):
+			}
+		}
+	}))
+	t.Cleanup(slow.Close)
+	beta := newUpstream(t, "beta")
+	r := newRig(t, twoHosts, &upstream{name: "alpha", srv: slow}, beta)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	body := `{"model":"alpha-only","stream":true,"messages":[{"role":"user","content":"cancel me"}]}`
+	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, r.front.URL+"/r/v1/chat/completions", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	buf := make([]byte, 64)
+	if _, err := resp.Body.Read(buf); err != nil {
+		t.Fatalf("first chunk: %v", err)
+	}
+	cancel()
+	resp.Body.Close()
+
+	deadline := time.Now().Add(3 * time.Second)
+	var counts []store.StatusCount
+	for time.Now().Before(deadline) {
+		counts, _ = r.store.StatusCounts(time.Time{})
+		if len(counts) > 0 {
+			break
+		}
+		time.Sleep(25 * time.Millisecond)
+	}
+	if len(counts) != 1 || counts[0].Status != 499 || counts[0].Route != "r" || counts[0].Count != 1 {
+		t.Fatalf("status counts after a cancelled stream = %+v, want one row: route r, status 499", counts)
+	}
+	rows, _ := r.store.Usage(time.Time{}, store.ByRoute)
+	if len(rows) != 1 || rows[0].Requests != 1 || rows[0].Errors != 1 {
+		t.Errorf("usage = %+v, want 1 request counted as an error", rows)
+	}
+}
+
+// The same when the client gives up while waiting in the queue: a 499 row, no slot leaked.
+func TestClientCancelWhileQueuedIsRecorded(t *testing.T) {
+	alpha := newUpstream(t, "alpha")
+	alpha.delay = 800 * time.Millisecond
+	r := newRig(t, `
+listen = "127.0.0.1:1"
+queue_max = 2
+[hosts.alpha]
+base_url = %q
+models = { "shared" = { parallel = 1 } }
+[routes.r]
+hosts = ["alpha"]
+default_model = "shared"
+`, alpha)
+	go func() { drain(r.post("/r/v1/chat/completions", conversation(1, 1))) }() // holds the one slot
+	time.Sleep(100 * time.Millisecond)
+	ctx, cancel := context.WithTimeout(context.Background(), 150*time.Millisecond)
+	defer cancel()
+	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, r.front.URL+"/r/v1/chat/completions", strings.NewReader(conversation(2, 1)))
+	req.Header.Set("Content-Type", "application/json")
+	if _, err := http.DefaultClient.Do(req); err == nil {
+		t.Fatal("the queued request should have been cancelled by its context")
+	}
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		counts, _ := r.store.StatusCounts(time.Time{})
+		for _, c := range counts {
+			if c.Status == 499 {
+				if r.lim.Queued("alpha", "shared") != 0 {
+					t.Errorf("queued = %d after the waiter cancelled", r.lim.Queued("alpha", "shared"))
+				}
+				return
+			}
+		}
+		time.Sleep(25 * time.Millisecond)
+	}
+	t.Fatal("no 499 row recorded for the request cancelled while queued")
+}

docs/plans/v1/01-store.md

@@ -0,0 +1,154 @@
+# v1 task 01: the SQLite store
+
+**Branch:** `v1` (create it from `master`: `git switch master && git switch -c v1`; `git status --short` must be empty first, otherwise stop)
+**Commit subject:** `Add the SQLite store for leases and accounting`
+
+## Goal
+
+One SQLite file holds crossbar's durable state (the lease table) and its accounting log (one row
+per proxied request, lease events, poller observations), with rollup queries that answer
+per-route / per-model / per-host usage. This is `PLAN.md` §7a.
+
+## Context
+
+The driver is `modernc.org/sqlite` (pure Go, no cgo — the arm64 static build stays a plain
+`go build`), registered under the `database/sql` name `"sqlite"`. Open with WAL and a busy
+timeout: `sql.Open("sqlite", "file:"+path+"?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)")`.
+Volume is a few rows per request, so nothing here is performance-sensitive; correctness of the
+sums is what matters. Times are stored as Unix milliseconds (`INTEGER`) and returned as
+`time.Time` in UTC.
+
+## Files
+
+- Copy (never edit afterwards): `go.sum` (replaces; adds the driver's lines), `internal/store/store_test.go`
+- Create: `internal/store/store.go` (and `schema.go` if you want the SQL separate; both under 400 lines)
+- Modify: `go.mod` (add `modernc.org/sqlite v1.59.0` to `require`), `docs/implementer-log.md`
+
+## Interfaces
+
+Produces, in `internal/store`, package `store`:
+
+```go
+type State string
+const ( Active State = "active"; Pinned State = "pinned" )
+
+const (
+    ReasonNew = "new"; ReasonUnhealthy = "unhealthy"; ReasonIdle = "idle"
+    ReasonPin = "pin"; ReasonRelease = "release"; ReasonDrain = "drain"
+)
+
+type By string
+const ( ByRoute By = "route"; ByModel By = "model"; ByHost By = "host" )
+
+type Lease struct {
+    Route, FP, Model, Host string
+    State                  State
+    Created, LastUsed      time.Time
+}
+type LeaseEvent struct {
+    TS                             time.Time
+    Route, Model, FromHost, ToHost string
+    Reason                         string
+}
+type Request struct {
+    Route, FP, Model, Host                       string
+    Started                                      time.Time
+    QueuedMs, TTFBMs, TotalMs                    int64
+    Status                                       int
+    Streamed                                     bool
+    PromptTokens, CachedTokens, CompletionTokens int64
+    Err                                          string
+}
+type HostHealth struct {
+    TS      time.Time
+    Host    string
+    Healthy bool
+    Loaded  []string   // stored as a JSON array in one TEXT column
+}
+type UsageRow struct {
+    Key              string `json:"key"`
+    Requests         int64  `json:"requests"`
+    Errors           int64  `json:"errors"`           // rows with Status >= 400
+    BusyMs           int64  `json:"busy_ms"`          // sum(TotalMs)
+    QueuedMs         int64  `json:"queued_ms"`
+    PromptTokens     int64  `json:"prompt_tokens"`
+    CachedTokens     int64  `json:"cached_tokens"`
+    CompletionTokens int64  `json:"completion_tokens"`
+}
+func (u UsageRow) CacheHitRatio() float64            // CachedTokens / PromptTokens; 0 when PromptTokens == 0
+
+type Store struct { /* private: *sql.DB */ }
+func Open(path string) (*Store, error)               // creates tables if missing; fails if the directory does not exist
+func (s *Store) Close() error
+func (s *Store) JournalMode() string                 // "wal"
+func (s *Store) SaveLease(l Lease) error             // INSERT OR REPLACE on (route, fp, model)
+func (s *Store) DeleteLease(route, fp, model string) error
+func (s *Store) ListLeases() ([]Lease, error)
+func (s *Store) RecordEvent(e LeaseEvent) error
+func (s *Store) RecordRequest(r Request) error
+func (s *Store) RecordHostHealth(h HostHealth) error
+func (s *Store) Usage(since time.Time, by By) ([]UsageRow, error)          // rows with Started >= since, grouped by `by`; a zero `since` means all time
+func (s *Store) Events(since time.Time, limit int) ([]LeaseEvent, error)   // oldest first
+func (s *Store) Prune(now time.Time, retention time.Duration) (int64, error)
+```
+
+Rules the tests check:
+
+1. **Schema** (create with `IF NOT EXISTS`, so `Open` twice on one file works):
+   `leases(route, fp, model, host, state, created, last_used, PRIMARY KEY(route, fp, model))`,
+   `lease_events(ts, route, model, from_host, to_host, reason)`,
+   `requests(id INTEGER PRIMARY KEY, route, fp, model, host, started, queued_ms, ttfb_ms, total_ms, status, streamed, prompt_tokens, cached_tokens, completion_tokens, err)`,
+   `host_health(ts, host, healthy, loaded_models)`,
+   `requests_daily(day, route, model, host, requests, errors, busy_ms, queued_ms, prompt_tokens, cached_tokens, completion_tokens, PRIMARY KEY(day, route, model, host))`.
+2. **`Usage`** sums `requests` rows with `started >= since` **plus** `requests_daily` rows whose
+   `day >= since` (day = UTC midnight of `started`), grouped by the `by` column. `Errors` counts
+   `status >= 400`. A zero `since` (`time.Time{}`) means everything. Result order: by `Key`.
+3. **`Prune(now, retention)`** moves every `requests` row with `started < now - retention` into
+   `requests_daily` (adding into the existing day row if there is one), deletes them, and returns
+   the number deleted. In one transaction.
+4. Nothing here panics; every `sql` error is returned wrapped (`fmt.Errorf("store: …: %w", err)`).
+5. `Loaded` in `HostHealth` is written as a JSON array; `nil` is written as `[]`.
+
+## Steps
+
+- [ ] **1. Branch and copy.**
+
+```sh
+git switch master && git switch -c v1
+cp docs/plans/v1/_files/go.sum go.sum
+mkdir -p internal/store && cp docs/plans/v1/_files/internal/store/store_test.go internal/store/
+```
+
+- [ ] **2. Add the dependency.** In `go.mod`, the `require` becomes a block with both modules:
+
+```
+require (
+	github.com/BurntSushi/toml v1.6.0
+	modernc.org/sqlite v1.59.0
+)
+```
+
+Then `go mod download modernc.org/sqlite` (network, once) and `go mod verify`. Expected:
+`all modules verified`. If `go mod tidy` wants to change `go.sum` or add `// indirect` lines to
+`go.mod`, let it, and stage the result; `go.sum` must end up a superset of the given file.
+
+- [ ] **3. See the test fail.** `go test ./internal/store/`. Expected: it does not compile.
+- [ ] **4. Write `internal/store/store.go`.** `gofmt -w internal/store/`.
+- [ ] **5. See the test pass.** `go test -race -count=1 ./internal/store/`. Expected: `ok`. The
+  first compile of the driver takes a minute or two.
+- [ ] **6. Run the gate.** `make gate`. Expected last line: `gate: ok`.
+- [ ] **7. Log and commit.** Row `v1/01-store`.
+
+```sh
+git add go.mod go.sum internal/store docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- `go test -race -count=1 ./internal/store/` is `ok`; `make gate` prints `gate: ok`.
+- `cmp internal/store/store_test.go docs/plans/v1/_files/internal/store/store_test.go` prints nothing.
+
+## Stop and report if
+
+- The module cannot be downloaded, or `go vet` rejects the driver on this Go version.

docs/plans/v1/02-fingerprint-config.md

@@ -0,0 +1,88 @@
+# v1 task 02: the conversation fingerprint; config additions
+
+**Branch:** `v1` (run `git switch v1`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Add the conversation fingerprint and the v1 config keys`
+
+## Goal
+
+Two small things. `fingerprint.Of` turns a chat-completions body into a stable key for the
+conversation it belongs to (`PLAN.md` §4a), and `config` learns `db`, `lease_idle` and
+`retention`, with durations that accept a `d` suffix.
+
+## Context
+
+OpenCode and Hermes send no session id. A conversation's system prompt and its **first user
+message** do not change from turn to turn, so hashing those two identifies the conversation
+without client support. Only the first 4 KiB of each is hashed, so a huge first message does
+not make every turn slow, and a body with no user message has no fingerprint (`""`): such
+requests fall back to the route-level lease (task 04).
+
+## Files
+
+- Copy: `internal/fingerprint/fingerprint_test.go`, `internal/config/config_v1_test.go`
+- Copy (**replaces** v0's): `internal/config/config_test.go`, `internal/config/testdata/bad-unknown-key.toml`
+  (v0's unknown-key example was `lease_idle`, which this task makes valid; the replacements use `bogus_key`)
+- Create: `internal/fingerprint/fingerprint.go`
+- Modify: `internal/config/config.go`, `docs/implementer-log.md`
+
+## Interfaces
+
+`internal/fingerprint`, package `fingerprint`:
+
+```go
+// Of returns the lowercase hex SHA-256 of the system prompt and the first user message of a
+// chat-completions body (first 4 KiB of each, joined with "\n"), or "" when the body is not a
+// JSON object with a "messages" array containing a user message.
+func Of(body []byte) string
+```
+
+Rules the tests check:
+
+1. Decode `{"messages":[{"role":…,"content":…}, …]}`. `content` is either a string or an array
+   of parts `[{"type":"text","text":"…"}, …]`; for an array, join the `text` of the text parts
+   with `""` (other part types are ignored). Use `json.Unmarshal` into a struct with
+   `Content json.RawMessage`, then decide.
+2. System prompt = content of the **first** message with `role == "system"` (or `""` if none).
+   First user message = content of the **first** message with `role == "user"`; **no user
+   message → return `""`**. Not JSON, or no `messages` → `""`.
+3. Truncate each of the two strings to its first 4096 **bytes**, hash `system + "\n" + user`
+   with `crypto/sha256`, return `hex.EncodeToString`.
+
+`internal/config` gains, in `Config`:
+
+```go
+DB        string   `toml:"db"`          // default "crossbar.db"; empty string is an error (field "db")
+LeaseIdle Duration `toml:"lease_idle"`  // default 30m; less than 1m is an error (field "lease_idle")
+Retention Duration `toml:"retention"`   // default 180d; less than 1d is an error (field "retention")
+```
+
+and `Duration.UnmarshalText` accepts an integer followed by `d` (`"7d"` = 7 × 24 h) **in addition
+to** `time.ParseDuration` syntax. Exactly: if the text matches `^[0-9]+d$`, multiply; otherwise
+`time.ParseDuration`. `"1.5d"`, `"d"`, `"1d2h"` are errors. Validation order of the new fields:
+after `queue_max`, before `hosts`.
+
+## Steps
+
+- [ ] **1. Copy.**
+
+```sh
+git switch v1
+mkdir -p internal/fingerprint
+cp docs/plans/v1/_files/internal/fingerprint/fingerprint_test.go internal/fingerprint/
+cp docs/plans/v1/_files/internal/config/config_v1_test.go internal/config/
+```
+
+- [ ] **2. See them fail.** `go test ./internal/fingerprint/ ./internal/config/`. Expected: compile errors.
+- [ ] **3. Write `fingerprint.go`; extend `config.go`.** `gofmt -w internal/`.
+- [ ] **4. See them pass.** `go test -race -count=1 ./internal/fingerprint/ ./internal/config/`. Expected: both `ok` (the v0 config tests must still pass).
+- [ ] **5. Run the gate.** `make gate`. Expected last line: `gate: ok`.
+- [ ] **6. Log and commit.** Row `v1/02-fingerprint-config`.
+
+```sh
+git add internal/fingerprint internal/config docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- Both packages pass with `-race`; `make gate` prints `gate: ok`; both copied files are byte-identical to `_files/`.

docs/plans/v1/03-limiter-choose.md

@@ -0,0 +1,94 @@
+# v1 task 03: the per-(host, model) limiter and the chooser
+
+**Branch:** `v1` (run `git switch v1`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Add the per-host-model limiter and the host chooser`
+
+## Goal
+
+Two pure packages. `limiter` hands out at most `parallel` concurrent slots per (host, model) and
+lets at most `queue_max` requests wait in line, first come first served. `choose` picks the host
+for a **new** lease: most free slots × weight, ties to the shortest queue, then list order.
+This is `PLAN.md` §4 (`choose`) and §6 (concurrency).
+
+## Context
+
+A `llama-server` router with `parallel = 4` and unified KV falls over when a fifth request
+arrives ("Context size has been exceeded"). The limiter is where that is prevented: the fifth
+request waits, the ninth (with `queue_max = 4`) is refused at once so the client can retry
+elsewhere. Waiting is cancellable (the client may go away) and must leak neither a slot nor a
+queue place.
+
+## Files
+
+- Copy: `internal/limiter/limiter_test.go`, `internal/choose/choose_test.go`
+- Create: `internal/limiter/limiter.go`, `internal/choose/choose.go`
+- Modify: `docs/implementer-log.md`
+
+## Interfaces
+
+`internal/limiter`, package `limiter`:
+
+```go
+var ErrQueueFull = errors.New("queue full")
+
+type Limiter struct { /* private: mutex, map[(host, model)]*pair */ }
+func New() *Limiter
+func (l *Limiter) Configure(host, model string, parallel, queueMax int)
+// Acquire returns when a slot is held. release gives it back (idempotent: a second call is a
+// no-op). waited is how long the caller sat in the queue. Errors: ErrQueueFull immediately
+// when queueMax waiters are already queued; ctx.Err() if ctx ends while waiting.
+func (l *Limiter) Acquire(ctx context.Context, host, model string) (release func(), waited time.Duration, err error)
+func (l *Limiter) InFlight(host, model string) int
+func (l *Limiter) Queued(host, model string) int
+func (l *Limiter) FreeSlots(host string) int   // sum over the host's configured models of parallel - inflight (never below 0); 0 for an unknown host
+```
+
+Rules the tests check:
+
+1. An unconfigured (host, model) behaves as `parallel = 1, queueMax = 0`.
+2. FIFO: waiters get slots in arrival order. Suggested shape: a mutex, `inflight`, and a slice
+   of waiter channels; `release` pops the head waiter (if any) and hands the slot over without
+   ever decrementing `inflight`, else decrements. A waiter whose ctx ends removes itself from
+   the queue under the mutex; if the slot was handed to it in the same instant, it releases it.
+3. `release` idempotent via `sync.Once`.
+4. Never panic; all methods safe for concurrent use.
+
+`internal/choose`, package `choose`:
+
+```go
+type Info struct {
+    Healthy, Draining, Loaded, CanServe bool   // Loaded: model is resident; CanServe: config lists the model
+    Free, Queued                        int
+    Weight                              float64
+}
+// Best returns the candidate with the highest Free*Weight among those that are healthy, not
+// draining and known (info ok) — preferring hosts with Loaded over merely CanServe; ties go to
+// the lowest Queued, then to candidate order. A host with Free == 0 is still eligible (it will
+// queue). ok is false when nothing is eligible.
+func Best(candidates []string, info func(host string) (Info, bool)) (string, bool)
+```
+
+Rules: two passes — first over eligible candidates with `Loaded`, then, if none, over eligible
+candidates with `CanServe`. Score `float64(Free) * Weight`. Compare with `>`; on equality prefer
+lower `Queued`; on equality keep the earlier candidate.
+
+## Steps
+
+- [ ] **1. Copy.** `git switch v1`; `mkdir -p internal/limiter internal/choose`; copy both tests from `docs/plans/v1/_files/internal/…`.
+- [ ] **2. See them fail** (compile). **3. Write both packages.** `gofmt -w internal/`.
+- [ ] **4. See them pass.** `go test -race -count=1 ./internal/limiter/ ./internal/choose/`. The
+  limiter tests are timing-based with generous margins; run them three times: `-count=3`.
+- [ ] **5. Run the gate.** `make gate`. **6. Log and commit.** Row `v1/03-limiter-choose`.
+
+```sh
+git add internal/limiter internal/choose docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- Both packages pass `-race -count=3`; `make gate` prints `gate: ok`; copied files byte-identical.
+
+## Stop and report if
+
+- A limiter test fails only sometimes: report which and how often; do not loosen it.

docs/plans/v1/04-lease.md

@@ -0,0 +1,117 @@
+# v1 task 04: the lease table
+
+**Branch:** `v1` (run `git switch v1`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Add the sticky lease table`
+
+## Goal
+
+The heart of crossbar: `lease.Table` remembers which host each conversation is on and keeps it
+there. A lease moves only when its host is unhealthy, when it has been idle longer than
+`lease_idle`, or when an operator releases or pins the route. It is written through to the store
+on every change and loaded back at start, so a restart does not reshuffle sessions.
+`PLAN.md` §5, §4 step 3.
+
+## Context
+
+Why sticky: a `llama-server` prompt cache is per process; moving a 200k-token conversation to
+another host costs minutes of re-prefill. A "better" host appearing is never a reason to move.
+A pin ("project A goes to titan right now") is an operator decision and outranks everything,
+including health: a pinned host that is down yields an error, not a silent move.
+
+## Files
+
+- Copy: `internal/lease/lease_test.go`
+- Create: `internal/lease/lease.go`
+- Modify: `docs/implementer-log.md`
+
+## Interfaces
+
+`internal/lease`, package `lease`:
+
+```go
+var (
+    ErrNoHost      = errors.New("lease: no usable host")
+    ErrPinnedDown  = errors.New("lease: pinned host is not healthy")
+    ErrUnknownHost = errors.New("lease: unknown host")
+)
+
+type Key struct{ Route, FP, Model string }
+type Lease struct {
+    Key
+    Host              string
+    State             store.State
+    Created, LastUsed time.Time
+}
+type Persister interface {                          // *store.Store satisfies it
+    SaveLease(store.Lease) error
+    DeleteLease(route, fp, model string) error
+    ListLeases() ([]store.Lease, error)
+    RecordEvent(store.LeaseEvent) error
+}
+type Hosts interface {
+    Healthy(name string) bool
+    Draining(name string) bool
+}
+type Chooser interface {
+    Choose(candidates []string, model string) (string, bool)
+}
+type Table struct { /* private: mutex, leases map[Key]*Lease, pins map[route]host, p, hosts, choose, idle */ }
+
+func New(p Persister, h Hosts, c Chooser, idle time.Duration) (*Table, error)   // loads p.ListLeases(): rows with FP=="" && Model=="" && State==Pinned are pins
+func (t *Table) Acquire(k Key, candidates []string, now time.Time) (host string, reused bool, err error)
+func (t *Table) ExpireIdle(now time.Time) int          // removes leases with now - LastUsed > idle (not pins); events ReasonIdle; returns how many
+func (t *Table) Pin(route, host string, now time.Time) error   // host must be in the candidates of at least one existing lease of the route, or in a candidate list seen for that route; else ErrUnknownHost
+func (t *Table) Unpin(route string)
+func (t *Table) Pinned(route string) string            // "" if not pinned
+func (t *Table) Release(route string) int              // drops all leases (not the pin) of the route; events ReasonRelease; returns how many
+func (t *Table) Snapshot() []Lease                     // copies, sorted by Route, FP, Model; pins excluded
+```
+
+`Acquire`, in this order:
+
+1. **Pinned route** (`pins[k.Route]` set): if `hosts.Healthy(pin)` → host = pin; if no lease for
+   `k` exists, create one (state `Active`, event `ReasonPin` only if this is the first lease
+   created under this pin for this key… keep it simple: event `ReasonNew` with `ToHost = pin`);
+   return `(pin, existed, nil)`. If the pin is not healthy → `ErrPinnedDown`.
+2. **Existing lease for `k`**: if its host is healthy → touch `LastUsed = now`, save, return
+   `(host, true, nil)`. (A draining host still serves its existing leases.) If not healthy →
+   record `ReasonUnhealthy` (`FromHost` = old host) and fall through to choose, excluding that
+   host.
+3. **Inherit**: if `k.FP != ""` and a lease for `Key{k.Route, "", k.Model}` exists on a healthy
+   host, create `k`'s lease on that host, save, return `(host, true, nil)`.
+4. **Choose**: candidates minus unhealthy minus draining → `choose.Choose(filtered, k.Model)`.
+   None → `ErrNoHost` (nothing is created). Else create the lease (`Created = LastUsed = now`),
+   save, record `ReasonNew` (or the `ReasonUnhealthy` event from step 2 instead, with `ToHost`
+   filled), return `(host, false, nil)`.
+
+`Pin` records `ReasonPin` (`ToHost` = host) and saves a pin row
+(`store.Lease{Route: route, FP: "", Model: "", Host: host, State: store.Pinned}`); existing
+leases of the route on other hosts are **deleted** (event `ReasonPin` per lease) so the next turn
+lands on the pin. `Unpin` deletes the pin row and records `ReasonRelease`; existing leases stay.
+`Pin` to a host that no candidate list for that route has ever contained → `ErrUnknownHost`
+(keep a `map[route]map[host]bool` of candidates seen in `Acquire`; at load time, hosts of stored
+leases count as seen).
+
+All persister errors are returned; nothing is left half-changed in memory when a save fails
+(apply to memory after the save succeeds).
+
+## Steps
+
+- [ ] **1. Copy.** `git switch v1`; `mkdir -p internal/lease`; `cp docs/plans/v1/_files/internal/lease/lease_test.go internal/lease/`.
+  Read `TestPinAndUnpin` and `TestFingerprintInheritsRouteLease` twice: they are the rules above as stories.
+- [ ] **2. See it fail** (compile). **3. Write `lease.go`.** `gofmt -w internal/lease/`.
+- [ ] **4. See it pass.** `go test -race -count=1 ./internal/lease/`.
+- [ ] **5. Run the gate.** `make gate`. **6. Log and commit.** Row `v1/04-lease`.
+
+```sh
+git add internal/lease docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- `go test -race -count=1 ./internal/lease/` is `ok`; `make gate` prints `gate: ok`; the copied test is byte-identical.
+
+## Stop and report if
+
+- A test expects an event sequence you cannot produce under the rules above: quote the test and the rule that conflict.

docs/plans/v1/05-proxy.md

@@ -0,0 +1,129 @@
+# v1 task 05: the proxy uses leases, the limiter, the SSE tee and the store
+
+**Branch:** `v1` (run `git switch v1`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Route by lease, queue per host and model, record every request`
+
+## Goal
+
+`internal/proxy` becomes the v1 proxy: route from path **or** header, fingerprint the body,
+acquire a lease, take a limiter slot (queue or 503), forward with streaming, tee the response
+to read `usage`/`timings`, mark hosts down on failure, and record one `store.Request` per
+request. `PLAN.md` §4, §6, §7a.
+
+## Context
+
+The v0 proxy stays the skeleton of this one: `SplitRoute`, the ordered error answers, the model
+peek, `httputil.ReverseProxy` with `FlushInterval: -1`, the status recorder with a checked
+`Flush`, the log line. What changes is who picks the host and what happens around the forward.
+Two new response headers make the behaviour observable: `X-Crossbar-Host` (existing) and
+`X-Crossbar-Lease: new|reused`. The given test drives the whole handler over real HTTP with a
+real `store`, `lease.Table`, `limiter` and `health.Table`.
+
+## Files
+
+- Copy (**replaces** v0's file): `internal/proxy/proxy_test.go`
+- Copy: `internal/proxy/helpers_test.go` (the `fakeHealth` helper that v0's `proxy_test.go` held and `recorder_test.go` still needs)
+- Modify: `internal/proxy/proxy.go` (split into more files if it passes 400 lines: `proxy.go`, `tee.go`, `hosts.go`), `docs/implementer-log.md`
+- Keep: `internal/proxy/recorder_test.go` from v0.1 — it must still pass. Its `proxy.New(cfg, h, nil)`
+  call no longer compiles, so **this is the one given test you edit**: change that call to
+  `proxy.New(cfg, h, nil, nil, nil, nil)` and nothing else; `New` must accept nils for
+  `leases`, `lim`, `rec` and then behave like v0 (first healthy host, no queue, no recording).
+  Say so in Deviations. The edited file is the plan's reference copy at
+  `_files/internal/proxy/recorder_test.go` for the reviewer's byte-exact check.
+
+## Interfaces
+
+`internal/proxy`, package `proxy` (v0 names kept; additions):
+
+```go
+const (
+    MaxBody     = 16 << 20
+    HostHeader  = "X-Crossbar-Host"
+    LeaseHeader = "X-Crossbar-Lease"   // "new" or "reused"
+    RouteHeader = "X-Crossbar-Route"   // client may name the route here instead of the path
+)
+type Health interface { Get(name string) (health.Status, bool); MarkDown(name, reason string) }
+type Recorder interface { RecordRequest(store.Request) error }   // *store.Store satisfies it
+
+// Hosts adapts the health table and config for the lease table, and holds the drain set.
+type Hosts struct { /* private */ }
+func HostView(h *health.Table, cfg *config.Config) *Hosts
+func (h *Hosts) Healthy(name string) bool
+func (h *Hosts) Draining(name string) bool
+func (h *Hosts) SetDraining(name string, on bool)
+
+// Chooser adapts config, health and limiter to lease.Chooser using choose.Best:
+// Info{Healthy, Draining: false (the lease table already filtered), Loaded: model in Loaded,
+// CanServe: cfg.Serves, Free: free slots FOR THIS MODEL on this host =
+// cfg.Hosts[host].Models[model].Parallel - lim.InFlight(host, model) (never below 0; 0 when the
+// host does not list the model), Queued: lim.Queued(host, model), Weight}.
+// (Corrected 2026-09-25: an earlier version said lim.FreeSlots(host), which sums every model's
+// slots and let a host win on slots the requested model cannot use.)
+func Chooser(cfg *config.Config, h *health.Table, l *limiter.Limiter) lease.Chooser
+
+func New(cfg *config.Config, h Health, leases *lease.Table, lim *limiter.Limiter, rec Recorder, log *slog.Logger) *Handler
+func (p *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
+func SplitRoute(path string) (route, rest string, ok bool)
+```
+
+`ServeHTTP`, in order (every error answer is JSON `{"error":"…"}` as in v0):
+
+1. **Route.** `hdr := r.Header.Get(RouteHeader)`. If `hdr != ""`: the path is used **whole** as
+   `rest` (it must then start with `/v1/` or be `/health` or `/props`); if the path *also* starts
+   with a known route name and it differs from `hdr` → **400** `conflicting route`. If `hdr == ""`:
+   `SplitRoute` as in v0 (400 `missing route`). Unknown route (either source) → 404
+   `unknown route`. Disallowed `rest` → 404 `not found`.
+2. **Peek** (v0 rule): body up to `MaxBody` → 413; `model` from the body or the route default;
+   `fp := fingerprint.Of(body)` (GET/HEAD → `""`).
+3. **Lease.** `host, reused, err := leases.Acquire(lease.Key{route, fp, model}, rt.Hosts, time.Now())`.
+   `ErrNoHost` → **503** `no healthy host`; `ErrPinnedDown` → **503** `pinned host down`.
+4. **Slot.** `release, waited, err := lim.Acquire(r.Context(), host, model)`. `ErrQueueFull` → **503**
+   `queue full`; ctx error → **499**-style: just return (the client left; log status 499).
+   `defer release()`.
+5. **Forward** as in v0 (`Rewrite`, `FlushInterval: -1`, `ModifyResponse` sets `HostHeader` and
+   `LeaseHeader`, `ErrorHandler` marks down + 502 with host). **Tee:** in `ModifyResponse`, wrap
+   `resp.Body` in a reader that passes every byte through unchanged and, when
+   `Content-Type` starts with `text/event-stream`, scans complete `data: ` lines for a JSON object
+   with `usage` and/or `timings`, remembering the **last** one seen; for non-streamed JSON
+   answers, remember the whole body's `usage`/`timings` (bounded: keep at most 1 MiB for the
+   parse; beyond that, record no tokens). The scanner must not hold data back: `Read` returns
+   what the upstream returned.
+6. **Record**, after the upstream body is closed (the tee's `Close`, or the error handler):
+   `store.Request{Route, FP: fp, Model, Host, Started, QueuedMs: waited, TTFBMs (first byte of
+   the response head), TotalMs, Status, Streamed, PromptTokens: usage.prompt_tokens (or
+   timings.prompt_n), CachedTokens: timings.cache_n, CompletionTokens: usage.completion_tokens
+   (or timings.predicted_n), Err}`. Also record the 503/502 cases (Status set, no tokens). Do it
+   from the request goroutine after `rp.ServeHTTP` returns, so tests that read the store right
+   after the response see the row; if the tee cannot tell that the body closed, record what
+   you have when `ServeHTTP` returns. A `rec` error is logged, never returned to the client.
+7. When `leases == nil` (v0.1 compatibility path used by `recorder_test.go`): choose with the
+   v0 `Choose` rule, skip the limiter and the store, still set `HostHeader`.
+8. Log line as v0, adding `lease=new|reused`, `queued_ms`, `fp` (**first 8 hex chars only**).
+   Never the body.
+
+## Steps
+
+- [ ] **1. Copy (replace).** `git switch v1`; `cp docs/plans/v1/_files/internal/proxy/proxy_test.go internal/proxy/proxy_test.go`;
+  `cp docs/plans/v1/_files/internal/proxy/helpers_test.go internal/proxy/`.
+  Edit the one call in `internal/proxy/recorder_test.go` as described above.
+- [ ] **2. See it fail** (compile). **3. Write the code.** `gofmt -w internal/proxy/`.
+- [ ] **4. See it pass.** `go test -race -count=1 ./internal/proxy/`. `TestDifferentConversationsSpreadByFreeSlots`
+  and `TestQueueFullIs503` are timing-based with generous margins; run `-count=3`.
+- [ ] **5. Run the gate.** `make gate`. `cmd/crossbar` will not compile until task 06 — if `go vet ./...`
+  fails only in `cmd/crossbar/main.go` because of the new `New` signature, change that one call
+  to pass `nil, nil, nil` for the new arguments (task 06 wires it properly) and say so in Deviations.
+- [ ] **6. Log and commit.** Row `v1/05-proxy`.
+
+```sh
+git add internal/proxy cmd/crossbar docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- `go test -race -count=3 ./internal/proxy/` is `ok`; `make gate` prints `gate: ok`;
+  `cmp internal/proxy/proxy_test.go docs/plans/v1/_files/internal/proxy/proxy_test.go` prints nothing.
+
+## Stop and report if
+
+- `TestAccountingRowsFromUsageAndTimings` fails on the token sums while the stream test passes: quote the recorded row.

docs/plans/v1/06-admin.md

@@ -0,0 +1,125 @@
+# v1 task 06: the admin handler (v1)
+
+**Branch:** `v1` (run `git switch v1`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Admin: leases, pin, release, drain, usage, metrics`
+
+## Goal
+
+Operators see and steer the system: the hosts view gains slots and drain state, the routes view
+shows leases and pins, `POST` endpoints pin/release a route and drain a host, `/usage` answers
+the accounting questions, `/metrics` exposes them to Prometheus. `PLAN.md` §7, §7a. The
+`cmd/crossbar` wiring is the next task (07), not this one.
+
+**State of the tree when this task starts:** an earlier session already added
+`store.StatusCounts` (`internal/store`) and `lease.Table.Candidates` (`internal/lease`), copied
+`example.toml` and `admin_test.go`, and left a broken draft of `internal/admin/admin.go`
+(duplicate `Handler` declarations). Those files are uncommitted in the working tree. Keep the
+store and lease additions (they pass their tests); treat `admin.go` as scratch you may rewrite
+from a blank file. This task commits all of them.
+
+## Files
+
+- Already copied (verify with `cmp`, never edit): `internal/admin/admin_test.go`, `example.toml`
+- Modify: `internal/admin/admin.go` (split if over 400 lines), `cmd/crossbar/main.go` (one call, see step 5), `docs/implementer-log.md`
+- Already modified, commit as they are after their tests pass: `internal/store/store.go`, `internal/store/schema.go`, `internal/lease/lease.go`
+
+## Interfaces
+
+`internal/lease` gains one method — the only change to that package allowed in this task:
+
+```go
+// Candidates records hosts as seen for route (idempotent), so Pin can accept a host the route
+// is configured for before any request has used it. cmd/crossbar calls it for every route at
+// start; the admin handler calls it before Pin.
+func (t *Table) Candidates(route string, hosts []string)
+```
+
+`internal/admin`, package `admin`:
+
+```go
+type Hosts interface { All() map[string]health.Status }
+type Drainer interface { Draining(name string) bool; SetDraining(name string, on bool) }   // *proxy.Hosts satisfies it
+
+type HostView struct {
+    Healthy   bool     `json:"healthy"`
+    Loaded    []string `json:"loaded"`      // never null
+    LastOK    string   `json:"last_ok"`     // RFC 3339 UTC or ""
+    LastErr   string   `json:"last_err"`
+    FreeSlots int      `json:"free_slots"`  // lim.FreeSlots(host)
+    InFlight  int      `json:"in_flight"`   // sum over the host's configured models
+    Queued    int      `json:"queued"`      // same
+    Draining  bool     `json:"draining"`
+}
+type LeaseView struct { FP, Model, Host, State, Created, LastUsed string }   // json tags: fp, model, host, state, created, last_used (RFC 3339 UTC)
+type RouteView struct {
+    Hosts        []string    `json:"hosts"`
+    DefaultModel string      `json:"default_model"`
+    Pinned       string      `json:"pinned"`   // "" when not pinned
+    Leases       []LeaseView `json:"leases"`   // never null
+}
+func Handler(cfg *config.Config, h Hosts, lt *lease.Table, lim *limiter.Limiter, st *store.Store, d Drainer) http.Handler
+```
+
+Endpoints (all JSON unless said; errors `{"error":"…"}`; wrong method → 405 with `Allow`):
+
+- `GET /_crossbar/hosts` → `map[string]HostView`.
+- `GET /_crossbar/routes` → `map[string]RouteView` from config + `lt.Snapshot()` + `lt.Pinned`.
+- `POST /_crossbar/routes/{route}` body `{"host":"…","pin":true}`: first check `host` is one of
+  `cfg.Routes[route].Hosts` (else **404**), then `lt.Candidates(route, cfg.Routes[route].Hosts)` so
+  the table knows them even if no request has used the route yet, then `lt.Pin(route, host, now)`;
+  `{"release":true}` → `lt.Release(route)` **and** `lt.Unpin(route)`. Unknown route → 404;
+  `lt.Pin` returning `ErrUnknownHost` → 404; not JSON, neither form, or both forms at once,
+  or `pin` without `host` → 400. Answer `{"ok":true}` (plus `"released": n` for a release).
+  `GET` on this path → 405.
+- `POST /_crossbar/hosts/{host}` body `{"drain":true|false}` → `d.SetDraining`; unknown host
+  (not in config) → 404; bad body → 400. `{"ok":true}`.
+- `GET /_crossbar/usage?since=…&by=route|model|host` → `[]store.UsageRow` (JSON array; sorted by
+  key). `by` defaults to `route`; `since` is either RFC 3339 or a duration like `24h`/`7d`
+  (meaning `now - d`); absent = all time; anything else → 400. With `Accept: text/plain`, a
+  fixed-width table with a header line containing `key requests errors busy_ms queued_ms
+  prompt cached completion cache_hit` and one line per row (`cache_hit` as `0.80`).
+- `GET /_crossbar/metrics` → `text/plain; version=0.0.4`, computed on request. Request counters
+  need (route, host, status), which `Usage` (one key) cannot give, so add **one** method to
+  `internal/store` — the only change to that package allowed in this task:
+  ```go
+  type StatusCount struct { Route, Host string; Status int; Count int64 }
+  func (s *Store) StatusCounts(since time.Time) ([]StatusCount, error)   // from `requests` only; rolled-up days are not in it, say so in a comment
+  ```
+  Then emit, in this order:
+  ```
+  # TYPE crossbar_requests_total counter
+  crossbar_requests_total{route="…",host="…",status="…"} N          (one line per StatusCount)
+  # TYPE crossbar_prompt_tokens_total counter
+  crossbar_prompt_tokens_total{route="…"} N                          (Usage(zero, ByRoute))
+  # TYPE crossbar_cached_tokens_total counter
+  # TYPE crossbar_completion_tokens_total counter
+  # TYPE crossbar_queue_wait_ms_total counter                        crossbar_queue_wait_ms_total{route="…"} N
+  # TYPE crossbar_host_healthy gauge                                 crossbar_host_healthy{host="…"} 0|1
+  # TYPE crossbar_host_free_slots gauge
+  # TYPE crossbar_host_in_flight gauge
+  # TYPE crossbar_host_queued gauge
+  ```
+  Label values escaped (`"` and `\`), lines sorted, no trailing spaces.
+
+## Steps
+
+- [ ] **1. Check the tree.** `git switch v1`; `git status --short` shows the modified store, lease,
+  admin and example files listed above. `cmp internal/admin/admin_test.go docs/plans/v1/_files/internal/admin/admin_test.go`
+  and `cmp example.toml docs/plans/v1/_files/example.toml` print nothing. If they do not, copy the given files again.
+- [ ] **2. Confirm the inherited pieces pass.** `go test -race -count=1 ./internal/store/ ./internal/lease/`. Expected: both `ok`.
+- [ ] **3. Write `internal/admin/admin.go`** (delete the draft first if it is easier). `gofmt -w internal/admin/`.
+- [ ] **4. See the test pass.** `go test -race -count=1 ./internal/admin/`. Expected: `ok`.
+- [ ] **5. Make the module build.** The new `admin.Handler` signature breaks the one call in
+  `cmd/crossbar/main.go`; change that call to `admin.Handler(cfg, table, nil, nil, nil, nil)` and
+  nothing else in that file (task 07 wires the real values). Then `make gate`. Expected last line:
+  `gate: ok`.
+- [ ] **6. Log and commit.** Row `v1/06-admin`. Deviations: say that the store and lease additions came from the earlier session.
+
+```sh
+git add internal/admin internal/store internal/lease cmd/crossbar example.toml docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- `go test -race -count=1 ./...` passes; `make gate` prints `gate: ok`; `admin_test.go` and `example.toml` are byte-identical to `_files/`.

docs/plans/v1/07-main.md

@@ -0,0 +1,67 @@
+# v1 task 07: wire the store, leases and limiter into `crossbar`
+
+**Branch:** `v1` (run `git switch v1`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Wire the store, lease table and limiter into crossbar`
+
+## Goal
+
+`cmd/crossbar` opens the SQLite store, builds the lease table and the limiter from the config,
+registers every route's hosts, serves the v1 proxy and admin, runs idle expiry and pruning in
+the background, records poller observations, and shuts down cleanly. `PLAN.md` §5–§7a.
+
+## Files
+
+- Modify: `cmd/crossbar/main.go`, `docs/implementer-log.md`
+
+## Rules
+
+`cmd/crossbar/main.go` (keep the v0 shape: `-config`, slog to stderr, signal context, graceful shutdown):
+
+1. After `config.Load`: `st, err := store.Open(cfg.DB)`; error → `crossbar: …` on stderr, exit 1. Close it on the way out.
+2. `table := health.New(bases, cfg.PollInterval.Duration, nil)`; `go table.Run(ctx)`.
+3. `hosts := proxy.HostView(table, cfg)`; `lim := limiter.New()` and, for every host and model in
+   `cfg.Hosts`, `lim.Configure(host, model, m.Parallel, cfg.QueueMax)`.
+4. `leases, err := lease.New(st, hosts, proxy.Chooser(cfg, table, lim), cfg.LeaseIdle.Duration)`;
+   error → exit 1. Then `for name, rt := range cfg.Routes { leases.Candidates(name, rt.Hosts) }`.
+5. `mux.Handle("/_crossbar/", admin.Handler(cfg, table, leases, lim, st, hosts))`;
+   `mux.Handle("/", proxy.New(cfg, table, leases, lim, st, log))`.
+6. Background goroutines until `ctx` is done: every minute `leases.ExpireIdle(time.Now())`; every
+   hour `st.Prune(time.Now(), cfg.Retention.Duration)` (log the count); every `poll_interval`
+   read `table.All()` and `st.RecordHostHealth` one row per host. Log errors, never exit on them.
+7. Shutdown as v0 (`srv.Shutdown` with a 10 s timeout), then `st.Close()`. Exit 0.
+
+## Steps
+
+- [ ] **1.** `git switch v1`; `git status --short` empty.
+- [ ] **2. Write `main.go`.** `gofmt -w cmd/`.
+- [ ] **3. Build and run for three seconds.**
+
+```sh
+make build
+timeout --preserve-status --signal=TERM 3 bin/crossbar -config example.toml; echo "exit=$?"
+ls crossbar.db* && rm -f crossbar.db crossbar.db-wal crossbar.db-shm
+```
+
+Expected: `listening`, `shutting down`, `exit=0`; the SQLite file existed (then removed). Then:
+
+```sh
+bin/crossbar -config /nonexistent.toml; echo "exit=$?"
+```
+
+Expected: `crossbar: config: open /nonexistent.toml: no such file or directory`, `exit=1`.
+
+- [ ] **4. Run the gate.** `make gate`. Expected last line: `gate: ok`.
+- [ ] **5. Log and commit.** Row `v1/07-main`.
+
+```sh
+git add cmd/crossbar docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- The three-second run exits 0 and created the db; the missing-config run exits 1; `make gate` prints `gate: ok`.
+
+## Stop and report if
+
+- `bin/crossbar` does not exit 0 on SIGTERM within the timeout.

docs/plans/v1/08-smoke-readme.md

@@ -0,0 +1,60 @@
+# v1 task 08: the smoke run and the README
+
+**Branch:** `v1` (run `git switch v1`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Smoke run for v1; README for leases, admin and accounting`
+
+## Goal
+
+Prove v1 end to end with the given `tools/smoke.sh` — leases, header route, pin, queue, drain,
+failover and recovery, streaming with the usage chunk intact, usage and metrics — and bring the
+README up to date.
+
+## Files
+
+- Copy (**replaces** v0's): `tools/smoke.sh`, `cmd/fakeupstream/main.go`
+- Modify: `README.md`, `docs/implementer-log.md`
+
+## Steps
+
+- [ ] **1. Copy and run.**
+
+```sh
+git switch v1
+cp docs/plans/v1/_files/tools/smoke.sh tools/
+cp docs/plans/v1/_files/cmd/fakeupstream/main.go cmd/fakeupstream/
+make smoke
+```
+
+Expected last line: `smoke: ok (stream spread N ms)`, N ≥ 600. The script prints which numbered
+check failed and crossbar's log. A failure is a defect in tasks 01–07 **or in the script**: fix
+code only when a rule from an earlier task was broken; if the script's expectation contradicts a
+task rule, stop and report which.
+
+- [ ] **1b. One known owner finding to fix before the smoke can pass.** `proxy.Chooser`
+  (task 05, `internal/proxy/hosts.go`) computes `Free` with `lim.FreeSlots(host)`, which sums the
+  slots of *every* model on the host; the rule now reads: `Free` = free slots **for the requested
+  model** = `cfg.Hosts[host].Models[model].Parallel - lim.InFlight(host, model)`, floored at 0,
+  and 0 when the host does not list the model. Make that change (only that), run
+  `go test -race -count=1 ./internal/proxy/` (must stay `ok`), then re-run `make smoke`. This is
+  the one code change this task makes; record it in Deviations as an owner-directed fix.
+- [ ] **2. Update `README.md`.** Keep the seven v0 sections; change: the intro (leases, not "first
+  healthy host"); `## Configure` gets `db`, `lease_idle`, `retention`, `queue_max` in the table and
+  the new `example.toml`; `## Point clients at it` adds the `X-Crossbar-Route` header
+  alternative; `## Inspect` becomes `## Operate` and documents all six endpoints with one example
+  each (`GET hosts`, `GET routes`, `POST routes/{route}` pin and release, `POST hosts/{host}`
+  drain, `GET usage` JSON and text, `GET metrics`), taken from the smoke run; `## What v1 does not
+  do`: context-size guard, wake-on-LAN, Tailscale identity, `/slots` — see `PLAN.md` v2.
+- [ ] **3. Run the gate.** `make gate`. **4. Log and commit.** Row `v1/08-smoke-readme`, with the smoke line in Notes.
+
+```sh
+git add tools/smoke.sh cmd/fakeupstream/main.go internal/proxy README.md docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- `make smoke` prints `smoke: ok (…)`; `make gate` prints `gate: ok`; both copied files byte-identical.
+
+## Stop and report if
+
+- `make smoke` fails twice in the same way.

docs/plans/v1/README.md

@@ -0,0 +1,127 @@
+# v1 implementation plan: leases, queueing, accounting
+
+> **For the implementing model:** do not work from this file. The owner gives you one task file at
+> a time (`01-…` to `07-…`). This file is the index for the owner and the reviewer.
+
+**Goal:** `PLAN.md` §4–§7a. Every conversation gets a sticky lease on one host (chosen by free
+slots × weight when it starts), requests queue per (host, model) instead of overflowing a
+router, an operator can pin a route or drain a host, and SQLite keeps the leases and an accounting
+log that answers "which session used which host and model, for how long, at what cache-hit rate".
+
+**Architecture:** five new packages — `store` (SQLite, `modernc.org/sqlite`), `fingerprint`
+(conversation key), `choose` (the scoring rule), `limiter` (per-(host, model) slots + bounded
+FIFO), `lease` (the sticky table, persisted through `store`) — and v1 versions of `proxy`,
+`admin`, `config` and `cmd/crossbar`. The proxy tees streamed responses through an SSE scanner
+to read the final `usage`/`timings` chunk; it never buffers or alters the stream.
+
+**How this plan was made:** acceptance tests first, from `PLAN.md`; no reference implementation.
+Every given test file was compiled against a panic-only skeleton of the interfaces named in the
+tasks (`go vet ./...` clean), and nothing else was run. If a test turns out to be wrong, that is
+the owner's finding: stop and report as `AGENTS.md` says; do not edit it.
+
+**Tech stack:** Go 1.26, stdlib, `github.com/BurntSushi/toml` v1.6.0, `modernc.org/sqlite`
+v1.59.0 (pure Go; `go.sum` given). No other module.
+
+## Global constraints
+
+- Everything in `AGENTS.md`. Branch `v1`. One task, one fresh OpenCode session, one commit.
+- Bodies are never logged or stored. Rows carry names, counts and timings only.
+- Given files (tests, `example.toml`, `cmd/fakeupstream/main.go`, `tools/smoke.sh`, `go.sum`)
+  are copied and never edited. Some **replace** v0 files of the same name; the task says so.
+
+## Tasks
+
+| # | File | Delivers | Tests that define it |
+|---|---|---|---|
+| 01 | `01-store.md` | `internal/store`: SQLite state + accounting | `internal/store/store_test.go` |
+| 02 | `02-fingerprint-config.md` | `internal/fingerprint`; `config` gains `db`, `lease_idle`, `retention`, day suffix | `fingerprint_test.go`, `config_v1_test.go` |
+| 03 | `03-limiter-choose.md` | `internal/limiter`, `internal/choose` | `limiter_test.go`, `choose_test.go` |
+| 04 | `04-lease.md` | `internal/lease`: the sticky table | `lease_test.go` |
+| 05 | `05-proxy.md` | proxy v1: leases, queue, SSE tee, accounting, header route | `proxy_test.go` (replaces v0's) |
+| 06 | `06-admin.md` | admin v1 (pin/release/drain/usage/metrics) | `admin_test.go` (replaces) |
+| 07 | `07-main.md` | `cmd/crossbar` wiring, background loops | start/stop check |
+| 08 | `08-smoke-readme.md` | `tools/smoke.sh` v1 run, README update | `make smoke` |
+
+## For the owner: running a task
+
+```sh
+tools/run-plan.sh docs/plans/v1          # from a clean checkout on master
+```
+
+## For the reviewer: after task 08
+
+1. `git log --oneline master..v1`: eight task commits with the trailer (plus owner merges).
+2. Copied files byte-identical to `_files/`; `git diff <merge-base>..v1 --stat -- PLAN.md AGENTS.md docs/plans` empty.
+3. `make gate`, `make smoke`.
+4. Read every source file against its task. Probe outside the tests: a lease whose host is
+   drained *and* unhealthy; `lease_idle` expiry while a request is in flight; a stream cut by the
+   client mid-way (the accounting row must still be written, with the status it had); a body
+   with `"messages"` that is not an array; two crossbars on the same `db` file; `Prune` while
+   requests are being recorded.
+5. Every `.(` type assertion in `internal/` is the two-value form or on a value we constructed.
+6. Findings under "Reviews" in `docs/implementer-log.md`, by fault (model / task / test).
+
+## Changes during the run
+
+- 2026-09-25, task 01, first attempt: three given test files under `_files/` were not `gofmt`-clean,
+  and the gate's `gofmt -l .` walks every file, so the gate failed on files the implementer may
+  not edit. Ornith diagnosed it (gofmt on its own code was clean) and did not touch them.
+  Owner's fault (the compile check ran `go vet`, not `gofmt`, on the given files). Fixed by
+  formatting the given files; the plan checklist now includes `gofmt -l docs/` before handover.
+  Ornith stopped correctly (a `stopped` row, code left in the tree, only the log committed);
+  a second session was told where the first had stopped and finished steps 6–7 without
+  starting over — the boxmaker precedent (`M3a/19`). The driver was then resumed from task 02.
+- 2026-09-25, task 02: v0's given `testdata/bad-unknown-key.toml` used `lease_idle` as its
+  unknown-key example, and v1 makes `lease_idle` a real key, so v0's `TestBadFiles` broke — the
+  task did not hand over replacements for the two v0 given files (tip T19). Ornith changed the
+  example to `bogus_key` in both files and logged it in Deviations; the content is right, but the
+  files were protected and the rule was to stop. Owner's fault for the conflict; the model's
+  deviation is noted. The corrected files now sit in `_files/internal/config/` as the reference
+  copies for the reviewer's byte-exact check.
+- 2026-09-25, task 04: my `TestPinAndUnpin` asserted the pin event at exactly `len-3` and the
+  release event at `len-1`, but the task's own rules make acquires under a pin record events too,
+  so a faithful implementation produces `[new pin pin new new release]` and the assertion cannot
+  hold. Ornith spent its first ten minutes puzzling over exactly that. Test fault (mine): the
+  assertion now checks order and content (a pin event naming beta, followed later by a release),
+  not positions.
+- 2026-09-25, before task 05 ran: a hand walk of the remaining given tests against the task rules
+  (which I should have done before handover) found two more faults of mine and one flake:
+  `TestDifferentConversationsSpreadByFreeSlots` assumed two conversations would both land on the
+  weight-2 host, but the scoring rule's tie-break sends the second to the other host — it now
+  uses a config where beta's weight is 10; `TestPinReleaseDrain` (admin) pins a route no request
+  has used, which `lease.Pin`'s "host must have been seen" rule refuses — task 06 now adds
+  `lease.Table.Candidates` and has the admin and `main` register configured hosts;
+  `TestQueueFullIs503` read the store right after the responses without the retry loop the
+  accounting test has. Task 05 restarted from a clean tree on the corrected files.
+- 2026-09-25, task 05, first session: ended after ~25 min without a commit or a row, 6 of 8 given
+  tests passing. Three things happened. (a) My replacement `proxy_test.go` dropped the
+  `fakeHealth` helper that v0.1's `recorder_test.go` uses; Ornith recreated it as
+  `helpers_test.go` — right call, unlisted file; it is now a given file (task fault). (b) My
+  fake upstream's `/v1/models` handler did not record requests, so `TestV0BehaviourStillHolds`
+  read an empty record — test fault, fixed. (c) Ornith tried to write an experiment under `/tmp`,
+  the sandbox refused, and it ended its turn with "Let me experiment…" and no tool call — the
+  known Ornith failure mode (I9), here triggered by a denied tool. Model fault; task 05 now says
+  a refusal is not a reason to stop. The tee's token extraction (`TestAccountingRows…`) was the
+  genuinely unfinished part. Resumed from the working tree.
+- 2026-09-25, task 05, resume session: my given `proxy_test.go` was 433 lines, over the gate's
+  400-line limit that `scripts/check-lines.sh` applies to every `.go` file including the copied
+  test and the plan copy under `docs/`. Ornith found it and went digging in git history instead
+  of stopping. Test-file fault (mine): the rig and fake-upstream scaffolding moved into
+  `helpers_test.go` (211 + 271 lines). Ornith's own `proxy.go` was also at 411 lines; splitting it
+  is part of the task as written.
+- 2026-09-25, task 06, first session: 50 minutes, admin package never compiled (duplicate
+  `Handler`, re-reading the same files in a loop) while the store and lease additions it made
+  were correct. Too large a task for one session — the size lesson from boxmaker, mine to apply.
+  Split into `06-admin.md` (handler only; inherits the store/lease additions from the tree) and
+  `07-main.md` (wiring); the smoke task became 08. Session stopped by the owner; the broken
+  `admin.go` draft was left in the tree for the next session to replace.
+- 2026-09-25, task 06 (admin), during the run: the task text said the wiring in `cmd/crossbar`
+  "does not fail the gate", but `go vet ./...` compiles `main.go`, whose two-argument
+  `admin.Handler` call no longer matches — the gate does fail. Ornith noticed while reading.
+  Task fault (mine): step 5 now allows the one-call edit to `main.go`.
+- 2026-09-25, task 08, first session: smoke check 1 sent conversation A to alpha, not beta. Cause:
+  my task 05 rule `Free: lim.FreeSlots(host)` sums a host's slots across all its models, so
+  alpha's six `small-9b` slots outscored beta's two `ornith` slots for an `ornith` request. The
+  smoke's expectation (per-model slots) is the right semantics. Task fault (mine): task 05's rule
+  is corrected and task 08 gained step 1b, the one code change allowed in it. Ornith had
+  diagnosed the summing correctly before it was stopped.

docs/plans/v1/_files/cmd/fakeupstream/main.go

@@ -0,0 +1,115 @@
+// fakeupstream stands in for a llama-server router in tests and the smoke run. Do not edit.
+//
+//	fakeupstream -listen 127.0.0.1:18081 -name alpha -models a,b -down-file /tmp/alpha.down -slow 0
+//
+// /health answers 503 while the down file exists, 200 otherwise. /v1/models lists -models.
+// /props answers a small JSON object. /v1/chat/completions echoes: a streamed answer of five
+// SSE chunks 200 ms apart when the body has "stream": true, then a final chunk carrying
+// "usage" and llama-server style "timings", then [DONE]; one JSON answer with usage and
+// timings otherwise. -slow adds that many milliseconds before answering (for queue tests).
+// Every response carries X-Upstream: <name>.
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+)
+
+func main() {
+	listen := flag.String("listen", "127.0.0.1:18081", "address to listen on")
+	name := flag.String("name", "fake", "name reported in X-Upstream and answers")
+	models := flag.String("models", "m", "comma-separated model ids for /v1/models")
+	downFile := flag.String("down-file", "", "while this file exists, /health answers 503")
+	slow := flag.Int("slow", 0, "milliseconds to wait before answering a completion")
+	flag.Parse()
+
+	ids := strings.Split(*models, ",")
+	mux := http.NewServeMux()
+	stamp := func(w http.ResponseWriter) { w.Header().Set("X-Upstream", *name) }
+	usage := map[string]any{"prompt_tokens": 100, "completion_tokens": 10, "total_tokens": 110}
+	timings := map[string]any{"prompt_n": 100, "cache_n": 90, "predicted_n": 10, "predicted_ms": 50.0}
+
+	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
+		stamp(w)
+		if *downFile != "" {
+			if _, err := os.Stat(*downFile); err == nil {
+				http.Error(w, `{"error":{"message":"Loading model"}}`, http.StatusServiceUnavailable)
+				return
+			}
+		}
+		writeJSON(w, map[string]string{"status": "ok"})
+	})
+	mux.HandleFunc("/v1/models", func(w http.ResponseWriter, r *http.Request) {
+		stamp(w)
+		data := []map[string]any{}
+		for _, id := range ids {
+			data = append(data, map[string]any{"id": id, "object": "model", "owned_by": *name})
+		}
+		writeJSON(w, map[string]any{"object": "list", "data": data})
+	})
+	mux.HandleFunc("/props", func(w http.ResponseWriter, r *http.Request) {
+		stamp(w)
+		writeJSON(w, map[string]any{"default_generation_settings": map[string]any{"n_ctx": 8192}, "total_slots": 2, "model_path": *name})
+	})
+	mux.HandleFunc("/v1/chat/completions", func(w http.ResponseWriter, r *http.Request) {
+		stamp(w)
+		body, _ := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+		var req struct {
+			Model  string `json:"model"`
+			Stream bool   `json:"stream"`
+		}
+		_ = json.Unmarshal(body, &req)
+		time.Sleep(time.Duration(*slow) * time.Millisecond)
+		if !req.Stream {
+			writeJSON(w, map[string]any{
+				"id": "chatcmpl-fake", "object": "chat.completion", "model": req.Model,
+				"choices": []map[string]any{{"index": 0, "message": map[string]string{"role": "assistant", "content": "hello from " + *name}, "finish_reason": "stop"}},
+				"usage":   usage, "timings": timings,
+			})
+			return
+		}
+		w.Header().Set("Content-Type", "text/event-stream")
+		w.Header().Set("Cache-Control", "no-cache")
+		w.WriteHeader(http.StatusOK)
+		fl, _ := w.(http.Flusher)
+		flush := func() {
+			if fl != nil {
+				fl.Flush()
+			}
+		}
+		for i := 1; i <= 5; i++ {
+			chunk := map[string]any{"id": "chatcmpl-fake", "object": "chat.completion.chunk", "model": req.Model,
+				"choices": []map[string]any{{"index": 0, "delta": map[string]string{"content": fmt.Sprintf("%s chunk %d ", *name, i)}}}}
+			b, _ := json.Marshal(chunk)
+			fmt.Fprintf(w, "data: %s\n\n", b)
+			flush()
+			time.Sleep(200 * time.Millisecond)
+		}
+		final := map[string]any{"id": "chatcmpl-fake", "object": "chat.completion.chunk", "model": req.Model,
+			"choices": []map[string]any{}, "usage": usage, "timings": timings}
+		b, _ := json.Marshal(final)
+		fmt.Fprintf(w, "data: %s\n\n", b)
+		flush()
+		fmt.Fprint(w, "data: [DONE]\n\n")
+	})
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		stamp(w)
+		http.Error(w, `{"error":"not found"}`, http.StatusNotFound)
+	})
+
+	log.Printf("fakeupstream %s listening on %s models=%v slow=%dms", *name, *listen, ids, *slow)
+	srv := &http.Server{Addr: *listen, Handler: mux, ReadHeaderTimeout: 5 * time.Second}
+	log.Fatal(srv.ListenAndServe())
+}
+
+func writeJSON(w http.ResponseWriter, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(v)
+}

docs/plans/v1/_files/example.toml

@@ -0,0 +1,26 @@
+# crossbar example configuration (v1). Replace <tailnet> and the addresses with your own.
+listen        = "127.0.0.1:17777"   # never 0.0.0.0 — bind the tailnet address in production
+db            = "crossbar.db"       # SQLite: leases + accounting (WAL). /var/lib/crossbar/crossbar.db under systemd
+poll_interval = "1s"                # 60s in production; 1s makes the smoke run quick
+lease_idle    = "30m"               # a conversation idle this long loses its host
+retention     = "180d"              # per-request rows older than this are rolled up daily
+queue_max     = 1                   # waiting places per (host, model) beyond `parallel`; 503 past that
+
+[hosts.alpha]
+base_url = "http://127.0.0.1:18081"    # e.g. http://straylight.<tailnet>:11434
+weight   = 1.0
+models   = { "ornith-1.5-35b-a3b" = { parallel = 1 }, "small-9b" = { parallel = 6 } }
+
+[hosts.beta]
+base_url = "http://127.0.0.1:18082"    # e.g. http://titan.<tailnet>:8081
+weight   = 2.0
+models   = { "ornith-1.5-35b-a3b" = { parallel = 2 } }
+
+# v1: a route is a set of candidate hosts; each conversation gets a sticky lease on the host with
+# the most free slots × weight at the time it starts. Pins and drains come from the admin API.
+[routes.opencode-a]
+hosts         = ["alpha", "beta"]
+default_model = "ornith-1.5-35b-a3b"
+
+[routes.hermes-x]
+hosts = ["beta", "alpha"]

docs/plans/v1/_files/go.sum

@@ -0,0 +1,52 @@
+github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
+github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
+github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
+golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/tools v0.48.0/go.mod h1:08xX0orndb/F7jJxGDicx061tyd5pcMto75YMAXr6lk=
+golang.org/x/tools v0.48.0 h1:3+hClM1aLL5mjMKm5ovokw9epgRXPuu2tILgismM6RE=
+modernc.org/ccgo/v4 v4.35.0/go.mod h1:qrVGs9S3Sr2Ztcg9ve+kTAYMp5a3YvWjo+SoN06kJ5I=
+modernc.org/ccgo/v4 v4.35.0 h1:F+TUsmw09QxLzmi3aeYYGxjAXarmZaKgj3mKQHNaA8w=
+modernc.org/cc/v4 v4.29.2/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
+modernc.org/cc/v4 v4.29.2 h1:h6+9ciCnPKutf4I03CvheAvDLX7+IHlqR6Iy6J+cgd8=
+modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
+modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v3 v3.1.5/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/gc/v3 v3.1.5 h1:21ldfPfRYE31Tb7B3mwAK8gy1AxP4+dKjrOQPfqakoc=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/libc v1.75.7/go.mod h1:bO5o2ztHxBb2rjz0PgdHN0sSMw57CgxGFLZ3Qd/QpVQ=
+modernc.org/libc v1.75.7 h1:o3DTP9/0p9pKmY2WCKQaySW6wIiZhNM7wc2lUoyhfew=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/memory v1.12.1/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/memory v1.12.1 h1:nFMiWrpStgZczNl6XI9GnIk/rWhYIyHGUaR04pGbp9g=
+modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sqlite v1.59.0/go.mod h1:+paeT2A3iPRHkQDwG7oA6Tk0zQd5woMEI8q7orfry8k=
+modernc.org/sqlite v1.59.0 h1:X1es1GpqBlS/5T+vbM4HLUdaa8OtQx468DF2vrx+38A=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=

docs/plans/v1/_files/internal/admin/admin_test.go

@@ -0,0 +1,293 @@
+package admin_test
+
+// v1 admin: read the tables, pin/release a route, drain a host, usage rollups, metrics.
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/admin"
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+	"git.wntrmute.dev/kyle/crossbar/internal/health"
+	"git.wntrmute.dev/kyle/crossbar/internal/lease"
+	"git.wntrmute.dev/kyle/crossbar/internal/limiter"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+type fakeHosts struct {
+	st       map[string]health.Status
+	draining map[string]bool
+}
+
+func (f *fakeHosts) All() map[string]health.Status { return f.st }
+func (f *fakeHosts) Healthy(n string) bool         { return f.st[n].Healthy }
+func (f *fakeHosts) Draining(n string) bool        { return f.draining[n] }
+func (f *fakeHosts) SetDraining(n string, on bool) { f.draining[n] = on }
+func (f *fakeHosts) Choose(c []string, model string) (string, bool) {
+	for _, h := range c {
+		if f.st[h].Healthy && !f.draining[h] {
+			return h, true
+		}
+	}
+	return "", false
+}
+
+type rig struct {
+	h      http.Handler
+	store  *store.Store
+	leases *lease.Table
+	hosts  *fakeHosts
+}
+
+func newRig(t *testing.T) *rig {
+	cfg, err := config.Parse(strings.NewReader(`
+listen = "127.0.0.1:1"
+[hosts.alpha]
+base_url = "http://alpha:1"
+models = { "m" = { parallel = 2 } }
+[hosts.beta]
+base_url = "http://beta:1"
+models = { "m" = { parallel = 4 } }
+[routes.r]
+hosts = ["alpha", "beta"]
+default_model = "m"
+`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	st, err := store.Open(filepath.Join(t.TempDir(), "x.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	hosts := &fakeHosts{
+		st: map[string]health.Status{
+			"alpha": {Healthy: true, Loaded: []string{"m"}, LastOK: time.Date(2026, 9, 25, 8, 0, 0, 0, time.UTC)},
+			"beta":  {Healthy: false, LastErr: "HTTP 503"},
+		},
+		draining: map[string]bool{},
+	}
+	lt, err := lease.New(st, hosts, hosts, 30*time.Minute)
+	if err != nil {
+		t.Fatal(err)
+	}
+	lim := limiter.New()
+	lim.Configure("alpha", "m", 2, 8)
+	lim.Configure("beta", "m", 4, 8)
+	return &rig{h: admin.Handler(cfg, hosts, lt, lim, st, hosts), store: st, leases: lt, hosts: hosts}
+}
+
+func (r *rig) do(t *testing.T, method, path, body string, hdr ...string) *httptest.ResponseRecorder {
+	req := httptest.NewRequest(method, path, strings.NewReader(body))
+	if body != "" {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	for i := 0; i+1 < len(hdr); i += 2 {
+		req.Header.Set(hdr[i], hdr[i+1])
+	}
+	rec := httptest.NewRecorder()
+	r.h.ServeHTTP(rec, req)
+	return rec
+}
+
+func TestHostsShowsSlotsAndDrain(t *testing.T) {
+	r := newRig(t)
+	rec := r.do(t, "GET", "/_crossbar/hosts", "")
+	if rec.Code != 200 {
+		t.Fatalf("%d %s", rec.Code, rec.Body.String())
+	}
+	var out map[string]admin.HostView
+	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	a := out["alpha"]
+	if !a.Healthy || a.FreeSlots != 2 || a.InFlight != 0 || a.Queued != 0 || a.Draining || a.LastOK != "2026-09-25T08:00:00Z" {
+		t.Errorf("alpha = %+v", a)
+	}
+	if b := out["beta"]; b.Healthy || b.LastErr != "HTTP 503" || b.FreeSlots != 4 || b.Loaded == nil {
+		t.Errorf("beta = %+v (loaded must be [] not null)", b)
+	}
+}
+
+func TestRoutesShowsLeases(t *testing.T) {
+	r := newRig(t)
+	now := time.Date(2026, 9, 25, 9, 0, 0, 0, time.UTC)
+	if _, _, err := r.leases.Acquire(lease.Key{Route: "r", FP: "abc", Model: "m"}, []string{"alpha", "beta"}, now); err != nil {
+		t.Fatal(err)
+	}
+	rec := r.do(t, "GET", "/_crossbar/routes", "")
+	var out map[string]admin.RouteView
+	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+		t.Fatalf("%v: %s", err, rec.Body.String())
+	}
+	rv := out["r"]
+	if len(rv.Hosts) != 2 || rv.DefaultModel != "m" || rv.Pinned != "" {
+		t.Errorf("route view = %+v", rv)
+	}
+	if len(rv.Leases) != 1 || rv.Leases[0].FP != "abc" || rv.Leases[0].Host != "alpha" || rv.Leases[0].State != "active" || rv.Leases[0].LastUsed != "2026-09-25T09:00:00Z" {
+		t.Errorf("leases = %+v", rv.Leases)
+	}
+}
+
+func TestPinReleaseDrain(t *testing.T) {
+	r := newRig(t)
+	rec := r.do(t, "POST", "/_crossbar/routes/r", `{"host":"beta","pin":true}`)
+	if rec.Code != 200 {
+		t.Fatalf("pin: %d %s", rec.Code, rec.Body.String())
+	}
+	if h, _, err := r.leases.Acquire(lease.Key{Route: "r", FP: "x", Model: "m"}, []string{"alpha", "beta"}, time.Now()); err == nil || h != "" {
+		// beta is unhealthy in the rig: a pin to a down host is honoured, not silently moved
+		t.Errorf("acquire on a route pinned to a down host: %q %v, want ErrPinnedDown", h, err)
+	}
+	rec = r.do(t, "GET", "/_crossbar/routes", "")
+	var out map[string]admin.RouteView
+	_ = json.Unmarshal(rec.Body.Bytes(), &out)
+	if out["r"].Pinned != "beta" {
+		t.Errorf("Pinned = %q after pin", out["r"].Pinned)
+	}
+	rec = r.do(t, "POST", "/_crossbar/routes/r", `{"release":true}`)
+	if rec.Code != 200 {
+		t.Fatalf("release: %d %s", rec.Code, rec.Body.String())
+	}
+	if h, _, err := r.leases.Acquire(lease.Key{Route: "r", FP: "x", Model: "m"}, []string{"alpha", "beta"}, time.Now()); err != nil || h != "alpha" {
+		t.Errorf("after release: %q %v, want alpha (the only healthy host)", h, err)
+	}
+	for _, tc := range []struct {
+		body string
+		want int
+	}{
+		{`{"host":"nobody","pin":true}`, 404},
+		{`{"pin":true}`, 400},
+		{`not json`, 400},
+		{`{"release":true,"pin":true,"host":"alpha"}`, 400},
+	} {
+		if rec := r.do(t, "POST", "/_crossbar/routes/r", tc.body); rec.Code != tc.want {
+			t.Errorf("POST %s: %d, want %d (%s)", tc.body, rec.Code, tc.want, rec.Body.String())
+		}
+	}
+	if rec := r.do(t, "POST", "/_crossbar/routes/nope", `{"release":true}`); rec.Code != 404 {
+		t.Errorf("unknown route: %d", rec.Code)
+	}
+
+	rec = r.do(t, "POST", "/_crossbar/hosts/alpha", `{"drain":true}`)
+	if rec.Code != 200 || !r.hosts.Draining("alpha") {
+		t.Fatalf("drain: %d %s draining=%v", rec.Code, rec.Body.String(), r.hosts.Draining("alpha"))
+	}
+	rec = r.do(t, "GET", "/_crossbar/hosts", "")
+	var hv map[string]admin.HostView
+	_ = json.Unmarshal(rec.Body.Bytes(), &hv)
+	if !hv["alpha"].Draining {
+		t.Errorf("hosts view must show draining")
+	}
+	if rec := r.do(t, "POST", "/_crossbar/hosts/alpha", `{"drain":false}`); rec.Code != 200 || r.hosts.Draining("alpha") {
+		t.Errorf("undrain: %d draining=%v", rec.Code, r.hosts.Draining("alpha"))
+	}
+	if rec := r.do(t, "POST", "/_crossbar/hosts/nobody", `{"drain":true}`); rec.Code != 404 {
+		t.Errorf("unknown host: %d", rec.Code)
+	}
+}
+
+func seedUsage(t *testing.T, st *store.Store) {
+	t0 := time.Now().UTC().Add(-time.Hour)
+	for i, r := range []store.Request{
+		{Route: "r", FP: "a", Model: "m", Host: "alpha", Status: 200, TotalMs: 1000, PromptTokens: 100, CachedTokens: 80, CompletionTokens: 10},
+		{Route: "r", FP: "a", Model: "m", Host: "alpha", Status: 200, TotalMs: 500, QueuedMs: 30, PromptTokens: 100, CachedTokens: 100, CompletionTokens: 5},
+		{Route: "r2", FP: "b", Model: "m", Host: "beta", Status: 503, TotalMs: 1, Err: "queue full"},
+	} {
+		r.Started = t0.Add(time.Duration(i) * time.Minute)
+		if err := st.RecordRequest(r); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func TestUsageJSONAndText(t *testing.T) {
+	r := newRig(t)
+	seedUsage(t, r.store)
+	rec := r.do(t, "GET", "/_crossbar/usage?by=route", "")
+	if rec.Code != 200 || !strings.HasPrefix(rec.Header().Get("Content-Type"), "application/json") {
+		t.Fatalf("%d %q", rec.Code, rec.Header().Get("Content-Type"))
+	}
+	var rows []store.UsageRow
+	if err := json.Unmarshal(rec.Body.Bytes(), &rows); err != nil {
+		t.Fatalf("%v: %s", err, rec.Body.String())
+	}
+	if len(rows) != 2 {
+		t.Fatalf("rows = %+v", rows)
+	}
+	for _, row := range rows {
+		if row.Key == "r" && (row.Requests != 2 || row.CachedTokens != 180 || row.QueuedMs != 30) {
+			t.Errorf("r = %+v", row)
+		}
+		if row.Key == "r2" && (row.Requests != 1 || row.Errors != 1) {
+			t.Errorf("r2 = %+v", row)
+		}
+	}
+	rec = r.do(t, "GET", "/_crossbar/usage?by=host&since=24h", "", "Accept", "text/plain")
+	if rec.Code != 200 || !strings.HasPrefix(rec.Header().Get("Content-Type"), "text/plain") {
+		t.Fatalf("text: %d %q", rec.Code, rec.Header().Get("Content-Type"))
+	}
+	body := rec.Body.String()
+	if !strings.Contains(body, "alpha") || !strings.Contains(body, "beta") || !strings.Contains(strings.ToLower(body), "cache") {
+		t.Errorf("text table = %q", body)
+	}
+	if rec := r.do(t, "GET", "/_crossbar/usage?by=colour", ""); rec.Code != 400 {
+		t.Errorf("bad by: %d", rec.Code)
+	}
+	if rec := r.do(t, "GET", "/_crossbar/usage?since=yesterday", ""); rec.Code != 400 {
+		t.Errorf("bad since: %d", rec.Code)
+	}
+	rec = r.do(t, "GET", "/_crossbar/usage?since=2026-09-25T00:00:00Z&by=model", "")
+	if rec.Code != 200 {
+		t.Errorf("RFC3339 since: %d %s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestMetrics(t *testing.T) {
+	r := newRig(t)
+	seedUsage(t, r.store)
+	rec := r.do(t, "GET", "/_crossbar/metrics", "")
+	if rec.Code != 200 || !strings.HasPrefix(rec.Header().Get("Content-Type"), "text/plain") {
+		t.Fatalf("%d %q", rec.Code, rec.Header().Get("Content-Type"))
+	}
+	body := rec.Body.String()
+	for _, want := range []string{
+		`# TYPE crossbar_requests_total counter`,
+		`crossbar_requests_total{route="r",host="alpha",status="200"} 2`,
+		`crossbar_requests_total{route="r2",host="beta",status="503"} 1`,
+		`crossbar_host_healthy{host="alpha"} 1`,
+		`crossbar_host_healthy{host="beta"} 0`,
+		`crossbar_host_free_slots{host="alpha"} 2`,
+		`crossbar_prompt_tokens_total{route="r"} 200`,
+		`crossbar_cached_tokens_total{route="r"} 180`,
+		`crossbar_queue_wait_ms_total{route="r"} 30`,
+	} {
+		if !strings.Contains(body, want) {
+			t.Errorf("metrics missing %q\n%s", want, body)
+		}
+	}
+}
+
+func TestMethodsAndUnknown(t *testing.T) {
+	r := newRig(t)
+	for _, tc := range []struct {
+		method, path string
+		want         int
+	}{
+		{http.MethodPost, "/_crossbar/hosts", 405},
+		{http.MethodDelete, "/_crossbar/routes", 405},
+		{http.MethodGet, "/_crossbar/routes/r", 405},
+		{http.MethodGet, "/_crossbar/nope", 404},
+		{http.MethodPut, "/_crossbar/usage", 405},
+	} {
+		rec := r.do(t, tc.method, tc.path, "")
+		if rec.Code != tc.want || !strings.HasPrefix(rec.Header().Get("Content-Type"), "application/json") {
+			t.Errorf("%s %s = %d %q, want %d JSON", tc.method, tc.path, rec.Code, rec.Header().Get("Content-Type"), tc.want)
+		}
+	}
+}

docs/plans/v1/_files/internal/choose/choose_test.go

@@ -0,0 +1,83 @@
+package choose_test
+
+import (
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/choose"
+)
+
+func infoFor(m map[string]choose.Info) func(string) (choose.Info, bool) {
+	return func(name string) (choose.Info, bool) { i, ok := m[name]; return i, ok }
+}
+
+func TestMostFreeSlotsTimesWeightWins(t *testing.T) {
+	info := infoFor(map[string]choose.Info{
+		"alpha": {Healthy: true, Loaded: true, CanServe: true, Free: 3, Weight: 1.0},
+		"beta":  {Healthy: true, Loaded: true, CanServe: true, Free: 2, Weight: 2.0}, // 4 > 3
+		"gamma": {Healthy: true, Loaded: true, CanServe: true, Free: 4, Weight: 0.5}, // 2
+	})
+	got, ok := choose.Best([]string{"alpha", "beta", "gamma"}, info)
+	if !ok || got != "beta" {
+		t.Errorf("got %q %v, want beta", got, ok)
+	}
+}
+
+func TestTieGoesToShortestQueueThenListOrder(t *testing.T) {
+	info := infoFor(map[string]choose.Info{
+		"alpha": {Healthy: true, Loaded: true, CanServe: true, Free: 2, Weight: 1, Queued: 3},
+		"beta":  {Healthy: true, Loaded: true, CanServe: true, Free: 2, Weight: 1, Queued: 1},
+		"gamma": {Healthy: true, Loaded: true, CanServe: true, Free: 2, Weight: 1, Queued: 1},
+	})
+	if got, _ := choose.Best([]string{"alpha", "beta", "gamma"}, info); got != "beta" {
+		t.Errorf("tie on score: shortest queue wins, then list order; got %q", got)
+	}
+	if got, _ := choose.Best([]string{"gamma", "beta"}, info); got != "gamma" {
+		t.Errorf("full tie: first in list order wins; got %q", got)
+	}
+}
+
+func TestLoadedBeatsMerelyCapable(t *testing.T) {
+	info := infoFor(map[string]choose.Info{
+		"alpha": {Healthy: true, Loaded: false, CanServe: true, Free: 8, Weight: 4},
+		"beta":  {Healthy: true, Loaded: true, CanServe: true, Free: 1, Weight: 1},
+	})
+	got, ok := choose.Best([]string{"alpha", "beta"}, info)
+	if !ok || got != "beta" {
+		t.Errorf("a host that has the model loaded wins over one that would have to load it; got %q", got)
+	}
+}
+
+func TestFallsBackToCapableHost(t *testing.T) {
+	info := infoFor(map[string]choose.Info{
+		"alpha": {Healthy: true, Loaded: false, CanServe: true, Free: 1, Weight: 1},
+		"beta":  {Healthy: true, Loaded: false, CanServe: false, Free: 9, Weight: 9},
+	})
+	got, ok := choose.Best([]string{"beta", "alpha"}, info)
+	if !ok || got != "alpha" {
+		t.Errorf("only a host configured to serve the model may load it; got %q %v", got, ok)
+	}
+}
+
+func TestSkipsUnhealthyDrainingUnknownAndFull(t *testing.T) {
+	info := infoFor(map[string]choose.Info{
+		"down":  {Healthy: false, Loaded: true, CanServe: true, Free: 9, Weight: 9},
+		"drain": {Healthy: true, Draining: true, Loaded: true, CanServe: true, Free: 9, Weight: 9},
+		"full":  {Healthy: true, Loaded: true, CanServe: true, Free: 0, Weight: 9, Queued: 0},
+		"ok":    {Healthy: true, Loaded: true, CanServe: true, Free: 1, Weight: 1},
+	})
+	got, ok := choose.Best([]string{"down", "drain", "missing", "full", "ok"}, info)
+	if !ok || got != "ok" {
+		t.Errorf("got %q %v, want ok", got, ok)
+	}
+	// A full host is still better than nothing: it gets the request (it will queue).
+	got, ok = choose.Best([]string{"down", "full"}, info)
+	if !ok || got != "full" {
+		t.Errorf("with only a full host left it must still be chosen; got %q %v", got, ok)
+	}
+	if _, ok := choose.Best([]string{"down", "drain", "missing"}, info); ok {
+		t.Errorf("nothing usable must give ok=false")
+	}
+	if _, ok := choose.Best(nil, info); ok {
+		t.Errorf("empty candidates must give ok=false")
+	}
+}

docs/plans/v1/_files/internal/config/config_test.go

@@ -0,0 +1,191 @@
+package config_test
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+)
+
+func TestGoodFile(t *testing.T) {
+	c, err := config.Load(filepath.Join("testdata", "good.toml"))
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if c.Listen != "100.64.0.9:7777" {
+		t.Errorf("Listen = %q", c.Listen)
+	}
+	if c.PollInterval.Duration != 5*time.Second {
+		t.Errorf("PollInterval = %v", c.PollInterval.Duration)
+	}
+	if c.QueueMax != 4 {
+		t.Errorf("QueueMax = %d", c.QueueMax)
+	}
+	alpha := c.Hosts["alpha"]
+	if alpha.BaseURL != "http://alpha.example:11434" {
+		t.Errorf("trailing slash not stripped: %q", alpha.BaseURL)
+	}
+	if alpha.Weight != 2 {
+		t.Errorf("alpha.Weight = %v", alpha.Weight)
+	}
+	if alpha.Models["ornith-1.5-35b-a3b"].Parallel != 4 || alpha.Models["small-9b"].Parallel != 6 {
+		t.Errorf("alpha.Models = %+v", alpha.Models)
+	}
+	beta := c.Hosts["beta"]
+	if beta.Weight != 1 {
+		t.Errorf("beta.Weight default = %v, want 1", beta.Weight)
+	}
+	if beta.Models["ornith-1.5-35b-a3b"].Parallel != 1 {
+		t.Errorf("beta parallel default = %d, want 1", beta.Models["ornith-1.5-35b-a3b"].Parallel)
+	}
+	r := c.Routes["opencode-a"]
+	if len(r.Hosts) != 2 || r.Hosts[0] != "alpha" || r.Hosts[1] != "beta" {
+		t.Errorf("route hosts = %v", r.Hosts)
+	}
+	if r.DefaultModel != "ornith-1.5-35b-a3b" {
+		t.Errorf("DefaultModel = %q", r.DefaultModel)
+	}
+	if c.Routes["hermes-x"].DefaultModel != "" {
+		t.Errorf("hermes-x DefaultModel should be empty")
+	}
+	if !c.Serves("alpha", "small-9b") || c.Serves("beta", "small-9b") || c.Serves("nope", "m") {
+		t.Errorf("Serves is wrong")
+	}
+}
+
+func TestDefaults(t *testing.T) {
+	c, err := config.Parse(strings.NewReader(`
+listen = "127.0.0.1:1"
+[hosts.a]
+base_url = "http://a:1"
+models = { "m" = { } }
+[routes.r]
+hosts = ["a"]
+`))
+	if err != nil {
+		t.Fatalf("Parse: %v", err)
+	}
+	if c.PollInterval.Duration != config.DefaultPollInterval {
+		t.Errorf("PollInterval default = %v", c.PollInterval.Duration)
+	}
+	if c.QueueMax != config.DefaultQueueMax {
+		t.Errorf("QueueMax default = %d", c.QueueMax)
+	}
+}
+
+func TestBadFiles(t *testing.T) {
+	cases := []struct{ file, field string }{
+		{"bad-listen.toml", "listen"},
+		{"bad-unknown-host.toml", "routes.r.hosts"},
+		{"bad-default-model.toml", "routes.r.default_model"},
+		{"bad-unknown-key.toml", "bogus_key"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.file, func(t *testing.T) {
+			_, err := config.Load(filepath.Join("testdata", tc.file))
+			if err == nil {
+				t.Fatalf("want error")
+			}
+			e, ok := config.IsError(err)
+			if !ok {
+				t.Fatalf("want *config.Error, got %T: %v", err, err)
+			}
+			if e.Field != tc.field {
+				t.Errorf("Field = %q, want %q (%v)", e.Field, tc.field, err)
+			}
+			if !strings.HasPrefix(err.Error(), "config: "+tc.field+": ") {
+				t.Errorf("Error() = %q", err.Error())
+			}
+		})
+	}
+}
+
+func TestBadValues(t *testing.T) {
+	base := `
+listen = %q
+poll_interval = %q
+[hosts.a]
+base_url = %q
+weight = %v
+models = { "m" = { parallel = %d } }
+[routes.%s]
+hosts = ["a"]
+`
+	cases := []struct {
+		name                     string
+		listen, poll, url, route string
+		weight                   float64
+		parallel                 int
+		field                    string
+	}{
+		{"empty listen", "", "5s", "http://a:1", "r", 1, 1, "listen"},
+		{"no port", "127.0.0.1", "5s", "http://a:1", "r", 1, 1, "listen"},
+		{"v6 any", "[::]:7", "5s", "http://a:1", "r", 1, 1, "listen"},
+		{"poll too short", "127.0.0.1:7", "500ms", "http://a:1", "r", 1, 1, "poll_interval"},
+		{"ftp url", "127.0.0.1:7", "5s", "ftp://a:1", "r", 1, 1, "hosts.a.base_url"},
+		{"no host", "127.0.0.1:7", "5s", "http://", "r", 1, 1, "hosts.a.base_url"},
+		{"query", "127.0.0.1:7", "5s", "http://a:1/v1?x=1", "r", 1, 1, "hosts.a.base_url"},
+		{"negative weight", "127.0.0.1:7", "5s", "http://a:1", "r", -1, 1, "hosts.a.weight"},
+		{"negative parallel", "127.0.0.1:7", "5s", "http://a:1", "r", 1, -2, "hosts.a.models.m.parallel"},
+		{"route name", "127.0.0.1:7", "5s", "http://a:1", "Bad_Name", 1, 1, "routes.Bad_Name"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			text := fmt.Sprintf(base, tc.listen, tc.poll, tc.url, tc.weight, tc.parallel, tc.route)
+			_, err := config.Parse(strings.NewReader(text))
+			if err == nil {
+				t.Fatalf("want error for %s", tc.name)
+			}
+			e, ok := config.IsError(err)
+			if !ok {
+				t.Fatalf("want *config.Error, got %T: %v", err, err)
+			}
+			if e.Field != tc.field {
+				t.Errorf("Field = %q, want %q (%v)", e.Field, tc.field, err)
+			}
+		})
+	}
+}
+
+func TestMissingSections(t *testing.T) {
+	for _, tc := range []struct{ name, text, field string }{
+		{"no hosts", "listen = \"127.0.0.1:7\"\n[routes.r]\nhosts = [\"a\"]\n", "hosts"},
+		{"no routes", "listen = \"127.0.0.1:7\"\n[hosts.a]\nbase_url = \"http://a:1\"\nmodels = { \"m\" = { } }\n", "routes"},
+		{"host without models", "listen = \"127.0.0.1:7\"\n[hosts.a]\nbase_url = \"http://a:1\"\n[routes.r]\nhosts = [\"a\"]\n", "hosts.a.models"},
+		{"route without hosts", "listen = \"127.0.0.1:7\"\n[hosts.a]\nbase_url = \"http://a:1\"\nmodels = { \"m\" = { } }\n[routes.r]\n", "routes.r.hosts"},
+		{"host twice", "listen = \"127.0.0.1:7\"\n[hosts.a]\nbase_url = \"http://a:1\"\nmodels = { \"m\" = { } }\n[routes.r]\nhosts = [\"a\", \"a\"]\n", "routes.r.hosts"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := config.Parse(strings.NewReader(tc.text))
+			e, ok := config.IsError(err)
+			if !ok {
+				t.Fatalf("want *config.Error, got %v", err)
+			}
+			if e.Field != tc.field {
+				t.Errorf("Field = %q, want %q", e.Field, tc.field)
+			}
+		})
+	}
+}
+
+func TestNotTOML(t *testing.T) {
+	_, err := config.Parse(strings.NewReader("listen = [unterminated"))
+	if err == nil {
+		t.Fatal("want error")
+	}
+	if _, ok := config.IsError(err); ok {
+		t.Errorf("a syntax error is not a validation Error")
+	}
+	if !strings.HasPrefix(err.Error(), "config: ") {
+		t.Errorf("Error() = %q", err.Error())
+	}
+}
+
+func TestMissingFile(t *testing.T) {
+	if _, err := config.Load(filepath.Join("testdata", "does-not-exist.toml")); err == nil {
+		t.Fatal("want error")
+	}
+}

docs/plans/v1/_files/internal/config/config_v1_test.go

@@ -0,0 +1,81 @@
+package config_test
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+)
+
+const v1Base = `
+listen = "127.0.0.1:1"
+[hosts.a]
+base_url = "http://a:1"
+models = { "m" = { } }
+[routes.r]
+hosts = ["a"]
+`
+
+func TestV1Defaults(t *testing.T) {
+	c, err := config.Parse(strings.NewReader(v1Base))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.DB != "crossbar.db" {
+		t.Errorf("DB default = %q", c.DB)
+	}
+	if c.LeaseIdle.Duration != 30*time.Minute {
+		t.Errorf("LeaseIdle default = %v", c.LeaseIdle.Duration)
+	}
+	if c.Retention.Duration != 180*24*time.Hour {
+		t.Errorf("Retention default = %v", c.Retention.Duration)
+	}
+}
+
+func TestV1Values(t *testing.T) {
+	c, err := config.Parse(strings.NewReader(`
+db = "/var/lib/crossbar/crossbar.db"
+lease_idle = "45m"
+retention = "30d"
+` + v1Base))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.DB != "/var/lib/crossbar/crossbar.db" || c.LeaseIdle.Duration != 45*time.Minute || c.Retention.Duration != 30*24*time.Hour {
+		t.Errorf("got db %q idle %v retention %v", c.DB, c.LeaseIdle.Duration, c.Retention.Duration)
+	}
+}
+
+func TestDurationAcceptsDays(t *testing.T) {
+	var d config.Duration
+	for _, tc := range []struct {
+		in   string
+		want time.Duration
+	}{
+		{"1d", 24 * time.Hour}, {"7d", 7 * 24 * time.Hour}, {"90m", 90 * time.Minute}, {"2h30m", 150 * time.Minute},
+	} {
+		if err := d.UnmarshalText([]byte(tc.in)); err != nil || d.Duration != tc.want {
+			t.Errorf("UnmarshalText(%q) = %v %v, want %v", tc.in, d.Duration, err, tc.want)
+		}
+	}
+	for _, bad := range []string{"1.5d", "d", "3 days", "1d2h"} {
+		if err := d.UnmarshalText([]byte(bad)); err == nil {
+			t.Errorf("UnmarshalText(%q) must fail", bad)
+		}
+	}
+}
+
+func TestV1Validation(t *testing.T) {
+	for _, tc := range []struct{ name, text, field string }{
+		{"empty db", "db = \"\"\n" + v1Base, "db"},
+		{"lease_idle too short", "lease_idle = \"10s\"\n" + v1Base, "lease_idle"},
+		{"retention too short", "retention = \"12h\"\n" + v1Base, "retention"},
+	} {
+		_, err := config.Parse(strings.NewReader(tc.text))
+		e, ok := config.IsError(err)
+		if !ok || e.Field != tc.field {
+			t.Errorf("%s: %v, want *Error on %s", tc.name, err, tc.field)
+		}
+	}
+}

docs/plans/v1/_files/internal/config/testdata/bad-unknown-key.toml

@@ -0,0 +1,9 @@
+listen = "127.0.0.1:7777"
+bogus_key = 1
+
+[hosts.alpha]
+base_url = "http://alpha.example:11434"
+models   = { "m" = { } }
+
+[routes.r]
+hosts = ["alpha"]

docs/plans/v1/_files/internal/fingerprint/fingerprint_test.go

@@ -0,0 +1,70 @@
+package fingerprint_test
+
+import (
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/fingerprint"
+)
+
+const conv1 = `{"model":"m","messages":[{"role":"system","content":"You are the project A assistant."},{"role":"user","content":"Add a config loader."},{"role":"assistant","content":"Sure."},{"role":"user","content":"Now tests."}]}`
+const conv1later = `{"model":"m","messages":[{"role":"system","content":"You are the project A assistant."},{"role":"user","content":"Add a config loader."},{"role":"assistant","content":"Sure."},{"role":"user","content":"Now tests."},{"role":"assistant","content":"Done."},{"role":"user","content":"And docs."}]}`
+const conv2 = `{"model":"m","messages":[{"role":"system","content":"You are the project A assistant."},{"role":"user","content":"Fix the flaky test."}]}`
+const conv3 = `{"model":"m","messages":[{"role":"system","content":"You are the project B assistant."},{"role":"user","content":"Add a config loader."}]}`
+
+func TestSameConversationSameKey(t *testing.T) {
+	a := fingerprint.Of([]byte(conv1))
+	b := fingerprint.Of([]byte(conv1later))
+	if a == "" || a != b {
+		t.Errorf("later turns of one conversation must keep the key: %q vs %q", a, b)
+	}
+	if len(a) != 64 || strings.Trim(a, "0123456789abcdef") != "" {
+		t.Errorf("key must be lowercase hex sha256 (64 chars), got %q", a)
+	}
+}
+
+func TestDifferentConversationsDifferentKeys(t *testing.T) {
+	a, b, c := fingerprint.Of([]byte(conv1)), fingerprint.Of([]byte(conv2)), fingerprint.Of([]byte(conv3))
+	if a == b {
+		t.Errorf("different first user message must change the key")
+	}
+	if a == c {
+		t.Errorf("different system prompt must change the key")
+	}
+}
+
+func TestNoUserMessageIsEmpty(t *testing.T) {
+	for _, body := range []string{
+		`{"model":"m","messages":[{"role":"system","content":"only a system prompt"}]}`,
+		`{"model":"m","messages":[]}`,
+		`{"model":"m"}`,
+		`{"input":"an embeddings request"}`,
+		`not json at all`,
+		``,
+	} {
+		if got := fingerprint.Of([]byte(body)); got != "" {
+			t.Errorf("Of(%q) = %q, want empty", body, got)
+		}
+	}
+}
+
+func TestOnlyTheFirstFourKiBCount(t *testing.T) {
+	long := strings.Repeat("x", 5000)
+	a := `{"messages":[{"role":"user","content":"` + long + `A"}]}`
+	b := `{"messages":[{"role":"user","content":"` + long + `B"}]}`
+	if fingerprint.Of([]byte(a)) != fingerprint.Of([]byte(b)) {
+		t.Errorf("bytes after the first 4 KiB of a message must not change the key")
+	}
+	c := `{"messages":[{"role":"user","content":"A` + long + `"}]}`
+	if fingerprint.Of([]byte(a)) == fingerprint.Of([]byte(c)) {
+		t.Errorf("bytes inside the first 4 KiB must change the key")
+	}
+}
+
+func TestContentPartsAreFlattened(t *testing.T) {
+	plain := `{"messages":[{"role":"user","content":"hello world"}]}`
+	parts := `{"messages":[{"role":"user","content":[{"type":"text","text":"hello world"}]}]}`
+	if fingerprint.Of([]byte(plain)) != fingerprint.Of([]byte(parts)) {
+		t.Errorf("a content array of text parts must fingerprint like the joined text")
+	}
+}

docs/plans/v1/_files/internal/lease/lease_test.go

@@ -0,0 +1,308 @@
+package lease_test
+
+import (
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/lease"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+// memPersister is an in-memory Persister that also counts writes.
+type memPersister struct {
+	mu     sync.Mutex
+	leases map[[3]string]store.Lease
+	events []store.LeaseEvent
+	saves  int
+}
+
+func newPersister() *memPersister { return &memPersister{leases: map[[3]string]store.Lease{}} }
+
+func (m *memPersister) SaveLease(l store.Lease) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.saves++
+	m.leases[[3]string{l.Route, l.FP, l.Model}] = l
+	return nil
+}
+func (m *memPersister) DeleteLease(route, fp, model string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.leases, [3]string{route, fp, model})
+	return nil
+}
+func (m *memPersister) ListLeases() ([]store.Lease, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	out := []store.Lease{}
+	for _, l := range m.leases {
+		out = append(out, l)
+	}
+	return out, nil
+}
+func (m *memPersister) RecordEvent(e store.LeaseEvent) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.events = append(m.events, e)
+	return nil
+}
+func (m *memPersister) reasons() []string {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	var r []string
+	for _, e := range m.events {
+		r = append(r, e.Reason)
+	}
+	return r
+}
+
+// world is a hand-set view of hosts plus a chooser that returns a fixed answer.
+type world struct {
+	mu       sync.Mutex
+	healthy  map[string]bool
+	draining map[string]bool
+	pick     string
+	picks    []string // candidates seen by Choose, for assertions
+}
+
+func (w *world) Healthy(name string) bool  { w.mu.Lock(); defer w.mu.Unlock(); return w.healthy[name] }
+func (w *world) Draining(name string) bool { w.mu.Lock(); defer w.mu.Unlock(); return w.draining[name] }
+func (w *world) Choose(candidates []string, model string) (string, bool) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	w.picks = append([]string{}, candidates...)
+	for _, c := range candidates {
+		if c == w.pick {
+			return c, true
+		}
+	}
+	if len(candidates) > 0 {
+		return candidates[0], true
+	}
+	return "", false
+}
+
+var t0 = time.Date(2026, 9, 25, 10, 0, 0, 0, time.UTC)
+
+func newTable(t *testing.T, p *memPersister, w *world) *lease.Table {
+	tbl, err := lease.New(p, w, w, 30*time.Minute)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return tbl
+}
+
+func TestNewLeaseThenSticky(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "beta"}
+	tbl := newTable(t, p, w)
+	k := lease.Key{Route: "r", FP: "conv1", Model: "m"}
+	host, reused, err := tbl.Acquire(k, []string{"alpha", "beta"}, t0)
+	if err != nil || host != "beta" || reused {
+		t.Fatalf("first: %q %v %v", host, reused, err)
+	}
+	w.pick = "alpha" // the chooser would now prefer alpha; the lease must hold
+	for i := 1; i <= 5; i++ {
+		host, reused, err = tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(time.Duration(i)*time.Minute))
+		if err != nil || host != "beta" || !reused {
+			t.Fatalf("turn %d: %q reused=%v %v, want beta reused", i, host, reused, err)
+		}
+	}
+	if got := p.reasons(); len(got) != 1 || got[0] != store.ReasonNew {
+		t.Errorf("events = %v, want one 'new'", got)
+	}
+	snap := tbl.Snapshot()
+	if len(snap) != 1 || snap[0].Host != "beta" || !snap[0].LastUsed.Equal(t0.Add(5*time.Minute)) {
+		t.Errorf("snapshot = %+v", snap)
+	}
+	if p.saves < 2 {
+		t.Errorf("LastUsed must be written through (saves=%d)", p.saves)
+	}
+}
+
+func TestUnhealthyHostMovesTheLease(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "alpha"}
+	tbl := newTable(t, p, w)
+	k := lease.Key{Route: "r", FP: "c", Model: "m"}
+	if host, _, _ := tbl.Acquire(k, []string{"alpha", "beta"}, t0); host != "alpha" {
+		t.Fatalf("first: %q", host)
+	}
+	w.mu.Lock()
+	w.healthy["alpha"] = false
+	w.pick = "beta"
+	w.mu.Unlock()
+	host, reused, err := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(time.Minute))
+	if err != nil || host != "beta" || reused {
+		t.Fatalf("after alpha down: %q reused=%v %v", host, reused, err)
+	}
+	if got := p.reasons(); len(got) != 2 || got[1] != store.ReasonUnhealthy {
+		t.Errorf("events = %v, want [new unhealthy]", got)
+	}
+	if len(w.picks) != 1 || w.picks[0] != "beta" {
+		t.Errorf("Choose must not see the unhealthy host: %v", w.picks)
+	}
+}
+
+func TestIdleExpiry(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "alpha"}
+	tbl := newTable(t, p, w)
+	k := lease.Key{Route: "r", FP: "c", Model: "m"}
+	tbl.Acquire(k, []string{"alpha", "beta"}, t0)
+	if n := tbl.ExpireIdle(t0.Add(29 * time.Minute)); n != 0 {
+		t.Errorf("expired %d before lease_idle", n)
+	}
+	if n := tbl.ExpireIdle(t0.Add(31 * time.Minute)); n != 1 {
+		t.Errorf("expired %d after lease_idle, want 1", n)
+	}
+	if got := p.reasons(); got[len(got)-1] != store.ReasonIdle {
+		t.Errorf("events = %v, want idle last", got)
+	}
+	w.pick = "beta"
+	if host, reused, _ := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(32*time.Minute)); host != "beta" || reused {
+		t.Errorf("after expiry a new lease is chosen: %q reused=%v", host, reused)
+	}
+	if l, _ := p.ListLeases(); len(l) != 1 {
+		t.Errorf("persister holds %d leases, want 1", len(l))
+	}
+}
+
+func TestFingerprintInheritsRouteLease(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "beta"}
+	tbl := newTable(t, p, w)
+	// A request without a fingerprint (no user message) leases the route itself…
+	if host, _, _ := tbl.Acquire(lease.Key{Route: "r", FP: "", Model: "m"}, []string{"alpha", "beta"}, t0); host != "beta" {
+		t.Fatalf("route lease: %q", host)
+	}
+	w.pick = "alpha"
+	// …and a new conversation on that route starts where the route already is.
+	host, reused, err := tbl.Acquire(lease.Key{Route: "r", FP: "conv", Model: "m"}, []string{"alpha", "beta"}, t0.Add(time.Second))
+	if err != nil || host != "beta" || !reused {
+		t.Errorf("fingerprint lease must inherit the route's host: %q reused=%v %v", host, reused, err)
+	}
+	if len(tbl.Snapshot()) != 2 {
+		t.Errorf("both the route lease and the conversation lease exist: %+v", tbl.Snapshot())
+	}
+}
+
+func TestPinAndUnpin(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "alpha"}
+	tbl := newTable(t, p, w)
+	k := lease.Key{Route: "r", FP: "c", Model: "m"}
+	tbl.Acquire(k, []string{"alpha", "beta"}, t0)
+	if err := tbl.Pin("r", "beta", t0.Add(time.Minute)); err != nil {
+		t.Fatal(err)
+	}
+	host, _, err := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(2*time.Minute))
+	if err != nil || host != "beta" {
+		t.Fatalf("pinned route must go to beta: %q %v", host, err)
+	}
+	host, _, err = tbl.Acquire(lease.Key{Route: "r", FP: "other", Model: "m"}, []string{"alpha", "beta"}, t0.Add(2*time.Minute))
+	if err != nil || host != "beta" {
+		t.Fatalf("new conversations on a pinned route go to the pin too: %q %v", host, err)
+	}
+	w.mu.Lock()
+	w.healthy["beta"] = false
+	w.mu.Unlock()
+	if _, _, err := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(3*time.Minute)); !errors.Is(err, lease.ErrPinnedDown) {
+		t.Errorf("a pinned host that is down is ErrPinnedDown, never a silent move: %v", err)
+	}
+	if err := tbl.Pin("r", "nobody", t0); !errors.Is(err, lease.ErrUnknownHost) {
+		t.Errorf("pinning to a host not in the candidates of any lease: %v, want ErrUnknownHost", err)
+	}
+	tbl.Unpin("r")
+	w.mu.Lock()
+	w.healthy["beta"] = true
+	w.mu.Unlock()
+	if host, _, _ := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(4*time.Minute)); host != "beta" {
+		t.Errorf("after unpin the existing lease (on beta) simply continues: %q", host)
+	}
+	// Events: a pin event naming beta must exist, and the unpin's release event must come after it.
+	// Acquires under the pin may record their own events in between; their number is not fixed here.
+	got := p.reasons()
+	pinAt, releaseAt := -1, -1
+	for i, r := range got {
+		if r == store.ReasonPin && pinAt < 0 {
+			pinAt = i
+		}
+		if r == store.ReasonRelease {
+			releaseAt = i
+		}
+	}
+	if pinAt < 0 || releaseAt < pinAt {
+		t.Errorf("events = %v, want a pin event followed later by a release event", got)
+	}
+	p.mu.Lock()
+	if pinAt >= 0 && p.events[pinAt].ToHost != "beta" {
+		t.Errorf("pin event = %+v, want ToHost beta", p.events[pinAt])
+	}
+	p.mu.Unlock()
+}
+
+func TestDrainKeepsExistingRefusesNew(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, draining: map[string]bool{}, pick: "alpha"}
+	tbl := newTable(t, p, w)
+	k := lease.Key{Route: "r", FP: "c", Model: "m"}
+	tbl.Acquire(k, []string{"alpha", "beta"}, t0)
+	w.mu.Lock()
+	w.draining["alpha"] = true
+	w.mu.Unlock()
+	if host, reused, _ := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(time.Minute)); host != "alpha" || !reused {
+		t.Errorf("an existing lease on a draining host continues: %q reused=%v", host, reused)
+	}
+	host, _, err := tbl.Acquire(lease.Key{Route: "r2", FP: "x", Model: "m"}, []string{"alpha", "beta"}, t0.Add(time.Minute))
+	if err != nil || host != "beta" {
+		t.Errorf("a new lease avoids the draining host: %q %v", host, err)
+	}
+	if len(w.picks) != 1 || w.picks[0] != "beta" {
+		t.Errorf("Choose must not see the draining host: %v", w.picks)
+	}
+	if _, _, err := tbl.Acquire(lease.Key{Route: "r3", FP: "y", Model: "m"}, []string{"alpha"}, t0); !errors.Is(err, lease.ErrNoHost) {
+		t.Errorf("only draining candidates: %v, want ErrNoHost", err)
+	}
+}
+
+func TestReleaseRoute(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "alpha"}
+	tbl := newTable(t, p, w)
+	tbl.Acquire(lease.Key{Route: "r", FP: "a", Model: "m"}, []string{"alpha", "beta"}, t0)
+	tbl.Acquire(lease.Key{Route: "r", FP: "b", Model: "m"}, []string{"alpha", "beta"}, t0)
+	tbl.Acquire(lease.Key{Route: "other", FP: "c", Model: "m"}, []string{"alpha", "beta"}, t0)
+	if n := tbl.Release("r"); n != 2 {
+		t.Errorf("Release removed %d, want 2", n)
+	}
+	if n := tbl.Release("r"); n != 0 {
+		t.Errorf("second Release removed %d", n)
+	}
+	if l, _ := p.ListLeases(); len(l) != 1 || l[0].Route != "other" {
+		t.Errorf("persister after release: %+v", l)
+	}
+	w.pick = "beta"
+	if host, reused, _ := tbl.Acquire(lease.Key{Route: "r", FP: "a", Model: "m"}, []string{"alpha", "beta"}, t0); host != "beta" || reused {
+		t.Errorf("after release the route is re-chosen: %q reused=%v", host, reused)
+	}
+}
+
+func TestLoadsFromPersister(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "alpha"}
+	_ = p.SaveLease(store.Lease{Route: "r", FP: "c", Model: "m", Host: "beta", State: store.Active, Created: t0, LastUsed: t0})
+	_ = p.SaveLease(store.Lease{Route: "pinned", FP: "", Model: "", Host: "beta", State: store.Pinned, Created: t0, LastUsed: t0})
+	tbl := newTable(t, p, w)
+	if host, reused, _ := tbl.Acquire(lease.Key{Route: "r", FP: "c", Model: "m"}, []string{"alpha", "beta"}, t0.Add(time.Second)); host != "beta" || !reused {
+		t.Errorf("a restart must not reshuffle: %q reused=%v", host, reused)
+	}
+	if host, _, _ := tbl.Acquire(lease.Key{Route: "pinned", FP: "new", Model: "m"}, []string{"alpha", "beta"}, t0.Add(time.Second)); host != "beta" {
+		t.Errorf("a pin survives a restart: %q", host)
+	}
+}
+
+func TestNoCandidates(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{}, pick: ""}
+	tbl := newTable(t, p, w)
+	if _, _, err := tbl.Acquire(lease.Key{Route: "r", FP: "c", Model: "m"}, []string{"alpha"}, t0); !errors.Is(err, lease.ErrNoHost) {
+		t.Errorf("no healthy host: %v, want ErrNoHost", err)
+	}
+	if len(tbl.Snapshot()) != 0 {
+		t.Errorf("a failed acquire must not create a lease")
+	}
+}

docs/plans/v1/_files/internal/limiter/limiter_test.go

@@ -0,0 +1,178 @@
+package limiter_test
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/limiter"
+)
+
+func TestParallelAndQueue(t *testing.T) {
+	l := limiter.New()
+	l.Configure("alpha", "m", 2, 1) // two slots, one waiting place
+	ctx := context.Background()
+
+	rel1, w1, err := l.Acquire(ctx, "alpha", "m")
+	if err != nil || w1 > 50*time.Millisecond {
+		t.Fatalf("first acquire: err %v waited %v", err, w1)
+	}
+	rel2, _, err := l.Acquire(ctx, "alpha", "m")
+	if err != nil {
+		t.Fatalf("second acquire: %v", err)
+	}
+	if l.InFlight("alpha", "m") != 2 || l.FreeSlots("alpha") != 0 {
+		t.Errorf("in flight %d free %d, want 2 and 0", l.InFlight("alpha", "m"), l.FreeSlots("alpha"))
+	}
+
+	// Third waits in the queue.
+	got3 := make(chan error, 1)
+	go func() {
+		rel, waited, err := l.Acquire(ctx, "alpha", "m")
+		if err == nil {
+			defer rel()
+			if waited < 40*time.Millisecond {
+				err = errors.New("third acquire did not wait")
+			}
+		}
+		got3 <- err
+	}()
+	time.Sleep(20 * time.Millisecond)
+	if l.Queued("alpha", "m") != 1 {
+		t.Errorf("queued = %d, want 1", l.Queued("alpha", "m"))
+	}
+	// Fourth finds the queue full and is refused at once.
+	start := time.Now()
+	_, _, err = l.Acquire(ctx, "alpha", "m")
+	if !errors.Is(err, limiter.ErrQueueFull) {
+		t.Fatalf("fourth acquire: %v, want ErrQueueFull", err)
+	}
+	if time.Since(start) > 50*time.Millisecond {
+		t.Errorf("a full queue must refuse immediately, took %v", time.Since(start))
+	}
+	time.Sleep(30 * time.Millisecond)
+	rel1() // frees a slot: the queued third proceeds
+	select {
+	case err := <-got3:
+		if err != nil {
+			t.Fatalf("third: %v", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("queued acquire did not proceed after a release")
+	}
+	rel2()
+	if l.InFlight("alpha", "m") != 0 || l.Queued("alpha", "m") != 0 {
+		t.Errorf("after releases: inflight %d queued %d", l.InFlight("alpha", "m"), l.Queued("alpha", "m"))
+	}
+}
+
+func TestReleaseIsIdempotent(t *testing.T) {
+	l := limiter.New()
+	l.Configure("h", "m", 1, 0)
+	rel, _, err := l.Acquire(context.Background(), "h", "m")
+	if err != nil {
+		t.Fatal(err)
+	}
+	rel()
+	rel() // a second call must not free a slot that was never taken
+	if l.InFlight("h", "m") != 0 {
+		t.Errorf("in flight %d after double release", l.InFlight("h", "m"))
+	}
+	if _, _, err := l.Acquire(context.Background(), "h", "m"); err != nil {
+		t.Errorf("slot must be free again: %v", err)
+	}
+}
+
+func TestCancelWhileQueuedLeaksNothing(t *testing.T) {
+	l := limiter.New()
+	l.Configure("h", "m", 1, 2)
+	rel, _, err := l.Acquire(context.Background(), "h", "m")
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { _, _, err := l.Acquire(ctx, "h", "m"); done <- err }()
+	time.Sleep(20 * time.Millisecond)
+	cancel()
+	select {
+	case err := <-done:
+		if !errors.Is(err, context.Canceled) {
+			t.Fatalf("cancelled acquire returned %v", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("cancelled acquire did not return")
+	}
+	if l.Queued("h", "m") != 0 {
+		t.Errorf("queued = %d after cancel", l.Queued("h", "m"))
+	}
+	rel()
+	if l.InFlight("h", "m") != 0 {
+		t.Errorf("in flight %d, the cancelled waiter must not have taken the slot", l.InFlight("h", "m"))
+	}
+}
+
+func TestQueueIsFIFO(t *testing.T) {
+	l := limiter.New()
+	l.Configure("h", "m", 1, 8)
+	rel, _, err := l.Acquire(context.Background(), "h", "m")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var mu sync.Mutex
+	var order []int
+	var wg sync.WaitGroup
+	for i := 1; i <= 4; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			r, _, err := l.Acquire(context.Background(), "h", "m")
+			if err != nil {
+				t.Errorf("waiter %d: %v", i, err)
+				return
+			}
+			mu.Lock()
+			order = append(order, i)
+			mu.Unlock()
+			time.Sleep(5 * time.Millisecond)
+			r()
+		}(i)
+		time.Sleep(15 * time.Millisecond) // stagger arrivals so the order is defined
+	}
+	rel()
+	wg.Wait()
+	if len(order) != 4 || order[0] != 1 || order[1] != 2 || order[2] != 3 || order[3] != 4 {
+		t.Errorf("waiters proceeded in order %v, want [1 2 3 4]", order)
+	}
+}
+
+func TestUnconfiguredPairIsOneSlotNoQueue(t *testing.T) {
+	l := limiter.New()
+	rel, _, err := l.Acquire(context.Background(), "x", "y")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer rel()
+	if _, _, err := l.Acquire(context.Background(), "x", "y"); !errors.Is(err, limiter.ErrQueueFull) {
+		t.Errorf("second acquire on an unconfigured pair: %v, want ErrQueueFull", err)
+	}
+}
+
+func TestFreeSlotsSumsModels(t *testing.T) {
+	l := limiter.New()
+	l.Configure("h", "a", 4, 0)
+	l.Configure("h", "b", 2, 0)
+	if got := l.FreeSlots("h"); got != 6 {
+		t.Fatalf("free = %d, want 6", got)
+	}
+	rel, _, _ := l.Acquire(context.Background(), "h", "a")
+	defer rel()
+	if got := l.FreeSlots("h"); got != 5 {
+		t.Errorf("free = %d, want 5", got)
+	}
+	if l.FreeSlots("nobody") != 0 {
+		t.Errorf("unknown host has no slots")
+	}
+}

docs/plans/v1/_files/internal/proxy/helpers_test.go

@@ -0,0 +1,211 @@
+package proxy_test
+
+// Test scaffolding shared by proxy_test.go and recorder_test.go: the fake health table, the fake
+// llama-server upstream, and the rig that builds a whole crossbar over real HTTP.
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+	"git.wntrmute.dev/kyle/crossbar/internal/health"
+	"git.wntrmute.dev/kyle/crossbar/internal/lease"
+	"git.wntrmute.dev/kyle/crossbar/internal/limiter"
+	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+// fakeHealth is a hand-set health table that also records MarkDown calls. It lived in the v0
+// proxy_test.go; the v1 given test replaces that file, so recorder_test.go (which still exercises
+// the nil-lease path through proxy.New) needs it here.
+type fakeHealth struct {
+	mu     sync.Mutex
+	st     map[string]health.Status
+	marked []string
+}
+
+func (f *fakeHealth) Get(name string) (health.Status, bool) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	s, ok := f.st[name]
+	return s, ok
+}
+
+func (f *fakeHealth) MarkDown(name, reason string) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.marked = append(f.marked, name)
+	s := f.st[name]
+	s.Healthy = false
+	s.LastErr = reason
+	f.st[name] = s
+}
+
+func (f *fakeHealth) markedHosts() []string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return append([]string{}, f.marked...)
+}
+
+// upstream is a llama-server stand-in: streams N chunks with a delay, reports usage/timings in
+// the final chunk, counts requests, and can be slowed down or killed.
+type upstream struct {
+	name  string
+	srv   *httptest.Server
+	hits  atomic.Int32
+	delay time.Duration
+	mu    sync.Mutex
+	last  recorded
+}
+
+type recorded struct{ method, path, host, xff, body string }
+
+func newUpstream(t *testing.T, name string) *upstream {
+	u := &upstream{name: name}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, `{"status":"ok"}`) })
+	mux.HandleFunc("/v1/models", func(w http.ResponseWriter, r *http.Request) {
+		u.mu.Lock()
+		u.last = recorded{r.Method, r.URL.RequestURI(), r.Host, r.Header.Get("X-Forwarded-For"), ""}
+		u.mu.Unlock()
+		fmt.Fprint(w, `{"object":"list","data":[{"id":"shared"},{"id":"`+name+`-only"}]}`)
+	})
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		u.hits.Add(1)
+		b, _ := io.ReadAll(r.Body)
+		u.mu.Lock()
+		u.last = recorded{r.Method, r.URL.RequestURI(), r.Host, r.Header.Get("X-Forwarded-For"), string(b)}
+		u.mu.Unlock()
+		var req struct {
+			Stream bool `json:"stream"`
+		}
+		_ = json.Unmarshal(b, &req)
+		w.Header().Set("X-Upstream", name)
+		time.Sleep(u.delay)
+		if !req.Stream {
+			w.Header().Set("Content-Type", "application/json")
+			fmt.Fprintf(w, `{"choices":[{"message":{"role":"assistant","content":"hi from %s"}}],"usage":{"prompt_tokens":100,"completion_tokens":10,"total_tokens":110},"timings":{"prompt_n":100,"cache_n":90,"predicted_n":10,"predicted_ms":50.0}}`, name)
+			return
+		}
+		w.Header().Set("Content-Type", "text/event-stream")
+		w.WriteHeader(200)
+		fl := w.(http.Flusher)
+		for i := 0; i < 3; i++ {
+			fmt.Fprintf(w, "data: {\"choices\":[{\"delta\":{\"content\":\"%s %d \"}}]}\n\n", name, i)
+			fl.Flush()
+			time.Sleep(10 * time.Millisecond)
+		}
+		fmt.Fprint(w, `data: {"choices":[],"usage":{"prompt_tokens":200,"completion_tokens":20,"total_tokens":220},"timings":{"prompt_n":200,"cache_n":150,"predicted_n":20,"predicted_ms":80.0}}`+"\n\n")
+		fl.Flush()
+		fmt.Fprint(w, "data: [DONE]\n\n")
+	})
+	u.srv = httptest.NewServer(mux)
+	t.Cleanup(u.srv.Close)
+	return u
+}
+
+func (u *upstream) lastReq() recorded { u.mu.Lock(); defer u.mu.Unlock(); return u.last }
+
+// rig is one crossbar: config, real health table (polled once), real lease table over a real
+// SQLite store, real limiter, the proxy handler served by httptest.
+type rig struct {
+	t      *testing.T
+	cfg    *config.Config
+	health *health.Table
+	store  *store.Store
+	leases *lease.Table
+	lim    *limiter.Limiter
+	front  *httptest.Server
+}
+
+// newRig builds crossbar from a config text where %s placeholders are the upstream base URLs.
+func newRig(t *testing.T, cfgText string, ups ...*upstream) *rig {
+	urls := make([]any, len(ups))
+	for i, u := range ups {
+		urls[i] = u.srv.URL
+	}
+	cfg, err := config.Parse(strings.NewReader(fmt.Sprintf(cfgText, urls...)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	bases := map[string]string{}
+	for name, h := range cfg.Hosts {
+		bases[name] = h.BaseURL
+	}
+	ht := health.New(bases, time.Hour, nil)
+	ht.PollOnce(t.Context())
+	st, err := store.Open(filepath.Join(t.TempDir(), "crossbar.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	lim := limiter.New()
+	for name, h := range cfg.Hosts {
+		for model, m := range h.Models {
+			lim.Configure(name, model, m.Parallel, cfg.QueueMax)
+		}
+	}
+	lt, err := lease.New(st, proxy.HostView(ht, cfg), proxy.Chooser(cfg, ht, lim), cfg.LeaseIdle.Duration)
+	if err != nil {
+		t.Fatal(err)
+	}
+	p := proxy.New(cfg, ht, lt, lim, st, nil)
+	front := httptest.NewServer(p)
+	t.Cleanup(front.Close)
+	return &rig{t: t, cfg: cfg, health: ht, store: st, leases: lt, lim: lim, front: front}
+}
+
+const twoHosts = `
+listen = "127.0.0.1:1"
+queue_max = 1
+lease_idle = "30m"
+[hosts.alpha]
+base_url = %q
+weight = 1.0
+models = { "shared" = { parallel = 2 }, "alpha-only" = { } }
+[hosts.beta]
+base_url = %q
+weight = 2.0
+models = { "shared" = { parallel = 2 }, "beta-only" = { } }
+[routes.r]
+hosts = ["alpha", "beta"]
+default_model = "shared"
+[routes.other]
+hosts = ["alpha"]
+`
+
+func conversation(id, turn int) string {
+	msgs := fmt.Sprintf(`{"role":"system","content":"project"},{"role":"user","content":"conversation %d opening"}`, id)
+	for i := 1; i < turn; i++ {
+		msgs += fmt.Sprintf(`,{"role":"assistant","content":"ok"},{"role":"user","content":"turn %d"}`, i)
+	}
+	return `{"model":"shared","stream":false,"messages":[` + msgs + `]}`
+}
+
+func (r *rig) post(path, body string, hdr ...string) *http.Response {
+	req, _ := http.NewRequest(http.MethodPost, r.front.URL+path, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	for i := 0; i+1 < len(hdr); i += 2 {
+		req.Header.Set(hdr[i], hdr[i+1])
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		r.t.Fatal(err)
+	}
+	return resp
+}
+
+func drain(resp *http.Response) string {
+	b, _ := io.ReadAll(resp.Body)
+	resp.Body.Close()
+	return string(b)
+}

docs/plans/v1/_files/internal/proxy/proxy_test.go

@@ -0,0 +1,271 @@
+package proxy_test
+
+// v1 acceptance tests for the proxy: leases, queueing, accounting, header route override.
+// They drive the whole handler over real HTTP against fake upstreams; only what a client or an
+// operator can observe is asserted (status codes, headers, the accounting rows, the health table).
+// The rig, the fake upstream and the request helpers live in helpers_test.go.
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+func TestConversationIsStickyAndLeaseHeaderTellsWhy(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	first := r.post("/r/v1/chat/completions", conversation(1, 1))
+	drain(first)
+	host := first.Header.Get(proxy.HostHeader)
+	if first.StatusCode != 200 || host != "beta" { // beta: same free slots, double weight
+		t.Fatalf("first turn: %d from %q, want 200 from beta", first.StatusCode, host)
+	}
+	if got := first.Header.Get(proxy.LeaseHeader); got != "new" {
+		t.Errorf("%s = %q on the first turn, want new", proxy.LeaseHeader, got)
+	}
+	// Take alpha's slots away as a "better host" signal: it must not matter, the lease holds.
+	for turn := 2; turn <= 6; turn++ {
+		resp := r.post("/r/v1/chat/completions", conversation(1, turn))
+		drain(resp)
+		if resp.Header.Get(proxy.HostHeader) != host || resp.Header.Get(proxy.LeaseHeader) != "reused" {
+			t.Fatalf("turn %d: host %q lease %q, want %q reused", turn, resp.Header.Get(proxy.HostHeader), resp.Header.Get(proxy.LeaseHeader), host)
+		}
+	}
+	if alpha.hits.Load() != 0 || beta.hits.Load() != 6 {
+		t.Errorf("hits alpha=%d beta=%d, want 0 and 6", alpha.hits.Load(), beta.hits.Load())
+	}
+}
+
+// spreadHosts: beta is preferred (weight 10) until both of its "shared" slots are busy; then
+// alpha (2 free × 1) beats beta (0 free × 10), and a new conversation must start on alpha.
+const spreadHosts = `
+listen = "127.0.0.1:1"
+queue_max = 4
+lease_idle = "30m"
+[hosts.alpha]
+base_url = %q
+weight = 1.0
+models = { "shared" = { parallel = 2 } }
+[hosts.beta]
+base_url = %q
+weight = 10.0
+models = { "shared" = { parallel = 2 } }
+[routes.r]
+hosts = ["alpha", "beta"]
+default_model = "shared"
+`
+
+func TestDifferentConversationsSpreadByFreeSlots(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	beta.delay = 400 * time.Millisecond
+	r := newRig(t, spreadHosts, alpha, beta)
+	// Two slow conversations occupy beta's two "shared" slots…
+	var wg sync.WaitGroup
+	for i := 1; i <= 2; i++ {
+		wg.Add(1)
+		go func(i int) { defer wg.Done(); drain(r.post("/r/v1/chat/completions", conversation(i, 1))) }(i)
+		time.Sleep(50 * time.Millisecond) // arrive one after the other so both pick beta (10 > 2)
+	}
+	time.Sleep(50 * time.Millisecond)
+	// …so a third conversation starting now is sent to alpha (beta has 0 free slots, alpha 2).
+	resp := r.post("/r/v1/chat/completions", conversation(3, 1))
+	drain(resp)
+	if resp.Header.Get(proxy.HostHeader) != "alpha" {
+		t.Errorf("third conversation went to %q, want alpha (free slots beat weight)", resp.Header.Get(proxy.HostHeader))
+	}
+	wg.Wait()
+	if beta.hits.Load() != 2 || alpha.hits.Load() != 1 {
+		t.Errorf("hits beta=%d alpha=%d, want 2 and 1", beta.hits.Load(), alpha.hits.Load())
+	}
+}
+
+func TestQueueFullIs503(t *testing.T) {
+	alpha := newUpstream(t, "alpha")
+	alpha.delay = 400 * time.Millisecond
+	r := newRig(t, `
+listen = "127.0.0.1:1"
+queue_max = 1
+[hosts.alpha]
+base_url = %q
+models = { "shared" = { parallel = 1 } }
+[routes.r]
+hosts = ["alpha"]
+default_model = "shared"
+`, alpha)
+	codes := make(chan int, 3)
+	for i := 1; i <= 3; i++ {
+		go func(i int) {
+			resp := r.post("/r/v1/chat/completions", conversation(i, 1))
+			drain(resp)
+			codes <- resp.StatusCode
+		}(i)
+		time.Sleep(30 * time.Millisecond) // arrival order: 1 runs, 2 queues, 3 finds the queue full
+	}
+	got := map[int]int{}
+	for i := 0; i < 3; i++ {
+		got[<-codes]++
+	}
+	if got[200] != 2 || got[503] != 1 {
+		t.Fatalf("status counts = %v, want two 200 and one 503", got)
+	}
+	// Rows are written after each response completes; allow the store a moment to catch up.
+	var rows []store.UsageRow
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		rows, _ = r.store.Usage(time.Time{}, store.ByRoute)
+		if len(rows) == 1 && rows[0].Requests == 3 {
+			break
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	if len(rows) != 1 || rows[0].Requests != 3 || rows[0].Errors != 1 {
+		t.Fatalf("usage = %+v, want 3 requests, 1 error (the 503 is recorded too)", rows)
+	}
+	if rows[0].QueuedMs <= 0 {
+		t.Errorf("the queued request must record its wait: %+v", rows[0])
+	}
+}
+
+func TestUnhealthyHostReleasesAndMoves(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	drain(r.post("/r/v1/chat/completions", conversation(1, 1))) // lands on beta
+	beta.srv.Close()
+	resp := r.post("/r/v1/chat/completions", conversation(1, 2))
+	drain(resp)
+	if resp.StatusCode != http.StatusBadGateway {
+		t.Fatalf("first request after beta died: %d, want 502", resp.StatusCode)
+	}
+	if s, _ := r.health.Get("beta"); s.Healthy {
+		t.Fatalf("beta must be marked down after the 502")
+	}
+	resp = r.post("/r/v1/chat/completions", conversation(1, 3))
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.HostHeader) != "alpha" || resp.Header.Get(proxy.LeaseHeader) != "new" {
+		t.Errorf("after the move: %d from %q lease %q, want 200 alpha new", resp.StatusCode, resp.Header.Get(proxy.HostHeader), resp.Header.Get(proxy.LeaseHeader))
+	}
+	ev, _ := r.store.Events(time.Time{}, 10)
+	var reasons []string
+	for _, e := range ev {
+		reasons = append(reasons, e.Reason)
+	}
+	if len(reasons) != 2 || reasons[0] != store.ReasonNew || reasons[1] != store.ReasonUnhealthy {
+		t.Errorf("lease events = %v, want [new unhealthy]", reasons)
+	}
+}
+
+func TestAccountingRowsFromUsageAndTimings(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	drain(r.post("/r/v1/chat/completions", conversation(1, 1)))                                                        // non-streamed
+	drain(r.post("/r/v1/chat/completions", strings.Replace(conversation(1, 2), `"stream":false`, `"stream":true`, 1))) // streamed
+	deadline := time.Now().Add(2 * time.Second)
+	var rows []store.UsageRow
+	for time.Now().Before(deadline) {
+		rows, _ = r.store.Usage(time.Time{}, store.ByHost)
+		if len(rows) == 1 && rows[0].Requests == 2 {
+			break
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	if len(rows) != 1 || rows[0].Requests != 2 {
+		t.Fatalf("usage by host = %+v, want one host with 2 requests (rows may be written after the response completes, within 2 s)", rows)
+	}
+	u := rows[0]
+	if u.PromptTokens != 300 || u.CachedTokens != 240 || u.CompletionTokens != 30 {
+		t.Errorf("tokens = prompt %d cached %d completion %d, want 300/240/30 (100+200, 90+150, 10+20)", u.PromptTokens, u.CachedTokens, u.CompletionTokens)
+	}
+	if u.BusyMs <= 0 || u.Errors != 0 {
+		t.Errorf("busy %d errors %d", u.BusyMs, u.Errors)
+	}
+	if got := u.CacheHitRatio(); got < 0.79 || got > 0.81 {
+		t.Errorf("cache hit ratio = %v, want 0.8", got)
+	}
+}
+
+func TestStreamIsUnalteredWhileTeed(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	resp := r.post("/r/v1/chat/completions", strings.Replace(conversation(9, 1), `"stream":false`, `"stream":true`, 1))
+	body := drain(resp)
+	want := 0
+	for _, line := range strings.Split(body, "\n") {
+		if strings.HasPrefix(line, "data: ") {
+			want++
+		}
+	}
+	if want != 5 || !strings.HasSuffix(strings.TrimSpace(body), "data: [DONE]") {
+		t.Errorf("client must receive every SSE line untouched (3 deltas, usage, DONE); got %d data lines:\n%s", want, body)
+	}
+}
+
+func TestHeaderRouteOverride(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	// The header names the route; the path has none.
+	resp := r.post("/v1/chat/completions", conversation(1, 1), proxy.RouteHeader, "other")
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.HostHeader) != "alpha" {
+		t.Errorf("header route 'other' (alpha only): %d from %q", resp.StatusCode, resp.Header.Get(proxy.HostHeader))
+	}
+	if alpha.lastReq().path != "/v1/chat/completions" {
+		t.Errorf("upstream path = %q", alpha.lastReq().path)
+	}
+	// A path route and a header route that disagree: the header is the operator's intent → 400.
+	resp = r.post("/r/v1/chat/completions", conversation(1, 1), proxy.RouteHeader, "other")
+	if drain(resp); resp.StatusCode != 400 {
+		t.Errorf("conflicting route in path and header: %d, want 400", resp.StatusCode)
+	}
+	resp = r.post("/v1/chat/completions", conversation(1, 1), proxy.RouteHeader, "nope")
+	if drain(resp); resp.StatusCode != 404 {
+		t.Errorf("unknown header route: %d, want 404", resp.StatusCode)
+	}
+}
+
+func TestV0BehaviourStillHolds(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	for _, tc := range []struct {
+		method, path string
+		want         int
+		msg          string
+	}{
+		{http.MethodGet, "/", 400, "missing route"},
+		{http.MethodGet, "/nope/v1/models", 404, "unknown route"},
+		{http.MethodGet, "/r/slots", 404, "not found"},
+		{http.MethodGet, "/r/_crossbar/hosts", 404, "not found"},
+	} {
+		req, _ := http.NewRequest(tc.method, r.front.URL+tc.path, nil)
+		resp, err := http.DefaultClient.Do(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		body := drain(resp)
+		var e map[string]string
+		if resp.StatusCode != tc.want || json.Unmarshal([]byte(body), &e) != nil || e["error"] != tc.msg {
+			t.Errorf("%s: %d %s, want %d %q", tc.path, resp.StatusCode, body, tc.want, tc.msg)
+		}
+	}
+	big := strings.Repeat("x", proxy.MaxBody+1)
+	resp := r.post("/r/v1/chat/completions", big)
+	if drain(resp); resp.StatusCode != 413 {
+		t.Errorf("oversize body: %d, want 413", resp.StatusCode)
+	}
+	// GET pass-through with query string, Host and X-Forwarded-For as in v0.
+	resp, err := http.Get(r.front.URL + "/r/v1/models?x=1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	drain(resp)
+	host := resp.Header.Get(proxy.HostHeader)
+	u := map[string]*upstream{"alpha": alpha, "beta": beta}[host]
+	if u == nil || u.lastReq().path != "/v1/models?x=1" || u.lastReq().host != strings.TrimPrefix(u.srv.URL, "http://") || u.lastReq().xff == "" {
+		t.Errorf("GET pass-through: host %q last %+v", host, u.lastReq())
+	}
+}

docs/plans/v1/_files/internal/proxy/recorder_test.go

@@ -0,0 +1,66 @@
+package proxy_test
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+	"git.wntrmute.dev/kyle/crossbar/internal/health"
+	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+)
+
+// noFlush is a ResponseWriter that does not implement http.Flusher. Middleware and test
+// recorders like this exist in the wild; the proxy must degrade to buffering, never panic.
+type noFlush struct{ w http.ResponseWriter }
+
+func (n noFlush) Header() http.Header         { return n.w.Header() }
+func (n noFlush) Write(b []byte) (int, error) { return n.w.Write(b) }
+func (n noFlush) WriteHeader(code int)        { n.w.WriteHeader(code) }
+
+func TestStreamingWriterWithoutFlusherDoesNotPanic(t *testing.T) {
+	up := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/event-stream")
+		w.WriteHeader(200)
+		for i := 0; i < 3; i++ {
+			fmt.Fprintf(w, "data: chunk %d\n\n", i)
+			w.(http.Flusher).Flush()
+		}
+	}))
+	t.Cleanup(up.Close)
+	cfg, err := config.Parse(strings.NewReader(fmt.Sprintf(`
+listen = "127.0.0.1:1"
+[hosts.alpha]
+base_url = %q
+models = { "m" = { } }
+[routes.r]
+hosts = ["alpha"]
+`, up.URL)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	h := &fakeHealth{st: map[string]health.Status{"alpha": {Healthy: true, Loaded: []string{"m"}}}}
+	p := proxy.New(cfg, h, nil, nil, nil, nil)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/r/v1/chat/completions", strings.NewReader(`{"model":"m","stream":true}`))
+	func() {
+		defer func() {
+			if r := recover(); r != nil {
+				t.Fatalf("ServeHTTP panicked on a writer without Flush: %v", r)
+			}
+		}()
+		p.ServeHTTP(noFlush{rec}, req)
+	}()
+	if rec.Code != 200 {
+		t.Fatalf("status %d", rec.Code)
+	}
+	if got := rec.Body.String(); !strings.Contains(got, "chunk 0") || !strings.Contains(got, "chunk 2") {
+		t.Errorf("body = %q, want all three chunks", got)
+	}
+	if rec.Header().Get(proxy.HostHeader) != "alpha" {
+		t.Errorf("host header %q", rec.Header().Get(proxy.HostHeader))
+	}
+}

docs/plans/v1/_files/internal/store/store_test.go

@@ -0,0 +1,185 @@
+package store_test
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+func open(t *testing.T, dir string) *store.Store {
+	s, err := store.Open(filepath.Join(dir, "crossbar.db"))
+	if err != nil {
+		t.Fatalf("Open: %v", err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+	return s
+}
+
+func TestOpenIsIdempotentAndWAL(t *testing.T) {
+	dir := t.TempDir()
+	s := open(t, dir)
+	if got := s.JournalMode(); got != "wal" {
+		t.Errorf("journal_mode = %q, want wal", got)
+	}
+	if err := s.Close(); err != nil {
+		t.Fatal(err)
+	}
+	open(t, dir) // second open on the same file must not fail on existing tables
+}
+
+func TestLeasesSurviveReopen(t *testing.T) {
+	dir := t.TempDir()
+	s := open(t, dir)
+	now := time.Date(2026, 9, 25, 10, 0, 0, 0, time.UTC)
+	l := store.Lease{Route: "opencode-a", FP: "abc", Model: "m", Host: "alpha", State: store.Active, Created: now, LastUsed: now}
+	if err := s.SaveLease(l); err != nil {
+		t.Fatal(err)
+	}
+	l2 := l
+	l2.FP = "def"
+	l2.Host = "beta"
+	l2.State = store.Pinned
+	if err := s.SaveLease(l2); err != nil {
+		t.Fatal(err)
+	}
+	// Saving the same key again replaces, not duplicates.
+	l.Host = "beta"
+	l.LastUsed = now.Add(time.Minute)
+	if err := s.SaveLease(l); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.Close(); err != nil {
+		t.Fatal(err)
+	}
+	s = open(t, dir)
+	got, err := s.ListLeases()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 2 {
+		t.Fatalf("ListLeases = %d rows, want 2: %+v", len(got), got)
+	}
+	byFP := map[string]store.Lease{}
+	for _, x := range got {
+		byFP[x.FP] = x
+	}
+	if a := byFP["abc"]; a.Host != "beta" || !a.LastUsed.Equal(now.Add(time.Minute)) || a.State != store.Active {
+		t.Errorf("abc = %+v", a)
+	}
+	if d := byFP["def"]; d.State != store.Pinned || d.Host != "beta" {
+		t.Errorf("def = %+v", d)
+	}
+	if err := s.DeleteLease("opencode-a", "abc", "m"); err != nil {
+		t.Fatal(err)
+	}
+	got, _ = s.ListLeases()
+	if len(got) != 1 || got[0].FP != "def" {
+		t.Errorf("after delete: %+v", got)
+	}
+}
+
+func TestEventsAndRequestsAndUsage(t *testing.T) {
+	s := open(t, t.TempDir())
+	t0 := time.Date(2026, 9, 25, 10, 0, 0, 0, time.UTC)
+	must := func(err error) {
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	must(s.RecordEvent(store.LeaseEvent{TS: t0, Route: "r1", Model: "m", FromHost: "", ToHost: "alpha", Reason: store.ReasonNew}))
+	must(s.RecordEvent(store.LeaseEvent{TS: t0.Add(time.Hour), Route: "r1", Model: "m", FromHost: "alpha", ToHost: "beta", Reason: store.ReasonUnhealthy}))
+	reqs := []store.Request{
+		{Route: "r1", FP: "a", Model: "m", Host: "alpha", Started: t0, QueuedMs: 0, TTFBMs: 100, TotalMs: 1000, Status: 200, Streamed: true, PromptTokens: 1000, CachedTokens: 900, CompletionTokens: 50},
+		{Route: "r1", FP: "a", Model: "m", Host: "alpha", Started: t0.Add(time.Minute), QueuedMs: 40, TTFBMs: 120, TotalMs: 2000, Status: 200, Streamed: true, PromptTokens: 1100, CachedTokens: 1000, CompletionTokens: 60},
+		{Route: "r2", FP: "b", Model: "m", Host: "beta", Started: t0.Add(2 * time.Minute), TotalMs: 500, Status: 502, Err: "upstream failed"},
+		{Route: "r2", FP: "b", Model: "m", Host: "beta", Started: t0.Add(-48 * time.Hour), TotalMs: 300, Status: 200, PromptTokens: 10, CompletionTokens: 5},
+	}
+	for _, r := range reqs {
+		must(s.RecordRequest(r))
+	}
+	must(s.RecordHostHealth(store.HostHealth{TS: t0, Host: "alpha", Healthy: true, Loaded: []string{"m"}}))
+
+	rows, err := s.Usage(t0.Add(-time.Hour), store.ByRoute)
+	must(err)
+	if len(rows) != 2 {
+		t.Fatalf("Usage by route since t0-1h: %d rows, want 2 (r1, r2): %+v", len(rows), rows)
+	}
+	byKey := map[string]store.UsageRow{}
+	for _, r := range rows {
+		byKey[r.Key] = r
+	}
+	r1 := byKey["r1"]
+	if r1.Requests != 2 || r1.Errors != 0 || r1.BusyMs != 3000 || r1.QueuedMs != 40 {
+		t.Errorf("r1 = %+v", r1)
+	}
+	if r1.PromptTokens != 2100 || r1.CachedTokens != 1900 || r1.CompletionTokens != 110 {
+		t.Errorf("r1 tokens = %+v", r1)
+	}
+	if got := r1.CacheHitRatio(); got < 0.904 || got > 0.905 {
+		t.Errorf("r1 cache hit ratio = %v, want 1900/2100", got)
+	}
+	r2 := byKey["r2"]
+	if r2.Requests != 1 || r2.Errors != 1 || r2.BusyMs != 500 {
+		t.Errorf("r2 = %+v (the 48h-old request is outside since)", r2)
+	}
+	if r2.CacheHitRatio() != 0 {
+		t.Errorf("no prompt tokens: ratio must be 0, got %v", r2.CacheHitRatio())
+	}
+	byHost, err := s.Usage(time.Time{}, store.ByHost)
+	must(err)
+	if len(byHost) != 2 {
+		t.Errorf("by host, all time: %+v", byHost)
+	}
+	for _, r := range byHost {
+		if r.Key == "beta" && r.Requests != 2 {
+			t.Errorf("beta all-time requests = %d, want 2", r.Requests)
+		}
+	}
+	byModel, err := s.Usage(time.Time{}, store.ByModel)
+	must(err)
+	if len(byModel) != 1 || byModel[0].Key != "m" || byModel[0].Requests != 4 {
+		t.Errorf("by model: %+v", byModel)
+	}
+	ev, err := s.Events(t0.Add(-time.Minute), 10)
+	must(err)
+	if len(ev) != 2 || ev[0].Reason != store.ReasonNew || ev[1].ToHost != "beta" {
+		t.Errorf("events = %+v", ev)
+	}
+}
+
+func TestPruneRollsUpOldRequests(t *testing.T) {
+	s := open(t, t.TempDir())
+	t0 := time.Date(2026, 9, 25, 10, 0, 0, 0, time.UTC)
+	old := t0.Add(-200 * 24 * time.Hour)
+	for i := 0; i < 3; i++ {
+		if err := s.RecordRequest(store.Request{Route: "r", Model: "m", Host: "h", Started: old.Add(time.Duration(i) * time.Minute), TotalMs: 100, Status: 200, PromptTokens: 10, CachedTokens: 5, CompletionTokens: 1}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := s.RecordRequest(store.Request{Route: "r", Model: "m", Host: "h", Started: t0, TotalMs: 100, Status: 200}); err != nil {
+		t.Fatal(err)
+	}
+	n, err := s.Prune(t0, 180*24*time.Hour)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n != 3 {
+		t.Errorf("Prune removed %d rows, want 3", n)
+	}
+	rows, _ := s.Usage(time.Time{}, store.ByRoute)
+	if len(rows) != 1 || rows[0].Requests != 4 || rows[0].PromptTokens != 30 {
+		t.Errorf("usage must still include pruned traffic through the daily rollup: %+v", rows)
+	}
+	live, _ := s.Usage(old.Add(24*time.Hour), store.ByRoute)
+	if len(live) != 1 || live[0].Requests != 1 {
+		t.Errorf("recent-only usage = %+v", live)
+	}
+}
+
+func TestBadPath(t *testing.T) {
+	if _, err := store.Open(filepath.Join(t.TempDir(), "no", "such", "dir", "x.db")); err == nil {
+		t.Fatal("Open must fail when the directory does not exist")
+	}
+}

docs/plans/v1/_files/tools/smoke.sh

@@ -0,0 +1,80 @@
+#!/bin/sh
+# Smoke run (v1): two fake upstreams, one crossbar with a fresh SQLite file, real HTTP.
+# Checks routing, leases (sticky + header), failover, recovery, streaming, queueing, pin, drain,
+# usage and metrics. Prints "smoke: ok" or fails with the crossbar log.
+set -eu
+cd "$(dirname "$0")/.."
+tmp=$(mktemp -d); trap 'kill $pids 2>/dev/null; rm -rf "$tmp"' EXIT INT TERM
+pids=""
+sed "s#^db .*#db = \"$tmp/crossbar.db\"#" example.toml > "$tmp/crossbar.toml"
+bin/fakeupstream -listen 127.0.0.1:18081 -name alpha -models ornith-1.5-35b-a3b,small-9b -down-file "$tmp/alpha.down" -slow 600 >"$tmp/alpha.log" 2>&1 & pids="$pids $!"
+bin/fakeupstream -listen 127.0.0.1:18082 -name beta  -models ornith-1.5-35b-a3b -down-file "$tmp/beta.down" >"$tmp/beta.log" 2>&1 & pids="$pids $!"
+bin/crossbar -config "$tmp/crossbar.toml" >"$tmp/crossbar.log" 2>&1 & pids="$pids $!"
+sleep 1.5
+fail() { echo "smoke: FAIL: $*" >&2; echo "--- crossbar.log"; cat "$tmp/crossbar.log"; exit 1; }
+base=http://127.0.0.1:17777
+conv() { printf '{"model":"ornith-1.5-35b-a3b","stream":false,"messages":[{"role":"system","content":"smoke"},{"role":"user","content":"conversation %s"}]}' "$1"; }
+hdrs() { curl -s -o /dev/null -w '%{http_code} %header{X-Crossbar-Host} %header{X-Crossbar-Lease}' "$@"; }
+
+# 1. a conversation gets a lease and keeps it; beta wins (2 slots × weight 2 vs 1 × 1)
+h=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv A)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 beta new" ] || fail "first turn should be '200 beta new', got '$h'"
+h=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv A)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 beta reused" ] || fail "second turn should reuse beta, got '$h'"
+
+# 2. header route
+h=$(hdrs -X POST -H 'Content-Type: application/json' -H 'X-Crossbar-Route: hermes-x' -d "$(conv B)" "$base/v1/chat/completions")
+case "$h" in "200 beta new") ;; *) fail "header route hermes-x should be '200 beta new', got '$h'";; esac
+h=$(curl -s -o /dev/null -w '%{http_code}' "$base/nope/v1/models"); [ "$h" = "404" ] || fail "unknown route 404, got $h"
+
+# 3. pin opencode-a to alpha: conversation A's next turn moves (an operator pin outranks the lease)
+h=$(curl -s -o /dev/null -w '%{http_code}' -X POST -H 'Content-Type: application/json' -d '{"host":"alpha","pin":true}' "$base/_crossbar/routes/opencode-a")
+[ "$h" = "200" ] || fail "pin returned $h"
+h=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv A)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 alpha new" ] || fail "after pin, conversation A should be '200 alpha new', got '$h'"
+curl -s "$base/_crossbar/routes" | grep -q '"pinned":"alpha"' || fail "routes view does not show the pin: $(curl -s $base/_crossbar/routes)"
+
+# 4. queue: alpha has parallel 1, queue_max 1, and answers in 600 ms → of three concurrent, one is 503
+for i in 1 2 3; do (curl -s -o /dev/null -w '%{http_code}\n' -X POST -H 'Content-Type: application/json' -d "$(conv Q$i)" "$base/opencode-a/v1/chat/completions" >> "$tmp/codes") & sleep 0.1; done; wait $! 2>/dev/null || true
+sleep 2.5
+sort "$tmp/codes" | uniq -c | tr -s ' ' > "$tmp/counts"
+grep -q '2 200' "$tmp/counts" && grep -q '1 503' "$tmp/counts" || fail "queue test wanted two 200 and one 503, got: $(cat "$tmp/counts")"
+
+# 5. release the pin, drain alpha: new conversations go to beta, A stays on alpha
+curl -s -o /dev/null -X POST -H 'Content-Type: application/json' -d '{"release":true}' "$base/_crossbar/routes/opencode-a"
+h=$(curl -s -o /dev/null -w '%{http_code}' -X POST -H 'Content-Type: application/json' -d '{"drain":true}' "$base/_crossbar/hosts/alpha"); [ "$h" = "200" ] || fail "drain returned $h"
+h=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv C)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 beta new" ] || fail "with alpha draining a new conversation should go to beta, got '$h'"
+curl -s "$base/_crossbar/hosts" | grep -q '"alpha":{[^}]*"draining":true' || fail "hosts view does not show alpha draining"
+curl -s -o /dev/null -X POST -H 'Content-Type: application/json' -d '{"drain":false}' "$base/_crossbar/hosts/alpha"
+
+# 6. failover + recovery
+touch "$tmp/beta.down"; sleep 2.5
+h=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv C)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 alpha new" ] || fail "with beta down conversation C should move to alpha, got '$h'"
+curl -s "$base/_crossbar/hosts" | grep -q '"beta":{"healthy":false' || fail "hosts view does not show beta unhealthy"
+rm "$tmp/beta.down"; sleep 3.5
+curl -s "$base/_crossbar/hosts" | grep -q '"beta":{"healthy":true' || fail "beta did not recover after two good polls"
+
+# 7. streaming still arrives incrementally, and the final usage chunk is untouched
+start=$(date +%s%N)
+curl -sN -X POST -H 'Content-Type: application/json' -d '{"model":"ornith-1.5-35b-a3b","stream":true,"messages":[{"role":"user","content":"stream me"}]}' \
+  "$base/opencode-a/v1/chat/completions" | while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    now=$(date +%s%N); echo "$(( (now - start) / 1000000 )) $line"
+  done > "$tmp/stream.txt"
+firstms=$(head -1 "$tmp/stream.txt" | cut -d' ' -f1); lastms=$(tail -1 "$tmp/stream.txt" | cut -d' ' -f1)
+[ -n "$firstms" ] && [ "$((lastms - firstms))" -ge 600 ] || fail "stream arrived in one burst: $(cat "$tmp/stream.txt")"
+grep -q '"usage"' "$tmp/stream.txt" && grep -q 'DONE' "$tmp/stream.txt" || fail "stream lost the usage chunk or DONE"
+
+# 8. accounting and metrics
+sleep 1
+u=$(curl -s "$base/_crossbar/usage?by=host")
+echo "$u" | grep -q '"key":"alpha"' && echo "$u" | grep -q '"key":"beta"' || fail "usage by host: $u"
+echo "$u" | grep -q '"cached_tokens":[1-9]' || fail "usage has no cached tokens (SSE/JSON usage not captured): $u"
+curl -s -H 'Accept: text/plain' "$base/_crossbar/usage?by=route" | grep -qi 'cache' || fail "text usage table missing"
+m=$(curl -s "$base/_crossbar/metrics")
+echo "$m" | grep -q 'crossbar_requests_total{route="opencode-a",host="alpha",status="503"} 1' || fail "metrics missing the 503: $m"
+echo "$m" | grep -q 'crossbar_host_healthy{host="beta"} 1' || fail "metrics missing host health"
+grep -q 'route=opencode-a host=' "$tmp/crossbar.log" || fail "no request log line"
+echo "smoke: ok (stream spread $((lastms - firstms)) ms)"

docs/plans/v2/01-props.md

@@ -0,0 +1,64 @@
+# v2 task 01: learn each host's context size from `/props`
+
+**Branch:** `v2` (create it from `master`: `git switch master && git switch -c v2`; `git status --short` must be empty first, otherwise stop)
+**Commit subject:** `Health: learn n_ctx and total_slots from /props`
+
+## Goal
+
+The poller already asks each host `/health` and `/v1/models`. It now also reads `/props` and
+remembers the context size and slot count, so the proxy (task 02) can tell whether a prompt fits.
+A missing or malformed `/props` is **not** a health failure: context is then simply unknown (0).
+
+## Context
+
+`llama-server` answers `GET /props` with a JSON object containing
+`default_generation_settings.n_ctx` (the total context the server was started with) and
+`total_slots` (how many parallel slots share it). With unified KV, one slot can use up to
+`n_ctx / total_slots` tokens. Some builds omit fields; old ones 404. Read at most `MaxModelsBody`
+bytes as for the other endpoints.
+
+## Files
+
+- Copy: `internal/health/props_test.go`
+- Modify: `internal/health/health.go`, `internal/admin/admin.go` (or wherever `HostView` is built), `docs/implementer-log.md`
+
+## Interfaces
+
+`internal/health`, additions:
+
+```go
+type Status struct {
+    // …existing fields…
+    NCtx  int `json:"n_ctx"`  // total context from /props; 0 = unknown
+    Slots int `json:"slots"`  // total_slots from /props; 0 = unknown
+}
+// PerSlotCtx is the context one request may use: NCtx / Slots, or NCtx when Slots is 0.
+func (s Status) PerSlotCtx() int
+```
+
+Rules the tests check:
+
+1. A poll is `/health`, `/v1/models` (as before), then `GET <base>/props`. If that request fails,
+   returns non-200, is not JSON, or lacks the fields, set `NCtx = 0`, `Slots = 0` and **do not
+   count the poll as failed**. Otherwise `NCtx = default_generation_settings.n_ctx`,
+   `Slots = total_slots` (negative values → 0).
+2. `PerSlotCtx()` is integer division; `NCtx` when `Slots == 0`; 0 when `NCtx == 0`.
+3. `admin.HostView` gains `NCtx int \`json:"n_ctx"\`` and `Slots int \`json:"slots"\`` copied
+   from the status (the v2 smoke reads `"n_ctx":8192` from `/_crossbar/hosts`). `admin_test.go`
+   must keep passing unchanged.
+
+## Steps
+
+- [ ] **1.** `git switch master && git switch -c v2`; `cp docs/plans/v2/_files/internal/health/props_test.go internal/health/`.
+- [ ] **2. See it fail** (compile: `NCtx` undefined). **3. Write the code.** `gofmt -w internal/`.
+- [ ] **4.** `go test -race -count=1 ./internal/health/ ./internal/admin/` → both `ok`.
+- [ ] **5.** `make gate` → `gate: ok`. **6.** Row `v2/01-props`; commit.
+
+```sh
+git add internal/health internal/admin docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- Both packages pass; gate ok; `props_test.go` byte-identical to `_files/`.

docs/plans/v2/02-ctxguard.md

@@ -0,0 +1,67 @@
+# v2 task 02: the context-size guard
+
+**Branch:** `v2` (run `git switch v2`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Proxy: move or refuse prompts that do not fit the leased host's context`
+
+## Goal
+
+The single worst failure a client sees today is the upstream's "Context size has been exceeded"
+after a long wait. With `PerSlotCtx` known (task 01), crossbar can estimate a prompt's size from
+its body and act before forwarding: move the conversation to a host where it fits, or answer 400
+with the estimate and the largest slot available. `PLAN.md` §4b.
+
+## Files
+
+- Copy: `internal/proxy/ctxguard_test.go`
+- Modify: `internal/proxy/proxy.go` and/or `forward.go` (new file `ctxguard.go` if that keeps files under 400 lines), `internal/lease/lease.go` (one addition, below), `docs/implementer-log.md`
+
+## Interfaces
+
+```go
+// internal/proxy
+const CtxHeader = "X-Crossbar-Ctx"      // set only when the guard moved a conversation: "moved:<from>>><to>" e.g. "moved:small>big"
+
+// internal/lease — one addition, the only change allowed there:
+// Move re-leases k onto host (deleting any existing lease for k), records a LeaseEvent with
+// Reason "ctx", FromHost the previous host ("" if none), ToHost host. Returns an error only from
+// the persister.
+func (t *Table) Move(k Key, host string, now time.Time) error
+```
+
+Rules the tests check (`ServeHTTP`, between acquiring the lease and taking a slot):
+
+1. `estimate := int(float64(len(body)) / 4 * 1.2)` tokens (body = the bytes already peeked; GET/HEAD → 0).
+2. `limit := PerSlotCtx` of the leased host's `health.Status`. If `limit == 0` (unknown) or
+   `estimate <= limit`: no action, no header.
+3. Otherwise find, among the route's candidate hosts (in order), the healthy, non-draining hosts
+   whose `PerSlotCtx() >= estimate` — prefer one that lists the model as loaded, else one that
+   can serve it (`cfg.Serves`). If one exists: `leases.Move(key, host, now)`, set
+   `CtxHeader` to `moved:<old>><new>`, and continue with the new host (**this request and the
+   following turns**: the lease moved).
+4. If none exists: **400** `{"error":"prompt too large","estimate":E,"max":M}` where `M` is the
+   largest `PerSlotCtx()` among the route's healthy hosts (0 if all unknown — but then rule 2
+   already let the request through). Record an accounting row with status 400 and
+   `Err: "prompt too large"`; do not mark anything down; do not forward.
+5. The estimate is never logged with the body; the log line gains `ctx_est=E` only.
+
+Add `ReasonCtx = "ctx"` to `internal/store` constants (one-line change, allowed).
+
+## Steps
+
+- [ ] **1.** `git switch v2`; `cp docs/plans/v2/_files/internal/proxy/ctxguard_test.go internal/proxy/`.
+- [ ] **2. See it fail** (compile: `CtxHeader`). **3. Write the code.** `gofmt -w internal/`.
+- [ ] **4.** `go test -race -count=2 ./internal/proxy/ ./internal/lease/` → `ok`.
+- [ ] **5.** `make gate` → `gate: ok`. **6.** Row `v2/02-ctxguard`; commit.
+
+```sh
+git add internal/proxy internal/lease internal/store docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- Tests pass with `-race -count=2`; gate ok; the copied test is byte-identical.
+
+## Stop and report if
+
+- `TestStickyLeaseSurvivesGrowthUntilItDoesNotFit` fails on the *second* request after the move (the lease did not actually move): quote the lease table.

docs/plans/v2/03-wake.md

@@ -0,0 +1,65 @@
+# v2 task 03: wake-on-LAN
+
+**Branch:** `v2` (run `git switch v2`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Add the wake package: magic packets and a waiter`
+
+## Goal
+
+A pure package. `wake.MagicPacket` builds the 102-byte wake-on-LAN frame, `wake.Send` puts it on
+the wire as UDP, and `wake.Waker` wakes a named host at most once per wait window and waits for
+the health table to report it healthy. Task 05 uses it when a route has no healthy host.
+
+## Context
+
+A magic packet is six `0xff` bytes followed by the target MAC sixteen times, sent as a UDP
+datagram to the LAN broadcast address (port 9 by convention). The sleeping Mac (titan) has
+wake-on-magic-packet enabled; it takes 20–40 s to be reachable. Waking twice inside that window
+is harmless but pointless, so the waker remembers when it last sent.
+
+## Files
+
+- Copy: `internal/wake/wake_test.go`
+- Create: `internal/wake/wake.go`
+- Modify: `docs/implementer-log.md`
+
+## Interfaces
+
+```go
+package wake
+
+type Target struct {
+    MAC, Broadcast string   // "aa:bb:cc:dd:ee:ff" (also "-" separated, any case); "host:port"
+    Wait           time.Duration
+}
+type Health interface{ Healthy(name string) bool }
+
+func MagicPacket(mac string) ([]byte, error)     // net.ParseMAC; must be 6 bytes; 102-byte frame
+func Send(mac, broadcast string) error           // one UDP datagram via net.DialUDP("udp4", …); errors from parse/resolve/write
+type Waker struct { /* private: targets, health, mutex, last-sent per host, poll interval (default 1s) */ }
+func New(targets map[string]Target, h Health) *Waker
+func (w *Waker) PollEvery(d time.Duration)       // test hook; production keeps the 1 s default
+// Wake returns true as soon as h.Healthy(host) is true, false if host is unknown, if Wait passes,
+// or if ctx ends first. It sends the packet only if none was sent for host in the last Wait.
+func (w *Waker) Wake(ctx context.Context, host string) bool
+```
+
+Rules the tests check: packet layout; separators; errors for bad MACs and unresolvable
+addresses; one packet per window; return within about `Wait` when the host never comes up;
+early return on a cancelled context; `false` for an unknown host without sending anything.
+Never panic; safe for concurrent `Wake` calls on different hosts.
+
+## Steps
+
+- [ ] **1.** `git switch v2`; `mkdir -p internal/wake`; copy the test.
+- [ ] **2. See it fail** (compile). **3. Write `wake.go`.** `gofmt -w internal/wake/`.
+- [ ] **4.** `go test -race -count=3 ./internal/wake/` → `ok` (timing tests; three runs).
+- [ ] **5.** `make gate`. **6.** Row `v2/03-wake`; commit.
+
+```sh
+git add internal/wake docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- `-race -count=3` passes; gate ok; the copied test is byte-identical.

docs/plans/v2/04-identity.md

@@ -0,0 +1,92 @@
+# v2 task 04: tailnet identity and the route gate; config additions
+
+**Branch:** `v2` (run `git switch v2`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Add identity: whois resolver, checker, header mode, middleware; config for wake, peers, identity`
+
+## Goal
+
+Some routes should be usable only from particular tailnet nodes ("`hermes-talos` only from
+talos"). `identity` resolves a caller's address to a tailnet node name — in production through
+`tailscale whois --json <ip>`, in tests through a fake, in the smoke run through a header — and a
+middleware in front of the proxy refuses other callers with 403. Config gains the keys the rest
+of v2 needs.
+
+## Files
+
+- Copy: `internal/identity/identity_test.go`, `internal/identity/middleware_test.go`, `internal/identity/testdata/whois.json`, `internal/config/config_v2_test.go`
+- Create: `internal/identity/identity.go`, `internal/identity/middleware.go`
+- Modify: `internal/config/config.go`, `docs/implementer-log.md`
+
+## Interfaces
+
+```go
+package identity
+
+var (
+    ErrNotAPeer  = errors.New("identity: not a tailnet peer")
+    ErrForbidden = errors.New("identity: forbidden route")
+)
+type ID struct{ Node, Login string }
+type Resolver interface { Identity(ctx context.Context, ip string) (ID, error) }
+
+// ParseWhois reads `tailscale whois --json` output: Node = Node.ComputedName (else Node.Name
+// without its trailing dot and domain), Login = UserProfile.LoginName. Empty node → error.
+func ParseWhois(raw []byte) (ID, error)
+
+// TailscaleResolver runs `tailscale whois --json <ip>` (exec, 3 s timeout) and parses it; a
+// non-zero exit is ErrNotAPeer; a missing binary is an error that the Checker treats as "deny".
+type TailscaleResolver struct{ Bin string }   // Bin default "tailscale"
+func (TailscaleResolver) Identity(ctx context.Context, ip string) (ID, error)
+
+type Checker struct { /* private: resolver, cache map[ip]ID with a 5-minute TTL, mutex */ }
+func NewChecker(r Resolver) *Checker
+// NewHeaderChecker trusts the X-Crossbar-Peer request header as the node name. TEST/SMOKE ONLY.
+func NewHeaderChecker() *Checker
+// Allow: nil when peers is empty (open route); otherwise the caller's node (from remoteAddr's
+// IP, or the header in header mode) must be in peers, else ErrForbidden. Any resolver error,
+// unparsable address or loopback → ErrForbidden.
+func (c *Checker) Allow(ctx context.Context, peers []string, remoteAddr string) error
+
+// Middleware names the route like the proxy (X-Crossbar-Route header, else first path segment),
+// asks peersFor(route), and answers 403 {"error":"forbidden route"} when Allow refuses. Paths
+// under /_crossbar/ and routes peersFor does not know pass straight through.
+func Middleware(c *Checker, peersFor func(route string) ([]string, bool), next http.Handler) http.Handler
+```
+
+Header mode: `Allow` needs the request to read the header, but its signature takes an address.
+Make the header checker's resolver read from a `context.Context` value that `Middleware` sets
+(`identity.WithHeaderPeer(ctx, r.Header.Get("X-Crossbar-Peer"))`); the tests only observe the
+behaviour. Cache: per address, 5 minutes, for both hit and `ErrNotAPeer`.
+
+`internal/config` gains:
+
+```go
+Identity string `toml:"identity"`   // "off" (default) | "tailscale" | "header"; anything else → *Error field "identity"
+// on Host:
+Wake *Wake `toml:"wake"`             // nil when absent
+type Wake struct { MAC string `toml:"mac"`; Broadcast string `toml:"broadcast"`; Wait Duration `toml:"wait"` }
+// on Route:
+Peers []string `toml:"peers"`
+```
+
+Validation (after the existing host/route checks): `wake.mac` must parse (`net.ParseMAC`, 6
+bytes) → field `hosts.<h>.wake.mac`; `wake.broadcast` non-empty `host:port` → `hosts.<h>.wake.broadcast`;
+`wake.wait` default 45 s, less than 5 s → `hosts.<h>.wake.wait`. `routes.<r>.peers` non-empty
+while `identity == "off"` → `routes.<r>.peers` ("peers need identity = tailscale or header");
+`peers = []` (present but empty) with identity on → same field ("empty peers list").
+
+## Steps
+
+- [ ] **1.** `git switch v2`; `mkdir -p internal/identity/testdata`; copy the four given files.
+- [ ] **2. See them fail** (compile). **3. Write the code.** `gofmt -w internal/`.
+- [ ] **4.** `go test -race -count=1 ./internal/identity/ ./internal/config/` → `ok` (v0/v1 config tests included).
+- [ ] **5.** `make gate`. **6.** Row `v2/04-identity`; commit.
+
+```sh
+git add internal/identity internal/config docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- Both packages pass; gate ok; all four copied files byte-identical.

docs/plans/v2/05-wiring-smoke.md

@@ -0,0 +1,58 @@
+# v2 task 05: wiring, the smoke run, README
+
+**Branch:** `v2` (run `git switch v2`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Wire wake and identity into crossbar; v2 smoke and README`
+
+## Goal
+
+Put the pieces together: the proxy wakes a sleeping host when a route has no healthy host left,
+`main` builds the waker from config and wraps the proxy in the identity middleware when
+`identity` is on, the given fake upstream can be woken, and `tools/smoke.sh` proves the whole of
+v2 over real HTTP.
+
+## Files
+
+- Copy (**replaces** v1's): `cmd/fakeupstream/main.go`, `tools/smoke.sh`, `example.toml`
+- Modify: `internal/proxy/proxy.go` (or a new file), `cmd/crossbar/main.go`, `README.md`, `docs/implementer-log.md`
+
+## Rules
+
+1. `proxy.Handler` gains `func (p *Handler) SetWaker(w Waker)` where
+   `type Waker interface{ Wake(ctx context.Context, host string) bool }` (defined in `proxy`).
+   When `leases.Acquire` returns `ErrNoHost` and a waker is set: for each candidate host of the
+   route, in order, that has a wake target (ask `cfg.Hosts[h].Wake != nil`), call
+   `Wake(r.Context(), h)`; on `true`, retry `Acquire` once; on `false` for every candidate, 503
+   `{"error":"no healthy host","woke":["<hosts tried>"]}`. The context-guard's "no host fits"
+   path (task 02) also tries waking a host whose `PerSlotCtx` is unknown or large enough, before
+   answering 400.
+2. `cmd/crossbar`: build `wake.New(targets, hosts)` from every host with `Wake != nil`
+   (`hosts` is the `proxy.HostView`, which has `Healthy`), call `p.SetWaker(w)`. When
+   `cfg.Identity != "off"`: `checker := identity.NewChecker(identity.TailscaleResolver{})` or
+   `identity.NewHeaderChecker()`; wrap the proxy handler:
+   `mux.Handle("/", identity.Middleware(checker, func(route string) ([]string, bool) { rt, ok := cfg.Routes[route]; return rt.Peers, ok }, p))`.
+   Log at start which mode is active; with `"header"` log a warning that it is insecure.
+3. Copy the three given files; `make build`; `make smoke` → `smoke: ok (…)`. The smoke's check 2
+   waits up to 40 s for the wake; the fake wakes in ~1 s.
+4. README: sections stay; add under `## Operate` the wake behaviour and the identity modes with
+   the `peers` example; under `## Configure` the three new keys; `## What v2 does not do`:
+   `/slots`, request coalescing, TLS — `PLAN.md`.
+
+## Steps
+
+- [ ] **1.** `git switch v2`; copy the three given files.
+- [ ] **2. Write the code** (proxy waker path, `main`). `gofmt -w .`
+- [ ] **3.** `go test -race -count=1 ./...` → all `ok`. **4.** `make smoke` → `smoke: ok`.
+- [ ] **5.** README. **6.** `make gate`. **7.** Row `v2/05-wiring-smoke`; commit.
+
+```sh
+git add internal/proxy cmd/crossbar cmd/fakeupstream tools/smoke.sh example.toml README.md docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- `make smoke` prints `smoke: ok (…)`; gate ok; the three copied files byte-identical.
+
+## Stop and report if
+
+- `make smoke` fails twice in the same way; quote the failing check and the crossbar log.

docs/plans/v2/README.md

@@ -0,0 +1,54 @@
+# v2 implementation plan: learned context, the context guard, wake-on-LAN, identity
+
+> **For the implementing model:** do not work from this file. The owner gives you one task file at
+> a time (`01-…` to `05-…`). This file is the index for the owner and the reviewer.
+
+**Goal:** `PLAN.md` §4b and §10 v2. The poller learns each host's context size from `/props`; a
+prompt that cannot fit the leased host's per-slot context moves to one where it fits or is
+refused with a clear 400; a route whose hosts are all down can wake a sleeping host by
+wake-on-LAN and wait for it; a route can be restricted to named tailnet peers.
+
+**Architecture:** `health.Status` gains `NCtx`/`Slots` (task 01); the proxy gains the guard
+(task 02); two new small packages, `wake` (magic packets + a waiter, task 03) and `identity`
+(whois resolver, checker, middleware, task 04); config gains `identity`, `[hosts.x.wake]`,
+`routes.x.peers`; `main` wires the waker and the middleware (task 05).
+
+**How this plan was made:** acceptance tests first, from `PLAN.md`; no reference implementation.
+Every given test compiled against a panic-only skeleton of the names in the tasks (`go vet`
+clean). The given tests were walked against the task rules and against the other given files
+(helpers, line limits, `main.go` call sites) before handover — the v1 findings list is the
+reason.
+
+**Tech stack:** as v1; no new module. `identity`'s production resolver shells out to
+`tailscale whois --json`, which exists on every fleet host.
+
+## Global constraints
+
+- Everything in `AGENTS.md`. Branch `v2`. One task, one fresh OpenCode session, one commit.
+- Bodies never logged. Type assertions two-valued. Files under 400 lines.
+- Given files are copied and never edited; some **replace** earlier ones (the task says so).
+
+## Tasks
+
+| # | File | Delivers | Tests that define it |
+|---|---|---|---|
+| 01 | `01-props.md` | `Status.NCtx`, `Status.Slots`, `PerSlotCtx()`; `/props` in the poll; hosts view shows them | `health/props_test.go` |
+| 02 | `02-ctxguard.md` | prompt-size estimate; move or 400; `X-Crossbar-Ctx` | `proxy/ctxguard_test.go` |
+| 03 | `03-wake.md` | `internal/wake`: magic packet, `Send`, `Waker` | `wake/wake_test.go` |
+| 04 | `04-identity.md` | `internal/identity`: whois parse, checker, header mode, middleware; config `identity`/`peers`/`wake` | `identity/*_test.go`, `config/config_v2_test.go` |
+| 05 | `05-wiring-smoke.md` | proxy wakes on no-host; `main` wires waker + middleware; given fakeupstream/smoke/example; README | `make smoke` |
+
+## For the owner
+
+`tools/run-plan.sh docs/plans/v2` from a clean checkout on `master`.
+
+## For the reviewer: after task 05
+
+1. Five task commits with the trailer; given files byte-identical; protected files untouched.
+2. `make gate`, `make smoke`.
+3. Probe: a `/props` that returns 200 with a huge body (bounded read); a MAC with an unusual
+   separator in config; `identity = "tailscale"` on a host where `tailscale` is not on PATH
+   (must log and refuse the gated routes, never allow); two routes, one gated one open, from
+   the same peer; a wake target whose broadcast address is unroutable (503 within `wait`, no
+   hang); the guard with a body of exactly `MaxBody`.
+4. Findings under "Reviews" in `docs/implementer-log.md`, by fault.

docs/plans/v2/_files/cmd/fakeupstream/main.go

@@ -0,0 +1,161 @@
+// fakeupstream stands in for a llama-server router in tests and the smoke run. Do not edit.
+//
+//	fakeupstream -listen 127.0.0.1:18081 -name alpha -models a,b -down-file /tmp/alpha.down -slow 0
+//
+// /health answers 503 while the down file exists, 200 otherwise. /v1/models lists -models.
+// /props answers a small JSON object. /v1/chat/completions echoes: a streamed answer of five
+// SSE chunks 200 ms apart when the body has "stream": true, then a final chunk carrying
+// "usage" and llama-server style "timings", then [DONE]; one JSON answer with usage and
+// timings otherwise. -slow adds that many milliseconds before answering (for queue tests).
+// Every response carries X-Upstream: <name>. /props reports -n-ctx and -slots. With -wol-listen,
+// a valid wake-on-LAN magic packet for -wol-mac received on that UDP address removes the down
+// file, so the fake "boots" when woken.
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+)
+
+func main() {
+	listen := flag.String("listen", "127.0.0.1:18081", "address to listen on")
+	name := flag.String("name", "fake", "name reported in X-Upstream and answers")
+	models := flag.String("models", "m", "comma-separated model ids for /v1/models")
+	downFile := flag.String("down-file", "", "while this file exists, /health answers 503")
+	slow := flag.Int("slow", 0, "milliseconds to wait before answering a completion")
+	nCtx := flag.Int("n-ctx", 8192, "n_ctx reported by /props")
+	slots := flag.Int("slots", 2, "total_slots reported by /props")
+	wolListen := flag.String("wol-listen", "", "UDP address to listen on for a wake-on-LAN magic packet")
+	wolMAC := flag.String("wol-mac", "aa:bb:cc:dd:ee:01", "MAC the magic packet must carry")
+	flag.Parse()
+	if *wolListen != "" && *downFile != "" {
+		go wakeOnPacket(*wolListen, *wolMAC, *downFile)
+	}
+
+	ids := strings.Split(*models, ",")
+	mux := http.NewServeMux()
+	stamp := func(w http.ResponseWriter) { w.Header().Set("X-Upstream", *name) }
+	usage := map[string]any{"prompt_tokens": 100, "completion_tokens": 10, "total_tokens": 110}
+	timings := map[string]any{"prompt_n": 100, "cache_n": 90, "predicted_n": 10, "predicted_ms": 50.0}
+
+	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
+		stamp(w)
+		if *downFile != "" {
+			if _, err := os.Stat(*downFile); err == nil {
+				http.Error(w, `{"error":{"message":"Loading model"}}`, http.StatusServiceUnavailable)
+				return
+			}
+		}
+		writeJSON(w, map[string]string{"status": "ok"})
+	})
+	mux.HandleFunc("/v1/models", func(w http.ResponseWriter, r *http.Request) {
+		stamp(w)
+		data := []map[string]any{}
+		for _, id := range ids {
+			data = append(data, map[string]any{"id": id, "object": "model", "owned_by": *name})
+		}
+		writeJSON(w, map[string]any{"object": "list", "data": data})
+	})
+	mux.HandleFunc("/props", func(w http.ResponseWriter, r *http.Request) {
+		stamp(w)
+		writeJSON(w, map[string]any{"default_generation_settings": map[string]any{"n_ctx": *nCtx}, "total_slots": *slots, "model_path": *name})
+	})
+	mux.HandleFunc("/v1/chat/completions", func(w http.ResponseWriter, r *http.Request) {
+		stamp(w)
+		body, _ := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+		var req struct {
+			Model  string `json:"model"`
+			Stream bool   `json:"stream"`
+		}
+		_ = json.Unmarshal(body, &req)
+		time.Sleep(time.Duration(*slow) * time.Millisecond)
+		if !req.Stream {
+			writeJSON(w, map[string]any{
+				"id": "chatcmpl-fake", "object": "chat.completion", "model": req.Model,
+				"choices": []map[string]any{{"index": 0, "message": map[string]string{"role": "assistant", "content": "hello from " + *name}, "finish_reason": "stop"}},
+				"usage":   usage, "timings": timings,
+			})
+			return
+		}
+		w.Header().Set("Content-Type", "text/event-stream")
+		w.Header().Set("Cache-Control", "no-cache")
+		w.WriteHeader(http.StatusOK)
+		fl, _ := w.(http.Flusher)
+		flush := func() {
+			if fl != nil {
+				fl.Flush()
+			}
+		}
+		for i := 1; i <= 5; i++ {
+			chunk := map[string]any{"id": "chatcmpl-fake", "object": "chat.completion.chunk", "model": req.Model,
+				"choices": []map[string]any{{"index": 0, "delta": map[string]string{"content": fmt.Sprintf("%s chunk %d ", *name, i)}}}}
+			b, _ := json.Marshal(chunk)
+			fmt.Fprintf(w, "data: %s\n\n", b)
+			flush()
+			time.Sleep(200 * time.Millisecond)
+		}
+		final := map[string]any{"id": "chatcmpl-fake", "object": "chat.completion.chunk", "model": req.Model,
+			"choices": []map[string]any{}, "usage": usage, "timings": timings}
+		b, _ := json.Marshal(final)
+		fmt.Fprintf(w, "data: %s\n\n", b)
+		flush()
+		fmt.Fprint(w, "data: [DONE]\n\n")
+	})
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		stamp(w)
+		http.Error(w, `{"error":"not found"}`, http.StatusNotFound)
+	})
+
+	log.Printf("fakeupstream %s listening on %s models=%v slow=%dms", *name, *listen, ids, *slow)
+	srv := &http.Server{Addr: *listen, Handler: mux, ReadHeaderTimeout: 5 * time.Second}
+	log.Fatal(srv.ListenAndServe())
+}
+
+func writeJSON(w http.ResponseWriter, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(v)
+}
+
+// wakeOnPacket removes downFile when a magic packet for mac arrives: 6×0xff then the MAC 16 times.
+func wakeOnPacket(addr, mac, downFile string) {
+	hw, err := net.ParseMAC(mac)
+	if err != nil {
+		log.Fatalf("wol-mac: %v", err)
+	}
+	pc, err := net.ListenPacket("udp4", addr)
+	if err != nil {
+		log.Fatalf("wol-listen: %v", err)
+	}
+	log.Printf("fakeupstream listening for wake-on-LAN on %s (mac %s)", addr, hw)
+	buf := make([]byte, 256)
+	for {
+		n, _, err := pc.ReadFrom(buf)
+		if err != nil {
+			return
+		}
+		if n != 102 {
+			continue
+		}
+		ok := true
+		for i := 0; i < 6; i++ {
+			ok = ok && buf[i] == 0xff
+		}
+		for i := 0; i < 16 && ok; i++ {
+			for j := 0; j < 6; j++ {
+				ok = ok && buf[6+6*i+j] == hw[j]
+			}
+		}
+		if ok {
+			log.Printf("magic packet received: waking (removing %s)", downFile)
+			_ = os.Remove(downFile)
+		}
+	}
+}

docs/plans/v2/_files/example.toml

@@ -0,0 +1,32 @@
+# crossbar example configuration (v1). Replace <tailnet> and the addresses with your own.
+listen        = "127.0.0.1:17777"   # never 0.0.0.0 — bind the tailnet address in production
+db            = "crossbar.db"       # SQLite: leases + accounting (WAL). /var/lib/crossbar/crossbar.db under systemd
+poll_interval = "1s"                # 60s in production; 1s makes the smoke run quick
+lease_idle    = "30m"               # a conversation idle this long loses its host
+retention     = "180d"              # per-request rows older than this are rolled up daily
+queue_max     = 1                   # waiting places per (host, model) beyond `parallel`; 503 past that
+identity      = "off"               # "tailscale" gates routes with `peers` by `tailscale whois`; "header" trusts X-Crossbar-Peer (TEST ONLY)
+
+[hosts.alpha]
+base_url = "http://127.0.0.1:18081"    # e.g. http://straylight.<tailnet>:11434
+weight   = 1.0
+models   = { "ornith-1.5-35b-a3b" = { parallel = 1 }, "small-9b" = { parallel = 6 } }
+
+[hosts.beta]
+base_url = "http://127.0.0.1:18082"    # e.g. http://titan.<tailnet>:8081
+weight   = 2.0
+models   = { "ornith-1.5-35b-a3b" = { parallel = 2 } }
+[hosts.beta.wake]                      # v2: wake a sleeping host when nothing else can take a new lease
+mac       = "aa:bb:cc:dd:ee:02"
+broadcast = "127.0.0.1:19082"          # the LAN broadcast address, port 9, in production
+wait      = "20s"
+
+# v1: a route is a set of candidate hosts; each conversation gets a sticky lease on the host with
+# the most free slots × weight at the time it starts. Pins and drains come from the admin API.
+[routes.opencode-a]
+hosts         = ["alpha", "beta"]
+default_model = "ornith-1.5-35b-a3b"
+
+[routes.hermes-x]
+hosts = ["beta", "alpha"]
+# peers = ["talos"]                    # v2: with identity = "tailscale", only these tailnet nodes may use the route

docs/plans/v2/_files/internal/config/config_v2_test.go

@@ -0,0 +1,75 @@
+package config_test
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+)
+
+const v2Base = `
+listen = "127.0.0.1:1"
+[hosts.a]
+base_url = "http://a:1"
+models = { "m" = { } }
+[hosts.b]
+base_url = "http://b:1"
+models = { "m" = { } }
+[hosts.b.wake]
+mac = "aa:bb:cc:dd:ee:ff"
+broadcast = "192.168.1.255:9"
+wait = "45s"
+[routes.r]
+hosts = ["a", "b"]
+peers = ["talos", "imladris"]
+`
+
+func TestV2Defaults(t *testing.T) {
+	c, err := config.Parse(strings.NewReader(v2Base))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.Identity != "off" {
+		t.Errorf("identity default = %q, want off", c.Identity)
+	}
+	if c.Hosts["a"].Wake != nil {
+		t.Errorf("host without [wake] must have nil Wake")
+	}
+	w := c.Hosts["b"].Wake
+	if w == nil || w.MAC != "aa:bb:cc:dd:ee:ff" || w.Broadcast != "192.168.1.255:9" || w.Wait.Duration != 45*time.Second {
+		t.Errorf("wake = %+v", w)
+	}
+	if p := c.Routes["r"].Peers; len(p) != 2 || p[0] != "talos" {
+		t.Errorf("peers = %v", p)
+	}
+}
+
+func TestV2Validation(t *testing.T) {
+	good := v2Base
+	for _, tc := range []struct{ name, text, field string }{
+		{"bad identity", "identity = \"maybe\"\n" + good, "identity"},
+		{"peers without identity", "identity = \"off\"\n" + good, "routes.r.peers"},
+		{"bad mac", strings.Replace(good, `mac = "aa:bb:cc:dd:ee:ff"`, `mac = "nope"`, 1), "hosts.b.wake.mac"},
+		{"no broadcast", strings.Replace(good, `broadcast = "192.168.1.255:9"`, `broadcast = ""`, 1), "hosts.b.wake.broadcast"},
+		{"wait too short", strings.Replace(good, `wait = "45s"`, `wait = "2s"`, 1), "hosts.b.wake.wait"},
+		{"peers on unknown route field", "identity = \"tailscale\"\n" + strings.Replace(good, `peers = ["talos", "imladris"]`, `peers = []`, 1), "routes.r.peers"},
+	} {
+		_, err := config.Parse(strings.NewReader(tc.text))
+		e, ok := config.IsError(err)
+		if !ok || e.Field != tc.field {
+			t.Errorf("%s: %v, want *Error on %s", tc.name, err, tc.field)
+		}
+	}
+	// identity = "header" is the test/smoke mode; "tailscale" the real one; both accept peers.
+	for _, mode := range []string{"header", "tailscale"} {
+		if _, err := config.Parse(strings.NewReader("identity = \"" + mode + "\"\n" + good)); err != nil {
+			t.Errorf("identity=%s with peers: %v", mode, err)
+		}
+	}
+	// wait defaults to 45s when the [wake] table omits it
+	c, err := config.Parse(strings.NewReader("identity = \"header\"\n" + strings.Replace(good, "wait = \"45s\"\n", "", 1)))
+	if err != nil || c.Hosts["b"].Wake == nil || c.Hosts["b"].Wake.Wait.Duration != 45*time.Second {
+		t.Errorf("wake.wait default: %v %+v", err, c.Hosts["b"].Wake)
+	}
+}

docs/plans/v2/_files/internal/health/props_test.go

@@ -0,0 +1,75 @@
+package health_test
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/health"
+)
+
+// propsFake answers /health, /v1/models and a configurable /props.
+func propsFake(t *testing.T, props string, status int) *httptest.Server {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, `{"status":"ok"}`) })
+	mux.HandleFunc("/v1/models", func(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, `{"data":[{"id":"m"}]}`) })
+	mux.HandleFunc("/props", func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(status)
+		fmt.Fprint(w, props)
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestPropsLearned(t *testing.T) {
+	srv := propsFake(t, `{"default_generation_settings":{"n_ctx":131072,"params":{}},"total_slots":4,"model_path":"/x/m.gguf","chat_template":"..."}`, 200)
+	tbl := health.New(map[string]string{"a": srv.URL}, time.Hour, nil)
+	tbl.PollOnce(context.Background())
+	s, _ := tbl.Get("a")
+	if !s.Healthy || s.NCtx != 131072 || s.Slots != 4 {
+		t.Fatalf("status = %+v, want healthy with NCtx 131072 and Slots 4", s)
+	}
+	if got := s.PerSlotCtx(); got != 32768 {
+		t.Errorf("PerSlotCtx = %d, want 131072/4", got)
+	}
+}
+
+func TestPropsAbsentOrBrokenIsNotAFailure(t *testing.T) {
+	for name, tc := range map[string]struct {
+		props  string
+		status int
+	}{
+		"404":       {`not found`, 404},
+		"not json":  {`<html>`, 200},
+		"no fields": {`{"model_path":"/x"}`, 200},
+		"zero ctx":  {`{"default_generation_settings":{"n_ctx":0},"total_slots":0}`, 200},
+	} {
+		t.Run(name, func(t *testing.T) {
+			srv := propsFake(t, tc.props, tc.status)
+			tbl := health.New(map[string]string{"a": srv.URL}, time.Hour, nil)
+			tbl.PollOnce(context.Background())
+			s, _ := tbl.Get("a")
+			if !s.Healthy {
+				t.Fatalf("a bad /props must not make the host unhealthy: %+v", s)
+			}
+			if s.NCtx != 0 || s.Slots != 0 || s.PerSlotCtx() != 0 {
+				t.Errorf("unknown context must read as 0: %+v", s)
+			}
+		})
+	}
+}
+
+func TestPerSlotCtxWithUnknownSlots(t *testing.T) {
+	s := health.Status{NCtx: 8192, Slots: 0}
+	if s.PerSlotCtx() != 8192 {
+		t.Errorf("with Slots unknown the whole context is the per-slot value; got %d", s.PerSlotCtx())
+	}
+	s = health.Status{NCtx: 8192, Slots: 3}
+	if s.PerSlotCtx() != 2730 {
+		t.Errorf("integer division: got %d, want 2730", s.PerSlotCtx())
+	}
+}

docs/plans/v2/_files/internal/identity/identity_test.go

@@ -0,0 +1,90 @@
+package identity_test
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/identity"
+)
+
+func TestParseWhois(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join("testdata", "whois.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	id, err := identity.ParseWhois(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if id.Node != "titan" || id.Login == "" {
+		t.Errorf("parsed %+v, want Node titan and a login", id)
+	}
+	if _, err := identity.ParseWhois([]byte(`{"Node":{}}`)); err == nil {
+		t.Error("a whois answer without a node name must be an error")
+	}
+	if _, err := identity.ParseWhois([]byte(`nope`)); err == nil {
+		t.Error("non-JSON must be an error")
+	}
+}
+
+// fakeResolver answers from a map; "" means not a tailnet peer.
+type fakeResolver map[string]string
+
+func (f fakeResolver) Identity(ctx context.Context, ip string) (identity.ID, error) {
+	n, ok := f[ip]
+	if !ok {
+		return identity.ID{}, identity.ErrNotAPeer
+	}
+	return identity.ID{Node: n, Login: n + "@example"}, nil
+}
+
+func TestChecker(t *testing.T) {
+	c := identity.NewChecker(fakeResolver{"100.64.0.5": "talos", "100.64.0.9": "titan"})
+	for _, tc := range []struct {
+		name  string
+		peers []string
+		addr  string
+		want  error
+	}{
+		{"open route", nil, "203.0.113.7:1", nil},
+		{"allowed peer", []string{"talos", "titan"}, "100.64.0.5:44444", nil},
+		{"other peer", []string{"talos"}, "100.64.0.9:1", identity.ErrForbidden},
+		{"not a peer", []string{"talos"}, "203.0.113.7:1", identity.ErrForbidden},
+		{"loopback", []string{"talos"}, "127.0.0.1:1", identity.ErrForbidden},
+		{"garbage addr", []string{"talos"}, "nonsense", identity.ErrForbidden},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got := c.Allow(context.Background(), tc.peers, tc.addr)
+			if !errors.Is(got, tc.want) && !(got == nil && tc.want == nil) {
+				t.Errorf("Allow(%v, %q) = %v, want %v", tc.peers, tc.addr, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestCheckerCachesPerAddress(t *testing.T) {
+	calls := 0
+	r := countingResolver{f: fakeResolver{"100.64.0.5": "talos"}, calls: &calls}
+	c := identity.NewChecker(r)
+	for i := 0; i < 5; i++ {
+		if err := c.Allow(context.Background(), []string{"talos"}, "100.64.0.5:1"); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if calls != 1 {
+		t.Errorf("resolver called %d times for one address, want 1 (cache)", calls)
+	}
+}
+
+type countingResolver struct {
+	f     fakeResolver
+	calls *int
+}
+
+func (c countingResolver) Identity(ctx context.Context, ip string) (identity.ID, error) {
+	*c.calls++
+	return c.f.Identity(ctx, ip)
+}

docs/plans/v2/_files/internal/identity/middleware_test.go

@@ -0,0 +1,74 @@
+package identity_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/identity"
+)
+
+// The middleware sits in front of the proxy: it names the route the same way the proxy does
+// (X-Crossbar-Route header, else first path segment) and refuses callers a route does not list.
+func TestMiddleware(t *testing.T) {
+	peers := map[string][]string{"locked": {"talos"}, "open": nil}
+	inner := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(204) })
+	h := identity.Middleware(identity.NewChecker(fakeResolver{"100.64.0.5": "talos", "100.64.0.9": "titan"}),
+		func(route string) ([]string, bool) { p, ok := peers[route]; return p, ok }, inner)
+	for _, tc := range []struct {
+		name, path, hdr, addr string
+		want                  int
+	}{
+		{"open route, anyone", "/open/v1/models", "", "203.0.113.1:5", 204},
+		{"locked, right peer", "/locked/v1/models", "", "100.64.0.5:5", 204},
+		{"locked, wrong peer", "/locked/v1/models", "", "100.64.0.9:5", 403},
+		{"locked, not a peer", "/locked/v1/models", "", "203.0.113.1:5", 403},
+		{"locked via header", "/v1/models", "locked", "100.64.0.9:5", 403},
+		{"header wins over path", "/open/v1/models", "locked", "203.0.113.1:5", 403},
+		{"unknown route passes through to the proxy's own 404", "/nope/v1/models", "", "203.0.113.1:5", 204},
+		{"admin path is never gated here", "/_crossbar/hosts", "", "203.0.113.1:5", 204},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			req := httptest.NewRequest(http.MethodGet, tc.path, nil)
+			req.RemoteAddr = tc.addr
+			if tc.hdr != "" {
+				req.Header.Set("X-Crossbar-Route", tc.hdr)
+			}
+			rec := httptest.NewRecorder()
+			h.ServeHTTP(rec, req)
+			if rec.Code != tc.want {
+				t.Errorf("%s = %d, want %d (%s)", tc.path, rec.Code, tc.want, rec.Body.String())
+			}
+			if rec.Code == 403 && (!strings.HasPrefix(rec.Header().Get("Content-Type"), "application/json") || !strings.Contains(rec.Body.String(), `"forbidden route"`)) {
+				t.Errorf("403 must be JSON {\"error\":\"forbidden route\"}: %q", rec.Body.String())
+			}
+		})
+	}
+}
+
+// HeaderResolver is the test/smoke identity source: it trusts X-Crossbar-Peer. It exists so the
+// smoke run can exercise the gate without a tailnet; config must call it out as insecure.
+func TestHeaderResolver(t *testing.T) {
+	inner := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(204) })
+	h := identity.Middleware(identity.NewHeaderChecker(), func(route string) ([]string, bool) { return []string{"talos"}, true }, inner)
+	req := httptest.NewRequest(http.MethodGet, "/r/v1/models", nil)
+	req.Header.Set("X-Crossbar-Peer", "talos")
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != 204 {
+		t.Errorf("header peer talos: %d", rec.Code)
+	}
+	req.Header.Set("X-Crossbar-Peer", "titan")
+	rec = httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != 403 {
+		t.Errorf("header peer titan: %d, want 403", rec.Code)
+	}
+	req.Header.Del("X-Crossbar-Peer")
+	rec = httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != 403 {
+		t.Errorf("no header: %d, want 403", rec.Code)
+	}
+}

docs/plans/v2/_files/internal/identity/testdata/whois.json

@@ -0,0 +1,24 @@
+{
+ "Node": {
+  "ID": 1,
+  "StableID": "nEXAMPLE",
+  "Name": "titan.example.ts.net.",
+  "User": 2,
+  "Addresses": [
+   "100.64.0.9/32",
+   "fd7a:115c:a1e0::9/128"
+  ],
+  "HomeDERP": 2,
+  "Created": "2026-01-01T00:00:00Z",
+  "Cap": 138,
+  "Online": true,
+  "ComputedName": "titan",
+  "ComputedNameWithHost": "titan"
+ },
+ "UserProfile": {
+  "ID": 2,
+  "LoginName": "user@example.com",
+  "DisplayName": "Example User"
+ },
+ "CapMap": null
+}

docs/plans/v2/_files/internal/proxy/ctxguard_test.go

@@ -0,0 +1,142 @@
+package proxy_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+)
+
+// ctxUpstream is a fake router that reports a context size in /props and echoes completions.
+func ctxUpstream(t *testing.T, name string, nCtx, slots int) *upstream {
+	u := &upstream{name: name}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, `{"status":"ok"}`) })
+	mux.HandleFunc("/v1/models", func(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, `{"data":[{"id":"shared"}]}`) })
+	mux.HandleFunc("/props", func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprintf(w, `{"default_generation_settings":{"n_ctx":%d},"total_slots":%d}`, nCtx, slots)
+	})
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		u.hits.Add(1)
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprint(w, `{"choices":[{"message":{"role":"assistant","content":"ok"}}],"usage":{"prompt_tokens":1,"completion_tokens":1}}`)
+	})
+	u.srv = httptest.NewServer(mux)
+	t.Cleanup(u.srv.Close)
+	return u
+}
+
+const ctxHosts = `
+listen = "127.0.0.1:1"
+queue_max = 2
+[hosts.small]
+base_url = %q
+weight = 10.0
+models = { "shared" = { parallel = 2 } }
+[hosts.big]
+base_url = %q
+weight = 1.0
+models = { "shared" = { parallel = 1 } }
+[routes.r]
+hosts = ["small", "big"]
+default_model = "shared"
+`
+
+// bodyOfTokens builds a chat body whose byte size implies roughly n tokens under the guard's
+// estimate (bytes/4 × 1.2): n tokens ≈ 3.33 n bytes ≈ 2n/3 five-byte words.
+func bodyOfTokens(n int) string {
+	text := strings.Repeat("word ", n*2/3)
+	return fmt.Sprintf(`{"model":"shared","stream":false,"messages":[{"role":"user","content":"%s"}]}`, text)
+}
+
+func TestOversizedPromptMovesToAHostWhereItFits(t *testing.T) {
+	small := ctxUpstream(t, "small", 8192, 2) // 4096 per slot
+	big := ctxUpstream(t, "big", 131072, 1)   // 131072 per slot
+	r := newRig(t, ctxHosts, small, big)
+	// A small prompt starts on `small` (weight 10).
+	resp := r.post("/r/v1/chat/completions", bodyOfTokens(100))
+	drain(resp)
+	if resp.Header.Get(proxy.HostHeader) != "small" {
+		t.Fatalf("small prompt went to %q, want small", resp.Header.Get(proxy.HostHeader))
+	}
+	// A new conversation with ~10k tokens does not fit small's 4096-token slot: it must be
+	// placed on big, with the reason visible in a header.
+	resp = r.post("/r/v1/chat/completions", bodyOfTokens(10000))
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.HostHeader) != "big" {
+		t.Fatalf("oversized prompt: %d from %q, want 200 from big", resp.StatusCode, resp.Header.Get(proxy.HostHeader))
+	}
+	if got := resp.Header.Get(proxy.CtxHeader); !strings.HasPrefix(got, "moved") {
+		t.Errorf("%s = %q, want moved:… ", proxy.CtxHeader, got)
+	}
+}
+
+func TestOversizedPromptWithNoFitIs400(t *testing.T) {
+	small := ctxUpstream(t, "small", 8192, 2)
+	tiny := ctxUpstream(t, "big", 4096, 2) // also too small
+	r := newRig(t, ctxHosts, small, tiny)
+	resp := r.post("/r/v1/chat/completions", bodyOfTokens(10000))
+	body := drain(resp)
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("status %d body %s, want 400", resp.StatusCode, body)
+	}
+	var e map[string]any
+	if err := json.Unmarshal([]byte(body), &e); err != nil || e["error"] != "prompt too large" {
+		t.Fatalf("body = %s, want error 'prompt too large'", body)
+	}
+	if est, _ := e["estimate"].(float64); est < 8000 || est > 13000 {
+		t.Errorf("estimate = %v, want roughly 10000 tokens", e["estimate"])
+	}
+	if max, _ := e["max"].(float64); max != 4096 {
+		t.Errorf("max = %v, want the largest per-slot context among the route's hosts (4096)", e["max"])
+	}
+	if small.hits.Load()+tiny.hits.Load() != 0 {
+		t.Errorf("a refused prompt must not reach any upstream")
+	}
+}
+
+func TestUnknownContextNeverBlocks(t *testing.T) {
+	// /props missing on both hosts: NCtx 0 means "unknown", and the guard must stay out of the way.
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	resp := r.post("/r/v1/chat/completions", bodyOfTokens(50000))
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.CtxHeader) != "" {
+		t.Errorf("unknown context: %d %q, want 200 and no ctx header", resp.StatusCode, resp.Header.Get(proxy.CtxHeader))
+	}
+}
+
+func TestStickyLeaseSurvivesGrowthUntilItDoesNotFit(t *testing.T) {
+	small := ctxUpstream(t, "small", 8192, 2)
+	big := ctxUpstream(t, "big", 131072, 1)
+	r := newRig(t, ctxHosts, small, big)
+	body := bodyOfTokens(100)
+	resp := r.post("/r/v1/chat/completions", body)
+	drain(resp)
+	if resp.Header.Get(proxy.HostHeader) != "small" {
+		t.Fatal("setup: first turn must be on small")
+	}
+	// Same conversation (same first user message), later turn well under 4096: stays.
+	longer := strings.Replace(body, `"content":"`, `"content":"`+strings.Repeat("x ", 500), 1)
+	resp = r.post("/r/v1/chat/completions", longer)
+	drain(resp)
+	if resp.Header.Get(proxy.HostHeader) != "small" || resp.Header.Get(proxy.LeaseHeader) != "reused" {
+		t.Errorf("turn 2: %q %q, want small reused", resp.Header.Get(proxy.HostHeader), resp.Header.Get(proxy.LeaseHeader))
+	}
+	// A turn that outgrows the slot moves the lease — once — and the move is recorded as an event.
+	huge := strings.Replace(body, `"content":"`, `"content":"`+strings.Repeat("x ", 30000), 1)
+	resp = r.post("/r/v1/chat/completions", huge)
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.HostHeader) != "big" {
+		t.Fatalf("outgrown turn: %d %q, want 200 from big", resp.StatusCode, resp.Header.Get(proxy.HostHeader))
+	}
+	resp = r.post("/r/v1/chat/completions", huge)
+	drain(resp)
+	if resp.Header.Get(proxy.HostHeader) != "big" || resp.Header.Get(proxy.LeaseHeader) != "reused" {
+		t.Errorf("after the move the lease is on big: %q %q", resp.Header.Get(proxy.HostHeader), resp.Header.Get(proxy.LeaseHeader))
+	}
+}

docs/plans/v2/_files/internal/wake/wake_test.go

@@ -0,0 +1,114 @@
+package wake_test
+
+import (
+	"bytes"
+	"context"
+	"net"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/wake"
+)
+
+func listen(t *testing.T) (*net.UDPConn, string) {
+	conn, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { conn.Close() })
+	return conn, conn.LocalAddr().String()
+}
+
+func TestMagicPacket(t *testing.T) {
+	pkt, err := wake.MagicPacket("aa:bb:cc:dd:ee:ff")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(pkt) != 102 || !bytes.Equal(pkt[:6], bytes.Repeat([]byte{0xff}, 6)) {
+		t.Fatalf("packet = % x", pkt)
+	}
+	mac := []byte{0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}
+	for i := 0; i < 16; i++ {
+		if !bytes.Equal(pkt[6+6*i:12+6*i], mac) {
+			t.Fatalf("repetition %d wrong: % x", i, pkt[6+6*i:12+6*i])
+		}
+	}
+	for _, bad := range []string{"", "aa:bb", "zz:bb:cc:dd:ee:ff", "aabbccddeeff00"} {
+		if _, err := wake.MagicPacket(bad); err == nil {
+			t.Errorf("MagicPacket(%q) must fail", bad)
+		}
+	}
+	if p2, _ := wake.MagicPacket("AA-BB-CC-DD-EE-FF"); !bytes.Equal(p2, pkt) {
+		t.Errorf("dash-separated upper-case MAC must give the same packet")
+	}
+}
+
+func TestSendReachesTheBroadcastAddress(t *testing.T) {
+	conn, addr := listen(t)
+	if err := wake.Send("aa:bb:cc:dd:ee:ff", addr); err != nil {
+		t.Fatal(err)
+	}
+	buf := make([]byte, 200)
+	_ = conn.SetReadDeadline(time.Now().Add(time.Second))
+	n, _, err := conn.ReadFromUDP(buf)
+	if err != nil || n != 102 {
+		t.Fatalf("received %d bytes, err %v", n, err)
+	}
+	if err := wake.Send("aa:bb:cc:dd:ee:ff", "256.1.1.1:9"); err == nil {
+		t.Error("an unresolvable broadcast address must be an error")
+	}
+}
+
+// fakeHealth flips to healthy after `after` calls to Healthy.
+type fakeHealth struct{ calls, after int }
+
+func (f *fakeHealth) Healthy(name string) bool { f.calls++; return f.calls > f.after }
+
+func TestWakerSendsOncePerWindowAndWaitsForHealth(t *testing.T) {
+	conn, addr := listen(t)
+	h := &fakeHealth{after: 3}
+	w := wake.New(map[string]wake.Target{"titan": {MAC: "aa:bb:cc:dd:ee:ff", Broadcast: addr, Wait: 2 * time.Second}}, h)
+	w.PollEvery(20 * time.Millisecond) // test hook: how often Wake re-checks health
+	start := time.Now()
+	ok := w.Wake(context.Background(), "titan")
+	if !ok {
+		t.Fatal("Wake must return true once the host reports healthy")
+	}
+	if time.Since(start) > time.Second {
+		t.Errorf("Wake waited %v for a host that came up after 3 checks", time.Since(start))
+	}
+	_ = conn.SetReadDeadline(time.Now().Add(200 * time.Millisecond))
+	buf := make([]byte, 200)
+	if n, _, err := conn.ReadFromUDP(buf); err != nil || n != 102 {
+		t.Fatalf("no magic packet received: %d %v", n, err)
+	}
+	// A second Wake inside the same window does not send again (the host is booting).
+	_ = w.Wake(context.Background(), "titan")
+	_ = conn.SetReadDeadline(time.Now().Add(150 * time.Millisecond))
+	if n, _, err := conn.ReadFromUDP(buf); err == nil {
+		t.Errorf("a second packet (%d bytes) was sent inside the wait window", n)
+	}
+	if w.Wake(context.Background(), "nobody") {
+		t.Errorf("unknown host: Wake must return false")
+	}
+}
+
+func TestWakeGivesUpAfterWait(t *testing.T) {
+	_, addr := listen(t)
+	h := &fakeHealth{after: 1 << 30}
+	w := wake.New(map[string]wake.Target{"titan": {MAC: "aa:bb:cc:dd:ee:ff", Broadcast: addr, Wait: 300 * time.Millisecond}}, h)
+	w.PollEvery(20 * time.Millisecond)
+	start := time.Now()
+	if w.Wake(context.Background(), "titan") {
+		t.Fatal("Wake must return false when the host never comes up")
+	}
+	if d := time.Since(start); d < 250*time.Millisecond || d > 900*time.Millisecond {
+		t.Errorf("Wake returned after %v, want about the 300ms wait", d)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+	start = time.Now()
+	if w.Wake(ctx, "titan") || time.Since(start) > 200*time.Millisecond {
+		t.Errorf("a cancelled context must end the wait early (took %v)", time.Since(start))
+	}
+}

docs/plans/v2/_files/tools/smoke.sh

@@ -0,0 +1,58 @@
+#!/bin/sh
+# Smoke run (v2): everything v1 checked, plus the context guard, wake-on-LAN and identity gating.
+# Prints "smoke: ok" or fails with the crossbar log.
+set -eu
+cd "$(dirname "$0")/.."
+tmp=$(mktemp -d); trap 'kill $pids 2>/dev/null; rm -rf "$tmp"' EXIT INT TERM
+pids=""
+sed -e "s#^db .*#db = \"$tmp/crossbar.db\"#" -e 's#^identity .*#identity = "header"#' -e 's#^\# peers = \["talos"\]#peers = ["talos"]#' example.toml > "$tmp/crossbar.toml"
+# alpha: small context (4096 per slot = 8192/2); beta: large, sleeps until woken
+bin/fakeupstream -listen 127.0.0.1:18081 -name alpha -models ornith-1.5-35b-a3b,small-9b -down-file "$tmp/alpha.down" -slow 600 -n-ctx 8192 -slots 2 >"$tmp/alpha.log" 2>&1 & pids="$pids $!"
+bin/fakeupstream -listen 127.0.0.1:18082 -name beta  -models ornith-1.5-35b-a3b -down-file "$tmp/beta.down" -n-ctx 131072 -slots 2 -wol-listen 127.0.0.1:19082 -wol-mac aa:bb:cc:dd:ee:02 >"$tmp/beta.log" 2>&1 & pids="$pids $!"
+touch "$tmp/beta.down"                       # beta starts "asleep"
+bin/crossbar -config "$tmp/crossbar.toml" >"$tmp/crossbar.log" 2>&1 & pids="$pids $!"
+sleep 2.5                                    # two polls: alpha healthy, beta down
+fail() { echo "smoke: FAIL: $*" >&2; echo "--- crossbar.log"; cat "$tmp/crossbar.log"; exit 1; }
+base=http://127.0.0.1:17777
+conv() { printf '{"model":"ornith-1.5-35b-a3b","stream":false,"messages":[{"role":"system","content":"smoke"},{"role":"user","content":"conversation %s"}]}' "$1"; }
+big() { printf '{"model":"ornith-1.5-35b-a3b","stream":false,"messages":[{"role":"user","content":"%s"}]}' "$(head -c 40000 /dev/zero | tr '\0' 'x')"; }
+hdrs() { curl -s -o /dev/null -w '%{http_code} %header{X-Crossbar-Host} %header{X-Crossbar-Lease}' "$@"; }
+
+# 1. v1 behaviour: with beta asleep, opencode-a goes to alpha
+h=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv A)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 alpha new" ] || fail "with beta asleep conversation A should be '200 alpha new', got '$h'"
+curl -s "$base/_crossbar/hosts" | grep -q '"alpha":{[^}]*"n_ctx":8192' || fail "hosts view does not show alpha n_ctx 8192: $(curl -s $base/_crossbar/hosts)"
+
+# 2. context guard: a ~12k-token prompt does not fit alpha's 4096-token slot; beta is asleep and
+#    wakeable, so crossbar must send the magic packet, wait for beta, and place the prompt there.
+start=$(date +%s)
+h=$(hdrs -m 40 -X POST -H 'Content-Type: application/json' -d "$(big)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 beta new" ] || fail "oversized prompt should wake beta and land there, got '$h' after $(( $(date +%s) - start ))s"
+grep -q "magic packet received" "$tmp/beta.log" || fail "beta never saw a magic packet"
+curl -s "$base/_crossbar/hosts" | grep -q '"beta":{"healthy":true' || fail "beta not healthy after wake"
+
+# 3. with beta awake, a prompt that fits nowhere is a 400 (both slots too small? no — beta fits):
+#    check the guard's refusal with a prompt beyond beta's 65536-per-slot too
+h=$(curl -s -o "$tmp/toolarge.json" -w '%{http_code}' -X POST -H 'Content-Type: application/json' -d "$(printf '{"model":"ornith-1.5-35b-a3b","messages":[{"role":"user","content":"%s"}]}' "$(head -c 300000 /dev/zero | tr '\0' 'x')")" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "400" ] && grep -q '"prompt too large"' "$tmp/toolarge.json" || fail "300 KB prompt should be 400 prompt too large, got $h $(cat "$tmp/toolarge.json")"
+
+# 4. identity: hermes-x is locked to peer talos (header mode)
+h=$(curl -s -o /dev/null -w '%{http_code}' -X POST -H 'Content-Type: application/json' -d "$(conv B)" "$base/hermes-x/v1/chat/completions")
+[ "$h" = "403" ] || fail "hermes-x without a peer header should be 403, got $h"
+h=$(curl -s -o /dev/null -w '%{http_code}' -X POST -H 'Content-Type: application/json' -H 'X-Crossbar-Peer: titan' -d "$(conv B)" "$base/hermes-x/v1/chat/completions")
+[ "$h" = "403" ] || fail "hermes-x as titan should be 403, got $h"
+h=$(hdrs -X POST -H 'Content-Type: application/json' -H 'X-Crossbar-Peer: talos' -d "$(conv B)" "$base/hermes-x/v1/chat/completions")
+case "$h" in 200*) ;; *) fail "hermes-x as talos should be 200, got '$h'";; esac
+h=$(curl -s -o /dev/null -w '%{http_code}' "$base/_crossbar/hosts"); [ "$h" = "200" ] || fail "admin must not be gated, got $h"
+
+# 5. v1 regression: streaming still incremental, usage and metrics present
+start=$(date +%s%N)
+curl -sN -X POST -H 'Content-Type: application/json' -H 'X-Crossbar-Peer: talos' -d '{"model":"ornith-1.5-35b-a3b","stream":true,"messages":[{"role":"user","content":"stream me"}]}' \
+  "$base/hermes-x/v1/chat/completions" | while IFS= read -r line; do [ -n "$line" ] || continue; now=$(date +%s%N); echo "$(( (now - start) / 1000000 )) $line"; done > "$tmp/stream.txt"
+firstms=$(head -1 "$tmp/stream.txt" | cut -d' ' -f1); lastms=$(tail -1 "$tmp/stream.txt" | cut -d' ' -f1)
+[ -n "$firstms" ] && [ "$((lastms - firstms))" -ge 600 ] || fail "stream arrived in one burst"
+sleep 1
+curl -s "$base/_crossbar/usage?by=host" | grep -q '"cached_tokens":[1-9]' || fail "usage has no cached tokens"
+curl -s "$base/_crossbar/metrics" | grep -q 'crossbar_requests_total{route="hermes-x",host="beta",status="403"}' && fail "403s are refused before a lease and must not be counted as requests"
+curl -s "$base/_crossbar/metrics" | grep -q 'crossbar_host_healthy{host="beta"} 1' || fail "metrics missing beta health"
+echo "smoke: ok (stream spread $((lastms - firstms)) ms)"

example.toml

@@ -1,19 +1,23 @@
-# crossbar example configuration. Replace <tailnet> and the addresses with your own.
+# crossbar example configuration (v1). Replace <tailnet> and the addresses with your own.
 listen        = "127.0.0.1:17777"   # never 0.0.0.0 — bind the tailnet address in production
+db            = "crossbar.db"       # SQLite: leases + accounting (WAL). /var/lib/crossbar/crossbar.db under systemd
 poll_interval = "1s"                # 60s in production; 1s makes the smoke run quick
-queue_max     = 8
+lease_idle    = "30m"               # a conversation idle this long loses its host
+retention     = "180d"              # per-request rows older than this are rolled up daily
+queue_max     = 1                   # waiting places per (host, model) beyond `parallel`; 503 past that
 
 [hosts.alpha]
 base_url = "http://127.0.0.1:18081"    # e.g. http://straylight.<tailnet>:11434
 weight   = 1.0
-models   = { "ornith-1.5-35b-a3b" = { parallel = 4 }, "small-9b" = { parallel = 6 } }
+models   = { "ornith-1.5-35b-a3b" = { parallel = 1 }, "small-9b" = { parallel = 6 } }
 
 [hosts.beta]
 base_url = "http://127.0.0.1:18082"    # e.g. http://titan.<tailnet>:8081
 weight   = 2.0
-models   = { "ornith-1.5-35b-a3b" = { parallel = 4 } }
+models   = { "ornith-1.5-35b-a3b" = { parallel = 2 } }
 
-# v0: a route is a preference list; the first healthy host that has the model wins.
+# v1: a route is a set of candidate hosts; each conversation gets a sticky lease on the host with
+# the most free slots × weight at the time it starts. Pins and drains come from the admin API.
 [routes.opencode-a]
 hosts         = ["alpha", "beta"]
 default_model = "ornith-1.5-35b-a3b"

go.mod

@@ -2,4 +2,19 @@ module git.wntrmute.dev/kyle/crossbar
 
 go 1.26
 
-require github.com/BurntSushi/toml v1.6.0
+require (
+	github.com/BurntSushi/toml v1.6.0
+	modernc.org/sqlite v1.59.0
+)
+
+require (
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/mattn/go-isatty v0.0.24 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	modernc.org/libc v1.75.7 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.12.1 // indirect
+)

go.sum

@@ -1,2 +1,52 @@
-github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
 github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
+github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
+github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
+golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/tools v0.48.0/go.mod h1:08xX0orndb/F7jJxGDicx061tyd5pcMto75YMAXr6lk=
+golang.org/x/tools v0.48.0 h1:3+hClM1aLL5mjMKm5ovokw9epgRXPuu2tILgismM6RE=
+modernc.org/ccgo/v4 v4.35.0/go.mod h1:qrVGs9S3Sr2Ztcg9ve+kTAYMp5a3YvWjo+SoN06kJ5I=
+modernc.org/ccgo/v4 v4.35.0 h1:F+TUsmw09QxLzmi3aeYYGxjAXarmZaKgj3mKQHNaA8w=
+modernc.org/cc/v4 v4.29.2/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
+modernc.org/cc/v4 v4.29.2 h1:h6+9ciCnPKutf4I03CvheAvDLX7+IHlqR6Iy6J+cgd8=
+modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
+modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v3 v3.1.5/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/gc/v3 v3.1.5 h1:21ldfPfRYE31Tb7B3mwAK8gy1AxP4+dKjrOQPfqakoc=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/libc v1.75.7/go.mod h1:bO5o2ztHxBb2rjz0PgdHN0sSMw57CgxGFLZ3Qd/QpVQ=
+modernc.org/libc v1.75.7 h1:o3DTP9/0p9pKmY2WCKQaySW6wIiZhNM7wc2lUoyhfew=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/memory v1.12.1/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/memory v1.12.1 h1:nFMiWrpStgZczNl6XI9GnIk/rWhYIyHGUaR04pGbp9g=
+modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sqlite v1.59.0/go.mod h1:+paeT2A3iPRHkQDwG7oA6Tk0zQd5woMEI8q7orfry8k=
+modernc.org/sqlite v1.59.0 h1:X1es1GpqBlS/5T+vbM4HLUdaa8OtQx468DF2vrx+38A=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=

internal/admin/admin.go

@@ -1,15 +1,19 @@
-// Package admin serves the operator's view of crossbar: the health table and the routes as JSON,
-// mounted at /_crossbar/ on the same listener as the proxy. The shape of /_crossbar/hosts is
-// fixed so operators can read why a request went where it went.
+// Package admin serves the operator's view of crossbar: the hosts view with
+// slots and drain state, the routes view with leases and pins, the pin/release
+// and drain controls, usage accounting, and Prometheus metrics, all under
+// /_crossbar/.
 package admin
 
 import (
-	"encoding/json"
 	"net/http"
+	"sort"
 	"time"
 
 	"git.wntrmute.dev/kyle/crossbar/internal/config"
 	"git.wntrmute.dev/kyle/crossbar/internal/health"
+	"git.wntrmute.dev/kyle/crossbar/internal/lease"
+	"git.wntrmute.dev/kyle/crossbar/internal/limiter"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
 )
 
 // Hosts is what the admin handler needs from the health table.
@@ -17,59 +21,93 @@ type Hosts interface {
 	All() map[string]health.Status
 }
 
+// Drainer is what the admin handler needs to steer draining; *proxy.Hosts
+// satisfies it.
+type Drainer interface {
+	Draining(name string) bool
+	SetDraining(name string, on bool)
+}
+
+// HostView is one host's row in the hosts view.
 type HostView struct {
-	Healthy bool     `json:"healthy"`
-	Loaded  []string `json:"loaded"`  // never null: an empty slice when nothing is loaded
-	LastOK  string   `json:"last_ok"` // time.RFC3339 in UTC, or "" if never
-	LastErr string   `json:"last_err"`
+	Healthy   bool     `json:"healthy"`
+	Loaded    []string `json:"loaded"`  // never null
+	LastOK    string   `json:"last_ok"` // RFC 3339 UTC or ""
+	LastErr   string   `json:"last_err"`
+	FreeSlots int      `json:"free_slots"` // lim.FreeSlots(host)
+	InFlight  int      `json:"in_flight"`  // sum over the host's configured models
+	Queued    int      `json:"queued"`     // same
+	Draining  bool     `json:"draining"`
 }
 
+// LeaseView is one lease's row in a route's leases.
+type LeaseView struct {
+	FP       string `json:"fp"`
+	Model    string `json:"model"`
+	Host     string `json:"host"`
+	State    string `json:"state"`
+	Created  string `json:"created"`   // RFC 3339 UTC
+	LastUsed string `json:"last_used"` // RFC 3339 UTC
+}
+
+// RouteView is one route's row in the routes view.
 type RouteView struct {
-	Hosts        []string `json:"hosts"`
-	DefaultModel string   `json:"default_model"`
+	Hosts        []string    `json:"hosts"`
+	DefaultModel string      `json:"default_model"`
+	Pinned       string      `json:"pinned"` // "" when not pinned
+	Leases       []LeaseView `json:"leases"` // never null
 }
 
-// Handler serves GET /_crossbar/hosts and GET /_crossbar/routes. Any other method on those paths is
-// a 405 with an Allow: GET header; anything else under the handler is a 404.
-func Handler(cfg *config.Config, h Hosts) http.Handler {
+// handler implements the operator's endpoints under /_crossbar/.
+type handler struct {
+	cfg *config.Config
+	h   Hosts
+	lt  *lease.Table
+	lim *limiter.Limiter
+	st  *store.Store
+	d   Drainer
+}
+
+// Handler builds the operator's HTTP handler.
+func Handler(cfg *config.Config, h Hosts, lt *lease.Table, lim *limiter.Limiter, st *store.Store, d Drainer) http.Handler {
+	hx := &handler{cfg: cfg, h: h, lt: lt, lim: lim, st: st, d: d}
 	mux := http.NewServeMux()
-	mux.HandleFunc("/_crossbar/hosts", hostsHandler(h))
-	mux.HandleFunc("/_crossbar/routes", routesHandler(cfg))
-	mux.HandleFunc("/", notFound)
+	mux.HandleFunc("/_crossbar/hosts", hx.hostsGet)
+	mux.HandleFunc("/_crossbar/hosts/{host}", hx.hostDrain)
+	mux.HandleFunc("/_crossbar/routes", hx.routesGet)
+	mux.HandleFunc("/_crossbar/routes/{route}", hx.routePin)
+	mux.HandleFunc("/_crossbar/usage", hx.usageGet)
+	mux.HandleFunc("/_crossbar/metrics", hx.metricsGet)
+	mux.HandleFunc("/_crossbar/", hx.unknown)
 	return mux
 }
 
-func hostsHandler(h Hosts) http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		if r.Method != http.MethodGet {
-			wrongMethod(w)
-			return
-		}
-		views := make(map[string]HostView, len(h.All()))
-		for name, s := range h.All() {
-			views[name] = hostView(s)
-		}
-		writeJSON(w, http.StatusOK, views)
+func (hx *handler) hostsGet(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		wrongMethod(w, "GET")
+		return
 	}
+	writeJSON(w, http.StatusOK, hx.hostViews())
 }
 
-func routesHandler(cfg *config.Config) http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		if r.Method != http.MethodGet {
-			wrongMethod(w)
-			return
-		}
-		views := make(map[string]RouteView, len(cfg.Routes))
-		for name, route := range cfg.Routes {
-			hosts := make([]string, len(route.Hosts))
-			copy(hosts, route.Hosts)
-			views[name] = RouteView{Hosts: hosts, DefaultModel: route.DefaultModel}
-		}
-		writeJSON(w, http.StatusOK, views)
+// hostViews builds every host's row, keyed by host name.
+func (hx *handler) hostViews() map[string]HostView {
+	all := hx.h.All()
+	out := make(map[string]HostView, len(all))
+	for name, s := range all {
+		out[name] = hx.hostView(name, s)
 	}
+	return out
 }
 
-func hostView(s health.Status) HostView {
+// hostView builds one host's row: concurrency from the limiter summed over the
+// models the host serves, draining from the drainer, and the health snapshot.
+func (hx *handler) hostView(name string, s health.Status) HostView {
+	inflight, queued := 0, 0
+	for _, m := range configuredModels(hx.cfg, name) {
+		inflight += hx.lim.InFlight(name, m)
+		queued += hx.lim.Queued(name, m)
+	}
 	loaded := s.Loaded
 	if loaded == nil {
 		loaded = []string{}
@@ -79,24 +117,80 @@ func hostView(s health.Status) HostView {
 		lastOK = s.LastOK.UTC().Format(time.RFC3339)
 	}
 	return HostView{
-		Healthy: s.Healthy,
-		Loaded:  loaded,
-		LastOK:  lastOK,
-		LastErr: s.LastErr,
+		Healthy:   s.Healthy,
+		Loaded:    loaded,
+		LastOK:    lastOK,
+		LastErr:   s.LastErr,
+		FreeSlots: hx.lim.FreeSlots(name),
+		InFlight:  inflight,
+		Queued:    queued,
+		Draining:  hx.d.Draining(name),
 	}
 }
 
-func wrongMethod(w http.ResponseWriter) {
-	w.Header().Set("Allow", "GET")
-	writeJSON(w, http.StatusMethodNotAllowed, map[string]string{"error": "method not allowed"})
+// configuredModels returns the sorted model ids the host serves, or nil when
+// the host is unknown.
+func configuredModels(cfg *config.Config, name string) []string {
+	h, ok := cfg.Hosts[name]
+	if !ok {
+		return nil
+	}
+	models := make([]string, 0, len(h.Models))
+	for m := range h.Models {
+		models = append(models, m)
+	}
+	sort.Strings(models)
+	return models
 }
 
-func notFound(w http.ResponseWriter, r *http.Request) {
-	writeJSON(w, http.StatusNotFound, map[string]string{"error": "not found"})
+func (hx *handler) routesGet(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		wrongMethod(w, "GET")
+		return
+	}
+	snap := hx.lt.Snapshot()
+	views := make(map[string]RouteView, len(hx.cfg.Routes))
+	for name, route := range hx.cfg.Routes {
+		hosts := make([]string, len(route.Hosts))
+		copy(hosts, route.Hosts)
+		views[name] = hx.routeView(name, hosts, route.DefaultModel, snap)
+	}
+	writeJSON(w, http.StatusOK, views)
 }
 
-func writeJSON(w http.ResponseWriter, status int, v any) {
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(v)
+// routeView builds one route's row: the pinned host (empty if none) and the
+// active leases on it, in snapshot order.
+func (hx *handler) routeView(route string, hosts []string, defaultModel string, snap []lease.Lease) RouteView {
+	leases := make([]LeaseView, 0)
+	for _, l := range snap {
+		if l.Route == route {
+			leases = append(leases, leaseView(l))
+		}
+	}
+	return RouteView{
+		Hosts:        hosts,
+		DefaultModel: defaultModel,
+		Pinned:       hx.lt.Pinned(route),
+		Leases:       leases,
+	}
+}
+
+// leaseView maps a lease to its operator view.
+func leaseView(l lease.Lease) LeaseView {
+	return LeaseView{
+		FP:       l.FP,
+		Model:    l.Model,
+		Host:     l.Host,
+		State:    string(l.State),
+		Created:  formatTime(l.Created),
+		LastUsed: formatTime(l.LastUsed),
+	}
+}
+
+// formatTime renders t as RFC 3339 in UTC, or "" for the zero time.
+func formatTime(t time.Time) string {
+	if t.IsZero() {
+		return ""
+	}
+	return t.UTC().Format(time.RFC3339)
 }

internal/admin/admin_ops.go

@@ -0,0 +1,369 @@
+package admin
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+	"git.wntrmute.dev/kyle/crossbar/internal/lease"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+// routePin handles POST /_crossbar/routes/{route}: pin the route to a host or
+// release and unpin it.
+func (hx *handler) routePin(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		wrongMethod(w, "POST")
+		return
+	}
+	route := r.PathValue("route")
+	routeCfg, ok := hx.cfg.Routes[route]
+	if !ok {
+		writeError(w, http.StatusNotFound, "unknown route")
+		return
+	}
+
+	var raw struct {
+		Host    string `json:"host"`
+		Pin     *bool  `json:"pin"`
+		Release *bool  `json:"release"`
+	}
+	if err := decodeJSON(r, &raw); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid body")
+		return
+	}
+
+	pinSet := raw.Pin != nil
+	releaseSet := raw.Release != nil
+	switch {
+	case pinSet && releaseSet:
+		writeError(w, http.StatusBadRequest, "pin and release at once")
+	case !pinSet && !releaseSet:
+		writeError(w, http.StatusBadRequest, "pin or release required")
+	case pinSet:
+		hx.pin(w, route, routeCfg, raw.Host)
+	default:
+		hx.release(w, route)
+	}
+}
+
+// pin validates the host, records candidates, and pins the route.
+func (hx *handler) pin(w http.ResponseWriter, route string, routeCfg config.Route, host string) {
+	if host == "" {
+		writeError(w, http.StatusBadRequest, "pin requires host")
+		return
+	}
+	if !containsHost(routeCfg.Hosts, host) {
+		writeError(w, http.StatusNotFound, "host not in route")
+		return
+	}
+	// Record the route's hosts as candidates so Pin accepts a host no request
+	// has used yet.
+	hx.lt.Candidates(route, routeCfg.Hosts)
+	if err := hx.lt.Pin(route, host, time.Now()); err != nil {
+		if errors.Is(err, lease.ErrUnknownHost) {
+			writeError(w, http.StatusNotFound, "unknown host")
+			return
+		}
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]bool{"ok": true})
+}
+
+// release drops the route's leases and clears its pin.
+func (hx *handler) release(w http.ResponseWriter, route string) {
+	n := hx.lt.Release(route)
+	hx.lt.Unpin(route)
+	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "released": n})
+}
+
+// hostDrain handles POST /_crossbar/hosts/{host}: set or clear draining.
+func (hx *handler) hostDrain(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		wrongMethod(w, "POST")
+		return
+	}
+	host := r.PathValue("host")
+	if _, ok := hx.cfg.Hosts[host]; !ok {
+		writeError(w, http.StatusNotFound, "unknown host")
+		return
+	}
+	var body struct {
+		Drain *bool `json:"drain"`
+	}
+	if err := decodeJSON(r, &body); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid body")
+		return
+	}
+	if body.Drain == nil {
+		writeError(w, http.StatusBadRequest, "drain required")
+		return
+	}
+	hx.d.SetDraining(host, *body.Drain)
+	writeJSON(w, http.StatusOK, map[string]bool{"ok": true})
+}
+
+// usageGet handles GET /_crossbar/usage: usage rows as JSON, or a fixed-width
+// table when Accept is text/plain.
+func (hx *handler) usageGet(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		wrongMethod(w, "GET")
+		return
+	}
+	q := r.URL.Query()
+	var byv store.By
+	switch q.Get("by") {
+	case "", "route":
+		byv = store.ByRoute
+	case "model":
+		byv = store.ByModel
+	case "host":
+		byv = store.ByHost
+	default:
+		writeError(w, http.StatusBadRequest, "invalid by")
+		return
+	}
+	since, err := parseSince(q.Get("since"))
+	if err != nil {
+		writeError(w, http.StatusBadRequest, "invalid since")
+		return
+	}
+	rows, err := hx.st.Usage(since, byv)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "usage: "+err.Error())
+		return
+	}
+	if rows == nil {
+		rows = []store.UsageRow{}
+	}
+	if r.Header.Get("Accept") == "text/plain" {
+		writeUsageTable(w, rows)
+		return
+	}
+	writeJSON(w, http.StatusOK, rows)
+}
+
+// parseSince resolves the since query value: absent means all time, otherwise
+// an RFC 3339 instant or a duration (which may end in "d" for days) meaning
+// now - d.
+func parseSince(s string) (time.Time, error) {
+	if s == "" {
+		return time.Time{}, nil
+	}
+	if t, err := time.Parse(time.RFC3339, s); err == nil {
+		return t.UTC(), nil
+	}
+	d, err := parseWindow(s)
+	if err != nil {
+		return time.Time{}, err
+	}
+	return time.Now().Add(-d), nil
+}
+
+// parseWindow parses a duration, accepting a trailing "d" for whole days.
+func parseWindow(s string) (time.Duration, error) {
+	if n, ok := splitDays(s); ok {
+		return time.Duration(n) * 24 * time.Hour, nil
+	}
+	return time.ParseDuration(s)
+}
+
+// splitDays reports whether s is an integer number of days ("Nd").
+func splitDays(s string) (int, bool) {
+	if len(s) < 2 || s[len(s)-1] != 'd' {
+		return 0, false
+	}
+	n, err := strconv.Atoi(s[:len(s)-1])
+	if err != nil || n < 0 {
+		return 0, false
+	}
+	return n, true
+}
+
+// writeUsageTable renders the rows as a fixed-width table with a header line,
+// one row per entry, no trailing spaces.
+func writeUsageTable(w http.ResponseWriter, rows []store.UsageRow) {
+	headers := []string{"key", "requests", "errors", "busy_ms", "queued_ms", "prompt", "cached", "completion", "cache_hit"}
+	lines := make([][]string, 0, len(rows)+1)
+	lines = append(lines, headers)
+	for _, u := range rows {
+		lines = append(lines, []string{
+			u.Key,
+			strconv.FormatInt(u.Requests, 10),
+			strconv.FormatInt(u.Errors, 10),
+			strconv.FormatInt(u.BusyMs, 10),
+			strconv.FormatInt(u.QueuedMs, 10),
+			strconv.FormatInt(u.PromptTokens, 10),
+			strconv.FormatInt(u.CachedTokens, 10),
+			strconv.FormatInt(u.CompletionTokens, 10),
+			strconv.FormatFloat(u.CacheHitRatio(), 'f', 2, 64),
+		})
+	}
+	widths := columnWidths(lines)
+
+	var b strings.Builder
+	for _, line := range lines {
+		for i, f := range line {
+			if i < len(line)-1 {
+				b.WriteString(fmt.Sprintf("%-*s ", widths[i], f))
+			} else {
+				b.WriteString(f)
+			}
+		}
+		b.WriteByte('\n')
+	}
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte(b.String()))
+}
+
+// columnWidths returns the widest rendered field in each column.
+func columnWidths(lines [][]string) []int {
+	widths := make([]int, len(lines[0]))
+	for _, line := range lines {
+		for i, f := range line {
+			if len(f) > widths[i] {
+				widths[i] = len(f)
+			}
+		}
+	}
+	return widths
+}
+
+// metricsGet handles GET /_crossbar/metrics, emitting the Prometheus text
+// exposition format computed on request.
+func (hx *handler) metricsGet(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		wrongMethod(w, "GET")
+		return
+	}
+	counts, err := hx.st.StatusCounts(time.Time{})
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "metrics: "+err.Error())
+		return
+	}
+	usage, err := hx.st.Usage(time.Time{}, store.ByRoute)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "metrics: "+err.Error())
+		return
+	}
+
+	var reqSamples []string
+	for _, c := range counts {
+		reqSamples = append(reqSamples, fmt.Sprintf(
+			"crossbar_requests_total{route=\"%s\",host=\"%s\",status=\"%s\"} %d",
+			esc(c.Route), esc(c.Host), esc(strconv.Itoa(c.Status)), c.Count))
+	}
+
+	var prompt, cached, queue []string
+	for _, u := range usage {
+		prompt = append(prompt, fmt.Sprintf("crossbar_prompt_tokens_total{route=\"%s\"} %d", esc(u.Key), u.PromptTokens))
+		cached = append(cached, fmt.Sprintf("crossbar_cached_tokens_total{route=\"%s\"} %d", esc(u.Key), u.CachedTokens))
+		queue = append(queue, fmt.Sprintf("crossbar_queue_wait_ms_total{route=\"%s\"} %d", esc(u.Key), u.QueuedMs))
+	}
+
+	all := hx.h.All()
+	names := make([]string, 0, len(all))
+	for name := range all {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	var healthy, free, inflight, queued []string
+	for _, name := range names {
+		s := all[name]
+		healthy = append(healthy, fmt.Sprintf("crossbar_host_healthy{host=\"%s\"} %d", esc(name), btoi(s.Healthy)))
+		free = append(free, fmt.Sprintf("crossbar_host_free_slots{host=\"%s\"} %d", esc(name), hx.lim.FreeSlots(name)))
+		fi, q := 0, 0
+		for _, m := range configuredModels(hx.cfg, name) {
+			fi += hx.lim.InFlight(name, m)
+			q += hx.lim.Queued(name, m)
+		}
+		inflight = append(inflight, fmt.Sprintf("crossbar_host_in_flight{host=\"%s\"} %d", esc(name), fi))
+		queued = append(queued, fmt.Sprintf("crossbar_host_queued{host=\"%s\"} %d", esc(name), q))
+	}
+
+	var b strings.Builder
+	appendFamily(&b, "crossbar_requests_total", "counter", reqSamples)
+	appendFamily(&b, "crossbar_prompt_tokens_total", "counter", prompt)
+	appendFamily(&b, "crossbar_cached_tokens_total", "counter", cached)
+	appendFamily(&b, "crossbar_queue_wait_ms_total", "counter", queue)
+	appendFamily(&b, "crossbar_host_healthy", "gauge", healthy)
+	appendFamily(&b, "crossbar_host_free_slots", "gauge", free)
+	appendFamily(&b, "crossbar_host_in_flight", "gauge", inflight)
+	appendFamily(&b, "crossbar_host_queued", "gauge", queued)
+
+	w.Header().Set("Content-Type", "text/plain; version=0.0.4")
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte(b.String()))
+}
+
+// appendFamily writes a metric family: its TYPE line followed by the sorted
+// sample lines.
+func appendFamily(b *strings.Builder, name, typ string, samples []string) {
+	fmt.Fprintf(b, "# TYPE %s %s\n", name, typ)
+	sort.Strings(samples)
+	for _, s := range samples {
+		b.WriteString(s)
+		b.WriteByte('\n')
+	}
+}
+
+// esc escapes a label value for the Prometheus text format.
+func esc(s string) string {
+	s = strings.ReplaceAll(s, `\`, `\\`)
+	s = strings.ReplaceAll(s, `"`, `\"`)
+	return s
+}
+
+// btoi converts a bool to 0/1 for a gauge.
+func btoi(v bool) int {
+	if v {
+		return 1
+	}
+	return 0
+}
+
+// containsHost reports whether hosts contains h.
+func containsHost(hosts []string, h string) bool {
+	for _, x := range hosts {
+		if x == h {
+			return true
+		}
+	}
+	return false
+}
+
+// decodeJSON decodes a bounded JSON body.
+func decodeJSON(r *http.Request, v any) error {
+	dec := json.NewDecoder(io.LimitReader(r.Body, 4096))
+	return dec.Decode(v)
+}
+
+func writeJSON(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(v)
+}
+
+func writeError(w http.ResponseWriter, status int, msg string) {
+	writeJSON(w, status, map[string]string{"error": msg})
+}
+
+// wrongMethod answers 405 with the allowed method in the Allow header.
+func wrongMethod(w http.ResponseWriter, allow string) {
+	w.Header().Set("Allow", allow)
+	writeJSON(w, http.StatusMethodNotAllowed, map[string]string{"error": "method not allowed"})
+}
+
+func (hx *handler) unknown(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusNotFound, map[string]string{"error": "not found"})
+}

internal/admin/admin_test.go

@@ -1,9 +1,12 @@
 package admin_test
 
+// v1 admin: read the tables, pin/release a route, drain a host, usage rollups, metrics.
+
 import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
@@ -11,21 +14,45 @@ import (
 	"git.wntrmute.dev/kyle/crossbar/internal/admin"
 	"git.wntrmute.dev/kyle/crossbar/internal/config"
 	"git.wntrmute.dev/kyle/crossbar/internal/health"
+	"git.wntrmute.dev/kyle/crossbar/internal/lease"
+	"git.wntrmute.dev/kyle/crossbar/internal/limiter"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
 )
 
-type fakeHosts map[string]health.Status
+type fakeHosts struct {
+	st       map[string]health.Status
+	draining map[string]bool
+}
 
-func (f fakeHosts) All() map[string]health.Status { return f }
+func (f *fakeHosts) All() map[string]health.Status { return f.st }
+func (f *fakeHosts) Healthy(n string) bool         { return f.st[n].Healthy }
+func (f *fakeHosts) Draining(n string) bool        { return f.draining[n] }
+func (f *fakeHosts) SetDraining(n string, on bool) { f.draining[n] = on }
+func (f *fakeHosts) Choose(c []string, model string) (string, bool) {
+	for _, h := range c {
+		if f.st[h].Healthy && !f.draining[h] {
+			return h, true
+		}
+	}
+	return "", false
+}
 
-func testConfig(t *testing.T) *config.Config {
-	c, err := config.Parse(strings.NewReader(`
+type rig struct {
+	h      http.Handler
+	store  *store.Store
+	leases *lease.Table
+	hosts  *fakeHosts
+}
+
+func newRig(t *testing.T) *rig {
+	cfg, err := config.Parse(strings.NewReader(`
 listen = "127.0.0.1:1"
 [hosts.alpha]
 base_url = "http://alpha:1"
-models = { "m" = { } }
+models = { "m" = { parallel = 2 } }
 [hosts.beta]
 base_url = "http://beta:1"
-models = { "m" = { } }
+models = { "m" = { parallel = 4 } }
 [routes.r]
 hosts = ["alpha", "beta"]
 default_model = "m"
@@ -33,67 +60,234 @@ default_model = "m"
 	if err != nil {
 		t.Fatal(err)
 	}
-	return c
+	st, err := store.Open(filepath.Join(t.TempDir(), "x.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	hosts := &fakeHosts{
+		st: map[string]health.Status{
+			"alpha": {Healthy: true, Loaded: []string{"m"}, LastOK: time.Date(2026, 9, 25, 8, 0, 0, 0, time.UTC)},
+			"beta":  {Healthy: false, LastErr: "HTTP 503"},
+		},
+		draining: map[string]bool{},
+	}
+	lt, err := lease.New(st, hosts, hosts, 30*time.Minute)
+	if err != nil {
+		t.Fatal(err)
+	}
+	lim := limiter.New()
+	lim.Configure("alpha", "m", 2, 8)
+	lim.Configure("beta", "m", 4, 8)
+	return &rig{h: admin.Handler(cfg, hosts, lt, lim, st, hosts), store: st, leases: lt, hosts: hosts}
 }
 
-func TestHosts(t *testing.T) {
-	when := time.Date(2026, 9, 25, 8, 0, 0, 0, time.UTC)
-	h := admin.Handler(testConfig(t), fakeHosts{
-		"alpha": {Healthy: true, Loaded: []string{"m"}, LastOK: when},
-		"beta":  {Healthy: false, LastErr: "HTTP 503"},
-	})
+func (r *rig) do(t *testing.T, method, path, body string, hdr ...string) *httptest.ResponseRecorder {
+	req := httptest.NewRequest(method, path, strings.NewReader(body))
+	if body != "" {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	for i := 0; i+1 < len(hdr); i += 2 {
+		req.Header.Set(hdr[i], hdr[i+1])
+	}
 	rec := httptest.NewRecorder()
-	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/_crossbar/hosts", nil))
-	if rec.Code != 200 || !strings.HasPrefix(rec.Header().Get("Content-Type"), "application/json") {
-		t.Fatalf("status %d, content-type %q", rec.Code, rec.Header().Get("Content-Type"))
+	r.h.ServeHTTP(rec, req)
+	return rec
+}
+
+func TestHostsShowsSlotsAndDrain(t *testing.T) {
+	r := newRig(t)
+	rec := r.do(t, "GET", "/_crossbar/hosts", "")
+	if rec.Code != 200 {
+		t.Fatalf("%d %s", rec.Code, rec.Body.String())
 	}
 	var out map[string]admin.HostView
 	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
 		t.Fatal(err)
 	}
-	if a := out["alpha"]; !a.Healthy || len(a.Loaded) != 1 || a.LastOK != "2026-09-25T08:00:00Z" || a.LastErr != "" {
+	a := out["alpha"]
+	if !a.Healthy || a.FreeSlots != 2 || a.InFlight != 0 || a.Queued != 0 || a.Draining || a.LastOK != "2026-09-25T08:00:00Z" {
 		t.Errorf("alpha = %+v", a)
 	}
-	if b := out["beta"]; b.Healthy || b.LastOK != "" || b.LastErr != "HTTP 503" || b.Loaded == nil {
+	if b := out["beta"]; b.Healthy || b.LastErr != "HTTP 503" || b.FreeSlots != 4 || b.Loaded == nil {
 		t.Errorf("beta = %+v (loaded must be [] not null)", b)
 	}
-	if !strings.Contains(rec.Body.String(), `"loaded":[]`) {
-		t.Errorf("beta.loaded must encode as []: %s", rec.Body.String())
-	}
 }
 
-func TestRoutes(t *testing.T) {
-	h := admin.Handler(testConfig(t), fakeHosts{})
-	rec := httptest.NewRecorder()
-	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/_crossbar/routes", nil))
+func TestRoutesShowsLeases(t *testing.T) {
+	r := newRig(t)
+	now := time.Date(2026, 9, 25, 9, 0, 0, 0, time.UTC)
+	if _, _, err := r.leases.Acquire(lease.Key{Route: "r", FP: "abc", Model: "m"}, []string{"alpha", "beta"}, now); err != nil {
+		t.Fatal(err)
+	}
+	rec := r.do(t, "GET", "/_crossbar/routes", "")
 	var out map[string]admin.RouteView
 	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
 		t.Fatalf("%v: %s", err, rec.Body.String())
 	}
-	r := out["r"]
-	if len(r.Hosts) != 2 || r.Hosts[0] != "alpha" || r.DefaultModel != "m" {
-		t.Errorf("routes = %+v", out)
+	rv := out["r"]
+	if len(rv.Hosts) != 2 || rv.DefaultModel != "m" || rv.Pinned != "" {
+		t.Errorf("route view = %+v", rv)
+	}
+	if len(rv.Leases) != 1 || rv.Leases[0].FP != "abc" || rv.Leases[0].Host != "alpha" || rv.Leases[0].State != "active" || rv.Leases[0].LastUsed != "2026-09-25T09:00:00Z" {
+		t.Errorf("leases = %+v", rv.Leases)
+	}
+}
+
+func TestPinReleaseDrain(t *testing.T) {
+	r := newRig(t)
+	rec := r.do(t, "POST", "/_crossbar/routes/r", `{"host":"beta","pin":true}`)
+	if rec.Code != 200 {
+		t.Fatalf("pin: %d %s", rec.Code, rec.Body.String())
+	}
+	if h, _, err := r.leases.Acquire(lease.Key{Route: "r", FP: "x", Model: "m"}, []string{"alpha", "beta"}, time.Now()); err == nil || h != "" {
+		// beta is unhealthy in the rig: a pin to a down host is honoured, not silently moved
+		t.Errorf("acquire on a route pinned to a down host: %q %v, want ErrPinnedDown", h, err)
+	}
+	rec = r.do(t, "GET", "/_crossbar/routes", "")
+	var out map[string]admin.RouteView
+	_ = json.Unmarshal(rec.Body.Bytes(), &out)
+	if out["r"].Pinned != "beta" {
+		t.Errorf("Pinned = %q after pin", out["r"].Pinned)
+	}
+	rec = r.do(t, "POST", "/_crossbar/routes/r", `{"release":true}`)
+	if rec.Code != 200 {
+		t.Fatalf("release: %d %s", rec.Code, rec.Body.String())
+	}
+	if h, _, err := r.leases.Acquire(lease.Key{Route: "r", FP: "x", Model: "m"}, []string{"alpha", "beta"}, time.Now()); err != nil || h != "alpha" {
+		t.Errorf("after release: %q %v, want alpha (the only healthy host)", h, err)
+	}
+	for _, tc := range []struct {
+		body string
+		want int
+	}{
+		{`{"host":"nobody","pin":true}`, 404},
+		{`{"pin":true}`, 400},
+		{`not json`, 400},
+		{`{"release":true,"pin":true,"host":"alpha"}`, 400},
+	} {
+		if rec := r.do(t, "POST", "/_crossbar/routes/r", tc.body); rec.Code != tc.want {
+			t.Errorf("POST %s: %d, want %d (%s)", tc.body, rec.Code, tc.want, rec.Body.String())
+		}
+	}
+	if rec := r.do(t, "POST", "/_crossbar/routes/nope", `{"release":true}`); rec.Code != 404 {
+		t.Errorf("unknown route: %d", rec.Code)
+	}
+
+	rec = r.do(t, "POST", "/_crossbar/hosts/alpha", `{"drain":true}`)
+	if rec.Code != 200 || !r.hosts.Draining("alpha") {
+		t.Fatalf("drain: %d %s draining=%v", rec.Code, rec.Body.String(), r.hosts.Draining("alpha"))
+	}
+	rec = r.do(t, "GET", "/_crossbar/hosts", "")
+	var hv map[string]admin.HostView
+	_ = json.Unmarshal(rec.Body.Bytes(), &hv)
+	if !hv["alpha"].Draining {
+		t.Errorf("hosts view must show draining")
+	}
+	if rec := r.do(t, "POST", "/_crossbar/hosts/alpha", `{"drain":false}`); rec.Code != 200 || r.hosts.Draining("alpha") {
+		t.Errorf("undrain: %d draining=%v", rec.Code, r.hosts.Draining("alpha"))
+	}
+	if rec := r.do(t, "POST", "/_crossbar/hosts/nobody", `{"drain":true}`); rec.Code != 404 {
+		t.Errorf("unknown host: %d", rec.Code)
+	}
+}
+
+func seedUsage(t *testing.T, st *store.Store) {
+	t0 := time.Now().UTC().Add(-time.Hour)
+	for i, r := range []store.Request{
+		{Route: "r", FP: "a", Model: "m", Host: "alpha", Status: 200, TotalMs: 1000, PromptTokens: 100, CachedTokens: 80, CompletionTokens: 10},
+		{Route: "r", FP: "a", Model: "m", Host: "alpha", Status: 200, TotalMs: 500, QueuedMs: 30, PromptTokens: 100, CachedTokens: 100, CompletionTokens: 5},
+		{Route: "r2", FP: "b", Model: "m", Host: "beta", Status: 503, TotalMs: 1, Err: "queue full"},
+	} {
+		r.Started = t0.Add(time.Duration(i) * time.Minute)
+		if err := st.RecordRequest(r); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func TestUsageJSONAndText(t *testing.T) {
+	r := newRig(t)
+	seedUsage(t, r.store)
+	rec := r.do(t, "GET", "/_crossbar/usage?by=route", "")
+	if rec.Code != 200 || !strings.HasPrefix(rec.Header().Get("Content-Type"), "application/json") {
+		t.Fatalf("%d %q", rec.Code, rec.Header().Get("Content-Type"))
+	}
+	var rows []store.UsageRow
+	if err := json.Unmarshal(rec.Body.Bytes(), &rows); err != nil {
+		t.Fatalf("%v: %s", err, rec.Body.String())
+	}
+	if len(rows) != 2 {
+		t.Fatalf("rows = %+v", rows)
+	}
+	for _, row := range rows {
+		if row.Key == "r" && (row.Requests != 2 || row.CachedTokens != 180 || row.QueuedMs != 30) {
+			t.Errorf("r = %+v", row)
+		}
+		if row.Key == "r2" && (row.Requests != 1 || row.Errors != 1) {
+			t.Errorf("r2 = %+v", row)
+		}
+	}
+	rec = r.do(t, "GET", "/_crossbar/usage?by=host&since=24h", "", "Accept", "text/plain")
+	if rec.Code != 200 || !strings.HasPrefix(rec.Header().Get("Content-Type"), "text/plain") {
+		t.Fatalf("text: %d %q", rec.Code, rec.Header().Get("Content-Type"))
+	}
+	body := rec.Body.String()
+	if !strings.Contains(body, "alpha") || !strings.Contains(body, "beta") || !strings.Contains(strings.ToLower(body), "cache") {
+		t.Errorf("text table = %q", body)
+	}
+	if rec := r.do(t, "GET", "/_crossbar/usage?by=colour", ""); rec.Code != 400 {
+		t.Errorf("bad by: %d", rec.Code)
+	}
+	if rec := r.do(t, "GET", "/_crossbar/usage?since=yesterday", ""); rec.Code != 400 {
+		t.Errorf("bad since: %d", rec.Code)
+	}
+	rec = r.do(t, "GET", "/_crossbar/usage?since=2026-09-25T00:00:00Z&by=model", "")
+	if rec.Code != 200 {
+		t.Errorf("RFC3339 since: %d %s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestMetrics(t *testing.T) {
+	r := newRig(t)
+	seedUsage(t, r.store)
+	rec := r.do(t, "GET", "/_crossbar/metrics", "")
+	if rec.Code != 200 || !strings.HasPrefix(rec.Header().Get("Content-Type"), "text/plain") {
+		t.Fatalf("%d %q", rec.Code, rec.Header().Get("Content-Type"))
+	}
+	body := rec.Body.String()
+	for _, want := range []string{
+		`# TYPE crossbar_requests_total counter`,
+		`crossbar_requests_total{route="r",host="alpha",status="200"} 2`,
+		`crossbar_requests_total{route="r2",host="beta",status="503"} 1`,
+		`crossbar_host_healthy{host="alpha"} 1`,
+		`crossbar_host_healthy{host="beta"} 0`,
+		`crossbar_host_free_slots{host="alpha"} 2`,
+		`crossbar_prompt_tokens_total{route="r"} 200`,
+		`crossbar_cached_tokens_total{route="r"} 180`,
+		`crossbar_queue_wait_ms_total{route="r"} 30`,
+	} {
+		if !strings.Contains(body, want) {
+			t.Errorf("metrics missing %q\n%s", want, body)
+		}
 	}
 }
 
 func TestMethodsAndUnknown(t *testing.T) {
-	h := admin.Handler(testConfig(t), fakeHosts{})
+	r := newRig(t)
 	for _, tc := range []struct {
 		method, path string
 		want         int
 	}{
 		{http.MethodPost, "/_crossbar/hosts", 405},
 		{http.MethodDelete, "/_crossbar/routes", 405},
+		{http.MethodGet, "/_crossbar/routes/r", 405},
 		{http.MethodGet, "/_crossbar/nope", 404},
-		{http.MethodGet, "/_crossbar/", 404},
+		{http.MethodPut, "/_crossbar/usage", 405},
 	} {
-		rec := httptest.NewRecorder()
-		h.ServeHTTP(rec, httptest.NewRequest(tc.method, tc.path, nil))
-		if rec.Code != tc.want {
-			t.Errorf("%s %s = %d, want %d", tc.method, tc.path, rec.Code, tc.want)
-		}
-		if !strings.HasPrefix(rec.Header().Get("Content-Type"), "application/json") {
-			t.Errorf("%s %s: errors are JSON too", tc.method, tc.path)
+		rec := r.do(t, tc.method, tc.path, "")
+		if rec.Code != tc.want || !strings.HasPrefix(rec.Header().Get("Content-Type"), "application/json") {
+			t.Errorf("%s %s = %d %q, want %d JSON", tc.method, tc.path, rec.Code, rec.Header().Get("Content-Type"), tc.want)
 		}
 	}
 }

internal/admin/usage_empty_test.go

@@ -0,0 +1,31 @@
+package admin_test
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+// An empty usage table is an empty JSON array, not null: clients iterate it.
+func TestUsageEmptyIsAnArray(t *testing.T) {
+	r := newRig(t)
+	for _, q := range []string{"/_crossbar/usage", "/_crossbar/usage?by=host", "/_crossbar/usage?by=model&since=1h"} {
+		rec := r.do(t, "GET", q, "")
+		if rec.Code != 200 {
+			t.Fatalf("%s: %d", q, rec.Code)
+		}
+		if strings.TrimSpace(rec.Body.String()) != "[]" {
+			t.Errorf("%s: body %q, want []", q, rec.Body.String())
+		}
+		var rows []store.UsageRow
+		if err := json.Unmarshal(rec.Body.Bytes(), &rows); err != nil || rows == nil || len(rows) != 0 {
+			t.Errorf("%s: decoded %v %v, want an empty non-nil slice", q, rows, err)
+		}
+	}
+	rec := r.do(t, "GET", "/_crossbar/usage?by=route", "", "Accept", "text/plain")
+	if rec.Code != 200 || !strings.Contains(rec.Body.String(), "key") {
+		t.Errorf("text form with no rows must still print the header: %d %q", rec.Code, rec.Body.String())
+	}
+}

internal/choose/choose.go

@@ -0,0 +1,63 @@
+// Package choose picks the host for a new lease: among the healthy, non-draining, known hosts it
+// prefers those that have the model loaded over those that would only be able to serve it, then the
+// one with the most free slots times weight, breaking ties by shortest queue and finally list
+// order.
+package choose
+
+// Info is one candidate host's view of itself for a single model.
+type Info struct {
+	Healthy  bool // answered its last poll
+	Draining bool // operator is draining it; no new leases
+	Loaded   bool // the model is resident here
+	CanServe bool // config lists the model, so we may load it
+	Free     int
+	Queued   int
+	Weight   float64
+}
+
+// Best returns the best host for a new lease, or ok=false when nothing is eligible. It runs two
+// passes over the candidates in order: the first over those that have the model loaded, the second,
+// only if the first found nothing, over those that can serve it. A host must be healthy, not
+// draining, and known (info reported ok) to be eligible in either pass; a host with zero free slots
+// is still eligible, since it will queue. Among the eligible ones the highest Free*Weight wins, ties
+// go to the lowest queue, and a remaining tie keeps the earlier candidate.
+func Best(candidates []string, info func(host string) (Info, bool)) (string, bool) {
+	const (
+		passLoaded   = 0
+		passCanServe = 1
+	)
+	best := ""
+	var (
+		bestScore  float64
+		bestQueued int
+		found      bool
+	)
+	for pass := passLoaded; pass <= passCanServe; pass++ {
+		for _, host := range candidates {
+			v, ok := info(host)
+			if !ok || !v.Healthy || v.Draining {
+				continue
+			}
+			switch pass {
+			case passLoaded:
+				if !v.Loaded {
+					continue
+				}
+			case passCanServe:
+				if !v.CanServe {
+					continue
+				}
+			}
+			score := float64(v.Free) * v.Weight
+			// Replace only when strictly better on score, or equal score with a shorter queue; a
+			// further tie keeps the earlier candidate because we scan in order and use "<".
+			if !found || score > bestScore || (score == bestScore && v.Queued < bestQueued) {
+				best, bestScore, bestQueued, found = host, score, v.Queued, true
+			}
+		}
+		if found {
+			break
+		}
+	}
+	return best, found
+}

internal/choose/choose_test.go

@@ -0,0 +1,83 @@
+package choose_test
+
+import (
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/choose"
+)
+
+func infoFor(m map[string]choose.Info) func(string) (choose.Info, bool) {
+	return func(name string) (choose.Info, bool) { i, ok := m[name]; return i, ok }
+}
+
+func TestMostFreeSlotsTimesWeightWins(t *testing.T) {
+	info := infoFor(map[string]choose.Info{
+		"alpha": {Healthy: true, Loaded: true, CanServe: true, Free: 3, Weight: 1.0},
+		"beta":  {Healthy: true, Loaded: true, CanServe: true, Free: 2, Weight: 2.0}, // 4 > 3
+		"gamma": {Healthy: true, Loaded: true, CanServe: true, Free: 4, Weight: 0.5}, // 2
+	})
+	got, ok := choose.Best([]string{"alpha", "beta", "gamma"}, info)
+	if !ok || got != "beta" {
+		t.Errorf("got %q %v, want beta", got, ok)
+	}
+}
+
+func TestTieGoesToShortestQueueThenListOrder(t *testing.T) {
+	info := infoFor(map[string]choose.Info{
+		"alpha": {Healthy: true, Loaded: true, CanServe: true, Free: 2, Weight: 1, Queued: 3},
+		"beta":  {Healthy: true, Loaded: true, CanServe: true, Free: 2, Weight: 1, Queued: 1},
+		"gamma": {Healthy: true, Loaded: true, CanServe: true, Free: 2, Weight: 1, Queued: 1},
+	})
+	if got, _ := choose.Best([]string{"alpha", "beta", "gamma"}, info); got != "beta" {
+		t.Errorf("tie on score: shortest queue wins, then list order; got %q", got)
+	}
+	if got, _ := choose.Best([]string{"gamma", "beta"}, info); got != "gamma" {
+		t.Errorf("full tie: first in list order wins; got %q", got)
+	}
+}
+
+func TestLoadedBeatsMerelyCapable(t *testing.T) {
+	info := infoFor(map[string]choose.Info{
+		"alpha": {Healthy: true, Loaded: false, CanServe: true, Free: 8, Weight: 4},
+		"beta":  {Healthy: true, Loaded: true, CanServe: true, Free: 1, Weight: 1},
+	})
+	got, ok := choose.Best([]string{"alpha", "beta"}, info)
+	if !ok || got != "beta" {
+		t.Errorf("a host that has the model loaded wins over one that would have to load it; got %q", got)
+	}
+}
+
+func TestFallsBackToCapableHost(t *testing.T) {
+	info := infoFor(map[string]choose.Info{
+		"alpha": {Healthy: true, Loaded: false, CanServe: true, Free: 1, Weight: 1},
+		"beta":  {Healthy: true, Loaded: false, CanServe: false, Free: 9, Weight: 9},
+	})
+	got, ok := choose.Best([]string{"beta", "alpha"}, info)
+	if !ok || got != "alpha" {
+		t.Errorf("only a host configured to serve the model may load it; got %q %v", got, ok)
+	}
+}
+
+func TestSkipsUnhealthyDrainingUnknownAndFull(t *testing.T) {
+	info := infoFor(map[string]choose.Info{
+		"down":  {Healthy: false, Loaded: true, CanServe: true, Free: 9, Weight: 9},
+		"drain": {Healthy: true, Draining: true, Loaded: true, CanServe: true, Free: 9, Weight: 9},
+		"full":  {Healthy: true, Loaded: true, CanServe: true, Free: 0, Weight: 9, Queued: 0},
+		"ok":    {Healthy: true, Loaded: true, CanServe: true, Free: 1, Weight: 1},
+	})
+	got, ok := choose.Best([]string{"down", "drain", "missing", "full", "ok"}, info)
+	if !ok || got != "ok" {
+		t.Errorf("got %q %v, want ok", got, ok)
+	}
+	// A full host is still better than nothing: it gets the request (it will queue).
+	got, ok = choose.Best([]string{"down", "full"}, info)
+	if !ok || got != "full" {
+		t.Errorf("with only a full host left it must still be chosen; got %q %v", got, ok)
+	}
+	if _, ok := choose.Best([]string{"down", "drain", "missing"}, info); ok {
+		t.Errorf("nothing usable must give ok=false")
+	}
+	if _, ok := choose.Best(nil, info); ok {
+		t.Errorf("empty candidates must give ok=false")
+	}
+}

internal/config/config.go

@@ -15,18 +15,25 @@ import (
 	"os"
 	"regexp"
 	"sort"
+	"strconv"
 	"strings"
 	"time"
 
 	"github.com/BurntSushi/toml"
 )
 
-// Duration is a time.Duration that TOML reads from a string such as "60s" or
-// "30m".
+// Duration is a time.Duration that TOML reads from a string such as "60s",
+// "30m", or "7d" (an integer number of days).
 type Duration struct{ time.Duration }
 
-// UnmarshalText implements encoding.TextUnmarshaler via time.ParseDuration.
+// UnmarshalText implements encoding.TextUnmarshaler. It accepts the "Nd" form
+// — an integer number of days, so "7d" is 7 × 24h — in addition to
+// time.ParseDuration syntax.
 func (d *Duration) UnmarshalText(text []byte) error {
+	if days, ok := parseDays(text); ok {
+		d.Duration = days
+		return nil
+	}
 	dt, err := time.ParseDuration(string(text))
 	if err != nil {
 		return err
@@ -35,6 +42,22 @@ func (d *Duration) UnmarshalText(text []byte) error {
 	return nil
 }
 
+// dayPattern matches a run of digits followed by "d", e.g. "7d".
+var dayPattern = regexp.MustCompile(`^[0-9]+d$`)
+
+// parseDays reports whether text is the "Nd" day form and returns that many
+// hours. The regex guarantees the prefix is a base-10 integer.
+func parseDays(text []byte) (time.Duration, bool) {
+	if !dayPattern.MatchString(string(text)) {
+		return 0, false
+	}
+	n, err := strconv.Atoi(string(text[:len(text)-1]))
+	if err != nil {
+		return 0, false
+	}
+	return time.Duration(n) * 24 * time.Hour, true
+}
+
 // Model is the per-model tuning carried by a host entry.
 type Model struct {
 	Parallel int `toml:"parallel"`
@@ -58,6 +81,9 @@ type Config struct {
 	Listen       string           `toml:"listen"`
 	PollInterval Duration         `toml:"poll_interval"`
 	QueueMax     int              `toml:"queue_max"`
+	DB           string           `toml:"db"`
+	LeaseIdle    Duration         `toml:"lease_idle"`
+	Retention    Duration         `toml:"retention"`
 	Hosts        map[string]Host  `toml:"hosts"`
 	Routes       map[string]Route `toml:"routes"`
 }
@@ -76,6 +102,13 @@ const (
 	DefaultPollInterval = 60 * time.Second
 	DefaultQueueMax     = 8
 	MinPollInterval     = time.Second
+
+	DefaultDB        = "crossbar.db"
+	DefaultLeaseIdle = 30 * time.Minute
+	DefaultRetention = 180 * 24 * time.Hour
+
+	MinLeaseIdle = time.Minute
+	MinRetention = 24 * time.Hour
 )
 
 var routeName = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
@@ -109,6 +142,15 @@ func Parse(r io.Reader) (*Config, error) {
 		return nil, &Error{Field: keys[0], Msg: "unknown key"}
 	}
 
+	if !md.IsDefined("db") {
+		c.DB = DefaultDB
+	}
+	if !md.IsDefined("lease_idle") {
+		c.LeaseIdle.Duration = DefaultLeaseIdle
+	}
+	if !md.IsDefined("retention") {
+		c.Retention.Duration = DefaultRetention
+	}
 	if c.PollInterval.Duration == 0 {
 		c.PollInterval.Duration = DefaultPollInterval
 	}
@@ -152,6 +194,15 @@ func (c *Config) validate() *Error {
 	if e := c.checkQueue(); e != nil {
 		return e
 	}
+	if e := c.checkDB(); e != nil {
+		return e
+	}
+	if e := c.checkLeaseIdle(); e != nil {
+		return e
+	}
+	if e := c.checkRetention(); e != nil {
+		return e
+	}
 	if e := c.checkHosts(); e != nil {
 		return e
 	}
@@ -193,6 +244,27 @@ func (c *Config) checkQueue() *Error {
 	return nil
 }
 
+func (c *Config) checkDB() *Error {
+	if c.DB == "" {
+		return &Error{Field: "db", Msg: "required"}
+	}
+	return nil
+}
+
+func (c *Config) checkLeaseIdle() *Error {
+	if c.LeaseIdle.Duration < MinLeaseIdle {
+		return &Error{Field: "lease_idle", Msg: "must be at least 1m"}
+	}
+	return nil
+}
+
+func (c *Config) checkRetention() *Error {
+	if c.Retention.Duration < MinRetention {
+		return &Error{Field: "retention", Msg: "must be at least 1d"}
+	}
+	return nil
+}
+
 func (c *Config) checkHosts() *Error {
 	if len(c.Hosts) == 0 {
 		return &Error{Field: "hosts", Msg: "at least one required"}

internal/config/config_test.go

@@ -81,7 +81,7 @@ func TestBadFiles(t *testing.T) {
 		{"bad-listen.toml", "listen"},
 		{"bad-unknown-host.toml", "routes.r.hosts"},
 		{"bad-default-model.toml", "routes.r.default_model"},
-		{"bad-unknown-key.toml", "lease_idle"},
+		{"bad-unknown-key.toml", "bogus_key"},
 	}
 	for _, tc := range cases {
 		t.Run(tc.file, func(t *testing.T) {

internal/config/config_v1_test.go

@@ -0,0 +1,81 @@
+package config_test
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+)
+
+const v1Base = `
+listen = "127.0.0.1:1"
+[hosts.a]
+base_url = "http://a:1"
+models = { "m" = { } }
+[routes.r]
+hosts = ["a"]
+`
+
+func TestV1Defaults(t *testing.T) {
+	c, err := config.Parse(strings.NewReader(v1Base))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.DB != "crossbar.db" {
+		t.Errorf("DB default = %q", c.DB)
+	}
+	if c.LeaseIdle.Duration != 30*time.Minute {
+		t.Errorf("LeaseIdle default = %v", c.LeaseIdle.Duration)
+	}
+	if c.Retention.Duration != 180*24*time.Hour {
+		t.Errorf("Retention default = %v", c.Retention.Duration)
+	}
+}
+
+func TestV1Values(t *testing.T) {
+	c, err := config.Parse(strings.NewReader(`
+db = "/var/lib/crossbar/crossbar.db"
+lease_idle = "45m"
+retention = "30d"
+` + v1Base))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.DB != "/var/lib/crossbar/crossbar.db" || c.LeaseIdle.Duration != 45*time.Minute || c.Retention.Duration != 30*24*time.Hour {
+		t.Errorf("got db %q idle %v retention %v", c.DB, c.LeaseIdle.Duration, c.Retention.Duration)
+	}
+}
+
+func TestDurationAcceptsDays(t *testing.T) {
+	var d config.Duration
+	for _, tc := range []struct {
+		in   string
+		want time.Duration
+	}{
+		{"1d", 24 * time.Hour}, {"7d", 7 * 24 * time.Hour}, {"90m", 90 * time.Minute}, {"2h30m", 150 * time.Minute},
+	} {
+		if err := d.UnmarshalText([]byte(tc.in)); err != nil || d.Duration != tc.want {
+			t.Errorf("UnmarshalText(%q) = %v %v, want %v", tc.in, d.Duration, err, tc.want)
+		}
+	}
+	for _, bad := range []string{"1.5d", "d", "3 days", "1d2h"} {
+		if err := d.UnmarshalText([]byte(bad)); err == nil {
+			t.Errorf("UnmarshalText(%q) must fail", bad)
+		}
+	}
+}
+
+func TestV1Validation(t *testing.T) {
+	for _, tc := range []struct{ name, text, field string }{
+		{"empty db", "db = \"\"\n" + v1Base, "db"},
+		{"lease_idle too short", "lease_idle = \"10s\"\n" + v1Base, "lease_idle"},
+		{"retention too short", "retention = \"12h\"\n" + v1Base, "retention"},
+	} {
+		_, err := config.Parse(strings.NewReader(tc.text))
+		e, ok := config.IsError(err)
+		if !ok || e.Field != tc.field {
+			t.Errorf("%s: %v, want *Error on %s", tc.name, err, tc.field)
+		}
+	}
+}

internal/config/testdata/bad-unknown-key.toml

@@ -1,5 +1,5 @@
 listen = "127.0.0.1:7777"
-lease_idle = "30m"
+bogus_key = 1
 
 [hosts.alpha]
 base_url = "http://alpha.example:11434"

internal/config/unreadable_test.go

@@ -0,0 +1,47 @@
+package config_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+)
+
+// A file that exists but cannot be read is an error, and not a validation error: nothing about
+// the configuration has been judged. Only a missing file is "absent" (and that is an error too).
+func TestUnreadableFileIsAnError(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root can read a 000 file")
+	}
+	dir := t.TempDir()
+	path := filepath.Join(dir, "crossbar.toml")
+	good, err := os.ReadFile(filepath.Join("testdata", "good.toml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, good, 0o000); err != nil {
+		t.Fatal(err)
+	}
+	_, err = config.Load(path)
+	if err == nil {
+		t.Fatal("Load on an unreadable file must fail")
+	}
+	if _, ok := config.IsError(err); ok {
+		t.Errorf("an unreadable file is not a validation *Error: %v", err)
+	}
+	if !strings.HasPrefix(err.Error(), "config: ") {
+		t.Errorf("Error() = %q, want the config: prefix", err.Error())
+	}
+}
+
+func TestDirectoryIsAnError(t *testing.T) {
+	_, err := config.Load(t.TempDir())
+	if err == nil {
+		t.Fatal("Load on a directory must fail")
+	}
+	if _, ok := config.IsError(err); ok {
+		t.Errorf("a directory is not a validation *Error: %v", err)
+	}
+}

internal/fingerprint/fingerprint.go

@@ -0,0 +1,88 @@
+// Package fingerprint identifies a chat-completions conversation without a
+// session id: the system prompt and the first user message never change from
+// turn to turn, so hashing them pins the conversation.
+package fingerprint
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"strings"
+)
+
+// maxPart is the number of bytes of each input string that contributes to the
+// key: 4 KiB keeps a huge first message from slowing every turn.
+const maxPart = 4096
+
+// Of returns the lowercase hex SHA-256 of the system prompt and the first user
+// message of a chat-completions body (first 4 KiB of each, joined with "\n"),
+// or "" when the body is not a JSON object with a "messages" array containing a
+// user message.
+func Of(body []byte) string {
+	var doc struct {
+		Messages []json.RawMessage `json:"messages"`
+	}
+	if err := json.Unmarshal(body, &doc); err != nil || doc.Messages == nil {
+		return ""
+	}
+
+	var system, user string
+	seenSystem, seenUser := false, false
+	for _, raw := range doc.Messages {
+		var msg struct {
+			Role    string          `json:"role"`
+			Content json.RawMessage `json:"content"`
+		}
+		if err := json.Unmarshal(raw, &msg); err != nil {
+			return ""
+		}
+		switch msg.Role {
+		case "system":
+			if !seenSystem {
+				seenSystem = true
+				system = contentText(msg.Content)
+			}
+		case "user":
+			if !seenUser {
+				seenUser = true
+				user = contentText(msg.Content)
+			}
+		}
+	}
+	if !seenUser {
+		return ""
+	}
+
+	if len(system) > maxPart {
+		system = system[:maxPart]
+	}
+	if len(user) > maxPart {
+		user = user[:maxPart]
+	}
+	sum := sha256.Sum256([]byte(system + "\n" + user))
+	return hex.EncodeToString(sum[:])
+}
+
+// contentText renders a message content value: a JSON string is returned as-is,
+// an array of parts is the concatenation of its text parts (other types
+// ignored), and anything else is "".
+func contentText(raw json.RawMessage) string {
+	var text string
+	if err := json.Unmarshal(raw, &text); err == nil {
+		return text
+	}
+	var parts []struct {
+		Type string `json:"type"`
+		Text string `json:"text"`
+	}
+	if err := json.Unmarshal(raw, &parts); err != nil {
+		return ""
+	}
+	var b strings.Builder
+	for _, p := range parts {
+		if p.Type == "text" {
+			b.WriteString(p.Text)
+		}
+	}
+	return b.String()
+}

internal/fingerprint/fingerprint_test.go

@@ -0,0 +1,70 @@
+package fingerprint_test
+
+import (
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/fingerprint"
+)
+
+const conv1 = `{"model":"m","messages":[{"role":"system","content":"You are the project A assistant."},{"role":"user","content":"Add a config loader."},{"role":"assistant","content":"Sure."},{"role":"user","content":"Now tests."}]}`
+const conv1later = `{"model":"m","messages":[{"role":"system","content":"You are the project A assistant."},{"role":"user","content":"Add a config loader."},{"role":"assistant","content":"Sure."},{"role":"user","content":"Now tests."},{"role":"assistant","content":"Done."},{"role":"user","content":"And docs."}]}`
+const conv2 = `{"model":"m","messages":[{"role":"system","content":"You are the project A assistant."},{"role":"user","content":"Fix the flaky test."}]}`
+const conv3 = `{"model":"m","messages":[{"role":"system","content":"You are the project B assistant."},{"role":"user","content":"Add a config loader."}]}`
+
+func TestSameConversationSameKey(t *testing.T) {
+	a := fingerprint.Of([]byte(conv1))
+	b := fingerprint.Of([]byte(conv1later))
+	if a == "" || a != b {
+		t.Errorf("later turns of one conversation must keep the key: %q vs %q", a, b)
+	}
+	if len(a) != 64 || strings.Trim(a, "0123456789abcdef") != "" {
+		t.Errorf("key must be lowercase hex sha256 (64 chars), got %q", a)
+	}
+}
+
+func TestDifferentConversationsDifferentKeys(t *testing.T) {
+	a, b, c := fingerprint.Of([]byte(conv1)), fingerprint.Of([]byte(conv2)), fingerprint.Of([]byte(conv3))
+	if a == b {
+		t.Errorf("different first user message must change the key")
+	}
+	if a == c {
+		t.Errorf("different system prompt must change the key")
+	}
+}
+
+func TestNoUserMessageIsEmpty(t *testing.T) {
+	for _, body := range []string{
+		`{"model":"m","messages":[{"role":"system","content":"only a system prompt"}]}`,
+		`{"model":"m","messages":[]}`,
+		`{"model":"m"}`,
+		`{"input":"an embeddings request"}`,
+		`not json at all`,
+		``,
+	} {
+		if got := fingerprint.Of([]byte(body)); got != "" {
+			t.Errorf("Of(%q) = %q, want empty", body, got)
+		}
+	}
+}
+
+func TestOnlyTheFirstFourKiBCount(t *testing.T) {
+	long := strings.Repeat("x", 5000)
+	a := `{"messages":[{"role":"user","content":"` + long + `A"}]}`
+	b := `{"messages":[{"role":"user","content":"` + long + `B"}]}`
+	if fingerprint.Of([]byte(a)) != fingerprint.Of([]byte(b)) {
+		t.Errorf("bytes after the first 4 KiB of a message must not change the key")
+	}
+	c := `{"messages":[{"role":"user","content":"A` + long + `"}]}`
+	if fingerprint.Of([]byte(a)) == fingerprint.Of([]byte(c)) {
+		t.Errorf("bytes inside the first 4 KiB must change the key")
+	}
+}
+
+func TestContentPartsAreFlattened(t *testing.T) {
+	plain := `{"messages":[{"role":"user","content":"hello world"}]}`
+	parts := `{"messages":[{"role":"user","content":[{"type":"text","text":"hello world"}]}]}`
+	if fingerprint.Of([]byte(plain)) != fingerprint.Of([]byte(parts)) {
+		t.Errorf("a content array of text parts must fingerprint like the joined text")
+	}
+}

internal/lease/lease.go

@@ -0,0 +1,330 @@
+// Package lease is crossbar's sticky placement table. It remembers which host each
+// conversation (and each route) is on and keeps it there unless the host is
+// unhealthy, the lease has been idle past lease_idle, or an operator releases or
+// pins the route. Every change is written through to a Persister and replayed back
+// at start so a restart does not reshuffle sessions.
+package lease
+
+import (
+	"errors"
+	"fmt"
+	"sort"
+	"sync"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+var (
+	ErrNoHost      = errors.New("lease: no usable host")
+	ErrPinnedDown  = errors.New("lease: pinned host is not healthy")
+	ErrUnknownHost = errors.New("lease: unknown host")
+)
+
+// Key identifies one conversation: a route, the fingerprint of its first request
+// (empty for a request with no user message, which leases the route itself), and
+// the model it wants.
+type Key struct {
+	Route, FP, Model string
+}
+
+// Lease is one routed model on one host, in memory.
+type Lease struct {
+	Key
+	Host              string
+	State             store.State
+	Created, LastUsed time.Time
+}
+
+// Persister is the durable half of the table: leases, the pin row, and the event
+// log. *store.Store satisfies it.
+type Persister interface {
+	SaveLease(store.Lease) error
+	DeleteLease(route, fp, model string) error
+	ListLeases() ([]store.Lease, error)
+	RecordEvent(store.LeaseEvent) error
+}
+
+// Hosts is the live health view the table consults before placing a lease.
+type Hosts interface {
+	Healthy(name string) bool
+	Draining(name string) bool
+}
+
+// Chooser picks a host for a new lease among the eligible candidates.
+type Chooser interface {
+	Choose(candidates []string, model string) (string, bool)
+}
+
+type Table struct {
+	mu     sync.Mutex
+	leases map[Key]*Lease             // active leases, keyed by (route, fp, model)
+	pins   map[string]string          // route -> pinned host
+	seen   map[string]map[string]bool // route -> candidate hosts ever asked for or stored
+	p      Persister
+	hosts  Hosts
+	choose Chooser
+	idle   time.Duration
+}
+
+// New builds a table and loads its state. Rows with FP=="" && Model=="" &&
+// State==Pinned are pins; every other row becomes an active lease and its host
+// counts as a candidate already seen for the route.
+func New(p Persister, h Hosts, c Chooser, idle time.Duration) (*Table, error) {
+	loads, err := p.ListLeases()
+	if err != nil {
+		return nil, fmt.Errorf("lease: list leases: %w", err)
+	}
+	t := &Table{
+		leases: make(map[Key]*Lease),
+		pins:   make(map[string]string),
+		seen:   make(map[string]map[string]bool),
+		p:      p,
+		hosts:  h,
+		choose: c,
+		idle:   idle,
+	}
+	for _, l := range loads {
+		if l.FP == "" && l.Model == "" && l.State == store.Pinned {
+			t.pins[l.Route] = l.Host
+		} else {
+			t.leases[Key{l.Route, l.FP, l.Model}] = &Lease{Key{l.Route, l.FP, l.Model}, l.Host, l.State, l.Created, l.LastUsed}
+		}
+		if t.seen[l.Route] == nil {
+			t.seen[l.Route] = make(map[string]bool)
+		}
+		t.seen[l.Route][l.Host] = true
+	}
+	return t, nil
+}
+
+func (l *Lease) store() store.Lease {
+	return store.Lease{Route: l.Route, FP: l.FP, Model: l.Model, Host: l.Host, State: l.State, Created: l.Created, LastUsed: l.LastUsed}
+}
+
+// Acquire places k, keeping it sticky. See the task's Acquire ordering: pinned
+// route, existing lease, inherit the route's host, else choose. Only one lease is
+// created per call, and a failed save is rolled back in memory.
+func (t *Table) Acquire(k Key, candidates []string, now time.Time) (host string, reused bool, err error) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	if t.seen[k.Route] == nil {
+		t.seen[k.Route] = make(map[string]bool)
+	}
+	for _, c := range candidates {
+		t.seen[k.Route][c] = true
+	}
+
+	// unhealthyFrom is set when an existing lease sat on a dead host; the next
+	// create records an unhealthy move instead of a fresh new.
+	var unhealthyFrom string
+	reason := store.ReasonNew
+
+	// 1. Pinned route.
+	if pin, ok := t.pins[k.Route]; ok {
+		if !t.hosts.Healthy(pin) {
+			return "", false, ErrPinnedDown
+		}
+		if _, exists := t.leases[k]; exists {
+			return pin, true, nil
+		}
+		l := &Lease{k, pin, store.Active, now, now}
+		t.leases[k] = l
+		if err := t.save(l); err != nil {
+			delete(t.leases, k)
+			return "", false, err
+		}
+		t.event(now, k, store.ReasonNew, "", pin)
+		return pin, false, nil
+	}
+
+	// 2. Existing lease for k.
+	if l, exists := t.leases[k]; exists {
+		if t.hosts.Healthy(l.Host) {
+			l.LastUsed = now
+			if err := t.save(l); err != nil {
+				return "", false, err
+			}
+			return l.Host, true, nil
+		}
+		unhealthyFrom = l.Host
+	}
+
+	// 3. Inherit the route's own host when a fingerprinted request can start
+	//    where the route already lives.
+	if k.FP != "" {
+		rk := Key{k.Route, "", k.Model}
+		if rl, exists := t.leases[rk]; exists && t.hosts.Healthy(rl.Host) {
+			l := &Lease{k, rl.Host, store.Active, now, now}
+			t.leases[k] = l
+			if err := t.save(l); err != nil {
+				delete(t.leases, k)
+				return "", false, err
+			}
+			if unhealthyFrom != "" {
+				reason = store.ReasonUnhealthy
+			}
+			t.event(now, k, reason, unhealthyFrom, rl.Host)
+			return rl.Host, true, nil
+		}
+	}
+
+	// 4. Choose among healthy, non-draining candidates.
+	filtered := make([]string, 0, len(candidates))
+	for _, c := range candidates {
+		if t.hosts.Healthy(c) && !t.hosts.Draining(c) {
+			filtered = append(filtered, c)
+		}
+	}
+	host, ok := t.choose.Choose(filtered, k.Model)
+	if !ok {
+		return "", false, ErrNoHost
+	}
+	l := &Lease{k, host, store.Active, now, now}
+	t.leases[k] = l
+	if err := t.save(l); err != nil {
+		delete(t.leases, k)
+		return "", false, err
+	}
+	if unhealthyFrom != "" {
+		reason = store.ReasonUnhealthy
+	}
+	t.event(now, k, reason, unhealthyFrom, host)
+	return host, false, nil
+}
+
+// Candidates records hosts as seen for route (idempotent), so Pin can accept a host the route
+// is configured for before any request has used it. cmd/crossbar calls it for every route at
+// start; the admin handler calls it before Pin.
+func (t *Table) Candidates(route string, hosts []string) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	if t.seen[route] == nil {
+		t.seen[route] = make(map[string]bool)
+	}
+	for _, h := range hosts {
+		t.seen[route][h] = true
+	}
+}
+
+// save writes a lease through, failing the call on a persister error.
+func (t *Table) save(l *Lease) error {
+	if err := t.p.SaveLease(l.store()); err != nil {
+		return fmt.Errorf("lease: %w", err)
+	}
+	return nil
+}
+
+// event appends a lease event. from is empty for a fresh placement.
+func (t *Table) event(now time.Time, k Key, reason, from, to string) {
+	_ = t.p.RecordEvent(store.LeaseEvent{TS: now, Route: k.Route, Model: k.Model, FromHost: from, ToHost: to, Reason: reason})
+}
+
+// ExpireIdle removes leases idle longer than lease_idle (never pins, which are
+// not in the lease map) and records an idle event for each. It returns how many
+// it removed.
+func (t *Table) ExpireIdle(now time.Time) int {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	var idle []Key
+	for k, l := range t.leases {
+		if now.Sub(l.LastUsed) > t.idle {
+			idle = append(idle, k)
+		}
+	}
+	for _, k := range idle {
+		l := t.leases[k]
+		delete(t.leases, k)
+		_ = t.p.DeleteLease(k.Route, k.FP, k.Model)
+		t.event(now, k, store.ReasonIdle, l.Host, "")
+	}
+	return len(idle)
+}
+
+// Pin routes route to host. host must be a candidate the table has seen for the
+// route, else ErrUnknownHost. It records a pin event, stores the pin row, and
+// deletes the route's existing leases on other hosts so the next turn lands on
+// the pin.
+func (t *Table) Pin(route, host string, now time.Time) error {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	if t.seen[route] == nil || !t.seen[route][host] {
+		return ErrUnknownHost
+	}
+	t.event(now, Key{Route: route}, store.ReasonPin, "", host)
+	if err := t.p.SaveLease(store.Lease{Route: route, FP: "", Model: "", Host: host, State: store.Pinned, Created: now, LastUsed: now}); err != nil {
+		return fmt.Errorf("lease: %w", err)
+	}
+	t.pins[route] = host
+	for k, l := range t.leases {
+		if k.Route == route && l.Host != host {
+			delete(t.leases, k)
+			_ = t.p.DeleteLease(k.Route, k.FP, k.Model)
+			t.event(now, k, store.ReasonPin, l.Host, host)
+		}
+	}
+	return nil
+}
+
+// Unpin clears the pin for route and records a release. Existing leases stay put.
+func (t *Table) Unpin(route string) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	delete(t.pins, route)
+	_ = t.p.DeleteLease(route, "", "")
+	t.event(time.Now(), Key{Route: route}, store.ReasonRelease, "", "")
+}
+
+// Pinned returns the pinned host for route, or "" if it is not pinned.
+func (t *Table) Pinned(route string) string {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return t.pins[route]
+}
+
+// Release drops every lease (not the pin) of route and records a release event
+// per dropped lease. It returns how many were removed.
+func (t *Table) Release(route string) int {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	var keys []Key
+	for k := range t.leases {
+		if k.Route == route {
+			keys = append(keys, k)
+		}
+	}
+	for _, k := range keys {
+		delete(t.leases, k)
+		_ = t.p.DeleteLease(k.Route, k.FP, k.Model)
+		t.event(time.Now(), k, store.ReasonRelease, "", "")
+	}
+	return len(keys)
+}
+
+// Snapshot returns copies of the active leases, sorted by route, fp, model. Pins
+// are excluded.
+func (t *Table) Snapshot() []Lease {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	out := make([]Lease, 0, len(t.leases))
+	for _, l := range t.leases {
+		out = append(out, *l)
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].Route != out[j].Route {
+			return out[i].Route < out[j].Route
+		}
+		if out[i].FP != out[j].FP {
+			return out[i].FP < out[j].FP
+		}
+		return out[i].Model < out[j].Model
+	})
+	return out
+}

internal/lease/lease_test.go

@@ -0,0 +1,308 @@
+package lease_test
+
+import (
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/lease"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+// memPersister is an in-memory Persister that also counts writes.
+type memPersister struct {
+	mu     sync.Mutex
+	leases map[[3]string]store.Lease
+	events []store.LeaseEvent
+	saves  int
+}
+
+func newPersister() *memPersister { return &memPersister{leases: map[[3]string]store.Lease{}} }
+
+func (m *memPersister) SaveLease(l store.Lease) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.saves++
+	m.leases[[3]string{l.Route, l.FP, l.Model}] = l
+	return nil
+}
+func (m *memPersister) DeleteLease(route, fp, model string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.leases, [3]string{route, fp, model})
+	return nil
+}
+func (m *memPersister) ListLeases() ([]store.Lease, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	out := []store.Lease{}
+	for _, l := range m.leases {
+		out = append(out, l)
+	}
+	return out, nil
+}
+func (m *memPersister) RecordEvent(e store.LeaseEvent) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.events = append(m.events, e)
+	return nil
+}
+func (m *memPersister) reasons() []string {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	var r []string
+	for _, e := range m.events {
+		r = append(r, e.Reason)
+	}
+	return r
+}
+
+// world is a hand-set view of hosts plus a chooser that returns a fixed answer.
+type world struct {
+	mu       sync.Mutex
+	healthy  map[string]bool
+	draining map[string]bool
+	pick     string
+	picks    []string // candidates seen by Choose, for assertions
+}
+
+func (w *world) Healthy(name string) bool  { w.mu.Lock(); defer w.mu.Unlock(); return w.healthy[name] }
+func (w *world) Draining(name string) bool { w.mu.Lock(); defer w.mu.Unlock(); return w.draining[name] }
+func (w *world) Choose(candidates []string, model string) (string, bool) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	w.picks = append([]string{}, candidates...)
+	for _, c := range candidates {
+		if c == w.pick {
+			return c, true
+		}
+	}
+	if len(candidates) > 0 {
+		return candidates[0], true
+	}
+	return "", false
+}
+
+var t0 = time.Date(2026, 9, 25, 10, 0, 0, 0, time.UTC)
+
+func newTable(t *testing.T, p *memPersister, w *world) *lease.Table {
+	tbl, err := lease.New(p, w, w, 30*time.Minute)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return tbl
+}
+
+func TestNewLeaseThenSticky(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "beta"}
+	tbl := newTable(t, p, w)
+	k := lease.Key{Route: "r", FP: "conv1", Model: "m"}
+	host, reused, err := tbl.Acquire(k, []string{"alpha", "beta"}, t0)
+	if err != nil || host != "beta" || reused {
+		t.Fatalf("first: %q %v %v", host, reused, err)
+	}
+	w.pick = "alpha" // the chooser would now prefer alpha; the lease must hold
+	for i := 1; i <= 5; i++ {
+		host, reused, err = tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(time.Duration(i)*time.Minute))
+		if err != nil || host != "beta" || !reused {
+			t.Fatalf("turn %d: %q reused=%v %v, want beta reused", i, host, reused, err)
+		}
+	}
+	if got := p.reasons(); len(got) != 1 || got[0] != store.ReasonNew {
+		t.Errorf("events = %v, want one 'new'", got)
+	}
+	snap := tbl.Snapshot()
+	if len(snap) != 1 || snap[0].Host != "beta" || !snap[0].LastUsed.Equal(t0.Add(5*time.Minute)) {
+		t.Errorf("snapshot = %+v", snap)
+	}
+	if p.saves < 2 {
+		t.Errorf("LastUsed must be written through (saves=%d)", p.saves)
+	}
+}
+
+func TestUnhealthyHostMovesTheLease(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "alpha"}
+	tbl := newTable(t, p, w)
+	k := lease.Key{Route: "r", FP: "c", Model: "m"}
+	if host, _, _ := tbl.Acquire(k, []string{"alpha", "beta"}, t0); host != "alpha" {
+		t.Fatalf("first: %q", host)
+	}
+	w.mu.Lock()
+	w.healthy["alpha"] = false
+	w.pick = "beta"
+	w.mu.Unlock()
+	host, reused, err := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(time.Minute))
+	if err != nil || host != "beta" || reused {
+		t.Fatalf("after alpha down: %q reused=%v %v", host, reused, err)
+	}
+	if got := p.reasons(); len(got) != 2 || got[1] != store.ReasonUnhealthy {
+		t.Errorf("events = %v, want [new unhealthy]", got)
+	}
+	if len(w.picks) != 1 || w.picks[0] != "beta" {
+		t.Errorf("Choose must not see the unhealthy host: %v", w.picks)
+	}
+}
+
+func TestIdleExpiry(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "alpha"}
+	tbl := newTable(t, p, w)
+	k := lease.Key{Route: "r", FP: "c", Model: "m"}
+	tbl.Acquire(k, []string{"alpha", "beta"}, t0)
+	if n := tbl.ExpireIdle(t0.Add(29 * time.Minute)); n != 0 {
+		t.Errorf("expired %d before lease_idle", n)
+	}
+	if n := tbl.ExpireIdle(t0.Add(31 * time.Minute)); n != 1 {
+		t.Errorf("expired %d after lease_idle, want 1", n)
+	}
+	if got := p.reasons(); got[len(got)-1] != store.ReasonIdle {
+		t.Errorf("events = %v, want idle last", got)
+	}
+	w.pick = "beta"
+	if host, reused, _ := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(32*time.Minute)); host != "beta" || reused {
+		t.Errorf("after expiry a new lease is chosen: %q reused=%v", host, reused)
+	}
+	if l, _ := p.ListLeases(); len(l) != 1 {
+		t.Errorf("persister holds %d leases, want 1", len(l))
+	}
+}
+
+func TestFingerprintInheritsRouteLease(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "beta"}
+	tbl := newTable(t, p, w)
+	// A request without a fingerprint (no user message) leases the route itself…
+	if host, _, _ := tbl.Acquire(lease.Key{Route: "r", FP: "", Model: "m"}, []string{"alpha", "beta"}, t0); host != "beta" {
+		t.Fatalf("route lease: %q", host)
+	}
+	w.pick = "alpha"
+	// …and a new conversation on that route starts where the route already is.
+	host, reused, err := tbl.Acquire(lease.Key{Route: "r", FP: "conv", Model: "m"}, []string{"alpha", "beta"}, t0.Add(time.Second))
+	if err != nil || host != "beta" || !reused {
+		t.Errorf("fingerprint lease must inherit the route's host: %q reused=%v %v", host, reused, err)
+	}
+	if len(tbl.Snapshot()) != 2 {
+		t.Errorf("both the route lease and the conversation lease exist: %+v", tbl.Snapshot())
+	}
+}
+
+func TestPinAndUnpin(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "alpha"}
+	tbl := newTable(t, p, w)
+	k := lease.Key{Route: "r", FP: "c", Model: "m"}
+	tbl.Acquire(k, []string{"alpha", "beta"}, t0)
+	if err := tbl.Pin("r", "beta", t0.Add(time.Minute)); err != nil {
+		t.Fatal(err)
+	}
+	host, _, err := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(2*time.Minute))
+	if err != nil || host != "beta" {
+		t.Fatalf("pinned route must go to beta: %q %v", host, err)
+	}
+	host, _, err = tbl.Acquire(lease.Key{Route: "r", FP: "other", Model: "m"}, []string{"alpha", "beta"}, t0.Add(2*time.Minute))
+	if err != nil || host != "beta" {
+		t.Fatalf("new conversations on a pinned route go to the pin too: %q %v", host, err)
+	}
+	w.mu.Lock()
+	w.healthy["beta"] = false
+	w.mu.Unlock()
+	if _, _, err := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(3*time.Minute)); !errors.Is(err, lease.ErrPinnedDown) {
+		t.Errorf("a pinned host that is down is ErrPinnedDown, never a silent move: %v", err)
+	}
+	if err := tbl.Pin("r", "nobody", t0); !errors.Is(err, lease.ErrUnknownHost) {
+		t.Errorf("pinning to a host not in the candidates of any lease: %v, want ErrUnknownHost", err)
+	}
+	tbl.Unpin("r")
+	w.mu.Lock()
+	w.healthy["beta"] = true
+	w.mu.Unlock()
+	if host, _, _ := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(4*time.Minute)); host != "beta" {
+		t.Errorf("after unpin the existing lease (on beta) simply continues: %q", host)
+	}
+	// Events: a pin event naming beta must exist, and the unpin's release event must come after it.
+	// Acquires under the pin may record their own events in between; their number is not fixed here.
+	got := p.reasons()
+	pinAt, releaseAt := -1, -1
+	for i, r := range got {
+		if r == store.ReasonPin && pinAt < 0 {
+			pinAt = i
+		}
+		if r == store.ReasonRelease {
+			releaseAt = i
+		}
+	}
+	if pinAt < 0 || releaseAt < pinAt {
+		t.Errorf("events = %v, want a pin event followed later by a release event", got)
+	}
+	p.mu.Lock()
+	if pinAt >= 0 && p.events[pinAt].ToHost != "beta" {
+		t.Errorf("pin event = %+v, want ToHost beta", p.events[pinAt])
+	}
+	p.mu.Unlock()
+}
+
+func TestDrainKeepsExistingRefusesNew(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, draining: map[string]bool{}, pick: "alpha"}
+	tbl := newTable(t, p, w)
+	k := lease.Key{Route: "r", FP: "c", Model: "m"}
+	tbl.Acquire(k, []string{"alpha", "beta"}, t0)
+	w.mu.Lock()
+	w.draining["alpha"] = true
+	w.mu.Unlock()
+	if host, reused, _ := tbl.Acquire(k, []string{"alpha", "beta"}, t0.Add(time.Minute)); host != "alpha" || !reused {
+		t.Errorf("an existing lease on a draining host continues: %q reused=%v", host, reused)
+	}
+	host, _, err := tbl.Acquire(lease.Key{Route: "r2", FP: "x", Model: "m"}, []string{"alpha", "beta"}, t0.Add(time.Minute))
+	if err != nil || host != "beta" {
+		t.Errorf("a new lease avoids the draining host: %q %v", host, err)
+	}
+	if len(w.picks) != 1 || w.picks[0] != "beta" {
+		t.Errorf("Choose must not see the draining host: %v", w.picks)
+	}
+	if _, _, err := tbl.Acquire(lease.Key{Route: "r3", FP: "y", Model: "m"}, []string{"alpha"}, t0); !errors.Is(err, lease.ErrNoHost) {
+		t.Errorf("only draining candidates: %v, want ErrNoHost", err)
+	}
+}
+
+func TestReleaseRoute(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "alpha"}
+	tbl := newTable(t, p, w)
+	tbl.Acquire(lease.Key{Route: "r", FP: "a", Model: "m"}, []string{"alpha", "beta"}, t0)
+	tbl.Acquire(lease.Key{Route: "r", FP: "b", Model: "m"}, []string{"alpha", "beta"}, t0)
+	tbl.Acquire(lease.Key{Route: "other", FP: "c", Model: "m"}, []string{"alpha", "beta"}, t0)
+	if n := tbl.Release("r"); n != 2 {
+		t.Errorf("Release removed %d, want 2", n)
+	}
+	if n := tbl.Release("r"); n != 0 {
+		t.Errorf("second Release removed %d", n)
+	}
+	if l, _ := p.ListLeases(); len(l) != 1 || l[0].Route != "other" {
+		t.Errorf("persister after release: %+v", l)
+	}
+	w.pick = "beta"
+	if host, reused, _ := tbl.Acquire(lease.Key{Route: "r", FP: "a", Model: "m"}, []string{"alpha", "beta"}, t0); host != "beta" || reused {
+		t.Errorf("after release the route is re-chosen: %q reused=%v", host, reused)
+	}
+}
+
+func TestLoadsFromPersister(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{"alpha": true, "beta": true}, pick: "alpha"}
+	_ = p.SaveLease(store.Lease{Route: "r", FP: "c", Model: "m", Host: "beta", State: store.Active, Created: t0, LastUsed: t0})
+	_ = p.SaveLease(store.Lease{Route: "pinned", FP: "", Model: "", Host: "beta", State: store.Pinned, Created: t0, LastUsed: t0})
+	tbl := newTable(t, p, w)
+	if host, reused, _ := tbl.Acquire(lease.Key{Route: "r", FP: "c", Model: "m"}, []string{"alpha", "beta"}, t0.Add(time.Second)); host != "beta" || !reused {
+		t.Errorf("a restart must not reshuffle: %q reused=%v", host, reused)
+	}
+	if host, _, _ := tbl.Acquire(lease.Key{Route: "pinned", FP: "new", Model: "m"}, []string{"alpha", "beta"}, t0.Add(time.Second)); host != "beta" {
+		t.Errorf("a pin survives a restart: %q", host)
+	}
+}
+
+func TestNoCandidates(t *testing.T) {
+	p, w := newPersister(), &world{healthy: map[string]bool{}, pick: ""}
+	tbl := newTable(t, p, w)
+	if _, _, err := tbl.Acquire(lease.Key{Route: "r", FP: "c", Model: "m"}, []string{"alpha"}, t0); !errors.Is(err, lease.ErrNoHost) {
+		t.Errorf("no healthy host: %v, want ErrNoHost", err)
+	}
+	if len(tbl.Snapshot()) != 0 {
+		t.Errorf("a failed acquire must not create a lease")
+	}
+}

internal/limiter/limiter.go

@@ -0,0 +1,180 @@
+// Package limiter hands out at most `parallel` concurrent slots per (host, model) and lets at
+// most `queue_max` requests wait in a FIFO. A request that finds the queue full is refused at
+// once so the caller can retry elsewhere; a waiting request can cancel and leave without leaking
+// a slot or a queue place.
+package limiter
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"time"
+)
+
+// ErrQueueFull is returned by Acquire when the queue is already at queue_max; the caller may try a
+// different host.
+var ErrQueueFull = errors.New("queue full")
+
+// defaults is what an unconfigured (host, model) behaves as: one slot, no waiting room.
+const (
+	defaultParallel = 1
+	defaultQueueMax = 0
+)
+
+// pair holds the live state for one (host, model): how many slots exist, how many are taken, and
+// the FIFO of waiters. All fields are guarded by Limiter.mu.
+type pair struct {
+	parallel   int
+	queueMax   int
+	inflight   int
+	waiters    []chan struct{}
+	configured bool
+}
+
+// Limiter tracks one pair per (host, model). Safe for concurrent use.
+type Limiter struct {
+	mu    sync.Mutex
+	pairs map[pairKey]*pair
+}
+
+type pairKey struct {
+	host  string
+	model string
+}
+
+// New returns an empty Limiter.
+func New() *Limiter {
+	return &Limiter{pairs: make(map[pairKey]*pair)}
+}
+
+// Configure sets the slot and queue limits for one (host, model). It may be called before any
+// request or after one has created the pair with the defaults; either way the limits apply.
+func (l *Limiter) Configure(host, model string, parallel, queueMax int) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	p := l.pairLocked(host, model)
+	p.parallel = parallel
+	p.queueMax = queueMax
+	p.configured = true
+}
+
+// pairLocked returns the pair for (host, model), creating it with the unconfigured defaults if it
+// does not exist yet. The caller holds l.mu.
+func (l *Limiter) pairLocked(host, model string) *pair {
+	k := pairKey{host, model}
+	p := l.pairs[k]
+	if p == nil {
+		p = &pair{parallel: defaultParallel, queueMax: defaultQueueMax}
+		l.pairs[k] = p
+	}
+	return p
+}
+
+// Acquire blocks until a slot is held. It returns a release that gives the slot back exactly once
+// (a second call is a no-op), how long the caller spent in the queue, and an error: ErrQueueFull
+// when the queue is already full (returned immediately, without waiting), or ctx.Err() when the
+// context ends while waiting.
+func (l *Limiter) Acquire(ctx context.Context, host, model string) (release func(), waited time.Duration, err error) {
+	l.mu.Lock()
+	start := time.Now()
+	p := l.pairLocked(host, model)
+	if p.inflight < p.parallel {
+		p.inflight++
+		l.mu.Unlock()
+		return l.release(p), time.Since(start), nil
+	}
+	if len(p.waiters) >= p.queueMax {
+		l.mu.Unlock()
+		return nil, time.Since(start), ErrQueueFull
+	}
+	waiter := make(chan struct{})
+	p.waiters = append(p.waiters, waiter)
+	l.mu.Unlock()
+
+	select {
+	case <-ctx.Done():
+		// The slot may have been handed to us the instant the context ended; release it either
+		// way so neither a slot nor a queue place leaks.
+		l.mu.Lock()
+		if !p.dropWaiter(waiter) {
+			l.mu.Unlock()
+			l.release(p)
+			return nil, time.Since(start), ctx.Err()
+		}
+		l.mu.Unlock()
+		return nil, time.Since(start), ctx.Err()
+	case <-waiter:
+		return l.release(p), time.Since(start), nil
+	}
+}
+
+// release returns the function the caller holds for a slot: it hands the slot to the next waiter
+// if one is waiting, otherwise it frees the slot. It is safe to call through the sync.Once that
+// Acquire wrapped it in.
+func (l *Limiter) release(p *pair) func() {
+	var once sync.Once
+	return func() {
+		once.Do(func() {
+			l.mu.Lock()
+			defer l.mu.Unlock()
+			if len(p.waiters) > 0 {
+				next := p.waiters[0]
+				p.waiters = p.waiters[1:]
+				close(next)
+				return
+			}
+			p.inflight--
+		})
+	}
+}
+
+// dropWaiter removes w from the middle of the queue. It reports whether w was there; false means
+// the slot was already handed to w (its channel closed) and the caller must give it back.
+func (p *pair) dropWaiter(w chan struct{}) bool {
+	for i, cw := range p.waiters {
+		if cw == w {
+			p.waiters = append(p.waiters[:i], p.waiters[i+1:]...)
+			return true
+		}
+	}
+	return false
+}
+
+// InFlight returns the number of held slots for (host, model).
+func (l *Limiter) InFlight(host, model string) int {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	p := l.pairs[pairKey{host, model}]
+	if p == nil {
+		return 0
+	}
+	return p.inflight
+}
+
+// Queued returns the number of requests waiting for (host, model).
+func (l *Limiter) Queued(host, model string) int {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	p := l.pairs[pairKey{host, model}]
+	if p == nil {
+		return 0
+	}
+	return len(p.waiters)
+}
+
+// FreeSlots sums the unused slots over the host's configured models, never counting below zero for
+// one. An unknown host has none.
+func (l *Limiter) FreeSlots(host string) int {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	total := 0
+	for k, p := range l.pairs {
+		if k.host != host || !p.configured {
+			continue
+		}
+		if free := p.parallel - p.inflight; free > 0 {
+			total += free
+		}
+	}
+	return total
+}

internal/limiter/limiter_test.go

@@ -0,0 +1,178 @@
+package limiter_test
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/limiter"
+)
+
+func TestParallelAndQueue(t *testing.T) {
+	l := limiter.New()
+	l.Configure("alpha", "m", 2, 1) // two slots, one waiting place
+	ctx := context.Background()
+
+	rel1, w1, err := l.Acquire(ctx, "alpha", "m")
+	if err != nil || w1 > 50*time.Millisecond {
+		t.Fatalf("first acquire: err %v waited %v", err, w1)
+	}
+	rel2, _, err := l.Acquire(ctx, "alpha", "m")
+	if err != nil {
+		t.Fatalf("second acquire: %v", err)
+	}
+	if l.InFlight("alpha", "m") != 2 || l.FreeSlots("alpha") != 0 {
+		t.Errorf("in flight %d free %d, want 2 and 0", l.InFlight("alpha", "m"), l.FreeSlots("alpha"))
+	}
+
+	// Third waits in the queue.
+	got3 := make(chan error, 1)
+	go func() {
+		rel, waited, err := l.Acquire(ctx, "alpha", "m")
+		if err == nil {
+			defer rel()
+			if waited < 40*time.Millisecond {
+				err = errors.New("third acquire did not wait")
+			}
+		}
+		got3 <- err
+	}()
+	time.Sleep(20 * time.Millisecond)
+	if l.Queued("alpha", "m") != 1 {
+		t.Errorf("queued = %d, want 1", l.Queued("alpha", "m"))
+	}
+	// Fourth finds the queue full and is refused at once.
+	start := time.Now()
+	_, _, err = l.Acquire(ctx, "alpha", "m")
+	if !errors.Is(err, limiter.ErrQueueFull) {
+		t.Fatalf("fourth acquire: %v, want ErrQueueFull", err)
+	}
+	if time.Since(start) > 50*time.Millisecond {
+		t.Errorf("a full queue must refuse immediately, took %v", time.Since(start))
+	}
+	time.Sleep(30 * time.Millisecond)
+	rel1() // frees a slot: the queued third proceeds
+	select {
+	case err := <-got3:
+		if err != nil {
+			t.Fatalf("third: %v", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("queued acquire did not proceed after a release")
+	}
+	rel2()
+	if l.InFlight("alpha", "m") != 0 || l.Queued("alpha", "m") != 0 {
+		t.Errorf("after releases: inflight %d queued %d", l.InFlight("alpha", "m"), l.Queued("alpha", "m"))
+	}
+}
+
+func TestReleaseIsIdempotent(t *testing.T) {
+	l := limiter.New()
+	l.Configure("h", "m", 1, 0)
+	rel, _, err := l.Acquire(context.Background(), "h", "m")
+	if err != nil {
+		t.Fatal(err)
+	}
+	rel()
+	rel() // a second call must not free a slot that was never taken
+	if l.InFlight("h", "m") != 0 {
+		t.Errorf("in flight %d after double release", l.InFlight("h", "m"))
+	}
+	if _, _, err := l.Acquire(context.Background(), "h", "m"); err != nil {
+		t.Errorf("slot must be free again: %v", err)
+	}
+}
+
+func TestCancelWhileQueuedLeaksNothing(t *testing.T) {
+	l := limiter.New()
+	l.Configure("h", "m", 1, 2)
+	rel, _, err := l.Acquire(context.Background(), "h", "m")
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { _, _, err := l.Acquire(ctx, "h", "m"); done <- err }()
+	time.Sleep(20 * time.Millisecond)
+	cancel()
+	select {
+	case err := <-done:
+		if !errors.Is(err, context.Canceled) {
+			t.Fatalf("cancelled acquire returned %v", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("cancelled acquire did not return")
+	}
+	if l.Queued("h", "m") != 0 {
+		t.Errorf("queued = %d after cancel", l.Queued("h", "m"))
+	}
+	rel()
+	if l.InFlight("h", "m") != 0 {
+		t.Errorf("in flight %d, the cancelled waiter must not have taken the slot", l.InFlight("h", "m"))
+	}
+}
+
+func TestQueueIsFIFO(t *testing.T) {
+	l := limiter.New()
+	l.Configure("h", "m", 1, 8)
+	rel, _, err := l.Acquire(context.Background(), "h", "m")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var mu sync.Mutex
+	var order []int
+	var wg sync.WaitGroup
+	for i := 1; i <= 4; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			r, _, err := l.Acquire(context.Background(), "h", "m")
+			if err != nil {
+				t.Errorf("waiter %d: %v", i, err)
+				return
+			}
+			mu.Lock()
+			order = append(order, i)
+			mu.Unlock()
+			time.Sleep(5 * time.Millisecond)
+			r()
+		}(i)
+		time.Sleep(15 * time.Millisecond) // stagger arrivals so the order is defined
+	}
+	rel()
+	wg.Wait()
+	if len(order) != 4 || order[0] != 1 || order[1] != 2 || order[2] != 3 || order[3] != 4 {
+		t.Errorf("waiters proceeded in order %v, want [1 2 3 4]", order)
+	}
+}
+
+func TestUnconfiguredPairIsOneSlotNoQueue(t *testing.T) {
+	l := limiter.New()
+	rel, _, err := l.Acquire(context.Background(), "x", "y")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer rel()
+	if _, _, err := l.Acquire(context.Background(), "x", "y"); !errors.Is(err, limiter.ErrQueueFull) {
+		t.Errorf("second acquire on an unconfigured pair: %v, want ErrQueueFull", err)
+	}
+}
+
+func TestFreeSlotsSumsModels(t *testing.T) {
+	l := limiter.New()
+	l.Configure("h", "a", 4, 0)
+	l.Configure("h", "b", 2, 0)
+	if got := l.FreeSlots("h"); got != 6 {
+		t.Fatalf("free = %d, want 6", got)
+	}
+	rel, _, _ := l.Acquire(context.Background(), "h", "a")
+	defer rel()
+	if got := l.FreeSlots("h"); got != 5 {
+		t.Errorf("free = %d, want 5", got)
+	}
+	if l.FreeSlots("nobody") != 0 {
+		t.Errorf("unknown host has no slots")
+	}
+}

internal/proxy/cancel_test.go

@@ -0,0 +1,109 @@
+package proxy_test
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+// A client that goes away mid-stream is still a request that happened: it held a slot, it cost
+// prefill, and it belongs in the accounting. The row records status 499 and a non-empty err.
+func TestClientCancelMidStreamIsRecorded(t *testing.T) {
+	slow := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/health":
+			fmt.Fprint(w, `{"status":"ok"}`)
+		case "/v1/models":
+			fmt.Fprint(w, `{"object":"list","data":[{"id":"shared"}]}`)
+		default:
+			w.Header().Set("Content-Type", "text/event-stream")
+			w.WriteHeader(200)
+			fmt.Fprint(w, "data: {\"choices\":[{\"delta\":{\"content\":\"first\"}}]}\n\n")
+			w.(http.Flusher).Flush()
+			select {
+			case <-r.Context().Done():
+			case <-time.After(3 * time.Second):
+			}
+		}
+	}))
+	t.Cleanup(slow.Close)
+	beta := newUpstream(t, "beta")
+	r := newRig(t, twoHosts, &upstream{name: "alpha", srv: slow}, beta)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	body := `{"model":"alpha-only","stream":true,"messages":[{"role":"user","content":"cancel me"}]}`
+	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, r.front.URL+"/r/v1/chat/completions", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	buf := make([]byte, 64)
+	if _, err := resp.Body.Read(buf); err != nil {
+		t.Fatalf("first chunk: %v", err)
+	}
+	cancel()
+	resp.Body.Close()
+
+	deadline := time.Now().Add(3 * time.Second)
+	var counts []store.StatusCount
+	for time.Now().Before(deadline) {
+		counts, _ = r.store.StatusCounts(time.Time{})
+		if len(counts) > 0 {
+			break
+		}
+		time.Sleep(25 * time.Millisecond)
+	}
+	if len(counts) != 1 || counts[0].Status != 499 || counts[0].Route != "r" || counts[0].Count != 1 {
+		t.Fatalf("status counts after a cancelled stream = %+v, want one row: route r, status 499", counts)
+	}
+	rows, _ := r.store.Usage(time.Time{}, store.ByRoute)
+	if len(rows) != 1 || rows[0].Requests != 1 || rows[0].Errors != 1 {
+		t.Errorf("usage = %+v, want 1 request counted as an error", rows)
+	}
+}
+
+// The same when the client gives up while waiting in the queue: a 499 row, no slot leaked.
+func TestClientCancelWhileQueuedIsRecorded(t *testing.T) {
+	alpha := newUpstream(t, "alpha")
+	alpha.delay = 800 * time.Millisecond
+	r := newRig(t, `
+listen = "127.0.0.1:1"
+queue_max = 2
+[hosts.alpha]
+base_url = %q
+models = { "shared" = { parallel = 1 } }
+[routes.r]
+hosts = ["alpha"]
+default_model = "shared"
+`, alpha)
+	go func() { drain(r.post("/r/v1/chat/completions", conversation(1, 1))) }() // holds the one slot
+	time.Sleep(100 * time.Millisecond)
+	ctx, cancel := context.WithTimeout(context.Background(), 150*time.Millisecond)
+	defer cancel()
+	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, r.front.URL+"/r/v1/chat/completions", strings.NewReader(conversation(2, 1)))
+	req.Header.Set("Content-Type", "application/json")
+	if _, err := http.DefaultClient.Do(req); err == nil {
+		t.Fatal("the queued request should have been cancelled by its context")
+	}
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		counts, _ := r.store.StatusCounts(time.Time{})
+		for _, c := range counts {
+			if c.Status == 499 {
+				if r.lim.Queued("alpha", "shared") != 0 {
+					t.Errorf("queued = %d after the waiter cancelled", r.lim.Queued("alpha", "shared"))
+				}
+				return
+			}
+		}
+		time.Sleep(25 * time.Millisecond)
+	}
+	t.Fatal("no 499 row recorded for the request cancelled while queued")
+}

internal/proxy/forward.go

@@ -0,0 +1,196 @@
+package proxy
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"strings"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+// forward builds the reverse proxy for one host, tees the response, records the accounting row, and
+// logs. leaseState is "new" or "reused"; waited is the time spent in the queue.
+func (p *Handler) forward(w http.ResponseWriter, r *http.Request, route, host, leaseState, rest, fp, model string, started time.Time, waited time.Duration) {
+	hostCfg, ok := p.cfg.Hosts[host]
+	if !ok {
+		p.writeError(w, http.StatusBadGateway, "upstream failed")
+		return
+	}
+	target, err := url.Parse(hostCfg.BaseURL)
+	if err != nil {
+		p.writeError(w, http.StatusBadGateway, "upstream failed")
+		return
+	}
+
+	rev := &forwardState{started: started}
+	rp := newReverseProxy(p.health, host, leaseState, target, rest, rev)
+	rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
+
+	// ServeHTTP unwinds with http.ErrAbortHandler when a client leaves mid-stream; recover so the
+	// row the request earned is still written, then re-panic so the server keeps its semantics.
+	defer func() {
+		if pv := recover(); pv != nil {
+			total := time.Since(started).Milliseconds()
+			req := forwardRow(route, fp, model, host, started, waited, rev, rec.status, total)
+			if perr, ok := pv.(error); ok && errors.Is(perr, http.ErrAbortHandler) {
+				req.Status = 499
+				req.Err = "client cancelled"
+			} else {
+				req.Err = "upstream error"
+			}
+			p.writeRecord(req)
+			panic(pv)
+		}
+	}()
+
+	rp.ServeHTTP(rec, r)
+	total := time.Since(started)
+
+	req := forwardRow(route, fp, model, host, started, waited, rev, rec.status, total.Milliseconds())
+	if r.Context().Err() != nil {
+		req.Status = 499
+		req.Err = "client cancelled"
+	}
+	p.writeRecord(req)
+
+	fp8 := fp
+	if len(fp8) > 8 {
+		fp8 = fp8[:8]
+	}
+	p.log.Info("request",
+		"route", route,
+		"host", host,
+		"method", r.Method,
+		"path", rest,
+		"status", rec.status,
+		"lease", leaseState,
+		"queued_ms", waited.Milliseconds(),
+		"fp", fp8,
+		"ms", total.Milliseconds(),
+	)
+}
+
+// forwardRow builds the accounting row from the state a forward gathered: what the tee scanned and
+// what the recorder captured. totalMs is measured from start to the caller's exit, so the forward
+// path and the recovery path above build identical rows.
+func forwardRow(route, fp, model, host string, start time.Time, waited time.Duration, rev *forwardState, status int, totalMs int64) store.Request {
+	req := store.Request{
+		Route:    route,
+		FP:       fp,
+		Model:    model,
+		Host:     host,
+		Started:  start,
+		QueuedMs: waited.Milliseconds(),
+		TTFBMs:   ttfbMs(rev),
+		TotalMs:  totalMs,
+		Status:   status,
+		Streamed: rev.streamed,
+	}
+	if rev.tee != nil {
+		prompt, cached, completion := rev.tee.tokens()
+		req.PromptTokens = int64(prompt)
+		req.CachedTokens = int64(cached)
+		req.CompletionTokens = int64(completion)
+	}
+	return req
+}
+
+// leaseState is "reused" when the lease already held the conversation, else "new".
+func leaseState(reused bool) string {
+	if reused {
+		return "reused"
+	}
+	return "new"
+}
+
+// ttfbMs is the time from request start to the response head; zero when the head never arrived.
+func ttfbMs(rev *forwardState) int64 {
+	if rev.ttfb.IsZero() || rev.ttfb.Before(rev.started) {
+		return 0
+	}
+	return rev.ttfb.Sub(rev.started).Milliseconds()
+}
+
+// forwardState carries, across one forward, when the request started, when the head arrived, whether
+// the response streamed, and the tee that scanned it.
+type forwardState struct {
+	started  time.Time
+	ttfb     time.Time
+	streamed bool
+	tee      *tee
+}
+
+// statusRecorder records the status written and forwards Flush so the reverse proxy can stream.
+type statusRecorder struct {
+	http.ResponseWriter
+	status int
+}
+
+func (r *statusRecorder) WriteHeader(code int) {
+	r.status = code
+	r.ResponseWriter.WriteHeader(code)
+}
+
+func (r *statusRecorder) Flush() {
+	if f, ok := r.ResponseWriter.(http.Flusher); ok {
+		f.Flush()
+	}
+}
+
+// writeError answers with a JSON {"error":"…"} body.
+func (p *Handler) writeError(w http.ResponseWriter, status int, msg string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(map[string]string{"error": msg})
+}
+
+// writeRecord writes one accounting row, logging (never returning) a recorder error.
+func (p *Handler) writeRecord(req store.Request) {
+	if p.rec == nil {
+		return
+	}
+	if err := p.rec.RecordRequest(req); err != nil {
+		p.log.Error("record request", "err", err)
+	}
+}
+
+// newReverseProxy forwards to a single host, rewriting the path to target.Path+rest and keeping the
+// original query string. It flushes after every write so long server-sent-event streams are not
+// buffered, tees the response for usage/timings, and marks the host down on any transport error
+// other than a client disconnect.
+func newReverseProxy(h Health, host, leaseState string, target *url.URL, rest string, rev *forwardState) *httputil.ReverseProxy {
+	return &httputil.ReverseProxy{
+		Rewrite: func(pr *httputil.ProxyRequest) {
+			pr.SetURL(target)
+			pr.Out.URL.Path = target.Path + rest
+			pr.Out.URL.RawPath = ""
+			pr.Out.Host = target.Host
+			pr.SetXForwarded()
+		},
+		FlushInterval: -1,
+		ModifyResponse: func(resp *http.Response) error {
+			resp.Header.Set(HostHeader, host)
+			resp.Header.Set(LeaseHeader, leaseState)
+			rev.ttfb = time.Now()
+			rev.streamed = strings.HasPrefix(resp.Header.Get("Content-Type"), "text/event-stream")
+			t := newTee(resp.Body, rev.streamed)
+			resp.Body = t
+			rev.tee = t
+			return nil
+		},
+		ErrorHandler: func(w http.ResponseWriter, req *http.Request, err error) {
+			if errors.Is(err, context.Canceled) {
+				return
+			}
+			h.MarkDown(host, err.Error())
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusBadGateway)
+			_ = json.NewEncoder(w).Encode(map[string]string{"error": "upstream failed", "host": host})
+		},
+	}
+}

internal/proxy/helpers_test.go

@@ -0,0 +1,211 @@
+package proxy_test
+
+// Test scaffolding shared by proxy_test.go and recorder_test.go: the fake health table, the fake
+// llama-server upstream, and the rig that builds a whole crossbar over real HTTP.
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+	"git.wntrmute.dev/kyle/crossbar/internal/health"
+	"git.wntrmute.dev/kyle/crossbar/internal/lease"
+	"git.wntrmute.dev/kyle/crossbar/internal/limiter"
+	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+// fakeHealth is a hand-set health table that also records MarkDown calls. It lived in the v0
+// proxy_test.go; the v1 given test replaces that file, so recorder_test.go (which still exercises
+// the nil-lease path through proxy.New) needs it here.
+type fakeHealth struct {
+	mu     sync.Mutex
+	st     map[string]health.Status
+	marked []string
+}
+
+func (f *fakeHealth) Get(name string) (health.Status, bool) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	s, ok := f.st[name]
+	return s, ok
+}
+
+func (f *fakeHealth) MarkDown(name, reason string) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.marked = append(f.marked, name)
+	s := f.st[name]
+	s.Healthy = false
+	s.LastErr = reason
+	f.st[name] = s
+}
+
+func (f *fakeHealth) markedHosts() []string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return append([]string{}, f.marked...)
+}
+
+// upstream is a llama-server stand-in: streams N chunks with a delay, reports usage/timings in
+// the final chunk, counts requests, and can be slowed down or killed.
+type upstream struct {
+	name  string
+	srv   *httptest.Server
+	hits  atomic.Int32
+	delay time.Duration
+	mu    sync.Mutex
+	last  recorded
+}
+
+type recorded struct{ method, path, host, xff, body string }
+
+func newUpstream(t *testing.T, name string) *upstream {
+	u := &upstream{name: name}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, `{"status":"ok"}`) })
+	mux.HandleFunc("/v1/models", func(w http.ResponseWriter, r *http.Request) {
+		u.mu.Lock()
+		u.last = recorded{r.Method, r.URL.RequestURI(), r.Host, r.Header.Get("X-Forwarded-For"), ""}
+		u.mu.Unlock()
+		fmt.Fprint(w, `{"object":"list","data":[{"id":"shared"},{"id":"`+name+`-only"}]}`)
+	})
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		u.hits.Add(1)
+		b, _ := io.ReadAll(r.Body)
+		u.mu.Lock()
+		u.last = recorded{r.Method, r.URL.RequestURI(), r.Host, r.Header.Get("X-Forwarded-For"), string(b)}
+		u.mu.Unlock()
+		var req struct {
+			Stream bool `json:"stream"`
+		}
+		_ = json.Unmarshal(b, &req)
+		w.Header().Set("X-Upstream", name)
+		time.Sleep(u.delay)
+		if !req.Stream {
+			w.Header().Set("Content-Type", "application/json")
+			fmt.Fprintf(w, `{"choices":[{"message":{"role":"assistant","content":"hi from %s"}}],"usage":{"prompt_tokens":100,"completion_tokens":10,"total_tokens":110},"timings":{"prompt_n":100,"cache_n":90,"predicted_n":10,"predicted_ms":50.0}}`, name)
+			return
+		}
+		w.Header().Set("Content-Type", "text/event-stream")
+		w.WriteHeader(200)
+		fl := w.(http.Flusher)
+		for i := 0; i < 3; i++ {
+			fmt.Fprintf(w, "data: {\"choices\":[{\"delta\":{\"content\":\"%s %d \"}}]}\n\n", name, i)
+			fl.Flush()
+			time.Sleep(10 * time.Millisecond)
+		}
+		fmt.Fprint(w, `data: {"choices":[],"usage":{"prompt_tokens":200,"completion_tokens":20,"total_tokens":220},"timings":{"prompt_n":200,"cache_n":150,"predicted_n":20,"predicted_ms":80.0}}`+"\n\n")
+		fl.Flush()
+		fmt.Fprint(w, "data: [DONE]\n\n")
+	})
+	u.srv = httptest.NewServer(mux)
+	t.Cleanup(u.srv.Close)
+	return u
+}
+
+func (u *upstream) lastReq() recorded { u.mu.Lock(); defer u.mu.Unlock(); return u.last }
+
+// rig is one crossbar: config, real health table (polled once), real lease table over a real
+// SQLite store, real limiter, the proxy handler served by httptest.
+type rig struct {
+	t      *testing.T
+	cfg    *config.Config
+	health *health.Table
+	store  *store.Store
+	leases *lease.Table
+	lim    *limiter.Limiter
+	front  *httptest.Server
+}
+
+// newRig builds crossbar from a config text where %s placeholders are the upstream base URLs.
+func newRig(t *testing.T, cfgText string, ups ...*upstream) *rig {
+	urls := make([]any, len(ups))
+	for i, u := range ups {
+		urls[i] = u.srv.URL
+	}
+	cfg, err := config.Parse(strings.NewReader(fmt.Sprintf(cfgText, urls...)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	bases := map[string]string{}
+	for name, h := range cfg.Hosts {
+		bases[name] = h.BaseURL
+	}
+	ht := health.New(bases, time.Hour, nil)
+	ht.PollOnce(t.Context())
+	st, err := store.Open(filepath.Join(t.TempDir(), "crossbar.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	lim := limiter.New()
+	for name, h := range cfg.Hosts {
+		for model, m := range h.Models {
+			lim.Configure(name, model, m.Parallel, cfg.QueueMax)
+		}
+	}
+	lt, err := lease.New(st, proxy.HostView(ht, cfg), proxy.Chooser(cfg, ht, lim), cfg.LeaseIdle.Duration)
+	if err != nil {
+		t.Fatal(err)
+	}
+	p := proxy.New(cfg, ht, lt, lim, st, nil)
+	front := httptest.NewServer(p)
+	t.Cleanup(front.Close)
+	return &rig{t: t, cfg: cfg, health: ht, store: st, leases: lt, lim: lim, front: front}
+}
+
+const twoHosts = `
+listen = "127.0.0.1:1"
+queue_max = 1
+lease_idle = "30m"
+[hosts.alpha]
+base_url = %q
+weight = 1.0
+models = { "shared" = { parallel = 2 }, "alpha-only" = { } }
+[hosts.beta]
+base_url = %q
+weight = 2.0
+models = { "shared" = { parallel = 2 }, "beta-only" = { } }
+[routes.r]
+hosts = ["alpha", "beta"]
+default_model = "shared"
+[routes.other]
+hosts = ["alpha"]
+`
+
+func conversation(id, turn int) string {
+	msgs := fmt.Sprintf(`{"role":"system","content":"project"},{"role":"user","content":"conversation %d opening"}`, id)
+	for i := 1; i < turn; i++ {
+		msgs += fmt.Sprintf(`,{"role":"assistant","content":"ok"},{"role":"user","content":"turn %d"}`, i)
+	}
+	return `{"model":"shared","stream":false,"messages":[` + msgs + `]}`
+}
+
+func (r *rig) post(path, body string, hdr ...string) *http.Response {
+	req, _ := http.NewRequest(http.MethodPost, r.front.URL+path, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	for i := 0; i+1 < len(hdr); i += 2 {
+		req.Header.Set(hdr[i], hdr[i+1])
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		r.t.Fatal(err)
+	}
+	return resp
+}
+
+func drain(resp *http.Response) string {
+	b, _ := io.ReadAll(resp.Body)
+	resp.Body.Close()
+	return string(b)
+}

internal/proxy/hosts.go

@@ -0,0 +1,107 @@
+package proxy
+
+import (
+	"sync"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/choose"
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+	"git.wntrmute.dev/kyle/crossbar/internal/health"
+	"git.wntrmute.dev/kyle/crossbar/internal/lease"
+	"git.wntrmute.dev/kyle/crossbar/internal/limiter"
+)
+
+// Hosts adapts the health table and config for the lease table, and holds the operator's drain set.
+// The lease table filters candidates by Healthy && !Draining: Healthy is the health table's view of
+// a host, Draining is an operator flag that keeps new leases off a host being taken out of service.
+type Hosts struct {
+	health *health.Table
+	drain  map[string]bool
+	mu     sync.Mutex
+}
+
+// HostView builds the lease-table view of the health table and config.
+func HostView(h *health.Table, cfg *config.Config) *Hosts {
+	return &Hosts{health: h, drain: make(map[string]bool)}
+}
+
+// Healthy reports whether the health table says the host answered its last poll; an unknown host is
+// not healthy.
+func (h *Hosts) Healthy(name string) bool {
+	s, ok := h.health.Get(name)
+	if !ok {
+		return false
+	}
+	return s.Healthy
+}
+
+// Draining reports whether an operator is draining the host.
+func (h *Hosts) Draining(name string) bool {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	return h.drain[name]
+}
+
+// SetDraining turns draining on or off for a host.
+func (h *Hosts) SetDraining(name string, on bool) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if on {
+		h.drain[name] = true
+		return
+	}
+	delete(h.drain, name)
+}
+
+// hostChooser adapts config, health and limiter to lease.Chooser via choose.Best.
+type hostChooser struct {
+	cfg    *config.Config
+	health *health.Table
+	lim    *limiter.Limiter
+}
+
+// Chooser adapts config, health and limiter to lease.Chooser using choose.Best: among the candidates
+// it prefers the hosts that have the model loaded over those that can only serve it, then the one
+// with the most free slots times weight, breaking ties by shortest queue. Draining is reported false
+// because the lease table already filtered draining hosts out before calling Choose.
+func Chooser(cfg *config.Config, h *health.Table, l *limiter.Limiter) lease.Chooser {
+	return &hostChooser{cfg: cfg, health: h, lim: l}
+}
+
+func (c *hostChooser) Choose(candidates []string, model string) (string, bool) {
+	return choose.Best(candidates, func(host string) (choose.Info, bool) {
+		s, ok := c.health.Get(host)
+		info := choose.Info{
+			Healthy:  ok && s.Healthy,
+			Draining: false,
+			Loaded:   contains(s.Loaded, model),
+			CanServe: c.cfg.Serves(host, model),
+			Free:     freeForModel(c.cfg.Hosts[host], model, c.lim.InFlight(host, model)),
+			Queued:   c.lim.Queued(host, model),
+			Weight:   c.cfg.Hosts[host].Weight,
+		}
+		return info, ok
+	})
+}
+
+func contains(list []string, v string) bool {
+	for _, s := range list {
+		if s == v {
+			return true
+		}
+	}
+	return false
+}
+
+// freeForModel returns the free slots for one model on one host: its parallel minus the in-flight
+// count, floored at zero, and zero when the host does not list that model.
+func freeForModel(h config.Host, model string, inflight int) int {
+	m, ok := h.Models[model]
+	if !ok {
+		return 0
+	}
+	free := m.Parallel - inflight
+	if free < 0 {
+		return 0
+	}
+	return free
+}

internal/proxy/proxy.go

@@ -1,31 +1,34 @@
-// Package proxy is the routing reverse proxy. It takes /{route}/v1/…, picks a host from the
-// route's ordered list using the health table, forwards the request, streams the answer back as it
-// arrives, and tells the health table when a host fails.
+// Package proxy is the routing reverse proxy. It takes /{route}/v1/…, picks a host for the
+// conversation from its ordered list using a lease table (or the health table alone), queues per
+// (host, model), forwards the request streaming the answer back as it arrives, tees the response to
+// read usage/timings, marks a host down when a forward fails, and records one accounting row per
+// request.
 package proxy
 
 import (
 	"bytes"
-	"context"
 	"encoding/json"
 	"errors"
 	"io"
+	"log/slog"
 	"net/http"
-	"net/http/httputil"
-	"net/url"
 	"strings"
 	"time"
 
-	"log/slog"
-
 	"git.wntrmute.dev/kyle/crossbar/internal/config"
+	"git.wntrmute.dev/kyle/crossbar/internal/fingerprint"
 	"git.wntrmute.dev/kyle/crossbar/internal/health"
+	"git.wntrmute.dev/kyle/crossbar/internal/lease"
+	"git.wntrmute.dev/kyle/crossbar/internal/limiter"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
 )
 
-// MaxBody is the largest request body we look at for a top-level "model" field.
-const MaxBody = 16 << 20
-
-// HostHeader is set on every proxied response: the name of the host that answered.
-const HostHeader = "X-Crossbar-Host"
+const (
+	MaxBody     = 16 << 20
+	HostHeader  = "X-Crossbar-Host"
+	LeaseHeader = "X-Crossbar-Lease" // "new" or "reused"
+	RouteHeader = "X-Crossbar-Route" // client may name the route here instead of the path
+)
 
 // errBodyTooLarge is returned when a request body exceeds MaxBody during the model peek.
 var errBodyTooLarge = errors.New("body too large")
@@ -36,19 +39,30 @@ type Health interface {
 	MarkDown(name, reason string)
 }
 
-// Handler forwards requests for a route to one of the route's healthy hosts.
+// Recorder is what the proxy needs to write an accounting row; *store.Store satisfies it.
+type Recorder interface {
+	RecordRequest(store.Request) error
+}
+
+// Handler forwards requests for a route to one of the route's healthy hosts, choosing by lease when
+// one is configured and by health alone otherwise.
 type Handler struct {
 	cfg    *config.Config
 	health Health
+	leases *lease.Table
+	lim    *limiter.Limiter
+	rec    Recorder
 	log    *slog.Logger
 }
 
-// New builds a Handler. A nil logger becomes slog.Default().
-func New(cfg *config.Config, h Health, log *slog.Logger) *Handler {
+// New builds a Handler. A nil logger becomes slog.Default(). With a nil lease table it behaves like
+// the v0 proxy: first healthy host, no queueing, no recording; nil limiter and recorder are likewise
+// no-ops.
+func New(cfg *config.Config, h Health, leases *lease.Table, lim *limiter.Limiter, rec Recorder, log *slog.Logger) *Handler {
 	if log == nil {
 		log = slog.Default()
 	}
-	return &Handler{cfg: cfg, health: h, log: log}
+	return &Handler{cfg: cfg, health: h, leases: leases, lim: lim, rec: rec, log: log}
 }
 
 // SplitRoute takes the first path segment as the route. "/a/v1/x" -> ("a", "/v1/x", true); "/a" and
@@ -108,22 +122,57 @@ func allowedPath(rest string) bool {
 	return strings.HasPrefix(rest, "/v1/") || rest == "/health" || rest == "/props"
 }
 
-// peekModel reads a non-GET/HEAD body up to MaxBody+1 bytes, restores it on the request, and
-// returns the top-level "model". A non-JSON body or one without a model gives "". A body larger
-// than MaxBody returns errBodyTooLarge.
-func peekModel(r *http.Request) (string, error) {
+// route resolves the route name and the upstream path (rest) from the request, honouring the
+// optional route header. code is non-zero when the request must be answered; msg is the JSON error
+// text for that code.
+func (p *Handler) route(r *http.Request) (route, rest string, code int, msg string) {
+	hdr := r.Header.Get(RouteHeader)
+	if hdr != "" {
+		rest := r.URL.Path
+		// A path that also carries a (different) route name is a client mistake: the header is the
+		// operator's intent, but the path disagrees.
+		if rname, _, ok := SplitRoute(rest); ok {
+			if _, known := p.cfg.Routes[rname]; known && rname != hdr {
+				return "", "", http.StatusBadRequest, "conflicting route"
+			}
+		}
+		if _, known := p.cfg.Routes[hdr]; !known {
+			return "", "", http.StatusNotFound, "unknown route"
+		}
+		if !allowedPath(rest) {
+			return "", "", http.StatusNotFound, "not found"
+		}
+		return hdr, rest, 0, ""
+	}
+	route, rest, ok := SplitRoute(r.URL.Path)
+	if !ok {
+		return "", "", http.StatusBadRequest, "missing route"
+	}
+	if _, known := p.cfg.Routes[route]; !known {
+		return "", "", http.StatusNotFound, "unknown route"
+	}
+	if !allowedPath(rest) {
+		return "", "", http.StatusNotFound, "not found"
+	}
+	return route, rest, 0, ""
+}
+
+// peekModel reads a non-GET/HEAD body up to MaxBody+1 bytes, restores it on the request, and returns
+// the top-level "model" and the body itself (for fingerprinting). A non-JSON body or one without a
+// model gives "". A body larger than MaxBody returns errBodyTooLarge.
+func peekModel(r *http.Request) (string, []byte, error) {
 	if r.Method == http.MethodGet || r.Method == http.MethodHead {
-		return "", nil
+		return "", nil, nil
 	}
 	if r.Body == nil || r.Body == http.NoBody {
-		return "", nil
+		return "", nil, nil
 	}
 	body, err := io.ReadAll(io.LimitReader(r.Body, MaxBody+1))
 	if err != nil {
-		return "", err
+		return "", nil, err
 	}
 	if len(body) > MaxBody {
-		return "", errBodyTooLarge
+		return "", nil, errBodyTooLarge
 	}
 	r.Body = io.NopCloser(bytes.NewReader(body))
 	r.ContentLength = int64(len(body))
@@ -132,40 +181,21 @@ func peekModel(r *http.Request) (string, error) {
 		Model string `json:"model"`
 	}
 	_ = json.Unmarshal(body, &req)
-	return req.Model, nil
-}
-
-// statusRecorder records the status written and forwards Flush so the reverse proxy can stream.
-type statusRecorder struct {
-	http.ResponseWriter
-	status int
-}
-
-func (r *statusRecorder) WriteHeader(code int) {
-	r.status = code
-	r.ResponseWriter.WriteHeader(code)
-}
-
-func (r *statusRecorder) Flush() {
-	r.ResponseWriter.(http.Flusher).Flush()
+	return req.Model, body, nil
 }
 
+// ServeHTTP routes, fingerprints, leases a host, queues per (host, model), forwards with streaming,
+// tees the response for usage/timings, and records one accounting row. Every error answer is JSON
+// {"error":"…"}.
 func (p *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	route, rest, ok := SplitRoute(r.URL.Path)
-	if !ok {
-		p.writeError(w, http.StatusBadRequest, "missing route")
+	route, rest, code, msg := p.route(r)
+	if code != 0 {
+		p.writeError(w, code, msg)
 		return
 	}
-	routeCfg, ok := p.cfg.Routes[route]
-	if !ok {
-		p.writeError(w, http.StatusNotFound, "unknown route")
-		return
-	}
-	if !allowedPath(rest) {
-		p.writeError(w, http.StatusNotFound, "not found")
-		return
-	}
-	model, err := peekModel(r)
+	routeCfg := p.cfg.Routes[route]
+
+	model, body, err := peekModel(r)
 	if err != nil {
 		p.writeError(w, http.StatusRequestEntityTooLarge, "body too large")
 		return
@@ -173,68 +203,65 @@ func (p *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	if model == "" {
 		model = routeCfg.DefaultModel
 	}
-	name, ok := Choose(routeCfg.Hosts, model, p.health)
-	if !ok {
-		p.writeError(w, http.StatusServiceUnavailable, "no healthy host")
+	fp := fingerprint.Of(body)
+	started := time.Now()
+
+	// v0 compatibility path: no lease table, no limiter, no recording.
+	if p.leases == nil {
+		name, ok := Choose(routeCfg.Hosts, model, p.health)
+		if !ok {
+			p.writeError(w, http.StatusServiceUnavailable, "no healthy host")
+			return
+		}
+		p.forward(w, r, route, name, "", rest, fp, model, started, 0)
 		return
 	}
 
-	host, ok := p.cfg.Hosts[name]
-	if !ok {
-		p.writeError(w, http.StatusBadGateway, "upstream failed")
-		return
-	}
-	target, err := url.Parse(host.BaseURL)
+	// Lease. The route's ordered host list is the candidate set.
+	host, reused, err := p.leases.Acquire(lease.Key{Route: route, FP: fp, Model: model}, routeCfg.Hosts, time.Now())
 	if err != nil {
-		p.writeError(w, http.StatusBadGateway, "upstream failed")
+		switch {
+		case errors.Is(err, lease.ErrNoHost):
+			p.writeError(w, http.StatusServiceUnavailable, "no healthy host")
+		case errors.Is(err, lease.ErrPinnedDown):
+			p.writeError(w, http.StatusServiceUnavailable, "pinned host down")
+		default:
+			p.writeError(w, http.StatusBadGateway, "upstream failed")
+		}
 		return
 	}
 
-	pr := newReverseProxy(p.health, name, target, rest)
-	rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
-	start := time.Now()
-	pr.ServeHTTP(rec, r)
-	p.log.Info("request",
-		"route", route,
-		"host", name,
-		"method", r.Method,
-		"path", rest,
-		"status", rec.status,
-		"ms", time.Since(start).Milliseconds(),
-	)
-}
-
-func (p *Handler) writeError(w http.ResponseWriter, status int, msg string) {
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(map[string]string{"error": msg})
-}
-
-// newReverseProxy forwards to a single host, rewriting the path to target.Path+rest and keeping the
-// original query string. It flushes after every write so long server-sent-event streams are not
-// buffered, and marks the host down on any transport error other than a client disconnect.
-func newReverseProxy(h Health, name string, target *url.URL, rest string) *httputil.ReverseProxy {
-	return &httputil.ReverseProxy{
-		Rewrite: func(pr *httputil.ProxyRequest) {
-			pr.SetURL(target)
-			pr.Out.URL.Path = target.Path + rest
-			pr.Out.URL.RawPath = ""
-			pr.Out.Host = target.Host
-			pr.SetXForwarded()
-		},
-		FlushInterval: -1,
-		ModifyResponse: func(resp *http.Response) error {
-			resp.Header.Set(HostHeader, name)
-			return nil
-		},
-		ErrorHandler: func(w http.ResponseWriter, req *http.Request, err error) {
-			if errors.Is(err, context.Canceled) {
-				return
-			}
-			h.MarkDown(name, err.Error())
-			w.Header().Set("Content-Type", "application/json")
-			w.WriteHeader(http.StatusBadGateway)
-			_ = json.NewEncoder(w).Encode(map[string]string{"error": "upstream failed", "host": name})
-		},
+	// Slot. A full queue is a 503; a context done while waiting means the client left.
+	release, waited, err := p.lim.Acquire(r.Context(), host, model)
+	if err != nil {
+		if errors.Is(err, limiter.ErrQueueFull) {
+			p.writeRecord(store.Request{
+				Route:   route,
+				FP:      fp,
+				Model:   model,
+				Host:    host,
+				Started: started,
+				TotalMs: time.Since(started).Milliseconds(),
+				Status:  http.StatusServiceUnavailable,
+				Err:     "queue full",
+			})
+			p.writeError(w, http.StatusServiceUnavailable, "queue full")
+			return
+		}
+		p.log.Warn("request", "route", route, "host", host, "method", r.Method, "path", rest, "status", 499)
+		p.writeRecord(store.Request{
+			Route:   route,
+			FP:      fp,
+			Model:   model,
+			Host:    host,
+			Started: started,
+			TotalMs: time.Since(started).Milliseconds(),
+			Status:  499,
+			Err:     "client cancelled while queued",
+		})
+		return
 	}
+	defer release()
+
+	p.forward(w, r, route, host, leaseState(reused), rest, fp, model, started, waited)
 }

internal/proxy/proxy_test.go

@@ -1,318 +1,271 @@
 package proxy_test
 
+// v1 acceptance tests for the proxy: leases, queueing, accounting, header route override.
+// They drive the whole handler over real HTTP against fake upstreams; only what a client or an
+// operator can observe is asserted (status codes, headers, the accounting rows, the health table).
+// The rig, the fake upstream and the request helpers live in helpers_test.go.
+
 import (
 	"encoding/json"
-	"fmt"
-	"io"
 	"net/http"
-	"net/http/httptest"
 	"strings"
 	"sync"
 	"testing"
 	"time"
 
-	"git.wntrmute.dev/kyle/crossbar/internal/config"
-	"git.wntrmute.dev/kyle/crossbar/internal/health"
 	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
 )
 
-// fakeHealth is a hand-set health table that also records MarkDown calls.
-type fakeHealth struct {
-	mu     sync.Mutex
-	st     map[string]health.Status
-	marked []string
-}
-
-func (f *fakeHealth) Get(name string) (health.Status, bool) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	s, ok := f.st[name]
-	return s, ok
-}
-
-func (f *fakeHealth) MarkDown(name, reason string) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.marked = append(f.marked, name)
-	s := f.st[name]
-	s.Healthy = false
-	s.LastErr = reason
-	f.st[name] = s
-}
-
-func (f *fakeHealth) markedHosts() []string {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	return append([]string{}, f.marked...)
-}
-
-// upstream records what it received and answers with its name.
-type upstream struct {
-	name string
-	srv  *httptest.Server
-	mu   sync.Mutex
-	reqs []recorded
-}
-
-type recorded struct {
-	method, path, host, xff string
-	body                    string
-}
-
-func newUpstream(t *testing.T, name string) *upstream {
-	u := &upstream{name: name}
-	u.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		b, _ := io.ReadAll(r.Body)
-		u.mu.Lock()
-		u.reqs = append(u.reqs, recorded{r.Method, r.URL.RequestURI(), r.Host, r.Header.Get("X-Forwarded-For"), string(b)})
-		u.mu.Unlock()
-		w.Header().Set("Content-Type", "application/json")
-		fmt.Fprintf(w, `{"from":%q}`, name)
-	}))
-	t.Cleanup(u.srv.Close)
-	return u
-}
-
-func (u *upstream) last(t *testing.T) recorded {
-	u.mu.Lock()
-	defer u.mu.Unlock()
-	if len(u.reqs) == 0 {
-		t.Fatalf("%s: no request received", u.name)
+func TestConversationIsStickyAndLeaseHeaderTellsWhy(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	first := r.post("/r/v1/chat/completions", conversation(1, 1))
+	drain(first)
+	host := first.Header.Get(proxy.HostHeader)
+	if first.StatusCode != 200 || host != "beta" { // beta: same free slots, double weight
+		t.Fatalf("first turn: %d from %q, want 200 from beta", first.StatusCode, host)
+	}
+	if got := first.Header.Get(proxy.LeaseHeader); got != "new" {
+		t.Errorf("%s = %q on the first turn, want new", proxy.LeaseHeader, got)
+	}
+	// Take alpha's slots away as a "better host" signal: it must not matter, the lease holds.
+	for turn := 2; turn <= 6; turn++ {
+		resp := r.post("/r/v1/chat/completions", conversation(1, turn))
+		drain(resp)
+		if resp.Header.Get(proxy.HostHeader) != host || resp.Header.Get(proxy.LeaseHeader) != "reused" {
+			t.Fatalf("turn %d: host %q lease %q, want %q reused", turn, resp.Header.Get(proxy.HostHeader), resp.Header.Get(proxy.LeaseHeader), host)
+		}
+	}
+	if alpha.hits.Load() != 0 || beta.hits.Load() != 6 {
+		t.Errorf("hits alpha=%d beta=%d, want 0 and 6", alpha.hits.Load(), beta.hits.Load())
 	}
-	return u.reqs[len(u.reqs)-1]
 }
 
-func cfgFor(t *testing.T, alpha, beta string) *config.Config {
-	c, err := config.Parse(strings.NewReader(fmt.Sprintf(`
+// spreadHosts: beta is preferred (weight 10) until both of its "shared" slots are busy; then
+// alpha (2 free × 1) beats beta (0 free × 10), and a new conversation must start on alpha.
+const spreadHosts = `
 listen = "127.0.0.1:1"
+queue_max = 4
+lease_idle = "30m"
 [hosts.alpha]
 base_url = %q
-models = { "shared" = { }, "alpha-only" = { } }
+weight = 1.0
+models = { "shared" = { parallel = 2 } }
 [hosts.beta]
 base_url = %q
-models = { "shared" = { }, "beta-only" = { } }
+weight = 10.0
+models = { "shared" = { parallel = 2 } }
 [routes.r]
 hosts = ["alpha", "beta"]
 default_model = "shared"
-[routes.beta-first]
-hosts = ["beta", "alpha"]
-`, alpha, beta)))
-	if err != nil {
-		t.Fatal(err)
-	}
-	return c
-}
+`
 
-func healthy(loaded ...string) health.Status {
-	return health.Status{Healthy: true, Loaded: loaded, Consecutive: 1}
-}
-
-func TestSplitRoute(t *testing.T) {
-	for _, tc := range []struct {
-		path, route, rest string
-		ok                bool
-	}{
-		{"/a/v1/x", "a", "/v1/x", true},
-		{"/a/v1/x?q=1", "a", "/v1/x?q=1", true},
-		{"/a", "a", "/", true},
-		{"/a/", "a", "/", true},
-		{"/opencode-a/v1/chat/completions", "opencode-a", "/v1/chat/completions", true},
-		{"/", "", "", false},
-		{"//x", "", "", false},
-		{"", "", "", false},
-		{"noslash/v1", "", "", false},
-	} {
-		route, rest, ok := proxy.SplitRoute(tc.path)
-		if route != tc.route || rest != tc.rest || ok != tc.ok {
-			t.Errorf("SplitRoute(%q) = %q %q %v, want %q %q %v", tc.path, route, rest, ok, tc.route, tc.rest, tc.ok)
-		}
-	}
-}
-
-func TestChoose(t *testing.T) {
-	h := &fakeHealth{st: map[string]health.Status{
-		"down":  {Healthy: false, Loaded: []string{"m"}},
-		"alpha": healthy("shared", "alpha-only"),
-		"beta":  healthy("shared", "beta-only"),
-	}}
-	hosts := []string{"down", "alpha", "beta"}
-	if got, ok := proxy.Choose(hosts, "", h); !ok || got != "alpha" {
-		t.Errorf("no model: %q %v, want alpha (first healthy)", got, ok)
-	}
-	if got, ok := proxy.Choose(hosts, "beta-only", h); !ok || got != "beta" {
-		t.Errorf("beta-only: %q %v, want beta (has the model loaded)", got, ok)
-	}
-	if got, ok := proxy.Choose(hosts, "nobody-has-it", h); !ok || got != "alpha" {
-		t.Errorf("unknown model falls back to the first healthy host: %q %v", got, ok)
-	}
-	if got, ok := proxy.Choose([]string{"down", "missing"}, "m", h); ok {
-		t.Errorf("no healthy host must give ok=false, got %q", got)
-	}
-	if got, ok := proxy.Choose(nil, "m", h); ok {
-		t.Errorf("empty hosts: %q %v", got, ok)
-	}
-}
-
-func TestRoutesToFirstHealthyAndRewrites(t *testing.T) {
+func TestDifferentConversationsSpreadByFreeSlots(t *testing.T) {
 	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
-	h := &fakeHealth{st: map[string]health.Status{"alpha": healthy("shared"), "beta": healthy("shared")}}
-	p := proxy.New(cfgFor(t, alpha.srv.URL, beta.srv.URL), h, nil)
-	rec := httptest.NewRecorder()
-	req := httptest.NewRequest(http.MethodGet, "http://crossbar.local:7777/r/v1/models?x=1", nil)
-	req.RemoteAddr = "10.9.8.7:5555"
-	p.ServeHTTP(rec, req)
-	if rec.Code != 200 || rec.Header().Get(proxy.HostHeader) != "alpha" {
-		t.Fatalf("status %d host %q body %s", rec.Code, rec.Header().Get(proxy.HostHeader), rec.Body.String())
-	}
-	got := alpha.last(t)
-	if got.path != "/v1/models?x=1" {
-		t.Errorf("upstream path = %q, want route stripped and query kept", got.path)
-	}
-	if got.host != strings.TrimPrefix(alpha.srv.URL, "http://") {
-		t.Errorf("Host header = %q, want the upstream's %q", got.host, strings.TrimPrefix(alpha.srv.URL, "http://"))
-	}
-	if got.xff != "10.9.8.7" {
-		t.Errorf("X-Forwarded-For = %q, want the client address", got.xff)
-	}
-	if !strings.Contains(rec.Body.String(), `"from":"alpha"`) {
-		t.Errorf("body = %s", rec.Body.String())
-	}
-}
-
-func TestModelPreferenceAndBodyPassThrough(t *testing.T) {
-	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
-	h := &fakeHealth{st: map[string]health.Status{"alpha": healthy("shared", "alpha-only"), "beta": healthy("shared", "beta-only")}}
-	p := proxy.New(cfgFor(t, alpha.srv.URL, beta.srv.URL), h, nil)
-	body := `{"model":"beta-only","messages":[{"role":"user","content":"hi"}],"stream":false}`
-	rec := httptest.NewRecorder()
-	p.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/r/v1/chat/completions", strings.NewReader(body)))
-	if rec.Code != 200 || rec.Header().Get(proxy.HostHeader) != "beta" {
-		t.Fatalf("status %d host %q", rec.Code, rec.Header().Get(proxy.HostHeader))
-	}
-	if got := beta.last(t); got.body != body || got.method != http.MethodPost {
-		t.Errorf("upstream got %+v; the body must arrive unchanged after the model peek", got)
-	}
-	// Not JSON: no model, the route default ("shared") applies, first healthy wins.
-	rec = httptest.NewRecorder()
-	p.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/r/v1/embeddings", strings.NewReader("plain text")))
-	if rec.Header().Get(proxy.HostHeader) != "alpha" {
-		t.Errorf("non-JSON body: host %q, want alpha", rec.Header().Get(proxy.HostHeader))
-	}
-	if got := alpha.last(t); got.body != "plain text" {
-		t.Errorf("non-JSON body must pass through unchanged, got %q", got.body)
-	}
-}
-
-func TestFailoverOnUpstreamError(t *testing.T) {
-	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
-	h := &fakeHealth{st: map[string]health.Status{"alpha": healthy("shared"), "beta": healthy("shared")}}
-	p := proxy.New(cfgFor(t, alpha.srv.URL, beta.srv.URL), h, nil)
-	alpha.srv.Close() // health still believes alpha is up
-	rec := httptest.NewRecorder()
-	p.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/r/v1/models", nil))
-	if rec.Code != http.StatusBadGateway {
-		t.Fatalf("first request after alpha died: %d, want 502", rec.Code)
-	}
-	var e map[string]string
-	if err := json.Unmarshal(rec.Body.Bytes(), &e); err != nil || e["error"] != "upstream failed" || e["host"] != "alpha" {
-		t.Errorf("502 body = %s", rec.Body.String())
-	}
-	if m := h.markedHosts(); len(m) != 1 || m[0] != "alpha" {
-		t.Errorf("MarkDown calls = %v, want [alpha]", m)
-	}
-	rec = httptest.NewRecorder()
-	p.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/r/v1/models", nil))
-	if rec.Code != 200 || rec.Header().Get(proxy.HostHeader) != "beta" {
-		t.Errorf("second request: %d %q, want 200 from beta", rec.Code, rec.Header().Get(proxy.HostHeader))
-	}
-}
-
-func TestErrors(t *testing.T) {
-	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
-	h := &fakeHealth{st: map[string]health.Status{"alpha": {Healthy: false}, "beta": {Healthy: false}}}
-	p := proxy.New(cfgFor(t, alpha.srv.URL, beta.srv.URL), h, nil)
-	for _, tc := range []struct {
-		name, method, path string
-		body               io.Reader
-		want               int
-		msg                string
-	}{
-		{"bare slash", http.MethodGet, "/", nil, 400, "missing route"},
-		{"double slash", http.MethodGet, "//v1/models", nil, 400, "missing route"},
-		{"unknown route", http.MethodGet, "/nope/v1/models", nil, 404, "unknown route"},
-		{"disallowed path", http.MethodGet, "/r/slots", nil, 404, "not found"},
-		{"admin through proxy", http.MethodGet, "/r/_crossbar/hosts", nil, 404, "not found"},
-		{"no healthy host", http.MethodGet, "/r/v1/models", nil, 503, "no healthy host"},
-		{"body too large", http.MethodPost, "/r/v1/chat/completions", strings.NewReader(strings.Repeat("x", proxy.MaxBody+1)), 413, "body too large"},
-	} {
-		rec := httptest.NewRecorder()
-		p.ServeHTTP(rec, httptest.NewRequest(tc.method, tc.path, tc.body))
-		if rec.Code != tc.want {
-			t.Errorf("%s: status %d, want %d", tc.name, rec.Code, tc.want)
-		}
-		var e map[string]string
-		if err := json.Unmarshal(rec.Body.Bytes(), &e); err != nil || e["error"] != tc.msg {
-			t.Errorf("%s: body %s, want error %q", tc.name, rec.Body.String(), tc.msg)
-		}
-		if !strings.HasPrefix(rec.Header().Get("Content-Type"), "application/json") {
-			t.Errorf("%s: errors are JSON", tc.name)
-		}
-	}
-	if len(h.markedHosts()) != 0 {
-		t.Errorf("errors before choosing a host must not mark anything down: %v", h.markedHosts())
-	}
-}
-
-// TestStreamingIsNotBuffered: the upstream writes one chunk, flushes, and then waits until the
-// test has *read* that chunk. If the proxy buffered, the read would never complete.
-func TestStreamingIsNotBuffered(t *testing.T) {
-	release := make(chan struct{})
-	up := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "text/event-stream")
-		w.WriteHeader(200)
-		fmt.Fprint(w, "data: first\n\n")
-		w.(http.Flusher).Flush()
-		select {
-		case <-release:
-		case <-time.After(5 * time.Second):
-		}
-		fmt.Fprint(w, "data: second\n\n")
-	}))
-	t.Cleanup(up.Close)
-	beta := newUpstream(t, "beta")
-	h := &fakeHealth{st: map[string]health.Status{"alpha": healthy("shared"), "beta": healthy("shared")}}
-	front := httptest.NewServer(proxy.New(cfgFor(t, up.URL, beta.srv.URL), h, nil))
-	t.Cleanup(front.Close)
-
-	resp, err := http.Post(front.URL+"/r/v1/chat/completions", "application/json", strings.NewReader(`{"model":"shared","stream":true}`))
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer resp.Body.Close()
-	buf := make([]byte, 64)
-	done := make(chan string, 1)
-	go func() {
-		n, err := resp.Body.Read(buf)
-		if err != nil {
-			done <- "read error: " + err.Error()
-			return
-		}
-		done <- string(buf[:n])
-	}()
-	select {
-	case got := <-done:
-		if !strings.HasPrefix(got, "data: first") {
-			t.Fatalf("first read = %q", got)
-		}
-	case <-time.After(2 * time.Second):
-		t.Fatal("the first chunk did not arrive before the upstream finished: the proxy buffers")
-	}
-	close(release)
-	rest, _ := io.ReadAll(resp.Body)
-	if !strings.Contains(string(rest), "data: second") {
-		t.Errorf("rest = %q", rest)
+	beta.delay = 400 * time.Millisecond
+	r := newRig(t, spreadHosts, alpha, beta)
+	// Two slow conversations occupy beta's two "shared" slots…
+	var wg sync.WaitGroup
+	for i := 1; i <= 2; i++ {
+		wg.Add(1)
+		go func(i int) { defer wg.Done(); drain(r.post("/r/v1/chat/completions", conversation(i, 1))) }(i)
+		time.Sleep(50 * time.Millisecond) // arrive one after the other so both pick beta (10 > 2)
 	}
+	time.Sleep(50 * time.Millisecond)
+	// …so a third conversation starting now is sent to alpha (beta has 0 free slots, alpha 2).
+	resp := r.post("/r/v1/chat/completions", conversation(3, 1))
+	drain(resp)
 	if resp.Header.Get(proxy.HostHeader) != "alpha" {
-		t.Errorf("host header %q", resp.Header.Get(proxy.HostHeader))
+		t.Errorf("third conversation went to %q, want alpha (free slots beat weight)", resp.Header.Get(proxy.HostHeader))
+	}
+	wg.Wait()
+	if beta.hits.Load() != 2 || alpha.hits.Load() != 1 {
+		t.Errorf("hits beta=%d alpha=%d, want 2 and 1", beta.hits.Load(), alpha.hits.Load())
+	}
+}
+
+func TestQueueFullIs503(t *testing.T) {
+	alpha := newUpstream(t, "alpha")
+	alpha.delay = 400 * time.Millisecond
+	r := newRig(t, `
+listen = "127.0.0.1:1"
+queue_max = 1
+[hosts.alpha]
+base_url = %q
+models = { "shared" = { parallel = 1 } }
+[routes.r]
+hosts = ["alpha"]
+default_model = "shared"
+`, alpha)
+	codes := make(chan int, 3)
+	for i := 1; i <= 3; i++ {
+		go func(i int) {
+			resp := r.post("/r/v1/chat/completions", conversation(i, 1))
+			drain(resp)
+			codes <- resp.StatusCode
+		}(i)
+		time.Sleep(30 * time.Millisecond) // arrival order: 1 runs, 2 queues, 3 finds the queue full
+	}
+	got := map[int]int{}
+	for i := 0; i < 3; i++ {
+		got[<-codes]++
+	}
+	if got[200] != 2 || got[503] != 1 {
+		t.Fatalf("status counts = %v, want two 200 and one 503", got)
+	}
+	// Rows are written after each response completes; allow the store a moment to catch up.
+	var rows []store.UsageRow
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		rows, _ = r.store.Usage(time.Time{}, store.ByRoute)
+		if len(rows) == 1 && rows[0].Requests == 3 {
+			break
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	if len(rows) != 1 || rows[0].Requests != 3 || rows[0].Errors != 1 {
+		t.Fatalf("usage = %+v, want 3 requests, 1 error (the 503 is recorded too)", rows)
+	}
+	if rows[0].QueuedMs <= 0 {
+		t.Errorf("the queued request must record its wait: %+v", rows[0])
+	}
+}
+
+func TestUnhealthyHostReleasesAndMoves(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	drain(r.post("/r/v1/chat/completions", conversation(1, 1))) // lands on beta
+	beta.srv.Close()
+	resp := r.post("/r/v1/chat/completions", conversation(1, 2))
+	drain(resp)
+	if resp.StatusCode != http.StatusBadGateway {
+		t.Fatalf("first request after beta died: %d, want 502", resp.StatusCode)
+	}
+	if s, _ := r.health.Get("beta"); s.Healthy {
+		t.Fatalf("beta must be marked down after the 502")
+	}
+	resp = r.post("/r/v1/chat/completions", conversation(1, 3))
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.HostHeader) != "alpha" || resp.Header.Get(proxy.LeaseHeader) != "new" {
+		t.Errorf("after the move: %d from %q lease %q, want 200 alpha new", resp.StatusCode, resp.Header.Get(proxy.HostHeader), resp.Header.Get(proxy.LeaseHeader))
+	}
+	ev, _ := r.store.Events(time.Time{}, 10)
+	var reasons []string
+	for _, e := range ev {
+		reasons = append(reasons, e.Reason)
+	}
+	if len(reasons) != 2 || reasons[0] != store.ReasonNew || reasons[1] != store.ReasonUnhealthy {
+		t.Errorf("lease events = %v, want [new unhealthy]", reasons)
+	}
+}
+
+func TestAccountingRowsFromUsageAndTimings(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	drain(r.post("/r/v1/chat/completions", conversation(1, 1)))                                                        // non-streamed
+	drain(r.post("/r/v1/chat/completions", strings.Replace(conversation(1, 2), `"stream":false`, `"stream":true`, 1))) // streamed
+	deadline := time.Now().Add(2 * time.Second)
+	var rows []store.UsageRow
+	for time.Now().Before(deadline) {
+		rows, _ = r.store.Usage(time.Time{}, store.ByHost)
+		if len(rows) == 1 && rows[0].Requests == 2 {
+			break
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	if len(rows) != 1 || rows[0].Requests != 2 {
+		t.Fatalf("usage by host = %+v, want one host with 2 requests (rows may be written after the response completes, within 2 s)", rows)
+	}
+	u := rows[0]
+	if u.PromptTokens != 300 || u.CachedTokens != 240 || u.CompletionTokens != 30 {
+		t.Errorf("tokens = prompt %d cached %d completion %d, want 300/240/30 (100+200, 90+150, 10+20)", u.PromptTokens, u.CachedTokens, u.CompletionTokens)
+	}
+	if u.BusyMs <= 0 || u.Errors != 0 {
+		t.Errorf("busy %d errors %d", u.BusyMs, u.Errors)
+	}
+	if got := u.CacheHitRatio(); got < 0.79 || got > 0.81 {
+		t.Errorf("cache hit ratio = %v, want 0.8", got)
+	}
+}
+
+func TestStreamIsUnalteredWhileTeed(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	resp := r.post("/r/v1/chat/completions", strings.Replace(conversation(9, 1), `"stream":false`, `"stream":true`, 1))
+	body := drain(resp)
+	want := 0
+	for _, line := range strings.Split(body, "\n") {
+		if strings.HasPrefix(line, "data: ") {
+			want++
+		}
+	}
+	if want != 5 || !strings.HasSuffix(strings.TrimSpace(body), "data: [DONE]") {
+		t.Errorf("client must receive every SSE line untouched (3 deltas, usage, DONE); got %d data lines:\n%s", want, body)
+	}
+}
+
+func TestHeaderRouteOverride(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	// The header names the route; the path has none.
+	resp := r.post("/v1/chat/completions", conversation(1, 1), proxy.RouteHeader, "other")
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.HostHeader) != "alpha" {
+		t.Errorf("header route 'other' (alpha only): %d from %q", resp.StatusCode, resp.Header.Get(proxy.HostHeader))
+	}
+	if alpha.lastReq().path != "/v1/chat/completions" {
+		t.Errorf("upstream path = %q", alpha.lastReq().path)
+	}
+	// A path route and a header route that disagree: the header is the operator's intent → 400.
+	resp = r.post("/r/v1/chat/completions", conversation(1, 1), proxy.RouteHeader, "other")
+	if drain(resp); resp.StatusCode != 400 {
+		t.Errorf("conflicting route in path and header: %d, want 400", resp.StatusCode)
+	}
+	resp = r.post("/v1/chat/completions", conversation(1, 1), proxy.RouteHeader, "nope")
+	if drain(resp); resp.StatusCode != 404 {
+		t.Errorf("unknown header route: %d, want 404", resp.StatusCode)
+	}
+}
+
+func TestV0BehaviourStillHolds(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	for _, tc := range []struct {
+		method, path string
+		want         int
+		msg          string
+	}{
+		{http.MethodGet, "/", 400, "missing route"},
+		{http.MethodGet, "/nope/v1/models", 404, "unknown route"},
+		{http.MethodGet, "/r/slots", 404, "not found"},
+		{http.MethodGet, "/r/_crossbar/hosts", 404, "not found"},
+	} {
+		req, _ := http.NewRequest(tc.method, r.front.URL+tc.path, nil)
+		resp, err := http.DefaultClient.Do(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		body := drain(resp)
+		var e map[string]string
+		if resp.StatusCode != tc.want || json.Unmarshal([]byte(body), &e) != nil || e["error"] != tc.msg {
+			t.Errorf("%s: %d %s, want %d %q", tc.path, resp.StatusCode, body, tc.want, tc.msg)
+		}
+	}
+	big := strings.Repeat("x", proxy.MaxBody+1)
+	resp := r.post("/r/v1/chat/completions", big)
+	if drain(resp); resp.StatusCode != 413 {
+		t.Errorf("oversize body: %d, want 413", resp.StatusCode)
+	}
+	// GET pass-through with query string, Host and X-Forwarded-For as in v0.
+	resp, err := http.Get(r.front.URL + "/r/v1/models?x=1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	drain(resp)
+	host := resp.Header.Get(proxy.HostHeader)
+	u := map[string]*upstream{"alpha": alpha, "beta": beta}[host]
+	if u == nil || u.lastReq().path != "/v1/models?x=1" || u.lastReq().host != strings.TrimPrefix(u.srv.URL, "http://") || u.lastReq().xff == "" {
+		t.Errorf("GET pass-through: host %q last %+v", host, u.lastReq())
 	}
 }

internal/proxy/recorder_test.go

@@ -0,0 +1,66 @@
+package proxy_test
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+	"git.wntrmute.dev/kyle/crossbar/internal/health"
+	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+)
+
+// noFlush is a ResponseWriter that does not implement http.Flusher. Middleware and test
+// recorders like this exist in the wild; the proxy must degrade to buffering, never panic.
+type noFlush struct{ w http.ResponseWriter }
+
+func (n noFlush) Header() http.Header         { return n.w.Header() }
+func (n noFlush) Write(b []byte) (int, error) { return n.w.Write(b) }
+func (n noFlush) WriteHeader(code int)        { n.w.WriteHeader(code) }
+
+func TestStreamingWriterWithoutFlusherDoesNotPanic(t *testing.T) {
+	up := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/event-stream")
+		w.WriteHeader(200)
+		for i := 0; i < 3; i++ {
+			fmt.Fprintf(w, "data: chunk %d\n\n", i)
+			w.(http.Flusher).Flush()
+		}
+	}))
+	t.Cleanup(up.Close)
+	cfg, err := config.Parse(strings.NewReader(fmt.Sprintf(`
+listen = "127.0.0.1:1"
+[hosts.alpha]
+base_url = %q
+models = { "m" = { } }
+[routes.r]
+hosts = ["alpha"]
+`, up.URL)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	h := &fakeHealth{st: map[string]health.Status{"alpha": {Healthy: true, Loaded: []string{"m"}}}}
+	p := proxy.New(cfg, h, nil, nil, nil, nil)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/r/v1/chat/completions", strings.NewReader(`{"model":"m","stream":true}`))
+	func() {
+		defer func() {
+			if r := recover(); r != nil {
+				t.Fatalf("ServeHTTP panicked on a writer without Flush: %v", r)
+			}
+		}()
+		p.ServeHTTP(noFlush{rec}, req)
+	}()
+	if rec.Code != 200 {
+		t.Fatalf("status %d", rec.Code)
+	}
+	if got := rec.Body.String(); !strings.Contains(got, "chunk 0") || !strings.Contains(got, "chunk 2") {
+		t.Errorf("body = %q, want all three chunks", got)
+	}
+	if rec.Header().Get(proxy.HostHeader) != "alpha" {
+		t.Errorf("host header %q", rec.Header().Get(proxy.HostHeader))
+	}
+}

internal/proxy/tee.go

@@ -0,0 +1,147 @@
+package proxy
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"sync"
+)
+
+// maxParseBody bounds the non-streamed JSON body accumulated to extract usage/timings: beyond it we
+// record no tokens rather than hold an unbounded body in memory.
+const maxParseBody = 1 << 20 // 1 MiB
+
+// usageTimings is the last usage/timings object seen in a stream, or the single object parsed from a
+// non-streamed JSON body.
+type usageTimings struct {
+	hasUsage   bool
+	usage      struct{ prompt, completion int }
+	hasTimings bool
+	timings    struct{ promptN, cacheN, predictedN int }
+}
+
+// tokens resolves the recorded usage and timings to the three counts the accounting row needs.
+// prompt and completion come from usage when present, else from timings; cached comes only from
+// timings.
+func (u *usageTimings) tokens() (prompt, cached, completion int) {
+	if u.hasUsage {
+		prompt = u.usage.prompt
+		completion = u.usage.completion
+	} else if u.hasTimings {
+		prompt = u.timings.promptN
+		completion = u.timings.predictedN
+	}
+	if u.hasTimings {
+		cached = u.timings.cacheN
+	}
+	return
+}
+
+// tee wraps a response body, passing every byte through unchanged while scanning for usage/timings.
+// For a text/event-stream body it scans complete data: lines and remembers the last object seen; for
+// anything else it accumulates the body (bounded) and parses it once at Close.
+type tee struct {
+	body     io.Reader
+	closed   bool
+	streamed bool
+	pending  []byte
+	buf      bytes.Buffer
+	mu       sync.Mutex
+	last     usageTimings
+}
+
+func newTee(r io.Reader, streamed bool) *tee {
+	return &tee{body: r, streamed: streamed}
+}
+
+// Read reads from the upstream body and feeds the bytes to the scanner without holding any back.
+func (t *tee) Read(b []byte) (int, error) {
+	n, err := t.body.Read(b)
+	if n > 0 {
+		t.ingest(b[:n])
+	}
+	return n, err
+}
+
+// ingest routes a fresh chunk to the streamed scanner or the non-streamed accumulator.
+func (t *tee) ingest(p []byte) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	if t.streamed {
+		t.scanSSE(p)
+		return
+	}
+	if t.buf.Len() < maxParseBody {
+		t.buf.Write(p)
+	}
+}
+
+// scanSSE splits complete lines off the pending buffer and parses each "data: " line.
+func (t *tee) scanSSE(p []byte) {
+	t.pending = append(t.pending, p...)
+	for {
+		i := bytes.IndexByte(t.pending, '\n')
+		if i < 0 {
+			return
+		}
+		line := t.pending[:i]
+		t.pending = t.pending[i+1:]
+		if bytes.HasPrefix(line, []byte("data: ")) {
+			t.parseData(line[len("data: "):])
+		}
+	}
+}
+
+// parseData decodes one data line's JSON object and remembers its usage and/or timings.
+func (t *tee) parseData(data []byte) {
+	var doc struct {
+		Usage *struct {
+			PromptTokens     int `json:"prompt_tokens"`
+			CompletionTokens int `json:"completion_tokens"`
+		} `json:"usage"`
+		Timings *struct {
+			PromptN    int `json:"prompt_n"`
+			CacheN     int `json:"cache_n"`
+			PredictedN int `json:"predicted_n"`
+		} `json:"timings"`
+	}
+	if err := json.Unmarshal(data, &doc); err != nil {
+		return
+	}
+	if doc.Usage != nil {
+		t.last.hasUsage = true
+		t.last.usage.prompt = doc.Usage.PromptTokens
+		t.last.usage.completion = doc.Usage.CompletionTokens
+	}
+	if doc.Timings != nil {
+		t.last.hasTimings = true
+		t.last.timings.promptN = doc.Timings.PromptN
+		t.last.timings.cacheN = doc.Timings.CacheN
+		t.last.timings.predictedN = doc.Timings.PredictedN
+	}
+}
+
+// Close closes the underlying body, parsing a non-streamed JSON body once at the end.
+func (t *tee) Close() error {
+	t.mu.Lock()
+	if t.closed {
+		t.mu.Unlock()
+		return nil
+	}
+	t.closed = true
+	if !t.streamed && t.buf.Len() > 0 {
+		t.parseData(t.buf.Bytes())
+	}
+	t.mu.Unlock()
+	if c, ok := t.body.(io.Closer); ok {
+		return c.Close()
+	}
+	return nil
+}
+
+// tokens returns the last usage/timings seen, if any.
+func (t *tee) tokens() (prompt, cached, completion int) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return t.last.tokens()
+}

internal/store/schema.go

@@ -0,0 +1,168 @@
+package store
+
+import (
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"time"
+)
+
+// schema is the durable layout: the lease table, the lease-event log, the
+// per-request accounting rows, the host-health poll log, and the daily
+// rollup that Prune writes into. Times are Unix milliseconds.
+const schema = `
+CREATE TABLE IF NOT EXISTS leases (
+    route     TEXT NOT NULL,
+    fp        TEXT NOT NULL,
+    model     TEXT NOT NULL,
+    host      TEXT NOT NULL,
+    state     TEXT NOT NULL,
+    created   INTEGER NOT NULL,
+    last_used INTEGER NOT NULL,
+    PRIMARY KEY (route, fp, model)
+);
+CREATE TABLE IF NOT EXISTS lease_events (
+    ts        INTEGER NOT NULL,
+    route     TEXT NOT NULL,
+    model     TEXT NOT NULL,
+    from_host TEXT NOT NULL,
+    to_host   TEXT NOT NULL,
+    reason    TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS requests (
+    id                INTEGER PRIMARY KEY,
+    route             TEXT NOT NULL,
+    fp                TEXT NOT NULL,
+    model             TEXT NOT NULL,
+    host              TEXT NOT NULL,
+    started           INTEGER NOT NULL,
+    queued_ms         INTEGER NOT NULL,
+    ttfb_ms           INTEGER NOT NULL,
+    total_ms          INTEGER NOT NULL,
+    status            INTEGER NOT NULL,
+    streamed          INTEGER NOT NULL,
+    prompt_tokens     INTEGER NOT NULL,
+    cached_tokens     INTEGER NOT NULL,
+    completion_tokens INTEGER NOT NULL,
+    err               TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS host_health (
+    ts            INTEGER NOT NULL,
+    host          TEXT NOT NULL,
+    healthy       INTEGER NOT NULL,
+    loaded_models TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS requests_daily (
+    day               INTEGER NOT NULL,
+    route             TEXT NOT NULL,
+    model             TEXT NOT NULL,
+    host              TEXT NOT NULL,
+    requests          INTEGER NOT NULL,
+    errors            INTEGER NOT NULL,
+    busy_ms           INTEGER NOT NULL,
+    queued_ms         INTEGER NOT NULL,
+    prompt_tokens     INTEGER NOT NULL,
+    cached_tokens     INTEGER NOT NULL,
+    completion_tokens INTEGER NOT NULL,
+    PRIMARY KEY (day, route, model, host)
+);
+`
+
+// byColumn maps a grouping to its table column, rejecting anything else.
+func byColumn(b By) (string, error) {
+	switch b {
+	case ByRoute:
+		return "route", nil
+	case ByModel:
+		return "model", nil
+	case ByHost:
+		return "host", nil
+	default:
+		return "", fmt.Errorf("store: unknown grouping %q", b)
+	}
+}
+
+// midnight returns UTC midnight of the day holding ms.
+func midnight(ms int64) int64 {
+	return time.UnixMilli(ms).Truncate(24 * time.Hour).UnixMilli()
+}
+
+// btoi converts a bool to 0/1 for storage.
+func btoi(b bool) int64 {
+	if b {
+		return 1
+	}
+	return 0
+}
+
+// encodeLoaded serialises a Loaded slice as JSON, writing nil as [].
+func encodeLoaded(loaded []string) ([]byte, error) {
+	if loaded == nil {
+		loaded = []string{}
+	}
+	return json.Marshal(loaded)
+}
+
+// wrap prefixes a driver error with the package name.
+func wrap(err error) error {
+	if err == nil {
+		return nil
+	}
+	return fmt.Errorf("store: %w", err)
+}
+
+func scanLeases(rows *sql.Rows) ([]Lease, error) {
+	var out []Lease
+	for rows.Next() {
+		var (
+			l             Lease
+			created, last int64
+		)
+		if err := rows.Scan(&l.Route, &l.FP, &l.Model, &l.Host, (*string)(&l.State), &created, &last); err != nil {
+			return nil, wrap(err)
+		}
+		l.Created = time.UnixMilli(created).UTC()
+		l.LastUsed = time.UnixMilli(last).UTC()
+		out = append(out, l)
+	}
+	return out, rows.Err()
+}
+
+func scanUsage(rows *sql.Rows) ([]UsageRow, error) {
+	var out []UsageRow
+	for rows.Next() {
+		var u UsageRow
+		if err := rows.Scan(&u.Key, &u.Requests, &u.Errors, &u.BusyMs, &u.QueuedMs,
+			&u.PromptTokens, &u.CachedTokens, &u.CompletionTokens); err != nil {
+			return nil, wrap(err)
+		}
+		out = append(out, u)
+	}
+	return out, rows.Err()
+}
+
+func scanStatusCounts(rows *sql.Rows) ([]StatusCount, error) {
+	var out []StatusCount
+	for rows.Next() {
+		var c StatusCount
+		if err := rows.Scan(&c.Route, &c.Host, &c.Status, &c.Count); err != nil {
+			return nil, wrap(err)
+		}
+		out = append(out, c)
+	}
+	return out, rows.Err()
+}
+
+func scanEvents(rows *sql.Rows) ([]LeaseEvent, error) {
+	var out []LeaseEvent
+	for rows.Next() {
+		var e LeaseEvent
+		var ts int64
+		if err := rows.Scan(&ts, &e.Route, &e.Model, &e.FromHost, &e.ToHost, (*string)(&e.Reason)); err != nil {
+			return nil, wrap(err)
+		}
+		e.TS = time.UnixMilli(ts).UTC()
+		out = append(out, e)
+	}
+	return out, rows.Err()
+}

internal/store/store.go

@@ -0,0 +1,373 @@
+// Package store is crossbar's durable state: the lease table and the
+// accounting log (requests, lease events, host-health polls) with rollup
+// queries that answer per-route / per-model / per-host usage. All times are
+// stored as Unix milliseconds (INTEGER) and returned as time.Time in UTC.
+package store
+
+import (
+	"database/sql"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	_ "modernc.org/sqlite"
+)
+
+// State is the lease's placement state.
+type State string
+
+const (
+	Active State = "active"
+	Pinned State = "pinned"
+)
+
+// Reasons a lease event carries.
+const (
+	ReasonNew       = "new"
+	ReasonUnhealthy = "unhealthy"
+	ReasonIdle      = "idle"
+	ReasonPin       = "pin"
+	ReasonRelease   = "release"
+	ReasonDrain     = "drain"
+)
+
+// By selects the grouping column of a Usage query.
+type By string
+
+const (
+	ByRoute By = "route"
+	ByModel By = "model"
+	ByHost  By = "host"
+)
+
+// Lease is one routed model on one host.
+type Lease struct {
+	Route, FP, Model, Host string
+	State                  State
+	Created, LastUsed      time.Time
+}
+
+// LeaseEvent records a change to a lease.
+type LeaseEvent struct {
+	TS                             time.Time
+	Route, Model, FromHost, ToHost string
+	Reason                         string
+}
+
+// Request is one proxied request, for the accounting log.
+type Request struct {
+	Route, FP, Model, Host                       string
+	Started                                      time.Time
+	QueuedMs, TTFBMs, TotalMs                    int64
+	Status                                       int
+	Streamed                                     bool
+	PromptTokens, CachedTokens, CompletionTokens int64
+	Err                                          string
+}
+
+// HostHealth is one poller observation of a host.
+type HostHealth struct {
+	TS      time.Time
+	Host    string
+	Healthy bool
+	Loaded  []string
+}
+
+// UsageRow is one group of a Usage query.
+type UsageRow struct {
+	Key              string `json:"key"`
+	Requests         int64  `json:"requests"`
+	Errors           int64  `json:"errors"`
+	BusyMs           int64  `json:"busy_ms"`
+	QueuedMs         int64  `json:"queued_ms"`
+	PromptTokens     int64  `json:"prompt_tokens"`
+	CachedTokens     int64  `json:"cached_tokens"`
+	CompletionTokens int64  `json:"completion_tokens"`
+}
+
+// CacheHitRatio is CachedTokens / PromptTokens, or 0 when there were no prompt
+// tokens to spend.
+func (u UsageRow) CacheHitRatio() float64 {
+	if u.PromptTokens == 0 {
+		return 0
+	}
+	return float64(u.CachedTokens) / float64(u.PromptTokens)
+}
+
+// StatusCount is one (route, host, status) group of live requests, for the metrics endpoint, which
+// needs the per-status breakdown Usage cannot give.
+type StatusCount struct {
+	Route, Host string
+	Status      int
+	Count       int64
+}
+
+// Store holds the SQLite connection to crossbar's durable state.
+type Store struct {
+	db *sql.DB
+}
+
+// Open connects to path in WAL mode and creates the tables if they are missing.
+// It fails if the directory that holds the file does not exist.
+func Open(path string) (*Store, error) {
+	if dir := filepath.Dir(path); dir != "" {
+		if _, err := os.Stat(dir); err != nil {
+			return nil, fmt.Errorf("store: %s: %w", dir, err)
+		}
+	}
+	db, err := sql.Open("sqlite", "file:"+path+"?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)")
+	if err != nil {
+		return nil, wrap(err)
+	}
+	if _, err := db.Exec(schema); err != nil {
+		_ = db.Close()
+		return nil, wrap(err)
+	}
+	return &Store{db: db}, nil
+}
+
+// Close releases the connection.
+func (s *Store) Close() error {
+	return wrap(s.db.Close())
+}
+
+// JournalMode reports the active journal mode ("wal").
+func (s *Store) JournalMode() string {
+	var mode string
+	_ = s.db.QueryRow(`PRAGMA journal_mode`).Scan(&mode)
+	return mode
+}
+
+// SaveLease inserts or replaces a lease on (route, fp, model).
+func (s *Store) SaveLease(l Lease) error {
+	_, err := s.db.Exec(`
+		INSERT OR REPLACE INTO leases (route, fp, model, host, state, created, last_used)
+		VALUES (?, ?, ?, ?, ?, ?, ?)`,
+		l.Route, l.FP, l.Model, l.Host, string(l.State),
+		l.Created.UnixMilli(), l.LastUsed.UnixMilli())
+	return wrap(err)
+}
+
+// DeleteLease removes the lease identified by (route, fp, model).
+func (s *Store) DeleteLease(route, fp, model string) error {
+	_, err := s.db.Exec(`DELETE FROM leases WHERE route = ? AND fp = ? AND model = ?`, route, fp, model)
+	return wrap(err)
+}
+
+// ListLeases returns every lease, ordered by (route, fp, model).
+func (s *Store) ListLeases() ([]Lease, error) {
+	rows, err := s.db.Query(`
+		SELECT route, fp, model, host, state, created, last_used
+		FROM leases ORDER BY route, fp, model`)
+	if err != nil {
+		return nil, wrap(err)
+	}
+	defer rows.Close()
+	return scanLeases(rows)
+}
+
+// RecordEvent appends a lease event.
+func (s *Store) RecordEvent(e LeaseEvent) error {
+	_, err := s.db.Exec(`
+		INSERT INTO lease_events (ts, route, model, from_host, to_host, reason)
+		VALUES (?, ?, ?, ?, ?, ?)`,
+		e.TS.UnixMilli(), e.Route, e.Model, e.FromHost, e.ToHost, e.Reason)
+	return wrap(err)
+}
+
+// RecordRequest appends one request to the accounting log.
+func (s *Store) RecordRequest(r Request) error {
+	_, err := s.db.Exec(`
+		INSERT INTO requests (route, fp, model, host, started, queued_ms, ttfb_ms, total_ms, status, streamed, prompt_tokens, cached_tokens, completion_tokens, err)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		r.Route, r.FP, r.Model, r.Host,
+		r.Started.UnixMilli(), r.QueuedMs, r.TTFBMs, r.TotalMs,
+		r.Status, btoi(r.Streamed),
+		r.PromptTokens, r.CachedTokens, r.CompletionTokens, r.Err)
+	return wrap(err)
+}
+
+// RecordHostHealth appends one host-health observation.
+func (s *Store) RecordHostHealth(h HostHealth) error {
+	b, err := encodeLoaded(h.Loaded)
+	if err != nil {
+		return wrap(err)
+	}
+	_, err = s.db.Exec(`
+		INSERT INTO host_health (ts, host, healthy, loaded_models)
+		VALUES (?, ?, ?, ?)`,
+		h.TS.UnixMilli(), h.Host, btoi(h.Healthy), string(b))
+	return wrap(err)
+}
+
+// Usage sums requests at or after since, grouped by by. A zero since means all
+// time. It counts the live requests table plus the requests_daily rollup whose
+// day is at or after since. Results are ordered by Key.
+func (s *Store) Usage(since time.Time, by By) ([]UsageRow, error) {
+	col, err := byColumn(by)
+	if err != nil {
+		return nil, err
+	}
+	sinceMs := since.UnixMilli()
+	query := `
+	SELECT key,
+	       SUM(requests)  AS requests,
+	       SUM(errors)    AS errors,
+	       SUM(busy_ms)   AS busy_ms,
+	       SUM(queued_ms) AS queued_ms,
+	       SUM(prompt_tokens)     AS prompt_tokens,
+	       SUM(cached_tokens)     AS cached_tokens,
+	       SUM(completion_tokens) AS completion_tokens
+	FROM (
+		SELECT ` + col + ` AS key, 1 AS requests,
+		       CASE WHEN status >= 400 THEN 1 ELSE 0 END AS errors,
+		       total_ms AS busy_ms, queued_ms,
+		       prompt_tokens, cached_tokens, completion_tokens
+		FROM requests WHERE started >= ?
+		UNION ALL
+		SELECT ` + col + ` AS key, requests, errors, busy_ms, queued_ms,
+		       prompt_tokens, cached_tokens, completion_tokens
+		FROM requests_daily WHERE day >= ?
+	)
+	GROUP BY key
+	ORDER BY key`
+	rows, err := s.db.Query(query, sinceMs, sinceMs)
+	if err != nil {
+		return nil, wrap(err)
+	}
+	defer rows.Close()
+	return scanUsage(rows)
+}
+
+// StatusCounts groups the live requests at or after since by (route, host, status). It reads the
+// requests table only; the rolled-up requests_daily rows are not in it (Prune has moved them out of
+// requests), so counts cover only traffic still in the live table.
+func (s *Store) StatusCounts(since time.Time) ([]StatusCount, error) {
+	sinceMs := since.UnixMilli()
+	rows, err := s.db.Query(`
+		SELECT route, host, status, COUNT(*)
+		FROM requests WHERE started >= ?
+		GROUP BY route, host, status
+		ORDER BY route, host, status`, sinceMs)
+	if err != nil {
+		return nil, wrap(err)
+	}
+	defer rows.Close()
+	return scanStatusCounts(rows)
+}
+
+// Events returns lease events at or after since, oldest first, at most limit.
+func (s *Store) Events(since time.Time, limit int) ([]LeaseEvent, error) {
+	rows, err := s.db.Query(`
+		SELECT ts, route, model, from_host, to_host, reason
+		FROM lease_events WHERE ts >= ?
+		ORDER BY ts ASC LIMIT ?`, since.UnixMilli(), limit)
+	if err != nil {
+		return nil, wrap(err)
+	}
+	defer rows.Close()
+	return scanEvents(rows)
+}
+
+// Prune moves every request older than now-retention into requests_daily (adding
+// into the existing daily row for that day/route/model/host), deletes the live
+// rows, and returns how many were removed. All in one transaction.
+func (s *Store) Prune(now time.Time, retention time.Duration) (int64, error) {
+	threshold := now.Add(-retention).UnixMilli()
+	tx, err := s.db.Begin()
+	if err != nil {
+		return 0, wrap(err)
+	}
+	defer func() { _ = tx.Rollback() }()
+
+	rows, err := tx.Query(`
+		SELECT route, model, host, started, total_ms, queued_ms,
+		       status, prompt_tokens, cached_tokens, completion_tokens
+		FROM requests WHERE started < ?`, threshold)
+	if err != nil {
+		_ = tx.Rollback()
+		return 0, wrap(err)
+	}
+
+	type bucket struct {
+		day   int64
+		route string
+		model string
+		host  string
+	}
+	type agg struct {
+		requests int64
+		errors   int64
+		busyMs   int64
+		queuedMs int64
+		prompt   int64
+		cached   int64
+		done     int64
+	}
+	aggs := map[bucket]*agg{}
+	count := int64(0)
+	for rows.Next() {
+		var (
+			route, model, host   string
+			started              int64
+			totalMs, queuedMs    int64
+			status               int
+			prompt, cached, done int64
+		)
+		if err := rows.Scan(&route, &model, &host, &started, &totalMs, &queuedMs, &status, &prompt, &cached, &done); err != nil {
+			_ = rows.Close()
+			_ = tx.Rollback()
+			return 0, wrap(err)
+		}
+		count++
+		k := bucket{day: midnight(started), route: route, model: model, host: host}
+		a := aggs[k]
+		if a == nil {
+			a = &agg{}
+			aggs[k] = a
+		}
+		a.requests++
+		if status >= 400 {
+			a.errors++
+		}
+		a.busyMs += totalMs
+		a.queuedMs += queuedMs
+		a.prompt += prompt
+		a.cached += cached
+		a.done += done
+	}
+	if err := rows.Err(); err != nil {
+		_ = rows.Close()
+		_ = tx.Rollback()
+		return 0, wrap(err)
+	}
+	_ = rows.Close()
+
+	upsert := `
+		INSERT INTO requests_daily (day, route, model, host, requests, errors, busy_ms, queued_ms, prompt_tokens, cached_tokens, completion_tokens)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		ON CONFLICT (day, route, model, host) DO UPDATE SET
+			requests          = requests          + excluded.requests,
+			errors            = errors            + excluded.errors,
+			busy_ms           = busy_ms           + excluded.busy_ms,
+			queued_ms         = queued_ms         + excluded.queued_ms,
+			prompt_tokens     = prompt_tokens     + excluded.prompt_tokens,
+			cached_tokens     = cached_tokens     + excluded.cached_tokens,
+			completion_tokens = completion_tokens + excluded.completion_tokens`
+	for k, a := range aggs {
+		if _, err := tx.Exec(upsert, k.day, k.route, k.model, k.host,
+			a.requests, a.errors, a.busyMs, a.queuedMs, a.prompt, a.cached, a.done); err != nil {
+			_ = tx.Rollback()
+			return 0, wrap(err)
+		}
+	}
+	if _, err := tx.Exec(`DELETE FROM requests WHERE started < ?`, threshold); err != nil {
+		_ = tx.Rollback()
+		return 0, wrap(err)
+	}
+	if err := tx.Commit(); err != nil {
+		return 0, wrap(err)
+	}
+	return count, nil
+}

internal/store/store_test.go

@@ -0,0 +1,185 @@
+package store_test
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+func open(t *testing.T, dir string) *store.Store {
+	s, err := store.Open(filepath.Join(dir, "crossbar.db"))
+	if err != nil {
+		t.Fatalf("Open: %v", err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+	return s
+}
+
+func TestOpenIsIdempotentAndWAL(t *testing.T) {
+	dir := t.TempDir()
+	s := open(t, dir)
+	if got := s.JournalMode(); got != "wal" {
+		t.Errorf("journal_mode = %q, want wal", got)
+	}
+	if err := s.Close(); err != nil {
+		t.Fatal(err)
+	}
+	open(t, dir) // second open on the same file must not fail on existing tables
+}
+
+func TestLeasesSurviveReopen(t *testing.T) {
+	dir := t.TempDir()
+	s := open(t, dir)
+	now := time.Date(2026, 9, 25, 10, 0, 0, 0, time.UTC)
+	l := store.Lease{Route: "opencode-a", FP: "abc", Model: "m", Host: "alpha", State: store.Active, Created: now, LastUsed: now}
+	if err := s.SaveLease(l); err != nil {
+		t.Fatal(err)
+	}
+	l2 := l
+	l2.FP = "def"
+	l2.Host = "beta"
+	l2.State = store.Pinned
+	if err := s.SaveLease(l2); err != nil {
+		t.Fatal(err)
+	}
+	// Saving the same key again replaces, not duplicates.
+	l.Host = "beta"
+	l.LastUsed = now.Add(time.Minute)
+	if err := s.SaveLease(l); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.Close(); err != nil {
+		t.Fatal(err)
+	}
+	s = open(t, dir)
+	got, err := s.ListLeases()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 2 {
+		t.Fatalf("ListLeases = %d rows, want 2: %+v", len(got), got)
+	}
+	byFP := map[string]store.Lease{}
+	for _, x := range got {
+		byFP[x.FP] = x
+	}
+	if a := byFP["abc"]; a.Host != "beta" || !a.LastUsed.Equal(now.Add(time.Minute)) || a.State != store.Active {
+		t.Errorf("abc = %+v", a)
+	}
+	if d := byFP["def"]; d.State != store.Pinned || d.Host != "beta" {
+		t.Errorf("def = %+v", d)
+	}
+	if err := s.DeleteLease("opencode-a", "abc", "m"); err != nil {
+		t.Fatal(err)
+	}
+	got, _ = s.ListLeases()
+	if len(got) != 1 || got[0].FP != "def" {
+		t.Errorf("after delete: %+v", got)
+	}
+}
+
+func TestEventsAndRequestsAndUsage(t *testing.T) {
+	s := open(t, t.TempDir())
+	t0 := time.Date(2026, 9, 25, 10, 0, 0, 0, time.UTC)
+	must := func(err error) {
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	must(s.RecordEvent(store.LeaseEvent{TS: t0, Route: "r1", Model: "m", FromHost: "", ToHost: "alpha", Reason: store.ReasonNew}))
+	must(s.RecordEvent(store.LeaseEvent{TS: t0.Add(time.Hour), Route: "r1", Model: "m", FromHost: "alpha", ToHost: "beta", Reason: store.ReasonUnhealthy}))
+	reqs := []store.Request{
+		{Route: "r1", FP: "a", Model: "m", Host: "alpha", Started: t0, QueuedMs: 0, TTFBMs: 100, TotalMs: 1000, Status: 200, Streamed: true, PromptTokens: 1000, CachedTokens: 900, CompletionTokens: 50},
+		{Route: "r1", FP: "a", Model: "m", Host: "alpha", Started: t0.Add(time.Minute), QueuedMs: 40, TTFBMs: 120, TotalMs: 2000, Status: 200, Streamed: true, PromptTokens: 1100, CachedTokens: 1000, CompletionTokens: 60},
+		{Route: "r2", FP: "b", Model: "m", Host: "beta", Started: t0.Add(2 * time.Minute), TotalMs: 500, Status: 502, Err: "upstream failed"},
+		{Route: "r2", FP: "b", Model: "m", Host: "beta", Started: t0.Add(-48 * time.Hour), TotalMs: 300, Status: 200, PromptTokens: 10, CompletionTokens: 5},
+	}
+	for _, r := range reqs {
+		must(s.RecordRequest(r))
+	}
+	must(s.RecordHostHealth(store.HostHealth{TS: t0, Host: "alpha", Healthy: true, Loaded: []string{"m"}}))
+
+	rows, err := s.Usage(t0.Add(-time.Hour), store.ByRoute)
+	must(err)
+	if len(rows) != 2 {
+		t.Fatalf("Usage by route since t0-1h: %d rows, want 2 (r1, r2): %+v", len(rows), rows)
+	}
+	byKey := map[string]store.UsageRow{}
+	for _, r := range rows {
+		byKey[r.Key] = r
+	}
+	r1 := byKey["r1"]
+	if r1.Requests != 2 || r1.Errors != 0 || r1.BusyMs != 3000 || r1.QueuedMs != 40 {
+		t.Errorf("r1 = %+v", r1)
+	}
+	if r1.PromptTokens != 2100 || r1.CachedTokens != 1900 || r1.CompletionTokens != 110 {
+		t.Errorf("r1 tokens = %+v", r1)
+	}
+	if got := r1.CacheHitRatio(); got < 0.904 || got > 0.905 {
+		t.Errorf("r1 cache hit ratio = %v, want 1900/2100", got)
+	}
+	r2 := byKey["r2"]
+	if r2.Requests != 1 || r2.Errors != 1 || r2.BusyMs != 500 {
+		t.Errorf("r2 = %+v (the 48h-old request is outside since)", r2)
+	}
+	if r2.CacheHitRatio() != 0 {
+		t.Errorf("no prompt tokens: ratio must be 0, got %v", r2.CacheHitRatio())
+	}
+	byHost, err := s.Usage(time.Time{}, store.ByHost)
+	must(err)
+	if len(byHost) != 2 {
+		t.Errorf("by host, all time: %+v", byHost)
+	}
+	for _, r := range byHost {
+		if r.Key == "beta" && r.Requests != 2 {
+			t.Errorf("beta all-time requests = %d, want 2", r.Requests)
+		}
+	}
+	byModel, err := s.Usage(time.Time{}, store.ByModel)
+	must(err)
+	if len(byModel) != 1 || byModel[0].Key != "m" || byModel[0].Requests != 4 {
+		t.Errorf("by model: %+v", byModel)
+	}
+	ev, err := s.Events(t0.Add(-time.Minute), 10)
+	must(err)
+	if len(ev) != 2 || ev[0].Reason != store.ReasonNew || ev[1].ToHost != "beta" {
+		t.Errorf("events = %+v", ev)
+	}
+}
+
+func TestPruneRollsUpOldRequests(t *testing.T) {
+	s := open(t, t.TempDir())
+	t0 := time.Date(2026, 9, 25, 10, 0, 0, 0, time.UTC)
+	old := t0.Add(-200 * 24 * time.Hour)
+	for i := 0; i < 3; i++ {
+		if err := s.RecordRequest(store.Request{Route: "r", Model: "m", Host: "h", Started: old.Add(time.Duration(i) * time.Minute), TotalMs: 100, Status: 200, PromptTokens: 10, CachedTokens: 5, CompletionTokens: 1}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := s.RecordRequest(store.Request{Route: "r", Model: "m", Host: "h", Started: t0, TotalMs: 100, Status: 200}); err != nil {
+		t.Fatal(err)
+	}
+	n, err := s.Prune(t0, 180*24*time.Hour)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n != 3 {
+		t.Errorf("Prune removed %d rows, want 3", n)
+	}
+	rows, _ := s.Usage(time.Time{}, store.ByRoute)
+	if len(rows) != 1 || rows[0].Requests != 4 || rows[0].PromptTokens != 30 {
+		t.Errorf("usage must still include pruned traffic through the daily rollup: %+v", rows)
+	}
+	live, _ := s.Usage(old.Add(24*time.Hour), store.ByRoute)
+	if len(live) != 1 || live[0].Requests != 1 {
+		t.Errorf("recent-only usage = %+v", live)
+	}
+}
+
+func TestBadPath(t *testing.T) {
+	if _, err := store.Open(filepath.Join(t.TempDir(), "no", "such", "dir", "x.db")); err == nil {
+		t.Fatal("Open must fail when the directory does not exist")
+	}
+}

tools/smoke.sh

@@ -1,45 +1,80 @@
 #!/bin/sh
-# Smoke run: two fake upstreams, one crossbar, real HTTP. Prints "smoke: ok" or fails.
-# Needs: bin/crossbar and bin/fakeupstream (make build), curl.
+# Smoke run (v1): two fake upstreams, one crossbar with a fresh SQLite file, real HTTP.
+# Checks routing, leases (sticky + header), failover, recovery, streaming, queueing, pin, drain,
+# usage and metrics. Prints "smoke: ok" or fails with the crossbar log.
 set -eu
 cd "$(dirname "$0")/.."
 tmp=$(mktemp -d); trap 'kill $pids 2>/dev/null; rm -rf "$tmp"' EXIT INT TERM
 pids=""
-bin/fakeupstream -listen 127.0.0.1:18081 -name alpha -models ornith-1.5-35b-a3b,small-9b -down-file "$tmp/alpha.down" >"$tmp/alpha.log" 2>&1 & pids="$pids $!"
+sed "s#^db .*#db = \"$tmp/crossbar.db\"#" example.toml > "$tmp/crossbar.toml"
+bin/fakeupstream -listen 127.0.0.1:18081 -name alpha -models ornith-1.5-35b-a3b,small-9b -down-file "$tmp/alpha.down" -slow 600 >"$tmp/alpha.log" 2>&1 & pids="$pids $!"
 bin/fakeupstream -listen 127.0.0.1:18082 -name beta  -models ornith-1.5-35b-a3b -down-file "$tmp/beta.down" >"$tmp/beta.log" 2>&1 & pids="$pids $!"
-bin/crossbar -config example.toml >"$tmp/crossbar.log" 2>&1 & pids="$pids $!"
+bin/crossbar -config "$tmp/crossbar.toml" >"$tmp/crossbar.log" 2>&1 & pids="$pids $!"
 sleep 1.5
 fail() { echo "smoke: FAIL: $*" >&2; echo "--- crossbar.log"; cat "$tmp/crossbar.log"; exit 1; }
 base=http://127.0.0.1:17777
+conv() { printf '{"model":"ornith-1.5-35b-a3b","stream":false,"messages":[{"role":"system","content":"smoke"},{"role":"user","content":"conversation %s"}]}' "$1"; }
+hdrs() { curl -s -o /dev/null -w '%{http_code} %header{X-Crossbar-Host} %header{X-Crossbar-Lease}' "$@"; }
 
-h=$(curl -s -o /dev/null -w '%{http_code} %header{X-Crossbar-Host}' "$base/opencode-a/v1/models")
-[ "$h" = "200 alpha" ] || fail "opencode-a should go to alpha, got '$h'"
-h=$(curl -s -o /dev/null -w '%{http_code} %header{X-Crossbar-Host}' "$base/hermes-x/v1/models")
-[ "$h" = "200 beta" ] || fail "hermes-x should go to beta, got '$h'"
-h=$(curl -s -o /dev/null -w '%{http_code}' "$base/nope/v1/models")
-[ "$h" = "404" ] || fail "unknown route should be 404, got '$h'"
+# 1. a conversation gets a lease and keeps it; beta wins (2 slots × weight 2 vs 1 × 1)
+h=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv A)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 beta new" ] || fail "first turn should be '200 beta new', got '$h'"
+h=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv A)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 beta reused" ] || fail "second turn should reuse beta, got '$h'"
 
-touch "$tmp/alpha.down"; sleep 2.5   # poll_interval is 1s in example.toml
-h=$(curl -s -o /dev/null -w '%{http_code} %header{X-Crossbar-Host}' "$base/opencode-a/v1/models")
-[ "$h" = "200 beta" ] || fail "with alpha down, opencode-a should fail over to beta, got '$h'"
-curl -s "$base/_crossbar/hosts" | grep -q '"alpha":{"healthy":false' || fail "/_crossbar/hosts does not show alpha unhealthy: $(curl -s $base/_crossbar/hosts)"
+# 2. header route
+h=$(hdrs -X POST -H 'Content-Type: application/json' -H 'X-Crossbar-Route: hermes-x' -d "$(conv B)" "$base/v1/chat/completions")
+case "$h" in "200 beta new") ;; *) fail "header route hermes-x should be '200 beta new', got '$h'";; esac
+h=$(curl -s -o /dev/null -w '%{http_code}' "$base/nope/v1/models"); [ "$h" = "404" ] || fail "unknown route 404, got $h"
 
-rm "$tmp/alpha.down"; sleep 3.5     # recovery needs two good polls
-h=$(curl -s -o /dev/null -w '%header{X-Crossbar-Host}' "$base/opencode-a/v1/models")
-[ "$h" = "alpha" ] || fail "alpha should be back after two good polls, got '$h'"
+# 3. pin opencode-a to alpha: conversation A's next turn moves (an operator pin outranks the lease)
+h=$(curl -s -o /dev/null -w '%{http_code}' -X POST -H 'Content-Type: application/json' -d '{"host":"alpha","pin":true}' "$base/_crossbar/routes/opencode-a")
+[ "$h" = "200" ] || fail "pin returned $h"
+h=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv A)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 alpha new" ] || fail "after pin, conversation A should be '200 alpha new', got '$h'"
+curl -s "$base/_crossbar/routes" | grep -q '"pinned":"alpha"' || fail "routes view does not show the pin: $(curl -s $base/_crossbar/routes)"
 
-# Streaming: five chunks 200 ms apart must arrive over >= 0.6 s, not all at once at the end.
+# 4. queue: alpha has parallel 1, queue_max 1, and answers in 600 ms → of three concurrent, one is 503
+for i in 1 2 3; do (curl -s -o /dev/null -w '%{http_code}\n' -X POST -H 'Content-Type: application/json' -d "$(conv Q$i)" "$base/opencode-a/v1/chat/completions" >> "$tmp/codes") & sleep 0.1; done; wait $! 2>/dev/null || true
+sleep 2.5
+sort "$tmp/codes" | uniq -c | tr -s ' ' > "$tmp/counts"
+grep -q '2 200' "$tmp/counts" && grep -q '1 503' "$tmp/counts" || fail "queue test wanted two 200 and one 503, got: $(cat "$tmp/counts")"
+
+# 5. release the pin, drain alpha: new conversations go to beta, A stays on alpha
+curl -s -o /dev/null -X POST -H 'Content-Type: application/json' -d '{"release":true}' "$base/_crossbar/routes/opencode-a"
+h=$(curl -s -o /dev/null -w '%{http_code}' -X POST -H 'Content-Type: application/json' -d '{"drain":true}' "$base/_crossbar/hosts/alpha"); [ "$h" = "200" ] || fail "drain returned $h"
+h=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv C)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 beta new" ] || fail "with alpha draining a new conversation should go to beta, got '$h'"
+curl -s "$base/_crossbar/hosts" | grep -q '"alpha":{[^}]*"draining":true' || fail "hosts view does not show alpha draining"
+curl -s -o /dev/null -X POST -H 'Content-Type: application/json' -d '{"drain":false}' "$base/_crossbar/hosts/alpha"
+
+# 6. failover + recovery
+touch "$tmp/beta.down"; sleep 2.5
+h=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv C)" "$base/opencode-a/v1/chat/completions")
+[ "$h" = "200 alpha new" ] || fail "with beta down conversation C should move to alpha, got '$h'"
+curl -s "$base/_crossbar/hosts" | grep -q '"beta":{"healthy":false' || fail "hosts view does not show beta unhealthy"
+rm "$tmp/beta.down"; sleep 3.5
+curl -s "$base/_crossbar/hosts" | grep -q '"beta":{"healthy":true' || fail "beta did not recover after two good polls"
+
+# 7. streaming still arrives incrementally, and the final usage chunk is untouched
 start=$(date +%s%N)
-first=""
-curl -sN -X POST -H 'Content-Type: application/json' -d '{"model":"ornith-1.5-35b-a3b","stream":true,"messages":[]}' \
+curl -sN -X POST -H 'Content-Type: application/json' -d '{"model":"ornith-1.5-35b-a3b","stream":true,"messages":[{"role":"user","content":"stream me"}]}' \
   "$base/opencode-a/v1/chat/completions" | while IFS= read -r line; do
     [ -n "$line" ] || continue
     now=$(date +%s%N); echo "$(( (now - start) / 1000000 )) $line"
   done > "$tmp/stream.txt"
 firstms=$(head -1 "$tmp/stream.txt" | cut -d' ' -f1); lastms=$(tail -1 "$tmp/stream.txt" | cut -d' ' -f1)
-[ -n "$firstms" ] && [ "$((lastms - firstms))" -ge 600 ] || fail "stream arrived in one burst (first ${firstms:-?} ms, last ${lastms:-?} ms):
-$(cat "$tmp/stream.txt")"
-grep -q 'DONE' "$tmp/stream.txt" || fail "stream did not end with [DONE]"
+[ -n "$firstms" ] && [ "$((lastms - firstms))" -ge 600 ] || fail "stream arrived in one burst: $(cat "$tmp/stream.txt")"
+grep -q '"usage"' "$tmp/stream.txt" && grep -q 'DONE' "$tmp/stream.txt" || fail "stream lost the usage chunk or DONE"
 
-grep -q 'route=opencode-a host=alpha' "$tmp/crossbar.log" || fail "no request log line"
+# 8. accounting and metrics
+sleep 1
+u=$(curl -s "$base/_crossbar/usage?by=host")
+echo "$u" | grep -q '"key":"alpha"' && echo "$u" | grep -q '"key":"beta"' || fail "usage by host: $u"
+echo "$u" | grep -q '"cached_tokens":[1-9]' || fail "usage has no cached tokens (SSE/JSON usage not captured): $u"
+curl -s -H 'Accept: text/plain' "$base/_crossbar/usage?by=route" | grep -qi 'cache' || fail "text usage table missing"
+m=$(curl -s "$base/_crossbar/metrics")
+echo "$m" | grep -q 'crossbar_requests_total{route="opencode-a",host="alpha",status="503"} 1' || fail "metrics missing the 503: $m"
+echo "$m" | grep -q 'crossbar_host_healthy{host="beta"} 1' || fail "metrics missing host health"
+grep -q 'route=opencode-a host=' "$tmp/crossbar.log" || fail "no request log line"
 echo "smoke: ok (stream spread $((lastms - firstms)) ms)"