Pin compose example to v0.1.7

README.md

@@ -72,6 +72,7 @@ override file values. Invalid values fail at startup.
 | `UPDATE_INTERVAL` | `6h` | Auto-update check interval |
 | `UPDATE_REPO` | `https://git.rambossek.at/PUBLIC/gpu-turnstile` | Repository checked for releases |
 | `UPDATE_ASSET` | `gpu-turnstile.exe` | Release asset to download |
+| `APP_VER` | `stable` | `dev` disables updates, `stable` tracks latest, or pin an exact `vX.Y.Z` |
 
 ## Observability
 
@@ -112,12 +113,19 @@ gpu-turnstile.exe --remove-service
 ```
 
 Layout: `C:\Program Files\gpu-turnstile\` holds the exe and
-`gpu-turnstile.env`, logs go to `C:\ProgramData\gpu-turnstile\` (set
-`LOG_FILE` in the env file — there is no console). The service always runs
+`gpu-turnstile.env`, logs go to `C:\ProgramData\gpu-turnstile\`. If you
+install without a config, the installer writes a sample env file with every
+setting commented and explained — only `LOG_FILE` is active (a service has
+no console). Your own `LOG_FILE` setting is always kept. The service always
+runs
 as the virtual account `NT SERVICE\gpu-turnstile` (low-privilege,
 per-service, no password); the installer automatically grants it write
 access to the install and data directories — nothing else to do.
 
+Re-running `--install-service` is safe: it stops a running service,
+replaces the installed binary only if it changed, fixes the registration
+only where it drifted, and restarts the service only if it was running.
+
 ### Run natively on Linux (systemd)
 
 The same binary works on Linux. Install it as a systemd service as root:
@@ -144,7 +152,10 @@ containers and interactive shells.
 release on startup and every `UPDATE_INTERVAL`, verifies the Ed25519
 signature of the download against the public key embedded at build time,
 and — once the GPU lock is idle — restarts the service onto the new
-version. Disable with `AUTO_UPDATE=false`. Releases are signed by CI with
+version. `APP_VER` controls the target: `dev` disables updates, `stable`
+(the default) tracks the latest release, and an exact `vX.Y.Z` pins that
+release (even as a downgrade or to replace a dev build). Disable entirely
+with `AUTO_UPDATE=false`. Releases are signed by CI with
 OpenSSL; the matching public key lives in `internal/update/pubkey.go`
 (one-time setup: `openssl genpkey -algorithm ed25519 -out private.pem`,
 `openssl pkey -in private.pem -pubout -out public.pem`; private key goes

SPEC.md

@@ -158,6 +158,8 @@ override file values. A missing file is fine; a malformed one is fatal.
 | `UPDATE_INTERVAL` | `6h` | auto-update check interval |
 | `UPDATE_REPO` | `https://git.rambossek.at/PUBLIC/gpu-turnstile` | repository to check for releases |
 | `UPDATE_ASSET` | `gpu-turnstile.exe` | release asset to download |
+| `APP_VER` | `stable` | version to run: `dev` disables updates, `stable` tracks the latest release, or an exact `vX.Y.Z` pin (up- or downgraded to) |
+| `CFG_VER` | _(installer-managed)_ | config format reference written by `--install-service`; missing = the file is replaced with a fresh sample (backup `.bak`) |
 
 Startup fails fast on unparsable values and when neither consumer URL is
 set. Enabled upstreams are probed once at start (`/api/version`,
@@ -176,12 +178,27 @@ prompt instead of failing — the command relaunches itself elevated, waits
 for the child, and mirrors its exit code. The legacy form
 `gpu-turnstile service install|remove` does the same thing.
 
+Re-running install on an already-registered service converges instead of
+failing: a running service is stopped first, the installed binary copy is
+refreshed only when the content differs, the registration (Windows service
+config / systemd unit) is updated only where it drifted, and the service is
+started again only if it was running before.
+
 By default install creates the canonical layout and copies the binary into
 it (Windows: `%ProgramFiles%\gpu-turnstile\`, plus
 `%ProgramData%\gpu-turnstile\` for logs; Linux: `/var/lib/gpu-turnstile/`
-with the config at `/etc/gpu-turnstile.env`). An existing config in the
-target location is never overwritten. `--no-copy` registers the current
-executable location as-is instead.
+with the config at `/etc/gpu-turnstile.env`). If there is no config at all,
+install writes a sample env file covering every setting — each with a
+comment line, everything commented out — except the `CFG_VER`/`APP_VER`
+header and `LOG_FILE`, which is active on Windows
+(`%ProgramData%\gpu-turnstile\gpu-turnstile.log`) since a service has no
+console; on Linux it stays commented because stderr goes to the journal.
+The first line is `CFG_VER=vX.Y.Z`, recording the installer version. When a
+later version's install finds an older `CFG_VER`, it appends every setting
+the file does not mention (commented or not) at the end and updates
+`CFG_VER`; a file without `CFG_VER` is invalid and gets replaced by a fresh
+sample, with the old content kept as `<file>.bak`. `--no-copy` registers
+the current executable location as-is and leaves the config untouched.
 
 ### Windows
 
@@ -189,8 +206,9 @@ executable location as-is instead.
   `%ProgramData%\gpu-turnstile\`, copies the exe and (if none exists there
   yet) the `gpu-turnstile.env` into the Program Files directory, and
   registers that copy as a Windows service; recovery actions restart it
-  5 s after any failure. Logs go to the ProgramData directory via
-  `LOG_FILE` since there is no console.
+  5 s after any failure. The install ensures the env file sets `LOG_FILE`
+  to `%ProgramData%\gpu-turnstile\gpu-turnstile.log` since there is no
+  console — an existing `LOG_FILE` setting is kept.
 - **Account**: the service always runs as the virtual account
   `NT SERVICE\gpu-turnstile` — a per-service low-privilege identity the
   SCM manages (no password, automatic logon-as-a-service right, no admin
@@ -238,19 +256,25 @@ executable location as-is instead.
   `RestartSec=5s` brings up the staged binary after the updater exits with
   code 3.
 - **Auto-update**: on startup and every `UPDATE_INTERVAL`, the binary
-  checks `UPDATE_REPO`'s latest release; if its tag is a newer `vX.Y.Z`,
-  it downloads `UPDATE_ASSET` plus its `.sig` (and `.sha256` when present)
-  and verifies an Ed25519 signature against the public key embedded in
+  consults `APP_VER`: `dev` disables updates; `stable` (the default)
+  fetches `UPDATE_REPO`'s latest release and applies it when its tag is a
+  newer `vX.Y.Z` (a `dev` binary cannot be compared and is replaced by the
+  latest release); a `vX.Y.Z` pin fetches that exact tag and stages it on
+  any difference, including downgrades. Applying means downloading
+  `UPDATE_ASSET` plus its `.sig` (and `.sha256` when present) and verifying
+  an Ed25519 signature against the public key embedded in
   `internal/update/pubkey.go`. A verified binary is swapped in next to the
   running exe (rename-aside, allowed on Windows), and once the GPU lock is
   idle the process exits with code 3 so the service recovery restarts it
   on the new version. Interactive runs only log "restart to apply".
-  `dev` builds and builds without an embedded public key never update.
-- **`--force-update`** runs the same check immediately: it downloads,
-  verifies and stages a newer release, and if the service is running it
-  restarts it right away (otherwise the new version applies on next
-  start). On Windows it elevates via UAC only when the stage or restart
-  needs permissions the caller does not have.
+  Builds without an embedded public key never update.
+- **`--force-update`** runs the same check immediately, single-shot: one
+  attempt with a 30 s timeout, then exit — "up to date" (exit 0) or the
+  error (exit 1), no retries. When a newer release is found it downloads,
+  verifies and stages it, and if the service is running it restarts it
+  right away (otherwise the new version applies on next start). On Windows
+  it elevates via UAC only when the stage or restart needs permissions the
+  caller does not have.
 - **Signing setup (one time)**: `openssl genpkey -algorithm ed25519 -out
   private.pem`; `openssl pkey -in private.pem -pubout -out public.pem`.
   Private key → repo secret `RELEASE_SIGNING_KEY`; public key → committed into
@@ -334,7 +358,8 @@ are new.
   receives the first chunk before the last is sent (no buffering).
 - `internal/config`: env-file parsing, precedence, fail-fast values.
 - `internal/update`: fake Gitea releases API; staged update happy path,
-  tampered signature rejected, older versions and dev builds skipped.
+  tampered signature rejected, older versions skipped, APP_VER=dev and
+  pinned releases honored.
 
 ## Build and CI
 

cmd/gpu-turnstile/main.go

@@ -299,6 +299,9 @@ func forceUpdateCommand(configPath string, elevatedChild bool) int {
 		defer waitForEnter()
 	}
 	cfg, err := loadMergedConfig(configPath)
+	if errors.Is(err, config.ErrNoConsumer) {
+		err = nil // update settings do not depend on a consumer URL
+	}
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "%s\n\ngpu-turnstile: %v\n", versionLine(), err)
 		return 1
@@ -310,9 +313,15 @@ func forceUpdateCommand(configPath string, elevatedChild bool) int {
 	}
 	log, _, logCloser := newLogger(cfg)
 	defer logCloser.Close()
-	u := &update.Updater{Repo: cfg.UpdateRepo, Asset: cfg.UpdateAsset, Version: version, Log: log}
+	if cfg.AppVersion == "dev" {
+		fmt.Printf("%s: APP_VER=dev, updates disabled\n", versionLine())
+		return 0
+	}
+	u := &update.Updater{Repo: cfg.UpdateRepo, Asset: cfg.UpdateAsset, Version: version, Desired: cfg.AppVersion, Log: log}
 
-	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	// Single-shot: one attempt, fail fast when the server is unreachable
+	// instead of hanging in a TCP connect for minutes.
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancel()
 	staged, err := u.Check(ctx, exePath)
 	if err != nil && isPermission(err) && !service.Elevated() {
@@ -381,7 +390,7 @@ func serviceCommand(configPath string, install, noCopy, elevatedChild bool) int
 		if abs, absErr := filepath.Abs(path); absErr == nil {
 			path = abs
 		}
-		err = service.Install(path, !noCopy)
+		err = service.Install(path, !noCopy, version)
 	} else {
 		err = service.Remove()
 	}
@@ -561,7 +570,7 @@ func updateLoop(ctx context.Context, cfg config.Config, log *slog.Logger, lk *lo
 		log.Warn("auto-update disabled: cannot locate executable", "err", err)
 		return
 	}
-	u := &update.Updater{Repo: cfg.UpdateRepo, Asset: cfg.UpdateAsset, Version: version, Log: log}
+	u := &update.Updater{Repo: cfg.UpdateRepo, Asset: cfg.UpdateAsset, Version: version, Desired: cfg.AppVersion, Log: log}
 	for {
 		staged, err := u.Check(ctx, exePath)
 		if err != nil && ctx.Err() == nil {

compose.yaml.example

@@ -6,7 +6,7 @@
 # ComfyUI --listen 0.0.0.0 --port 8189).
 services:
   gpu-turnstile:
-    image: git.rambossek.at/public/gpu-turnstile:v0.1.6
+    image: git.rambossek.at/public/gpu-turnstile:v0.1.7
     restart: unless-stopped
     environment:
       # Each consumer is enabled by setting its URL; leave one unset to

internal/config/config.go

@@ -4,6 +4,7 @@ package config
 
 import (
 	"bufio"
+	"errors"
 	"fmt"
 	"io"
 	"log/slog"
@@ -37,6 +38,11 @@ type Config struct {
 	UpdateRepo     string
 	UpdateAsset    string
 
+	// AppVersion is the version the user wants to run: "dev" disables
+	// updates, "stable" tracks the latest release, anything else is an
+	// exact vX.Y.Z release to pin. From APP_VER; defaults to "stable".
+	AppVersion string
+
 	// LLMBusyMode is "wait" (hold requests until the lock is free or
 	// LLMWaitTimeout expires) or "reject" (immediately answer with
 	// LLMBusyStatus + Retry-After when an image job is active or pending).
@@ -75,6 +81,7 @@ func Defaults() Config {
 		UpdateInterval: 6 * time.Hour,
 		UpdateRepo:     "https://git.rambossek.at/PUBLIC/gpu-turnstile",
 		UpdateAsset:    "gpu-turnstile.exe",
+		AppVersion:     "stable",
 
 		LLMBusyMode:    "wait",
 		LLMBusyStatus:  503,
@@ -84,6 +91,11 @@ func Defaults() Config {
 	}
 }
 
+// ErrNoConsumer is returned by Load when neither OLLAMA_URL nor COMFY_URL
+// is set. Commands that never talk to an upstream (--force-update) may
+// ignore it and proceed with the rest of the configuration.
+var ErrNoConsumer = errors.New("at least one of OLLAMA_URL or COMFY_URL must be set (each URL enables its consumer)")
+
 // ParseEnvFile parses a .env-style file: KEY=VALUE lines, blank lines and
 // #-comments are ignored, no quoting. A line without '=' is an error.
 func ParseEnvFile(r io.Reader) (map[string]string, error) {
@@ -199,6 +211,17 @@ func Load(getenv func(string) string) (Config, error) {
 		}
 		cfg.BusyRetryAfter = n
 	}
+	if v := getenv("APP_VER"); v != "" {
+		switch {
+		case v == "dev" || v == "stable":
+			cfg.AppVersion = v
+		default:
+			if _, ok := parseVersion(v); !ok {
+				return cfg, fmt.Errorf("APP_VER: must be \"dev\", \"stable\" or a vX.Y.Z version")
+			}
+			cfg.AppVersion = "v" + strings.TrimPrefix(v, "v")
+		}
+	}
 	// LOGLEVEL is the canonical spelling; LOG_LEVEL is kept as an alias.
 	logLevelValue := getenv("LOGLEVEL")
 	if logLevelValue == "" {
@@ -219,7 +242,7 @@ func Load(getenv func(string) string) (Config, error) {
 		return cfg, fmt.Errorf("LOG_FORMAT: must be \"text\" or \"json\"")
 	}
 	if cfg.OllamaURL == "" && cfg.ComfyURL == "" {
-		return cfg, fmt.Errorf("at least one of OLLAMA_URL or COMFY_URL must be set (each URL enables its consumer)")
+		return cfg, ErrNoConsumer
 	}
 	return cfg, nil
 }

internal/config/config_test.go

@@ -1,6 +1,7 @@
 package config
 
 import (
+	"errors"
 	"log/slog"
 	"strings"
 	"testing"
@@ -39,6 +40,38 @@ func TestLoadRequiresConsumer(t *testing.T) {
 	if err == nil || !strings.Contains(err.Error(), "OLLAMA_URL") {
 		t.Fatalf("err = %v, want missing-consumer error", err)
 	}
+	if !errors.Is(err, ErrNoConsumer) {
+		t.Fatalf("err = %v, want errors.Is(err, ErrNoConsumer)", err)
+	}
+}
+
+func TestAppVersion(t *testing.T) {
+	load := func(appVer string) (Config, error) {
+		return Load(func(k string) string {
+			switch k {
+			case "OLLAMA_URL":
+				return "http://127.0.0.1:11435"
+			case "APP_VER":
+				return appVer
+			}
+			return ""
+		})
+	}
+	cfg, err := load("")
+	if err != nil || cfg.AppVersion != "stable" {
+		t.Fatalf("default AppVersion = %q, err %v; want stable", cfg.AppVersion, err)
+	}
+	for _, v := range []string{"dev", "stable"} {
+		if cfg, err := load(v); err != nil || cfg.AppVersion != v {
+			t.Fatalf("APP_VER=%s: got %q, err %v", v, cfg.AppVersion, err)
+		}
+	}
+	if cfg, err := load("1.2.3"); err != nil || cfg.AppVersion != "v1.2.3" {
+		t.Fatalf("APP_VER=1.2.3: got %q, err %v; want normalized v1.2.3", cfg.AppVersion, err)
+	}
+	if _, err := load("nightly"); err == nil {
+		t.Fatal("APP_VER=nightly: want validation error")
+	}
 }
 
 func TestParseEnvFile(t *testing.T) {

internal/config/sample.go

@@ -0,0 +1,176 @@
+package config
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// sampleEntry is one line pair in the sample env file: a comment and the
+// (usually commented-out) KEY=VALUE line.
+type sampleEntry struct {
+	name    string
+	value   string
+	comment string
+	active  bool // rendered uncommented
+}
+
+// appVerComment documents APP_VER wherever it is rendered.
+const appVerComment = `Version to run: "dev" disables updates, "stable" tracks the latest release, or pin an exact release like v0.1.7`
+
+// sampleEntries lists every setting in sample order. logFile activates the
+// LOG_FILE line (Windows install); empty keeps it commented like the rest.
+// CFG_VER and APP_VER are not entries — they head the file, always active.
+func sampleEntries(logFile string) []sampleEntry {
+	return []sampleEntry{
+		{"LISTEN_OLLAMA", ":11434", "Ollama-facing listener address", false},
+		{"LISTEN_COMFY", ":8188", "ComfyUI-facing listener address", false},
+		{"OLLAMA_URL", "http://127.0.0.1:11434", "Ollama upstream URL; setting it enables the Ollama consumer (default: empty = disabled)", false},
+		{"COMFY_URL", "http://127.0.0.1:8188", "ComfyUI upstream URL; setting it enables the ComfyUI consumer (default: empty = disabled)", false},
+		{"WARM_MODEL", "", "Optional model to reload after an image job (default: empty = none)", false},
+		{"UNLOAD_TIMEOUT", "60s", "How long to wait for Ollama to unload a model", false},
+		{"JOB_TIMEOUT", "15m", "Maximum time to wait for a ComfyUI job", false},
+		{"LLM_WAIT_TIMEOUT", "10m", "Max time an LLM request waits for the GPU before being answered 503 (wait mode)", false},
+		{"LLM_BUSY_MODE", "wait", `How blocked LLM requests are handled: "wait" holds them, "reject" fails them immediately`, false},
+		{"LLM_BUSY_STATUS", "503", "HTTP status for rejected LLM requests in reject mode (400-599, e.g. 429)", false},
+		{"BUSY_RETRY_AFTER", "30", "Seconds sent as Retry-After on busy responses (both modes)", false},
+		{"LOGLEVEL", "warn", `Log verbosity: debug, info, warn, error; "info" logs every request (LOG_LEVEL works too)`, false},
+		{"LOG_FORMAT", "text", `Log format: "text" or "json"`, false},
+		{"LOG_FILE", logFile, "Append logs to this file instead of stderr (a Windows service has no console)", logFile != ""},
+		{"UNLOAD_POLL_INTERVAL", "500ms", "/api/ps poll interval while unloading", false},
+		{"HISTORY_POLL_INTERVAL", "1s", "/history/<id> poll interval while a job runs", false},
+		{"PROBE_TIMEOUT", "5s", "Startup probe timeout for the enabled upstreams", false},
+		{"FREE_TIMEOUT", "30s", "Timeout for the POST /free call after an image job", false},
+		{"WARM_TIMEOUT", "2m", "Timeout for the warm-model reload after an image job", false},
+		{"SHUTDOWN_TIMEOUT", "10s", "Graceful shutdown timeout on SIGINT/SIGTERM", false},
+		{"BACKOFF_INITIAL", "1s", "First retry wait when an upstream connection fails", false},
+		{"BACKOFF_MAX", "60s", "Cap for the exponential retry backoff", false},
+		{"PROMPT_CAPTURE_LIMIT", "65536", "Bytes of the /prompt response buffered to find prompt_id (pass-through unaffected)", false},
+		{"AUTO_UPDATE", "true", "Poll the releases API for signed updates", false},
+		{"UPDATE_INTERVAL", "6h", "Auto-update check interval", false},
+		{"UPDATE_REPO", "https://git.rambossek.at/PUBLIC/gpu-turnstile", "Repository to check for releases", false},
+		{"UPDATE_ASSET", "gpu-turnstile.exe", "Release asset to download", false},
+	}
+}
+
+// SampleEnv renders a sample .env file covering every setting, each with a
+// comment line. Everything is commented out — so all defaults apply —
+// except the CFG_VER/APP_VER header and LOG_FILE when logFile is non-empty
+// (a Windows service has no console). CFG_VER records the version that
+// wrote the file so later installs can upgrade it.
+func SampleEnv(version, logFile string) string {
+	var b strings.Builder
+	fmt.Fprintf(&b, "CFG_VER=%s\n", version)
+	b.WriteString("# Config format reference, written by the installer — do not edit.\n")
+	b.WriteString("# The installer uses it to append newly added settings on updates.\n\n")
+	b.WriteString("# gpu-turnstile configuration\n")
+	b.WriteString("# KEY=VALUE lines; \"#\" starts a comment. Every setting below is at its\n")
+	b.WriteString("# default and commented out — remove the \"#\" to change it.\n")
+	b.WriteString("# At least one of OLLAMA_URL / COMFY_URL must be set for the proxy to start.\n\n")
+	writeEntry(&b, sampleEntry{"APP_VER", "stable", appVerComment, true})
+	for _, e := range sampleEntries(logFile) {
+		writeEntry(&b, e)
+	}
+	return b.String()
+}
+
+func writeEntry(b *strings.Builder, e sampleEntry) {
+	fmt.Fprintf(b, "# %s\n", e.comment)
+	if e.active {
+		fmt.Fprintf(b, "%s=%s\n\n", e.name, e.value)
+	} else {
+		fmt.Fprintf(b, "#%s=%s\n\n", e.name, e.value)
+	}
+}
+
+// SyncSample upgrades an installer-written env file: when its CFG_VER says
+// it was written by an older gpu-turnstile, every setting the file does not
+// mention — commented or not — is appended at the end, and CFG_VER is
+// updated to version. Files without CFG_VER (hand-written or foreign),
+// up-to-date files and "dev" builds are returned unchanged; changed reports
+// whether the returned content differs.
+func SyncSample(data, version, logFile string) (string, bool) {
+	if version == "" || version == "dev" {
+		return data, false
+	}
+	values, err := ParseEnvFile(strings.NewReader(data))
+	if err != nil || values["CFG_VER"] == "" {
+		return data, false // not installer-written; the caller decides
+	}
+	if compareVersions(values["CFG_VER"], version) >= 0 {
+		return data, false // same or newer
+	}
+
+	present := make(map[string]bool)
+	for _, line := range strings.Split(data, "\n") {
+		line = strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(line), "#"))
+		if name, _, ok := strings.Cut(line, "="); ok {
+			present[strings.TrimSpace(name)] = true
+		}
+	}
+
+	lines := strings.Split(data, "\n")
+	for i, l := range lines {
+		if strings.HasPrefix(strings.TrimSpace(l), "CFG_VER=") {
+			lines[i] = "CFG_VER=" + version
+			break
+		}
+	}
+	out := strings.Join(lines, "\n")
+	if !strings.HasSuffix(out, "\n") {
+		out += "\n"
+	}
+
+	var b strings.Builder
+	if !present["APP_VER"] {
+		fmt.Fprintf(&b, "\n# Added by gpu-turnstile %s:\n", version)
+		writeEntry(&b, sampleEntry{"APP_VER", "stable", appVerComment, true})
+	}
+	for _, e := range sampleEntries(logFile) {
+		if !present[e.name] {
+			fmt.Fprintf(&b, "\n# Added by gpu-turnstile %s:\n", version)
+			writeEntry(&b, e)
+		}
+	}
+	out += b.String()
+	return out, out != data
+}
+
+// compareVersions orders two vX.Y.Z version strings. Unparseable versions
+// (including "dev") sort before any release.
+func compareVersions(a, b string) int {
+	pa, oka := parseVersion(a)
+	pb, okb := parseVersion(b)
+	if oka != okb {
+		if oka {
+			return 1
+		}
+		return -1
+	}
+	for i := range pa {
+		if pa[i] != pb[i] {
+			if pa[i] > pb[i] {
+				return 1
+			}
+			return -1
+		}
+	}
+	return 0
+}
+
+func parseVersion(v string) ([3]int, bool) {
+	var out [3]int
+	v = strings.TrimPrefix(strings.TrimSpace(v), "v")
+	parts := strings.Split(v, ".")
+	if len(parts) != 3 {
+		return out, false
+	}
+	for i, p := range parts {
+		n, err := strconv.Atoi(p)
+		if err != nil || n < 0 {
+			return out, false
+		}
+		out[i] = n
+	}
+	return out, true
+}

internal/config/sample_test.go

@@ -0,0 +1,143 @@
+package config
+
+import (
+	"strings"
+	"testing"
+)
+
+const sampleLogPath = `C:\ProgramData\gpu-turnstile\gpu-turnstile.log`
+
+var allSettingNames = []string{
+	"LISTEN_OLLAMA", "LISTEN_COMFY", "OLLAMA_URL", "COMFY_URL",
+	"WARM_MODEL", "UNLOAD_TIMEOUT", "JOB_TIMEOUT", "LLM_WAIT_TIMEOUT",
+	"LLM_BUSY_MODE", "LLM_BUSY_STATUS", "BUSY_RETRY_AFTER",
+	"LOGLEVEL", "LOG_FORMAT", "LOG_FILE",
+	"UNLOAD_POLL_INTERVAL", "HISTORY_POLL_INTERVAL", "PROBE_TIMEOUT",
+	"FREE_TIMEOUT", "WARM_TIMEOUT", "SHUTDOWN_TIMEOUT",
+	"BACKOFF_INITIAL", "BACKOFF_MAX", "PROMPT_CAPTURE_LIMIT",
+	"AUTO_UPDATE", "UPDATE_INTERVAL", "UPDATE_REPO", "UPDATE_ASSET",
+}
+
+func TestSampleEnv(t *testing.T) {
+	sample := SampleEnv("v0.1.7", sampleLogPath)
+
+	if !strings.HasPrefix(sample, "CFG_VER=v0.1.7\n") {
+		t.Errorf("first line does not carry CFG_VER: %q", strings.SplitN(sample, "\n", 2)[0])
+	}
+
+	// Every setting known to Load must appear.
+	for _, name := range allSettingNames {
+		if !strings.Contains(sample, name+"=") {
+			t.Errorf("sample is missing %s", name)
+		}
+	}
+
+	// The sample must parse cleanly; active values are CFG_VER, APP_VER
+	// and LOG_FILE.
+	values, err := ParseEnvFile(strings.NewReader(sample))
+	if err != nil {
+		t.Fatalf("sample does not parse: %v", err)
+	}
+	want := map[string]string{"CFG_VER": "v0.1.7", "APP_VER": "stable", "LOG_FILE": sampleLogPath}
+	if len(values) != len(want) {
+		t.Fatalf("active values = %v, want %v", values, want)
+	}
+	for k, v := range want {
+		if values[k] != v {
+			t.Errorf("%s = %q, want %q", k, values[k], v)
+		}
+	}
+
+	// Without a log path LOG_FILE stays commented out.
+	values, err = ParseEnvFile(strings.NewReader(SampleEnv("v0.1.7", "")))
+	if err != nil {
+		t.Fatalf("sample without log path does not parse: %v", err)
+	}
+	if len(values) != 2 || values["LOG_FILE"] != "" {
+		t.Fatalf("active values = %v, want only CFG_VER and APP_VER", values)
+	}
+}
+
+func TestSyncSample(t *testing.T) {
+	old := SampleEnv("v0.1.6", sampleLogPath)
+	// Simulate a setting that did not exist yet when the file was written.
+	old = strings.Replace(old, "#UPDATE_ASSET=gpu-turnstile.exe\n", "", 1)
+
+	out, changed := SyncSample(old, "v0.1.7", sampleLogPath)
+	if !changed {
+		t.Fatal("older installer file was not upgraded")
+	}
+	if !strings.Contains(out, "\nCFG_VER=v0.1.7\n") && !strings.HasPrefix(out, "CFG_VER=v0.1.7\n") {
+		t.Error("CFG_VER was not updated to the new version")
+	}
+	if !strings.Contains(out, "#UPDATE_ASSET=gpu-turnstile.exe") {
+		t.Error("missing setting was not appended")
+	}
+	if !strings.Contains(out, "LOG_FILE="+sampleLogPath) {
+		t.Error("existing active LOG_FILE was lost")
+	}
+	if !strings.Contains(out, "Added by gpu-turnstile v0.1.7") {
+		t.Error("appended section is not attributed")
+	}
+	if _, err := ParseEnvFile(strings.NewReader(out)); err != nil {
+		t.Fatalf("upgraded file does not parse: %v", err)
+	}
+
+	// A file written by the same or a newer version is left alone.
+	if _, changed := SyncSample(SampleEnv("v0.1.7", sampleLogPath), "v0.1.7", sampleLogPath); changed {
+		t.Error("same-version file was modified")
+	}
+	if _, changed := SyncSample(SampleEnv("v0.2.0", sampleLogPath), "v0.1.7", sampleLogPath); changed {
+		t.Error("newer-version file was modified")
+	}
+
+	// Files without CFG_VER are not installer-written; the installer
+	// replaces them, SyncSample leaves them alone.
+	user := "OLLAMA_URL=http://host:11434\n"
+	if out, changed := SyncSample(user, "v0.1.7", sampleLogPath); changed || out != user {
+		t.Error("file without CFG_VER was modified")
+	}
+
+	// A dev build never upgrades.
+	if _, changed := SyncSample(old, "dev", sampleLogPath); changed {
+		t.Error("dev build modified the file")
+	}
+}
+
+func TestSyncSampleAppendsMissingAppVer(t *testing.T) {
+	old := SampleEnv("v0.1.6", sampleLogPath)
+	old = strings.Replace(old, "# "+appVerComment+"\n", "", 1)
+	old = strings.Replace(old, "APP_VER=stable\n", "", 1)
+
+	out, changed := SyncSample(old, "v0.1.7", sampleLogPath)
+	if !changed {
+		t.Fatal("file without APP_VER was not upgraded")
+	}
+	values, err := ParseEnvFile(strings.NewReader(out))
+	if err != nil {
+		t.Fatalf("upgraded file does not parse: %v", err)
+	}
+	if values["APP_VER"] != "stable" {
+		t.Fatalf("APP_VER = %q, want appended default \"stable\"", values["APP_VER"])
+	}
+}
+
+func TestCompareVersions(t *testing.T) {
+	cases := []struct {
+		a, b string
+		want int
+	}{
+		{"v0.1.6", "v0.1.7", -1},
+		{"v0.1.7", "v0.1.7", 0},
+		{"v1.0.0", "v0.9.9", 1},
+		{"0.1.7", "v0.1.6", 1},
+		{"dev", "v0.1.7", -1},
+		{"v0.1.7", "dev", 1},
+		{"dev", "dev", 0},
+	}
+	for _, c := range cases {
+		if got := compareVersions(c.a, c.b); got != c.want {
+			t.Errorf("compareVersions(%q, %q) = %d, want %d", c.a, c.b, got, c.want)
+		}
+	}
+}

internal/service/envfile.go

@@ -0,0 +1,47 @@
+// Shared env-file handling for the installers (Windows and Linux).
+package service
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"gpu-turnstile/internal/config"
+)
+
+// syncEnvFile ensures the installed env file at path is a current
+// installer-written sample. A missing file is created; a file without a
+// CFG_VER line (hand-written or from before versioning) is invalid and
+// replaced by a fresh sample after a .bak backup; a file written by an
+// older version gets newly added settings appended via config.SyncSample.
+// logPath activates the LOG_FILE line (Windows); empty leaves it commented.
+func syncEnvFile(path, version, logPath string) error {
+	data, err := os.ReadFile(path)
+	switch {
+	case os.IsNotExist(err):
+		return writeEnvFile(path, config.SampleEnv(version, logPath))
+	case err != nil:
+		return fmt.Errorf("read %s: %w", path, err)
+	}
+	values, perr := config.ParseEnvFile(strings.NewReader(string(data)))
+	if perr == nil && values["CFG_VER"] != "" {
+		synced, changed := config.SyncSample(string(data), version, logPath)
+		if !changed {
+			return nil
+		}
+		return writeEnvFile(path, synced)
+	}
+	// No readable CFG_VER: the file is invalid — keep a backup and start
+	// from a fresh sample.
+	if err := os.WriteFile(path+".bak", data, 0o644); err != nil {
+		return fmt.Errorf("back up %s: %w", path, err)
+	}
+	return writeEnvFile(path, config.SampleEnv(version, logPath))
+}
+
+func writeEnvFile(path, content string) error {
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		return fmt.Errorf("write %s: %w", path, err)
+	}
+	return nil
+}

internal/service/service_linux.go

@@ -6,6 +6,7 @@
 package service
 
 import (
+	"bytes"
 	"context"
 	"fmt"
 	"io"
@@ -126,12 +127,18 @@ func copyFile(src, dst string, mode os.FileMode) error {
 // copyBin=false the current executable location and config path are
 // registered as-is instead. Needs root.
 //
+// Re-running install converges an existing unit instead of failing: it is
+// stopped first if active, the installed binary is replaced only when the
+// content differs, the unit file is rewritten (followed by daemon-reload)
+// only when it changed, and the service is started again only if it was
+// active before.
+//
 // The binary lives in the StateDirectory rather than /usr/local/sbin on
 // purpose: replacing a running binary needs write access to its
 // *directory*, and granting the sandboxed service user write access to a
 // shared system directory would let a compromised service overwrite other
 // binaries. /var/lib/gpu-turnstile is exclusively ours.
-func Install(configPath string, copyBin bool) error {
+func Install(configPath string, copyBin bool, version string) error {
 	exe, err := os.Executable()
 	if err != nil {
 		return err
@@ -139,6 +146,16 @@ func Install(configPath string, copyBin bool) error {
 	if abs, absErr := filepath.Abs(exe); absErr == nil {
 		exe = abs
 	}
+	unit := Name + ".service"
+	_, statErr := os.Stat(unitPath)
+	fresh := os.IsNotExist(statErr)
+	wasRunning := exec.Command("systemctl", "is-active", "--quiet", unit).Run() == nil
+	if wasRunning {
+		if out, err := exec.Command("systemctl", "stop", unit).CombinedOutput(); err != nil {
+			return fmt.Errorf("systemctl stop (run as root): %w (%s)", err, out)
+		}
+	}
+
 	cfg := etcConfig
 	if copyBin {
 		if err := os.MkdirAll(stateDir, 0o755); err != nil {
@@ -146,32 +163,73 @@ func Install(configPath string, copyBin bool) error {
 		}
 		installedExe := filepath.Join(stateDir, Name)
 		if exe != installedExe {
+			if same, _ := sameFileContent(exe, installedExe); !same {
 				if err := copyFile(exe, installedExe, 0o755); err != nil {
 					return fmt.Errorf("install binary to %s: %w", installedExe, err)
 				}
 			}
+		}
 		exe = installedExe
 		if _, err := os.Stat(etcConfig); os.IsNotExist(err) && configPath != "" {
-			// Missing config is not fatal: the service fails fast with a
-			// clear "no consumer URL" error until the user writes one.
 			copyFile(configPath, etcConfig, 0o644) //nolint:errcheck // best effort
 		}
+		// Missing configs get a fully commented sample (LOG_FILE stays
+		// commented — stderr goes to the journal on Linux);
+		// installer-written ones from older versions get new settings
+		// appended; anything without CFG_VER is invalid and gets replaced
+		// (backup kept as .bak).
+		if err := syncEnvFile(etcConfig, version, ""); err != nil {
+			return err
+		}
 	} else if configPath != "" {
 		if abs, absErr := filepath.Abs(configPath); absErr == nil {
 			cfg = abs
 		}
 	}
-	if err := os.WriteFile(unitPath, []byte(renderUnit(exe, cfg)), 0o644); err != nil {
+	rendered := renderUnit(exe, cfg)
+	if old, _ := os.ReadFile(unitPath); string(old) != rendered {
+		if err := os.WriteFile(unitPath, []byte(rendered), 0o644); err != nil {
 			return fmt.Errorf("write %s (run as root): %w", unitPath, err)
 		}
 		if out, err := exec.Command("systemctl", "daemon-reload").CombinedOutput(); err != nil {
 			return fmt.Errorf("systemctl daemon-reload: %w (%s)", err, out)
 		}
-	if out, err := exec.Command("systemctl", "enable", "--now", Name+".service").CombinedOutput(); err != nil {
+	}
+	if fresh {
+		if out, err := exec.Command("systemctl", "enable", "--now", unit).CombinedOutput(); err != nil {
 			return fmt.Errorf("systemctl enable --now: %w (%s)", err, out)
 		}
 		return nil
 	}
+	if exec.Command("systemctl", "is-enabled", "--quiet", unit).Run() != nil {
+		if out, err := exec.Command("systemctl", "enable", unit).CombinedOutput(); err != nil {
+			return fmt.Errorf("systemctl enable: %w (%s)", err, out)
+		}
+	}
+	if wasRunning {
+		if out, err := exec.Command("systemctl", "start", unit).CombinedOutput(); err != nil {
+			return fmt.Errorf("systemctl start: %w (%s)", err, out)
+		}
+	}
+	return nil
+}
+
+// sameFileContent reports whether two files hold identical bytes. A missing
+// destination is simply "different".
+func sameFileContent(a, b string) (bool, error) {
+	ba, err := os.ReadFile(a)
+	if err != nil {
+		return false, err
+	}
+	bb, err := os.ReadFile(b)
+	if os.IsNotExist(err) {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	}
+	return bytes.Equal(ba, bb), nil
+}
 
 // Remove stops and disables the service and deletes the unit file and the
 // installed binary. The config file in /etc is left in place (user data).

internal/service/service_other.go

@@ -29,7 +29,7 @@ func Run(run func(ctx context.Context) error) error {
 }
 
 // Install is unsupported on non-Windows, non-Linux platforms.
-func Install(string, bool) error { return errUnsupported }
+func Install(string, bool, string) error { return errUnsupported }
 
 // Remove is unsupported on non-Windows, non-Linux platforms.
 func Remove() error { return errUnsupported }

internal/service/service_windows.go

@@ -8,6 +8,7 @@
 package service
 
 import (
+	"bytes"
 	"context"
 	"errors"
 	"fmt"
@@ -109,7 +110,13 @@ func (h *handler) Execute(_ []string, requests <-chan svc.ChangeRequest, status
 // config file if it lives elsewhere. The grants must come after
 // CreateService: the virtual account's SID only exists once the service is
 // registered.
-func Install(configPath string, copyBin bool) error {
+//
+// Re-running install on an existing service converges instead of failing:
+// the service is stopped first if running (so the binary can be replaced),
+// the installed binary is refreshed only when the content differs, the
+// registration is updated only where it drifted, and the service is
+// started again only if it was running before.
+func Install(configPath string, copyBin bool, version string) error {
 	exe, err := os.Executable()
 	if err != nil {
 		return err
@@ -123,33 +130,63 @@ func Install(configPath string, copyBin bool) error {
 		}
 	}
 
-	installDir, _ := installDirs()
-	if copyBin && !strings.EqualFold(filepath.Dir(exe), installDir) {
-		if err := os.MkdirAll(installDir, 0o755); err != nil {
-			return fmt.Errorf("create %s: %w", installDir, err)
-		}
-		installedExe := filepath.Join(installDir, "gpu-turnstile.exe")
-		if err := copyFile(exe, installedExe); err != nil {
-			return fmt.Errorf("copy binary to %s: %w", installedExe, err)
-		}
-		exe = installedExe
-		targetCfg := filepath.Join(installDir, "gpu-turnstile.env")
-		if configPath != "" && !strings.EqualFold(configPath, targetCfg) {
-			if _, statErr := os.Stat(targetCfg); os.IsNotExist(statErr) {
-				copyFile(configPath, targetCfg) //nolint:errcheck // best effort
-			}
-			configPath = targetCfg
-		}
-	}
-
 	m, err := mgr.Connect()
 	if err != nil {
 		return fmt.Errorf("connect to service manager (run as administrator): %w", err)
 	}
 	defer m.Disconnect()
 
+	// An existing service is converged, not an error. Stop it first so the
+	// binary copy can be replaced, and remember whether to start it again.
+	var s *mgr.Service
+	wasRunning := false
+	if existing, openErr := m.OpenService(Name); openErr == nil {
+		s = existing
+		defer s.Close()
+		if st, qErr := s.Query(); qErr == nil &&
+			(st.State == svc.Running || st.State == svc.StartPending) {
+			wasRunning = true
+			if err := stopAndWait(s); err != nil {
+				return err
+			}
+		}
+	}
+
+	installDir, dataDir := installDirs()
+	if copyBin {
+		targetCfg := filepath.Join(installDir, "gpu-turnstile.env")
+		if !strings.EqualFold(filepath.Dir(exe), installDir) {
+			if err := os.MkdirAll(installDir, 0o755); err != nil {
+				return fmt.Errorf("create %s: %w", installDir, err)
+			}
+			installedExe := filepath.Join(installDir, "gpu-turnstile.exe")
+			if same, _ := sameFileContent(exe, installedExe); !same {
+				if err := copyFile(exe, installedExe); err != nil {
+					return fmt.Errorf("copy binary to %s: %w", installedExe, err)
+				}
+			}
+			exe = installedExe
+			if configPath != "" && !strings.EqualFold(configPath, targetCfg) {
+				if _, statErr := os.Stat(targetCfg); os.IsNotExist(statErr) {
+					copyFile(configPath, targetCfg) //nolint:errcheck // best effort
+				}
+			}
+		}
+		// A service has no console: without LOG_FILE the output vanishes, so
+		// the sample pre-wires it to ProgramData. Missing configs get a
+		// fresh sample; installer-written ones from older versions get new
+		// settings appended; anything without CFG_VER is invalid and gets
+		// replaced (backup kept as .bak).
+		logPath := filepath.Join(dataDir, "gpu-turnstile.log")
+		if err := syncEnvFile(targetCfg, version, logPath); err != nil {
+			return err
+		}
+		configPath = targetCfg
+	}
 	binPath := fmt.Sprintf(`"%s" -config "%s"`, exe, configPath)
-	s, err := m.CreateService(Name, binPath, mgr.Config{
+
+	if s == nil {
+		s, err = m.CreateService(Name, binPath, mgr.Config{
 			StartType:        mgr.StartAutomatic,
 			DisplayName:      "gpu-turnstile",
 			Description:      "GPU arbitration proxy for Ollama and ComfyUI",
@@ -160,14 +197,10 @@ func Install(configPath string, copyBin bool) error {
 		}
 		defer s.Close()
 
-	restart := mgr.RecoveryAction{Type: mgr.ServiceRestart, Delay: 5 * time.Second}
-	if err := s.SetRecoveryActions([]mgr.RecoveryAction{restart, restart, restart}, 24*60*60); err != nil {
-		return fmt.Errorf("set recovery actions: %w", err)
+		if err := ensureRecovery(s); err != nil {
+			s.Delete() // roll back so a retry starts clean
+			return err
 		}
-	if err := s.SetRecoveryActionsOnNonCrashFailures(true); err != nil {
-		return fmt.Errorf("set failure actions flag: %w", err)
-	}
-
 		if err := grantAll(exe, configPath); err != nil {
 			s.Delete() // roll back so a retry starts clean
 			return err
@@ -179,6 +212,109 @@ func Install(configPath string, copyBin bool) error {
 		return nil
 	}
 
+	// Existing service: update the registration only where it drifted.
+	cur, err := s.Config()
+	if err != nil {
+		return fmt.Errorf("query service config: %w", err)
+	}
+	const displayName = "gpu-turnstile"
+	const description = "GPU arbitration proxy for Ollama and ComfyUI"
+	if cur.BinaryPathName != binPath ||
+		cur.StartType != mgr.StartAutomatic ||
+		cur.ServiceStartName != virtualAccount ||
+		cur.DisplayName != displayName ||
+		cur.Description != description {
+		upd := cur
+		upd.BinaryPathName = binPath
+		upd.StartType = mgr.StartAutomatic
+		upd.ServiceStartName = virtualAccount
+		upd.DisplayName = displayName
+		upd.Description = description
+		if err := s.UpdateConfig(upd); err != nil {
+			return fmt.Errorf("update service config: %w", err)
+		}
+	}
+	if err := ensureRecovery(s); err != nil {
+		return err
+	}
+	// Idempotent: re-assert the virtual account's ACLs (granting an
+	// existing ACE is a no-op).
+	if err := grantAll(exe, configPath); err != nil {
+		return err
+	}
+	if wasRunning {
+		if err := s.Start(); err != nil {
+			return fmt.Errorf("start service: %w", err)
+		}
+	}
+	return nil
+}
+
+// ensureRecovery makes sure the service restarts 5s after a failure — the
+// mechanism that also brings up a staged update. The current actions are
+// queried first so an up-to-date service is left untouched.
+func ensureRecovery(s *mgr.Service) error {
+	want := mgr.RecoveryAction{Type: mgr.ServiceRestart, Delay: 5 * time.Second}
+	actions, err := s.RecoveryActions()
+	onFailure, flagErr := s.RecoveryActionsOnNonCrashFailures()
+	if err == nil && flagErr == nil && onFailure && len(actions) == 3 {
+		ok := true
+		for _, a := range actions {
+			if a.Type != want.Type || a.Delay != want.Delay {
+				ok = false
+			}
+		}
+		if ok {
+			return nil
+		}
+	}
+	if err := s.SetRecoveryActions([]mgr.RecoveryAction{want, want, want}, 24*60*60); err != nil {
+		return fmt.Errorf("set recovery actions: %w", err)
+	}
+	if err := s.SetRecoveryActionsOnNonCrashFailures(true); err != nil {
+		return fmt.Errorf("set failure actions flag: %w", err)
+	}
+	return nil
+}
+
+// stopAndWait stops the service and waits up to 30s for the stopped state.
+func stopAndWait(s *mgr.Service) error {
+	if _, err := s.Control(svc.Stop); err != nil {
+		return fmt.Errorf("stop service: %w", err)
+	}
+	deadline := time.Now().Add(30 * time.Second)
+	for {
+		st, err := s.Query()
+		if err != nil {
+			return fmt.Errorf("query service: %w", err)
+		}
+		if st.State == svc.Stopped {
+			return nil
+		}
+		if time.Now().After(deadline) {
+			return fmt.Errorf("service did not stop within 30s")
+		}
+		time.Sleep(300 * time.Millisecond)
+	}
+}
+
+// sameFileContent reports whether two files hold identical bytes. A missing
+// destination is simply "different".
+func sameFileContent(a, b string) (bool, error) {
+	ba, err := os.ReadFile(a)
+	if err != nil {
+		return false, err
+	}
+	bb, err := os.ReadFile(b)
+	if os.IsNotExist(err) {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	}
+	return bytes.Equal(ba, bb), nil
+}
+
 // copyFile copies src to dst (0755 on the new file).
 func copyFile(src, dst string) error {
 	in, err := os.Open(src)
@@ -374,22 +510,8 @@ func RestartIfRunning() (bool, error) {
 	if st.State != svc.Running && st.State != svc.StartPending {
 		return false, nil
 	}
-	if _, err := s.Control(svc.Stop); err != nil {
-		return false, fmt.Errorf("stop service: %w", err)
-	}
-	deadline := time.Now().Add(30 * time.Second)
-	for {
-		st, err = s.Query()
-		if err != nil {
-			return false, fmt.Errorf("query service: %w", err)
-		}
-		if st.State == svc.Stopped {
-			break
-		}
-		if time.Now().After(deadline) {
-			return false, fmt.Errorf("service did not stop within 30s")
-		}
-		time.Sleep(300 * time.Millisecond)
+	if err := stopAndWait(s); err != nil {
+		return false, err
 	}
 	if err := s.Start(); err != nil {
 		return false, fmt.Errorf("start service: %w", err)

internal/update/update.go

@@ -26,11 +26,15 @@ import (
 // maxAssetSize bounds release asset downloads.
 const maxAssetSize = 512 << 20
 
-// Updater checks one Gitea repository for newer releases.
+// Updater checks one Gitea repository for releases.
 type Updater struct {
 	Repo    string // e.g. https://git.rambossek.at/PUBLIC/gpu-turnstile
 	Asset   string // e.g. gpu-turnstile.exe
-	Version string // current version, e.g. v0.1.2 ("dev" disables updates)
+	Version string // current binary version, e.g. v0.1.2 ("dev" cannot be compared)
+	// Desired is the APP_VER policy: "dev" disables updates, "stable" (or
+	// empty) tracks the latest release, anything else is an exact vX.Y.Z
+	// release tag to pin — staging it even when that means a downgrade.
+	Desired string
 	Log     *slog.Logger
 	Client  *http.Client
 }
@@ -167,15 +171,20 @@ func CleanupOld(exePath string) {
 	os.Remove(exePath + ".new")
 }
 
-// Check performs a single update check. staged is true when a newer,
+// Check performs a single update check. staged is true when a
 // signature-verified binary has been swapped into place at exePath; the
 // caller should then restart the process. A nil error with staged=false
-// means "no action" (up to date, disabled, or dev build); a non-nil error
-// means the check failed and the running binary is untouched.
+// means "no action" (up to date, APP_VER=dev, or no embedded public key);
+// a non-nil error means the check failed and the running binary is
+// untouched.
 func (u *Updater) Check(ctx context.Context, exePath string) (staged bool, err error) {
 	log := u.logger()
-	if u.Version == "" || u.Version == "dev" {
-		log.Debug("auto-update: dev build, skipping")
+	desired := u.Desired
+	if desired == "" {
+		desired = "stable"
+	}
+	if desired == "dev" {
+		log.Debug("auto-update: APP_VER=dev, skipping")
 		return false, nil
 	}
 	if publicKeyPEM == "" {
@@ -187,14 +196,29 @@ func (u *Updater) Check(ctx context.Context, exePath string) (staged bool, err e
 		return false, err
 	}
 
-	body, err := u.get(ctx, api+"/releases/latest")
+	pinned := desired != "stable"
+	endpoint := api + "/releases/latest"
+	if pinned {
+		endpoint = api + "/releases/tags/" + desired
+	}
+	body, err := u.get(ctx, endpoint)
 	if err != nil {
-		return false, fmt.Errorf("fetch latest release: %w", err)
+		return false, fmt.Errorf("fetch release: %w", err)
 	}
 	var rel release
 	if err := json.Unmarshal(body, &rel); err != nil {
 		return false, fmt.Errorf("parse release: %w", err)
 	}
+	if pinned {
+		// Pin mode: any difference from the target tag means stage it —
+		// including downgrades and replacing a dev binary.
+		if u.Version == rel.TagName {
+			log.Debug("auto-update: already on pinned version", "version", u.Version)
+			return false, nil
+		}
+	} else if u.Version != "" && u.Version != "dev" {
+		// Stable mode: only strictly newer releases count; a dev binary
+		// cannot be compared and is always replaced by the latest release.
 		newer, err := newerVersion(u.Version, rel.TagName)
 		if err != nil {
 			return false, err
@@ -203,6 +227,7 @@ func (u *Updater) Check(ctx context.Context, exePath string) (staged bool, err e
 			log.Debug("auto-update: up to date", "version", u.Version, "latest", rel.TagName)
 			return false, nil
 		}
+	}
 
 	urls := make(map[string]string, len(rel.Assets))
 	for _, a := range rel.Assets {

internal/update/update_test.go

@@ -43,7 +43,7 @@ func newFakeGitea(t *testing.T, tag string, assetContent []byte) *fakeGitea {
 	sign := func() []byte { return ed25519.Sign(priv, f.asset) }
 
 	mux := http.NewServeMux()
-	mux.HandleFunc("/api/v1/repos/o/r/releases/latest", func(w http.ResponseWriter, r *http.Request) {
+	serveRelease := func(w http.ResponseWriter, r *http.Request) {
 		assets := []map[string]string{
 			{"name": "gpu-turnstile.exe", "browser_download_url": f.srv.URL + "/dl/exe"},
 			{"name": "gpu-turnstile.exe.sha256", "browser_download_url": f.srv.URL + "/dl/sha"},
@@ -52,7 +52,9 @@ func newFakeGitea(t *testing.T, tag string, assetContent []byte) *fakeGitea {
 			assets = append(assets, map[string]string{"name": "gpu-turnstile.exe.sig", "browser_download_url": f.srv.URL + "/dl/sig"})
 		}
 		json.NewEncoder(w).Encode(map[string]any{"tag_name": f.tag, "assets": assets})
-	})
+	}
+	mux.HandleFunc("/api/v1/repos/o/r/releases/latest", serveRelease)
+	mux.HandleFunc("/api/v1/repos/o/r/releases/tags/"+f.tag, serveRelease)
 	mux.HandleFunc("/dl/exe", func(w http.ResponseWriter, r *http.Request) { w.Write(f.asset) })
 	mux.HandleFunc("/dl/sig", func(w http.ResponseWriter, r *http.Request) {
 		sig := sign()
@@ -73,6 +75,12 @@ func (f *fakeGitea) updater(version string) *Updater {
 	return &Updater{Repo: f.srv.URL + "/o/r", Asset: "gpu-turnstile.exe", Version: version}
 }
 
+func (f *fakeGitea) updaterDesired(version, desired string) *Updater {
+	u := f.updater(version)
+	u.Desired = desired
+	return u
+}
+
 func fakeExe(t *testing.T) string {
 	t.Helper()
 	exe := filepath.Join(t.TempDir(), "gpu-turnstile.exe")
@@ -153,12 +161,61 @@ func TestCheckSkipsWithoutPublicKey(t *testing.T) {
 	}
 }
 
-func TestCheckSkipsDevBuild(t *testing.T) {
+func TestCheckDevBuildGetsStable(t *testing.T) {
+	// A dev binary cannot be compared; APP_VER=stable replaces it with the
+	// latest release.
 	f := newFakeGitea(t, "v9.9.9", []byte("new-binary"))
 	withPublicKey(t, f.pubPEM)
-	staged, err := f.updater("dev").Check(context.Background(), fakeExe(t))
+	exe := fakeExe(t)
+	staged, err := f.updater("dev").Check(context.Background(), exe)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !staged {
+		t.Fatal("expected dev binary to be replaced by the latest release")
+	}
+	content, _ := os.ReadFile(exe)
+	if string(content) != "new-binary" {
+		t.Fatalf("exe content = %q", content)
+	}
+}
+
+func TestCheckDesiredDevDisables(t *testing.T) {
+	f := newFakeGitea(t, "v9.9.9", []byte("new-binary"))
+	withPublicKey(t, f.pubPEM)
+	for _, version := range []string{"dev", "v0.1.2"} {
+		staged, err := f.updaterDesired(version, "dev").Check(context.Background(), fakeExe(t))
 		if err != nil || staged {
-		t.Fatalf("staged=%v err=%v, want no action for dev build", staged, err)
+			t.Fatalf("version %s: staged=%v err=%v, want no action with APP_VER=dev", version, staged, err)
+		}
+	}
+}
+
+func TestCheckPinned(t *testing.T) {
+	// Pin mode stages the exact tag — up or down — and skips when the
+	// binary already matches.
+	for _, version := range []string{"v0.1.2", "v9.9.9", "dev"} {
+		f := newFakeGitea(t, "v0.5.0", []byte("pinned-binary"))
+		withPublicKey(t, f.pubPEM)
+		exe := fakeExe(t)
+		staged, err := f.updaterDesired(version, "v0.5.0").Check(context.Background(), exe)
+		if err != nil {
+			t.Fatalf("version %s: %v", version, err)
+		}
+		if !staged {
+			t.Fatalf("version %s: expected pinned v0.5.0 to be staged", version)
+		}
+		content, _ := os.ReadFile(exe)
+		if string(content) != "pinned-binary" {
+			t.Fatalf("version %s: exe content = %q", version, content)
+		}
+	}
+
+	f := newFakeGitea(t, "v0.5.0", []byte("pinned-binary"))
+	withPublicKey(t, f.pubPEM)
+	staged, err := f.updaterDesired("v0.5.0", "v0.5.0").Check(context.Background(), fakeExe(t))
+	if err != nil || staged {
+		t.Fatalf("staged=%v err=%v, want no action when already on the pinned version", staged, err)
 	}
 }