CFG_VER/APP_VER in the env file: invalid configs replaced, updates follow APP_VER (dev/stable/pin)

internal/config/config.go

@@ -38,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).
@@ -76,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,
@@ -205,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 == "" {

internal/config/config_test.go

@@ -45,6 +45,35 @@ func TestLoadRequiresConsumer(t *testing.T) {
 	}
 }
 
+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) {
 	input := `# comment
 OLLAMA_URL=http://host:11435

internal/config/sample.go

@@ -15,12 +15,12 @@ type sampleEntry struct {
 	active  bool // rendered uncommented
 }
 
-// versionMarker prefixes the first line of an installer-written env file so
-// later installs can tell which version wrote it.
-const versionMarker = "# gpu-turnstile version: "
+// 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},
@@ -55,15 +55,19 @@ func sampleEntries(logFile string) []sampleEntry {
 
 // SampleEnv renders a sample .env file covering every setting, each with a
 // comment line. Everything is commented out — so all defaults apply —
-// except LOG_FILE when logFile is non-empty: a Windows service has no
-// console, so the installer pre-wires file logging there. The first line
-// carries the writing version so later installs can upgrade the file.
+// 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
-	b.WriteString(versionMarker + version + "\n")
+	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)
 	}
@@ -79,22 +83,21 @@ func writeEntry(b *strings.Builder, e sampleEntry) {
 	}
 }
 
-// SyncSample upgrades an installer-written env file: when its version
-// marker 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
-// the marker is updated to version. Files without the marker (hand-written
-// configs) and up-to-date files are returned unchanged; changed reports
-// whether the returned content differs. A "dev" version never upgrades.
+// 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
 	}
-	first, _, _ := strings.Cut(data, "\n")
-	marker, ok := strings.CutPrefix(first, versionMarker)
-	if !ok {
-		return data, false // not written by the installer
+	values, err := ParseEnvFile(strings.NewReader(data))
+	if err != nil || values["CFG_VER"] == "" {
+		return data, false // not installer-written; the caller decides
 	}
-	if compareVersions(strings.TrimSpace(marker), version) >= 0 {
+	if compareVersions(values["CFG_VER"], version) >= 0 {
 		return data, false // same or newer
 	}
 
@@ -106,18 +109,30 @@ func SyncSample(data, version, logFile string) (string, bool) {
 		}
 	}
 
+	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
-	b.WriteString(versionMarker + version + "\n")
-	rest := strings.TrimPrefix(data, first)
-	b.WriteString(strings.TrimRight(rest, "\n"))
-	b.WriteString("\n")
+	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()
+	out += b.String()
 	return out, out != data
 }
 

internal/config/sample_test.go

@@ -21,8 +21,8 @@ var allSettingNames = []string{
 func TestSampleEnv(t *testing.T) {
 	sample := SampleEnv("v0.1.7", sampleLogPath)
 
-	if !strings.HasPrefix(sample, "# gpu-turnstile version: v0.1.7\n") {
-		t.Errorf("first line does not carry the version marker: %q", strings.SplitN(sample, "\n", 2)[0])
+	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.
@@ -32,22 +32,29 @@ func TestSampleEnv(t *testing.T) {
 		}
 	}
 
-	// The sample must parse cleanly, and only LOG_FILE is active.
+	// 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)
 	}
-	if len(values) != 1 || values["LOG_FILE"] != sampleLogPath {
-		t.Fatalf("active values = %v, want only LOG_FILE", values)
+	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 everything is commented out.
+	// 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) != 0 {
-		t.Fatalf("active values = %v, want none", values)
+	if len(values) != 2 || values["LOG_FILE"] != "" {
+		t.Fatalf("active values = %v, want only CFG_VER and APP_VER", values)
 	}
 }
 
@@ -60,8 +67,8 @@ func TestSyncSample(t *testing.T) {
 	if !changed {
 		t.Fatal("older installer file was not upgraded")
 	}
-	if !strings.HasPrefix(out, "# gpu-turnstile version: v0.1.7\n") {
-		t.Error("marker was not updated to the new version")
+	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")
@@ -84,10 +91,11 @@ func TestSyncSample(t *testing.T) {
 		t.Error("newer-version file was modified")
 	}
 
-	// Hand-written configs (no marker) are never touched.
+	// 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("hand-written config was modified")
+		t.Error("file without CFG_VER was modified")
 	}
 
 	// A dev build never upgrades.
@@ -96,6 +104,24 @@ func TestSyncSample(t *testing.T) {
 	}
 }
 
+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

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

@@ -15,8 +15,6 @@ import (
 	"os/signal"
 	"path/filepath"
 	"syscall"
-
-	"gpu-turnstile/internal/config"
 )
 
 // Name matches the Windows service name; the systemd unit is Name + ".service".
@@ -172,26 +170,16 @@ func Install(configPath string, copyBin bool, version string) error {
 			}
 		}
 		exe = installedExe
-		data, readErr := os.ReadFile(etcConfig)
-		switch {
-		case os.IsNotExist(readErr):
-			if configPath != "" {
-				copyFile(configPath, etcConfig, 0o644) //nolint:errcheck // best effort
-			} else if err := os.WriteFile(etcConfig, []byte(config.SampleEnv(version, "")), 0o644); err != nil {
-				// Fully commented sample covering every setting; LOG_FILE
-				// stays commented — stderr goes to the journal on Linux.
-				return fmt.Errorf("write %s: %w", etcConfig, err)
-			}
-		case readErr != nil:
-			return fmt.Errorf("read %s: %w", etcConfig, readErr)
-		default:
-			// An installer-written config from an older version gets any
-			// new settings appended; hand-written files stay untouched.
-			if synced, changed := config.SyncSample(string(data), version, ""); changed {
-				if err := os.WriteFile(etcConfig, []byte(synced), 0o644); err != nil {
-					return fmt.Errorf("write %s: %w", etcConfig, err)
-				}
-			}
+		if _, err := os.Stat(etcConfig); os.IsNotExist(err) && configPath != "" {
+			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 {

internal/service/service_windows.go

@@ -172,28 +172,14 @@ func Install(configPath string, copyBin bool, version string) error {
 				}
 			}
 		}
-		// A service has no console: without LOG_FILE the output vanishes.
-		// With no config at all, install a fully commented sample covering
-		// every setting (only LOG_FILE active). An existing installer-written
-		// config from an older version gets any new settings appended; any
-		// other existing config just gets a LOG_FILE line if it has none.
+		// 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")
-		data, readErr := os.ReadFile(targetCfg)
-		switch {
-		case os.IsNotExist(readErr):
-			if err := os.WriteFile(targetCfg, []byte(config.SampleEnv(version, logPath)), 0o644); err != nil {
-				return fmt.Errorf("write %s: %w", targetCfg, err)
-			}
-		case readErr != nil:
-			return fmt.Errorf("read %s: %w", targetCfg, readErr)
-		default:
-			if synced, changed := config.SyncSample(string(data), version, logPath); changed {
-				if err := os.WriteFile(targetCfg, []byte(synced), 0o644); err != nil {
-					return fmt.Errorf("write %s: %w", targetCfg, err)
-				}
-			} else if err := ensureLogFile(targetCfg, logPath); err != nil {
-				return err
-			}
+		if err := syncEnvFile(targetCfg, version, logPath); err != nil {
+			return err
 		}
 		configPath = targetCfg
 	}
@@ -329,30 +315,6 @@ func sameFileContent(a, b string) (bool, error) {
 	return bytes.Equal(ba, bb), nil
 }
 
-// ensureLogFile makes sure the env file at path sets LOG_FILE, creating
-// the file or appending the line as needed. An existing LOG_FILE= line
-// (even an empty one) is respected and left untouched.
-func ensureLogFile(path, logPath string) error {
-	data, err := os.ReadFile(path)
-	if err != nil && !os.IsNotExist(err) {
-		return fmt.Errorf("read %s: %w", path, err)
-	}
-	for _, line := range strings.Split(string(data), "\n") {
-		if strings.HasPrefix(strings.TrimSpace(line), "LOG_FILE=") {
-			return nil
-		}
-	}
-	s := string(data)
-	if s != "" && !strings.HasSuffix(s, "\n") {
-		s += "\n"
-	}
-	s += "LOG_FILE=" + logPath + "\n"
-	if err := os.WriteFile(path, []byte(s), 0o644); err != nil {
-		return fmt.Errorf("write %s: %w", path, err)
-	}
-	return nil
-}
-
 // copyFile copies src to dst (0755 on the new file).
 func copyFile(src, dst string) error {
 	in, err := os.Open(src)

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,21 +196,37 @@ 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)
 	}
-	newer, err := newerVersion(u.Version, rel.TagName)
-	if err != nil {
-		return false, err
-	}
-	if !newer {
-		log.Debug("auto-update: up to date", "version", u.Version, "latest", rel.TagName)
-		return false, nil
+	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
+		}
+		if !newer {
+			log.Debug("auto-update: up to date", "version", u.Version, "latest", rel.TagName)
+			return false, nil
+		}
 	}
 
 	urls := make(map[string]string, len(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("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 for dev build", staged, err)
+		t.Fatalf("staged=%v err=%v, want no action when already on the pinned version", staged, err)
 	}
 }