refactor(selfupdate): CC-style stateless self-update — runner self-decides, reports nothing

Collapse the upgrade flow to the Claude-Code model: the backend only
advertises the latest version; the runner alone decides whether to apply
and reports no status over the wire. The backend infers the outcome purely
from the version the runner reports on its next heartbeat.

- Drop the upgrade.status wire message + UpgradeStatusPayload; the phase
  labels are now local-log-only constants (journald), not a protocol.
- Add --disable-auto-update (env FLASHDUTY_RUNNER_DISABLE_AUTO_UPDATE):
  a per-runner opt-out replaces any server-side policy. handleUpgrade
  short-circuits on it before any disk work.
- CanSelfUpdate(): probe whether the binary's dir is writable and skip the
  swap for manual root-owned installs instead of looping a doomed upgrade.
- Runner-local last-rolled-back-version guard (ShouldSkipTarget): since the
  backend re-advertises the same latest every heartbeat, a rollback records
  the bad version and the handler ignores re-advertisements of exactly that
  version until a newer one is published or a later upgrade commits — no
  more endless download -> swap -> rollback loop.
- Download resilience: a 60s no-bytes stall watchdog plus bounded retry on
  transient failures (connection drop, stall, 5xx/429), and NO retry on
  deterministic ones (checksum mismatch, 4xx, bad archive).
- install.sh documents the opt-out in the generated env file.

Author: ysyneu

cmd/main.go

@@ -10,7 +10,7 @@ import (
 	"os"
 	"os/signal"
 	"path/filepath"
-	"sync"
+	"strings"
 	"sync/atomic"
 	"syscall"
 	"time"
@@ -19,7 +19,6 @@ import (
 
 	"github.com/flashcatcloud/flashduty-runner/environment"
 	"github.com/flashcatcloud/flashduty-runner/permission"
-	"github.com/flashcatcloud/flashduty-runner/protocol"
 	"github.com/flashcatcloud/flashduty-runner/selfupdate"
 	"github.com/flashcatcloud/flashduty-runner/ws"
 )
@@ -33,11 +32,12 @@ var (
 
 // Command line flags
 var (
-	flagToken       string
-	flagURL         string
-	flagWorkspace   string
-	flagLogLevel    string
-	flagMaxAttempts int
+	flagToken             string
+	flagURL               string
+	flagWorkspace         string
+	flagLogLevel          string
+	flagMaxAttempts       int
+	flagDisableAutoUpdate bool
 )
 
 // Default values
@@ -113,6 +113,7 @@ Environment variables:
 	cmd.Flags().StringVar(&flagWorkspace, "workspace", "", "Workspace root directory (env: FLASHDUTY_RUNNER_WORKSPACE)")
 	cmd.Flags().StringVar(&flagLogLevel, "log-level", "", "Log level: debug, info, warn, error (env: FLASHDUTY_RUNNER_LOG_LEVEL)")
 	cmd.Flags().IntVar(&flagMaxAttempts, "max-attempts", -1, "Max reconnect attempts (0=unlimited, default=30, env: FLASHDUTY_RUNNER_MAX_ATTEMPTS)")
+	cmd.Flags().BoolVar(&flagDisableAutoUpdate, "disable-auto-update", false, "Opt out of automatic self-updates; this runner stays on its installed version (env: FLASHDUTY_RUNNER_DISABLE_AUTO_UPDATE)")
 
 	return cmd
 }
@@ -131,11 +132,12 @@ func versionCmd() *cobra.Command {
 
 // Config holds the runtime configuration
 type Config struct {
-	Token         string
-	URL           string
-	WorkspaceRoot string
-	LogLevel      string
-	MaxAttempts   int
+	Token             string
+	URL               string
+	WorkspaceRoot     string
+	LogLevel          string
+	MaxAttempts       int
+	DisableAutoUpdate bool
 }
 
 func loadConfig() (*Config, error) {
@@ -197,9 +199,23 @@ func loadConfig() (*Config, error) {
 		}
 	}
 
+	// Auto-update opt-out: flag OR env truthy disables it. Opt-out only, so we
+	// never need to distinguish "explicitly false" from "unset".
+	cfg.DisableAutoUpdate = flagDisableAutoUpdate || isTruthy(os.Getenv("FLASHDUTY_RUNNER_DISABLE_AUTO_UPDATE"))
+
 	return cfg, nil
 }
 
+// isTruthy reports whether an env-var string requests an enabled boolean.
+func isTruthy(v string) bool {
+	switch strings.ToLower(strings.TrimSpace(v)) {
+	case "1", "true", "yes", "on":
+		return true
+	default:
+		return false
+	}
+}
+
 func runRunner() error {
 	// Load configuration
 	cfg, err := loadConfig()
@@ -241,6 +257,10 @@ func runRunner() error {
 
 	// Create message handler
 	handler := ws.NewHandler(wspace)
+	handler.SetDisableAutoUpdate(cfg.DisableAutoUpdate)
+	if cfg.DisableAutoUpdate {
+		slog.Info("auto-update disabled; this runner stays on its installed version", "version", Version)
+	}
 
 	// Create WebSocket client
 	client := ws.NewClient(cfg.Token, cfg.URL, cfg.WorkspaceRoot, handler.Handle, Version, cfg.MaxAttempts)
@@ -265,27 +285,17 @@ func runRunner() error {
 	}
 
 	// On the first successful handshake during probation, commit the upgrade
-	// (clear marker + .bak) and report it; if we rolled back on boot, report
-	// that once and clear the marker. onConnected fires only after a successful
+	// (clear marker + .bak + failed-version memory). The backend infers success
+	// purely from the version the runner reports on its next heartbeat — there is
+	// no upgrade-status wire message. onConnected fires only after a successful
 	// welcome handshake (ws.Client.Connect returns an error otherwise).
-	var reportRolledBackOnce sync.Once
 	client.SetOnConnected(func() {
 		if bootOutcome.InProbation && committed.CompareAndSwap(false, true) {
 			if probationTimer != nil {
 				probationTimer.Stop()
 			}
 			pm.Commit()
-			_ = client.SendPayload(protocol.MessageTypeUpgradeStatus, protocol.UpgradeStatusPayload{
-				TargetVersion: Version, Phase: protocol.UpgradePhaseCommitted,
-			})
-		}
-		if bootOutcome.ReportRolledBack {
-			reportRolledBackOnce.Do(func() {
-				_ = client.SendPayload(protocol.MessageTypeUpgradeStatus, protocol.UpgradeStatusPayload{
-					TargetVersion: bootOutcome.RolledBackTarget, Phase: protocol.UpgradePhaseRolledBack,
-				})
-				pm.ClearAfterReport()
-			})
+			slog.Info("self-update committed after successful handshake", "version", Version)
 		}
 	})
 

install.sh

@@ -419,6 +419,10 @@ write_env_file() {
         printf 'FLASHDUTY_RUNNER_URL=%s\n' "$URL"
         printf 'FLASHDUTY_RUNNER_WORKSPACE=%s\n' "$WORKSPACE_DIR"
         printf 'FLASHDUTY_RUNNER_LOG_LEVEL=info\n'
+        printf '# Auto-update is on by default: the runner upgrades itself when Flashduty\n'
+        printf '# publishes a newer version. To pin this host to its installed version,\n'
+        printf '# uncomment the next line (then: systemctl restart flashduty-runner).\n'
+        printf '# FLASHDUTY_RUNNER_DISABLE_AUTO_UPDATE=true\n'
     } >"$ENV_FILE"
     chown 0:0 "$ENV_FILE" 2>/dev/null || true
     chmod 0600 "$ENV_FILE"

protocol/messages.go

@@ -31,10 +31,10 @@ const (
 	// unregister timeout.
 	MessageTypeShutdown MessageType = "shutdown"
 
-	// Flashduty -> Runner
+	// Flashduty -> Runner. Advertises the target version in response to a
+	// heartbeat; the runner self-decides whether to apply (it reports only its
+	// own version back — there is no upgrade-status channel).
 	MessageTypeUpgrade MessageType = "upgrade"
-	// Runner -> Flashduty
-	MessageTypeUpgradeStatus MessageType = "upgrade.status"
 )
 
 // Message is the base WebSocket message structure.
@@ -488,28 +488,21 @@ type ReconcileKnowledgeManifestResult struct {
 	NeedsStage []string `json:"needs_stage,omitempty"`
 }
 
-// Upgrade phases (UpgradeStatusPayload.Phase values).
+// Upgrade phase labels for the runner's own local logging (journald). They are
+// not reported over the wire — the backend infers progress from the version the
+// runner reports on its next heartbeat.
 const (
-	UpgradePhaseReceived    = "received"
-	UpgradePhaseDeferred    = "deferred"
 	UpgradePhaseDownloading = "downloading"
 	UpgradePhaseVerifying   = "verifying"
 	UpgradePhaseSwapping    = "swapping"
-	UpgradePhaseCommitted   = "committed"
-	UpgradePhaseRolledBack  = "rolled_back"
 	UpgradePhaseFailed      = "failed"
 )
 
-// UpgradePayload is sent by Flashduty to trigger an in-process self-update.
+// UpgradePayload is sent by Flashduty to advertise the target version (with its
+// download URL + checksum) in response to a heartbeat. The runner self-decides
+// whether to apply it.
 type UpgradePayload struct {
 	TargetVersion string `json:"target_version"`
 	DownloadURL   string `json:"download_url"`
 	SHA256        string `json:"sha256"`
 }
-
-// UpgradeStatusPayload reports self-update progress back to Flashduty.
-type UpgradeStatusPayload struct {
-	TargetVersion string `json:"target_version"`
-	Phase         string `json:"phase"`
-	Error         string `json:"error,omitempty"`
-}

selfupdate/capability.go

@@ -0,0 +1,24 @@
+package selfupdate
+
+import (
+	"os"
+	"path/filepath"
+)
+
+// CanSelfUpdate reports whether the runner can replace its own binary in place.
+// The atomic swap copies the current binary to <dir>/.bak and renames the new
+// one over the canonical path, so the executable's *directory* must be writable
+// by the service user. A manual install that drops the binary in root-owned
+// /usr/local/bin and runs as a non-root user cannot — and must not attempt to —
+// self-update; the handler checks this before a doomed download ever begins, so
+// such runners simply stay on their version instead of failing in a loop.
+func CanSelfUpdate(exePath string) bool {
+	f, err := os.CreateTemp(filepath.Dir(exePath), ".swcheck-*")
+	if err != nil {
+		return false
+	}
+	name := f.Name()
+	_ = f.Close()
+	_ = os.Remove(name)
+	return true
+}

selfupdate/capability_test.go

@@ -0,0 +1,38 @@
+package selfupdate
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// TestCanSelfUpdateWritableDir verifies that a runner whose executable lives in
+// a writable directory can self-update, and that the writability probe leaves no
+// litter behind.
+func TestCanSelfUpdateWritableDir(t *testing.T) {
+	dir := t.TempDir()
+	exe := filepath.Join(dir, "flashduty-runner")
+	if err := os.WriteFile(exe, []byte("x"), 0o755); err != nil { //nolint:gosec // test fixture
+		t.Fatal(err)
+	}
+	if !CanSelfUpdate(exe) {
+		t.Fatal("expected CanSelfUpdate true for a writable exe dir")
+	}
+	entries, _ := os.ReadDir(dir)
+	for _, e := range entries {
+		if e.Name() != "flashduty-runner" {
+			t.Fatalf("writability probe left a stray file: %s", e.Name())
+		}
+	}
+}
+
+// TestCanSelfUpdateNonWritableDir verifies that a manual install whose binary
+// sits in a directory the runner cannot write (modelled here as a missing
+// parent) reports it cannot self-update, so the handler skips the upgrade
+// locally instead of looping on a swap it can never complete.
+func TestCanSelfUpdateNonWritableDir(t *testing.T) {
+	exe := filepath.Join(t.TempDir(), "missing-subdir", "flashduty-runner")
+	if CanSelfUpdate(exe) {
+		t.Fatal("expected CanSelfUpdate false when the exe dir is not writable")
+	}
+}

selfupdate/download_retry_test.go

@@ -0,0 +1,83 @@
+package selfupdate
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// TestDownloadRetriesTransientThenSucceeds verifies the borrowed download
+// resilience: two 503s are retried and the third (200) succeeds.
+func TestDownloadRetriesTransientThenSucceeds(t *testing.T) {
+	binBytes := []byte("hi")
+	targz := makeTarGz(t, "flashduty-runner", binBytes)
+	sum := sha256Hex(targz)
+
+	var calls int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		if atomic.AddInt32(&calls, 1) < 3 {
+			w.WriteHeader(http.StatusServiceUnavailable)
+			return
+		}
+		_, _ = w.Write(targz)
+	}))
+	defer srv.Close()
+
+	// Shrink the backoff so the test doesn't actually sleep seconds between tries.
+	origBackoff := downloadBackoffBase
+	downloadBackoffBase = time.Millisecond
+	defer func() { downloadBackoffBase = origBackoff }()
+
+	dest := filepath.Join(t.TempDir(), "flashduty-runner.new")
+	if err := downloadVerifyExtract(context.Background(), srv.URL, sum, dest); err != nil {
+		t.Fatalf("expected success after retries, got %v", err)
+	}
+	if got := atomic.LoadInt32(&calls); got != 3 {
+		t.Fatalf("expected 3 attempts, got %d", got)
+	}
+}
+
+// TestDownloadDoesNotRetry4xx verifies a deterministic failure (404 wrong URL)
+// is not retried — another attempt would fail identically and burn the window.
+func TestDownloadDoesNotRetry4xx(t *testing.T) {
+	var calls int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer srv.Close()
+
+	dest := filepath.Join(t.TempDir(), "flashduty-runner.new")
+	if err := downloadVerifyExtract(context.Background(), srv.URL, "abc", dest); err == nil {
+		t.Fatal("expected error on 404")
+	}
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("expected exactly 1 attempt (no retry on 4xx), got %d", got)
+	}
+}
+
+// TestDownloadDoesNotRetryChecksumMismatch verifies a checksum mismatch is
+// deterministic: a re-download of the same artifact can't fix it, so it fails
+// after a single attempt.
+func TestDownloadDoesNotRetryChecksumMismatch(t *testing.T) {
+	targz := makeTarGz(t, "flashduty-runner", []byte("hi"))
+
+	var calls int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		_, _ = w.Write(targz)
+	}))
+	defer srv.Close()
+
+	dest := filepath.Join(t.TempDir(), "flashduty-runner.new")
+	if err := downloadVerifyExtract(context.Background(), srv.URL, "deadbeef", dest); err == nil {
+		t.Fatal("expected checksum error")
+	}
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("expected exactly 1 attempt (no retry on checksum mismatch), got %d", got)
+	}
+}

selfupdate/failed.go

@@ -0,0 +1,38 @@
+package selfupdate
+
+import (
+	"os"
+	"strings"
+)
+
+// Failed-version memory. The backend is stateless: it keeps advertising the
+// channel's latest version on every heartbeat. Without a local guard, a runner
+// that rolls back from a bad latest would re-download → swap → roll back on a
+// loop. So a rollback records the version it backed out of; ShouldSkipTarget
+// then ignores re-advertisements of exactly that version until a *newer* one is
+// published (different string) or a later upgrade commits (cleared on commit).
+
+func recordFailedVersion(path, version string) {
+	if version == "" {
+		return
+	}
+	_ = os.WriteFile(path, []byte(version), 0o600)
+}
+
+func lastFailedVersion(path string) string {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(data))
+}
+
+func clearFailedVersion(path string) {
+	_ = os.Remove(path)
+}
+
+// ShouldSkipTarget reports whether an advertised target should be ignored
+// because this host already rolled back from exactly that version.
+func ShouldSkipTarget(exePath, target string) bool {
+	return target != "" && lastFailedVersion(layoutFor(exePath).Failed) == target
+}