@@ -0,0 +1,5 @@
+---
+"ftw": patch
+---
+
+Start FTW when one old history file cannot be read. FTW renames the file with an `.unreadable` suffix and keeps it, imports the other days, keeps that day's older copy for history views, and lists the file under `unreadable_cold_files` in the history health report.
@@ -0,0 +1,181 @@
+package state
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"slices"
+	"testing"
+	"time"
+)
+
+func unreadableBucket(at time.Time, v float64) metricBucket {
+	return metricBucket{Driver: "meter", Metric: "grid_w", BucketSummary: BucketSummary{StartMS: at.UnixMilli(), ResolutionMS: ArchiveResolutionMS, FirstMS: at.UnixMilli(), LastMS: at.UnixMilli() + 1000, N: 1, Sum: v, Min: v, Max: v, Last: v}}
+}
+
+// unreadableColdFixture opens a store the way main.go does, with the same
+// cold folder for reads and for the boot import, so runtime readers see
+// whatever the import leaves behind.
+func unreadableColdFixture(t *testing.T) (*Store, string, time.Time) {
+	t.Helper()
+	s := freshStore(t)
+	if err := s.EnableHistoryAggregation(); err != nil {
+		t.Fatal(err)
+	}
+	cold := t.TempDir()
+	s.coldDir = cold
+	return s, cold, time.Now().UTC().Add(-40 * 24 * time.Hour).Truncate(24 * time.Hour)
+}
+
+func dayFile(t *testing.T, cold string, day time.Time, suffix string) string {
+	t.Helper()
+	path := filepath.Join(cold, day.Format("2006/01"), day.Format("02")+suffix)
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+func assertFile(t *testing.T, path string, want bool) {
+	t.Helper()
+	_, err := os.Stat(path)
+	if want && err != nil {
+		t.Fatalf("%s must stay: %v", path, err)
+	}
+	if !want && !os.IsNotExist(err) {
+		t.Fatalf("%s must be gone: %v", path, err)
+	}
+}
+
+func listedUnreadable(s *Store) []string {
+	listed, _ := s.HistoryBackend()["unreadable_cold_files"].([]string)
+	return listed
+}
+
+// One damaged bucket day must not stop boot-time absorb of the other days.
+// main.go exits on an AbsorbColdHistory error, and the file would stay, so
+// every restart would fail the same way. The kept file must also leave the
+// day's history reads working.
+func TestAbsorbColdHistorySkipsUnreadableBucketFile(t *testing.T) {
+	damage := map[string]func(t *testing.T, path string){
+		"truncated": func(t *testing.T, path string) {
+			info, err := os.Stat(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := os.Truncate(path, info.Size()/2); err != nil {
+				t.Fatal(err)
+			}
+		},
+		"no read permission": func(t *testing.T, path string) {
+			if os.Geteuid() == 0 {
+				t.Skip("root reads files without permission")
+			}
+			if err := os.Chmod(path, 0); err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() { _ = os.Chmod(path, 0o644); _ = os.Chmod(path+unreadableColdSuffix, 0o644) })
+		},
+	}
+	for name, spoil := range damage {
+		t.Run(name, func(t *testing.T) {
+			s, cold, good := unreadableColdFixture(t)
+			bad := good.Add(24 * time.Hour)
+			hour := good.Add(3 * time.Hour)
+			badHour := bad.Add(5 * time.Hour)
+			goodPath := dayFile(t, cold, good, ".buckets.parquet")
+			badPath := dayFile(t, cold, bad, ".buckets.parquet")
+			legacyPath := dayFile(t, cold, bad, ".legacy-buckets.parquet")
+			if err := writeTestBuckets(goodPath, []metricBucket{unreadableBucket(hour, 10)}); err != nil {
+				t.Fatal(err)
+			}
+			if err := writeTestBuckets(badPath, []metricBucket{unreadableBucket(bad, 5)}); err != nil {
+				t.Fatal(err)
+			}
+			spoil(t, badPath)
+			// The older copy of the damaged day is readable and serves it.
+			if err := writeTestBuckets(legacyPath, []metricBucket{unreadableBucket(badHour, 7)}); err != nil {
+				t.Fatal(err)
+			}
+
+			for boot := 1; boot <= 2; boot++ {
+				if err := s.AbsorbColdHistory(context.Background(), cold); err != nil {
+					t.Fatalf("boot %d: AbsorbColdHistory: %v", boot, err)
+				}
+				assertFile(t, goodPath, false)
+				assertFile(t, badPath, false)
+				assertFile(t, badPath+unreadableColdSuffix, true)
+				assertFile(t, legacyPath, true)
+				if want := bad.Format("2006/01/02") + ".buckets.parquet" + unreadableColdSuffix; !slices.Equal(listedUnreadable(s), []string{want}) {
+					t.Fatalf("boot %d: unreadable_cold_files = %v, want [%s]", boot, listedUnreadable(s), want)
+				}
+				for _, want := range []struct {
+					at time.Time
+					v  float64
+				}{{hour, 10}, {badHour, 7}} {
+					points, err := s.LoadSeriesBucketsOrRaw("meter", "grid_w", want.at.UnixMilli(), want.at.UnixMilli()+HistoryHourResolutionMS-1, 0)
+					if err != nil || len(points) != 1 || points[0].V != want.v {
+						t.Fatalf("boot %d: hour %s = %+v, %v; want one point of %v", boot, want.at, points, err, want.v)
+					}
+				}
+				from, to := good.UnixMilli(), bad.Add(48*time.Hour).UnixMilli()
+				for _, maxPoints := range []int{0, 200} {
+					for _, metric := range []string{"grid_w", "other_w"} {
+						if _, err := s.LoadSeriesBucketsOrRaw("meter", metric, from, to, maxPoints); err != nil {
+							t.Fatalf("boot %d: %s range over the damaged day, maxPoints=%d: %v", boot, metric, maxPoints, err)
+						}
+					}
+				}
+				now := time.Now()
+				if _, err := s.LoadSeriesBuckets("meter", "grid_w", now.Add(-365*24*time.Hour).UnixMilli(), now.UnixMilli(), 365); err != nil {
+					t.Fatalf("boot %d: year chart: %v", boot, err)
+				}
+			}
+		})
+	}
+}
+
+// An operator who puts back a good copy of the damaged file must get a
+// clean boot. Had the legacy copy imported the same hour, the restored file
+// would conflict with it and stop boot again.
+func TestAbsorbColdHistoryImportsRestoredBucketFile(t *testing.T) {
+	s, cold, day := unreadableColdFixture(t)
+	at := day.Add(2 * time.Hour)
+	orig := dayFile(t, cold, day, ".buckets.parquet")
+	legacy := dayFile(t, cold, day, ".legacy-buckets.parquet")
+	full := []metricBucket{unreadableBucket(at, 3), unreadableBucket(at.Add(time.Minute), 4)}
+	if err := writeTestBuckets(orig, full); err != nil {
+		t.Fatal(err)
+	}
+	good, err := os.ReadFile(orig)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Truncate(orig, int64(len(good)/2)); err != nil {
+		t.Fatal(err)
+	}
+	if err := writeTestBuckets(legacy, full[:1]); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.AbsorbColdHistory(context.Background(), cold); err != nil {
+		t.Fatalf("first boot: %v", err)
+	}
+	if err := os.Remove(orig + unreadableColdSuffix); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(orig, good, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.AbsorbColdHistory(context.Background(), cold); err != nil {
+		t.Fatalf("boot after restoring the file: %v", err)
+	}
+	assertFile(t, orig, false)
+	assertFile(t, legacy, false)
+	if listed := listedUnreadable(s); len(listed) != 0 {
+		t.Fatalf("unreadable_cold_files = %v after recovery", listed)
+	}
+	points, err := s.LoadSeriesBucketsOrRaw("meter", "grid_w", at.UnixMilli(), at.UnixMilli()+HistoryHourResolutionMS-1, 0)
+	if err != nil || len(points) != 1 || points[0].N != 2 {
+		t.Fatalf("restored hour = %+v, %v; want one point from both minutes", points, err)
+	}
+}
@@ -9,6 +9,7 @@ import (
 	"math"
 	"os"
 	"path/filepath"
+	"slices"
 	"strconv"
 	"strings"
 	"time"
@@ -200,6 +201,13 @@ func (s *Store) RetireRawHistory(ctx context.Context) error {
 // goes with them, and so does a sample day whose hourly summary receipt
 // matches the file. Other sample days stay readable until the background
 // rollup summarizes them. Diagnostics files are left in place.
+//
+// An unreadable bucket file never stops boot. It moves aside under
+// unreadableColdSuffix, out of every reader's glob, so reads for that day
+// still work. It stays on disk, and HistoryBackend lists it. The day's legacy
+// copy stays on disk unimported and serves reads. A good copy of the original
+// restored under its normal name imports on the next boot, and the legacy
+// copy then goes without a conflict.
 func (s *Store) AbsorbColdHistory(ctx context.Context, cold string) error {
 	if s == nil || s.history == nil || strings.TrimSpace(cold) == "" {
 		return nil
@@ -213,19 +221,49 @@ func (s *Store) AbsorbColdHistory(ctx context.Context, cold string) error {
 		return err
 	}
 	var imported int
+	unreadable := map[string]bool{}
+	// held lists files kept at their normal name: an unreadable file that
+	// could not move aside, or the legacy copy of an unreadable original.
+	held := map[string]bool{}
+	skip := func(path string, err error) {
+		unreadable[path] = true
+		aside := path + unreadableColdSuffix
+		if _, statErr := os.Lstat(aside); errors.Is(statErr, os.ErrNotExist) {
+			renameErr := os.Rename(path, aside)
+			if renameErr == nil {
+				slog.Warn("history bucket file unreadable; moved aside", "path", aside, "err", err)
+				return
+			}
+			slog.Warn("history bucket file could not move aside", "path", path, "err", renameErr)
+		}
+		slog.Warn("history bucket file unreadable; kept in place", "path", path, "err", err)
+		held[path] = true
+	}
 	for _, path := range paths {
 		if err := ctx.Err(); err != nil {
 			return err
 		}
 		if strings.Contains(path, ".legacy-buckets.") {
 			original := strings.Replace(path, ".legacy-buckets.parquet", ".buckets.parquet", 1)
-			if _, statErr := os.Stat(original); statErr == nil {
+			if _, statErr := os.Stat(original); statErr == nil && !unreadable[original] {
+				continue
+			}
+			// Importing these hours would conflict with a good copy of the
+			// original restored later, and stop that boot. Keep the file;
+			// it serves reads for the day until then.
+			if _, statErr := os.Lstat(original + unreadableColdSuffix); statErr == nil || unreadable[original] {
+				slog.Warn("history legacy bucket file kept while its original is unreadable", "path", path)
+				held[path] = true
 				continue
 			}
 		}
 		digest, err := historyFileHashContext(ctx, path)
 		if err != nil {
-			return err
+			if ctx.Err() != nil {
+				return ctx.Err()
+			}
+			skip(path, err)
+			continue
 		}
 		receipt := "plain-archive:" + digest
 		hours := map[string]*namedHour{}
@@ -240,7 +278,11 @@ func (s *Store) AbsorbColdHistory(ctx context.Context, cold string) error {
 			h.sources = append(h.sources, b.BucketSummary)
 			return nil
 		}); err != nil {
-			return fmt.Errorf("read %s: %w", filepath.Base(path), err)
+			if ctx.Err() != nil {
+				return ctx.Err()
+			}
+			skip(path, err)
+			continue
 		}
 		if err := s.writeHourBuckets(ctx, hours, receipt); err != nil {
 			return err
@@ -251,20 +293,50 @@ func (s *Store) AbsorbColdHistory(ctx context.Context, cold string) error {
 	if err != nil {
 		return err
 	}
+	sampleDays := len(keep)
+	// Earlier boots moved unreadable files aside; list them on every boot.
+	aside, err := filepath.Glob(filepath.Join(cold, "[0-9][0-9][0-9][0-9]", "[0-9][0-9]", "[0-9][0-9].*"+unreadableColdSuffix))
+	if err != nil {
+		return err
+	}
+	var kept []string
+	for _, path := range aside {
+		keep[path] = true
+		kept = append(kept, coldRel(path))
+	}
+	for path := range held {
+		keep[path] = true
+		if unreadable[path] {
+			kept = append(kept, coldRel(path))
+		}
+	}
+	slices.Sort(kept)
+	s.maintenanceStatusMu.Lock()
+	s.coldUnreadable = kept
+	s.maintenanceStatusMu.Unlock()
 	if err := removeColdHistory(cold, keep); err != nil {
 		return err
 	}
 	removed, err := removeRetiredHistory(s.historyPath)
 	if err != nil {
 		return err
 	}
-	if len(keep) > 0 {
-		slog.Warn("history sample days kept until they have hourly summaries", "days", len(keep))
+	if sampleDays > 0 {
+		slog.Warn("history sample days kept until they have hourly summaries", "days", sampleDays)
 	}
 	slog.Info("history cold files absorbed", "days", imported, "retired_files", removed)
 	return nil
 }
 
+// unreadableColdSuffix marks a bucket file that failed to read. The name no
+// longer ends in .parquet, so no reader, importer or converter opens it.
+const unreadableColdSuffix = ".unreadable"
+
+// coldRel names a cold file as YYYY/MM/<file>.
+func coldRel(path string) string {
+	return filepath.Base(filepath.Dir(filepath.Dir(path))) + "/" + filepath.Base(filepath.Dir(path)) + "/" + filepath.Base(path)
+}
+
 // A sample day counts as absorbed only through the summary receipt for this
 // exact file. 2.x wrote these days and never summarized them.
 func (s *Store) unsummarizedSampleDays(ctx context.Context, cold string) (map[string]bool, error) {
 
@@ -13,6 +13,7 @@ import (
 	"math"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	"time"
 
@@ -463,6 +464,11 @@ func historyFloatBits(value float64) uint64 {
 func (s *Store) HistoryBackend() map[string]any {
 	info := map[string]any{"engine": "sqlite", "archive": "sqlite", "file": filepath.Base(s.historyPath), "writer": s.HistoryWriterStatus(), "migration": s.HistoryMigrationStatus(), "series_hour": s.SeriesHourBackfillStatus()}
 	info["maintenance"] = s.HistoryMaintenanceStatus()
+	s.maintenanceStatusMu.Lock()
+	if len(s.coldUnreadable) > 0 {
+		info["unreadable_cold_files"] = slices.Clone(s.coldUnreadable)
+	}
+	s.maintenanceStatusMu.Unlock()
 	if s.aggregateHistory.Load() {
 		info["policy"] = map[string]any{"id": "sqlite-v1", "recent_resolution_ms": HistoryResolutionMS, "recent_retention_hours": int(plainTenSecondKeep.Hours()), "archive_resolution_ms": ArchiveResolutionMS, "archive_minute_days": int(plainMinuteKeep.Hours() / 24), "older_resolution_ms": HistoryHourResolutionMS, "detailed_retention_days": int(plainHourKeep.Hours() / 24)}
 	}
 
@@ -87,6 +87,7 @@ type Store struct {
 
 	maintenanceStatusMu sync.Mutex
 	maintenanceStatus   HistoryMaintenanceStatus
+	coldUnreadable      []string // guarded by maintenanceStatusMu
 	// offlineBackup is set by OpenBackupSource. Live Core backups yield
 	// between copy batches so goal and control writes stay within latency
 	// limits; the offline helper must not inherit that 100 ms live pause.
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"ftw": patch
 +---
++
 +Start FTW when one old history file cannot be read. FTW renames the file with an `.unreadable` suffix and keeps it, imports the other days, keeps that day's older copy for history views, and lists the file under `unreadable_cold_files` in the history health report.