sensorium-mcp 2.17.27 → 3.0.0

package/supervisor/secrets_test.go

@@ -0,0 +1,119 @@
+package main
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/zalando/go-keyring"
+)
+
+func TestResolveSecretWithKeyring_EnvWins(t *testing.T) {
+	t.Setenv("MCP_HTTP_SECRET", "env-secret")
+
+	orig := keyringGet
+	keyringGet = func(service, user string) (string, error) {
+		return "keyring-secret", nil
+	}
+	t.Cleanup(func() { keyringGet = orig })
+
+	got := resolveSecretWithKeyring("MCP_HTTP_SECRET", "sensorium-supervisor")
+	if got != "env-secret" {
+		t.Fatalf("resolveSecretWithKeyring() = %q, want %q", got, "env-secret")
+	}
+}
+
+func TestResolveSecretWithKeyring_FallbackToKeyring(t *testing.T) {
+	t.Setenv("MCP_HTTP_SECRET", "")
+
+	orig := keyringGet
+	keyringGet = func(service, user string) (string, error) {
+		if service != "sensorium-supervisor" {
+			t.Fatalf("service = %q, want %q", service, "sensorium-supervisor")
+		}
+		if user != "MCP_HTTP_SECRET" {
+			t.Fatalf("user = %q, want %q", user, "MCP_HTTP_SECRET")
+		}
+		return "keyring-secret", nil
+	}
+	t.Cleanup(func() { keyringGet = orig })
+
+	got := resolveSecretWithKeyring("MCP_HTTP_SECRET", "sensorium-supervisor")
+	if got != "keyring-secret" {
+		t.Fatalf("resolveSecretWithKeyring() = %q, want %q", got, "keyring-secret")
+	}
+}
+
+func TestResolveSecretWithKeyring_NotFound(t *testing.T) {
+	t.Setenv("MCP_HTTP_SECRET", "")
+
+	orig := keyringGet
+	keyringGet = func(service, user string) (string, error) {
+		return "", keyring.ErrNotFound
+	}
+	t.Cleanup(func() { keyringGet = orig })
+
+	got := resolveSecretWithKeyring("MCP_HTTP_SECRET", "sensorium-supervisor")
+	if got != "" {
+		t.Fatalf("resolveSecretWithKeyring() = %q, want empty", got)
+	}
+}
+
+func TestResolveSecretWithKeyring_OtherError(t *testing.T) {
+	t.Setenv("MCP_HTTP_SECRET", "")
+
+	orig := keyringGet
+	keyringGet = func(service, user string) (string, error) {
+		return "", errors.New("keyring backend unavailable")
+	}
+	t.Cleanup(func() { keyringGet = orig })
+
+	got := resolveSecretWithKeyring("MCP_HTTP_SECRET", "sensorium-supervisor")
+	if got != "" {
+		t.Fatalf("resolveSecretWithKeyring() = %q, want empty", got)
+	}
+}
+
+func TestResolveIntWithKeyring_EnvWins(t *testing.T) {
+	t.Setenv("MCP_HTTP_PORT", "3847")
+
+	orig := keyringGet
+	keyringGet = func(service, user string) (string, error) {
+		return "9999", nil
+	}
+	t.Cleanup(func() { keyringGet = orig })
+
+	got := resolveIntWithKeyring("MCP_HTTP_PORT", "sensorium-supervisor", 0)
+	if got != 3847 {
+		t.Fatalf("resolveIntWithKeyring() = %d, want %d", got, 3847)
+	}
+}
+
+func TestResolveIntWithKeyring_FallbackToKeyring(t *testing.T) {
+	t.Setenv("MCP_HTTP_PORT", "")
+
+	orig := keyringGet
+	keyringGet = func(service, user string) (string, error) {
+		return "5001", nil
+	}
+	t.Cleanup(func() { keyringGet = orig })
+
+	got := resolveIntWithKeyring("MCP_HTTP_PORT", "sensorium-supervisor", 0)
+	if got != 5001 {
+		t.Fatalf("resolveIntWithKeyring() = %d, want %d", got, 5001)
+	}
+}
+
+func TestResolveIntWithKeyring_InvalidFallback(t *testing.T) {
+	t.Setenv("MCP_HTTP_PORT", "")
+
+	orig := keyringGet
+	keyringGet = func(service, user string) (string, error) {
+		return "not-a-number", nil
+	}
+	t.Cleanup(func() { keyringGet = orig })
+
+	got := resolveIntWithKeyring("MCP_HTTP_PORT", "sensorium-supervisor", 3847)
+	if got != 3847 {
+		t.Fatalf("resolveIntWithKeyring() = %d, want fallback %d", got, 3847)
+	}
+}

package/supervisor/self_update.go

@@ -0,0 +1,282 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+)
+
+const supervisorRollbackAttemptedMarker = "rollback_attempted=true"
+const supervisorWindowsServiceName = "SensoriumSupervisor"
+
+// applyPendingSupervisorUpdate applies a downloaded supervisor binary before the
+// rest of the process starts. On Windows, a detached helper performs the swap
+// after this bootstrap process exits because a running .exe cannot overwrite
+// itself in place.
+func applyPendingSupervisorUpdate(cfg Config, log *Logger) (bool, error) {
+	recordPendingSupervisorApplyFailureIfPresent(cfg, log)
+
+	if _, err := os.Stat(cfg.Paths.PendingBinary); err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			if _, versionErr := os.Stat(cfg.Paths.PendingVersion); versionErr == nil {
+				log.Warn("Removing stale pending supervisor version file %s", cfg.Paths.PendingVersion)
+				_ = os.Remove(cfg.Paths.PendingVersion)
+			}
+			return false, nil
+		}
+		return false, fmt.Errorf("stat pending supervisor binary: %w", err)
+	}
+
+	exePath, err := os.Executable()
+	if err != nil {
+		cleanupPendingSupervisorUpdate(cfg, log)
+		return false, fmt.Errorf("resolve current executable: %w", err)
+	}
+
+	if runtime.GOOS == "windows" {
+		isService, serviceErr := isWindowsService()
+		if serviceErr != nil {
+			markSupervisorApplyFailure(cfg, log, fmt.Sprintf("detect service mode for pending supervisor apply: %v", serviceErr))
+			cleanupPendingSupervisorUpdate(cfg, log)
+			return false, fmt.Errorf("detect service mode for pending supervisor apply: %w", serviceErr)
+		}
+
+		if err := launchWindowsApplyHelper(cfg, exePath, isService); err != nil {
+			markSupervisorApplyFailure(cfg, log, fmt.Sprintf("schedule pending supervisor apply: %v", err))
+			cleanupPendingSupervisorUpdate(cfg, log)
+			return false, fmt.Errorf("schedule pending supervisor apply: %w", err)
+		}
+		log.Info("Pending supervisor update detected; restarting to apply")
+		return true, nil
+	}
+
+	if err := os.Rename(cfg.Paths.PendingBinary, exePath); err != nil {
+		cleanupPendingSupervisorUpdate(cfg, log)
+		return false, fmt.Errorf("apply pending supervisor binary: %w", err)
+	}
+
+	if err := finalizePendingSupervisorVersion(cfg); err != nil {
+		log.Warn("Applied supervisor update but failed to persist version: %v", err)
+	} else {
+		log.Info("Applied supervisor update")
+	}
+
+	return false, nil
+}
+
+func finalizePendingSupervisorVersion(cfg Config) error {
+	data, err := os.ReadFile(cfg.Paths.PendingVersion)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil
+		}
+		return fmt.Errorf("read pending supervisor version: %w", err)
+	}
+
+	if err := atomicWrite(cfg.Paths.SupervisorVersion, data); err != nil {
+		return fmt.Errorf("write supervisor version: %w", err)
+	}
+	if err := os.Remove(cfg.Paths.PendingVersion); err != nil && !errors.Is(err, os.ErrNotExist) {
+		return fmt.Errorf("remove pending supervisor version: %w", err)
+	}
+	return nil
+}
+
+func cleanupPendingSupervisorUpdate(cfg Config, log *Logger) {
+	for _, path := range []string{cfg.Paths.PendingBinary, cfg.Paths.PendingVersion} {
+		if err := os.Remove(path); err != nil && !errors.Is(err, os.ErrNotExist) {
+			log.Warn("Failed to remove stale supervisor update artifact %s: %v", path, err)
+		}
+	}
+}
+
+func launchWindowsApplyHelper(cfg Config, exePath string, restartViaService bool) error {
+	if err := os.MkdirAll(filepath.Dir(cfg.Paths.SupervisorVersion), 0755); err != nil {
+		return fmt.Errorf("create supervisor version directory: %w", err)
+	}
+
+	scriptFile, err := os.CreateTemp("", "sensorium-supervisor-apply-*.cmd")
+	if err != nil {
+		return fmt.Errorf("create apply helper script: %w", err)
+	}
+
+	script := buildWindowsApplyHelperScript(cfg, exePath, restartViaService)
+
+	if _, err := scriptFile.WriteString(script); err != nil {
+		scriptFile.Close()
+		_ = os.Remove(scriptFile.Name())
+		return fmt.Errorf("write apply helper script: %w", err)
+	}
+	if err := scriptFile.Close(); err != nil {
+		_ = os.Remove(scriptFile.Name())
+		return fmt.Errorf("close apply helper script: %w", err)
+	}
+
+	cmd := exec.Command("cmd", "/c", scriptFile.Name())
+	cmd.Env = os.Environ()
+	cmd.Stdin = nil
+	cmd.Stdout = nil
+	cmd.Stderr = nil
+	setSysProcAttr(cmd)
+
+	if err := cmd.Start(); err != nil {
+		_ = os.Remove(scriptFile.Name())
+		return fmt.Errorf("start apply helper: %w", err)
+	}
+
+	_ = cmd.Process.Release()
+	return nil
+}
+
+func buildWindowsApplyHelperScript(cfg Config, exePath string, restartViaService bool) string {
+	failReason := fmt.Sprintf("helper failed to swap pending supervisor binary after retries (pending=%s current=%s)", cfg.Paths.PendingBinary, exePath)
+	escapedFailReason := batchEscapeForSetValue(failReason)
+
+	failLines := []string{
+		fmt.Sprintf(`set "FAIL_REASON=%s"`, escapedFailReason),
+		fmt.Sprintf(`<nul set /p "=%%FAIL_REASON%%" > %s`, batchQuote(supervisorApplyFailureMarkerPath(cfg))),
+		fmt.Sprintf(`if exist %s del /F /Q %s`, batchQuote(cfg.Paths.PendingBinary), batchQuote(cfg.Paths.PendingBinary)),
+		fmt.Sprintf(`if exist %s del /F /Q %s`, batchQuote(cfg.Paths.PendingVersion), batchQuote(cfg.Paths.PendingVersion)),
+	}
+
+	if restartViaService {
+		failLines = append(failLines,
+			fmt.Sprintf(`sc start %s >NUL 2>&1`, batchQuote(supervisorWindowsServiceName)),
+			"if errorlevel 1 (",
+			"  timeout /T 2 /NOBREAK >NUL",
+			fmt.Sprintf(`  sc start %s >NUL 2>&1`, batchQuote(supervisorWindowsServiceName)),
+			")",
+		)
+	} else {
+		failLines = append(failLines, fmt.Sprintf(`start "" %s`, batchQuote(exePath)))
+	}
+
+	failLines = append(failLines, "exit /b 1")
+
+	scriptLines := []string{
+		"@echo off",
+		"setlocal",
+		":wait",
+		fmt.Sprintf(`tasklist /FI "PID eq %d" 2>NUL | find "%d" >NUL`, os.Getpid(), os.Getpid()),
+		"if not errorlevel 1 (",
+		"  timeout /T 1 /NOBREAK >NUL",
+		"  goto wait",
+		")",
+		"set attempts=0",
+		":move",
+		fmt.Sprintf(`move /Y %s %s >NUL`, batchQuote(cfg.Paths.PendingBinary), batchQuote(exePath)),
+		"if not errorlevel 1 goto applied",
+		"set /a attempts+=1",
+		"if %attempts% GEQ 5 goto fail",
+		"timeout /T 1 /NOBREAK >NUL",
+		"goto move",
+		":applied",
+		fmt.Sprintf(`if exist %s move /Y %s %s >NUL`, batchQuote(cfg.Paths.PendingVersion), batchQuote(cfg.Paths.PendingVersion), batchQuote(cfg.Paths.SupervisorVersion)),
+		fmt.Sprintf(`if exist %s del /F /Q %s`, batchQuote(supervisorApplyFailureMarkerPath(cfg)), batchQuote(supervisorApplyFailureMarkerPath(cfg))),
+	}
+
+	if !restartViaService {
+		scriptLines = append(scriptLines, fmt.Sprintf(`start "" %s`, batchQuote(exePath)))
+	}
+
+	scriptLines = append(scriptLines,
+		"exit /b 0",
+		":fail",
+	)
+
+	scriptLines = append(scriptLines, failLines...)
+	scriptLines = append(scriptLines, "")
+
+	return strings.Join(scriptLines, "\r\n")
+}
+
+func supervisorApplyFailureMarkerPath(cfg Config) string {
+	return cfg.Paths.PendingBinary + ".failed"
+}
+
+func recordPendingSupervisorApplyFailureIfPresent(cfg Config, log *Logger) {
+	markerPath := supervisorApplyFailureMarkerPath(cfg)
+	data, err := os.ReadFile(markerPath)
+	if err != nil {
+		if !errors.Is(err, os.ErrNotExist) {
+			log.Warn("Failed to read supervisor apply failure marker %s: %v", markerPath, err)
+		}
+		return
+	}
+
+	reason := strings.TrimSpace(string(data))
+	if reason == "" {
+		reason = "pending supervisor apply helper reported failure"
+	}
+
+	store := NewUpdateStateStore(cfg.Paths.UpdateState, log)
+	state, stateErr := store.Load()
+	if stateErr != nil {
+		log.Warn("Failed to load update state while reconciling supervisor apply failure marker: %v", stateErr)
+	}
+	targetVersion := strings.TrimSpace(state.TargetVersion)
+	if targetVersion == "" {
+		targetVersion = strings.TrimSpace(readTrimmedFile(cfg.Paths.PendingVersion))
+	}
+	if targetVersion != "" {
+		currentVersion := strings.TrimSpace(readTrimmedFile(cfg.Paths.SupervisorVersion))
+		if currentVersion == targetVersion {
+			log.Warn("Ignoring stale supervisor apply failure marker because supervisor version already matches target %s", targetVersion)
+			store.Transition(updateScopeSupervisor, updatePhaseIdle, targetVersion, state.PreviousVersion, "")
+			if err := os.Remove(markerPath); err != nil && !errors.Is(err, os.ErrNotExist) {
+				log.Warn("Failed to remove stale supervisor apply failure marker %s: %v", markerPath, err)
+			}
+			return
+		}
+	}
+
+	markSupervisorApplyFailure(cfg, log, reason)
+
+	if err := os.Remove(markerPath); err != nil && !errors.Is(err, os.ErrNotExist) {
+		log.Warn("Failed to remove supervisor apply failure marker %s: %v", markerPath, err)
+	}
+}
+
+func markSupervisorApplyFailure(cfg Config, log *Logger, reason string) {
+	store := NewUpdateStateStore(cfg.Paths.UpdateState, log)
+	state, err := store.Load()
+	targetVersion := ""
+	previousVersion := ""
+	if err != nil {
+		log.Warn("Failed to load update state while marking supervisor apply failure: %v", err)
+	} else {
+		targetVersion = state.TargetVersion
+		previousVersion = state.PreviousVersion
+	}
+
+	if targetVersion == "" {
+		targetVersion = strings.TrimSpace(readTrimmedFile(cfg.Paths.PendingVersion))
+	}
+	if previousVersion == "" {
+		previousVersion = strings.TrimSpace(readTrimmedFile(cfg.Paths.SupervisorVersion))
+	}
+
+	lastError := reason
+	if !strings.Contains(lastError, supervisorRollbackAttemptedMarker) {
+		lastError = strings.TrimSpace(lastError + "; " + supervisorRollbackAttemptedMarker)
+	}
+
+	store.Transition(updateScopeSupervisor, updatePhaseRollback, targetVersion, previousVersion, lastError)
+	store.Transition(updateScopeSupervisor, updatePhaseFailed, targetVersion, previousVersion, lastError)
+}
+
+func batchQuote(path string) string {
+	return `"` + strings.ReplaceAll(path, `"`, `""`) + `"`
+}
+
+func batchEscapeForSetValue(value string) string {
+	value = strings.ReplaceAll(value, "\r", " ")
+	value = strings.ReplaceAll(value, "\n", " ")
+	value = strings.ReplaceAll(value, `%`, `%%`)
+	value = strings.ReplaceAll(value, `"`, `'`)
+	return value
+}

package/supervisor/self_update_test.go

@@ -0,0 +1,177 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestApplyPendingSupervisorUpdate_ConvergesToFailedFromRollbackMarker(t *testing.T) {
+	dir := t.TempDir()
+	log := NewLogger(filepath.Join(dir, "test.log"))
+	defer log.Close()
+
+	cfg := Config{
+		Paths: Paths{
+			PendingBinary:     filepath.Join(dir, "bin", "sensorium-supervisor.new.exe"),
+			PendingVersion:    filepath.Join(dir, "bin", "sensorium-supervisor.new.exe.version"),
+			SupervisorVersion: filepath.Join(dir, "supervisor-version.txt"),
+			UpdateState:       filepath.Join(dir, "update-state.json"),
+		},
+	}
+
+	if err := os.MkdirAll(filepath.Dir(cfg.Paths.PendingBinary), 0755); err != nil {
+		t.Fatalf("create pending dir: %v", err)
+	}
+
+	store := NewUpdateStateStore(cfg.Paths.UpdateState, log)
+	store.Transition(updateScopeSupervisor, updatePhaseRestarting, "2.0.0", "1.0.0", "")
+
+	reason := "helper failed to swap pending supervisor binary after retries"
+	if err := os.WriteFile(supervisorApplyFailureMarkerPath(cfg), []byte(reason), 0644); err != nil {
+		t.Fatalf("write apply failure marker: %v", err)
+	}
+
+	shouldRestart, err := applyPendingSupervisorUpdate(cfg, log)
+	if err != nil {
+		t.Fatalf("applyPendingSupervisorUpdate() error = %v", err)
+	}
+	if shouldRestart {
+		t.Fatal("applyPendingSupervisorUpdate() shouldRestart = true, want false")
+	}
+
+	state, err := store.Load()
+	if err != nil {
+		t.Fatalf("load state: %v", err)
+	}
+	if state.Scope != updateScopeSupervisor {
+		t.Fatalf("scope = %q, want %q", state.Scope, updateScopeSupervisor)
+	}
+	if state.Phase != updatePhaseFailed {
+		t.Fatalf("phase = %q, want %q", state.Phase, updatePhaseFailed)
+	}
+	if !strings.Contains(state.LastError, reason) {
+		t.Fatalf("last error = %q, want reason %q", state.LastError, reason)
+	}
+	if !strings.Contains(state.LastError, supervisorRollbackAttemptedMarker) {
+		t.Fatalf("last error = %q, missing rollback marker %q", state.LastError, supervisorRollbackAttemptedMarker)
+	}
+
+	if _, statErr := os.Stat(supervisorApplyFailureMarkerPath(cfg)); !os.IsNotExist(statErr) {
+		t.Fatalf("expected apply failure marker to be removed, got: %v", statErr)
+	}
+}
+
+func TestBuildWindowsApplyHelperScript_TaskModeFailPathRestartsCurrentBinary(t *testing.T) {
+	cfg := Config{
+		Paths: Paths{
+			PendingBinary:     `C:\data\bin\sensorium-supervisor.new.exe`,
+			PendingVersion:    `C:\data\bin\sensorium-supervisor.new.exe.version`,
+			SupervisorVersion: `C:\data\supervisor-version.txt`,
+		},
+	}
+	exePath := `C:\data\sensorium-supervisor.exe`
+
+	script := buildWindowsApplyHelperScript(cfg, exePath, false)
+
+	failStart := `:fail` + "\r\n" + `set "FAIL_REASON=helper failed to swap pending supervisor binary after retries (pending=C:\data\bin\sensorium-supervisor.new.exe current=C:\data\sensorium-supervisor.exe)"` + "\r\n" + `<nul set /p "=%FAIL_REASON%" > "C:\data\bin\sensorium-supervisor.new.exe.failed"` + "\r\n" + `if exist "C:\data\bin\sensorium-supervisor.new.exe" del /F /Q "C:\data\bin\sensorium-supervisor.new.exe"` + "\r\n" + `if exist "C:\data\bin\sensorium-supervisor.new.exe.version" del /F /Q "C:\data\bin\sensorium-supervisor.new.exe.version"` + "\r\n" + `start "" "C:\data\sensorium-supervisor.exe"`
+	if !strings.Contains(script, failStart) {
+		t.Fatalf("task-mode fail fallback restart block missing\nscript:\n%s", script)
+	}
+
+	if !strings.Contains(script, `:applied`+"\r\n"+`if exist "C:\data\bin\sensorium-supervisor.new.exe.version" move /Y "C:\data\bin\sensorium-supervisor.new.exe.version" "C:\data\supervisor-version.txt" >NUL`+"\r\n"+`if exist "C:\data\bin\sensorium-supervisor.new.exe.failed" del /F /Q "C:\data\bin\sensorium-supervisor.new.exe.failed"`+"\r\n"+`start "" "C:\data\sensorium-supervisor.exe"`) {
+		t.Fatalf("task-mode applied restart block missing\nscript:\n%s", script)
+	}
+}
+
+func TestBuildWindowsApplyHelperScript_ServiceModeDoesNotStartBinary(t *testing.T) {
+	cfg := Config{
+		Paths: Paths{
+			PendingBinary:     `C:\data\bin\sensorium-supervisor.new.exe`,
+			PendingVersion:    `C:\data\bin\sensorium-supervisor.new.exe.version`,
+			SupervisorVersion: `C:\data\supervisor-version.txt`,
+		},
+	}
+	exePath := `C:\data\sensorium-supervisor.exe`
+
+	script := buildWindowsApplyHelperScript(cfg, exePath, true)
+	if strings.Contains(script, `start "" "C:\data\sensorium-supervisor.exe"`) {
+		t.Fatalf("service-mode helper unexpectedly starts supervisor binary\nscript:\n%s", script)
+	}
+
+	serviceFailRestart := `:fail` + "\r\n" + `set "FAIL_REASON=helper failed to swap pending supervisor binary after retries (pending=C:\data\bin\sensorium-supervisor.new.exe current=C:\data\sensorium-supervisor.exe)"` + "\r\n" + `<nul set /p "=%FAIL_REASON%" > "C:\data\bin\sensorium-supervisor.new.exe.failed"` + "\r\n" + `if exist "C:\data\bin\sensorium-supervisor.new.exe" del /F /Q "C:\data\bin\sensorium-supervisor.new.exe"` + "\r\n" + `if exist "C:\data\bin\sensorium-supervisor.new.exe.version" del /F /Q "C:\data\bin\sensorium-supervisor.new.exe.version"` + "\r\n" + `sc start "SensoriumSupervisor" >NUL 2>&1` + "\r\n" + `if errorlevel 1 (` + "\r\n" + `  timeout /T 2 /NOBREAK >NUL` + "\r\n" + `  sc start "SensoriumSupervisor" >NUL 2>&1` + "\r\n" + `)`
+	if !strings.Contains(script, serviceFailRestart) {
+		t.Fatalf("service-mode fail recovery assist block missing\nscript:\n%s", script)
+	}
+}
+
+func TestBuildWindowsApplyHelperScript_EscapesFailReasonForCmdSafety(t *testing.T) {
+	cfg := Config{
+		Paths: Paths{
+			PendingBinary:     `C:\data\bin\sensorium&supervisor.new%TMP%.exe`,
+			PendingVersion:    `C:\data\bin\sensorium-supervisor.new.exe.version`,
+			SupervisorVersion: `C:\data\supervisor-version.txt`,
+		},
+	}
+	exePath := `C:\data\sensorium"supervisor.exe`
+
+	script := buildWindowsApplyHelperScript(cfg, exePath, false)
+
+	if !strings.Contains(script, `set "FAIL_REASON=helper failed to swap pending supervisor binary after retries (pending=C:\data\bin\sensorium&supervisor.new%%TMP%%.exe current=C:\data\sensorium'supervisor.exe)"`) {
+		t.Fatalf("expected escaped quoted FAIL_REASON assignment\nscript:\n%s", script)
+	}
+	if strings.Contains(script, `set FAIL_REASON=`) {
+		t.Fatalf("found unsafe unquoted FAIL_REASON assignment\nscript:\n%s", script)
+	}
+}
+
+func TestRecordPendingSupervisorApplyFailureIfPresent_IgnoresStaleMarkerWhenTargetAlreadyApplied(t *testing.T) {
+	dir := t.TempDir()
+	log := NewLogger(filepath.Join(dir, "test.log"))
+	defer log.Close()
+
+	targetVersion := "2.0.0"
+	cfg := Config{
+		Paths: Paths{
+			PendingBinary:     filepath.Join(dir, "bin", "sensorium-supervisor.new.exe"),
+			PendingVersion:    filepath.Join(dir, "bin", "sensorium-supervisor.new.exe.version"),
+			SupervisorVersion: filepath.Join(dir, "supervisor-version.txt"),
+			UpdateState:       filepath.Join(dir, "update-state.json"),
+		},
+	}
+
+	if err := os.MkdirAll(filepath.Dir(cfg.Paths.PendingBinary), 0755); err != nil {
+		t.Fatalf("create pending dir: %v", err)
+	}
+	if err := os.WriteFile(cfg.Paths.SupervisorVersion, []byte(targetVersion), 0644); err != nil {
+		t.Fatalf("write supervisor version: %v", err)
+	}
+
+	store := NewUpdateStateStore(cfg.Paths.UpdateState, log)
+	store.Transition(updateScopeSupervisor, updatePhaseFailed, targetVersion, "1.0.0", "old failure")
+
+	if err := os.WriteFile(supervisorApplyFailureMarkerPath(cfg), []byte("stale helper failure"), 0644); err != nil {
+		t.Fatalf("write apply failure marker: %v", err)
+	}
+
+	recordPendingSupervisorApplyFailureIfPresent(cfg, log)
+
+	state, err := store.Load()
+	if err != nil {
+		t.Fatalf("load state: %v", err)
+	}
+	if state.Phase != updatePhaseIdle {
+		t.Fatalf("phase = %q, want %q", state.Phase, updatePhaseIdle)
+	}
+	if state.TargetVersion != targetVersion {
+		t.Fatalf("target = %q, want %q", state.TargetVersion, targetVersion)
+	}
+	if state.LastError != "" {
+		t.Fatalf("last error = %q, want empty", state.LastError)
+	}
+
+	if _, statErr := os.Stat(supervisorApplyFailureMarkerPath(cfg)); !os.IsNotExist(statErr) {
+		t.Fatalf("expected apply failure marker to be removed, got: %v", statErr)
+	}
+}

package/supervisor/service_restart_stub.go

@@ -0,0 +1,9 @@
+//go:build !windows
+
+package main
+
+import "errors"
+
+func scheduleServiceRestartForUpdate(_ *Logger) error {
+	return errors.New("not supported on this OS")
+}

package/supervisor/service_restart_windows.go

@@ -0,0 +1,63 @@
+//go:build windows
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+)
+
+func scheduleServiceRestartForUpdate(log *Logger) error {
+	scriptFile, err := os.CreateTemp("", "sensorium-supervisor-service-restart-*.cmd")
+	if err != nil {
+		return fmt.Errorf("create service restart helper: %w", err)
+	}
+
+	script := strings.Join([]string{
+		"@echo off",
+		"setlocal",
+		fmt.Sprintf(`sc stop %s >NUL 2>&1`, batchQuote(serviceName)),
+		"timeout /T 2 /NOBREAK >NUL",
+		"set attempts=0",
+		":waitStopped",
+		fmt.Sprintf(`sc query %s | find "STATE" | find "STOPPED" >NUL`, batchQuote(serviceName)),
+		"if not errorlevel 1 goto start",
+		"set /a attempts+=1",
+		"if %attempts% GEQ 10 goto start",
+		"timeout /T 1 /NOBREAK >NUL",
+		"goto waitStopped",
+		":start",
+		"timeout /T 3 /NOBREAK >NUL",
+		fmt.Sprintf(`sc start %s >NUL 2>&1`, batchQuote(serviceName)),
+		"exit /b 0",
+		"",
+	}, "\r\n")
+
+	if _, err := scriptFile.WriteString(script); err != nil {
+		scriptFile.Close()
+		_ = os.Remove(scriptFile.Name())
+		return fmt.Errorf("write service restart helper: %w", err)
+	}
+	if err := scriptFile.Close(); err != nil {
+		_ = os.Remove(scriptFile.Name())
+		return fmt.Errorf("close service restart helper: %w", err)
+	}
+
+	cmd := exec.Command("cmd", "/c", scriptFile.Name())
+	cmd.Env = os.Environ()
+	cmd.Stdin = nil
+	cmd.Stdout = nil
+	cmd.Stderr = nil
+	setSysProcAttr(cmd)
+
+	if err := cmd.Start(); err != nil {
+		_ = os.Remove(scriptFile.Name())
+		return fmt.Errorf("start service restart helper: %w", err)
+	}
+
+	_ = cmd.Process.Release()
+	log.Info("Scheduled detached service restart helper to apply pending supervisor update")
+	return nil
+}

package/supervisor/service_stub.go

@@ -0,0 +1,15 @@
+//go:build !windows
+
+package main
+
+import "errors"
+
+func runAsService() error { return errors.New("not supported on this OS") }
+func installService(_, _, _ string) error {
+	return errors.New("not supported on this OS")
+}
+func uninstallService() error         { return errors.New("not supported on this OS") }
+func startService() error             { return errors.New("not supported on this OS") }
+func stopService() error              { return errors.New("not supported on this OS") }
+func serviceStatus() error            { return errors.New("not supported on this OS") }
+func isWindowsService() (bool, error) { return false, nil }