Add docker_volumes_remove_anonymous: remove leftover unmounted anonymous volumes (issue 1796)

modules/docker/cmd/docker-tools/main.go

@@ -11,6 +11,7 @@ import (
 	"math"
 	"os"
 	"strings"
+	"time"
 
 	stdio "git.novox.be/novox/mesh-sdk/go"
 )
@@ -286,6 +287,34 @@ func tools(c *Client) []stdio.Tool {
 				return c.Volumes(ctx, flag(args, "unmounted", false), flag(args, "sizes", false))
 			},
 		},
+		{
+			Name: "docker_volumes_remove_anonymous",
+			Description: "Remove the leftover anonymous volumes (novox/hq issue 1796): only a volume docker labels anonymous (as docker_volumes says), which no container mounts in any state " +
+				"and so none the mesh holds, and with created_before only one created before it. Every other volume is answered with why it stays; a named volume is data and is never taken, " +
+				"and no volume can be named. Each is removed on its own, never forced; the answer has the count and names removed. Docker does not report the space a removed volume freed. " +
+				"A dry run by default; dry_run false needs why. Replaces docker volume rm and docker volume prune. (a)",
+			Input: map[string]any{
+				"dry_run":        map[string]any{"type": "boolean", "description": "list only (default true)"},
+				"why":            map[string]any{"type": "string", "description": "why: required when dry_run is false"},
+				"created_before": map[string]any{"type": "string", "description": "RFC 3339 time: only volumes created before it (default: any age)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				for _, k := range []string{"name", "names", "volume", "volumes"} {
+					if _, ok := args[k]; ok {
+						return nil, fmt.Errorf("%s: this tool takes no volume by name; it removes only unmounted anonymous volumes", k)
+					}
+				}
+				ask := RemoveVolumesAsk{DryRun: flag(args, "dry_run", true), Why: optional(args, "why")}
+				if s := optional(args, "created_before"); s != "" {
+					t, err := time.Parse(time.RFC3339, s)
+					if err != nil {
+						return nil, fmt.Errorf("created_before must be an RFC 3339 time such as 2026-10-01T00:00:00Z")
+					}
+					ask.CreatedBefore = &t
+				}
+				return c.RemoveAnonymousVolumes(ctx, ask)
+			},
+		},
 		{
 			Name: "docker_events",
 			Description: "What the runtime did in a window ending now (default the last 60 minutes, at most 24 hours): containers created, started, died, health changes, images pulled — with mesh_held. Exec events are left out unless asked; " +