feat: allow replicas on full disks reclaim the space and squash all data into the heads

cmd/local/longhornctl-local.go

@@ -52,6 +52,7 @@ func newCmdLonghornctlLocal() *cobra.Command {
 			Message: "Operation Commands:",
 			Commands: []*cobra.Command{
 				localsubcmd.NewCmdTrim(globalOpts),
+				localsubcmd.NewCmdRecover(globalOpts),
 			},
 		},
 		{

cmd/local/subcmd/recover.go

@@ -0,0 +1,77 @@
+package subcmd
+
+import (
+	"os"
+
+	"github.com/pkg/errors"
+	"github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+
+	"github.com/longhorn/cli/pkg/consts"
+	"github.com/longhorn/cli/pkg/types"
+	"github.com/longhorn/cli/pkg/utils"
+
+	localRep "github.com/longhorn/cli/pkg/local/replica"
+)
+
+func NewCmdRecover(globalOpts *types.GlobalCmdOptions) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   consts.SubCmdRecover,
+		Short: "Longhorn recovery operations",
+	}
+
+	utils.SetGlobalOptionsLocal(cmd, globalOpts)
+	cmd.AddCommand(newCmdRecoverReplica(globalOpts))
+
+	return cmd
+}
+
+func newCmdRecoverReplica(globalOpts *types.GlobalCmdOptions) *cobra.Command {
+	var localRecoverer = localRep.Recoverer{}
+
+	cmd := &cobra.Command{
+		Use:   consts.SubCmdReplica,
+		Short: "Recover disk space for a single v1 replica",
+		Long: `This command reclaims disk space on a single Longhorn v1 replica directory by:
+- scanning its snapshot chain for sectors that are fully overlapped (shadowed) by newer snapshots or the volume head,
+- then punching holes in the older, now-redundant snapshot files.
+It is particularly useful after extensive snapshot churn, where older snapshot files continue to consume disk space even though every sector they hold has been superseded elsewhere in the chain.
+
+To use this command, specify the following option:
+- --` + consts.CmdOptReplicaDir + `: The path to the replica data directory you wish to recover.
+- --dryRun (default false): set to true, if you wish to preview changes before applying them.
+
+WARNING: This command modifies snapshot files in place via hole punching. Ensure the replica is not attached to a running engine before recovering it, and review the dry-run output carefully before confirming.`,
+
+		Run: func(cmd *cobra.Command, args []string) {
+			localRecoverer.LogLevel = globalOpts.LogLevel
+			localRecoverer.Namespace = os.Getenv(consts.EnvLonghornNamespace)
+
+			utils.CheckErr(localRecoverer.Validate())
+
+			err := localRecoverer.Init()
+			if err != nil {
+				utils.CheckErr(errors.Wrapf(err, "Failed to initialize recoverer for replica directory %s", localRecoverer.ReplicaDirectory))
+			}
+			defer func() {
+				_ = localRecoverer.Close()
+			}()
+			err = localRecoverer.Run()
+
+			if err != nil {
+				utils.CheckErr(errors.Wrapf(err, "Failed to run recoverer for replica directory %s", localRecoverer.ReplicaDirectory))
+			}
+
+			if localRecoverer.Recovered {
+				logrus.Infof("Successfully recovered replica directory %s", localRecoverer.ReplicaDirectory)
+			}
+		},
+	}
+
+	utils.SetGlobalOptionsLocal(cmd, globalOpts)
+
+	cmd.Flags().StringVar(&localRecoverer.ReplicaDirectory, consts.CmdOptReplicaDir, os.Getenv(consts.EnvReplicaDirectory), "Path to the replica data directory to recover.")
+	cmd.Flags().BoolVar(&localRecoverer.DryRun, "dry-run", false, "preview changes without applying them")
+
+	return cmd
+}

go.mod

@@ -3,13 +3,18 @@ module github.com/longhorn/cli
 go 1.26.0
 
 require (
+	github.com/dustin/go-humanize v1.0.1
 	github.com/longhorn/go-common-libs v0.0.0-20260730002911-add09e6eb92c
+	github.com/longhorn/longhorn-engine v1.13.0-dev-20260503.0.20260811002413-f97d5257ac06
 	github.com/longhorn/longhorn-manager v1.12.1
+	github.com/longhorn/sparse-tools v0.0.0-20260423074222-280e61de741a
 	github.com/otiai10/copy v1.14.1
 	github.com/pkg/errors v0.9.1
+	github.com/rancher/go-fibmap v0.0.0-20160418233256-5fc9f8c1ed47
 	github.com/sirupsen/logrus v1.10.1
 	github.com/spf13/cobra v1.10.2
 	github.com/stretchr/testify v1.12.1
+	golang.org/x/sys v0.47.0
 	gopkg.in/yaml.v3 v3.0.1
 	k8s.io/api v0.36.4
 	k8s.io/apimachinery v0.36.4
@@ -77,6 +82,7 @@ require (
 	github.com/kr/text v0.2.0 // indirect
 	github.com/liggitt/tabwriter v0.0.0-20181228230101-89fcab3d43de // indirect
 	github.com/longhorn/go-spdk-helper v0.9.0 // indirect
+	github.com/longhorn/types v0.0.0-20260810232958-141f76734364 // indirect
 	github.com/lufia/plan9stats v0.0.0-20251013123823-9fd1530e3ec3 // indirect
 	github.com/lxzan/gws v1.8.9 // indirect
 	github.com/mitchellh/go-ps v1.0.0 // indirect
@@ -111,11 +117,12 @@ require (
 	golang.org/x/net v0.57.0 // indirect
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/sync v0.22.0 // indirect
-	golang.org/x/sys v0.47.0 // indirect
 	golang.org/x/term v0.45.0 // indirect
 	golang.org/x/text v0.40.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
-	google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260904194346-d0f1323225a4 // indirect
+	google.golang.org/grpc v1.83.1 // indirect
+	google.golang.org/protobuf v1.36.12 // indirect
 	gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect

go.sum

@@ -16,6 +16,8 @@ github.com/blang/semver/v4 v4.0.0 h1:1PFHFE6yCCTv8C1TeyNNarDzntLi7wMI5i/pzqYIsAM
 github.com/blang/semver/v4 v4.0.0/go.mod h1:IbckMUScFkM3pff0VJDNKRiT6TG/YpiHIM2yvyW5YoQ=
 github.com/c9s/goprocinfo v0.0.0-20210130143923-c95fcf8c64a8 h1:SjZ2GvvOononHOpK84APFuMvxqsk3tEIaKH/z4Rpu3g=
 github.com/c9s/goprocinfo v0.0.0-20210130143923-c95fcf8c64a8/go.mod h1:uEyr4WpAH4hio6LFriaPkL938XnrvLpNPmQHBdrmbIE=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/chai2010/gettext-go v1.0.2 h1:1Lwwip6Q2QGsAdl/ZKPCwTe9fe0CjlUbqj5bFNSjIRk=
 github.com/chai2010/gettext-go v1.0.2/go.mod h1:y+wnP2cHYaVj19NZhYKAwEMH2CI1gNHeQQ+5AjwawxA=
 github.com/cockroachdb/errors v1.14.0 h1:EfdVEJpN3z8rPMo43Yit59LxoiIa470fSXpZXuEs+ZI=
@@ -40,6 +42,8 @@ github.com/distatus/battery v0.11.0 h1:KJk89gz90Iq/wJtbjjM9yUzBXV+ASV/EG2WOOL7N8
 github.com/distatus/battery v0.11.0/go.mod h1:KmVkE8A8hpIX4T78QRdMktYpEp35QfOL8A8dwZBxq2k=
 github.com/dolthub/maphash v0.1.0 h1:bsQ7JsF4FkkWyrP3oCnFJgrCUAFbFf3kOl4L/QxPDyQ=
 github.com/dolthub/maphash v0.1.0/go.mod h1:gkg4Ch4CdCDu5h6PMriVLawB7koZ+5ijb9puGMV50a4=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/ebitengine/purego v0.9.1 h1:a/k2f2HQU3Pi399RPW1MOaZyhKJL9w/xFpKAg4q1s0A=
 github.com/ebitengine/purego v0.9.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
 github.com/emicklei/go-restful/v3 v3.13.0 h1:C4Bl2xDndpU6nJ4bc1jXd+uTmYPVUwkD6bFY/oTyCes=
@@ -60,6 +64,8 @@ github.com/go-errors/errors v1.4.2 h1:J6MZopCL4uSllY1OfXM374weqZFFItUbrImctkmUxI
 github.com/go-errors/errors v1.4.2/go.mod h1:sIVyrIiJhuEF+Pj9Ebtd6P/rEYROXFi3BopGUQ5a5Og=
 github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
 github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
 github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE=
 github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78=
@@ -103,6 +109,8 @@ github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
 github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
 github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/btree v1.1.3 h1:CVpQJjYgC4VbzxeGVHfvZrv1ctoYCAI8vbl07Fcxlyg=
 github.com/google/btree v1.1.3/go.mod h1:qOPhT0dTNdNzV6Z/lhRX0YXUafgPLFUh+gZMl761Gm4=
 github.com/google/gnostic-models v0.7.1 h1:SisTfuFKJSKM5CPZkffwi6coztzzeYUhc3v4yxLWH8c=
@@ -141,8 +149,14 @@ github.com/longhorn/go-common-libs v0.0.0-20260730002911-add09e6eb92c h1:WR2BAcT
 github.com/longhorn/go-common-libs v0.0.0-20260730002911-add09e6eb92c/go.mod h1:pjOR2fdQA0dNp3is1xfA+Ni2PjPDP+JuOoSEjdL2cfQ=
 github.com/longhorn/go-spdk-helper v0.9.0 h1:CHXOCwj4lRmSOg8zBAeY95AEsdo26GIEVfyPHfKxKyk=
 github.com/longhorn/go-spdk-helper v0.9.0/go.mod h1:RBejkKtfaxUeNr/I5lzUwawqeJspylUo9UnP/iHtjiI=
+github.com/longhorn/longhorn-engine v1.13.0-dev-20260503.0.20260811002413-f97d5257ac06 h1:55jzVbTPerM+UdxWLLs1iETq8ouXTadsohkdJajl0is=
+github.com/longhorn/longhorn-engine v1.13.0-dev-20260503.0.20260811002413-f97d5257ac06/go.mod h1:kpvqTln9a0PRrLLuROxo0vvNMBKfB7VZBAEPuuYndr4=
 github.com/longhorn/longhorn-manager v1.12.1 h1:ncrTZUxXCpXvzWOhPbzdFCRk2Lp6pZfP3UMbyCY+z2E=
 github.com/longhorn/longhorn-manager v1.12.1/go.mod h1:msD+SdP1rvEqhPEFbuxAXw8HBePREwVKkMoF7kUhoJk=
+github.com/longhorn/sparse-tools v0.0.0-20260423074222-280e61de741a h1:xb71oeVPI7XZymAAG8ts5deC8s40dnX5IgxTYAB/qnk=
+github.com/longhorn/sparse-tools v0.0.0-20260423074222-280e61de741a/go.mod h1:d8l9nyC8No3PIfYHwZunnBj88y5M4sDM+h6uZyTtaNk=
+github.com/longhorn/types v0.0.0-20260810232958-141f76734364 h1:OwnsjatjbLF+D4MtlQjfc7G6MK5uIiY8ac7/ePypRsA=
+github.com/longhorn/types v0.0.0-20260810232958-141f76734364/go.mod h1:fmaMw+kNcCfoil6w9VNlEmXzBWIpZpofb2FvmxQFA8A=
 github.com/lufia/plan9stats v0.0.0-20251013123823-9fd1530e3ec3 h1:PwQumkgq4/acIiZhtifTV5OUqqiP82UAl0h87xj/l9k=
 github.com/lufia/plan9stats v0.0.0-20251013123823-9fd1530e3ec3/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg=
 github.com/lxzan/gws v1.8.9 h1:VU3SGUeWlQrEwfUSfokcZep8mdg/BrUF+y73YYshdBM=
@@ -187,6 +201,8 @@ github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRI
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU=
 github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
+github.com/rancher/go-fibmap v0.0.0-20160418233256-5fc9f8c1ed47 h1:JSipdfqjzjD9EMzehVJaS48FXXfC8Bec4japPmWE5pM=
+github.com/rancher/go-fibmap v0.0.0-20160418233256-5fc9f8c1ed47/go.mod h1:aLaSmp4RuKnOBJO5jFdPH+qkSfLByIGGZVczecL9okc=
 github.com/robfig/cron v1.2.0 h1:ZjScXvvxeQ63Dbyxy76Fj3AT3Ut0aKsyd2/tl3DTMuQ=
 github.com/robfig/cron v1.2.0/go.mod h1:JGuDeoQd7Z6yL4zQhZ3OPEVHB7fL6Ka6skscFHfmt2k=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
@@ -227,6 +243,18 @@ github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9de
 github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
 github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU=
+go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc=
+go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc=
+go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo=
+go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58=
+go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0=
+go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI=
+go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA=
+go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk=
+go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
@@ -285,8 +313,14 @@ golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8T
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af h1:+5/Sw3GsDNlEmu7TfklWKPdQ0Ykja5VEmq2i817+jbI=
-google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
+gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260904194346-d0f1323225a4 h1:5t+ZydAFj5kGVLrgCvLmpmCf9ylGRd64hpEronfRaws=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260904194346-d0f1323225a4/go.mod h1:DjtHYE8FKJLivXcBEjGwndXfIC23G0VpXiXKqG179uA=
+google.golang.org/grpc v1.83.1 h1:HIO0+BEtBP6soyqvqC8sNUjZ7bTs+0hFQuFF+RAy++Y=
+google.golang.org/grpc v1.83.1/go.mod h1:kDyl6SKsiHKt0uylY5gtn5cEjkrIOhQOGDgIc4JGwzQ=
+google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
+google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

pkg/consts/cmd.go

@@ -61,6 +61,10 @@ const (
 	CmdOptLonghornEngineImage   = "engine-image"
 	CmdOptLonghornNamespace     = "longhorn-namespace"
 	CmdOptLonghornVolumeName    = "volume-name"
+	CmdOptReplicaDir            = "replica-dir"
+	CmdOptReplicaDryRun         = "dry-run"
+	EnvReplicaDirectory         = "REPLICA_DIR"
+	SubCmdRecover               = "recover"
 )
 
 const (

pkg/local/replica/recoverer/coalesce/coalesce.go

@@ -0,0 +1,98 @@
+package coalesce
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/pkg/errors"
+
+	"github.com/longhorn/sparse-tools/sparse"
+
+	"github.com/longhorn/cli/pkg/local/replica/recoverer/common"
+	"github.com/longhorn/cli/pkg/local/replica/recoverer/sectormap"
+)
+
+// PromoteToHead copies every sector range whose current owner is NOT head into head,
+// then punches a hole in that source range so the copy is not duplicated on disk.
+func PromoteToHead(smap *sectormap.SectorMapping, chain *sectormap.Chain, headName string, dryRun bool) error {
+	location := smap.Location
+	names := smap.LocationFileNames
+
+	totalSectors := int64(len(location))
+	if totalSectors == 0 {
+		return nil
+	}
+
+	if dryRun {
+		if !common.Confirm("Do you want to proceed with promoting sectors to head?") {
+			fmt.Println("Operation canceled.")
+			return nil
+		}
+	}
+
+	headFile, err := chain.GetFile(headName)
+	if err != nil {
+		return errors.Wrap(err, "failed to get head layer file")
+	}
+
+	promoteRun := func(runStart, runEnd int64, ownerIdx byte) error {
+		if ownerIdx == 0 || names[ownerIdx] == headName {
+			// Unclaimed by any layer (sparse everywhere) or already on head; nothing to promote.
+			return nil
+		}
+		ownerName := names[ownerIdx]
+
+		srcFile, err := chain.GetFile(names[ownerIdx])
+		if err != nil {
+			return fmt.Errorf("failed to get file: %w", err)
+		}
+
+		for chunkBeg := runStart; chunkBeg < runEnd; chunkBeg += promoteChunkSectors {
+			chunkEnd := chunkBeg + promoteChunkSectors
+			if chunkEnd > runEnd {
+				chunkEnd = runEnd
+			}
+
+			offset := chunkBeg * sectorSize
+			length := (chunkEnd - chunkBeg) * sectorSize
+
+			if err := executePromote(srcFile, headFile, ownerName, offset, length); err != nil {
+				return err
+			}
+
+		}
+		return nil
+	}
+
+	runStart := int64(0)
+	runOwnerIdx := location[0]
+	for s := int64(1); s < totalSectors; s++ {
+		idx := location[s]
+		if idx != runOwnerIdx {
+			if err := promoteRun(runStart, s, runOwnerIdx); err != nil {
+				return err
+			}
+			runStart, runOwnerIdx = s, idx
+		}
+	}
+	return promoteRun(runStart, totalSectors, runOwnerIdx)
+}
+
+func executePromote(srcFile *os.File, headFile *os.File, ownerName string, offset, length int64) error {
+	buf := make([]byte, length)
+	if _, err := srcFile.ReadAt(buf, offset); err != nil && err != io.EOF {
+		return fmt.Errorf("failed to read %s at [%d,+%d): %w", ownerName, offset, length, err)
+	}
+
+	if _, err := headFile.WriteAt(buf, offset); err != nil {
+		return fmt.Errorf("failed to write head at [%d,+%d): %w", offset, length, err)
+	}
+
+	// Data is now durably in head, reclaim the now-redundant copy in the source.
+	fiemapFile := sparse.NewFiemapFile(srcFile)
+	if err := fiemapFile.PunchHole(offset, length); err != nil {
+		return fmt.Errorf("failed to punch hole in %v at [%d,+%d): %w", ownerName, offset, length, err)
+	}
+	return nil
+}

pkg/local/replica/recoverer/coalesce/constants.go

@@ -0,0 +1,6 @@
+package coalesce
+
+const (
+	sectorSize          = 512
+	promoteChunkSectors = 2048
+)

pkg/local/replica/recoverer/common/common.go

@@ -0,0 +1,16 @@
+package common
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"strings"
+)
+
+func Confirm(prompt string) bool {
+	fmt.Printf("\n%s [y/N]: ", prompt)
+	reader := bufio.NewReader(os.Stdin)
+	answer, _ := reader.ReadString('\n')
+	answer = strings.TrimSpace(strings.ToLower(answer))
+	return answer == "y" || answer == "yes"
+}