feat(update): channels, maintenance windows, min-version gate

Phase 6 of v0.3. The update agent now refuses to apply artifacts whose
channel doesn't match local policy, whose architecture differs from the
running host, or whose min_compatible_version is above the current
version. It also refuses to apply outside a configured maintenance window
unless --force is given.

New package update/pkg/config:
- config.Load parses /etc/kubesolo/update.conf (key=value, # comments,
  unknown keys ignored). Missing file is fine — fresh systems before
  cloud-init has run.
- ParseWindow handles "HH:MM-HH:MM" plus the wrapping midnight case
  (e.g. "23:00-01:00"). Empty input -> AlwaysOpen (no constraint).
  Degenerate zero-length windows never match.
- CompareVersions does a simple 3-component semver compare with the 'v'
  prefix optional and pre-release suffix ignored.
- 14 unit tests total.

update/pkg/image/image.UpdateMetadata gains three optional fields:
- channel ("stable", "beta", ...)
- min_compatible_version (refuse upgrade if current < this)
- architecture ("amd64", "arm64", ...)

update/cmd/opts.go reads update.conf and merges it into opts; explicit
--server / --channel / --pubkey / --maintenance-window CLI flags override
the file. New --force, --conf, --channel, --maintenance-window flags.
Precedence: CLI > config file > package defaults.

update/cmd/apply.go gains four gates in order:
1. Maintenance window — checked locally before any HTTP work; skipped
   with --force.
2. Channel — refused if metadata.channel doesn't match opts.Channel.
3. Architecture — refused if metadata.architecture != runtime.GOARCH.
4. Min compatible version — refused if FromVersion < min_compatible.
All gate failures transition state to Failed with a clear LastError.

cloud-init gains a top-level updates: block (Server, Channel,
MaintenanceWindow, PubKey). cloud-init.ApplyUpdates writes
/etc/kubesolo/update.conf from those fields on first boot. Empty block
leaves any existing file alone (so hand-edited update.conf survives a
reboot without cloud-init re-applying). 4 new tests cover empty / all /
partial / parent-dir-creation cases. full-config.yaml example updated.

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

update/cmd/apply.go

@@ -3,7 +3,10 @@ package cmd
 import (
 	"fmt"
 	"log/slog"
+	"runtime"
+	"time"
 
+	"github.com/portainer/kubesolo-os/update/pkg/config"
 	"github.com/portainer/kubesolo-os/update/pkg/image"
 	"github.com/portainer/kubesolo-os/update/pkg/partition"
 	"github.com/portainer/kubesolo-os/update/pkg/state"
@@ -18,7 +21,18 @@ func Apply(args []string) error {
 	opts := parseOpts(args)
 
 	if opts.ServerURL == "" {
-		return fmt.Errorf("--server is required")
+		return fmt.Errorf("--server is required (or set in /etc/kubesolo/update.conf)")
+	}
+
+	// Maintenance window gate — earliest cheap check, before any HTTP work.
+	// Skipped with --force.
+	window, werr := config.ParseWindow(opts.MaintenanceWindow)
+	if werr != nil {
+		return fmt.Errorf("parse maintenance_window: %w", werr)
+	}
+	if !opts.Force && !window.Contains(time.Now()) {
+		return fmt.Errorf("outside maintenance window (%s); pass --force to override",
+			window.String())
 	}
 
 	st, err := state.Load(opts.StatePath)
@@ -75,7 +89,40 @@ func Apply(args []string) error {
 		return fmt.Errorf("checking for update: %w", err)
 	}
 
-	slog.Info("update available", "version", meta.Version)
+	slog.Info("update available", "version", meta.Version, "channel", meta.Channel, "arch", meta.Architecture)
+
+	// Channel gate — refuse mismatched channels.
+	if meta.Channel != "" && meta.Channel != opts.Channel {
+		err := fmt.Errorf("metadata channel %q does not match local channel %q",
+			meta.Channel, opts.Channel)
+		_ = st.RecordError(opts.StatePath, err)
+		return err
+	}
+
+	// Architecture gate — refuse cross-arch artifacts. runtime.GOARCH is our
+	// canonical identifier ("amd64", "arm64", "arm").
+	if meta.Architecture != "" && meta.Architecture != runtime.GOARCH {
+		err := fmt.Errorf("metadata architecture %q does not match runtime %q",
+			meta.Architecture, runtime.GOARCH)
+		_ = st.RecordError(opts.StatePath, err)
+		return err
+	}
+
+	// Min-compatible-version gate — refuse if a stepping-stone is required.
+	// We need the active slot's version (already populated into st.FromVersion
+	// earlier in this command).
+	if meta.MinCompatibleVersion != "" && st.FromVersion != "" {
+		cmp, cerr := config.CompareVersions(st.FromVersion, meta.MinCompatibleVersion)
+		if cerr != nil {
+			slog.Warn("min-version comparison failed", "error", cerr,
+				"from", st.FromVersion, "min", meta.MinCompatibleVersion)
+		} else if cmp < 0 {
+			err := fmt.Errorf("current version %s is below min_compatible_version %s; install %s first",
+				st.FromVersion, meta.MinCompatibleVersion, meta.MinCompatibleVersion)
+			_ = st.RecordError(opts.StatePath, err)
+			return err
+		}
+	}
 
 	// Now we know the target version — record it (resets attempt count if it
 	// differs from the previous attempt's ToVersion).

update/cmd/opts.go

@@ -1,20 +1,27 @@
 package cmd
 
 import (
+	"log/slog"
+
 	"github.com/portainer/kubesolo-os/update/pkg/bootenv"
+	"github.com/portainer/kubesolo-os/update/pkg/config"
 	"github.com/portainer/kubesolo-os/update/pkg/state"
 )
 
 // opts holds shared command-line options for all subcommands.
 type opts struct {
-	ServerURL   string
-	GrubenvPath string
-	TimeoutSecs int
-	PubKeyPath  string
-	BootEnvType string // "grub" or "rpi"
-	BootEnvPath string // path for RPi boot control dir
-	StatePath   string // location of state.json (default: state.DefaultPath)
-	JSON        bool   // status: emit JSON instead of human-readable
+	ServerURL         string
+	GrubenvPath       string
+	TimeoutSecs       int
+	PubKeyPath        string
+	BootEnvType       string // "grub" or "rpi"
+	BootEnvPath       string // path for RPi boot control dir
+	StatePath         string // location of state.json (default: state.DefaultPath)
+	ConfPath          string // location of update.conf (default: config.DefaultPath)
+	Channel           string // update channel ("stable" by default)
+	MaintenanceWindow string // "HH:MM-HH:MM" or empty for always-allow
+	Force             bool   // bypass maintenance window
+	JSON              bool   // status: emit JSON instead of human-readable
 }
 
 // NewBootEnv creates a BootEnv from the parsed options.
@@ -28,22 +35,69 @@ func (o opts) NewBootEnv() bootenv.BootEnv {
 }
 
 // parseOpts extracts command-line flags from args.
-// Simple parser — no external dependencies.
+//
+// Precedence: explicit CLI flags > /etc/kubesolo/update.conf > package
+// defaults. The config file is loaded first so any CLI flag overrides it.
+//
+// Unknown flags are ignored (forward-compat).
 func parseOpts(args []string) opts {
 	o := opts{
 		GrubenvPath: "/boot/grub/grubenv",
 		TimeoutSecs: 120,
 		BootEnvType: "grub",
 		StatePath:   state.DefaultPath,
+		ConfPath:    config.DefaultPath,
+		Channel:     "stable",
 	}
 
+	// First pass: pick up --conf so it can point at a different file before
+	// we load. (Tests pass --conf <tempdir>/update.conf.)
+	for i := 0; i < len(args); i++ {
+		if args[i] == "--conf" && i+1 < len(args) {
+			o.ConfPath = args[i+1]
+		}
+	}
+
+	// Load config file. Missing file is fine (fresh system, no cloud-init yet).
+	if cfg, err := config.Load(o.ConfPath); err == nil && cfg != nil {
+		if cfg.Server != "" {
+			o.ServerURL = cfg.Server
+		}
+		if cfg.Channel != "" {
+			o.Channel = cfg.Channel
+		}
+		if cfg.MaintenanceWindow != "" {
+			o.MaintenanceWindow = cfg.MaintenanceWindow
+		}
+		if cfg.PubKey != "" {
+			o.PubKeyPath = cfg.PubKey
+		}
+	} else if err != nil {
+		slog.Warn("could not load update.conf", "path", o.ConfPath, "error", err)
+	}
+
+	// Second pass: CLI overrides config file values.
 	for i := 0; i < len(args); i++ {
 		switch args[i] {
+		case "--conf":
+			i++ // already handled above
 		case "--state":
 			if i+1 < len(args) {
 				o.StatePath = args[i+1]
 				i++
 			}
+		case "--channel":
+			if i+1 < len(args) {
+				o.Channel = args[i+1]
+				i++
+			}
+		case "--maintenance-window":
+			if i+1 < len(args) {
+				o.MaintenanceWindow = args[i+1]
+				i++
+			}
+		case "--force":
+			o.Force = true
 		case "--json":
 			o.JSON = true
 		case "--server":