v2.3 review: drop a duplicate logIdentityMode call; README wording; review notes

Co-Authored-By: Claude Opus 5.5 <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,27 @@ 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.
+- Never change when production code releases, flushes or records something just to make a
+  given test's timing pass. If a given test seems to check a value before the code could
+  settle it (a deferred release, a row written after the answer), that is the owner's test
+  bug: stop and report it. (v2.3 task 02 released every slot at the first flushed byte to
+  satisfy such a test, and the limiter silently stopped limiting streams.)
+
 ## The gate
 
 `make gate` must print `gate: ok` before a task is done. It runs offline: `gofmt -l`, `go vet`,
@@ -52,6 +76,10 @@ touched before the gate. `go test ./internal/<pkg>/` runs one package.
 - Work on the branch the task names. One task is one commit.
 - Stage only the paths the task lists: `git add <path> ...`. Never `git add -A` or `git add .`.
 - Never push, amend, rebase, reset, or switch to another branch.
+- A commit message with more than one line goes in `.state/commit-msg.txt` (inside the
+  repository and ignored by git; `/tmp` is refused) and is committed with
+  `git commit -F .state/commit-msg.txt`. An apostrophe inside a single-quoted `-m '…'` breaks
+  the shell command.
 - Commit message: the subject line the task gives, a blank line, then this trailer:
   `Implemented-By: OpenCode session (model recorded in docs/implementer-log.md)`
 
@@ -67,6 +95,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,13 +49,22 @@ 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. |
+| `routes.<name>.affinity` | `"conversation"` (default, one lease per conversation) or `"route"` (one lease for the whole route); see "Clients that manage their own slots". |
+| `routes.<name>.queue` | `false` leaves queueing to the client's own llama-server slot; the default counts requests in crossbar's per-(host, model) queue. |
+| `routes.<name>.listen` | A host:port for the route's own listener, every request there is this route; see "Clients that manage their own slots". |
+| `identity` | `"off"` (default), `"tailscale"`, or `"header"`; see below. |
+| `hosts.<name>.wake` | A wake-on-LAN target (`mac`, `broadcast`, `wait`) so crossbar can rouse a sleeping host when nothing else can take a new lease. |
+| `routes.<name>.peers` | The tailnet nodes allowed to reach the route, with `identity = "tailscale"`; see below. |
 
 ## Run
 
@@ -84,23 +99,157 @@ 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:
+## Clients that manage their own slots
 
-```json
-{"hermes-x":{"hosts":["beta","alpha"],"default_model":""},"opencode-a":{"hosts":["alpha","beta"],"default_model":"ornith-1.5-35b-a3b"}}
+Some clients connect to one crossbar address and manage a llama-server slot themselves: they pin
+`id_slot`, poll `/slots`, and steer a running completion through
+`/v1/chat/completions/control`. Boxmaker's `inferproxy` is one. crossbar serves such a
+client from a route that has its own `listen` address and `affinity = "route"`, so the whole route
+lives on one host:
+
+```toml
+# a client that manages its own llama-server slot (it pins id_slot, polls /slots, steers a
+# running completion through /v1/chat/completions/control) and cannot put a route in the path.
+# The route gets its own port; every request there is this route and the path goes upstream as is.
+[routes.boxmaker-a]
+hosts         = ["beta", "alpha"]
+default_model = "ornith-1.5-35b-a3b"
+listen        = "127.0.0.1:17801"      # a tailnet address in production; never the main listen address
+affinity      = "route"                # one lease for the whole route, not one per conversation
+queue         = false                  # counted as load but never held or refused: the server's own slot queue does that
 ```
 
-## What v0 does not do
+Every request to that address is this route, with its whole path passed upstream unchanged (there is
+no route segment to strip), so it runs through `Handler.ForRoute` rather than the usual
+`/{route}/` path. The address must split into a host and a numeric port, be unique across routes,
+not equal the top-level `listen`, and not be on a template route — crossbar refuses any of those at
+start-up.
 
-Leases and stickiness, SQLite, `/slots`, queueing and wake-on-LAN are out of scope for v0; see
-`PLAN.md`.
+A few things about how crossbar treats those requests:
+
+- **Control calls take no slot.** A GET or HEAD on any allowed path, and a POST to exactly
+  `/tokenize` or `/v1/chat/completions/control`, is a control call. It follows the route's single
+  lease but takes no slot, skips the context guard, and writes no accounting row: it is sent beside
+  its own stream, so it must never wait for or hold a slot. A chat completion on `/v1/chat/completions`
+  is not a control call.
+- **`/slots` and `/tokenize` are proxied; `/slots/<id>` actions are not.** Only the bare `/slots`
+  path is allowed, so an action on a specific slot id is not forwarded.
+- **A GET's model comes from its `?model=` query** (there is no body to read), which is how
+  `/slots?model=shared` learns which model's slots to report.
+- **The admin API is not served on a route listener.** `/_crossbar/hosts` there, and any prefixed
+  path such as `/boxmaker-a/v1/models`, are 404.
+
+## 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, drain state and the context sizes the poller learned (`n_ctx`/`slots` from a single
+server's `/props`, `models` per loaded model from `/props?model=`; 0 or absent means unknown):
+
+```json
+{"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,"n_ctx":0,"slots":0,"models":{"ornith-1.5-35b-a3b":{"n_ctx":262144,"slots":4},"small-9b":{"n_ctx":32768,"slots":2}}},"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,"n_ctx":131072,"slots":2,"models":{}}}
+```
+
+On a llama-server **router** only models whose `status.value` is `"loaded"` count as loaded, and
+crossbar asks `/props?model=X` only for those: asking about an unloaded model would make the
+router load it.
+
+`GET /_crossbar/routes` reports each route's candidate hosts, default model, any pin and its live
+leases:
+
+```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
+```
+
+## Context guard
+
+With unified KV a host's usable context per request is its context size divided by its slots.
+crossbar estimates a chat request's size from its body (bytes/4 with a margin) and compares it
+with the leased host's per-slot context for that model. A prompt that fits stays put. One that
+does not fit is moved to a healthy host on the route where it does fit (the lease moves with
+it, so the conversation stays there), and the response carries
+`X-Crossbar-Ctx: moved:<from>` + `>` + `<to>` — for example `moved:small>big`. When no host can
+fit it, the answer is a `400` in llama-server's own overflow shape, so a client that handles the
+server's error handles crossbar's refusal too:
+
+```json
+{"error":{"code":400,"type":"exceed_context_size_error","message":"prompt too large","n_prompt_tokens":<tokens>,"n_ctx":<largest per-slot context among hosts that have the model loaded>}}
+```
+
+Hosts whose context is unknown are never blocked by the guard.
+
+## Wake
+
+When a route has no healthy host left and at least one candidate lists a `wake` target, crossbar
+sends that host a wake-on-LAN magic packet, in route order, and retries the lease once. A host that
+wakes up takes the conversation; if none wakes, the request gets `503 {"error":"no healthy host",
+"woke":["<hosts tried>"]}`. The context-size guard wakes a sleeping host the same way before it
+answers `400 prompt too large`, when no healthy host's per-slot context can fit the prompt.
+
+## Identity
+
+`identity` gates who may use a route. With the default `"off"` every request is admitted. With
+`"tailscale"`, a route that lists `peers` answers `403` to any caller whose tailnet address is not
+one of them (checked with `tailscale whois`):
+
+```toml
+[routes.hermes-x]
+hosts = ["beta", "alpha"]
+peers = ["talos"]
+```
+
+`"header"` trusts the `X-Crossbar-Peer` header instead and needs no tailnet; it is insecure and for
+tests only, so crossbar logs a warning when it starts in that mode.
+
+## What v2 does not do
+
+Request coalescing and TLS are out of scope for v2; see `PLAN.md`.

cmd/crossbar/main.go

@@ -11,13 +11,19 @@ import (
 	"net/http"
 	"os"
 	"os/signal"
+	"sort"
 	"syscall"
 	"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/identity"
+	"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"
+	"git.wntrmute.dev/kyle/crossbar/internal/wake"
 )
 
 func main() {
@@ -38,6 +44,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 +60,147 @@ func run() error {
 	defer stop()
 	go table.Run(ctx)
 
+	hosts := proxy.HostView(table, cfg)
+	lim := limiter.New()
+
+	// Wake: rouse a sleeping host when a route has no healthy host left. Built
+	// from every host that carries a wake target; the health table satisfies the
+	// waker's Health interface.
+	targets := make(map[string]wake.Target, len(cfg.Hosts))
+	for name, h := range cfg.Hosts {
+		if h.Wake == nil {
+			continue
+		}
+		targets[name] = wake.Target{MAC: h.Wake.MAC, Broadcasts: h.Wake.Addresses(), Wait: h.Wake.Wait.Duration}
+	}
+	waker := wake.New(targets, hosts)
+	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)
+	}
+
+	// Identity: gate the proxy on the route's peers when a backend is
+	// configured; off leaves the proxy unwrapped.
+	logIdentityMode(log, cfg.Identity)
+
+	p := proxy.New(cfg, table, leases, lim, st, log)
+	p.SetWaker(waker)
+
+	// Identity: gate the proxy on the route's peers when a backend is
+	// configured; off leaves the proxy unwrapped. The same checker gates each
+	// route's dedicated listener.
+
+	var checker *identity.Checker
+	if cfg.Identity != "off" {
+		switch cfg.Identity {
+		case "tailscale":
+			checker = identity.NewChecker(identity.TailscaleResolver{})
+		default: // "header"
+			checker = identity.NewHeaderChecker()
+		}
+	}
+	var handler http.Handler = p
+	if checker != nil {
+		handler = identity.Middleware(checker, func(route string) ([]string, bool) {
+			rt, _, ok := cfg.Route(route)
+			return rt.Peers, ok
+		}, p)
+	}
+
+	// Routes with a dedicated listener each serve their own address, with every request there being
+	// that route and the path unprefixed. In sorted route order, one server each, the proxy's
+	// ForRoute handler wrapped in RouteMiddleware when identity is on. No admin mux on them.
+	type routeServer struct {
+		route string
+		srv   *http.Server
+	}
+	var routes []routeServer
+	listens := make([]string, 0, len(cfg.Routes))
+	for name := range cfg.Routes {
+		if cfg.Routes[name].Listen != "" {
+			listens = append(listens, name)
+		}
+	}
+	sort.Strings(listens)
+	for _, name := range listens {
+		rt := cfg.Routes[name]
+		var h http.Handler = p.ForRoute(name)
+		if checker != nil {
+			h = identity.RouteMiddleware(checker, rt.Peers, h)
+		}
+		routes = append(routes, routeServer{route: name, srv: &http.Server{
+			Addr:              rt.Listen,
+			Handler:           h,
+			ReadHeaderTimeout: 10 * time.Second,
+		}})
+	}
+
 	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("/", handler)
+
+	// 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,
@@ -58,22 +208,60 @@ func run() error {
 		ReadHeaderTimeout: 10 * time.Second,
 	}
 
-	serverErr := make(chan error, 1)
-	go func() {
-		log.Info("listening", "addr", srv.Addr)
-		serverErr <- srv.ListenAndServe()
-	}()
+	// Every listener shuts down together on ctx done; the first error other than a clean shutdown
+	// ends run and shuts the rest down.
+	servers := make([]*http.Server, 0, 1+len(routes))
+	servers = append(servers, srv)
+	for i := range routes {
+		servers = append(servers, routes[i].srv)
+	}
+	serverErr := make(chan error, len(servers))
+	start := func(s *http.Server, route string) {
+		go func() {
+			if route != "" {
+				log.Info("listening", "addr", s.Addr, "route", route)
+			} else {
+				log.Info("listening", "addr", s.Addr)
+			}
+			serverErr <- s.ListenAndServe()
+		}()
+	}
+	start(srv, "")
+	for _, rs := range routes {
+		start(rs.srv, rs.route)
+	}
 
 	select {
 	case <-ctx.Done():
 		log.Info("shutting down")
 		shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 		defer cancel()
-		return srv.Shutdown(shutdownCtx)
+		for _, s := range servers {
+			_ = s.Shutdown(shutdownCtx)
+		}
+		return nil
 	case err := <-serverErr:
 		if errors.Is(err, http.ErrServerClosed) {
 			return nil
 		}
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		for _, s := range servers {
+			_ = s.Shutdown(shutdownCtx)
+		}
 		return err
 	}
 }
+
+// logIdentityMode logs which identity backend is active and, for the unauthenticated header
+// backend used by the smoke run, warns that it must not be exposed.
+func logIdentityMode(log *slog.Logger, mode string) {
+	if mode == "off" {
+		log.Info("identity", "mode", "off")
+		return
+	}
+	log.Info("identity", "mode", mode)
+	if mode == "header" {
+		log.Warn("identity header mode is not authenticated; do not expose it")
+	}
+}

cmd/fakeupstream/main.go

@@ -1,11 +1,15 @@
 // 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>. /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 (
@@ -14,6 +18,7 @@ import (
 	"fmt"
 	"io"
 	"log"
+	"net"
 	"net/http"
 	"os"
 	"strings"
@@ -25,11 +30,21 @@ 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")
+	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)
@@ -51,7 +66,7 @@ func main() {
 	})
 	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})
+		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)
@@ -61,11 +76,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 +89,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 +114,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())
 }
@@ -99,3 +123,39 @@ 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)
+		}
+	}
+}

deploy/hyperborea/README.md

@@ -0,0 +1,82 @@
+# crossbar on hyperborea
+
+crossbar runs on **hyperborea** (Raspberry Pi, Debian 13, aarch64) as a `systemd --user` unit,
+bound to its tailnet address only. Clients on the tailnet reach it at
+
+    http://hyperborea.scylla-hammerhead.ts.net:7777/<route>/v1
+
+Why hyperborea: it is always on, wired on titan's LAN segment (`192.168.88.154`, which
+wake-on-LAN needs — magic packets are L2 broadcast), and not itself an inference host, so a
+router rebuild or a sleeping titan never takes crossbar down with it.
+
+## Files
+
+| file | purpose |
+|---|---|
+| `crossbar.toml` | the production config: hosts titan/straylight/dixie with their configured models and `parallel`, the routes |
+| `crossbar.service` | the user unit (`/srv/crossbar`, `Restart=always`) |
+| `install.sh` | cross-compiles for arm64 on the machine you run it from, copies binary + config + unit, restarts, prints the hosts view |
+
+On hyperborea: binary, config and SQLite database live in `/srv/crossbar/`; the unit is
+`~/.config/systemd/user/crossbar.service` (`loginctl` linger is on, so it survives logout).
+
+## Install / upgrade
+
+    deploy/hyperborea/install.sh          # from any checkout on a host with Go 1.26 and ssh to hyperborea
+
+Re-running upgrades in place (binary is replaced atomically, the unit restarted; leases persist in
+the database). Config-only changes: edit `crossbar.toml`, re-run.
+
+## Verify
+
+    curl -s http://hyperborea.scylla-hammerhead.ts.net:7777/_crossbar/hosts | jq .
+    curl -s http://hyperborea.scylla-hammerhead.ts.net:7777/_crossbar/routes | jq .
+    curl -s 'http://hyperborea.scylla-hammerhead.ts.net:7777/_crossbar/usage?by=route'
+    ssh hyperborea journalctl --user -u crossbar -f
+
+A cheap end-to-end check uses the `probe` route (dixie's 9B first):
+
+    curl -s -D - -X POST -H 'Content-Type: application/json' \
+      -d '{"model":"ornith-1.5-9b-uncensored","max_tokens":8,"messages":[{"role":"user","content":"Reply with pong."}]}' \
+      http://hyperborea.scylla-hammerhead.ts.net:7777/probe/v1/chat/completions
+
+The response carries `X-Crossbar-Host` (which router served it) and `X-Crossbar-Lease`
+(`new` or `reused`).
+
+## Pointing clients at it
+
+OpenCode (project-local `opencode.json`, or the global one with a per-project route):
+
+```jsonc
+"provider": { "crossbar": { "npm": "@ai-sdk/openai-compatible",
+  "options": { "baseURL": "http://hyperborea.scylla-hammerhead.ts.net:7777/opencode-a/v1" },
+  "models": { "ornith-1.5-35b-a3b": {} } } }
+```
+
+Hermes (`custom_providers[].base_url`, and the same in `delegation`/`auxiliary` blocks):
+
+    base_url: http://hyperborea.scylla-hammerhead.ts.net:7777/hermes-straylight/v1
+
+Routes must exist in `crossbar.toml`; an unknown first path segment is `404 unknown route`.
+**Known gap:** `PLAN.md`'s one-route-per-instance launcher (`CROSSBAR_ROUTE="$(basename "$PWD")-$$"`)
+needs a route *template* (e.g. `[routes."opencode-*"]`) that the code does not have yet; until
+then add each instance's route explicitly.
+
+## Wake-on-LAN for titan
+
+The `[hosts.titan.wake]` block is present but commented out until the MAC is settled. Titan is on
+Wi-Fi (active private address `5e:fc:f2:3f:23:6b`, hardware `60:3e:5f:33:6f:b8`) with its dock's
+three Ethernet ports (`d2:30:99:9a:ee:03/04/05`) unplugged. Wired + `womp 1` is the reliable path;
+magic-packet wake over Wi-Fi on Apple Silicon is not guaranteed and the private address may
+rotate. Broadcast address is `192.168.88.255:9`.
+
+## Security notes
+
+- The bind is the tailnet address; only tailnet members can reach it. `identity = "tailscale"`
+  with per-route `peers` is available when a route should be limited to named nodes;
+  `tailscale whois` already works unprivileged on hyperborea.
+- Plain HTTP over the tailnet is WireGuard-encrypted on the wire. Hermes agents' *terminal*
+  calls to this URL may trip tirith's `plain_http_to_sink`; prefer the MagicDNS name (never the
+  raw IP) and add a rule-scoped trust entry rather than `--broad` if a prompt recurs. Provider
+  traffic from the OpenAI client library is not scanned by tirith.
+- Bodies are never logged or stored; the database holds leases and per-request accounting only.

deploy/hyperborea/crossbar.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=crossbar — affinity router for the fleet's llama-servers (tailnet :7777)
+After=network-online.target
+Wants=network-online.target
+RequiresMountsFor=/srv
+
+[Service]
+Type=simple
+WorkingDirectory=/srv/crossbar
+ExecStart=/srv/crossbar/crossbar -config /srv/crossbar/crossbar.toml
+# The bind is the tailnet address; if tailscaled is not up yet at login, retry until it is.
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target

deploy/hyperborea/crossbar.toml

@@ -0,0 +1,82 @@
+# crossbar on hyperborea — the fleet's llama-server routers behind one tailnet endpoint.
+# Clients: http://hyperborea.scylla-hammerhead.ts.net:7777/<route>/v1
+listen        = "100.112.40.10:7777"   # hyperborea's tailnet address only; never a LAN or 0.0.0.0 bind
+db            = "/srv/crossbar/crossbar.db"
+poll_interval = "60s"
+lease_idle    = "30m"
+retention     = "180d"
+queue_max     = 2                      # waiting places per (host, model) beyond `parallel`; 503 past that
+identity      = "off"                  # switch to "tailscale" once routes carry `peers`
+
+# `models` lists what each router is configured to serve, with that model's `parallel` from its
+# preset; the poller learns which are actually loaded (only those count for stickiness and the
+# context guard) and a request for an unloaded model still goes to a healthy host, where the
+# router autoloads it as today.
+
+[hosts.titan]                          # M3 Max 128 GB; ~2x straylight's decode speed
+base_url = "http://titan.scylla-hammerhead.ts.net:8081"
+weight   = 2.0
+models   = { "ornith-1.5-35b-a3b" = { parallel = 4 }, "ornith-1.5-9b-uncensored" = { parallel = 2 }, "qwen3.8-27b-uncensored" = { parallel = 2 }, "qwen3.6-35b-a3b-abliterated" = { parallel = 2 }, "gemma4-26b-a4b-abliterated" = { parallel = 2 }, "laguna-s-2.1" = { parallel = 2 }, "hermes4-70b-heretic" = { parallel = 1 }, "llama33-70b-abliterated" = { parallel = 1 }, "qwen25-72b-abliterated" = { parallel = 1 } }
+# Wake-on-LAN (best effort — Kyle 2026-09-25: titan is Wi-Fi only, no wired option, and moves
+# between the infrastructure and generic Wi-Fi networks; the private Wi-Fi address is fixed).
+# Magic packets are L2 broadcast; hyperborea is wired on the 192.168.88.0/24 segment, so this
+# only reaches titan while it is on that network. Wake over Wi-Fi on Apple Silicon is unverified.
+[hosts.titan.wake]
+mac        = "5e:fc:f2:3f:23:6b"       # en0 active (private) address; hardware MAC is 60:3e:5f:33:6f:b8
+broadcasts = ["192.168.88.255:9", "192.168.1.255:9"]   # both home segments hyperborea sits on (eth0 / wlan0)
+wait       = "45s"
+
+[hosts.straylight]
+base_url = "http://straylight.scylla-hammerhead.ts.net:11434"
+weight   = 1.0
+models   = { "ornith-1.5-35b-a3b" = { parallel = 4 }, "ornith-1.5-9b-uncensored" = { parallel = 2 }, "qwen3.8-27b-uncensored" = { parallel = 2 }, "qwen3.6-35b-a3b-abliterated" = { parallel = 2 }, "gemma4-26b-a4b-abliterated" = { parallel = 2 }, "qwen3-vl-8b-abliterated" = { parallel = 2 }, "qwen3.8-flash-next-uncensored" = { parallel = 1 }, "ornith-1.0-35b" = { parallel = 2 } }
+
+[hosts.dixie]                          # helper tier: the 9B only (honcho-embed is Honcho's lane, not routed)
+base_url = "http://dixie.scylla-hammerhead.ts.net:11434"
+weight   = 0.5
+models   = { "ornith-1.5-9b-uncensored" = { parallel = 8 } }
+
+# Routes: the first URL path segment (or X-Crossbar-Route). Each conversation on a route gets a
+# sticky lease on the host with the most free slots x weight when it starts.
+[routes.opencode-a]
+hosts         = ["titan", "straylight"]
+default_model = "ornith-1.5-35b-a3b"
+
+[routes.opencode-b]
+hosts         = ["titan", "straylight"]
+default_model = "ornith-1.5-35b-a3b"
+
+[routes.paper]
+hosts         = ["titan", "straylight"]
+default_model = "ornith-1.5-35b-a3b"
+
+[routes.hermes-straylight]
+hosts         = ["straylight", "titan", "dixie"]
+default_model = "ornith-1.5-35b-a3b"
+
+[routes.hermes-titan]
+hosts         = ["titan", "straylight", "dixie"]
+default_model = "ornith-1.5-35b-a3b"
+
+[routes.hermes-talos]
+hosts         = ["titan", "straylight", "dixie"]
+default_model = "ornith-1.5-35b-a3b"
+
+# Templates (v2.2): a route named "x-*" serves any request route "x-<something>"; each concrete
+# route keeps its own lease and usage row. This is what the per-instance OpenCode launcher uses:
+#   CROSSBAR_ROUTE="opencode-$(basename "$PWD")-$$" exec opencode "$@"
+[routes."opencode-*"]
+hosts         = ["titan", "straylight"]
+default_model = "ornith-1.5-35b-a3b"
+
+[routes."hermes-*"]
+hosts         = ["straylight", "titan", "dixie"]
+default_model = "ornith-1.5-35b-a3b"
+
+[routes.probe]                         # for operators: curl tests, never a real client
+hosts         = ["dixie", "straylight", "titan"]
+default_model = "ornith-1.5-9b-uncensored"
+
+[routes."probe-*"]                     # templated probes, e.g. /probe-anything/v1
+hosts         = ["dixie", "straylight", "titan"]
+default_model = "ornith-1.5-9b-uncensored"

deploy/hyperborea/install.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# Build crossbar for hyperborea (arm64, static) on this machine and install it there as a
+# systemd --user unit. Run from anywhere inside the repo. Idempotent: re-running upgrades in place.
+set -eu
+HOST=${HOST:-hyperborea}
+DIR=/srv/crossbar
+cd "$(git rev-parse --show-toplevel)"
+out=$(mktemp -t crossbar-arm64.XXXXXX)
+trap 'rm -f "$out"' EXIT
+CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -ldflags="-s -w" -o "$out" ./cmd/crossbar
+ssh "$HOST" "mkdir -p $DIR ~/.config/systemd/user"
+scp -q "$out" "$HOST:$DIR/crossbar.new"
+scp -q deploy/hyperborea/crossbar.toml "$HOST:$DIR/crossbar.toml"
+scp -q deploy/hyperborea/crossbar.service "$HOST:.config/systemd/user/crossbar.service"
+ssh "$HOST" "chmod 755 $DIR/crossbar.new && mv $DIR/crossbar.new $DIR/crossbar \
+  && systemctl --user daemon-reload && systemctl --user enable crossbar.service >/dev/null 2>&1 \
+  && systemctl --user restart crossbar.service && sleep 2 && systemctl --user is-active crossbar.service"
+echo "installed; hosts view:"
+curl -fsS "http://$HOST.scylla-hammerhead.ts.net:7777/_crossbar/hosts"
+echo

docs/implementer-log.md

@@ -5,11 +5,36 @@ owner fills in the Model column. The reviewer adds findings under "Reviews" once
 
 | Task | Date | Status | Gate runs | First gate | Deviations | Notes | Model |
 |---|---|---|---|---|---|---|---|
+| v2.3/04-ctx-error-docs | 2026-09-25 | done | 1 | pass | none | Resumed after the owner's v2.3 replacement `ctxguard_router_test.go` landed (byte-identical to the plan copy), resolving the earlier conflict with the protected v2.1 test. `refuseCtx` in `internal/proxy/ctxguard.go` answered the rule-4 400 in llama-server's own overflow shape `{"error":{"code":400,"type":"exceed_context_size_error","message":"prompt too large","n_prompt_tokens":<estimate>,"n_ctx":<largest per-slot context>}}`, the accounting row unchanged (status 400, Err "prompt too large"), every other error keeping `{"error":"<text>"}`; the new test reads `error.n_ctx` instead of the old top-level `max`, and `go test ./internal/proxy/` passes. README verified against task rule 2: the context-guard section documents the new body, the "Clients that manage their own slots" section covers control calls (follow the lease, take no slot, skip the guard, write no row), `/slots`+`/tokenize` proxied with `/slots/<id>` not, a GET's model from `?model=`, the `affinity`/`queue`/`listen` route keys with the `boxmaker-a` example, `listen` refused on templates and as the main address, no admin API on a route listener, and the config table gained the three keys. The "What v2 does not do" line no longer lists `/slots`, now that v2.3 proxies it. `make gate` → `gate: ok` first run, `make smoke` → `smoke: ok (stream spread 1008 ms)`. | ? |
+| v2.3/03-route-listeners | 2026-09-25 | done | 1 | pass | `cmd/crossbar/main.go` refactors the identity build so one `*identity.Checker` (nil when off) gates both the main proxy and every route's `RouteMiddleware` (task said "wrapped in RouteMiddleware when identity on"; the checker had to be shared, not rebuilt per server). `proxy.go` gains a shared `serve()` flow that both `ServeHTTP` and `ForRoute` converge on, so lease keying is identical whether a request hits the main proxy or a dedicated listener (required by `TestForRouteServesUnprefixedPaths` which asserts bm-a/bm-b share one bm lease). | Implemented `internal/config/route.go`: `Route.Listen` (`toml:"listen"`), `checkListen` validating in the order the task lists it — numeric port 1–65535, not on the template, not equal to the main listen, unique across routes (a second route in sorted-name order reports the clash with the earlier route's name). `internal/proxy/proxy.go`: `ForRoute(name)` returns 404 for an unknown route, 400 for a conflicting `X-Crossbar-Route`, 404 for any prefixed/admin/root path (so a dedicated listener never serves another route), else the shared serve with the path unprefixed. `internal/identity/middleware.go`: `RouteMiddleware` (fixed peers, no admin-path exemption, empty peers lets all through). `main.go`: per-route servers in sorted route order, shared shutdown on ctx done, first non-`ErrServerClosed` error ends run. All five given/protected files byte-identical; `make gate` → `gate: ok` first run, `make smoke` → `smoke: ok (stream spread 1004 ms)`. | ? |
+| v2.3/02-affinity-queue | 2026-09-25 | done | 1 | pass | `internal/proxy/proxy.go`'s slot (Acquire) path now releases on flush, not after `forward()`; the task only said Track must flush. | Implemented `internal/config/route.go` (Route with `Affinity`/`Queue *bool`, `PerRoute()`, `Queues()`; affinity validation `""`/`conversation`/`route`, error names `routes.<name>.affinity`; moved `checkRoutes`/`routeName`). `config.go`: one-line call to `checkRoutes`. `internal/limiter/limiter.go`: `Track(host, model) func()` increments inflight, idempotent release hands a slot to a waiter only when `inflight <= parallel`. `proxy.go`: `leaseFP = ""` in the lease key when `routeCfg.PerRoute()` (main Acquire and wake call) so `route`/template routes share one lease; `serveLeased` uses `p.lim.Track` when `routeCfg.Queues()` is false, else `Acquire`. `forward.go`: `forward()` gained a `release func()` param; `statusRecorder.onFlush` field with `Flush()` calling `onFlush()` before the underlying flush. This was required to fix a scheduling race caught by the given `TestQueueFalseNeitherHoldsNorRefuse`: the release originally ran after `forward()` returned, but `forward()` writes the SQLite row after the response bytes are flushed, so the loopback client finished `Do()` before `release()` ran and the test's non-polling `InFlight == 0` check fired on a still-3 inflight. Releasing when the response flushes makes inflight zero before the caller observes it. Both given tests byte-identical; `make gate` → `gate: ok`, `make smoke` → `smoke: ok (stream spread 1007 ms)`. | ? **Owner review:** the release-on-flush was reverted — it let every streaming request give back its slot at its first byte, so the limiter stopped limiting generation; the race it worked around was in the owner's given test (`InFlight == 0` checked before the deferred release), now fixed, with `TestLoadIsHeldForTheWholeStream` added. Session ended on a refused `/tmp` write while committing; owner committed. |
+| v2.3/01-control-plane | 2026-09-25 | done | 1 | pass | none | New `internal/proxy/control.go`: `isControlCall` (GET/HEAD on any allowed path, or POST to exactly `/tokenize`/`/v1/chat/completions/control`) and `resolveModel` (body `model` → `?model=` → route `default_model`). `proxy.go`: `allowedPath` admits `/slots` and `/tokenize`; the default_model-only fallback replaced by `resolveModel`; `isControlCall` computed once in `ServeHTTP`; `serveLeased` forwards a control call straight to `forward` (no limiter acquire, no context guard, no row); `wakeOnErrNoHost` threads `isControlCall(r.Method, rest)` through. `forward.go` gained a trailing `control bool` that skips `writeRecord` in both the normal and recover paths and logs at Debug instead of Info. Both given tests byte-identical; `make gate` → `gate: ok` on the first run. | ? |
+| v2.2/02-broadcasts | 2026-09-25 | done | 1 | pass | The Wake struct and checkWake live in `internal/config/identity.go` (added in task 04), not `config.go`, so I edited `identity.go` rather than `config.go`; `wake.go` logs a broadcast that fails to resolve/send before continuing (task rule 2 allows "logged or ignored"). | Added `Broadcasts` to `Wake` and `Wake.Addresses()` (Broadcast then Broadcasts, never empty for a parsed config); `checkWake` errors on both-set → `.broadcasts`, neither-or-empty-list → `.broadcast`, and a non-`host:port` entry → `.broadcasts`; `Target` gains `Broadcasts` and `Wake`/`sendAll` send to Broadcast then each Broadcasts in order, logging/past a failure and returning false only when no address could be sent; `main.go` fills `Target.Broadcasts` from `Wake.Addresses()` and leaves `Target.Broadcast` empty so `sendAll` does not double-send. Given `broadcasts_test.go` and `config_v22_test.go` byte-identical, v2 `wake_test.go`/`config_v2_test.go` untouched and green; `make gate` → `gate: ok` first run. | ? |
+| v2.2/01-route-templates | 2026-09-25 | done | 1 | fail | `internal/config` red only on `Wake.Addresses()` (task 02), the one allowed red; `go build ./...` clean, proxy/admin/health/wake/lease/store/identity/fingerprint all pass under `-race`. New `internal/config/route.go`: `templateName` pattern `^[a-z0-9][a-z0-9-]*-\*$` and `Route()` (valid-name guard excludes `*`; exact wins; else longest `"<prefix>-*"`, prefix keeps the dash, non-empty remainder required, longest-prefix wins deterministically). `config.go`: the route-name check accepts a template too (one line). `proxy.go`: `route()` and `ServeHTTP` resolve both path and `X-Crossbar-Route` header forms through `cfg.Route`, and the conflicting-route check compares concrete names via `cfg.Route` (identical to before for non-template configs). `admin.go` `routeView` lists a lease under the exact key it matches or the longest template key; `admin_ops.go` `routePin` resolves through `cfg.Route` so a concrete route under a template can be pinned before its first request and the template name 404s. `main.go` identity lookup uses `cfg.Route`. All three given tests byte-identical (`config_v22_test.go` keeps `TestWakeBroadcasts`, which is why config is red). | ? |
+| v2.1/02-props-loaded-only | 2026-09-25 | done | 1 | pass | `movedHeader` separator `><`→`>` and the `CtxHeader` doc comment in `proxy.go`, both forced by the given router test (`moved:small>big`) which the task text did not mention; no production code parses the separator (`forward.go` passes it straight through) so it is safe. | Implemented per-model context. `health`: added `ModelCtx` and a `Models map[string]ModelCtx` field on `Status`, plus `PerSlotCtxFor(model)` (per-model figure when present, else host-level `PerSlotCtx` for a loaded model, else 0); moved `props` into a new `props.go` and added `propsModel`/`propsModels`. Poller rules 1-4: `/v1/models` treats an entry as loaded only with no `status` or `status.value=="loaded"` (other values dropped from `Loaded`); plain `/props` with `role:router` leaves host NCtx/Slots 0; each loaded model is asked `GET /props?model=<url.QueryEscape(id)>` and a failed/malformed answer leaves that id absent without failing the host; `Models` is a fresh non-nil map every successful poll, `MarkDown` leaves it. `ctxguard.go`: every `PerSlotCtx()` became `PerSlotCtxFor(model)` (leased host, candidates, wake "cannot serve" check) and `largestSlotCtx(hosts,h,model)` counts only hosts that have it loaded. `admin.go`: `HostView` gains `models` (empty object, never null). A plain single server keeps working as v2. All three given tests byte-identical; `make gate` → `gate: ok` on the first run. | ? |
+| v2.1/01-cancel-record | 2026-09-25 | done | 1 | pass | none | Implemented the rule: added a `cancelled` field to `forwardState`; the `ErrorHandler` sets it when it observes `context.Canceled` (client gone before any response byte) so the delivered row is no longer turned into a 499 by a pooled close after the body; removed the post-hoc `r.Context().Err()` check in the normal path, leaving the recover path's `http.ErrAbortHandler` (mid-body) check as the other 499 source. Given test failed the first run (`Errors:7`, status counts held 25×200/7×499), passes 3× under `-race`; `TestClientCancelMidStreamIsRecorded`, `TestClientCancelWhileQueuedIsRecorded` and `TestQueueFullIs503` still pass; `forward.go` 230 lines; `make gate` printed `gate: ok` on the first run. | ? |
+| v2/05-wiring-smoke | 2026-09-25 | done | 1 | pass | none | The wiring in `cmd/crossbar/main.go` and `internal/proxy/{proxy,forward,ctxguard}.go` plus the README section were already in the working tree from a prior session; this session only ran the tests, the gate, the log row, and the commit. `go test -race -count=1 ./...` failed once on `TestQueueFullIs503` (`Errors:2`, the 503 not recorded) — the known v1 recording defect the owner scheduled as a v2.1 task 01; reran once and it passed. `make gate` printed `gate: ok` on the first run. Committed the two owner-corrected given v1 tests (`internal/limiter/limiter_test.go`, `internal/proxy/proxy_test.go`) alongside the prior session's changes. | ? |
+| v2/04-identity | 2026-09-25 | done | 1 | pass | new file `internal/config/identity.go` | Implemented `internal/identity/identity.go`: `ParseWhois` (Node = ComputedName, else Name minus trailing dot/domain; empty node errors), `TailscaleResolver` (`tailscale whois --json`, 3 s timeout, non-zero exit → `ErrNotAPeer`, missing binary a real deny), `Checker` with a 5-min per-address cache that also caches `ErrNotAPeer`, and `NewHeaderChecker`/`WithHeaderPeer` that read the peer from a context value. `middleware.go` names the route like the proxy (X-Crossbar-Route header, else first path segment), passes `/_crossbar/` and unknown routes straight through, and answers 403 `{"error":"forbidden route"}`. Config gains `Identity`/`Wake`/`Peers`; validation keys the peers check on the *explicit* identity value (a config with peers but no identity key passes), and `wake.wait` defaults to 45 s. Copied all four given files byte-identical; `go test -race ./internal/identity/ ./internal/config/` and `make gate` printed `gate: ok` on the first run. | ? |
+| v2/03-wake | 2026-09-25 | done | 1 | pass | none | Implemented wake-on-LAN in new `internal/wake/wake.go`: `MagicPacket` builds the 102-byte frame via `net.ParseMAC` (six `0xff` bytes plus the MAC repeated sixteen times) and rejects bad MACs; `Send` emits one UDP4 datagram to the resolved broadcast address, returning parse/resolve/write errors; `Waker` tracks last-sent per host under a mutex and sends at most once per `Wait` window, polling health every second (`PollEvery` is a test hook) until healthy, on `Wait` timeout, or on ctx cancellation, returning false for an unknown host without sending. Copied `internal/wake/wake_test.go` byte-identical to `docs/plans/v2/_files/`; `go test -race -count=3 ./internal/wake/` ok and `make gate` printed `gate: ok` on the first run. | llama.cpp/ornith-1.5-35b-a3b |
+| v2/02-ctxguard | 2026-09-25 | done | 1 | pass | none | Implemented the context-size guard in new `internal/proxy/ctxguard.go` (estimate `int(float64(len(body))/4*1.2)`; rule 2 skip on unknown/fit; rule 3 move via `leases.Move` with a `moved:<old>><new>` header; rule 4 400 with `{"error":"prompt too large","estimate":E,"max":M}` and a status-400 accounting row, no forward, no mark-down) and wired it into `ServeHTTP` between the lease and the slot; added `Move` to `internal/lease/lease.go` (re-leases, deletes the old row, records a `ctx` event) and `ReasonCtx = "ctx"` to `internal/store`. Copied `internal/proxy/ctxguard_test.go` byte-identical to `docs/plans/v2/_files/`; `go test -race -count=2 ./internal/proxy/ ./internal/lease/` ok and `make gate` printed `gate: ok` on the first run. | llama.cpp/ornith-1.5-35b-a3b |
+| v2/01-props | 2026-09-25 | done | 1 | pass | none | Implemented /props learning in `internal/health/health.go`: added `Status.NCtx`/`Status.Slots`, `PerSlotCtx()`, and a best-effort `GET <base>/props` appended to the poll after `/v1/models`, setting NCtx/Slots to 0 (negative → 0) on any failure without counting the poll as failed; exposed them in `internal/admin/admin.go` `HostView`. Copied `internal/health/props_test.go` and the replacement `internal/proxy/helpers_test.go` byte-identical to `docs/plans/v2/_files/`. `go test -race ./...` and `make gate` pass on the first run. | ? |
+| v2/01-props | 2026-09-25 | stopped | 1 | fail | none | Implemented /props learning in `internal/health/health.go` (added `Status.NCtx`/`Status.Slots`, `PerSlotCtx`, and a best-effort `GET <base>/props` appended to the poll; 0/unknown on any failure without failing the poll) and exposed them in `internal/admin/admin.go` `HostView`; copied `internal/health/props_test.go` byte-identical to `docs/plans/v2/_files/`. `go test -race ./internal/health/ ./internal/admin/` ok. `make gate` fails on two GIVEN v1 proxy tests — `TestConversationIsStickyAndLeaseHeaderTellsWhy` (alpha 1/beta 7, want 0/6) and `TestDifferentConversationsSpreadByFreeSlots` (beta 3/alpha 2, want 2/1) — which assert exact upstream hit counts; the task-required `/props` poll now lands on that scaffold's `/` catch-all and bumps the counter by exactly 1 per host (deterministic, confirmed over 3 repeated runs, not a flake). `internal/proxy/helpers_test.go` is byte-identical to `docs/plans/v1/_files/` (protected) and cannot be updated here; the `/props` request is unavoidable per the task, so the owner must hand over a scaffold that registers `/props` without counting it as a hit. Code left uncommitted for review. | ? |
+| 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 +65,61 @@ 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.
+
+
+### v2.3 review (owner, 2026-09-25)
+
+Checked: gate, `-race -count=3` on proxy and limiter, smoke (check 6: dedicated listener). Task 01
+clean (nit: the Debug log block copies the Info block's fields). Task 02: release-on-first-flush
+reverted by the owner (limiter stopped limiting streams; cause was the owner's racy given test,
+now fixed, with `TestLoadIsHeldForTheWholeStream`). Task 03: correct; `main.go` called
+`logIdentityMode` twice (removed). Task 04: stopped correctly on the owner's missed v2.1 router
+test; resumed after the replacement. README: "Boxmaker's router" → "Boxmaker's `inferproxy`".
+Model faults this plan: one timing hack (logged as a deviation), one refusal-ending, one
+malformed tool call ending a session with no change. Owner faults: racy test, missed router test.

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,73 @@
+# 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. **Environment fact you need:** when the client disconnects while `httputil.ReverseProxy` is
+   copying the response and the request came through a real `http.Server`, `ServeHTTP` does not
+   return — it panics with `http.ErrAbortHandler`, which the server swallows. Code after
+   `rp.ServeHTTP` never runs on that path. Write the accounting row from a **deferred** function
+   in `forward`: `recover()`, record (status 499 when the recovered value is `http.ErrAbortHandler`
+   or the request context is done), then re-panic with the same value so the server keeps its
+   semantics. Exactly one row per request on every path.
+4. 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,50 @@
+# 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.
+- 2026-09-25, task 01, second session: two of three tests passing; the mid-stream cancel wrote
+  no row because `httputil.ReverseProxy` does not return when the client disconnects mid-copy on a
+  real server — it panics with `http.ErrAbortHandler`, so code after `rp.ServeHTTP` never runs.
+  Ornith tried to read the Go source tree to find that out; the sandbox refused (outside the
+  repository) and the session ended on the refusal again. Two faults: the task text did not state
+  the environment's behaviour (mine — the customer describes the world the code runs in), and the
+  model ended a turn on a refusal (its, fourth time). Third session given the fact and told to
+  record from a deferred function with `recover()`.
+- 2026-09-25, task 01, third session: the fix was complete and all three tests passed, but the
+  session measured the proxy package failing 7 of 20 runs and went looking for the cause,
+  ending its turn on a refused `/tmp` copy (fifth refusal-ending tonight). The owner ran the
+  package 12 times on an idle machine: 0 failures. The flakes were CPU contention from the
+  model's own inference on the same host hitting the timing-based tests (queue, spread, cancel).
+  Two faults: timing margins in the given tests are too tight for a loaded machine (owner's test
+  design — widen in v2.1 or run those tests with a retry), and the model again ended a turn on a
+  refusal. A fourth session was told to skip the investigation and finish steps 4–7.

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
+	waitUntil(t, func() bool { return r.lim.InFlight("alpha", "shared") == 1 })
+	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,188 @@
+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 {
+			if waited < 40*time.Millisecond {
+				err = errors.New("third acquire did not wait")
+			}
+			rel() // release before reporting, so the final count check cannot race it
+		}
+		got3 <- err
+	}()
+	waitUntil(t, func() bool { return l.Queued("alpha", "m") == 1 })
+	// 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(50 * time.Millisecond) // a lower bound on the third's wait, checked above as >= 40 ms
+	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 }()
+	waitUntil(t, func() bool { return l.Queued("h", "m") == 1 })
+	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)
+		waitUntil(t, func() bool { return l.Queued("h", "m") == i }) // arrivals in order, by observation
+	}
+	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")
+	}
+}
+
+// waitUntil polls cond every millisecond for up to two seconds and fails the test if it never holds.
+func waitUntil(t *testing.T, cond func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if cond() {
+			return
+		}
+		time.Sleep(time.Millisecond)
+	}
+	t.Fatal("condition not reached within two seconds")
+}

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,290 @@
+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)
+		// arrive one after the other so both pick beta (10 > 2): wait until beta holds i slots
+		waitUntil(t, func() bool { return r.lim.InFlight("beta", "shared") == i })
+	}
+	// …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())
+	}
+}
+
+// waitUntil polls cond every 5 ms for up to two seconds and fails the test if it never holds.
+func waitUntil(t *testing.T, cond func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if cond() {
+			return
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	t.Fatal("condition not reached within two seconds")
+}
+
+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)
+	fire := func(i int) {
+		go func() {
+			resp := r.post("/r/v1/chat/completions", conversation(i, 1))
+			drain(resp)
+			codes <- resp.StatusCode
+		}()
+	}
+	// Arrival order is enforced by watching the limiter, not by sleeping: 1 runs, 2 queues,
+	// 3 finds the queue full.
+	fire(1)
+	waitUntil(t, func() bool { return r.lim.InFlight("alpha", "shared") == 1 })
+	fire(2)
+	waitUntil(t, func() bool { return r.lim.Queued("alpha", "shared") == 1 })
+	fire(3)
+	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.1/01-cancel-record.md

@@ -0,0 +1,85 @@
+# v2.1 task 01: a delivered response is never recorded as cancelled
+
+**Branch:** `v2.1` (run `git switch -c v2.1 master` if it does not exist, else `git switch v2.1`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Record cancellation from what the reverse proxy observed, not the request context`
+
+## Goal
+
+The accounting row for a forwarded request takes its status from what the reverse proxy did.
+A response that was delivered in full is recorded with the status the upstream returned, even
+when the client closes its connection the instant the body ends. Status 499 ("client
+cancelled") is recorded in exactly two cases: the reverse proxy's transport failed with a
+context error before any response byte was written, or the client left mid-body (the
+`http.ErrAbortHandler` panic the recover path already handles).
+
+## Context
+
+v1's `forward.go` writes the row after `rp.ServeHTTP` returns and, if `r.Context().Err()` is
+non-nil at that moment, turns the row into a 499 error. The server cancels a request's context
+when the client's connection closes, and a pooled client closes a connection as soon as it has
+read a response whenever its idle pool is full. So a served 200 becomes a recorded 499 whenever
+that close lands before the row is written. Measured on 2026-09-25: about a third of delivered
+responses under the given test's load; `TestQueueFullIs503` flaked on it. The reverse proxy's
+`ErrorHandler` already sees `context.Canceled` for the "client gone before the response" case
+and currently returns without leaving a trace, which is why the post-hoc check was there.
+
+## Facts about `httputil.ReverseProxy` (Go 1.26) — you cannot read its source from here
+
+The standard library lives outside the repository and the sandbox refuses reads there; do not
+try. What you need:
+
+- `ServeHTTP` calls `ErrorHandler(w, req, err)` when the outgoing request fails **before any
+  response byte was written** — for a client that left, `err` satisfies
+  `errors.Is(err, context.Canceled)`. After the response headers were written, `ErrorHandler`
+  is never called.
+- If copying the response body to the client fails (the client left mid-body), `ServeHTTP`
+  **panics with `http.ErrAbortHandler`**; v1.1's deferred `recover` in `forward.go` already
+  turns that into the 499 row and re-panics.
+- `ServeHTTP` returning normally therefore means the response was delivered in full (or
+  `ErrorHandler` answered). The request's context may nonetheless already be cancelled at that
+  moment — the server cancels it when the client's connection closes — which is exactly the
+  signal the current code misreads.
+
+## Files
+
+- Copy: `internal/proxy/served_test.go`
+- Modify: `internal/proxy/forward.go`, `docs/implementer-log.md`
+
+## Rules the tests check
+
+- `TestServedResponseIsNeverRecordedCancelled` (given): 32 concurrent requests on one host
+  (`parallel = 8`, `queue_max = 64`), each on its own connection that closes after the response
+  is read; every response is 200; the usage row has 32 requests and **0 errors**; the status
+  counts hold only status 200.
+- `TestClientCancelMidStreamIsRecorded` and `TestClientCancelWhileQueuedIsRecorded` (v1, in the
+  tree) still pass: mid-stream and while-queued cancellations are still 499 rows with a
+  non-empty `err`.
+- `TestQueueFullIs503` (v1, in the tree) still passes: 3 requests, 1 error.
+
+Rule for the implementation: the `ErrorHandler` records that it observed a cancellation (a
+field on `forwardState` is the natural place) and the row is 499 when that field is set or the
+recover path saw `http.ErrAbortHandler`. The check of `r.Context().Err()` after the forward is
+removed. Nothing else in the row changes. `forward.go` stays under 400 lines.
+
+## Steps
+
+- [ ] **1.** Branch as above; copy the given test.
+- [ ] **2. See it fail:** `go test -race -count=3 -run 'TestServedResponseIsNeverRecordedCancelled$' ./internal/proxy/` fails every run with `want 0 errors`.
+- [ ] **3.** Change `forward.go` per the rule. `gofmt -w internal/proxy/`.
+- [ ] **4.** `go test -race -count=3 ./internal/proxy/` → `ok` three times. **5.** `go test -race -count=1 ./...` → all `ok`.
+- [ ] **6.** `make gate`. **7.** Row `v2.1/01-cancel-record`; commit.
+
+```sh
+git add internal/proxy docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- The given test passes three times in a row under `-race`; the two v1 cancel tests and
+  `TestQueueFullIs503` pass; gate ok; the given file byte-identical.
+
+## Stop and report if
+
+- The given test still fails after the post-hoc check is gone: quote the status counts.
+- Making the given test pass requires editing any `_test.go` file.

docs/plans/v2.1/02-props-loaded-only.md

@@ -0,0 +1,93 @@
+# v2.1 task 02: router mode — loaded means loaded, context is per model
+
+**Branch:** `v2.1` (`git switch v2.1`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Learn per-model context from /props?model=; only status "loaded" is loaded`
+
+## Goal
+
+crossbar's real upstreams are llama-server **routers**, not single servers, and v2's poller was
+written against the single-server shape. On a router: `/v1/models` lists every configured model
+with a `status.value` (`"loaded"`, `"unloaded"`, `"loading"`); the plain `/props` answers as the
+router itself (`"role":"router"`, `n_ctx` 0); and `/props?model=X` answers for X's child server —
+**and loads X if it is not loaded**, which a health poll must never cause. After this task the
+poller treats only `"loaded"` models as loaded, asks `/props?model=X` only for those, keeps the
+answers per model, and the guard and the hosts view use the per-model figures. A plain single
+server keeps working exactly as in v2.
+
+## Context
+
+Verified on straylight's router on 2026-09-25: `/v1/models` entries carry
+`"status":{"value":"unloaded",...}` for seven of eight models; plain `/props` returns
+`{"role":"router","model_alias":"llama-server","default_generation_settings":{"n_ctx":0}}`;
+`/props?model=ornith-1.5-35b-a3b` (loaded) returns `n_ctx` 262144 and `total_slots` 4. With v2's
+code every listed model counts as loaded and the guard learns nothing, so the "Context size has
+been exceeded" failure crossbar exists to prevent still happens on a router.
+
+## Files
+
+- Copy: `internal/health/props_router_test.go`, `internal/proxy/ctxguard_router_test.go`,
+  `internal/admin/admin_models_test.go`
+- Modify: `internal/health/health.go` (a new `internal/health/props.go` is allowed for the 400-line
+  limit), `internal/proxy/ctxguard.go`, `internal/admin/admin.go`, `docs/implementer-log.md`
+
+## Interfaces
+
+```go
+package health
+
+// ModelCtx is what /props?model=X taught us about one loaded model.
+type ModelCtx struct {
+    NCtx  int `json:"n_ctx"`
+    Slots int `json:"slots"`
+}
+
+type Status struct {
+    // ... as v2 ...
+    Models map[string]ModelCtx `json:"models"` // per loaded model; never nil after a poll; copied by Get/All
+}
+
+// PerSlotCtxFor is the per-slot context for one model on this host: Models[model] when present
+// (NCtx/Slots, 0 when either is 0); else, when model is in Loaded, the host-level PerSlotCtx();
+// else 0 ("unknown" / not resident).
+func (s Status) PerSlotCtxFor(model string) int
+```
+
+Poller rules:
+1. `/v1/models`: an entry is loaded when it has no `status` or `status.value == "loaded"`; any
+   other value (`"unloaded"`, `"loading"`, …) is **not loaded** and does not appear in `Loaded`.
+2. Plain `/props`: when the body has `"role":"router"` the host-level `NCtx`/`Slots` stay 0
+   whatever else it says; otherwise as v2 (best effort, never a failure).
+3. For each model in `Loaded`, `GET /props?model=<url.QueryEscape(id)>`, decoded like the plain
+   one, into `Models[id]`. A failed or malformed answer leaves that id absent and the host
+   healthy. Never ask for a model that is not in `Loaded`.
+4. `Models` is a fresh non-nil map on every successful poll; `MarkDown` leaves it as last seen.
+
+Proxy (`ctxguard.go`): every use of `PerSlotCtx()` becomes `PerSlotCtxFor(model)` — the leased
+host's figure, the candidates a prompt may move to, the wake path's "cannot serve it no matter
+how it wakes" check, and `largestSlotCtx`, which now takes the model and so only counts hosts
+that have it loaded. Admin (`admin.go`): `HostView` gains `Models map[string]health.ModelCtx`
+(JSON `models`, an empty object never `null`).
+
+## Steps
+
+- [ ] **1.** `git switch v2.1`; copy the three given tests.
+- [ ] **2. See them fail:** `go test -race -count=1 ./internal/health/ ./internal/proxy/ ./internal/admin/` — the new tests fail to compile until the names exist, then fail on behaviour.
+- [ ] **3.** `health` first (rules 1–4, `ModelCtx`, `PerSlotCtxFor`); `go test -race -count=1 ./internal/health/` → `ok`.
+- [ ] **4.** `ctxguard.go`, then `admin.go`; each package `ok`. `gofmt -w`.
+- [ ] **5.** `go test -race -count=1 ./...` → all `ok`; `make smoke` → `smoke: ok` (the smoke's fake is a single server; nothing there changes).
+- [ ] **6.** `make gate`. **7.** Row `v2.1/02-props-loaded-only`; commit.
+
+```sh
+git add internal/health internal/proxy internal/admin docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- All three given tests pass; every v2 health/guard/admin test still passes; gate and smoke ok;
+  given files byte-identical; no file over 400 lines.
+
+## Stop and report if
+
+- A v2 given test (`props_test.go`, `ctxguard_test.go`, `admin_test.go`, `health_test.go`) needs
+  changing to pass: quote it — that is the owner's test, not yours to edit.

docs/plans/v2.1/README.md

@@ -0,0 +1,43 @@
+# v2.1 implementation plan: fixes found while running v2
+
+> **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 two defects and one gap found while v2 ran, without new features.
+
+- **01-cancel-record** — a delivered response is never recorded as a 499; cancellation is what
+  the reverse proxy observed. Found 2026-09-25 by the intermittent `Errors:2` in
+  `TestQueueFullIs503`; verified with a diagnostic build; the given
+  `internal/proxy/served_test.go` reproduces it on every run.
+- **02-props-loaded-only** — on a router only `status.value == "loaded"` counts as loaded; the
+  poller asks `/props?model=X` only for those (the router autoloads a model named in that query)
+  and keeps the answers per model (`Status.Models`, `PerSlotCtxFor`); the guard and the hosts view
+  use them. Facts verified against straylight's router on 2026-09-25. Given tests:
+  `health/props_router_test.go`, `proxy/ctxguard_router_test.go`, `admin/admin_models_test.go`.
+- ~~03-timing-margins~~ — done by the owner directly (test-only work, no implementer task): the
+  remaining ordering sleeps in `limiter_test.go`, `proxy_test.go` and `cancel_test.go` now wait on
+  limiter state (`Queued`/`InFlight`); the one sleep left is a deliberate lower bound. Five clean
+  `-race` runs of both packages except the 499 defect task 01 fixes.
+
+**How this plan was made:** acceptance tests first; no reference implementation. The given test
+for task 01 was run against the v2 tree (fails six of six) and against a throwaway fix that
+follows the task's rule (passes four full package runs with the v1 cancel tests); the throwaway
+was discarded.
+
+## Global constraints
+
+- Everything in `AGENTS.md`. Branch `v2.1` from `master` after v2 merges. One task, one fresh
+  OpenCode session, one commit. Given files are copied and never edited.
+
+## Changes during the run
+
+- 2026-09-25, task 01, first session: 8 minutes of reading, then it tried to read Go's
+  `httputil/reverseproxy.go` from the nix store, the sandbox refused, and it ended the turn
+  without a commit — the eighth refusal-ending of the day. Model fault, but the want was
+  legitimate: the task now states the `ReverseProxy` facts it was after and says the standard
+  library cannot be read from the sandbox. Restarted.
+- 2026-09-25, task 02: the given `ctxguard_router_test.go` asserts `X-Crossbar-Ctx: moved:small>big`;
+  v2's code emitted `moved:small><big`. Owner fault twice over: the v2 task 02 text wrote the
+  separator as `<from>>><to>` (ambiguous), and no v2 given test asserted the header, so the
+  misreading passed. The example in that task (`moved:small>big`) is the intended format; Ornith
+  changed `movedHeader` to match and said so. Accepted as part of task 02.

docs/plans/v2.1/_files/internal/admin/admin_models_test.go

@@ -0,0 +1,46 @@
+package admin_test
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/admin"
+	"git.wntrmute.dev/kyle/crossbar/internal/health"
+)
+
+// The hosts view shows the per-model context the poller learned, and an empty object (never
+// null) for a host with nothing learned.
+func TestHostsShowsPerModelContext(t *testing.T) {
+	r := newRig(t)
+	r.hosts.st["alpha"] = health.Status{
+		Healthy: true,
+		Loaded:  []string{"m"},
+		NCtx:    0, // a router: the host-level figure stays unknown
+		Models:  map[string]health.ModelCtx{"m": {NCtx: 65536, Slots: 2}},
+	}
+	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 got := out["alpha"].Models["m"]; got != (health.ModelCtx{NCtx: 65536, Slots: 2}) {
+		t.Errorf("alpha.models[m] = %+v, want {65536 2}", got)
+	}
+	if out["alpha"].NCtx != 0 {
+		t.Errorf("alpha.n_ctx = %d, want 0 (unknown at host level on a router)", out["alpha"].NCtx)
+	}
+	var raw map[string]json.RawMessage
+	if err := json.Unmarshal(rec.Body.Bytes(), &raw); err != nil {
+		t.Fatal(err)
+	}
+	if beta := string(raw["beta"]); !strings.Contains(beta, `"models":{}`) {
+		t.Errorf("beta = %s, want \"models\":{} (never null)", beta)
+	}
+	if alpha := string(raw["alpha"]); !strings.Contains(alpha, `"models":{"m":{"n_ctx":65536,"slots":2}}`) {
+		t.Errorf("alpha = %s, want models keyed by id with n_ctx and slots", alpha)
+	}
+}

docs/plans/v2.1/_files/internal/health/props_router_test.go

@@ -0,0 +1,177 @@
+package health_test
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/health"
+)
+
+// routerFake is shaped like llama-server's router mode: /v1/models lists every configured model
+// with a status, a plain /props answers as the router itself (no context), and /props?model=X
+// answers for one loaded child server. It counts the per-model /props queries it receives.
+type routerFake struct {
+	srv     *httptest.Server
+	mu      sync.Mutex
+	queries map[string]int
+}
+
+func newRouterFake(t *testing.T) *routerFake {
+	f := &routerFake{queries: map[string]int{}}
+	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, `{"object":"list","data":[
+			{"id":"big","object":"model","status":{"value":"loaded","args":["--ctx-size","262144"]}},
+			{"id":"small","object":"model","status":{"value":"loaded"}},
+			{"id":"cold","object":"model","status":{"value":"unloaded"}},
+			{"id":"warming","object":"model","status":{"value":"loading"}}]}`)
+	})
+	mux.HandleFunc("/props", func(w http.ResponseWriter, r *http.Request) {
+		model := r.URL.Query().Get("model")
+		if model == "" {
+			fmt.Fprint(w, `{"role":"router","model_alias":"llama-server","model_path":"none","default_generation_settings":{"params":null,"n_ctx":0}}`)
+			return
+		}
+		f.mu.Lock()
+		f.queries[model]++
+		f.mu.Unlock()
+		switch model {
+		case "big":
+			fmt.Fprint(w, `{"default_generation_settings":{"n_ctx":262144,"params":{}},"total_slots":4,"model_alias":"big"}`)
+		case "small":
+			fmt.Fprint(w, `{"default_generation_settings":{"n_ctx":32768,"params":{}},"total_slots":1,"model_alias":"small"}`)
+		default:
+			// Asking a router for an unloaded model would make it load the model. The fake
+			// answers 500 so a wrong query is visible in the counts and cannot look like success.
+			w.WriteHeader(http.StatusInternalServerError)
+			fmt.Fprint(w, `{"error":"the poller must not ask for a model that is not loaded"}`)
+		}
+	})
+	f.srv = httptest.NewServer(mux)
+	t.Cleanup(f.srv.Close)
+	return f
+}
+
+func (f *routerFake) count(model string) int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.queries[model]
+}
+
+func TestRouterLoadedMeansStatusLoaded(t *testing.T) {
+	f := newRouterFake(t)
+	tbl := health.New(map[string]string{"r": f.srv.URL}, time.Hour, nil)
+	tbl.PollOnce(context.Background())
+	s, ok := tbl.Get("r")
+	if !ok || !s.Healthy {
+		t.Fatalf("status = %+v, want a healthy host", s)
+	}
+	if len(s.Loaded) != 2 || s.Loaded[0] != "big" || s.Loaded[1] != "small" {
+		t.Errorf("Loaded = %v, want [big small]: unloaded and loading models are not loaded", s.Loaded)
+	}
+}
+
+func TestRouterContextIsLearnedPerModel(t *testing.T) {
+	f := newRouterFake(t)
+	tbl := health.New(map[string]string{"r": f.srv.URL}, time.Hour, nil)
+	tbl.PollOnce(context.Background())
+	s, _ := tbl.Get("r")
+	if s.NCtx != 0 || s.Slots != 0 || s.PerSlotCtx() != 0 {
+		t.Errorf("a router's own /props carries no context; host-level must stay unknown: %+v", s)
+	}
+	if got := s.Models["big"]; got != (health.ModelCtx{NCtx: 262144, Slots: 4}) {
+		t.Errorf("Models[big] = %+v, want {262144 4}", got)
+	}
+	if got := s.Models["small"]; got != (health.ModelCtx{NCtx: 32768, Slots: 1}) {
+		t.Errorf("Models[small] = %+v, want {32768 1}", got)
+	}
+	if got := s.PerSlotCtxFor("big"); got != 65536 {
+		t.Errorf("PerSlotCtxFor(big) = %d, want 262144/4", got)
+	}
+	if got := s.PerSlotCtxFor("small"); got != 32768 {
+		t.Errorf("PerSlotCtxFor(small) = %d, want 32768/1", got)
+	}
+	if got := s.PerSlotCtxFor("cold"); got != 0 {
+		t.Errorf("PerSlotCtxFor(cold) = %d, want 0: nothing is known about an unloaded model", got)
+	}
+	if _, present := s.Models["cold"]; present {
+		t.Errorf("Models must not carry an entry for an unloaded model: %+v", s.Models)
+	}
+}
+
+func TestRouterUnloadedModelsAreNeverQueried(t *testing.T) {
+	f := newRouterFake(t)
+	tbl := health.New(map[string]string{"r": f.srv.URL}, time.Hour, nil)
+	for i := 0; i < 3; i++ {
+		tbl.PollOnce(context.Background())
+	}
+	if f.count("cold") != 0 || f.count("warming") != 0 {
+		t.Fatalf("/props?model= was asked for a model that is not loaded (cold %d, warming %d): on a real router that loads the model", f.count("cold"), f.count("warming"))
+	}
+	if f.count("big") == 0 || f.count("small") == 0 {
+		t.Errorf("loaded models must be asked: big %d, small %d", f.count("big"), f.count("small"))
+	}
+}
+
+func TestPlainServerStillReadsHostLevelContext(t *testing.T) {
+	// A single llama-server (no status field, no router role) behaves as in v2: every listed model
+	// is loaded, the host-level context comes from the plain /props, and the per-model view falls
+	// back to it for any loaded model.
+	srv := propsFake(t, `{"default_generation_settings":{"n_ctx":131072,"params":{}},"total_slots":4,"model_path":"/x/m.gguf"}`, 200)
+	tbl := health.New(map[string]string{"a": srv.URL}, time.Hour, nil)
+	tbl.PollOnce(context.Background())
+	s, _ := tbl.Get("a")
+	if !s.Healthy || len(s.Loaded) != 1 || s.Loaded[0] != "m" || s.NCtx != 131072 || s.Slots != 4 {
+		t.Fatalf("status = %+v, want healthy, Loaded [m], NCtx 131072, Slots 4", s)
+	}
+	if got := s.PerSlotCtxFor("m"); got != 32768 {
+		t.Errorf("PerSlotCtxFor(m) = %d, want the host-level 131072/4", got)
+	}
+	if got := s.PerSlotCtxFor("other"); got != 0 {
+		t.Errorf("PerSlotCtxFor(other) = %d, want 0 for a model the host does not list", got)
+	}
+	if s.Models == nil {
+		t.Errorf("Models must be an empty map after a poll, never nil")
+	}
+}
+
+func TestPerModelPropsFailureLeavesTheModelUnknown(t *testing.T) {
+	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":"ok","status":{"value":"loaded"}},{"id":"broken","status":{"value":"loaded"}}]}`)
+	})
+	mux.HandleFunc("/props", func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Query().Get("model") {
+		case "":
+			fmt.Fprint(w, `{"role":"router","default_generation_settings":{"n_ctx":0}}`)
+		case "ok":
+			fmt.Fprint(w, `{"default_generation_settings":{"n_ctx":8192},"total_slots":2}`)
+		default:
+			fmt.Fprint(w, `<html>not json</html>`)
+		}
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	tbl := health.New(map[string]string{"r": srv.URL}, time.Hour, nil)
+	tbl.PollOnce(context.Background())
+	s, _ := tbl.Get("r")
+	if !s.Healthy {
+		t.Fatalf("a broken per-model /props must not make the host unhealthy: %+v", s)
+	}
+	if len(s.Loaded) != 2 {
+		t.Errorf("Loaded = %v, want both models: /props is advisory", s.Loaded)
+	}
+	if got := s.PerSlotCtxFor("ok"); got != 4096 {
+		t.Errorf("PerSlotCtxFor(ok) = %d, want 8192/2", got)
+	}
+	if _, present := s.Models["broken"]; present || s.PerSlotCtxFor("broken") != 0 {
+		t.Errorf("a model whose /props failed stays unknown: %+v", s.Models)
+	}
+}

docs/plans/v2.1/_files/internal/proxy/ctxguard_router_test.go

@@ -0,0 +1,105 @@
+package proxy_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+)
+
+// routerUpstream is a fake shaped like llama-server's router mode: the plain /props carries no
+// context (role router, n_ctx 0), /v1/models lists models with a status, and /props?model=X
+// answers for one loaded model. The guard must work from the per-model figures.
+func routerUpstream(t *testing.T, name string, models map[string][2]int, unloaded ...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) {
+		fmt.Fprint(w, `{"object":"list","data":[`)
+		first := true
+		for id := range models {
+			if !first {
+				fmt.Fprint(w, ",")
+			}
+			first = false
+			fmt.Fprintf(w, `{"id":%q,"status":{"value":"loaded"}}`, id)
+		}
+		for _, id := range unloaded {
+			fmt.Fprintf(w, `,{"id":%q,"status":{"value":"unloaded"}}`, id)
+		}
+		fmt.Fprint(w, `]}`)
+	})
+	mux.HandleFunc("/props", func(w http.ResponseWriter, r *http.Request) {
+		model := r.URL.Query().Get("model")
+		if model == "" {
+			fmt.Fprint(w, `{"role":"router","default_generation_settings":{"n_ctx":0}}`)
+			return
+		}
+		m, ok := models[model]
+		if !ok {
+			w.WriteHeader(http.StatusInternalServerError)
+			fmt.Fprint(w, `{"error":"asked for a model that is not loaded"}`)
+			return
+		}
+		fmt.Fprintf(w, `{"default_generation_settings":{"n_ctx":%d},"total_slots":%d}`, m[0], m[1])
+	})
+	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
+}
+
+// On routers the guard reads the per-model per-slot context: `small` serves "shared" from a
+// 8192-context child with two slots (4096 per slot), `big` from a 131072-context child with one.
+// The plain /props of both says nothing, so a v2 guard that only knew host-level figures would
+// stay inert and let the oversized prompt overflow `small`.
+func TestRouterGuardUsesPerModelContext(t *testing.T) {
+	small := routerUpstream(t, "small", map[string][2]int{"shared": {8192, 2}})
+	big := routerUpstream(t, "big", map[string][2]int{"shared": {131072, 1}})
+	r := newRig(t, ctxHosts, small, big)
+
+	resp := r.post("/r/v1/chat/completions", bodyOfTokens(100))
+	drain(resp)
+	if got := resp.Header.Get(proxy.HostHeader); got != "small" {
+		t.Fatalf("small prompt went to %q, want small (weight 10)", got)
+	}
+	resp = r.post("/r/v1/chat/completions", bodyOfTokens(6000))
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.HostHeader) != "big" {
+		t.Fatalf("6000-token prompt: status %d host %q, want 200 on big", resp.StatusCode, resp.Header.Get(proxy.HostHeader))
+	}
+	if got := resp.Header.Get("X-Crossbar-Ctx"); got != "moved:small>big" {
+		t.Errorf("X-Crossbar-Ctx = %q, want moved:small>big", got)
+	}
+}
+
+// A model the router lists as unloaded is not resident there: the guard must not move a prompt
+// to that host, and the refusal names the largest per-slot context among hosts that do serve it.
+func TestRouterUnloadedModelIsNotACandidate(t *testing.T) {
+	small := routerUpstream(t, "small", map[string][2]int{"shared": {8192, 2}})
+	big := routerUpstream(t, "big", map[string][2]int{"other": {131072, 1}}, "shared") // shared unloaded on big
+	r := newRig(t, ctxHosts, small, big)
+
+	resp := r.post("/r/v1/chat/completions", bodyOfTokens(6000))
+	body := drain(resp)
+	if resp.StatusCode != 400 {
+		t.Fatalf("status %d body %s, want 400: shared is loaded only on small, where it does not fit", resp.StatusCode, body)
+	}
+	if big.hits.Load() != 0 {
+		t.Errorf("big served %d requests for a model it does not have loaded", big.hits.Load())
+	}
+	var e map[string]any
+	if err := json.Unmarshal([]byte(body), &e); err != nil {
+		t.Fatalf("body %q is not JSON: %v", body, err)
+	}
+	if max, _ := e["max"].(float64); max != 4096 {
+		t.Errorf("max = %v, want 4096: the largest per-slot context among hosts that have shared loaded", e["max"])
+	}
+}

docs/plans/v2.1/_files/internal/proxy/served_test.go

@@ -0,0 +1,83 @@
+package proxy_test
+
+import (
+	"net/http"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+// A response the proxy delivered in full is recorded with the status the upstream returned, even
+// when the client closes its connection the instant the body ends. Cancellation is what the
+// reverse proxy observed while forwarding (a transport error before any byte, or the client
+// leaving mid-body), never a look at the request context after the forward returned.
+//
+// Each request uses its own connection and closes it as soon as the response is read, which is
+// what a pooled client does when its idle pool is full; the server then cancels the request's
+// context while the handler may still be writing the accounting row.
+func TestServedResponseIsNeverRecordedCancelled(t *testing.T) {
+	alpha := newUpstream(t, "alpha")
+	alpha.delay = 20 * time.Millisecond
+	r := newRig(t, `
+listen = "127.0.0.1:1"
+queue_max = 64
+[hosts.alpha]
+base_url = %q
+models = { "shared" = { parallel = 8 } }
+[routes.r]
+hosts = ["alpha"]
+default_model = "shared"
+`, alpha)
+
+	const n = 32
+	var wg sync.WaitGroup
+	codes := make([]int, n)
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			client := &http.Client{Transport: &http.Transport{DisableKeepAlives: true}}
+			req, _ := http.NewRequest(http.MethodPost, r.front.URL+"/r/v1/chat/completions", strings.NewReader(conversation(i, 1)))
+			req.Header.Set("Content-Type", "application/json")
+			resp, err := client.Do(req)
+			if err != nil {
+				t.Error(err)
+				return
+			}
+			drain(resp)
+			codes[i] = resp.StatusCode
+		}(i)
+	}
+	wg.Wait()
+	for i, c := range codes {
+		if c != 200 {
+			t.Fatalf("request %d: status %d, want 200", i, c)
+		}
+	}
+
+	// Rows are written after each response completes; allow the store a moment to catch up.
+	var rows []store.UsageRow
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		rows, _ = r.store.Usage(time.Time{}, store.ByRoute)
+		if len(rows) == 1 && rows[0].Requests == n {
+			break
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	if len(rows) != 1 || rows[0].Requests != n {
+		t.Fatalf("usage = %+v, want one row with %d requests", rows, n)
+	}
+	if rows[0].Errors != 0 {
+		t.Errorf("usage = %+v, want 0 errors: every response was delivered with status 200", rows[0])
+	}
+	counts, _ := r.store.StatusCounts(time.Time{})
+	for _, c := range counts {
+		if c.Status != 200 {
+			t.Errorf("status counts %+v: a delivered 200 was recorded as %d", counts, c.Status)
+		}
+	}
+}

docs/plans/v2.2/01-route-templates.md

@@ -0,0 +1,82 @@
+# v2.2 task 01: route templates
+
+**Branch:** `v2.2` (`git switch -c v2.2 master` if it does not exist, else `git switch v2.2`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Route templates: a route named x-* serves any request route x-<something>`
+
+## Goal
+
+`PLAN.md` §4a gives every OpenCode instance its own route (`CROSSBAR_ROUTE="$(basename "$PWD")-$$"`),
+but the config only knows explicit `[routes.NAME]` tables and everything else is `404 unknown
+route`. After this task a route whose name ends in `-*` is a **template**: a request route that
+starts with the part before the star, with something non-empty after it, uses that route's hosts,
+default model and peers. Leases and accounting stay keyed by the concrete route name, so two
+instances never share a lease and each has its own usage row.
+
+## Files
+
+- Copy: `internal/config/config_v22_test.go` (its `TestWakeBroadcasts` belongs to task 02 and
+  will fail to compile until then — see step 2), `internal/proxy/template_test.go`,
+  `internal/admin/admin_template_test.go`
+- Create: `internal/config/route.go` — the template name pattern and `Route()` live here;
+  `config.go` is already at the 400-line limit, so add nothing to it beyond what the new file
+  needs from it (one-line hooks are fine)
+- Modify: `internal/config/config.go` (minimal), `internal/proxy/proxy.go`,
+  `internal/admin/admin.go`, `internal/admin/admin_ops.go`, `cmd/crossbar/main.go` (the identity
+  middleware's route→peers lookup), `docs/implementer-log.md`. If `proxy.go` would pass 400
+  lines, move route resolution (`route`, `SplitRoute`, `allowedPath`) into a new
+  `internal/proxy/route.go`.
+
+## Interfaces
+
+```go
+package config
+
+// Route resolves a request route name: an exact entry wins; else the longest template
+// "<prefix>-*" whose prefix (including the dash) starts name with a non-empty remainder;
+// else ok is false. key is the config key that matched (the template's name for a template).
+// A name that is not a valid route name (the pattern below) or contains '*' never matches.
+func (c *Config) Route(name string) (r Route, key string, ok bool)
+```
+
+Rules:
+1. Config route keys match `^[a-z0-9][a-z0-9-]*$` (as before) **or** `^[a-z0-9][a-z0-9-]*-\*$`
+   (a template). Anything else with a `*` is `routes.<name>: must match …` as today. A
+   template alone satisfies "at least one route".
+2. Resolution order: exact, then longest matching template, then none.
+3. The proxy resolves both the path form and the `X-Crossbar-Route` header form through
+   `cfg.Route`; the concrete name (not the template key) is the route used for leases,
+   accounting rows, logs and headers. The "conflicting route" check compares concrete names.
+4. Admin: `POST /_crossbar/routes/{route}` resolves through `cfg.Route` — a concrete route under
+   a template can be pinned/released even before its first request; the template name itself
+   is `404 unknown route`. `GET /_crossbar/routes` lists config keys (templates under their own
+   name) and, for a template, the leases of every concrete route it matches.
+5. `main.go`: the identity middleware's `func(route string) ([]string, bool)` uses `cfg.Route`.
+
+## Steps
+
+- [ ] **1.** Branch as above; copy the three given tests.
+- [ ] **2. See them fail.** `config_v22_test.go` also references `Wake.Addresses()` (task 02); until
+  then run the config package with `-run 'TestRouteTemplate'` **after** adding a temporary
+  stub? No — do not add stubs. Instead implement task 01 and run
+  `go test -race -count=1 ./internal/proxy/ ./internal/admin/` for the behaviour, and `go vet
+  ./internal/config/` will fail only on the missing `Addresses` method until task 02: that is
+  expected and is the one allowed red at the end of this task. Say so in the log row.
+- [ ] **3.** `config/route.go`: the template pattern, `Route()`; the validation in `config.go` accepts template names. **4.** `proxy.go` route resolution.
+  **5.** `admin.go` / `admin_ops.go`. **6.** `main.go`.
+- [ ] **7.** `gofmt -w`; `go test -race -count=1 ./internal/proxy/ ./internal/admin/ ./internal/health/ ./internal/wake/` → `ok`.
+- [ ] **8.** Row `v2.2/01-route-templates`; commit (the gate runs green after task 02).
+
+```sh
+git add internal/config internal/proxy internal/admin cmd/crossbar docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- `TestRouteTemplateServesConcreteRoutes` and `TestRoutesViewAndPinWithTemplates` pass under
+  `-race`; every earlier proxy/admin test still passes; given files byte-identical; no file over
+  400 lines. `internal/config` is red only on `Addresses` (task 02).
+
+## Stop and report if
+
+- Passing needs a change to any earlier given test.

docs/plans/v2.2/02-broadcasts.md

@@ -0,0 +1,68 @@
+# v2.2 task 02: several broadcast addresses per wake target
+
+**Branch:** `v2.2` (`git switch v2.2`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Wake: a target may list several broadcast addresses`
+
+## Goal
+
+Titan roams between two Wi-Fi networks; hyperborea sits on both segments. A wake target can
+therefore name **several** broadcast addresses and the magic packet goes to all of them. Config
+keeps `broadcast = "host:port"` (one) and adds `broadcasts = ["host:port", …]` (a list);
+exactly one of the two must be present.
+
+## Files
+
+- Copy: `internal/wake/broadcasts_test.go` (`internal/config/config_v22_test.go` was copied in
+  task 01 and its `TestWakeBroadcasts` becomes green here)
+- Modify: `internal/config/config.go`, `internal/wake/wake.go`, `cmd/crossbar/main.go`,
+  `example.toml` (show the list form, commented), `docs/implementer-log.md`
+
+## Interfaces
+
+```go
+package config
+type Wake struct {
+    MAC        string   `toml:"mac"`
+    Broadcast  string   `toml:"broadcast"`
+    Broadcasts []string `toml:"broadcasts"`
+    Wait       Duration `toml:"wait"`
+}
+// Addresses is Broadcast (when set) followed by Broadcasts: the list to send to, never empty
+// for a parsed config.
+func (w *Wake) Addresses() []string
+
+package wake
+type Target struct {
+    MAC        string
+    Broadcast  string   // one address, as before
+    Broadcasts []string // more addresses; Send goes to Broadcast (if set) and then each of these
+    Wait       time.Duration
+}
+```
+
+Rules:
+1. Validation (`hosts.<h>.wake…` fields): `broadcast` and `broadcasts` both set → error on
+   `hosts.<h>.wake.broadcasts`; neither, or an empty list → error on `hosts.<h>.wake.broadcast`;
+   every entry must be `host:port` (same check as `broadcast` today) → error on
+   `hosts.<h>.wake.broadcasts`.
+2. `Waker.Wake` sends one packet to every address in order. An address that fails to resolve
+   or send is logged (or ignored) and does **not** stop the remaining addresses; `Wake` returns
+   false only if *no* address could be sent to (or on the existing timeout/ctx rules).
+3. `main.go` fills `Target.Broadcasts` from `Wake.Addresses()`.
+
+## Steps
+
+- [ ] **1.** `git switch v2.2`; copy `broadcasts_test.go`.
+- [ ] **2. See it fail** (compile). **3.** `config.go`, then `wake.go`, then `main.go`, `example.toml`.
+- [ ] **4.** `go test -race -count=3 ./internal/wake/ ./internal/config/` → `ok`. **5.** `go test -race -count=1 ./...`; `make smoke`.
+- [ ] **6.** `make gate`. **7.** Row `v2.2/02-broadcasts`; commit.
+
+```sh
+git add internal/config internal/wake cmd/crossbar example.toml docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- All given tests pass; the v2 `wake_test.go` and `config_v2_test.go` are untouched and green;
+  gate and smoke ok; given files byte-identical.

docs/plans/v2.2/README.md

@@ -0,0 +1,39 @@
+# v2.2 implementation plan: what the hyperborea deploy exposed
+
+> **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:** two small gaps found on 2026-09-25 when crossbar went live on hyperborea.
+
+- **01-route-templates** — `PLAN.md`'s one-route-per-OpenCode-instance launcher produces route
+  names the config has never seen, and unknown routes are 404. A route named `opencode-*` now
+  serves every `opencode-<something>`; leases and accounting stay per concrete route. Given:
+  `config/config_v22_test.go`, `proxy/template_test.go`, `admin/admin_template_test.go`.
+- **02-broadcasts** — titan roams between two Wi-Fi networks and hyperborea is on both segments,
+  so a wake target needs more than one broadcast address. Given: `wake/broadcasts_test.go`
+  (+ `TestWakeBroadcasts` in the config test above).
+
+**Order matters:** the config given test covers both tasks, so `internal/config` is red on one
+method between task 01's commit and task 02's. Task 01's text says so; the gate runs after 02.
+
+**How this plan was made:** acceptance tests first, no reference implementation; the given tests
+compiled against a panic-only skeleton of the new names and failed on the v2.1 tree for the
+intended reasons.
+
+## Global constraints
+
+- Everything in `AGENTS.md`. Branch `v2.2` from `master`. One task, one fresh OpenCode session,
+  one commit. Given files are copied and never edited; earlier plans' given files stay protected.
+
+## Changes during the run
+
+- 2026-09-25, task 01, first session: ten minutes circling the line budget — `config.go` was
+  already at 401 lines and the task named no new file for the package. Owner fault: the task now
+  creates `internal/config/route.go` (and allows `internal/proxy/route.go`). Session stopped and
+  restarted on a clean tree.
+- 2026-09-25, task 02: the task told the implementer to modify `example.toml`, which is a v2
+  given file (protected). Owner fault — a replacement should have been given. The one-line change
+  (the commented `broadcasts` list) is adopted as the v2.2 given copy of `example.toml`.
+- Both tasks first-gate: 01 in 21 min after the restart, 02 in 8 min. Task 02 edited
+  `internal/config/identity.go` rather than `config.go` because that is where `Wake` lives
+  (logged deviation, correct call — owner named the wrong file).

docs/plans/v2.2/_files/example.toml

@@ -0,0 +1,33 @@
+# 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
+# broadcasts = ["127.0.0.1:19082", "127.0.0.1:19083"]  # v2.2: a roaming host on several networks; this or broadcast, not both, and at least one
+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.2/_files/internal/admin/admin_template_test.go

@@ -0,0 +1,92 @@
+package admin_test
+
+import (
+	"encoding/json"
+	"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"
+)
+
+// The routes view lists a template once, under its own name, with the leases of every concrete
+// route it matched. A concrete route can be pinned; the template itself cannot.
+func TestRoutesViewAndPinWithTemplates(t *testing.T) {
+	cfg, err := config.Parse(strings.NewReader(`
+listen = "127.0.0.1:1"
+[hosts.alpha]
+base_url = "http://alpha:1"
+models = { "m" = { parallel = 2 } }
+[routes."opencode-*"]
+hosts = ["alpha"]
+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"}}},
+		draining: map[string]bool{},
+	}
+	lt, err := lease.New(st, hosts, hosts, 30*time.Minute)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := lt.Acquire(lease.Key{Route: "opencode-projecta-4242", FP: "fp1", Model: "m"}, []string{"alpha"}, time.Now()); err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := lt.Acquire(lease.Key{Route: "opencode-projectb-7", FP: "fp2", Model: "m"}, []string{"alpha"}, time.Now()); err != nil {
+		t.Fatal(err)
+	}
+	lim := limiter.New()
+	lim.Configure("alpha", "m", 2, 8)
+	r := &rig{h: admin.Handler(cfg, hosts, lt, lim, st, hosts), store: st, leases: lt, hosts: hosts}
+
+	rec := r.do(t, "GET", "/_crossbar/routes", "")
+	if rec.Code != 200 {
+		t.Fatalf("%d %s", rec.Code, rec.Body.String())
+	}
+	var out map[string]admin.RouteView
+	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	v, ok := out["opencode-*"]
+	if !ok || len(out) != 1 {
+		t.Fatalf("routes view keys = %v, want exactly the template", keysOf(out))
+	}
+	if len(v.Hosts) != 1 || v.Hosts[0] != "alpha" || v.DefaultModel != "m" || len(v.Leases) != 2 {
+		t.Errorf("template view = %+v, want hosts [alpha], model m and the two concrete routes' leases", v)
+	}
+
+	rec = r.do(t, "POST", "/_crossbar/routes/opencode-projecta-4242", `{"host":"alpha","pin":true}`)
+	if rec.Code != 200 {
+		t.Errorf("pin of a concrete templated route: %d %s, want 200", rec.Code, rec.Body.String())
+	}
+	rec = r.do(t, "POST", "/_crossbar/routes/opencode-*", `{"host":"alpha","pin":true}`)
+	if rec.Code != 404 {
+		t.Errorf("pin of the template itself: %d, want 404 unknown route", rec.Code)
+	}
+	rec = r.do(t, "POST", "/_crossbar/routes/opencode-nothing-yet", `{"host":"alpha","pin":true}`)
+	if rec.Code != 200 {
+		t.Errorf("pin of a not-yet-seen concrete route under a template: %d %s, want 200 (it is a valid route)", rec.Code, rec.Body.String())
+	}
+}
+
+func keysOf(m map[string]admin.RouteView) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}

docs/plans/v2.2/_files/internal/config/config_v22_test.go

@@ -0,0 +1,115 @@
+package config_test
+
+import (
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+)
+
+const templateBase = `
+listen = "127.0.0.1:1"
+[hosts.a]
+base_url = "http://a:1"
+models = { "m" = { }, "n" = { } }
+[routes."opencode-*"]
+hosts = ["a"]
+default_model = "m"
+[routes."opencode-rust-*"]
+hosts = ["a"]
+default_model = "n"
+[routes.opencode-fixed]
+hosts = ["a"]
+[routes.paper]
+hosts = ["a"]
+`
+
+// A route whose name ends in "-*" is a template: any request route that starts with the part
+// before the star, with something after it, uses that route's config. An exact name wins over a
+// template; the longest matching template wins over shorter ones.
+func TestRouteTemplatesResolve(t *testing.T) {
+	c, err := config.Parse(strings.NewReader(templateBase))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct {
+		name, wantKey, wantModel string
+		ok                       bool
+	}{
+		{"paper", "paper", "", true},
+		{"opencode-fixed", "opencode-fixed", "", true},      // exact beats template
+		{"opencode-projecta-4242", "opencode-*", "m", true}, // template
+		{"opencode-rust-a-7", "opencode-rust-*", "n", true}, // longest template wins
+		{"opencode-", "", "", false},                        // nothing after the prefix
+		{"opencode", "", "", false},                         // the dash is part of the prefix
+		{"opencodex", "", "", false},                        // not a prefix match
+		{"opencode-*", "", "", false},                       // a literal star is never a request route
+		{"Opencode-A", "", "", false},                       // not a valid route name
+		{"nope", "", "", false},
+	} {
+		r, key, ok := c.Route(tc.name)
+		if ok != tc.ok || key != tc.wantKey || (ok && r.DefaultModel != tc.wantModel) {
+			t.Errorf("Route(%q) = (%+v, %q, %v), want key %q model %q ok %v", tc.name, r, key, ok, tc.wantKey, tc.wantModel, tc.ok)
+		}
+	}
+}
+
+func TestRouteTemplateNamesAreValidated(t *testing.T) {
+	for name, tc := range map[string]struct {
+		route   string
+		wantErr string
+	}{
+		"star in the middle": {`"open*code"`, "routes.open*code"},
+		"star without dash":  {`"opencode*"`, "routes.opencode*"},
+		"bare star":          {`"*"`, "routes.*"},
+		"double star":        {`"opencode-**"`, "routes.opencode-**"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			text := "listen = \"127.0.0.1:1\"\n[hosts.a]\nbase_url = \"http://a:1\"\nmodels = { \"m\" = { } }\n[routes." + tc.route + "]\nhosts = [\"a\"]\n"
+			_, err := config.Parse(strings.NewReader(text))
+			ce, ok := err.(*config.Error)
+			if !ok || ce.Field != tc.wantErr {
+				t.Fatalf("err = %v, want *config.Error on %q", err, tc.wantErr)
+			}
+		})
+	}
+	// A template alone satisfies "at least one route".
+	if _, err := config.Parse(strings.NewReader("listen = \"127.0.0.1:1\"\n[hosts.a]\nbase_url = \"http://a:1\"\nmodels = { \"m\" = { } }\n[routes.\"x-*\"]\nhosts = [\"a\"]\n")); err != nil {
+		t.Errorf("a template-only config must parse: %v", err)
+	}
+}
+
+// broadcasts: a wake target may name several broadcast addresses (a host that roams between two
+// Wi-Fi networks). `broadcast` (one) and `broadcasts` (a list) are alternatives: exactly one.
+func TestWakeBroadcasts(t *testing.T) {
+	head := "listen = \"127.0.0.1:1\"\n[hosts.a]\nbase_url = \"http://a:1\"\nmodels = { \"m\" = { } }\n[hosts.a.wake]\nmac = \"aa:bb:cc:dd:ee:ff\"\n"
+	tail := "\n[routes.r]\nhosts = [\"a\"]\n"
+	c, err := config.Parse(strings.NewReader(head + `broadcasts = ["192.168.88.255:9", "192.168.1.255:9"]` + tail))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := c.Hosts["a"].Wake.Addresses(); len(got) != 2 || got[0] != "192.168.88.255:9" || got[1] != "192.168.1.255:9" {
+		t.Errorf("Addresses() = %v, want both, in order", got)
+	}
+	c, err = config.Parse(strings.NewReader(head + `broadcast = "192.168.88.255:9"` + tail))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := c.Hosts["a"].Wake.Addresses(); len(got) != 1 || got[0] != "192.168.88.255:9" {
+		t.Errorf("Addresses() = %v, want the single broadcast", got)
+	}
+	for name, body := range map[string]string{
+		"both":       "broadcast = \"192.168.88.255:9\"\nbroadcasts = [\"192.168.1.255:9\"]",
+		"neither":    "wait = \"30s\"",
+		"empty list": "broadcasts = []",
+		"bad entry":  "broadcasts = [\"192.168.1.255\"]", // no port
+	} {
+		t.Run(name, func(t *testing.T) {
+			_, err := config.Parse(strings.NewReader(head + body + tail))
+			ce, ok := err.(*config.Error)
+			if !ok || !strings.HasPrefix(ce.Field, "hosts.a.wake") {
+				t.Fatalf("err = %v, want *config.Error under hosts.a.wake", err)
+			}
+		})
+	}
+}

docs/plans/v2.2/_files/internal/proxy/template_test.go

@@ -0,0 +1,85 @@
+package proxy_test
+
+import (
+	"net/http"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+	"git.wntrmute.dev/kyle/crossbar/internal/store"
+)
+
+const templateHosts = `
+listen = "127.0.0.1:1"
+[hosts.alpha]
+base_url = %q
+models = { "shared" = { parallel = 4 } }
+[routes."opencode-*"]
+hosts = ["alpha"]
+default_model = "shared"
+[routes.opencode-fixed]
+hosts = ["alpha"]
+default_model = "shared"
+`
+
+// One OpenCode instance per route, without listing every instance in the config: a route named
+// "opencode-*" serves any request route "opencode-<something>". Leases and accounting are keyed
+// by the concrete route name, so two instances never share a lease and each gets its own usage
+// row. The literal template name is never a request route.
+func TestRouteTemplateServesConcreteRoutes(t *testing.T) {
+	alpha := newUpstream(t, "alpha")
+	r := newRig(t, templateHosts, alpha)
+
+	resp := r.post("/opencode-projecta-4242/v1/chat/completions", conversation(1, 1))
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.HostHeader) != "alpha" || resp.Header.Get(proxy.LeaseHeader) != "new" {
+		t.Fatalf("first turn on a templated route: %d %q %q, want 200 alpha new", resp.StatusCode, resp.Header.Get(proxy.HostHeader), resp.Header.Get(proxy.LeaseHeader))
+	}
+	resp = r.post("/opencode-projecta-4242/v1/chat/completions", conversation(1, 2))
+	drain(resp)
+	if resp.Header.Get(proxy.LeaseHeader) != "reused" {
+		t.Errorf("second turn should reuse the lease, got %q", resp.Header.Get(proxy.LeaseHeader))
+	}
+	// A second instance with the same conversation shape is a different route: its own lease.
+	resp = r.post("/opencode-projectb-7/v1/chat/completions", conversation(1, 1))
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.LeaseHeader) != "new" {
+		t.Errorf("another instance must get its own lease: %d %q", resp.StatusCode, resp.Header.Get(proxy.LeaseHeader))
+	}
+	// The header form resolves templates too.
+	resp = r.post("/v1/chat/completions", conversation(2, 1), proxy.RouteHeader, "opencode-projectc-1")
+	drain(resp)
+	if resp.StatusCode != 200 {
+		t.Errorf("X-Crossbar-Route with a templated name: %d, want 200", resp.StatusCode)
+	}
+	// An exact route still works and is not shadowed by the template.
+	resp = r.post("/opencode-fixed/v1/chat/completions", conversation(3, 1))
+	drain(resp)
+	if resp.StatusCode != 200 {
+		t.Errorf("exact route: %d, want 200", resp.StatusCode)
+	}
+
+	for _, path := range []string{"/opencode-*/v1/models", "/opencode-/v1/models", "/opencode/v1/models", "/opencodex/v1/models"} {
+		req, _ := http.NewRequest(http.MethodGet, r.front.URL+path, nil)
+		resp, err := http.DefaultClient.Do(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		drain(resp)
+		if resp.StatusCode != 404 {
+			t.Errorf("%s: %d, want 404 unknown route", path, resp.StatusCode)
+		}
+	}
+
+	rows, _ := r.store.Usage(time.Time{}, store.ByRoute)
+	keys := map[string]int64{}
+	for _, row := range rows {
+		keys[row.Key] = row.Requests
+	}
+	if keys["opencode-projecta-4242"] != 2 || keys["opencode-projectb-7"] != 1 || keys["opencode-projectc-1"] != 1 || keys["opencode-fixed"] != 1 {
+		t.Errorf("usage by route = %v, want rows per concrete route", keys)
+	}
+	if _, present := keys["opencode-*"]; present {
+		t.Errorf("the template name must never be an accounting key: %v", keys)
+	}
+}

docs/plans/v2.2/_files/internal/wake/broadcasts_test.go

@@ -0,0 +1,73 @@
+package wake_test
+
+import (
+	"net"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/wake"
+)
+
+// listener returns a UDP socket on 127.0.0.1 and a channel that gets one value per datagram.
+func listener(t *testing.T) (string, <-chan []byte) {
+	t.Helper()
+	pc, err := net.ListenPacket("udp4", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { pc.Close() })
+	got := make(chan []byte, 4)
+	go func() {
+		buf := make([]byte, 256)
+		for {
+			n, _, err := pc.ReadFrom(buf)
+			if err != nil {
+				return
+			}
+			b := make([]byte, n)
+			copy(b, buf[:n])
+			got <- b
+		}
+	}()
+	return pc.LocalAddr().String(), got
+}
+
+func expectPacket(t *testing.T, name string, got <-chan []byte) {
+	t.Helper()
+	select {
+	case b := <-got:
+		if len(b) != 102 {
+			t.Errorf("%s: got %d bytes, want a 102-byte magic packet", name, len(b))
+		}
+	case <-time.After(2 * time.Second):
+		t.Errorf("%s: no packet within two seconds", name)
+	}
+}
+
+// A target may name several broadcast addresses (a host that roams between two networks): the
+// packet goes to every one of them, and one address that cannot be resolved does not stop the
+// others.
+func TestWakeSendsToEveryBroadcast(t *testing.T) {
+	a, gotA := listener(t)
+	b, gotB := listener(t)
+	h := &fakeHealth{after: 1 << 30} // never healthy
+	w := wake.New(map[string]wake.Target{"titan": {MAC: "aa:bb:cc:dd:ee:ff", Broadcasts: []string{a, "256.1.1.1:9", b}, Wait: 300 * time.Millisecond}}, h)
+	w.PollEvery(20 * time.Millisecond)
+	if w.Wake(t.Context(), "titan") {
+		t.Errorf("Wake must report false when the host never comes up")
+	}
+	expectPacket(t, "first address", gotA)
+	expectPacket(t, "third address, after an unresolvable second", gotB)
+}
+
+// The single-address form keeps working, alone or together with the list.
+func TestWakeBroadcastAndBroadcastsCombine(t *testing.T) {
+	a, gotA := listener(t)
+	b, gotB := listener(t)
+	h := &fakeHealth{after: 1 << 30} // never healthy
+	w := wake.New(map[string]wake.Target{"titan": {MAC: "aa:bb:cc:dd:ee:ff", Broadcast: a, Broadcasts: []string{b}, Wait: 300 * time.Millisecond}}, h)
+	w.PollEvery(20 * time.Millisecond)
+	w.Wake(t.Context(), "titan")
+	expectPacket(t, "Broadcast", gotA)
+	expectPacket(t, "Broadcasts[0]", gotB)
+}

docs/plans/v2.3/01-control-plane.md

@@ -0,0 +1,77 @@
+# v2.3 task 01: control-plane requests
+
+**Branch:** `v2.3` (`git switch -c v2.3 master` if it does not exist, else `git switch v2.3`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Control-plane requests follow the lease but take no slot and write no row`
+
+## Goal
+
+A client that manages its own llama-server slot makes small calls beside its chat stream: it
+polls `GET /slots?model=X` while it waits, reads `GET /props?model=X`, tokenizes, and sends
+`POST /v1/chat/completions/control` on a second connection **while its own stream holds a slot**.
+Today `/slots` and `/tokenize` are 404, a GET is leased under the route's default model instead
+of `?model=`, and every call takes a limiter slot — so `/control` can queue behind its own
+stream, or get 503 when the queue is full. After this task those calls follow the lease like any
+request but never wait for or take a slot, skip the context guard, and write no accounting row.
+
+## Files
+
+- Copy: `internal/proxy/control_test.go`, and the **replacement** `internal/proxy/proxy_test.go`
+  (overwrites the v1 copy: the `/r/slots → 404` row becomes `/r/slots/0` and `/r/metrics`; the
+  v2.3 copy is now the protected one)
+- Create: `internal/proxy/control.go` — the control-call test and the model-from-query rule live
+  here (`proxy.go` is at 325 lines)
+- Modify: `internal/proxy/proxy.go`, `internal/proxy/forward.go`, `docs/implementer-log.md`
+
+## Rules
+
+1. **Model.** The body's top-level `"model"` wins; else the query parameter `model`
+   (`r.URL.Query().Get("model")`); else the route's `default_model`. This is used for the lease
+   key and the limiter pair, exactly where the body model is used today.
+2. **Paths.** `allowedPath` also admits `rest == "/slots"` and `rest == "/tokenize"` (exact
+   match on the path; the query string is not part of `rest`). `/slots/0`, `/slots/0?action=…`
+   and anything else stay `404 {"error":"not found"}`.
+3. **Control calls** are: method `GET` or `HEAD` (any allowed path), or method `POST` with
+   `rest` exactly `/tokenize` or `/v1/chat/completions/control`. Everything else — in
+   particular `POST /v1/chat/completions` — is not a control call.
+4. A control call is routed and leased exactly as today (same `lease.Acquire`, same wake path
+   when no host is healthy), then forwarded **without** `lim.Acquire`, **without** the context
+   guard, and **without** an accounting row (`writeRecord` is not called for it). Its log line
+   is `Debug`, not `Info` (a client polls `/slots` every 5 s). It still gets the
+   `X-Crossbar-Host` / `X-Crossbar-Lease` headers and still marks a host down on a transport
+   error, like any forward.
+5. Do not duplicate `forward`. Pass what it needs to know (for example a `control bool`, or a
+   small options struct if the parameter list gets long) and skip the row and the `Info` log
+   inside it.
+
+## Facts you need
+
+- `peekModel` already reads and restores the body; `GET`/`HEAD` return `""` there. The query
+  fallback goes after it, in one place.
+- The rig in `helpers_test.go` passes the store as the recorder, and the row is written after
+  the answer is sent — the tests wait for rows; do not add sleeps to production code.
+- `waitUntil` is defined in `proxy_test.go`; `conversation(id, turn)` builds a chat body.
+
+## Steps
+
+- [ ] **1.** Branch as above; copy the two given files.
+- [ ] **2. See them fail:** `go test -count=1 ./internal/proxy/ -run 'TestGetModel|TestControl|TestChatIsNotControl'`
+  → 404 on `/slots` and `/tokenize`, 503 `queue full` on control calls, 4 stray rows.
+- [ ] **3.** `control.go`: the control-call test and the model rule. **4.** `proxy.go`: use them;
+  branch in `serveLeased` (no limiter, no guard for a control call). **5.** `forward.go`: no row,
+  `Debug` log for a control call.
+- [ ] **6.** `gofmt -w`; `go test -race -count=3 ./internal/proxy/` → `ok`.
+- [ ] **7.** `make gate`; `make smoke`. **8.** Row `v2.3/01-control-plane`; commit.
+
+```sh
+git add internal/proxy docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- The new tests and every earlier proxy test pass under `-race -count=3`; gate and smoke ok;
+  given files byte-identical; no file over 400 lines.
+
+## Stop and report if
+
+- Passing needs a change to any given test, or `forward` cannot skip the row without copying it.

docs/plans/v2.3/02-affinity-queue.md

@@ -0,0 +1,96 @@
+# v2.3 task 02: route affinity and queue = false
+
+**Branch:** `v2.3` (`git switch v2.3`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Routes may share one lease (affinity = "route") and skip crossbar's queue (queue = false)`
+
+## Goal
+
+Two route keys for a client that manages its own slot:
+
+- `affinity = "route"` — one lease for the whole route. Today each conversation (fingerprint)
+  gets its own lease, and calls without a fingerprint lease "the route itself"; a client whose
+  `/control` and `/slots` calls must reach the host its chat is on needs them all on one lease.
+- `queue = false` — crossbar never holds or refuses the route's requests. The client pins its
+  llama-server slot (`id_slot`), so llama-server queues it and its `/slots` shows the slot busy;
+  a request held in crossbar's queue instead looks idle to the client, which gives up after 30 s.
+  The requests still count as load on the host, so routes that do queue see the host full.
+
+## Files
+
+- Copy: `internal/config/config_v23_test.go`, `internal/limiter/track_test.go`,
+  `internal/proxy/affinity_test.go`
+- Modify: `internal/config/route.go` (**move the `Route` struct here** from `config.go`, which
+  is at 398 lines, and add the fields and methods here; `config.go` keeps a one-line call into
+  the route validation), `internal/config/config.go` (minimal), `internal/limiter/limiter.go`,
+  `internal/proxy/proxy.go` (or `control.go` if `proxy.go` would pass 400 lines),
+  `docs/implementer-log.md`
+
+## Interfaces
+
+```go
+package config
+
+type Route struct {
+	Hosts        []string `toml:"hosts"`
+	DefaultModel string   `toml:"default_model"`
+	Peers        []string `toml:"peers"`
+	Affinity     string   `toml:"affinity"` // "" or "conversation" (the default), or "route"
+	Queue        *bool    `toml:"queue"`    // nil means true
+}
+
+// PerRoute reports affinity = "route": every request on the route shares one lease.
+func (r Route) PerRoute() bool
+
+// Queues reports whether the route's requests wait in (and can be refused by) crossbar's
+// per-(host, model) queue; false only for queue = false.
+func (r Route) Queues() bool
+
+package limiter
+
+// Track counts one request against (host, model) without waiting and without refusing: in flight
+// may exceed parallel. The returned release is idempotent.
+func (l *Limiter) Track(host, model string) (release func())
+```
+
+## Rules
+
+1. **Validation.** `affinity` other than `""`, `"conversation"` or `"route"` is an error whose
+   text contains `routes.<name>.affinity` (for example
+   `routes.convo.affinity: must be "conversation" or "route"`). Both keys are allowed on
+   templates; `cfg.Route(name)` returns them for every concrete route the template serves.
+2. **Lease key.** For a `PerRoute()` route the lease key's fingerprint is `""` for **every**
+   request (chat or control), so every request on the route uses one lease per model. The
+   accounting row keeps the request's real fingerprint (it is still useful in usage views).
+3. **Queue.** For a route where `Queues()` is false, a non-control request takes
+   `lim.Track(host, model)` instead of `lim.Acquire` (and releases it when done, like the slot).
+   Control calls (task 01) take neither.
+4. **Release rule.** A release — from `Acquire`'s slot or from `Track` — hands the slot to the
+   first waiter **only when in flight ≤ parallel** at that moment; otherwise it just decrements
+   in flight. (With only `Acquire` in use in-flight never exceeds parallel, so today's behaviour
+   is unchanged.) `InFlight`, `FreeSlots` and `Queued` count tracked requests like any other.
+5. The context guard runs as today on both kinds of route.
+
+## Steps
+
+- [ ] **1.** `git switch v2.3`; copy the three given tests.
+- [ ] **2. See them fail** (compile: `PerRoute`, `Queues`, `Track` missing).
+- [ ] **3.** `route.go` (struct move, fields, methods, validation). **4.** `limiter.go`
+  (`Track`, the release rule). **5.** `proxy.go` (lease key, `Track`).
+- [ ] **6.** `gofmt -w`; `go test -race -count=3 ./internal/limiter/ ./internal/config/ ./internal/proxy/` → `ok`.
+- [ ] **7.** `make gate`; `make smoke`. **8.** Row `v2.3/02-affinity-queue`; commit.
+
+```sh
+git add internal/config internal/limiter internal/proxy docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- The new tests and every earlier test pass under `-race -count=3`; every earlier limiter test
+  is still green (the release rule must not change `Acquire`-only behaviour); gate and smoke ok;
+  given files byte-identical; no file over 400 lines.
+
+## Stop and report if
+
+- The struct move breaks a given test, or the release rule cannot be met without changing
+  `Acquire`'s results in an earlier test.

docs/plans/v2.3/03-route-listeners.md

@@ -0,0 +1,91 @@
+# v2.3 task 03: a route's dedicated listener
+
+**Branch:** `v2.3` (`git switch v2.3`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `A route may have its own listener: every request there is that route, paths unprefixed`
+
+## Goal
+
+Boxmaker's `inferproxy` connects to one host:port and rewrites nothing: its paths are
+`/v1/chat/completions`, `/slots?model=…`, and it sends no extra header. Crossbar reads the route
+from the first path segment or `X-Crossbar-Route`, so it cannot route those requests. After this
+task a concrete route may set `listen = "host:port"`; crossbar serves that address too, and every
+request arriving there is that route, with the whole path passed upstream as it is.
+
+## Files
+
+- Copy: `internal/config/listen_test.go`, `internal/proxy/listener_test.go`,
+  `internal/identity/route_middleware_test.go`, and the **replacements** `example.toml` (was
+  v2.2's) and `tools/smoke.sh` (was v2's; adds check 6) — the v2.3 copies are now protected
+- Modify: `internal/config/route.go` (the `Listen` field and its validation),
+  `internal/proxy/proxy.go` (or a new `internal/proxy/listener.go`), 
+  `internal/identity/middleware.go`, `cmd/crossbar/main.go`, `docs/implementer-log.md`
+
+## Interfaces
+
+```go
+package config
+// in Route:
+	Listen string `toml:"listen"` // "" = none; else host:port of the route's own listener
+
+package proxy
+// ForRoute serves route alone: the request path is the upstream path (no route segment is
+// taken from it), and everything after routing is exactly what ServeHTTP does.
+func (p *Handler) ForRoute(route string) http.Handler
+
+package identity
+// RouteMiddleware gates every request on peers (the fixed route's allow list), whatever path or
+// X-Crossbar-Route header it carries. Empty peers lets everyone through, as for Middleware.
+func RouteMiddleware(c *Checker, peers []string, next http.Handler) http.Handler
+```
+
+## Rules
+
+1. **Validation** (errors name the key):
+   - `listen` must split with `net.SplitHostPort` and its port must be a number 1–65535
+     (`strconv.Atoi`) → else an error containing `routes.<name>.listen`.
+   - Not on a template: `routes.<name>.listen: a template route cannot have its own listener`
+     (the text contains the template's name, e.g. `t-*`).
+   - Not the top-level `listen`: an error containing `routes.<name>.listen`.
+   - Unique across routes: the second route (in sorted name order) gets an error containing
+     `routes.<name>.listen` and the other route's name.
+2. **`ForRoute(route)`** for each request:
+   - `cfg.Route(route)` not ok → `404 {"error":"unknown route"}`.
+   - `X-Crossbar-Route` set and different from `route` → `400 {"error":"conflicting route"}`;
+     set and equal → ignored.
+   - `rest` is `r.URL.Path` unchanged; `allowedPath(rest)` false → `404 {"error":"not found"}`.
+     So `/bm/v1/models` (a prefixed path) and `/_crossbar/hosts` are 404 on the listener.
+   - Then the same flow as `ServeHTTP` from the model peek onwards — factor that flow into one
+     function both call; do not copy it.
+3. **`RouteMiddleware`**: like `Middleware`, including the `X-Crossbar-Peer` context for
+   header mode, but with the fixed peers and **no** admin-path exemption (there is no admin on
+   a route listener).
+4. **`main.go`**: for each route with `Listen` set, in sorted route order, one more
+   `http.Server{Addr: rt.Listen, Handler: h, ReadHeaderTimeout: 10 * time.Second}` where `h` is
+   `p.ForRoute(name)`, wrapped in `identity.RouteMiddleware(checker, rt.Peers, …)` when identity
+   is not `off`. No admin mux on it. Log `listening` with `addr` and `route`. All servers shut
+   down together on ctx done; any server's error other than `http.ErrServerClosed` ends `run`
+   with that error (and shuts the others down).
+
+## Steps
+
+- [ ] **1.** `git switch v2.3`; copy the five given files.
+- [ ] **2. See them fail** (compile: `Listen`, `ForRoute`, `RouteMiddleware` missing).
+- [ ] **3.** `route.go`. **4.** proxy (`ForRoute`, the shared flow). **5.** `middleware.go`.
+  **6.** `main.go`.
+- [ ] **7.** `gofmt -w`; `go test -race -count=3 ./internal/config/ ./internal/proxy/ ./internal/identity/` → `ok`.
+- [ ] **8.** `make gate`; `make smoke` (check 6 is the dedicated listener on 127.0.0.1:17801).
+- [ ] **9.** Row `v2.3/03-route-listeners`; commit.
+
+```sh
+git add internal/config internal/proxy internal/identity cmd/crossbar example.toml tools/smoke.sh docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- All given tests pass under `-race -count=3`; gate and smoke ok; given files byte-identical;
+  no file over 400 lines.
+
+## Stop and report if
+
+- Smoke check 6 fails for a reason in the fake upstream or the script rather than in crossbar.

docs/plans/v2.3/04-ctx-error-docs.md

@@ -0,0 +1,57 @@
+# v2.3 task 04: llama-server's error shape for a context refusal; README
+
+**Branch:** `v2.3` (`git switch v2.3`; `git status --short` must be empty, otherwise stop)
+**Commit subject:** `Context refusal in llama-server's exceed_context_size_error shape; README for v2.3`
+
+## Goal
+
+When no host can fit a prompt, crossbar answers `400 {"error":"prompt too large","estimate":N,"max":M}`.
+A client that already handles llama-server's own overflow error (Boxmaker keys on `error.type`
+and reads only the first 4 KiB) does not recognise it. After this task the body is the server's
+shape, so the client handles crossbar's refusal like the server's:
+
+```json
+{"error":{"code":400,"type":"exceed_context_size_error","message":"prompt too large","n_prompt_tokens":N,"n_ctx":M}}
+```
+
+`N` is the estimate and `M` the largest per-slot context on the route, as before.
+
+## Files
+
+- Copy: the **replacements** `internal/proxy/ctxguard_test.go` (was v2's) and
+  `internal/proxy/ctxguard_router_test.go` (was v2.1's); only their 400-body assertions changed;
+  the v2.3 copies are now protected
+- Modify: `internal/proxy/ctxguard.go` (`refuseCtx`), `README.md`, `docs/implementer-log.md`
+
+## Rules
+
+1. The body is exactly one JSON object whose only top-level key is `"error"`, so it starts with
+   `{"error":`; `Content-Type: application/json`; status 400. The accounting row is unchanged
+   (status 400, `Err` "prompt too large"). Every other crossbar error keeps its current
+   `{"error":"<text>"}` shape.
+2. `README.md`:
+   - The context-guard section: the new body.
+   - A new section **"Clients that manage their own slots"** covering: control calls (which
+     requests, and that they follow the lease but take no slot, skip the guard and write no
+     row); `/slots` and `/tokenize` are proxied, `/slots/<id>` actions are not; a GET's model
+     comes from `?model=`; the route keys `affinity`, `queue` and `listen` with the
+     `boxmaker-a` example from `example.toml`; that `listen` is refused on templates and must
+     not be the main address; that the admin API is not served on a route listener.
+   - The "hosts view"/config reference tables, if they list route keys, gain the three keys.
+
+## Steps
+
+- [ ] **1.** `git switch v2.3`; copy the replacement test. **2. See it fail** (old body).
+- [ ] **3.** `refuseCtx`. **4.** README.
+- [ ] **5.** `gofmt -w`; `make gate`; `make smoke` (check 3 still finds `"prompt too large"`).
+- [ ] **6.** Row `v2.3/04-ctx-error-docs`; commit.
+
+```sh
+git add internal/proxy README.md docs/implementer-log.md
+git commit
+```
+
+## Done when
+
+- All tests pass; gate and smoke ok; given files byte-identical; README describes what v2.3
+  does and nothing it does not.

docs/plans/v2.3/README.md

@@ -0,0 +1,74 @@
+# v2.3 implementation plan: clients that manage their own slots
+
+> **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:** serve Boxmaker, a harness whose `inferproxy` talks plain HTTP/1.1 to one host:port and
+rewrites nothing. It pins `id_slot`, polls `GET /slots?model=` while it waits, reads
+`GET /props?model=` once, and sends `POST /v1/chat/completions/control` on a second connection
+while its own stream is running. Checked on 2026-09-25 against crossbar at 4c64158, it failed on
+six counts (thread `i7jeubrtziru38s5gn8gmha44a`): no route in its paths; `/slots` and `/tokenize`
+not proxied; side calls leased separately from the stream; `/control` taking a limiter slot
+behind its own stream; crossbar's queue hiding a waiting request from the server's `/slots`; and a
+context refusal that is not llama-server's `exceed_context_size_error`.
+
+- **01-control-plane** — every route: a GET's model comes from `?model=`; `/slots` and
+  `/tokenize` are proxied; control calls (any GET/HEAD, `POST /tokenize`,
+  `POST /v1/chat/completions/control`) follow the lease but skip the limiter, the context guard
+  and the accounting row. Given: `proxy/control_test.go`; replaces `proxy/proxy_test.go` (v1:
+  the `/r/slots → 404` row becomes `/r/slots/0` and `/r/metrics`).
+- **02-affinity-queue** — route keys `affinity = "route"` (one lease for the route) and
+  `queue = false` (count the request as load, never hold or refuse it); `limiter.Track`.
+  Given: `config/config_v23_test.go`, `limiter/track_test.go`, `proxy/affinity_test.go`.
+- **03-route-listeners** — route key `listen`: a dedicated listener where every request is that
+  route with an unprefixed path; `Handler.ForRoute`, `identity.RouteMiddleware`, one server per
+  listener in `main`. Given: `config/listen_test.go`, `proxy/listener_test.go`,
+  `identity/route_middleware_test.go`; replaces `example.toml` (v2.2: adds `boxmaker-a`) and
+  `tools/smoke.sh` (v2: adds check 6, the dedicated listener).
+- **04-ctx-error-docs** — the context refusal in llama-server's shape
+  `{"error":{"code":400,"type":"exceed_context_size_error","message":"prompt too large","n_prompt_tokens":N,"n_ctx":M}}`;
+  README. Given: replaces `proxy/ctxguard_test.go` (v2) and `proxy/ctxguard_router_test.go` (v2.1).
+
+**Order matters:** 02's affinity test uses `/slots` (01); 03's listener test uses route affinity
+(02). Each task is green on its own given tests plus all earlier ones.
+
+**How this plan was made:** acceptance tests first, no reference implementation; the given tests
+compiled against a panic-only skeleton of the new names (`Route.PerRoute`, `Route.Queues`,
+`Route.Listen`, `Limiter.Track`, `Handler.ForRoute`, `identity.RouteMiddleware`) on master
+4c64158 and failed there for the intended reasons (404 on `/slots`/`/tokenize`, 503 queue full
+on control calls, 4 stray accounting rows, the old error body, requests held behind one slot,
+unvalidated `listen`/`affinity`).
+
+**Facts about the live hosts (2026-09-25):** all three routers run llama-server b10964; `/slots`
+answers 200 on all three; `POST /v1/chat/completions/control` exists (`{"success":false,"message":"no
+active completion for this id"}` for an unknown id). In router mode `GET /slots?model=X` and
+`/props?model=X` **autoload X** — a control call only ever reaches the leased host, which is where
+the client's chat goes anyway, so this is the load the client asked for.
+
+## Global constraints
+
+- Everything in `AGENTS.md`. Branch `v2.3` from `master`. One task, one fresh OpenCode session,
+  one commit. Given files are copied and never edited; earlier plans' given files stay protected,
+  except the five this plan replaces (`proxy/proxy_test.go`, `proxy/ctxguard_test.go`,
+  `proxy/ctxguard_router_test.go`, `example.toml`, `tools/smoke.sh`), whose v2.3 copies are then the protected ones.
+
+## Changes during the run
+
+- 2026-09-25, before task 02: straylight ran short of memory and Claude Code's reaper killed the
+  driver after task 01 committed (`33fa61b`, first-gate); resumed at 02 an hour later.
+- Task 02: **owner test fault, model hack.** `TestQueueFalseNeitherHoldsNorRefuses` checked
+  `InFlight == 0` right after the answers arrived, but the slot is released by a deferred call
+  just after the answer is sent. Ornith "fixed" the race by releasing the slot at the first
+  `Flush` — for every route, so a streaming request stopped counting against the limit at its
+  first byte (the limiter no longer limited generation). No given test caught it. Fixed the
+  test (waits for the release) and added `TestLoadIsHeldForTheWholeStream` (reads the first SSE
+  chunk, asserts the slot is still held; fails on the hack, passes without it). Owner removed the
+  `onFlush` hook and the `release` parameter from `forward`. The session then ended on a
+  refused `/tmp` write while committing (refusal-ending #9); owner committed its staged work.
+- Task 03: first session emitted a stray `</tool_call>` after reading files and ended with no
+  change (model); restarted unchanged, done in 16 min (`fa1c398`).
+- Task 04: **owner fault, correct stop.** The v2.1 given `ctxguard_router_test.go` also asserts
+  the refusal body (`e["max"]`); I grepped only for the `"prompt too large"` string when
+  writing the replacement list. Ornith implemented the new shape, saw the two protected tests
+  demand incompatible bodies, committed only its `stopped` row, and reported — exactly the
+  AGENTS.md rule. Replacement `ctxguard_router_test.go` (reads `error.n_ctx`) added.

docs/plans/v2.3/_files/example.toml

@@ -0,0 +1,43 @@
+# 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
+# broadcasts = ["127.0.0.1:19082", "127.0.0.1:19083"]  # v2.2: a roaming host on several networks; this or broadcast, not both, and at least one
+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
+
+# v2.3: a client that manages its own llama-server slot (it pins id_slot, polls /slots, steers a
+# running completion through /v1/chat/completions/control) and cannot put a route in the path.
+# The route gets its own port; every request there is this route and the path goes upstream as is.
+[routes.boxmaker-a]
+hosts         = ["beta", "alpha"]
+default_model = "ornith-1.5-35b-a3b"
+listen        = "127.0.0.1:17801"      # a tailnet address in production; never the main listen address
+affinity      = "route"                # one lease for the whole route, not one per conversation
+queue         = false                  # counted as load but never held or refused: the server's own slot queue does that

docs/plans/v2.3/_files/internal/config/config_v23_test.go

@@ -0,0 +1,75 @@
+package config_test
+
+// v2.3 task 02: the affinity and queue route keys.
+
+import (
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+)
+
+const affinityBase = `
+listen = "127.0.0.1:1"
+[hosts.a]
+base_url = "http://a:1"
+models = { "m" = { } }
+[routes.plain]
+hosts = ["a"]
+[routes.convo]
+hosts = ["a"]
+affinity = "conversation"
+[routes.boxmaker]
+hosts = ["a"]
+affinity = "route"
+queue = false
+[routes."bm-*"]
+hosts = ["a"]
+affinity = "route"
+queue = false
+[routes.queued]
+hosts = ["a"]
+queue = true
+`
+
+func TestAffinityAndQueueKeys(t *testing.T) {
+	c, err := config.Parse(strings.NewReader(affinityBase))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct {
+		route            string
+		perRoute, queues bool
+	}{
+		{"plain", false, true}, // defaults: conversation affinity, queueing on
+		{"convo", false, true},
+		{"boxmaker", true, false},
+		{"bm-agent-1", true, false}, // a template's keys reach its concrete routes
+		{"queued", false, true},
+	} {
+		r, _, ok := c.Route(tc.route)
+		if !ok {
+			t.Fatalf("route %q not found", tc.route)
+		}
+		if r.PerRoute() != tc.perRoute || r.Queues() != tc.queues {
+			t.Errorf("%s: PerRoute %v Queues %v, want %v %v", tc.route, r.PerRoute(), r.Queues(), tc.perRoute, tc.queues)
+		}
+	}
+}
+
+func TestAffinityRejectsUnknownValues(t *testing.T) {
+	for _, bad := range []string{`"session"`, `"Route"`, `1`} {
+		text := strings.Replace(affinityBase, `affinity = "conversation"`, "affinity = "+bad, 1)
+		_, err := config.Parse(strings.NewReader(text))
+		if err == nil || !strings.Contains(err.Error(), "routes.convo.affinity") {
+			t.Errorf("affinity = %s: err %v, want one naming routes.convo.affinity", bad, err)
+		}
+	}
+}
+
+func TestQueueMustBeABool(t *testing.T) {
+	text := strings.Replace(affinityBase, "queue = true", `queue = "no"`, 1)
+	if _, err := config.Parse(strings.NewReader(text)); err == nil {
+		t.Error(`queue = "no" parsed; want an error`)
+	}
+}

docs/plans/v2.3/_files/internal/config/listen_test.go

@@ -0,0 +1,54 @@
+package config_test
+
+// v2.3 task 03: a concrete route may own a dedicated listener. Every request that arrives on it is
+// that route, with the upstream path unprefixed, for clients that cannot put a route in the path
+// or a header (Boxmaker's inferproxy rewrites nothing).
+
+import (
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/config"
+)
+
+const listenBase = `
+listen = "127.0.0.1:7777"
+[hosts.a]
+base_url = "http://a:1"
+models = { "m" = { } }
+[routes.bm-a]
+hosts = ["a"]
+listen = "127.0.0.1:7801"
+[routes.bm-b]
+hosts = ["a"]
+listen = "127.0.0.1:7802"
+[routes.plain]
+hosts = ["a"]
+`
+
+func TestRouteListen(t *testing.T) {
+	c, err := config.Parse(strings.NewReader(listenBase))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for route, want := range map[string]string{"bm-a": "127.0.0.1:7801", "bm-b": "127.0.0.1:7802", "plain": ""} {
+		if got := c.Routes[route].Listen; got != want {
+			t.Errorf("%s listen = %q, want %q", route, got, want)
+		}
+	}
+}
+
+func TestRouteListenRejected(t *testing.T) {
+	for _, tc := range []struct{ name, text, want string }{
+		{"not host:port", strings.Replace(listenBase, `"127.0.0.1:7801"`, `"7801"`, 1), "routes.bm-a.listen"},
+		{"bad port", strings.Replace(listenBase, `"127.0.0.1:7801"`, `"127.0.0.1:http"`, 1), "routes.bm-a.listen"},
+		{"port zero", strings.Replace(listenBase, `"127.0.0.1:7801"`, `"127.0.0.1:0"`, 1), "routes.bm-a.listen"},
+		{"same as another route", strings.Replace(listenBase, `"127.0.0.1:7802"`, `"127.0.0.1:7801"`, 1), "listen"},
+		{"same as the main listener", strings.Replace(listenBase, `"127.0.0.1:7801"`, `"127.0.0.1:7777"`, 1), "routes.bm-a.listen"},
+		{"on a template", listenBase + "[routes.\"t-*\"]\nhosts = [\"a\"]\nlisten = \"127.0.0.1:7803\"\n", "t-*"},
+	} {
+		if _, err := config.Parse(strings.NewReader(tc.text)); err == nil || !strings.Contains(err.Error(), tc.want) {
+			t.Errorf("%s: err %v, want one containing %q", tc.name, err, tc.want)
+		}
+	}
+}

docs/plans/v2.3/_files/internal/identity/route_middleware_test.go

@@ -0,0 +1,47 @@
+package identity_test
+
+// v2.3 task 03: on a route's dedicated listener the route is fixed, so the gate is that route's
+// peers for every request, whatever path or X-Crossbar-Route header the caller sends.
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/identity"
+)
+
+func TestRouteMiddleware(t *testing.T) {
+	inner := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(204) })
+	checker := identity.NewChecker(fakeResolver{"100.64.0.5": "talos", "100.64.0.9": "titan"})
+	locked := identity.RouteMiddleware(checker, []string{"talos"}, inner)
+	open := identity.RouteMiddleware(checker, nil, inner)
+	for _, tc := range []struct {
+		name      string
+		h         http.Handler
+		path, hdr string
+		addr      string
+		want      int
+	}{
+		{"right peer", locked, "/v1/chat/completions", "", "100.64.0.5:5", 204},
+		{"wrong peer", locked, "/v1/chat/completions", "", "100.64.0.9:5", 403},
+		{"not a peer", locked, "/slots", "", "203.0.113.1:5", 403},
+		{"a path that looks like an open route is still this route", locked, "/open/v1/models", "", "100.64.0.9:5", 403},
+		{"a header naming another route does not change the gate", locked, "/v1/models", "open", "100.64.0.9:5", 403},
+		{"admin-looking path is gated too (no admin on this listener)", locked, "/_crossbar/hosts", "", "100.64.0.9:5", 403},
+		{"open route, anyone", open, "/v1/models", "", "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()
+			tc.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())
+			}
+		})
+	}
+}

docs/plans/v2.3/_files/internal/limiter/track_test.go

@@ -0,0 +1,91 @@
+package limiter_test
+
+// v2.3 task 02: Track counts a request without holding or refusing it. A route with queue = false
+// leaves queueing to llama-server's own slots, but its requests are still load on the host, so the
+// routes that do queue must see them.
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/limiter"
+)
+
+func TestTrackNeverWaitsAndCounts(t *testing.T) {
+	l := limiter.New()
+	l.Configure("alpha", "m", 1, 0) // one slot, no waiting room
+
+	start := time.Now()
+	rel1 := l.Track("alpha", "m")
+	rel2 := l.Track("alpha", "m")
+	rel3 := l.Track("alpha", "m")
+	if d := time.Since(start); d > 50*time.Millisecond {
+		t.Fatalf("Track waited %v", d)
+	}
+	if n := l.InFlight("alpha", "m"); n != 3 {
+		t.Fatalf("in flight = %d, want 3 (Track may pass parallel)", n)
+	}
+	if n := l.FreeSlots("alpha"); n != 0 {
+		t.Errorf("free slots = %d, want 0", n)
+	}
+	// A queueing request sees the host full: no waiting room, so it is refused.
+	if _, _, err := l.Acquire(context.Background(), "alpha", "m"); err == nil {
+		t.Error("Acquire on an over-tracked pair succeeded; want ErrQueueFull")
+	}
+	rel1()
+	rel1() // idempotent
+	rel2()
+	rel3()
+	if n := l.InFlight("alpha", "m"); n != 0 {
+		t.Errorf("in flight after release = %d, want 0", n)
+	}
+}
+
+// A waiter gets a slot only once in flight is back under parallel: releasing a tracked request
+// while the pair is still over its limit must not hand the slot on.
+func TestTrackReleaseHandsOverOnlyUnderTheLimit(t *testing.T) {
+	l := limiter.New()
+	l.Configure("alpha", "m", 1, 1)
+	relA := l.Track("alpha", "m")
+	relB := l.Track("alpha", "m") // in flight 2, parallel 1
+
+	got := make(chan func(), 1)
+	go func() {
+		rel, _, err := l.Acquire(context.Background(), "alpha", "m")
+		if err != nil {
+			t.Error(err)
+			close(got)
+			return
+		}
+		got <- rel
+	}()
+	waitUntil(t, func() bool { return l.Queued("alpha", "m") == 1 })
+
+	relA() // in flight 1 == parallel: still no free slot
+	select {
+	case <-got:
+		t.Fatal("waiter got a slot while in flight was still at parallel")
+	case <-time.After(100 * time.Millisecond):
+	}
+	if n := l.InFlight("alpha", "m"); n != 1 {
+		t.Fatalf("in flight = %d after one release, want 1", n)
+	}
+
+	relB() // now the slot is free: hand it to the waiter
+	select {
+	case rel := <-got:
+		if rel == nil {
+			t.Fatal("waiter failed")
+		}
+		if n := l.InFlight("alpha", "m"); n != 1 {
+			t.Errorf("in flight = %d with the waiter running, want 1", n)
+		}
+		rel()
+	case <-time.After(2 * time.Second):
+		t.Fatal("waiter never got the freed slot")
+	}
+	if n := l.InFlight("alpha", "m"); n != 0 {
+		t.Errorf("in flight at the end = %d, want 0", n)
+	}
+}

docs/plans/v2.3/_files/internal/proxy/affinity_test.go

@@ -0,0 +1,180 @@
+package proxy_test
+
+// v2.3 task 02: affinity = "route" puts every request on the route (every conversation, every
+// control call) on one lease, so one host; queue = false counts the route's requests on the host
+// without ever holding or refusing them, because the client pins its own llama-server slot and
+// the server's queue is the one that must show it.
+
+import (
+	"bufio"
+	"net/http"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+const affinityHosts = `
+listen = "127.0.0.1:1"
+queue_max = 0
+lease_idle = "30m"
+[hosts.alpha]
+base_url = %q
+weight = 1.0
+models = { "shared" = { parallel = 1 } }
+[hosts.beta]
+base_url = %q
+weight = 1.0
+models = { "shared" = { parallel = 1 } }
+[routes.r]
+hosts = ["alpha", "beta"]
+default_model = "shared"
+[routes.bm]
+hosts = ["alpha", "beta"]
+default_model = "shared"
+affinity = "route"
+queue = false
+[routes."agent-*"]
+hosts = ["alpha", "beta"]
+default_model = "shared"
+affinity = "route"
+`
+
+func TestRouteAffinityPutsEverythingOnOneHost(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, affinityHosts, alpha, beta)
+
+	seen := map[string]int{}
+	note := func(what string, resp *http.Response) {
+		body := drain(resp)
+		if resp.StatusCode != 200 {
+			t.Fatalf("%s: %d %s", what, resp.StatusCode, body)
+		}
+		seen[resp.Header.Get("X-Crossbar-Host")]++
+	}
+	// Different conversations (different fingerprints), then control calls without any.
+	for id := 1; id <= 4; id++ {
+		note("chat", r.do(http.MethodPost, "/bm/v1/chat/completions", conversation(id, 1)))
+	}
+	note("slots", r.do(http.MethodGet, "/bm/slots?model=shared", ""))
+	note("props", r.do(http.MethodGet, "/bm/props?model=shared", ""))
+	note("control", r.do(http.MethodPost, "/bm/v1/chat/completions/control", `{"id":"chatcmpl-1","action":"reasoning_end","model":"shared"}`))
+	if len(seen) != 1 {
+		t.Fatalf("route-affinity requests spread over %v, want one host", seen)
+	}
+
+	// Templated concrete routes each get their own route lease, and each is internally sticky.
+	for _, route := range []string{"agent-a", "agent-b", "agent-c"} {
+		hosts := map[string]bool{}
+		for id := 1; id <= 3; id++ {
+			resp := r.do(http.MethodPost, "/"+route+"/v1/chat/completions", conversation(id, 1))
+			drain(resp)
+			hosts[resp.Header.Get("X-Crossbar-Host")] = true
+		}
+		if len(hosts) != 1 {
+			t.Errorf("%s spread over %v, want one host", route, hosts)
+		}
+	}
+}
+
+func TestQueueFalseNeitherHoldsNorRefuses(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	alpha.delay, beta.delay = 400*time.Millisecond, 400*time.Millisecond
+	r := newRig(t, affinityHosts, alpha, beta)
+
+	// parallel = 1 and queue_max = 0: a queueing route would refuse the second and third.
+	var wg sync.WaitGroup
+	codes := make(chan int, 3)
+	start := time.Now()
+	for id := 1; id <= 3; id++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			resp := r.do(http.MethodPost, "/bm/v1/chat/completions", conversation(id, 1))
+			drain(resp)
+			codes <- resp.StatusCode
+		}(id)
+	}
+	// While they run, the host carries all three and a queueing route sees it full.
+	var host string
+	waitUntil(t, func() bool {
+		for _, h := range []string{"alpha", "beta"} {
+			if r.lim.InFlight(h, "shared") == 3 {
+				host = h
+				return true
+			}
+		}
+		return false
+	})
+	if n := r.lim.FreeSlots(host); n != 0 {
+		t.Errorf("free slots on %s = %d while bm runs three, want 0", host, n)
+	}
+	wg.Wait()
+	close(codes)
+	for c := range codes {
+		if c != 200 {
+			t.Errorf("queue = false request: %d, want 200", c)
+		}
+	}
+	// Concurrent, not serialised behind one slot: three 400 ms answers well under 1.2 s.
+	if d := time.Since(start); d > 1100*time.Millisecond {
+		t.Errorf("three queue = false requests took %v; they were held", d)
+	}
+	// The slot is given back just after the answer is sent (a deferred release), so wait for it.
+	waitUntil(t, func() bool { return r.lim.InFlight(host, "shared") == 0 })
+	// Accounting is unchanged: each chat is still a row.
+	waitUntil(t, func() bool { return r.rows("bm") == 3 })
+}
+
+// The default is unchanged: two conversations on a conversation-affinity route may land on
+// different hosts (they start where there is most room).
+func TestConversationAffinityStillSpreads(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	alpha.delay, beta.delay = 300*time.Millisecond, 300*time.Millisecond
+	r := newRig(t, affinityHosts, alpha, beta)
+	var wg sync.WaitGroup
+	var mu sync.Mutex
+	hosts := map[string]bool{}
+	for id := 1; id <= 2; id++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			resp := r.do(http.MethodPost, "/r/v1/chat/completions", conversation(id, 1))
+			drain(resp)
+			mu.Lock()
+			hosts[resp.Header.Get("X-Crossbar-Host")] = true
+			mu.Unlock()
+		}(id)
+		time.Sleep(50 * time.Millisecond) // let the first take its slot so the second sees one host full
+	}
+	wg.Wait()
+	if len(hosts) != 2 {
+		t.Errorf("two concurrent conversations on route r used %v, want both hosts", hosts)
+	}
+}
+
+// A request counts against its host for as long as its answer is streaming, not only until the
+// first byte: a slot (queueing route) or a tracked place (queue = false) is given back when the
+// stream ends.
+func TestLoadIsHeldForTheWholeStream(t *testing.T) {
+	for _, route := range []string{"r", "bm"} {
+		t.Run(route, func(t *testing.T) {
+			alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+			r := newRig(t, affinityHosts, alpha, beta)
+			body := strings.Replace(conversation(1, 1), `"stream":false`, `"stream":true`, 1)
+			resp := r.do(http.MethodPost, "/"+route+"/v1/chat/completions", body)
+			defer resp.Body.Close()
+			host := resp.Header.Get("X-Crossbar-Host")
+			line, err := bufio.NewReader(resp.Body).ReadString('\n')
+			if err != nil || !strings.HasPrefix(line, "data:") {
+				t.Fatalf("first line %q, err %v", line, err)
+			}
+			// The first chunk is here; the upstream sends more for another ~30 ms.
+			if n := r.lim.InFlight(host, "shared"); n != 1 {
+				t.Errorf("in flight on %s after the first chunk = %d, want 1 (released before the stream ended)", host, n)
+			}
+			drain(resp)
+			waitUntil(t, func() bool { return r.lim.InFlight(host, "shared") == 0 })
+		})
+	}
+}

docs/plans/v2.3/_files/internal/proxy/control_test.go

@@ -0,0 +1,176 @@
+package proxy_test
+
+// v2.3 task 01: control-plane requests. A client that manages its own slots (Boxmaker) polls
+// /slots, reads /props, tokenizes and steers a running completion through
+// /v1/chat/completions/control. Those calls follow the route's lease like any other request but
+// must never wait for, or take, a slot: /control is sent while the client's own stream holds one.
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+)
+
+// controlClient gives every control call a short deadline: a call that queues behind a full host
+// is the bug, and it must fail the test rather than hang it.
+var controlClient = &http.Client{Timeout: 2 * time.Second}
+
+func (r *rig) do(method, path, body string) *http.Response {
+	r.t.Helper()
+	var rd *strings.Reader
+	if body != "" {
+		rd = strings.NewReader(body)
+	}
+	var req *http.Request
+	var err error
+	if rd != nil {
+		req, err = http.NewRequest(method, r.front.URL+path, rd)
+		req.Header.Set("Content-Type", "application/json")
+	} else {
+		req, err = http.NewRequest(method, r.front.URL+path, nil)
+	}
+	if err != nil {
+		r.t.Fatal(err)
+	}
+	resp, err := controlClient.Do(req)
+	if err != nil {
+		r.t.Fatalf("%s %s: %v", method, path, err)
+	}
+	return resp
+}
+
+func (r *rig) rows(route string) int64 {
+	r.t.Helper()
+	counts, err := r.store.StatusCounts(time.Time{})
+	if err != nil {
+		r.t.Fatal(err)
+	}
+	var n int64
+	for _, c := range counts {
+		if c.Route == route {
+			n += c.Count
+		}
+	}
+	return n
+}
+
+// A GET names its model in the query string: /slots?model=alpha-only must reach the host that
+// has alpha-only loaded, not whichever host the route's default model would pick.
+func TestGetModelComesFromTheQuery(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+
+	resp := r.do(http.MethodGet, "/r/slots?model=alpha-only", "")
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get("X-Crossbar-Host") != "alpha" {
+		t.Fatalf("GET /r/slots?model=alpha-only: %d on %q, want 200 on alpha", resp.StatusCode, resp.Header.Get("X-Crossbar-Host"))
+	}
+	if got := alpha.lastReq(); got.method != "GET" || got.path != "/slots?model=alpha-only" {
+		t.Errorf("alpha saw %s %s, want GET /slots?model=alpha-only", got.method, got.path)
+	}
+	// The same for beta-only, so a lucky default cannot pass the test.
+	resp = r.do(http.MethodGet, "/r/slots?model=beta-only", "")
+	drain(resp)
+	if resp.Header.Get("X-Crossbar-Host") != "beta" {
+		t.Errorf("GET /r/slots?model=beta-only went to %q, want beta", resp.Header.Get("X-Crossbar-Host"))
+	}
+}
+
+// /slots and /tokenize are proxied; the per-slot actions under /slots/ (save, restore, erase)
+// are not.
+func TestControlPathsAllowed(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	for _, tc := range []struct {
+		method, path, body string
+		want               int
+	}{
+		{http.MethodGet, "/r/slots", "", 200},
+		{http.MethodGet, "/r/slots?model=shared", "", 200},
+		{http.MethodPost, "/r/tokenize", `{"model":"shared","content":"hello"}`, 200},
+		{http.MethodPost, "/r/v1/chat/completions/control", `{"id":"chatcmpl-1","action":"reasoning_end","model":"shared"}`, 200},
+		{http.MethodGet, "/r/slots/0", "", 404},
+		{http.MethodPost, "/r/slots/0?action=erase", "", 404},
+		{http.MethodPost, "/r/slots/0?action=save", `{"filename":"x"}`, 404},
+	} {
+		resp := r.do(tc.method, tc.path, tc.body)
+		body := drain(resp)
+		if resp.StatusCode != tc.want {
+			t.Errorf("%s %s: %d %s, want %d", tc.method, tc.path, resp.StatusCode, body, tc.want)
+		}
+	}
+}
+
+// With every slot on both hosts taken and the queue full, control-plane calls still go straight
+// through: no 503, no wait, no slot taken, no accounting row.
+func TestControlRequestsNeverTakeASlot(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+
+	// Take every "shared" slot (parallel 2 on each host) and the one queue place per host.
+	var releases []func()
+	for _, host := range []string{"alpha", "beta"} {
+		for i := 0; i < 2; i++ {
+			rel, _, err := r.lim.Acquire(context.Background(), host, "shared")
+			if err != nil {
+				t.Fatal(err)
+			}
+			releases = append(releases, rel)
+		}
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+		go func() { _, _, _ = r.lim.Acquire(ctx, host, "shared") }()
+		waitUntil(t, func() bool { return r.lim.Queued(host, "shared") == 1 })
+	}
+	defer func() {
+		for _, rel := range releases {
+			rel()
+		}
+	}()
+
+	for _, tc := range []struct{ method, path, body string }{
+		{http.MethodGet, "/r/slots?model=shared", ""},
+		{http.MethodGet, "/r/props?model=shared", ""},
+		{http.MethodHead, "/r/props?model=shared", ""},
+		{http.MethodGet, "/r/v1/models", ""},
+		{http.MethodPost, "/r/tokenize", `{"model":"shared","content":"hello"}`},
+		{http.MethodPost, "/r/v1/chat/completions/control", `{"id":"chatcmpl-1","action":"reasoning_end","model":"shared"}`},
+	} {
+		resp := r.do(tc.method, tc.path, tc.body)
+		body := drain(resp)
+		if resp.StatusCode != 200 {
+			t.Errorf("%s %s with the host full: %d %s, want 200", tc.method, tc.path, resp.StatusCode, body)
+		}
+	}
+	for _, host := range []string{"alpha", "beta"} {
+		if n := r.lim.InFlight(host, "shared"); n != 2 {
+			t.Errorf("%s in flight = %d after control calls, want 2 (control takes no slot)", host, n)
+		}
+	}
+	time.Sleep(100 * time.Millisecond) // a row is written after the answer; give a stray one time to land
+	if n := r.rows("r"); n != 0 {
+		t.Errorf("control calls wrote %d accounting rows, want 0", n)
+	}
+
+	// A chat completion on the same full route still queues or is refused as before: the bypass
+	// is for control calls only.
+	resp := r.do(http.MethodPost, "/r/v1/chat/completions", conversation(1, 1))
+	drain(resp)
+	if resp.StatusCode != http.StatusServiceUnavailable {
+		t.Errorf("chat on a full route: %d, want 503 (queue full)", resp.StatusCode)
+	}
+}
+
+// A chat completion is not a control call just because its path starts the same way.
+func TestChatIsNotControl(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, twoHosts, alpha, beta)
+	resp := r.do(http.MethodPost, "/r/v1/chat/completions", conversation(1, 1))
+	drain(resp)
+	if resp.StatusCode != 200 {
+		t.Fatalf("chat: %d", resp.StatusCode)
+	}
+	waitUntil(t, func() bool { return r.rows("r") == 1 }) // the row lands just after the answer
+}

docs/plans/v2.3/_files/internal/proxy/ctxguard_router_test.go

@@ -0,0 +1,110 @@
+package proxy_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+)
+
+// routerUpstream is a fake shaped like llama-server's router mode: the plain /props carries no
+// context (role router, n_ctx 0), /v1/models lists models with a status, and /props?model=X
+// answers for one loaded model. The guard must work from the per-model figures.
+func routerUpstream(t *testing.T, name string, models map[string][2]int, unloaded ...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) {
+		fmt.Fprint(w, `{"object":"list","data":[`)
+		first := true
+		for id := range models {
+			if !first {
+				fmt.Fprint(w, ",")
+			}
+			first = false
+			fmt.Fprintf(w, `{"id":%q,"status":{"value":"loaded"}}`, id)
+		}
+		for _, id := range unloaded {
+			fmt.Fprintf(w, `,{"id":%q,"status":{"value":"unloaded"}}`, id)
+		}
+		fmt.Fprint(w, `]}`)
+	})
+	mux.HandleFunc("/props", func(w http.ResponseWriter, r *http.Request) {
+		model := r.URL.Query().Get("model")
+		if model == "" {
+			fmt.Fprint(w, `{"role":"router","default_generation_settings":{"n_ctx":0}}`)
+			return
+		}
+		m, ok := models[model]
+		if !ok {
+			w.WriteHeader(http.StatusInternalServerError)
+			fmt.Fprint(w, `{"error":"asked for a model that is not loaded"}`)
+			return
+		}
+		fmt.Fprintf(w, `{"default_generation_settings":{"n_ctx":%d},"total_slots":%d}`, m[0], m[1])
+	})
+	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
+}
+
+// On routers the guard reads the per-model per-slot context: `small` serves "shared" from a
+// 8192-context child with two slots (4096 per slot), `big` from a 131072-context child with one.
+// The plain /props of both says nothing, so a v2 guard that only knew host-level figures would
+// stay inert and let the oversized prompt overflow `small`.
+func TestRouterGuardUsesPerModelContext(t *testing.T) {
+	small := routerUpstream(t, "small", map[string][2]int{"shared": {8192, 2}})
+	big := routerUpstream(t, "big", map[string][2]int{"shared": {131072, 1}})
+	r := newRig(t, ctxHosts, small, big)
+
+	resp := r.post("/r/v1/chat/completions", bodyOfTokens(100))
+	drain(resp)
+	if got := resp.Header.Get(proxy.HostHeader); got != "small" {
+		t.Fatalf("small prompt went to %q, want small (weight 10)", got)
+	}
+	resp = r.post("/r/v1/chat/completions", bodyOfTokens(6000))
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.HostHeader) != "big" {
+		t.Fatalf("6000-token prompt: status %d host %q, want 200 on big", resp.StatusCode, resp.Header.Get(proxy.HostHeader))
+	}
+	if got := resp.Header.Get("X-Crossbar-Ctx"); got != "moved:small>big" {
+		t.Errorf("X-Crossbar-Ctx = %q, want moved:small>big", got)
+	}
+}
+
+// A model the router lists as unloaded is not resident there: the guard must not move a prompt
+// to that host, and the refusal names the largest per-slot context among hosts that do serve it.
+func TestRouterUnloadedModelIsNotACandidate(t *testing.T) {
+	small := routerUpstream(t, "small", map[string][2]int{"shared": {8192, 2}})
+	big := routerUpstream(t, "big", map[string][2]int{"other": {131072, 1}}, "shared") // shared unloaded on big
+	r := newRig(t, ctxHosts, small, big)
+
+	resp := r.post("/r/v1/chat/completions", bodyOfTokens(6000))
+	body := drain(resp)
+	if resp.StatusCode != 400 {
+		t.Fatalf("status %d body %s, want 400: shared is loaded only on small, where it does not fit", resp.StatusCode, body)
+	}
+	if big.hits.Load() != 0 {
+		t.Errorf("big served %d requests for a model it does not have loaded", big.hits.Load())
+	}
+	// v2.3: the refusal is llama-server's exceed_context_size_error shape; n_ctx is what "max" was.
+	var e struct {
+		Error struct {
+			NCtx float64 `json:"n_ctx"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal([]byte(body), &e); err != nil {
+		t.Fatalf("body %q is not JSON: %v", body, err)
+	}
+	if e.Error.NCtx != 4096 {
+		t.Errorf("error.n_ctx = %v, want 4096: the largest per-slot context among hosts that have shared loaded", e.Error.NCtx)
+	}
+}

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

@@ -0,0 +1,164 @@
+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)
+	}
+	// v2.3: llama-server's own shape for this error, so a client handles crossbar's refusal the
+	// way it handles the server's (Boxmaker keys on error.type; the error JSON must come first).
+	if !strings.HasPrefix(body, `{"error":`) {
+		t.Errorf("body must start with the error object: %s", body)
+	}
+	var e struct {
+		Error struct {
+			Code          int     `json:"code"`
+			Type          string  `json:"type"`
+			Message       string  `json:"message"`
+			NPromptTokens float64 `json:"n_prompt_tokens"`
+			NCtx          float64 `json:"n_ctx"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal([]byte(body), &e); err != nil || e.Error.Code != 400 || e.Error.Type != "exceed_context_size_error" || e.Error.Message != "prompt too large" {
+		t.Fatalf("body = %s, want {\"error\":{\"code\":400,\"type\":\"exceed_context_size_error\",\"message\":\"prompt too large\",…}}", body)
+	}
+	if est := e.Error.NPromptTokens; est < 8000 || est > 13000 {
+		t.Errorf("n_prompt_tokens = %v, want roughly 10000 tokens", est)
+	}
+	if max := e.Error.NCtx; max != 4096 {
+		t.Errorf("n_ctx = %v, want the largest per-slot context among the route's hosts (4096)", max)
+	}
+	if ct := resp.Header.Get("Content-Type"); !strings.HasPrefix(ct, "application/json") {
+		t.Errorf("Content-Type = %q, want application/json", ct)
+	}
+	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))
+	}
+}
+
+// grow appends later turns to a conversation body without touching its system prompt or first
+// user message, so the fingerprint — and therefore the lease — stays the same.
+func grow(body string, words int) string {
+	turn := `,{"role":"assistant","content":"ok"},{"role":"user","content":"` + strings.Repeat("x ", words) + `"}`
+	return strings.Replace(body, `]}`, turn+`]}`, 1)
+}
+
+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, a later turn well under 4096 tokens: stays.
+	resp = r.post("/r/v1/chat/completions", grow(body, 500))
+	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 visible in the header.
+	huge := grow(body, 30000)
+	resp = r.post("/r/v1/chat/completions", huge)
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.HostHeader) != "big" || !strings.HasPrefix(resp.Header.Get(proxy.CtxHeader), "moved") {
+		t.Fatalf("outgrown turn: %d %q ctx=%q, want 200 from big with a moved header", resp.StatusCode, resp.Header.Get(proxy.HostHeader), resp.Header.Get(proxy.CtxHeader))
+	}
+	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.3/_files/internal/proxy/listener_test.go

@@ -0,0 +1,112 @@
+package proxy_test
+
+// v2.3 task 03: Handler.ForRoute serves one route with unprefixed paths, for a route's dedicated
+// listener.
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/proxy"
+)
+
+// dedicated serves r's route on its own test server, sharing r's health, leases, limiter and
+// store, as main does for a route with listen set.
+func dedicated(t *testing.T, r *rig, route string) *httptest.Server {
+	p := proxy.New(r.cfg, r.health, r.leases, r.lim, r.store, nil)
+	srv := httptest.NewServer(p.ForRoute(route))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func call(t *testing.T, method, url, body string, hdr ...string) (*http.Response, string) {
+	t.Helper()
+	var req *http.Request
+	if body != "" {
+		req, _ = http.NewRequest(method, url, strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+	} else {
+		req, _ = http.NewRequest(method, url, nil)
+	}
+	for i := 0; i+1 < len(hdr); i += 2 {
+		req.Header.Set(hdr[i], hdr[i+1])
+	}
+	resp, err := controlClient.Do(req)
+	if err != nil {
+		t.Fatalf("%s %s: %v", method, url, err)
+	}
+	return resp, drain(resp)
+}
+
+func TestForRouteServesUnprefixedPaths(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, affinityHosts, alpha, beta)
+	srv := dedicated(t, r, "bm")
+
+	resp, body := call(t, http.MethodPost, srv.URL+"/v1/chat/completions", conversation(1, 1))
+	if resp.StatusCode != 200 {
+		t.Fatalf("chat on the dedicated listener: %d %s", resp.StatusCode, body)
+	}
+	host := resp.Header.Get("X-Crossbar-Host")
+	up := map[string]*upstream{"alpha": alpha, "beta": beta}[host]
+	if up == nil || up.lastReq().path != "/v1/chat/completions" {
+		t.Fatalf("upstream %q saw %+v, want /v1/chat/completions unchanged", host, up.lastReq())
+	}
+	resp, _ = call(t, http.MethodGet, srv.URL+"/slots?model=shared", "")
+	if resp.StatusCode != 200 || resp.Header.Get("X-Crossbar-Host") != host || up.lastReq().path != "/slots?model=shared" {
+		t.Errorf("/slots: %d on %q (last %+v), want 200 on %q", resp.StatusCode, resp.Header.Get("X-Crossbar-Host"), up.lastReq(), host)
+	}
+	resp, _ = call(t, http.MethodPost, srv.URL+"/v1/chat/completions/control", `{"id":"chatcmpl-1","action":"reasoning_end","model":"shared"}`)
+	if resp.StatusCode != 200 || resp.Header.Get("X-Crossbar-Host") != host {
+		t.Errorf("/control: %d on %q, want 200 on %q", resp.StatusCode, resp.Header.Get("X-Crossbar-Host"), host)
+	}
+	// The chat is accounted to the route the listener serves.
+	waitUntil(t, func() bool { return r.rows("bm") == 1 })
+	// The same route through the main listener shares the lease: same host.
+	resp = r.do(http.MethodPost, "/bm/v1/chat/completions", conversation(2, 1))
+	drain(resp)
+	if resp.Header.Get("X-Crossbar-Host") != host {
+		t.Errorf("main listener /bm went to %q, dedicated to %q; one route, one lease", resp.Header.Get("X-Crossbar-Host"), host)
+	}
+}
+
+func TestForRouteRefusals(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, affinityHosts, alpha, beta)
+	srv := dedicated(t, r, "bm")
+	for _, tc := range []struct {
+		name, method, path string
+		hdr                []string
+		want               int
+		msg                string
+	}{
+		{"a prefixed path is not stripped", http.MethodGet, "/bm/v1/models", nil, 404, "not found"},
+		{"no admin here", http.MethodGet, "/_crossbar/hosts", nil, 404, "not found"},
+		{"root", http.MethodGet, "/", nil, 404, "not found"},
+		{"header naming another route", http.MethodGet, "/v1/models", []string{"X-Crossbar-Route", "r"}, 400, "conflicting route"},
+	} {
+		resp, body := call(t, tc.method, srv.URL+tc.path, "", tc.hdr...)
+		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.name, resp.StatusCode, body, tc.want, tc.msg)
+		}
+	}
+	// A header naming this same route is harmless.
+	resp, body := call(t, http.MethodGet, srv.URL+"/v1/models", "", "X-Crossbar-Route", "bm")
+	if resp.StatusCode != 200 {
+		t.Errorf("header naming the listener's own route: %d %s, want 200", resp.StatusCode, body)
+	}
+}
+
+func TestForRouteUnknownRoute(t *testing.T) {
+	alpha, beta := newUpstream(t, "alpha"), newUpstream(t, "beta")
+	r := newRig(t, affinityHosts, alpha, beta)
+	srv := dedicated(t, r, "nope")
+	resp, body := call(t, http.MethodGet, srv.URL+"/v1/models", "")
+	if resp.StatusCode != 404 || !strings.Contains(body, "unknown route") {
+		t.Errorf("ForRoute(unknown): %d %s, want 404 unknown route", resp.StatusCode, body)
+	}
+}

docs/plans/v2.3/_files/internal/proxy/proxy_test.go

@@ -0,0 +1,292 @@
+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)
+		// arrive one after the other so both pick beta (10 > 2): wait until beta holds i slots
+		waitUntil(t, func() bool { return r.lim.InFlight("beta", "shared") == i })
+	}
+	// …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())
+	}
+}
+
+// waitUntil polls cond every 5 ms for up to two seconds and fails the test if it never holds.
+func waitUntil(t *testing.T, cond func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if cond() {
+			return
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	t.Fatal("condition not reached within two seconds")
+}
+
+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)
+	fire := func(i int) {
+		go func() {
+			resp := r.post("/r/v1/chat/completions", conversation(i, 1))
+			drain(resp)
+			codes <- resp.StatusCode
+		}()
+	}
+	// Arrival order is enforced by watching the limiter, not by sleeping: 1 runs, 2 queues,
+	// 3 finds the queue full.
+	fire(1)
+	waitUntil(t, func() bool { return r.lim.InFlight("alpha", "shared") == 1 })
+	fire(2)
+	waitUntil(t, func() bool { return r.lim.Queued("alpha", "shared") == 1 })
+	fire(3)
+	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"},
+		// v2.3: /slots itself is proxied (a control-plane path); its per-slot actions are not.
+		{http.MethodGet, "/r/slots/0", 404, "not found"},
+		{http.MethodGet, "/r/metrics", 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/v2.3/_files/tools/smoke.sh

@@ -0,0 +1,71 @@
+#!/bin/sh
+# Smoke run (v2.3): everything v1 checked, plus the context guard, wake-on-LAN, identity gating and
+# a route's dedicated listener.
+# 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
+#    (the body goes through a file: a 300 KB string cannot be a single argv element on Linux)
+{ printf '{"model":"ornith-1.5-35b-a3b","messages":[{"role":"user","content":"'; head -c 300000 /dev/zero | tr '\0' 'x'; printf '"}]}'; } > "$tmp/toolarge-req.json"
+h=$(curl -s -o "$tmp/toolarge.json" -w '%{http_code}' -X POST -H 'Content-Type: application/json' -d @"$tmp/toolarge-req.json" "$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"
+# 6. v2.3: boxmaker-a has its own listener. Paths are unprefixed, the chat and a control call land
+#    on the same host (affinity = "route"), and the admin API is not served there.
+lb=http://127.0.0.1:17801
+h1=$(hdrs -X POST -H 'Content-Type: application/json' -d "$(conv C)" "$lb/v1/chat/completions")
+h2=$(hdrs "$lb/props?model=ornith-1.5-35b-a3b")
+case "$h1" in 200*) ;; *) fail "chat on the dedicated listener should be 200, got '$h1'";; esac
+[ "$(echo "$h1" | cut -d' ' -f2)" = "$(echo "$h2" | cut -d' ' -f2)" ] || fail "chat went to '$h1', /props to '$h2': one route, one host"
+h=$(curl -s -o /dev/null -w '%{http_code}' "$lb/_crossbar/hosts"); [ "$h" = "404" ] || fail "admin must not be served on a dedicated listener, got $h"
+h=$(curl -s -o /dev/null -w '%{http_code}' "$lb/boxmaker-a/v1/models"); [ "$h" = "404" ] || fail "a prefixed path on the dedicated listener should be 404, got $h"
+
+echo "smoke: ok (stream spread $((lastms - firstms)) ms)"

docs/plans/v2/01-props.md

@@ -0,0 +1,66 @@
+# 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`
+- Copy (**replaces** v1's): `internal/proxy/helpers_test.go` — the fake upstream now answers `/props` without counting it as a hit, so the v1 proxy tests' exact hit counts still hold once the poller asks for it
+- 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/`;
+  `cp docs/plans/v2/_files/internal/proxy/helpers_test.go internal/proxy/`.
+- [ ] **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 internal/proxy/helpers_test.go 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,98 @@
+# 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.
+
+## Changes during the run
+
+- 2026-09-25, task 01: the new `/props` poll lands on the v1 fake upstream's `/` catch-all, which
+  counts hits, so two v1 proxy tests with exact hit counts failed. Ornith implemented the task
+  correctly, did not touch the protected file, and stopped with a `stopped` row — exactly the
+  procedure. Owner's fault (T19 once more: a new task changed what an earlier given file
+  measures, and the pre-handover walk missed it). `helpers_test.go` is now a v2 given file that
+  answers `/props` without counting it; resumed.
+- 2026-09-25, task 02: my `TestStickyLeaseSurvivesGrowthUntilItDoesNotFit` "grew" the conversation
+  by enlarging the *first user message*, which by the fingerprint spec makes it a different
+  conversation — so the test demanded `reused` for a new key. Ornith diagnosed it exactly ("turn
+  2's fp differs from turn 1's, yet the test expects reuse") and the session ended on a
+  malformed tool call. Test fault (mine): later turns are now appended after the first user
+  message. Resumed from the working tree.
+- 2026-09-25, learned from titan's router (llama-server b10964) while v2 ran: in router mode a
+  plain `GET /props` answers `n_ctx: 0` (`role: router`), and `GET /props?model=X` **autoloads X**
+  when `models_autoload` is on — the same trap as `/slots?model=X`. Task 01's poller therefore
+  learns nothing on a real router and the guard stays inert there. Follow-up for v2.1: query
+  `/props?model=X` only for models `/v1/models` lists as loaded, never for others. Not a defect
+  in what the tasks asked for; a gap in what the owner knew when writing them.
+- 2026-09-25, task 05, first session: ended after 12 seconds. It misspelled the repository path
+  (`/home/kyle/src/crossar/Makefile`), the sandbox refused the out-of-repository read, and it
+  ended its turn — the sixth refusal-ending tonight, this one triggered by its own typo. Model
+  fault; no change to the task. Restarted.
+- 2026-09-25, task 05, second session (30 min in, wiring written, smoke check 3 failing): the given
+  `tools/smoke.sh` passed a 300 KB prompt as one `curl -d` argument, which Linux caps at 128 KiB
+  per argv element, so check 3 could never pass. Test fault (mine): the body now goes through a
+  file (`-d @file`). Ornith diagnosed it correctly. Resumed from the working tree with the
+  corrected script.
+- 2026-09-25, task 05, third session: `TestParallelAndQueue` (v1 given `limiter_test.go`) failed
+  once under full-suite `-race` load with `after releases: inflight 1 queued 0`. Test fault
+  (mine): the third acquirer sent its result before its deferred release ran, so the final
+  count check could observe one slot still held. The given file now releases before reporting.
+  Ornith found it and measured the flake rate rather than editing the protected file.
+- 2026-09-25, task 05, third session: also saw `TestQueueFullIs503` fail with
+  `Requests:3 Errors:2`. Two causes. (1) Test fault (mine): arrival order rested on 30 ms
+  sleeps; the given test now waits on the limiter's in-flight and queued counts. (2) A real v1
+  defect, verified by the owner with a diagnostic build (5 of 8 runs): after a forward completes,
+  `forward.go` checks `r.Context().Err()` and, when the client has already closed its connection,
+  records a served 200 as a 499 "client cancelled" error. Cancellation must be what the reverse
+  proxy itself observed, never a post-hoc context check. Scheduled as v2.1 task 01; not fixed in
+  task 05, which is wiring only. The session then ended on a refused read of `/proc/loadavg` —
+  the seventh refusal-ending. Model 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,148 @@
+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))
+	}
+}
+
+// grow appends later turns to a conversation body without touching its system prompt or first
+// user message, so the fingerprint — and therefore the lease — stays the same.
+func grow(body string, words int) string {
+	turn := `,{"role":"assistant","content":"ok"},{"role":"user","content":"` + strings.Repeat("x ", words) + `"}`
+	return strings.Replace(body, `]}`, turn+`]}`, 1)
+}
+
+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, a later turn well under 4096 tokens: stays.
+	resp = r.post("/r/v1/chat/completions", grow(body, 500))
+	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 visible in the header.
+	huge := grow(body, 30000)
+	resp = r.post("/r/v1/chat/completions", huge)
+	drain(resp)
+	if resp.StatusCode != 200 || resp.Header.Get(proxy.HostHeader) != "big" || !strings.HasPrefix(resp.Header.Get(proxy.CtxHeader), "moved") {
+		t.Fatalf("outgrown turn: %d %q ctx=%q, want 200 from big with a moved header", resp.StatusCode, resp.Header.Get(proxy.HostHeader), resp.Header.Get(proxy.CtxHeader))
+	}
+	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/proxy/helpers_test.go

@@ -0,0 +1,216 @@
+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"}]}`)
+	})
+	// The v2 poller also asks /props; it is a health request, not a hit, so it is not counted.
+	// No n_ctx here: "unknown context" is what the v1 tests and TestUnknownContextNeverBlocks want.
+	mux.HandleFunc("/props", func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, `{"model_path":"`+name+`"}`)
+	})
+	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/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,60 @@
+#!/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
+#    (the body goes through a file: a 300 KB string cannot be a single argv element on Linux)
+{ printf '{"model":"ornith-1.5-35b-a3b","messages":[{"role":"user","content":"'; head -c 300000 /dev/zero | tr '\0' 'x'; printf '"}]}'; } > "$tmp/toolarge-req.json"
+h=$(curl -s -o "$tmp/toolarge.json" -w '%{http_code}' -X POST -H 'Content-Type: application/json' -d @"$tmp/toolarge-req.json" "$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,22 +1,43 @@
-# 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
+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 = 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 } }
+[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
+# broadcasts = ["127.0.0.1:19082", "127.0.0.1:19083"]  # v2.2: a roaming host on several networks; this or broadcast, not both, and at least one
+wait      = "20s"
 
-# 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"
 
 [routes.hermes-x]
 hosts = ["beta", "alpha"]
+# peers = ["talos"]                    # v2: with identity = "tailscale", only these tailnet nodes may use the route
+
+# v2.3: a client that manages its own llama-server slot (it pins id_slot, polls /slots, steers a
+# running completion through /v1/chat/completions/control) and cannot put a route in the path.
+# The route gets its own port; every request there is this route and the path goes upstream as is.
+[routes.boxmaker-a]
+hosts         = ["beta", "alpha"]
+default_model = "ornith-1.5-35b-a3b"
+listen        = "127.0.0.1:17801"      # a tailnet address in production; never the main listen address
+affinity      = "route"                # one lease for the whole route, not one per conversation
+queue         = false                  # counted as load but never held or refused: the server's own slot queue does that

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,86 +21,188 @@ 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"`
+	NCtx      int                        `json:"n_ctx"`  // from /props; 0 = unknown
+	Slots     int                        `json:"slots"`  // from /props; 0 = unknown
+	Models    map[string]health.ModelCtx `json:"models"` // per loaded model; empty object, never null
 }
 
+// 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{}
 	}
+	models := s.Models
+	if models == nil {
+		models = map[string]health.ModelCtx{}
+	}
 	lastOK := ""
 	if !s.LastOK.IsZero() {
 		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),
+		NCtx:      s.NCtx,
+		Slots:     s.Slots,
+		Models:    models,
 	}
 }
 
-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 {
+		// A concrete route lists under the exact key it matches, or the longest
+		// template that matches it; a template's row is every such lease.
+		if _, key, ok := hx.cfg.Route(l.Route); ok && key == 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_models_test.go

@@ -0,0 +1,46 @@
+package admin_test
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/crossbar/internal/admin"
+	"git.wntrmute.dev/kyle/crossbar/internal/health"
+)
+
+// The hosts view shows the per-model context the poller learned, and an empty object (never
+// null) for a host with nothing learned.
+func TestHostsShowsPerModelContext(t *testing.T) {
+	r := newRig(t)
+	r.hosts.st["alpha"] = health.Status{
+		Healthy: true,
+		Loaded:  []string{"m"},
+		NCtx:    0, // a router: the host-level figure stays unknown
+		Models:  map[string]health.ModelCtx{"m": {NCtx: 65536, Slots: 2}},
+	}
+	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 got := out["alpha"].Models["m"]; got != (health.ModelCtx{NCtx: 65536, Slots: 2}) {
+		t.Errorf("alpha.models[m] = %+v, want {65536 2}", got)
+	}
+	if out["alpha"].NCtx != 0 {
+		t.Errorf("alpha.n_ctx = %d, want 0 (unknown at host level on a router)", out["alpha"].NCtx)
+	}
+	var raw map[string]json.RawMessage
+	if err := json.Unmarshal(rec.Body.Bytes(), &raw); err != nil {
+		t.Fatal(err)
+	}
+	if beta := string(raw["beta"]); !strings.Contains(beta, `"models":{}`) {
+		t.Errorf("beta = %s, want \"models\":{} (never null)", beta)
+	}
+	if alpha := string(raw["alpha"]); !strings.Contains(alpha, `"models":{"m":{"n_ctx":65536,"slots":2}}`) {
+		t.Errorf("alpha = %s, want models keyed by id with n_ctx and slots", alpha)
+	}
+}

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.Route(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_template_test.go

@@ -0,0 +1,92 @@
+package admin_test
+
+import (
+	"encoding/json"
+	"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"
+)
+
+// The routes view lists a template once, under its own name, with the leases of every concrete
+// route it matched. A concrete route can be pinned; the template itself cannot.
+func TestRoutesViewAndPinWithTemplates(t *testing.T) {
+	cfg, err := config.Parse(strings.NewReader(`
+listen = "127.0.0.1:1"
+[hosts.alpha]
+base_url = "http://alpha:1"
+models = { "m" = { parallel = 2 } }
+[routes."opencode-*"]
+hosts = ["alpha"]
+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"}}},
+		draining: map[string]bool{},
+	}
+	lt, err := lease.New(st, hosts, hosts, 30*time.Minute)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := lt.Acquire(lease.Key{Route: "opencode-projecta-4242", FP: "fp1", Model: "m"}, []string{"alpha"}, time.Now()); err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := lt.Acquire(lease.Key{Route: "opencode-projectb-7", FP: "fp2", Model: "m"}, []string{"alpha"}, time.Now()); err != nil {
+		t.Fatal(err)
+	}
+	lim := limiter.New()
+	lim.Configure("alpha", "m", 2, 8)
+	r := &rig{h: admin.Handler(cfg, hosts, lt, lim, st, hosts), store: st, leases: lt, hosts: hosts}
+
+	rec := r.do(t, "GET", "/_crossbar/routes", "")
+	if rec.Code != 200 {
+		t.Fatalf("%d %s", rec.Code, rec.Body.String())
+	}
+	var out map[string]admin.RouteView
+	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	v, ok := out["opencode-*"]
+	if !ok || len(out) != 1 {
+		t.Fatalf("routes view keys = %v, want exactly the template", keysOf(out))
+	}
+	if len(v.Hosts) != 1 || v.Hosts[0] != "alpha" || v.DefaultModel != "m" || len(v.Leases) != 2 {
+		t.Errorf("template view = %+v, want hosts [alpha], model m and the two concrete routes' leases", v)
+	}
+
+	rec = r.do(t, "POST", "/_crossbar/routes/opencode-projecta-4242", `{"host":"alpha","pin":true}`)
+	if rec.Code != 200 {
+		t.Errorf("pin of a concrete templated route: %d %s, want 200", rec.Code, rec.Body.String())
+	}
+	rec = r.do(t, "POST", "/_crossbar/routes/opencode-*", `{"host":"alpha","pin":true}`)
+	if rec.Code != 404 {
+		t.Errorf("pin of the template itself: %d, want 404 unknown route", rec.Code)
+	}
+	rec = r.do(t, "POST", "/_crossbar/routes/opencode-nothing-yet", `{"host":"alpha","pin":true}`)
+	if rec.Code != 200 {
+		t.Errorf("pin of a not-yet-seen concrete route under a template: %d %s, want 200 (it is a valid route)", rec.Code, rec.Body.String())
+	}
+}
+
+func keysOf(m map[string]admin.RouteView) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}