docs: record the workstation routing numbers where the router is documented (V-485)

CLAUDE.md carried only the homesrv figures, which now read as the whole story.
Also points offload.md's order at #490 for the naming half.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NJYcaBiuny9UGSpFweQVQ1

.gitignore

@@ -9,6 +9,7 @@
 /mavwaked
 /mavmaild
 /mavupdate
+/mavgpud
 
 # Certs (private keys, don't commit)
 certs/

CLAUDE.md

@@ -143,7 +143,15 @@ seed additions, both of which now score inside the classifier baseline. Qwen3-1.
 not a doubling, and the trade is worth re-arguing rather than assuming. **The ≈2.7s figure
 that stood here until 2026-08-02 was contention, not the model.** See `docs/evals/2026-07-31-routing.md` line 61, which measures the LLM router at
 p50 825ms / p95 1.2s / max 3.0s and the full cascade at p50 0.80-1.04s. Do not plan latency
-work off the bakeoff table. `Confidence: 1.0` used to be hardcoded in `llmrouter.go`, so the LLM
+work off the bakeoff table.
+
+**The numbers above are the homesrv floor, not the ceiling.** With the workstation up, routing
+completes through `llm.Pair` against gemma-4-12b and scores **84.4% full / 93.5% intent-only at
+p50 329ms** — better than the resident model and about 2.5× faster (`docs/evals/2026-08-02-workstation-gemma4-12b.md`,
+Vikunja #485). The workstation is never assumed up, so both sets of numbers are live. Judge a
+routing change against the classifier and the resident model, since those are what always answer.
+
+`Confidence: 1.0` used to be hardcoded in `llmrouter.go`, so the LLM
 path could never ask for clarification (6/6 refusal cases missed on the fixture) — Vikunja
 #359. Fixed 31-07-2026 with structural signal (single-token utterance, keyless fact, act with
 no allowlisted fn) feeding the same stage-3 gate the classifier path already had — see

Makefile

@@ -16,11 +16,11 @@ PIPER_BIN     := $(shell pwd)/deps/piper/piper
 PIPER_MODEL   := $(shell pwd)/models/tts/ru_RU-irina-medium.onnx
 PIPER_ESPEAK  := $(shell pwd)/deps/piper/espeak-ng-data
 
-.PHONY: simulate stt-fixtures test-stt-golden all build build-stt build-tts build-daemon build-client build-waked build-web build-poll build-caldav clean test fmt-check vet run-stt run-tts run-web download-embedder deps-go eval-router eval-recall eval-phrasing eval-models
+.PHONY: simulate stt-fixtures test-stt-golden all build build-stt build-tts build-daemon build-client build-waked build-web build-poll build-caldav clean test fmt-check vet run-stt run-tts run-web download-embedder deps-go eval-router eval-recall eval-phrasing eval-models build-gpud
 
 all: build
 
-build: build-stt build-tts build-daemon build-client build-waked build-web build-poll build-caldav build-mail build-update
+build: build-stt build-tts build-daemon build-client build-waked build-web build-poll build-caldav build-mail build-update build-gpud
 
 build-stt:
 	CGO_CFLAGS="$(CGO_CFLAGS)" CGO_LDFLAGS="$(CGO_LDFLAGS)" LD_LIBRARY_PATH="$(shell pwd)/deps/lib" \
@@ -59,6 +59,12 @@ build-mail:
 build-update:
 	$(GO) build $(GOFLAGS) -o mavupdate ./cmd/mavupdate/
 
+# mavgpud runs on the workstation, not here. It is built with the rest so a
+# broken supervisor is caught by `make build` on homesrv rather than by the
+# workstation refusing to serve. Copy the binary over, do not `make deploy` it.
+build-gpud:
+	$(GO) build $(GOFLAGS) -o mavgpud ./cmd/mavgpud/
+
 run-web: build-web
 	./mavweb -addr :9200 -voice 127.0.0.1:9100
 

cmd/mavend/modelseam_test.go

@@ -0,0 +1,91 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/kami/maven/internal/config"
+	"github.com/kami/maven/internal/llm"
+)
+
+// No `workstation` block is the shipping deploy. The seam must then be the
+// resident client itself, with nothing probing anything.
+func TestModelSeamUnconfiguredIsResidentOnly(t *testing.T) {
+	resident := llm.New("http://127.0.0.1:1", time.Second)
+	hot, pair := modelSeam(&config.Config{}, resident)
+	if pair != nil {
+		t.Error("built a pair with no workstation configured")
+	}
+	if hot == nil {
+		t.Fatal("no seam at all, so the cascade would route with the classifier")
+	}
+}
+
+// A workstation with no resident model behind it has no floor, and a Pair with
+// no floor is a configuration mistake rather than a degraded mode.
+func TestModelSeamWithoutResidentIsNil(t *testing.T) {
+	cfg := &config.Config{Workstation: &config.WorkstationConfig{URL: "http://127.0.0.1:1"}}
+	cfg.Workstation.Health = strings.TrimRight(cfg.Workstation.URL, "/") + "/health"
+	hot, pair := modelSeam(cfg, nil)
+	if hot != nil || pair != nil {
+		t.Errorf("built a seam with no floor: hot=%v pair=%v", hot, pair)
+	}
+}
+
+// The configured case: the seam is the pair, and the pair notices a workstation
+// that answers /health.
+func TestModelSeamPrefersAnAnsweringWorkstation(t *testing.T) {
+	up := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer up.Close()
+
+	cfg := &config.Config{Workstation: &config.WorkstationConfig{
+		URL:   up.URL,
+		Probe: config.Duration(10 * time.Millisecond),
+	}}
+	cfg.Workstation.Health = strings.TrimRight(cfg.Workstation.URL, "/") + "/health"
+
+	hot, pair := modelSeam(cfg, llm.New("http://127.0.0.1:1", time.Second))
+	if pair == nil || hot == nil {
+		t.Fatal("no pair built for a configured workstation")
+	}
+	defer pair.Stop()
+
+	deadline := time.Now().Add(2 * time.Second)
+	for !pair.Available() && time.Now().Before(deadline) {
+		time.Sleep(5 * time.Millisecond)
+	}
+	if !pair.Available() {
+		t.Fatal("the pair never saw a workstation that answers /health")
+	}
+}
+
+// A card held by a CPT run answers 503, and that must read as unavailable
+// rather than as an error a turn has to handle.
+func TestModelSeamHeldCardIsUnavailable(t *testing.T) {
+	busy := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "model not loaded", http.StatusServiceUnavailable)
+	}))
+	defer busy.Close()
+
+	cfg := &config.Config{Workstation: &config.WorkstationConfig{
+		URL:   busy.URL,
+		Probe: config.Duration(10 * time.Millisecond),
+	}}
+	cfg.Workstation.Health = strings.TrimRight(cfg.Workstation.URL, "/") + "/health"
+
+	_, pair := modelSeam(cfg, llm.New("http://127.0.0.1:1", time.Second))
+	if pair == nil {
+		t.Fatal("no pair built for a configured workstation")
+	}
+	defer pair.Stop()
+
+	time.Sleep(50 * time.Millisecond)
+	if pair.Available() {
+		t.Error("a 503 from the supervisor read as available")
+	}
+}

cmd/mavend/voicewire.go

@@ -48,7 +48,11 @@ type voiceWiring struct {
 	// mcp — the MCP client, nil unless the `mcp` block configures an enabled
 	// server (Vikunja #251). Its tools land in the same allowlist as every
 	// other act, so nothing else here has to know about it.
-	mcp *mcpWiring
+	// pair — the workstation model with the resident one as the floor, nil
+	// unless a `workstation` block names an address. Held here only so the
+	// prober is stopped on shutdown; callers were handed it at build time.
+	pair *llm.Pair
+	mcp  *mcpWiring
 	// home — the Home Assistant client, nil unless the `smarthome` block is
 	// enabled (Vikunja #256). Its devices land in the same allowlist as every
 	// other act, so nothing else here has to know about it.
@@ -76,6 +80,9 @@ func (w *voiceWiring) close() {
 	if w.ttsClient != nil {
 		_ = w.ttsClient.Close()
 	}
+	if w.pair != nil {
+		w.pair.Stop()
+	}
 	w.mcp.close()
 }
 
@@ -188,6 +195,11 @@ func wireVoice(cfg *config.Config, coreAPI ipc.CoreAPI, phr phraser.Phraser, mem
 		// the new llama-server when the resident model is swapped (Vikunja #250).
 		llmClient = llmClientFor(lp, 60*time.Second)
 	}
+	// The workstation model sits above that one when it is configured and its
+	// card is free. hot is what the router and the replier complete through:
+	// either the pair, or the resident client alone, or nothing at all.
+	hot, pair := modelSeam(cfg, llmClient)
+	w.pair = pair
 	// ----- router (the cascade; floor examples seed the classifier) -----
 	// The act matcher's allowlist is exactly the enabled tool names — the
 	// router only matches acts the executor can run (one source of truth).
@@ -199,7 +211,7 @@ func wireVoice(cfg *config.Config, coreAPI ipc.CoreAPI, phr phraser.Phraser, mem
 	// against the classifier's 50.0%, at about 1s a turn instead of 30ms (see
 	// config.VoiceConfig.LLMRouter). The classifier always stays wired as the
 	// fallback, so a model error never breaks a turn.
-	rtr := buildRouter(emb, matcher, threshold, pickLLMRouter(cfg.Voice.UseLLMRouter(), llmClient))
+	rtr := buildRouter(emb, matcher, threshold, pickLLMRouter(cfg.Voice.UseLLMRouter(), hot))
 
 	// ----- sessions registry (shared with voicesink) -----
 	sessions := voice.NewSessions()
@@ -233,8 +245,8 @@ func wireVoice(cfg *config.Config, coreAPI ipc.CoreAPI, phr phraser.Phraser, mem
 
 	// ----- replier (LLM-backed when the engine is on, Stub floor otherwise) -----
 	replier := voice.Replier(voice.NewStubReplier())
-	if llmClient != nil {
-		replier = newLLMReplier(llmClient, contextBlockFn(cfg, time.Now))
+	if hot != nil {
+		replier = newLLMReplier(hot, contextBlockFn(cfg, time.Now))
 	}
 
 	// ----- the handler (the reactive path; closes over stt / tts / router / coreAPI / memory) -----
@@ -291,7 +303,42 @@ func wireVoice(cfg *config.Config, coreAPI ipc.CoreAPI, phr phraser.Phraser, mem
 // pickLLMRouter returns the LLM router when the operator asked for it and there
 // is a llama-server to talk to, and nil otherwise. nil is safe: the cascade then
 // routes with the classifier, so an unusable setting costs accuracy, not turns.
-func pickLLMRouter(enabled bool, c *llm.Client) *router.LLMRouter {
+// modelSeam builds the completion seam the hot paths use: routing and replies.
+//
+// With no `workstation` block it is the resident client and nothing probes
+// anything, which is today's deploy exactly. With one, it is an llm.Pair that
+// prefers the workstation and falls back to the resident model silently — the
+// silent half of the degradation rule (docs/offload.md), because the big model
+// is only better here and the 1.7B is today's shipping quality. He is never
+// told which of the two phrased his reply.
+//
+// A nil resident client means the phraser is not an LLM phraser. There is then
+// no floor, and a Pair with no floor is a configuration mistake rather than a
+// degraded mode, so the seam is nil and the cascade routes with the classifier.
+func modelSeam(cfg *config.Config, resident *llm.Client) (router.Completer, *llm.Pair) {
+	if resident == nil {
+		if cfg.Workstation != nil {
+			log.Printf("voice: a workstation is configured but there is no resident model to floor it with — ignoring the block")
+		}
+		return nil, nil
+	}
+	if cfg.Workstation == nil {
+		return resident, nil
+	}
+	ws := cfg.Workstation
+	pair := llm.NewPair(
+		llm.New(ws.URL, time.Duration(ws.Timeout)),
+		resident,
+		ws.Health,
+		time.Duration(ws.Probe),
+	)
+	pair.Start(context.Background())
+	log.Printf("voice: workstation model at %s, probed every %s, resident model as the floor",
+		ws.URL, time.Duration(ws.Probe))
+	return pair, pair
+}
+
+func pickLLMRouter(enabled bool, c router.Completer) *router.LLMRouter {
 	if !enabled {
 		return nil
 	}

cmd/mavgpud/gpu.go

@@ -0,0 +1,117 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// The card is an AMD 7900 GRE with 16GB, driven by amdgpu and ROCm. Everything
+// here reads sysfs and forks nothing: rocm-smi is not even installed on the
+// workstation, and a poll that costs a subprocess every second is a poll that
+// gets tuned down until it is useless.
+
+// gpuProc — one process holding the compute engine.
+type gpuProc struct {
+	PID  int
+	Comm string
+	VRAM int64 // bytes, as the kernel accounts them to this process
+}
+
+// probe reads the two sysfs trees the supervisor decides from.
+//
+// kfdRoot is /sys/class/kfd/kfd/proc, one directory per ROCm process. The
+// directory appears when the process initialises HIP, which is well before it
+// allocates anything large. That is the whole reason this works: the job that
+// is about to want the card announces itself while it is still starting up,
+// so we see the contender rather than only the winner of an allocation race.
+//
+// drmDev is /sys/class/drm/cardN/device, which reports total and used VRAM for
+// the card as a whole.
+type probe struct {
+	kfdRoot string
+	drmDev  string
+}
+
+// foreign lists every ROCm process that is not ours. selfPID is the supervisor's
+// llama-server child, or 0 when it is not running.
+//
+// An unreadable kfd tree returns no processes and no error. That is deliberate
+// and it is the safe direction only because startVRAM also has to agree before
+// anything launches: a supervisor that cannot see the KFD never sees free VRAM
+// either, because the CPT run holding the card shows up in the drm totals.
+func (p probe) foreign(selfPID int) []gpuProc {
+	entries, err := os.ReadDir(p.kfdRoot)
+	if err != nil {
+		return nil
+	}
+	var out []gpuProc
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil || pid == selfPID {
+			continue
+		}
+		out = append(out, gpuProc{
+			PID:  pid,
+			Comm: readComm(pid),
+			VRAM: p.procVRAM(e.Name()),
+		})
+	}
+	return out
+}
+
+// procVRAM sums the per-node vram_* files under one process directory. The
+// suffix is the KFD topology node id (vram_35881 on this card), so it is
+// globbed rather than named, and a machine with two cards sums both.
+func (p probe) procVRAM(pid string) int64 {
+	matches, err := filepath.Glob(filepath.Join(p.kfdRoot, pid, "vram_*"))
+	if err != nil {
+		return 0
+	}
+	var total int64
+	for _, m := range matches {
+		total += readInt(m)
+	}
+	return total
+}
+
+// freeVRAM reports the bytes the card has left. Used only to decide whether to
+// start: a shortfall here means llama-server would refuse to load anyway. It is
+// never used to decide to stop, because by the time free VRAM has dropped the
+// other job has already failed its allocation, which is exactly the outcome
+// yielding exists to prevent.
+func (p probe) freeVRAM() int64 {
+	total := readInt(filepath.Join(p.drmDev, "mem_info_vram_total"))
+	used := readInt(filepath.Join(p.drmDev, "mem_info_vram_used"))
+	if total <= 0 {
+		return 0
+	}
+	if free := total - used; free > 0 {
+		return free
+	}
+	return 0
+}
+
+func readInt(path string) int64 {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return 0
+	}
+	n, err := strconv.ParseInt(strings.TrimSpace(string(b)), 10, 64)
+	if err != nil {
+		return 0
+	}
+	return n
+}
+
+// readComm names the contender for the log. The log is the instrument for the
+// open question in Vikunja #488: whether a process can want this card without
+// ever registering on the KFD, which a Vulkan or video-decode job would.
+func readComm(pid int) string {
+	b, err := os.ReadFile(filepath.Join("/proc", strconv.Itoa(pid), "comm"))
+	if err != nil {
+		return "?"
+	}
+	return strings.TrimSpace(string(b))
+}

cmd/mavgpud/gpu_test.go

@@ -0,0 +1,103 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"testing"
+)
+
+// fakeKFD builds the sysfs shape the workstation actually has: one directory
+// per ROCm process, each holding a vram_<node> file. Sampled from the live box
+// on 02-08-2026, where the CPT run appeared as proc/478104/vram_35881.
+func fakeKFD(t *testing.T, vramByPID map[int]int64) string {
+	t.Helper()
+	root := t.TempDir()
+	for pid, vram := range vramByPID {
+		dir := filepath.Join(root, strconv.Itoa(pid))
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		f := filepath.Join(dir, "vram_35881")
+		if err := os.WriteFile(f, []byte(strconv.FormatInt(vram, 10)+"\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return root
+}
+
+func TestForeignExcludesOurChild(t *testing.T) {
+	root := fakeKFD(t, map[int]int64{478104: 12791693312, 999: 4096})
+	p := probe{kfdRoot: root}
+
+	all := p.foreign(0)
+	if len(all) != 2 {
+		t.Fatalf("with no child running, both processes are foreign, got %d", len(all))
+	}
+
+	ours := p.foreign(999)
+	if len(ours) != 1 || ours[0].PID != 478104 {
+		t.Fatalf("our own llama-server must not count as a contender, got %+v", ours)
+	}
+	if ours[0].VRAM != 12791693312 {
+		t.Errorf("per-process VRAM = %d, want the value from vram_35881", ours[0].VRAM)
+	}
+}
+
+// An empty KFD tree is the state that permits a start, so it must read as empty
+// rather than as an error the caller has to interpret.
+func TestForeignEmptyAndMissing(t *testing.T) {
+	if got := (probe{kfdRoot: t.TempDir()}).foreign(0); len(got) != 0 {
+		t.Errorf("empty kfd tree: got %d processes, want 0", len(got))
+	}
+	if got := (probe{kfdRoot: "/nonexistent"}).foreign(0); got != nil {
+		t.Errorf("missing kfd tree: got %+v, want nil", got)
+	}
+}
+
+func TestFreeVRAM(t *testing.T) {
+	dev := t.TempDir()
+	write := func(name, v string) {
+		if err := os.WriteFile(filepath.Join(dev, name), []byte(v), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// The live numbers from the workstation while the CPT run held the card.
+	write("mem_info_vram_total", "17163091968\n")
+	write("mem_info_vram_used", "13396389888\n")
+	p := probe{drmDev: dev}
+	if got, want := p.freeVRAM(), int64(3766702080); got != want {
+		t.Errorf("freeVRAM = %d, want %d", got, want)
+	}
+	if got := (probe{drmDev: "/nonexistent"}).freeVRAM(); got != 0 {
+		t.Errorf("unreadable card reports %d free, want 0 so nothing starts", got)
+	}
+}
+
+// With no model loaded the supervisor must still answer, and it must answer 503
+// rather than hanging or proxying into a closed port. Maven reads this endpoint
+// on a timer forever, including while the workstation is busy.
+func TestHealthAndProxyRefuseWhenNotReady(t *testing.T) {
+	s := &supervisor{run: newRunner("/bin/true", nil, "")}
+	h := s.handler(mustURL(t, "http://127.0.0.1:1"))
+
+	for _, path := range []string{"/health", "/v1/chat/completions"} {
+		w := httptest.NewRecorder()
+		h.ServeHTTP(w, httptest.NewRequest(http.MethodGet, path, nil))
+		if w.Code != http.StatusServiceUnavailable {
+			t.Errorf("%s with no model: got %d, want 503", path, w.Code)
+		}
+	}
+}
+
+func mustURL(t *testing.T, s string) *url.URL {
+	t.Helper()
+	u, err := url.Parse(s)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return u
+}

cmd/mavgpud/main.go

@@ -0,0 +1,247 @@
+// mavgpud — the workstation's GPU supervisor.
+//
+// It runs on the workstation (an AMD 7900 GRE, 16GB), not on homesrv, and it is
+// deployed separately from the Maven daemons. Maven does not participate in any
+// of this and never asks for a start: it reads /health through internal/llm.Pair
+// and either gets the big model or falls back to the resident 1.7B.
+//
+// The rule, from Vikunja #488: keep llama-server loaded whenever the card is
+// free, unload it when it has been idle too long or when another process needs
+// the card. Not on demand, because a 7-14B takes tens of seconds to load and a
+// world question would be answered by a gap every time the card had been quiet.
+// Not always on, because that holds 16GB against the owner's own jobs.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"log"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"os"
+	"os/signal"
+	"sync/atomic"
+	"syscall"
+	"time"
+)
+
+type config struct {
+	Listen    string `json:"listen"`     // what Maven talks to
+	LlamaAddr string `json:"llama_addr"` // where llama-server binds
+	LlamaBin  string `json:"llama_bin"`
+	// LlamaArgs must include the flags that bind LlamaAddr. They are passed
+	// through untouched so the model, context size and layer count stay the
+	// owner's business and not this daemon's schema.
+	LlamaArgs []string `json:"llama_args"`
+
+	KFDRoot   string `json:"kfd_root"`
+	DRMDevice string `json:"drm_device"`
+
+	Poll        duration `json:"poll"`
+	IdleTimeout duration `json:"idle_timeout"`
+	StopGrace   duration `json:"stop_grace"`
+	MinFreeVRAM int64    `json:"min_free_vram_bytes"`
+	// EvictAfter and StartAfter are counted in polls, not seconds. Both exist
+	// to damp flapping: a one-tick blip from a short-lived rocm process must
+	// not evict the model, and a card that has just been released must not be
+	// grabbed before the previous job has finished unmapping.
+	EvictAfter int `json:"evict_after_polls"`
+	StartAfter int `json:"start_after_polls"`
+}
+
+func defaults() config {
+	return config{
+		Listen:      ":8080",
+		LlamaAddr:   "127.0.0.1:8081",
+		KFDRoot:     "/sys/class/kfd/kfd/proc",
+		DRMDevice:   "/sys/class/drm/card1/device",
+		Poll:        duration(time.Second),
+		IdleTimeout: duration(15 * time.Minute),
+		StopGrace:   duration(20 * time.Second),
+		MinFreeVRAM: 15 << 30,
+		EvictAfter:  2,
+		StartAfter:  5,
+	}
+}
+
+// duration lets the config file say "15m" instead of counting nanoseconds.
+type duration time.Duration
+
+func (d *duration) UnmarshalJSON(b []byte) error {
+	var s string
+	if err := json.Unmarshal(b, &s); err != nil {
+		return err
+	}
+	v, err := time.ParseDuration(s)
+	if err != nil {
+		return err
+	}
+	*d = duration(v)
+	return nil
+}
+
+func main() {
+	path := flag.String("config", "/etc/mavgpud.json", "config file")
+	flag.Parse()
+
+	cfg := defaults()
+	b, err := os.ReadFile(*path)
+	if err != nil {
+		log.Fatalf("mavgpud: read config: %v", err)
+	}
+	if err := json.Unmarshal(b, &cfg); err != nil {
+		log.Fatalf("mavgpud: parse config: %v", err)
+	}
+	if cfg.LlamaBin == "" {
+		log.Fatal("mavgpud: llama_bin is required")
+	}
+
+	base := "http://" + cfg.LlamaAddr
+	run := newRunner(cfg.LlamaBin, cfg.LlamaArgs, base+"/health")
+	sup := &supervisor{
+		cfg:   cfg,
+		probe: probe{kfdRoot: cfg.KFDRoot, drmDev: cfg.DRMDevice},
+		run:   run,
+	}
+	sup.touch()
+
+	ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer cancel()
+
+	target, err := url.Parse(base)
+	if err != nil {
+		log.Fatalf("mavgpud: llama_addr: %v", err)
+	}
+	srv := &http.Server{Addr: cfg.Listen, Handler: sup.handler(target)}
+	go func() {
+		log.Printf("mavgpud: listening on %s, model %s", cfg.Listen, cfg.LlamaBin)
+		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			log.Fatalf("mavgpud: listen: %v", err)
+		}
+	}()
+
+	sup.loop(ctx)
+
+	// The card must come back before we do. A supervisor that exits leaving
+	// llama-server holding 14GB is worse than one that never ran.
+	shut, done := context.WithTimeout(context.Background(), 5*time.Second)
+	defer done()
+	_ = srv.Shutdown(shut)
+	run.stop(time.Duration(cfg.StopGrace))
+}
+
+type supervisor struct {
+	cfg   config
+	probe probe
+	run   *runner
+
+	lastReq atomic.Int64 // unix nanos of the last request Maven sent
+
+	foreignStreak int
+	clearStreak   int
+}
+
+func (s *supervisor) touch() { s.lastReq.Store(time.Now().UnixNano()) }
+
+func (s *supervisor) idle() time.Duration {
+	return time.Since(time.Unix(0, s.lastReq.Load()))
+}
+
+// handler serves the two things the workstation exposes.
+//
+// /health is answered locally and always, with no GPU cost and no round trip,
+// because it is the only thing Maven reads and Maven reads it on a timer
+// forever. Everything else is llama-server's API, reverse-proxied. Proxying
+// rather than pointing Maven straight at llama-server is what makes the idle
+// window measurable: the supervisor cannot otherwise know when the model was
+// last used.
+func (s *supervisor) handler(target *url.URL) http.Handler {
+	proxy := httputil.NewSingleHostReverseProxy(target)
+	mux := http.NewServeMux()
+	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
+		if !s.run.isReady() {
+			http.Error(w, "model not loaded", http.StatusServiceUnavailable)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"status":"ok"}`))
+	})
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		if !s.run.isReady() {
+			http.Error(w, "model not loaded", http.StatusServiceUnavailable)
+			return
+		}
+		s.touch()
+		proxy.ServeHTTP(w, r)
+	})
+	return mux
+}
+
+func (s *supervisor) loop(ctx context.Context) {
+	t := time.NewTicker(time.Duration(s.cfg.Poll))
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			s.tick(ctx)
+		}
+	}
+}
+
+// tick is the whole decision. Yielding is checked before starting, and presence
+// on the KFD is what triggers it — not a VRAM threshold. A ROCm process
+// registers under /sys/class/kfd/kfd/proc when it initialises HIP, before it
+// allocates, so we see a contender during its startup rather than after it has
+// already failed to get the memory it wanted.
+func (s *supervisor) tick(ctx context.Context) {
+	others := s.probe.foreign(s.run.pid())
+	if len(others) > 0 {
+		s.foreignStreak++
+		s.clearStreak = 0
+	} else {
+		s.foreignStreak = 0
+		s.clearStreak++
+	}
+
+	if s.run.running() {
+		s.run.refreshReady(ctx)
+		switch {
+		case s.foreignStreak >= s.cfg.EvictAfter:
+			log.Printf("mavgpud: yielding the card to %s", describe(others))
+			s.run.stop(time.Duration(s.cfg.StopGrace))
+		case s.idle() > time.Duration(s.cfg.IdleTimeout):
+			log.Printf("mavgpud: idle for %s, unloading", s.idle().Round(time.Second))
+			s.run.stop(time.Duration(s.cfg.StopGrace))
+		}
+		return
+	}
+
+	if s.clearStreak < s.cfg.StartAfter {
+		return
+	}
+	if free := s.probe.freeVRAM(); free < s.cfg.MinFreeVRAM {
+		return
+	}
+	s.touch() // the idle clock starts at load, not at the last request before it
+	if err := s.run.start(); err != nil {
+		log.Printf("mavgpud: start llama-server: %v", err)
+	}
+}
+
+// describe names the contenders in the log. This log is the instrument for the
+// open question in #488: whether polling the KFD misses a job that wants the
+// card without registering there.
+func describe(procs []gpuProc) string {
+	out := ""
+	for i, p := range procs {
+		if i > 0 {
+			out += ", "
+		}
+		out += p.Comm
+	}
+	return out
+}

cmd/mavgpud/runner.go

@@ -0,0 +1,132 @@
+package main
+
+import (
+	"context"
+	"log"
+	"net/http"
+	"os/exec"
+	"sync"
+	"syscall"
+	"time"
+)
+
+// runner owns one llama-server process. Owning it is the point of the daemon:
+// the workstation cannot keep a 7-14B resident, because that holds 16GB against
+// the owner's CPT runs, Correx and the manga-recap pipeline. So the thing that
+// stays up is this, which costs no VRAM, and the model comes and goes under it.
+type runner struct {
+	bin  string
+	args []string
+	// ready is llama-server's own /health, which answers "is a model loaded".
+	// Loading a 7-14B takes tens of seconds, so started is not ready.
+	readyURL string
+
+	mu    sync.Mutex
+	cmd   *exec.Cmd
+	ready bool
+	http  *http.Client
+}
+
+func newRunner(bin string, args []string, readyURL string) *runner {
+	return &runner{
+		bin: bin, args: args, readyURL: readyURL,
+		http: &http.Client{Timeout: 2 * time.Second},
+	}
+}
+
+// pid is the child's, or 0. The GPU probe needs it to tell our own model apart
+// from a contender.
+func (r *runner) pid() int {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.cmd == nil || r.cmd.Process == nil {
+		return 0
+	}
+	return r.cmd.Process.Pid
+}
+
+func (r *runner) running() bool { return r.pid() != 0 }
+
+// isReady reports the cached readiness. The supervisor loop refreshes it; the
+// health handler only reads, so answering /health never costs a round trip.
+func (r *runner) isReady() bool {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.ready
+}
+
+// start launches llama-server. It returns as soon as the process exists, not
+// when the model is loaded.
+func (r *runner) start() error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.cmd != nil {
+		return nil
+	}
+	cmd := exec.Command(r.bin, r.args...)
+	// Own process group, so stop kills anything llama-server spawned rather
+	// than leaving it holding VRAM after we have declared the card yielded.
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if err := cmd.Start(); err != nil {
+		return err
+	}
+	r.cmd, r.ready = cmd, false
+	log.Printf("mavgpud: started llama-server pid=%d", cmd.Process.Pid)
+	go func() {
+		err := cmd.Wait()
+		r.mu.Lock()
+		r.cmd, r.ready = nil, false
+		r.mu.Unlock()
+		log.Printf("mavgpud: llama-server exited: %v", err)
+	}()
+	return nil
+}
+
+// stop ends llama-server and waits for the VRAM to come back. SIGTERM first so
+// it unmaps cleanly, SIGKILL after the grace window. Returning before the
+// process is gone would let the supervisor report a free card while 14GB is
+// still mapped, which is the one lie that would make yielding useless.
+func (r *runner) stop(grace time.Duration) {
+	r.mu.Lock()
+	cmd := r.cmd
+	r.ready = false
+	r.mu.Unlock()
+	if cmd == nil || cmd.Process == nil {
+		return
+	}
+	pgid := -cmd.Process.Pid
+	_ = syscall.Kill(pgid, syscall.SIGTERM)
+	deadline := time.Now().Add(grace)
+	for time.Now().Before(deadline) {
+		if !r.running() {
+			return
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+	log.Printf("mavgpud: llama-server did not exit in %s, killing", grace)
+	_ = syscall.Kill(pgid, syscall.SIGKILL)
+}
+
+// refreshReady asks llama-server whether the model is loaded. Called once per
+// supervisor tick, never per request.
+func (r *runner) refreshReady(ctx context.Context) {
+	if !r.running() {
+		return
+	}
+	ok := false
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, r.readyURL, nil)
+	if err == nil {
+		resp, err := r.http.Do(req)
+		if err == nil {
+			ok = resp.StatusCode == http.StatusOK
+			resp.Body.Close()
+		}
+	}
+	r.mu.Lock()
+	was := r.ready
+	r.ready = ok
+	r.mu.Unlock()
+	if ok && !was {
+		log.Printf("mavgpud: model ready")
+	}
+}

deploy/mavend.json

@@ -39,6 +39,23 @@
     "proxy": "socks5://192.168.240.1:10808"
   },
 
+  "//workstation": [
+    "The big model on the desk PC (bugmachine, 7900 GRE 16GB), fronted by",
+    "mavgpud on port 8080. It runs gemma-4-12b and it is preferred over the",
+    "resident Qwen3-1.7B for routing and replies whenever the card is free.",
+    "The machine is never assumed up: it sleeps, and the card is often held by",
+    "a CPT run, in which case mavgpud answers 503 and Maven falls back to the",
+    "resident model without saying so. Deleting this block restores exactly",
+    "the behaviour homesrv had before it existed.",
+    "Addressed by LAN address, not container name: mavgpud runs on another",
+    "machine and there is no shared docker network to name it on."
+  ],
+  "workstation": {
+    "url": "http://192.168.1.105:8080",
+    "probe": "15s",
+    "timeout": "90s"
+  },
+
   "//search": [
     "The live web, searched after his own notes and before Kiwix. Only the",
     "query string leaves the box — never a note, a fact, the persona block or",

deploy/mavgpud.json

@@ -0,0 +1,32 @@
+{
+  "listen": ":8080",
+  "llama_addr": "127.0.0.1:10000",
+  "llama_bin": "llama-server",
+  "llama_args": [
+    "-m", "/mnt/D/AI/gemma4/gemma-4-12B-it-qat-UD-Q4_K_XL.gguf",
+    "-md", "/mnt/D/AI/gemma4/mtp-gemma-4-12B-it-BF16.gguf",
+    "-ngl", "99",
+    "-fa", "on",
+    "-np", "1",
+    "--host", "127.0.0.1",
+    "--port", "10000",
+    "--ctx-size", "32768",
+    "--threads", "6",
+    "--batch-size", "2048",
+    "--ubatch-size", "512",
+    "--jinja",
+    "--chat-template-kwargs", "{\"enable_thinking\":false}",
+    "--spec-type", "draft-mtp",
+    "--spec-draft-n-max", "2"
+  ],
+
+  "kfd_root": "/sys/class/kfd/kfd/proc",
+  "drm_device": "/sys/class/drm/card1/device",
+
+  "poll": "1s",
+  "idle_timeout": "15m",
+  "stop_grace": "20s",
+  "min_free_vram_bytes": 10737418240,
+  "evict_after_polls": 2,
+  "start_after_polls": 5
+}

deploy/mavgpud.service

@@ -0,0 +1,24 @@
+[Unit]
+# Runs on the workstation (bugmachine), not on homesrv. Install as a systemd
+# user unit and turn on lingering, so the card is supervised after a reboot
+# with nobody logged in:
+#
+#   scp mavgpud workpc:~/.local/bin/mavgpud
+#   scp deploy/mavgpud.json workpc:~/.config/mavgpud.json
+#   scp deploy/mavgpud.service workpc:~/.config/systemd/user/mavgpud.service
+#   ssh workpc 'systemctl --user daemon-reload && systemctl --user enable --now mavgpud'
+#   sudo loginctl enable-linger kami
+Description=Maven GPU supervisor (holds llama-server while the card is free)
+After=network.target
+
+[Service]
+ExecStart=%h/.local/bin/mavgpud -config %h/.config/mavgpud.json
+Restart=always
+RestartSec=5
+# The card must come back when the supervisor goes down. mavgpud stops
+# llama-server on SIGTERM, so give it longer than stop_grace to do that.
+KillSignal=SIGTERM
+TimeoutStopSec=60
+
+[Install]
+WantedBy=default.target

docs/evals/2026-08-02-workstation-gemma4-12b.md

@@ -0,0 +1,82 @@
+# gemma-4-12b on the workstation, against the resident Qwen3-1.7B
+
+Measured 2026-08-02 on the fixtures as they stand. Dated file: it is not edited
+after today, and a newer number is a new file.
+
+Vikunja #485's first assumption was that a 7-14B measurably beats Qwen3-1.7B on
+the 77-case RU routing fixture and the 27-case talk fixture. It does, on both,
+and it is also faster.
+
+## The setup
+
+`gemma-4-12B-it-qat-UD-Q4_K_XL` with the `mtp-gemma-4-12B-it-BF16` draft model,
+served by `llama-server` b10220 on bugmachine (AMD 7900 GRE, 16GB), fronted by
+`mavgpud` on `192.168.1.105:8080`. Thinking is off through
+`--chat-template-kwargs '{"enable_thinking":false}'`, speculative decoding is
+`--spec-type draft-mtp --spec-draft-n-max 2`, context 32768. The exact line is
+`deploy/mavgpud.json`.
+
+Every number below crossed the LAN from homesrv. Note the trap: homesrv's shell
+exports `HTTP_PROXY`, Go honours it, and the runs need
+`env -u HTTP_PROXY -u HTTPS_PROXY -u http_proxy -u https_proxy`.
+
+## Routing, 77-case RU fixture
+
+| | full | intent-only | p50 | p95 |
+|---|---|---|---|---|
+| classifier alone (02-08) | 68.8% | — | 16.6µs | — |
+| Qwen3-1.7B through the cascade (31-07, 02-08) | 72.7% | 77.9% | 0.80-1.04s | — |
+| **gemma-4-12b through the cascade** | **84.4%** | **93.5%** | **329ms** | 429ms |
+| gemma-4-12b alone, no cascade | 55.8% | 85.7% | 335ms | 436ms |
+
+The workstation buys 11.7 points of full accuracy over the resident model. It
+buys 15.6 points of intent-only, at a third of the latency. The router's p50 was
+never the model's fault, which the 02-08 contention finding already said. A 12B
+on a free 16GB card answers a routing turn in a third of a second.
+
+Two things the table hides.
+
+The alone-versus-cascade gap is slots, not intents. gemma reads the intent right
+85.7% of the time on its own. It loses full accuracy on seven fact keys
+(`вода` instead of `water`, `ужин` instead of `meal`) and on six reminder times
+with no time slot. Stage 0 and the daemon's own extractor repair
+both, which is why the cascade is 28 points higher. The lesson is that the
+cascade earns its keep even under a much better model, not that it is scaffolding
+to remove.
+
+`errors: 6` in the alone row are declines on single-token and ambiguous
+utterances, all of which the cascade caught. The remaining defects through the
+cascade are three `query→fact` confusions, one `chat→query`, and one false
+clarify.
+
+## Talk, 27-case conversational fixture
+
+| | pass | notes |
+|---|---|---|
+| Qwen3-1.7B (31-07) | 20/27 | 11-17/27 for the 0.8B before it |
+| **gemma-4-12b** | **25/27 (92.6%)** | chat 8/9, knowledge 9/9, query 8/9 |
+
+Knowledge is the interesting column: 9/9, in Russian, with real answers about
+Rayleigh scattering, SSD versus HDD and thunder delay. That is the case the
+1.7B cannot do at all and the reason the naming half of the degradation rule
+exists.
+
+Two failures, and one of them is the persona defect the CPT (#122) targets:
+`query-notes-do-not-answer` wrote `заплатил` where Maven needs the feminine
+form. The other is `chat-joke`, where the model told a joke without using any of
+the words the check looks for. Run-to-run variance is about one case: a second
+run scored 24/27 with `chat-followup-server` also off-topic.
+
+## Nudge phrasing, 15-case fixture
+
+15/15, every check, no errors. `mood`, `lang`, `length`, `feminine`,
+`hisgender`, `address`, `cringe` and `ontopic` all clean.
+
+## What this settles and what it does not
+
+Settled: the size question. A 12B on the workstation beats the resident model on
+every fixture we have, and it is faster. The offload argument holds.
+
+Not settled: how often the card is free. That is #485's second assumption and
+only the `mavgpud` log answers it, after a week of the owner's normal work. A
+model that is better whenever it is up is worth little if it is never up.

docs/offload.md

@@ -58,6 +58,34 @@ jobs.
 
 The caller must be able to ask "is this peer usable right now" without a turn
 hanging on a timeout. A dead remote is a normal state, not an error state.
+`internal/llm.Pair` is that check on the Maven side. A prober caches the answer,
+so `Available()` is an atomic read and no turn pays for a health check.
+
+llama-server does not stay up on the workstation. It cannot: a resident 7-14B
+would hold 16GB against the owner's CPT runs. So a supervisor there owns its
+lifecycle, keeps it loaded while the card is free, and unloads it on idle or
+when another process needs the card (owner's call, 2026-08-02, Vikunja #488).
+
+That supervisor is still not a scheduler, and the distinction is worth holding.
+It arbitrates nothing between callers. It reports whether it can take work and
+manages one process to back that answer. Maven never asks it to start anything
+and never learns that it did.
+
+Contention is decided by presence under `/sys/class/kfd/kfd/proc`, not by a VRAM
+threshold. A ROCm process registers there when it initialises HIP, before it
+allocates anything. So the supervisor sees a contender during that job's startup,
+and yields before the job loses the memory it asked for. A
+threshold reads the card too late. By the time free VRAM has dropped, the other
+job has already lost the allocation race. Free VRAM is still read, but only as a
+precondition for loading, never as the eviction signal. One blind spot is known.
+A job can take the card without registering on the KFD, as a Vulkan or a
+video-decode job would. `describe()` logs every contender's comm, and that log is
+how we find out whether the blind spot is real.
+
+`mavgpud` runs from a systemd unit on the workstation with
+`deploy/mavgpud.json` as its config, and `llama_args` is passed to llama-server
+untouched. The model, the context size, the layer count and the MTP flags are the
+owner's business and not this daemon's schema.
 
 ## What stays on homesrv, permanently
 
@@ -97,7 +125,15 @@ Then the embedder above, **whisper.cpp** in `mavsttd`, and **piper** in `mavttsd
    `internal/netaddr` landed in PR #92. A seam address now carries its own scheme,
    and a scheme-less one is still unix. A tcp seam requires a shared token, because
    the filesystem permission that authenticated the unix socket is gone.
-2. **The resident model** (#485). Biggest quality delta. A 16GB card runs a 7-14B,
+2. **The resident model** (#485). Half wired, 02-08-2026. A `workstation` block
+   builds an `llm.Pair` in `modelSeam` (`cmd/mavend/voicewire.go`), and routing
+   and replies complete through it. Both are the silent half of the rule. The
+   naming half is not wired. A world question still goes to the resident model
+   through `PhraseQuery`. That, and the four callers 485 did not reach, are #490.
+   Measured, `docs/evals/2026-08-02-workstation-gemma4-12b.md`: gemma-4-12b
+   through the cascade scores 84.4% full accuracy at p50 329ms. The resident
+   model scores 72.7% at p50 0.80-1.04s. On the talk fixture it is 25/27
+   against 20/27. Biggest quality delta. A 16GB card runs a 7-14B,
    which fixes what the 1.7B gets wrong: world knowledge, and the persona the CPT
    targets. The degradation path is already written and measured, since the
    classifier scores 68.8% full accuracy at p50 16.6µs on its own.

internal/config/config.go

@@ -224,6 +224,11 @@ type Config struct {
 	// See SearchConfig.
 	Search *SearchConfig `json:"search,omitempty"`
 
+	// Workstation — the big model on the owner's desktop, preferred over the
+	// resident one when its GPU is free. nil / absent / url empty ⇒ homesrv
+	// behaves exactly as it does today. See WorkstationConfig.
+	Workstation *WorkstationConfig `json:"workstation,omitempty"`
+
 	// Praxis — the ecosystem attention-state service. When configured, maven
 	// calls the Praxis HTTP tools API for attention listing and item lifecycle.
 	// Maven never touches Praxis's database directly (ecosystem invariant: no
@@ -1105,6 +1110,44 @@ const (
 	DefaultKiwixSnippetRunes = 1500
 )
 
+// WorkstationConfig — the big model on the owner's desktop (bugmachine, a
+// 7900 GRE with 16GB), fronted by mavgpud.
+//
+// homesrv cannot grow a GPU, so the resident Qwen3-1.7B is the floor and this
+// is the preferred model above it (owner's call, 2026-08-02, docs/offload.md).
+// The workstation is never assumed up: its card is often held by a CPT run and
+// the machine sleeps. No block, or an empty URL, and homesrv behaves exactly as
+// it does today.
+//
+// Only the prompt crosses the LAN, and the workstation is not "the box". The
+// rules in CLAUDE.md about what may leave still apply.
+type WorkstationConfig struct {
+	// URL — where mavgpud listens, e.g. "http://192.168.1.105:8080". Empty ⇒
+	// the whole block is normalised to nil and nothing probes anything.
+	URL string `json:"url,omitempty"`
+
+	// Health — the admission endpoint. Empty ⇒ URL + "/health", which is what
+	// mavgpud serves. It answers 503 while the card is held, and that is the
+	// signal, so it must be the supervisor's endpoint and not llama-server's.
+	Health string `json:"health,omitempty"`
+
+	// Probe — how often admission is re-checked. 0 ⇒ DefaultWorkstationProbe.
+	// Nothing on the hot path waits for it: the answer is cached and read
+	// atomically, so this only sets how late Maven notices the card came back.
+	Probe Duration `json:"probe,omitempty"`
+
+	// Timeout — the per-request budget for a completion on the workstation.
+	// 0 ⇒ DefaultWorkstationTimeout. A big model on a LAN host is slower than
+	// the resident one, and a request that overruns falls back to the floor.
+	Timeout Duration `json:"timeout,omitempty"`
+}
+
+// Workstation defaults, applied in Normalise.
+const (
+	DefaultWorkstationProbe   = 15 * time.Second
+	DefaultWorkstationTimeout = 90 * time.Second
+)
+
 // SearchConfig — the self-hosted SearXNG instance she searches with.
 //
 // External search is allowed and off unless configured (CLAUDE.md). Configuring
@@ -1500,6 +1543,24 @@ func (c *Config) applyDefaults() {
 		}
 	}
 
+	// No address, no preferred model. An unconfigured workstation is the
+	// default deploy and must be indistinguishable from today.
+	if c.Workstation != nil && strings.TrimSpace(c.Workstation.URL) == "" {
+		c.Workstation = nil
+	}
+	if c.Workstation != nil {
+		w := c.Workstation
+		if strings.TrimSpace(w.Health) == "" {
+			w.Health = strings.TrimRight(w.URL, "/") + "/health"
+		}
+		if w.Probe <= 0 {
+			w.Probe = Duration(DefaultWorkstationProbe)
+		}
+		if w.Timeout <= 0 {
+			w.Timeout = Duration(DefaultWorkstationTimeout)
+		}
+	}
+
 	if c.Voice != nil {
 		if c.Voice.RouterThreshold <= 0 {
 			c.Voice.RouterThreshold = DefaultRouterThreshold

internal/config/config_test.go

@@ -413,3 +413,56 @@ func TestNormaliseFillsKiwixDefaults(t *testing.T) {
 		t.Error("rewrite: false was not honoured")
 	}
 }
+
+// A workstation with no address is not a workstation. The unconfigured deploy
+// must be indistinguishable from today, so the block is dropped rather than
+// left to fail one probe at a time.
+func TestNormaliseDropsAddresslessWorkstation(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		in   *WorkstationConfig
+	}{
+		{"no url", &WorkstationConfig{Probe: Duration(time.Second)}},
+		{"blank url", &WorkstationConfig{URL: "   "}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			c := &Config{Workstation: tc.in}
+			c.applyDefaults()
+			if c.Workstation != nil {
+				t.Errorf("kept an unusable workstation block: %+v", c.Workstation)
+			}
+		})
+	}
+}
+
+// The health endpoint defaults to the supervisor's, not llama-server's: mavgpud
+// answers 503 while the card is held, and that refusal is the whole signal.
+func TestNormaliseFillsWorkstationDefaults(t *testing.T) {
+	c := &Config{Workstation: &WorkstationConfig{URL: "http://192.168.1.105:8080/"}}
+	c.applyDefaults()
+	if c.Workstation == nil {
+		t.Fatal("dropped a usable workstation block")
+	}
+	if got, want := c.Workstation.Health, "http://192.168.1.105:8080/health"; got != want {
+		t.Errorf("Health = %q, want %q", got, want)
+	}
+	if time.Duration(c.Workstation.Probe) != DefaultWorkstationProbe {
+		t.Errorf("Probe = %s, want %s", time.Duration(c.Workstation.Probe), DefaultWorkstationProbe)
+	}
+	if time.Duration(c.Workstation.Timeout) != DefaultWorkstationTimeout {
+		t.Errorf("Timeout = %s, want %s", time.Duration(c.Workstation.Timeout), DefaultWorkstationTimeout)
+	}
+}
+
+// An explicit health URL is left alone: the supervisor may sit behind something
+// that does not put /health at the root.
+func TestNormaliseKeepsExplicitWorkstationHealth(t *testing.T) {
+	c := &Config{Workstation: &WorkstationConfig{
+		URL:    "http://192.168.1.105:8080",
+		Health: "http://192.168.1.105:9000/ready",
+	}}
+	c.applyDefaults()
+	if got, want := c.Workstation.Health, "http://192.168.1.105:9000/ready"; got != want {
+		t.Errorf("Health = %q, want %q", got, want)
+	}
+}

internal/llm/remote.go

@@ -0,0 +1,193 @@
+package llm
+
+import (
+	"context"
+	"errors"
+	"log"
+	"net/http"
+	"sync/atomic"
+	"time"
+)
+
+// Pair — a preferred model on another host, with the resident one as the floor.
+//
+// homesrv cannot grow a GPU and the workstation has 16GB of VRAM, so the big
+// model runs there and the resident Qwen3-1.7B stays here. See docs/offload.md.
+// The workstation is never assumed up: its GPU is often busy with CPT runs and
+// the manga-recap pipeline, and the machine sleeps. So the remote is preferred,
+// never required, and Pair is what makes "preferred" mean something precise.
+//
+// This is admission control, not a scheduler. There is no arbiter deciding who
+// gets the card. A prober asks the remote whether it will take work, caches the
+// answer, and every request reads that cached answer in nanoseconds. Routing
+// sits on the hot path at p50 825ms and must never wait on a machine that may
+// be asleep, so no request ever pays for a health check itself.
+//
+// Pair satisfies nothing by itself. Callers pick a method by which half of the
+// degradation rule they live under:
+//
+//   - Complete falls back silently. For routing, replies, and nudge phrasing,
+//     where the big model is only better and the 1.7B is today's shipping
+//     quality. He is not told which model phrased his reply.
+//   - CompleteRemote returns ErrRemoteUnavailable instead of falling back. For
+//     a world question, or a long Kiwix or search passage, where a 1.7B
+//     confabulates rather than summarises. A named gap beats an invented
+//     answer.
+type Pair struct {
+	remote *Client
+	floor  *Client
+
+	// up — the cached admission answer, written only by the prober goroutine
+	// and read by every request. Atomic so the read costs nanoseconds and no
+	// request ever contends with the prober.
+	up atomic.Bool
+
+	health   string
+	interval time.Duration
+	http     *http.Client
+	stop     chan struct{}
+}
+
+// ErrRemoteUnavailable — the workstation model was required and is not
+// answering. Callers on the naming half of the degradation rule turn this into
+// a gap in the reply ("не могу сейчас"), never into a guess from the floor.
+var ErrRemoteUnavailable = errors.New("llm: workstation model unavailable")
+
+// ErrNoFloor — a Pair was built with no resident model to fall back to. A
+// configuration mistake: the floor is the whole point.
+var ErrNoFloor = errors.New("llm: no floor client")
+
+// NewPair builds the two-model arrangement. remote may be nil, which is the
+// unconfigured deploy and must behave exactly as the box behaves today: every
+// call goes to the floor and nothing probes anything.
+//
+// health is the URL the prober asks. llama-server's /health answers "is a model
+// loaded and ready", which is the useful signal here, because llama-server
+// refuses to load at all when VRAM is short. That makes a busy card detectable
+// without any cooperation from the owner's other jobs.
+func NewPair(remote, floor *Client, health string, interval time.Duration) *Pair {
+	p := &Pair{
+		remote:   remote,
+		floor:    floor,
+		health:   health,
+		interval: interval,
+		http:     &http.Client{Timeout: probeTimeout},
+		stop:     make(chan struct{}),
+	}
+	return p
+}
+
+// probeTimeout — a remote that cannot answer /health this fast is not going to
+// serve a turn either. Short on purpose: the prober runs on its own goroutine,
+// but a slow probe still delays the moment Maven notices the card came back.
+const probeTimeout = 2 * time.Second
+
+// Start begins probing. It returns immediately, and the first probe runs before
+// the first tick so a remote that is already up is used on the first turn
+// rather than after one interval of falling back. Safe to call with a nil
+// remote; it does nothing.
+func (p *Pair) Start(ctx context.Context) {
+	if p.remote == nil || p.health == "" {
+		return
+	}
+	go func() {
+		p.probe(ctx)
+		t := time.NewTicker(p.interval)
+		defer t.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-p.stop:
+				return
+			case <-t.C:
+				p.probe(ctx)
+			}
+		}
+	}()
+}
+
+// Stop ends the prober. Idempotent.
+func (p *Pair) Stop() {
+	select {
+	case <-p.stop:
+	default:
+		close(p.stop)
+	}
+}
+
+// Available reports whether the workstation will take work right now. It reads
+// a cached flag, so it is safe to call per turn on the hot path. A false answer
+// is never stale in the direction that matters: the worst case is that Maven
+// falls back for up to one probe interval after the card frees up.
+func (p *Pair) Available() bool {
+	return p.remote != nil && p.up.Load()
+}
+
+func (p *Pair) probe(ctx context.Context) {
+	ctx, cancel := context.WithTimeout(ctx, probeTimeout)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, p.health, nil)
+	if err != nil {
+		p.set(false)
+		return
+	}
+	resp, err := p.http.Do(req)
+	if err != nil {
+		p.set(false)
+		return
+	}
+	defer resp.Body.Close()
+	p.set(resp.StatusCode == http.StatusOK)
+}
+
+// set records the admission answer and logs only the transitions. A machine
+// that sleeps every night would otherwise write one line per interval forever.
+func (p *Pair) set(up bool) {
+	if p.up.Swap(up) == up {
+		return
+	}
+	if up {
+		log.Printf("llm: workstation model available at %s", p.health)
+	} else {
+		log.Printf("llm: workstation model unavailable, falling back to the resident model")
+	}
+}
+
+// Complete runs r on the workstation when it will take work, and on the
+// resident model otherwise. A remote that fails mid-request falls back too: the
+// admission answer is a cache and can be one interval out of date, so an error
+// here is expected rather than exceptional.
+//
+// This is the silent half of the degradation rule. It must be indistinguishable
+// from today's behaviour when the workstation is down.
+func (p *Pair) Complete(ctx context.Context, r Req) (string, error) {
+	if p.floor == nil {
+		return "", ErrNoFloor
+	}
+	if p.Available() {
+		out, err := p.remote.Complete(ctx, r)
+		if err == nil {
+			return out, nil
+		}
+		// The cached answer was wrong. Correct it now rather than sending the
+		// next request into the same hole, then fall back.
+		p.set(false)
+	}
+	return p.floor.Complete(ctx, r)
+}
+
+// CompleteRemote runs r on the workstation or refuses. It never falls back,
+// because for a world question the resident 1.7B does not answer worse, it
+// invents. Callers turn ErrRemoteUnavailable into a named gap.
+func (p *Pair) CompleteRemote(ctx context.Context, r Req) (string, error) {
+	if !p.Available() {
+		return "", ErrRemoteUnavailable
+	}
+	out, err := p.remote.Complete(ctx, r)
+	if err != nil {
+		p.set(false)
+		return "", errors.Join(ErrRemoteUnavailable, err)
+	}
+	return out, nil
+}

internal/llm/remote_test.go

@@ -0,0 +1,210 @@
+package llm
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// completionServer stands in for a llama-server. It counts what reached it, so
+// a test can say which of the two models answered.
+func completionServer(t *testing.T, reply string, hits *atomic.Int64) *httptest.Server {
+	t.Helper()
+	s := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		hits.Add(1)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"` + reply + `"}}]}`))
+	}))
+	t.Cleanup(s.Close)
+	return s
+}
+
+func healthServer(t *testing.T, ok *atomic.Bool) *httptest.Server {
+	t.Helper()
+	s := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !ok.Load() {
+			w.WriteHeader(http.StatusServiceUnavailable)
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+	}))
+	t.Cleanup(s.Close)
+	return s
+}
+
+// waitFor polls until cond holds or the deadline passes. The prober runs on its
+// own goroutine, so a test has to wait for it rather than assume it has run.
+func waitFor(t *testing.T, cond func() bool) bool {
+	t.Helper()
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if cond() {
+			return true
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	return false
+}
+
+// The unconfigured deploy. No remote, no probing, every call to the floor —
+// exactly what the box does today.
+func TestNoRemoteGoesToTheFloor(t *testing.T) {
+	var floorHits atomic.Int64
+	floor := completionServer(t, "floor", &floorHits)
+
+	p := NewPair(nil, New(floor.URL, time.Second), "", time.Second)
+	p.Start(context.Background())
+	defer p.Stop()
+
+	if p.Available() {
+		t.Fatal("a Pair with no remote reports available")
+	}
+	out, err := p.Complete(context.Background(), Req{User: "привет"})
+	if err != nil {
+		t.Fatalf("complete: %v", err)
+	}
+	if out != "floor" || floorHits.Load() != 1 {
+		t.Fatalf("out = %q, floor hits = %d", out, floorHits.Load())
+	}
+}
+
+// The workstation is up, so it answers and the resident model is not touched.
+func TestAvailableRemoteAnswers(t *testing.T) {
+	var remoteHits, floorHits atomic.Int64
+	remote := completionServer(t, "remote", &remoteHits)
+	floor := completionServer(t, "floor", &floorHits)
+	up := &atomic.Bool{}
+	up.Store(true)
+	health := healthServer(t, up)
+
+	p := NewPair(New(remote.URL, time.Second), New(floor.URL, time.Second), health.URL, 20*time.Millisecond)
+	p.Start(context.Background())
+	defer p.Stop()
+	if !waitFor(t, p.Available) {
+		t.Fatal("prober never saw the remote come up")
+	}
+
+	out, err := p.Complete(context.Background(), Req{User: "привет"})
+	if err != nil {
+		t.Fatalf("complete: %v", err)
+	}
+	if out != "remote" || floorHits.Load() != 0 {
+		t.Fatalf("out = %q, floor hits = %d", out, floorHits.Load())
+	}
+}
+
+// The card is busy, so /health refuses and Complete degrades silently. This is
+// the constraint from 483: the workstation being down is indistinguishable from
+// today's behaviour.
+func TestBusyCardFallsBackSilently(t *testing.T) {
+	var remoteHits, floorHits atomic.Int64
+	remote := completionServer(t, "remote", &remoteHits)
+	floor := completionServer(t, "floor", &floorHits)
+	health := healthServer(t, &atomic.Bool{}) // never ok
+
+	p := NewPair(New(remote.URL, time.Second), New(floor.URL, time.Second), health.URL, 20*time.Millisecond)
+	p.Start(context.Background())
+	defer p.Stop()
+	time.Sleep(60 * time.Millisecond)
+
+	out, err := p.Complete(context.Background(), Req{User: "привет"})
+	if err != nil {
+		t.Fatalf("complete: %v", err)
+	}
+	if out != "floor" || remoteHits.Load() != 0 {
+		t.Fatalf("out = %q, remote hits = %d", out, remoteHits.Load())
+	}
+}
+
+// The cached admission answer can be one interval out of date, so a remote that
+// dies between probes must still not break the turn.
+func TestRemoteErrorMidRequestFallsBack(t *testing.T) {
+	var floorHits atomic.Int64
+	dead := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer dead.Close()
+	floor := completionServer(t, "floor", &floorHits)
+	up := &atomic.Bool{}
+	up.Store(true)
+	health := healthServer(t, up)
+
+	p := NewPair(New(dead.URL, time.Second), New(floor.URL, time.Second), health.URL, time.Hour)
+	p.Start(context.Background())
+	defer p.Stop()
+	if !waitFor(t, p.Available) {
+		t.Fatal("prober never saw the remote come up")
+	}
+
+	out, err := p.Complete(context.Background(), Req{User: "привет"})
+	if err != nil {
+		t.Fatalf("complete: %v", err)
+	}
+	if out != "floor" || floorHits.Load() != 1 {
+		t.Fatalf("out = %q, floor hits = %d", out, floorHits.Load())
+	}
+	// The failed request must have corrected the cached answer, so the next
+	// one does not walk into the same hole.
+	if p.Available() {
+		t.Fatal("a failed remote request left the admission answer up")
+	}
+}
+
+// The naming half of the degradation rule. A world question must not be handed
+// to the resident model, because it answers by inventing.
+func TestCompleteRemoteNamesTheGap(t *testing.T) {
+	var floorHits atomic.Int64
+	floor := completionServer(t, "floor", &floorHits)
+	health := healthServer(t, &atomic.Bool{}) // never ok
+
+	p := NewPair(New("http://127.0.0.1:1", time.Second), New(floor.URL, time.Second), health.URL, 20*time.Millisecond)
+	p.Start(context.Background())
+	defer p.Stop()
+	time.Sleep(60 * time.Millisecond)
+
+	if _, err := p.CompleteRemote(context.Background(), Req{User: "почему небо голубое"}); !errors.Is(err, ErrRemoteUnavailable) {
+		t.Fatalf("err = %v, want ErrRemoteUnavailable", err)
+	}
+	if floorHits.Load() != 0 {
+		t.Fatalf("CompleteRemote fell back to the floor %d times", floorHits.Load())
+	}
+}
+
+// Routing sits on the hot path and must never pay for a health check. Available
+// reads a cached flag, so it costs no network at all.
+func TestAvailableDoesNotProbe(t *testing.T) {
+	var probes atomic.Int64
+	health := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		probes.Add(1)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer health.Close()
+
+	p := NewPair(New("http://127.0.0.1:1", time.Second), New("http://127.0.0.1:1", time.Second), health.URL, time.Hour)
+	p.Start(context.Background())
+	defer p.Stop()
+	if !waitFor(t, p.Available) {
+		t.Fatal("prober never ran")
+	}
+
+	before := probes.Load()
+	for range 1000 {
+		p.Available()
+	}
+	if got := probes.Load(); got != before {
+		t.Fatalf("1000 Available calls made %d probes", got-before)
+	}
+}
+
+// A Pair with no floor is a configuration mistake, and it must say so rather
+// than silently having nowhere to degrade to.
+func TestNoFloorIsAnError(t *testing.T) {
+	p := NewPair(nil, nil, "", time.Second)
+	if _, err := p.Complete(context.Background(), Req{User: "привет"}); !errors.Is(err, ErrNoFloor) {
+		t.Fatalf("err = %v, want ErrNoFloor", err)
+	}
+}