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/pkg/config/config.go

@@ -0,0 +1,83 @@
+// Package config parses /etc/kubesolo/update.conf — the persistent
+// configuration for the update agent. Each line is "key = value"; blank
+// lines and "#"-prefixed comments are ignored. Unknown keys are tolerated
+// (forward compatibility).
+//
+// Example:
+//
+//	# Where to look for updates
+//	server = https://updates.kubesolo.example.com
+//	channel = stable
+//
+//	# Only apply between 03:00 and 05:00 local time
+//	maintenance_window = 03:00-05:00
+//
+//	pubkey = /etc/kubesolo/update-pubkey.hex
+//
+// The file is populated on first boot by cloud-init (see the cloud-init
+// updates: block) and can be hand-edited afterwards.
+package config
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"strings"
+)
+
+// DefaultPath is where update.conf lives on a live system.
+const DefaultPath = "/etc/kubesolo/update.conf"
+
+// Config holds the parsed update.conf values. Empty fields mean "not set" —
+// the caller's defaults apply.
+type Config struct {
+	Server            string
+	Channel           string
+	MaintenanceWindow string
+	PubKey            string
+}
+
+// Load reads and parses update.conf. A missing file returns an empty Config
+// (not an error) — fresh systems before cloud-init has run.
+func Load(path string) (*Config, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return &Config{}, nil
+		}
+		return nil, fmt.Errorf("open %s: %w", path, err)
+	}
+	defer f.Close()
+
+	c := &Config{}
+	scanner := bufio.NewScanner(f)
+	lineNo := 0
+	for scanner.Scan() {
+		lineNo++
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		eq := strings.IndexByte(line, '=')
+		if eq < 0 {
+			return nil, fmt.Errorf("%s:%d: missing '=' in line: %q", path, lineNo, line)
+		}
+		key := strings.TrimSpace(line[:eq])
+		value := strings.TrimSpace(line[eq+1:])
+		switch key {
+		case "server":
+			c.Server = value
+		case "channel":
+			c.Channel = value
+		case "maintenance_window":
+			c.MaintenanceWindow = value
+		case "pubkey":
+			c.PubKey = value
+		}
+		// Unknown keys are silently ignored for forward compatibility.
+	}
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("read %s: %w", path, err)
+	}
+	return c, nil
+}

update/pkg/config/config_test.go

@@ -0,0 +1,117 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func writeConf(t *testing.T, content string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "update.conf")
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	return path
+}
+
+func TestLoadMissingReturnsEmptyConfig(t *testing.T) {
+	c, err := Load(filepath.Join(t.TempDir(), "does-not-exist.conf"))
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if c == nil {
+		t.Fatal("Load returned nil config")
+	}
+	if c.Server != "" || c.Channel != "" || c.MaintenanceWindow != "" || c.PubKey != "" {
+		t.Errorf("expected empty config, got %+v", c)
+	}
+}
+
+func TestLoadAllFields(t *testing.T) {
+	path := writeConf(t, `# comment line
+server = https://updates.example.com
+channel = stable
+maintenance_window = 03:00-05:00
+pubkey = /etc/kubesolo/pub.hex
+`)
+	c, err := Load(path)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if c.Server != "https://updates.example.com" {
+		t.Errorf("server: got %q", c.Server)
+	}
+	if c.Channel != "stable" {
+		t.Errorf("channel: got %q", c.Channel)
+	}
+	if c.MaintenanceWindow != "03:00-05:00" {
+		t.Errorf("maintenance_window: got %q", c.MaintenanceWindow)
+	}
+	if c.PubKey != "/etc/kubesolo/pub.hex" {
+		t.Errorf("pubkey: got %q", c.PubKey)
+	}
+}
+
+func TestLoadIgnoresUnknownKeys(t *testing.T) {
+	// Unknown keys must not be an error — supports forward-compat config
+	// fields added by newer agent versions.
+	path := writeConf(t, `server = https://x
+future_field = whatever
+channel = beta
+`)
+	c, err := Load(path)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if c.Server != "https://x" {
+		t.Errorf("server: got %q", c.Server)
+	}
+	if c.Channel != "beta" {
+		t.Errorf("channel: got %q", c.Channel)
+	}
+}
+
+func TestLoadStripsWhitespace(t *testing.T) {
+	path := writeConf(t, "   server   =   https://example   \n  channel=stable\n")
+	c, err := Load(path)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if c.Server != "https://example" {
+		t.Errorf("server: got %q (whitespace not stripped?)", c.Server)
+	}
+	if c.Channel != "stable" {
+		t.Errorf("channel: got %q", c.Channel)
+	}
+}
+
+func TestLoadIgnoresBlankAndCommentLines(t *testing.T) {
+	path := writeConf(t, `
+# this is a comment
+
+server = https://example
+   # indented comment
+channel = stable
+
+`)
+	c, err := Load(path)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if c.Server != "https://example" {
+		t.Errorf("server: got %q", c.Server)
+	}
+}
+
+func TestLoadRejectsMissingEquals(t *testing.T) {
+	// "noEqualsHere" with no '=' is a syntax error worth surfacing — likely
+	// indicates a corrupted config file.
+	path := writeConf(t, `server = https://example
+noEqualsHere
+`)
+	_, err := Load(path)
+	if err == nil {
+		t.Error("expected error on malformed line, got nil")
+	}
+}

update/pkg/config/version.go

@@ -0,0 +1,60 @@
+package config
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// CompareVersions compares two semver-ish version strings.
+//
+// Accepts "v1.2.3", "1.2.3", "v1.2.3-rc1" (suffix ignored), with missing
+// components defaulting to 0 ("v1" == "1.0.0"). Returns -1 if a < b, 0 if
+// equal, +1 if a > b. Returns an error if either argument can't be parsed
+// at all.
+//
+// Used by apply.go to enforce MinCompatibleVersion. Pre-release suffix
+// handling is deliberately simple — we ignore it, treating "v1.2.3-rc1"
+// equal to "v1.2.3". Edge case: production releases should never carry
+// a pre-release suffix, and dev releases are the consumer's responsibility.
+func CompareVersions(a, b string) (int, error) {
+	pa, err := parseVersion(a)
+	if err != nil {
+		return 0, fmt.Errorf("parse %q: %w", a, err)
+	}
+	pb, err := parseVersion(b)
+	if err != nil {
+		return 0, fmt.Errorf("parse %q: %w", b, err)
+	}
+	for i := 0; i < 3; i++ {
+		if pa[i] < pb[i] {
+			return -1, nil
+		}
+		if pa[i] > pb[i] {
+			return 1, nil
+		}
+	}
+	return 0, nil
+}
+
+func parseVersion(s string) ([3]int, error) {
+	var out [3]int
+	s = strings.TrimSpace(s)
+	s = strings.TrimPrefix(s, "v")
+	// Drop pre-release suffix: "1.2.3-rc1" -> "1.2.3"
+	if i := strings.IndexAny(s, "-+"); i >= 0 {
+		s = s[:i]
+	}
+	parts := strings.SplitN(s, ".", 3)
+	for i, p := range parts {
+		n, err := strconv.Atoi(p)
+		if err != nil {
+			return out, fmt.Errorf("component %q not numeric", p)
+		}
+		if n < 0 {
+			return out, fmt.Errorf("component %d negative", n)
+		}
+		out[i] = n
+	}
+	return out, nil
+}

update/pkg/config/version_test.go

@@ -0,0 +1,46 @@
+package config
+
+import "testing"
+
+func TestCompareVersions(t *testing.T) {
+	tests := []struct {
+		a, b string
+		want int
+	}{
+		{"v1.0.0", "v1.0.0", 0},
+		{"1.0.0", "v1.0.0", 0}, // 'v' prefix optional
+		{"v1.0.0", "v1.0.1", -1},
+		{"v1.0.1", "v1.0.0", 1},
+		{"v1.1.0", "v1.0.99", 1},
+		{"v2.0.0", "v1.99.99", 1},
+		{"v0.3.0-dev", "v0.3.0", 0},   // pre-release suffix ignored
+		{"v0.2.5", "v0.3.0", -1},
+		{"v0.3.0", "v0.2.999", 1},
+		{"v1.2", "v1.2.0", 0}, // missing component defaults to 0
+		{"v1", "v1.0.0", 0},
+	}
+	for _, tt := range tests {
+		got, err := CompareVersions(tt.a, tt.b)
+		if err != nil {
+			t.Errorf("CompareVersions(%q, %q): %v", tt.a, tt.b, err)
+			continue
+		}
+		if got != tt.want {
+			t.Errorf("CompareVersions(%q, %q) = %d, want %d", tt.a, tt.b, got, tt.want)
+		}
+	}
+}
+
+func TestCompareVersionsRejectsGarbage(t *testing.T) {
+	bad := []string{
+		"not-a-version",
+		"v.1.2",
+		"vabc",
+		"",
+	}
+	for _, s := range bad {
+		if _, err := CompareVersions(s, "v1.0.0"); err == nil {
+			t.Errorf("CompareVersions(%q, ...) accepted, want error", s)
+		}
+	}
+}

update/pkg/config/window.go

@@ -0,0 +1,95 @@
+package config
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Window is a parsed maintenance-window expression. Times are minutes since
+// midnight in the local timezone. When End < Start, the window wraps
+// midnight (e.g. 23:00-01:00 means 23:00 today through 01:00 tomorrow).
+//
+// The zero value (Start == End == 0) means "always allowed" — used for
+// the empty-string-meaning-no-window case.
+type Window struct {
+	Start int // minutes since midnight, [0, 1440)
+	End   int // minutes since midnight, [0, 1440)
+
+	// alwaysOpen distinguishes "no constraint" from "midnight to midnight"
+	// (the literal 00:00-00:00 window, which is a degenerate same-instant
+	// window). Set when ParseWindow is called with an empty string.
+	alwaysOpen bool
+}
+
+// AlwaysOpen returns true if this window imposes no constraint (the empty
+// string was parsed).
+func (w Window) AlwaysOpen() bool { return w.alwaysOpen }
+
+// ParseWindow parses "HH:MM-HH:MM" into a Window. Empty input returns an
+// AlwaysOpen window (no constraint). Whitespace around the input is tolerated.
+func ParseWindow(s string) (Window, error) {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return Window{alwaysOpen: true}, nil
+	}
+	parts := strings.SplitN(s, "-", 2)
+	if len(parts) != 2 {
+		return Window{}, fmt.Errorf("maintenance window %q: expected HH:MM-HH:MM", s)
+	}
+	start, err := parseHHMM(strings.TrimSpace(parts[0]))
+	if err != nil {
+		return Window{}, fmt.Errorf("maintenance window %q: start: %w", s, err)
+	}
+	end, err := parseHHMM(strings.TrimSpace(parts[1]))
+	if err != nil {
+		return Window{}, fmt.Errorf("maintenance window %q: end: %w", s, err)
+	}
+	return Window{Start: start, End: end}, nil
+}
+
+func parseHHMM(s string) (int, error) {
+	parts := strings.SplitN(s, ":", 2)
+	if len(parts) != 2 {
+		return 0, fmt.Errorf("%q: expected HH:MM", s)
+	}
+	h, err := strconv.Atoi(parts[0])
+	if err != nil || h < 0 || h > 23 {
+		return 0, fmt.Errorf("%q: invalid hour", s)
+	}
+	m, err := strconv.Atoi(parts[1])
+	if err != nil || m < 0 || m > 59 {
+		return 0, fmt.Errorf("%q: invalid minute", s)
+	}
+	return h*60 + m, nil
+}
+
+// Contains reports whether the given local time falls inside this window.
+// AlwaysOpen windows return true for any time.
+func (w Window) Contains(t time.Time) bool {
+	if w.alwaysOpen {
+		return true
+	}
+	now := t.Hour()*60 + t.Minute()
+	if w.Start == w.End {
+		// Degenerate: zero-length window. Never matches.
+		return false
+	}
+	if w.Start < w.End {
+		// Same-day window: [Start, End)
+		return now >= w.Start && now < w.End
+	}
+	// Wrapping window: [Start, 1440) ∪ [0, End)
+	return now >= w.Start || now < w.End
+}
+
+// String renders the window in HH:MM-HH:MM form for display. AlwaysOpen
+// renders as "always".
+func (w Window) String() string {
+	if w.alwaysOpen {
+		return "always"
+	}
+	return fmt.Sprintf("%02d:%02d-%02d:%02d",
+		w.Start/60, w.Start%60, w.End/60, w.End%60)
+}

update/pkg/config/window_test.go

@@ -0,0 +1,120 @@
+package config
+
+import (
+	"testing"
+	"time"
+)
+
+func at(hour, min int) time.Time {
+	return time.Date(2026, 1, 1, hour, min, 0, 0, time.UTC)
+}
+
+func TestParseWindowEmpty(t *testing.T) {
+	w, err := ParseWindow("")
+	if err != nil {
+		t.Fatalf("empty window: %v", err)
+	}
+	if !w.AlwaysOpen() {
+		t.Error("empty input should produce AlwaysOpen window")
+	}
+	if !w.Contains(at(3, 0)) {
+		t.Error("AlwaysOpen window should contain any time")
+	}
+	if !w.Contains(at(23, 59)) {
+		t.Error("AlwaysOpen window should contain end-of-day")
+	}
+}
+
+func TestParseWindowSameDay(t *testing.T) {
+	w, err := ParseWindow("03:00-05:00")
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	tests := []struct {
+		hour, min int
+		want      bool
+	}{
+		{2, 59, false}, // just before
+		{3, 0, true},   // start (inclusive)
+		{4, 30, true},  // middle
+		{4, 59, true},  // just before end
+		{5, 0, false},  // end (exclusive)
+		{15, 0, false}, // far outside
+	}
+	for _, tt := range tests {
+		got := w.Contains(at(tt.hour, tt.min))
+		if got != tt.want {
+			t.Errorf("Contains(%02d:%02d) = %v, want %v", tt.hour, tt.min, got, tt.want)
+		}
+	}
+}
+
+func TestParseWindowWrappingMidnight(t *testing.T) {
+	w, err := ParseWindow("23:00-01:00")
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	tests := []struct {
+		hour, min int
+		want      bool
+	}{
+		{22, 59, false}, // just before
+		{23, 0, true},   // start (inclusive)
+		{23, 30, true},  // night-before
+		{0, 0, true},    // midnight
+		{0, 30, true},   // early morning
+		{0, 59, true},   // just before end
+		{1, 0, false},   // end (exclusive)
+		{12, 0, false},  // far outside (noon)
+	}
+	for _, tt := range tests {
+		got := w.Contains(at(tt.hour, tt.min))
+		if got != tt.want {
+			t.Errorf("Contains(%02d:%02d) wrapping = %v, want %v", tt.hour, tt.min, got, tt.want)
+		}
+	}
+}
+
+func TestParseWindowDegenerateZeroLength(t *testing.T) {
+	// 05:00-05:00 is a zero-length window — should never match. Different
+	// from "always" (empty string).
+	w, err := ParseWindow("05:00-05:00")
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	if w.AlwaysOpen() {
+		t.Error("05:00-05:00 must not be AlwaysOpen")
+	}
+	if w.Contains(at(5, 0)) {
+		t.Error("zero-length window must not contain its own boundary")
+	}
+}
+
+func TestParseWindowRejectsBadInput(t *testing.T) {
+	bad := []string{
+		"notatime",
+		"03:00",        // no end
+		"03:00-",       // empty end
+		"03:00-05",     // missing minutes
+		"24:00-05:00",  // hour out of range
+		"03:60-05:00",  // minute out of range
+		"abc:00-05:00", // non-numeric
+	}
+	for _, s := range bad {
+		_, err := ParseWindow(s)
+		if err == nil {
+			t.Errorf("ParseWindow(%q) accepted, want error", s)
+		}
+	}
+}
+
+func TestWindowString(t *testing.T) {
+	w, _ := ParseWindow("03:05-05:45")
+	if w.String() != "03:05-05:45" {
+		t.Errorf("String = %q, want 03:05-05:45", w.String())
+	}
+	always, _ := ParseWindow("")
+	if always.String() != "always" {
+		t.Errorf("AlwaysOpen.String = %q, want 'always'", always.String())
+	}
+}

update/pkg/image/image.go

@@ -35,6 +35,24 @@ type UpdateMetadata struct {
 	MetadataSigURL  string `json:"metadata_sig_url,omitempty"`
 	ReleaseNotes    string `json:"release_notes,omitempty"`
 	ReleaseDate     string `json:"release_date,omitempty"`
+
+	// Channel labels this artifact ("stable", "beta", "edge", ...). The agent
+	// refuses metadata whose channel doesn't match the locally-configured
+	// one. Empty in metadata means "no channel constraint, accept anything".
+	Channel string `json:"channel,omitempty"`
+
+	// MinCompatibleVersion is the lowest version that can upgrade to this
+	// one. The agent refuses to apply if the currently-running version is
+	// below this. Used for stepping-stone migrations (e.g. 0.2.x -> 0.3.x
+	// requires 0.2.5+ to land the state-file format first). Empty means
+	// "any source version OK".
+	MinCompatibleVersion string `json:"min_compatible_version,omitempty"`
+
+	// Architecture restricts this artifact to a specific GOARCH ("amd64",
+	// "arm64"). Empty means the artifact is arch-agnostic — which is rare
+	// since the kernel + initramfs are arch-specific; this should normally
+	// be populated by the build pipeline.
+	Architecture string `json:"architecture,omitempty"`
 }
 
 // StagedImage represents downloaded and verified update files.