feat(update): persistent state machine + lifecycle metrics

Phase 5 of v0.3. Adds an explicit, on-disk state machine to the update agent
so the lifecycle of an attempt is observable end-to-end, instead of being
inferred from logs and side effects.

New package update/pkg/state:
- Phase enum (idle, checking, downloading, staged, activated, verifying,
  success, rolled_back, failed)
- UpdateState struct persisted to /var/lib/kubesolo/update/state.json
  (overridable via --state). Atomic write (.tmp + rename). Survives reboots
  and slot switches because the file lives on the data partition.
- Transition helper that bumps AttemptCount when an attempt starts, resets
  it when the target version changes, sets/clears LastError on
  failed/success transitions, and stamps StartedAt + UpdatedAt.
- 13 unit tests cover the lifecycle, atomic write, version-change reset,
  error recording, idempotent SetFromVersion, garbage-file handling.

Wired into the existing commands:
- apply.go transitions Idle -> Checking -> Downloading -> Staged, with
  RecordError on any step failure. Reads the active slot's version file to
  populate FromVersion.
- activate.go transitions to Activated.
- healthcheck.go transitions Activated -> Verifying -> Success on pass,
  or to Failed on fail. Skips transitions if state isn't post-activation
  (manual healthcheck on a stable system shouldn't churn the state).
- rollback.go transitions to RolledBack with LastError="manual rollback".
- check.go intentionally untouched — checks are passive queries, not
  attempts; they shouldn't reset AttemptCount.

status.go gains a --json mode that emits the full state report (A/B slots,
boot counter, full UpdateState) for orchestration tooling. Human-readable
mode also prints an Update Lifecycle section when state.phase != idle.

pkg/metrics gains three new series, derived from state.json at scrape time:
- kubesolo_update_phase{phase="..."} — 1 for current, 0 for all others;
  all nine phase values always emitted so dashboards see complete series
- kubesolo_update_attempts_total
- kubesolo_update_last_attempt_timestamp_seconds
Server.SetStatePath() configures the file location; defaults to absent
which emits Idle defaults. Three new tests cover the absent / active /
all-phases-emitted cases.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

update/cmd/apply.go

@@ -6,10 +6,14 @@ import (
 
 	"github.com/portainer/kubesolo-os/update/pkg/image"
 	"github.com/portainer/kubesolo-os/update/pkg/partition"
+	"github.com/portainer/kubesolo-os/update/pkg/state"
 )
 
 // Apply downloads a new OS image and writes it to the passive partition.
 // It does NOT activate the new partition — use 'activate' for that.
+//
+// State transitions: Idle/Success/Failed → Checking → Downloading → Staged.
+// On any error the state moves to Failed with LastError set.
 func Apply(args []string) error {
 	opts := parseOpts(args)
 
@@ -17,11 +21,34 @@ func Apply(args []string) error {
 		return fmt.Errorf("--server is required")
 	}
 
+	st, err := state.Load(opts.StatePath)
+	if err != nil {
+		// Don't block the operation on a corrupt state file. Log + recover.
+		slog.Warn("state file unreadable, starting fresh", "error", err)
+		st = state.New()
+	}
+
 	env := opts.NewBootEnv()
 
+	// Record the current running version as the "from" reference. The active
+	// slot's version file is the most reliable source.
+	activeSlot, slotErr := env.ActiveSlot()
+	if slotErr == nil {
+		if partInfo, perr := partition.GetSlotPartition(activeSlot); perr == nil {
+			mp := "/tmp/kubesolo-active-" + activeSlot
+			if merr := partition.MountReadOnly(partInfo.Device, mp); merr == nil {
+				if v, rerr := partition.ReadVersion(mp); rerr == nil {
+					st.SetFromVersion(v)
+				}
+				partition.Unmount(mp)
+			}
+		}
+	}
+
 	// Determine passive slot
 	passiveSlot, err := env.PassiveSlot()
 	if err != nil {
+		_ = st.RecordError(opts.StatePath, fmt.Errorf("reading passive slot: %w", err))
 		return fmt.Errorf("reading passive slot: %w", err)
 	}
 
@@ -38,36 +65,55 @@ func Apply(args []string) error {
 		slog.Info("signature verification enabled", "pubkey", opts.PubKeyPath)
 	}
 
+	if err := st.Transition(opts.StatePath, state.PhaseChecking, "", ""); err != nil {
+		slog.Warn("state transition failed", "phase", state.PhaseChecking, "error", err)
+	}
+
 	meta, err := client.CheckForUpdate()
 	if err != nil {
+		_ = st.RecordError(opts.StatePath, fmt.Errorf("checking for update: %w", err))
 		return fmt.Errorf("checking for update: %w", err)
 	}
 
 	slog.Info("update available", "version", meta.Version)
 
+	// Now we know the target version — record it (resets attempt count if it
+	// differs from the previous attempt's ToVersion).
+	if err := st.Transition(opts.StatePath, state.PhaseDownloading, meta.Version, ""); err != nil {
+		slog.Warn("state transition failed", "phase", state.PhaseDownloading, "error", err)
+	}
+
 	// Download and verify
 	staged, err := client.Download(meta)
 	if err != nil {
+		_ = st.RecordError(opts.StatePath, fmt.Errorf("downloading update: %w", err))
 		return fmt.Errorf("downloading update: %w", err)
 	}
 
 	// Mount passive partition
 	partInfo, err := partition.GetSlotPartition(passiveSlot)
 	if err != nil {
+		_ = st.RecordError(opts.StatePath, fmt.Errorf("finding passive partition: %w", err))
 		return fmt.Errorf("finding passive partition: %w", err)
 	}
 
 	mountPoint := "/tmp/kubesolo-passive-" + passiveSlot
 	if err := partition.MountReadWrite(partInfo.Device, mountPoint); err != nil {
+		_ = st.RecordError(opts.StatePath, fmt.Errorf("mounting passive partition: %w", err))
 		return fmt.Errorf("mounting passive partition: %w", err)
 	}
 	defer partition.Unmount(mountPoint)
 
 	// Write image to passive partition
 	if err := partition.WriteSystemImage(mountPoint, staged.VmlinuzPath, staged.InitramfsPath, staged.Version); err != nil {
+		_ = st.RecordError(opts.StatePath, fmt.Errorf("writing system image: %w", err))
 		return fmt.Errorf("writing system image: %w", err)
 	}
 
+	if err := st.Transition(opts.StatePath, state.PhaseStaged, staged.Version, ""); err != nil {
+		slog.Warn("state transition failed", "phase", state.PhaseStaged, "error", err)
+	}
+
 	fmt.Printf("Update v%s written to slot %s (%s)\n", staged.Version, passiveSlot, partInfo.Device)
 	fmt.Println("Run 'kubesolo-update activate' to boot into the new version")