fix(snapshot): fall back to non-sparse tar when segment map exceeds PAX cap (#23)

Go's archive/tar caps the encoded PAX block at maxSpecialFileSize =
1<<20 (see archive/tar/format.go). Our sparse encoding stuffs the
entire sparse-segment list into a single COCOON.sparse.map PAX record,
which is fine for typical disk images but trips the cap when the
underlying file is highly fragmented.

Reproduced 2026-05-05 against a live cocoon Windows VM running the
simular-pro-agent-runtime 1.8.0 build (Electron app, real Firebase
WebSocket signed-in): the agent's V8 heap + IPC + WebSocket pools
fragment the guest memory enough that memory-ranges yields tens of
thousands of sparse segments; the resulting JSON exceeds 1MB and
`cocoon snapshot export` fails with:

    Error: write archive: write header memory-ranges:
        archive/tar: header field too long

vk-cocoon then loops indefinitely retrying the push (see
project_cocoon_sparse_pax_overflow memory note in vm-service tree),
silently breaking hibernate.

The fix detects the overflow up front (mapJSON > ~800KB, well below
the 1MB cap) and falls back to writing the file as a regular,
non-sparse tar entry. This loses the sparse-export size advantage on
the affected file (memory-ranges can be GB-scale), but those files are
not the dominant size driver in a snapshot — and a successful larger
push beats a hung loop. Empirical Go-tar limit measured: 30k segments
(~736KB JSON) succeed, 50k (~1.2MB) fail.

Reader path is unchanged. The fallback emits a standard tar entry that
existing extract logic already handles via the non-sparse code path.

Tests:
  - TestTarFileMaybeSparse_FallsBackOnLargeMap — verifies the fallback
    triggers when the map exceeds the cap and that no PAX sparse
    records are written.
  - TestTarFileMaybeSparse_FallbackRoundTrip — extract of a
    fallback-encoded file matches the original byte-for-byte.
  - TestTarFileMaybeSparse_PreservesSparsePathForSmallMaps — sanity
    that small fragmentation still uses the sparse encoding.

Author: tonicmuroq

utils/tar_sparse_linux.go

@@ -11,6 +11,9 @@ import (
 	"strconv"
 )
 
+// Sparse-map JSON cap (margin under tar's 1MB PAX block); var so tests can override.
+var maxSparseMapJSONSize = 800 * 1024
+
 // tarFileMaybeSparse writes a file to tw using our custom COCOON.sparse PAX
 // format when the file has holes (detected via SEEK_HOLE/SEEK_DATA).
 //
@@ -21,6 +24,7 @@ import (
 //   - the file is empty or very small
 //   - SEEK_HOLE/SEEK_DATA fails (unsupported filesystem)
 //   - the file has no holes (not actually sparse)
+//   - the segment-map JSON would exceed tar's 1MB PAX cap
 func tarFileMaybeSparse(tw *tar.Writer, path, nameInTar string) error {
 	f, err := os.Open(path) //nolint:gosec
 	if err != nil {
@@ -41,28 +45,27 @@ func tarFileMaybeSparse(tw *tar.Writer, path, nameInTar string) error {
 	segments, err := scanDataSegments(int(f.Fd()), size)
 	if err != nil {
 		// SEEK_HOLE/SEEK_DATA unsupported (e.g. tmpfs, NFS). Fall back.
-		if _, seekErr := f.Seek(0, io.SeekStart); seekErr != nil {
-			return fmt.Errorf("seek %s: %w", path, seekErr)
-		}
-		return tarFileFrom(tw, f, fi, nameInTar)
+		return rewindAndTarFull(tw, f, fi, path, nameInTar)
 	}
 
 	var dataSize int64
 	for _, seg := range segments {
 		dataSize += seg.Length
 	}
 	if dataSize == size {
-		if _, seekErr := f.Seek(0, io.SeekStart); seekErr != nil {
-			return fmt.Errorf("seek %s: %w", path, seekErr)
-		}
-		return tarFileFrom(tw, f, fi, nameInTar)
+		return rewindAndTarFull(tw, f, fi, path, nameInTar)
 	}
 
 	mapJSON, err := json.Marshal(segments)
 	if err != nil {
 		return fmt.Errorf("marshal sparse map for %s: %w", path, err)
 	}
 
+	// Segment-map JSON exceeds tar's 1MB PAX cap. Fall back to non-sparse.
+	if len(mapJSON) > maxSparseMapJSONSize {
+		return rewindAndTarFull(tw, f, fi, path, nameInTar)
+	}
+
 	hdr, err := tar.FileInfoHeader(fi, "")
 	if err != nil {
 		return fmt.Errorf("tar header for %s: %w", path, err)
@@ -89,3 +92,11 @@ func tarFileMaybeSparse(tw *tar.Writer, path, nameInTar string) error {
 
 	return nil
 }
+
+// rewindAndTarFull seeks f to the start and writes it as a non-sparse tar entry.
+func rewindAndTarFull(tw *tar.Writer, f *os.File, fi os.FileInfo, path, nameInTar string) error {
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		return fmt.Errorf("seek %s: %w", path, err)
+	}
+	return tarFileFrom(tw, f, fi, nameInTar)
+}

utils/tar_sparse_linux_test.go

@@ -0,0 +1,142 @@
+//go:build linux
+
+package utils
+
+import (
+	"archive/tar"
+	"bytes"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// writeSparseFile alternates numSegments data regions of blockSize with equal-sized holes.
+func writeSparseFile(t *testing.T, path string, numSegments, blockSize int) int64 {
+	t.Helper()
+	f, err := os.Create(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close() //nolint:errcheck
+	for i := range numSegments {
+		offset := int64(i) * int64(blockSize) * 2
+		data := bytes.Repeat([]byte{byte((i % 250) + 1)}, blockSize)
+		if _, err := f.WriteAt(data, offset); err != nil {
+			t.Fatal(err)
+		}
+	}
+	fi, err := f.Stat()
+	if err != nil {
+		t.Fatal(err)
+	}
+	return fi.Size()
+}
+
+// Segment-map JSON over the cap → tarFileMaybeSparse falls back to non-sparse.
+func TestTarFileMaybeSparse_FallsBackOnLargeMap(t *testing.T) {
+	orig := maxSparseMapJSONSize
+	maxSparseMapJSONSize = 4 * 1024
+	t.Cleanup(func() { maxSparseMapJSONSize = orig })
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "memory-ranges")
+	logicalSize := writeSparseFile(t, path, 200, 4096)
+
+	var buf bytes.Buffer
+	tw := tar.NewWriter(&buf)
+	if err := tarFileMaybeSparse(tw, path, "memory-ranges"); err != nil {
+		t.Fatalf("tarFileMaybeSparse: %v (expected fallback to succeed)", err)
+	}
+	if err := tw.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	tr := tar.NewReader(&buf)
+	hdr, err := tr.Next()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if hdr.Name != "memory-ranges" {
+		t.Fatalf("name = %q, want memory-ranges", hdr.Name)
+	}
+	if _, ok := hdr.PAXRecords[paxSparseMap]; ok {
+		t.Errorf("PAX %s present, expected non-sparse fallback", paxSparseMap)
+	}
+	if hdr.Size != logicalSize {
+		t.Errorf("hdr.Size = %d, want logical size %d", hdr.Size, logicalSize)
+	}
+}
+
+// Fallback round-trip: extracted file matches the original byte-for-byte (holes serialised as zeros).
+func TestTarFileMaybeSparse_FallbackRoundTrip(t *testing.T) {
+	orig := maxSparseMapJSONSize
+	maxSparseMapJSONSize = 4 * 1024
+	t.Cleanup(func() { maxSparseMapJSONSize = orig })
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "memory-ranges")
+	writeSparseFile(t, path, 200, 4096)
+
+	var buf bytes.Buffer
+	tw := tar.NewWriter(&buf)
+	if err := tarFileMaybeSparse(tw, path, "memory-ranges"); err != nil {
+		t.Fatal(err)
+	}
+	if err := tw.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	dst := t.TempDir()
+	if err := ExtractTar(dst, &buf); err != nil {
+		t.Fatalf("ExtractTar: %v", err)
+	}
+
+	got, err := os.ReadFile(filepath.Join(dst, "memory-ranges"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	want, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(got, want) {
+		t.Errorf("extracted content differs (len got=%d want=%d)", len(got), len(want))
+	}
+}
+
+// Small fragmentation still takes the sparse path; fallback only on PAX overflow.
+func TestTarFileMaybeSparse_PreservesSparsePathForSmallMaps(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "small-sparse")
+	f, err := os.Create(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := f.WriteAt(bytes.Repeat([]byte{0xAA}, 4096), 0); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := f.WriteAt(bytes.Repeat([]byte{0xBB}, 4096), 1<<20); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	var buf bytes.Buffer
+	tw := tar.NewWriter(&buf)
+	if err := tarFileMaybeSparse(tw, path, "small-sparse"); err != nil {
+		t.Fatal(err)
+	}
+	if err := tw.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	tr := tar.NewReader(&buf)
+	hdr, err := tr.Next()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := hdr.PAXRecords[paxSparseMap]; !ok {
+		t.Errorf("expected sparse PAX record for small fragmentation, got none")
+	}
+}