image: add banger image cache prune for OCI cache cleanup

OCI layer blobs accumulate forever — every pull writes layers to
~/.cache/banger/oci/blobs/sha256/<hex> via go-containerregistry's
filesystem cache, and nothing ever evicts them. The cache is purely
a re-pull-avoidance (every flattened image is independent of the
blobs that sourced it), so it's a perfect candidate for an opt-in
operator-driven prune.

New surface:
  * api: ImageCachePruneParams{DryRun}, ImageCachePruneResult
    {BytesFreed, BlobsFreed, DryRun, CacheDir}.
  * daemon: ImageService.PruneOCICache walks layout.OCICacheDir for
    a (bytes, blobs) tally, then — outside dry-run — atomically
    renames the cache aside, recreates it empty, and rm -rf's the
    aside dir. The rename-then-rm avoids leaving the cache in a
    half-removed state if a pull starts mid-prune (the in-flight
    pull's open files survive the rename via standard Linux
    semantics; it just sees a fresh empty cache afterwards). Missing
    cache dir is treated as zero — fresh installs that have never
    pulled an OCI image don't error.
  * dispatch: image.cache.prune RPC (paramHandler-wrapped, mirroring
    every other image RPC). Documented-methods test list updated.
  * cli: `banger image cache` group with a `prune` subcommand
    (--dry-run flag). Output is a single line: "freed 1.2 GiB
    across 47 blob(s) in /var/cache/banger/oci" or "would free …".
    formatBytes helper for the size pretty-print.

docs/oci-import.md: replaced the "Tech debt: cache eviction" bullet
with a "Cache lifecycle" section describing the new command and
the in-flight-pull caveat.

Tests: PruneOCICache covers the happy path (real prune empties the
cache, recreates an empty dir, doesn't leak the .pruning- aside),
the dry-run path (returns size, leaves blobs intact), and the
fresh-install path (cache dir absent → zero result, no error).
Smoke at JOBS=4 still green; live exercise against an empty cache
on a system install prints the expected zero summary.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

internal/daemon/dispatch.go

@@ -75,12 +75,13 @@ var rpcHandlers = map[string]handler{
 	"vm.workspace.prepare": paramHandler(workspacePrepareDispatch),
 	"vm.workspace.export":  paramHandler(workspaceExportDispatch),
 
-	"image.list":     noParamHandler(imageListDispatch),
-	"image.show":     paramHandler(imageShowDispatch),
-	"image.register": paramHandler(imageRegisterDispatch),
-	"image.promote":  paramHandler(imagePromoteDispatch),
-	"image.delete":   paramHandler(imageDeleteDispatch),
-	"image.pull":     paramHandler(imagePullDispatch),
+	"image.list":        noParamHandler(imageListDispatch),
+	"image.show":        paramHandler(imageShowDispatch),
+	"image.register":    paramHandler(imageRegisterDispatch),
+	"image.promote":     paramHandler(imagePromoteDispatch),
+	"image.delete":      paramHandler(imageDeleteDispatch),
+	"image.pull":        paramHandler(imagePullDispatch),
+	"image.cache.prune": paramHandler(imageCachePruneDispatch),
 
 	"kernel.list":    noParamHandler(kernelListDispatch),
 	"kernel.show":    paramHandler(kernelShowDispatch),
@@ -209,6 +210,10 @@ func imagePullDispatch(ctx context.Context, d *Daemon, p api.ImagePullParams) (a
 	return api.ImageShowResult{Image: image}, err
 }
 
+func imageCachePruneDispatch(ctx context.Context, d *Daemon, p api.ImageCachePruneParams) (api.ImageCachePruneResult, error) {
+	return d.img.PruneOCICache(ctx, p)
+}
+
 func kernelListDispatch(ctx context.Context, d *Daemon) (api.KernelListResult, error) {
 	return d.img.KernelList(ctx)
 }

internal/daemon/dispatch_test.go

@@ -20,6 +20,7 @@ import (
 // docs generator) can grep this test.
 func TestRPCHandlersMatchDocumentedMethods(t *testing.T) {
 	expected := []string{
+		"image.cache.prune",
 		"image.delete",
 		"image.list",
 		"image.promote",

internal/daemon/image_cache.go

@@ -0,0 +1,112 @@
+package daemon
+
+import (
+	"context"
+	crand "crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+
+	"banger/internal/api"
+)
+
+// PruneOCICache removes every blob under the OCI layer cache. The
+// cache is purely a re-pull-avoidance (every flattened image is
+// independent of the blobs that sourced it), so the worst-case
+// outcome of pruning is "next pull of the same ref re-downloads its
+// layers" — a reasonable disk-hygiene knob.
+//
+// DryRun=true walks the cache and returns the size that WOULD be
+// freed without touching anything; tests and CLI consumers print
+// that summary so the operator can decide.
+//
+// Concurrent in-flight pulls may break if they're mid-fetch when
+// the rename happens. That tradeoff is documented in the CLI help
+// and docs/oci-import.md; the prune is an operator action, not a
+// background sweep.
+func (s *ImageService) PruneOCICache(_ context.Context, params api.ImageCachePruneParams) (api.ImageCachePruneResult, error) {
+	cacheDir := s.layout.OCICacheDir
+	bytes, blobs, err := walkCacheUsage(cacheDir)
+	if err != nil {
+		return api.ImageCachePruneResult{}, fmt.Errorf("inspect oci cache: %w", err)
+	}
+	res := api.ImageCachePruneResult{
+		BytesFreed: bytes,
+		BlobsFreed: blobs,
+		DryRun:     params.DryRun,
+		CacheDir:   cacheDir,
+	}
+	if params.DryRun || blobs == 0 {
+		return res, nil
+	}
+	// Atomic rename aside so a follow-up pull doesn't see a half-
+	// removed tree, then rm -rf the renamed dir, then recreate the
+	// empty cache so future pulls find their write target.
+	aside, err := renameAside(cacheDir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return res, nil
+		}
+		return api.ImageCachePruneResult{}, fmt.Errorf("rename oci cache aside: %w", err)
+	}
+	if err := os.MkdirAll(cacheDir, 0o755); err != nil {
+		// Best-effort restore: try to rename back so the caller
+		// isn't left with a vanished cache dir. If both moves
+		// failed, surface both — the operator needs to know.
+		if restoreErr := os.Rename(aside, cacheDir); restoreErr != nil {
+			return api.ImageCachePruneResult{}, fmt.Errorf("recreate oci cache: %w (also failed to restore from %s: %v)", err, aside, restoreErr)
+		}
+		return api.ImageCachePruneResult{}, fmt.Errorf("recreate oci cache: %w", err)
+	}
+	if err := os.RemoveAll(aside); err != nil {
+		return api.ImageCachePruneResult{}, fmt.Errorf("remove old oci cache (%s): %w", aside, err)
+	}
+	return res, nil
+}
+
+func walkCacheUsage(cacheDir string) (int64, int, error) {
+	var bytes int64
+	var blobs int
+	err := filepath.WalkDir(cacheDir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			// Cache dir doesn't exist yet (fresh install, no OCI
+			// pulls so far) — that's not a prune error, it's a
+			// 0-byte / 0-blob result.
+			if os.IsNotExist(err) && path == cacheDir {
+				return filepath.SkipAll
+			}
+			return err
+		}
+		if d.IsDir() {
+			return nil
+		}
+		info, err := d.Info()
+		if err != nil {
+			return err
+		}
+		bytes += info.Size()
+		blobs++
+		return nil
+	})
+	if err != nil {
+		return 0, 0, err
+	}
+	return bytes, blobs, nil
+}
+
+// renameAside moves cacheDir to a sibling temp path so the prune can
+// rm-rf it without racing against fresh writes. Returns the aside
+// path on success.
+func renameAside(cacheDir string) (string, error) {
+	var suffix [8]byte
+	if _, err := crand.Read(suffix[:]); err != nil {
+		return "", err
+	}
+	aside := cacheDir + ".pruning-" + hex.EncodeToString(suffix[:])
+	if err := os.Rename(cacheDir, aside); err != nil {
+		return "", err
+	}
+	return aside, nil
+}

internal/daemon/image_cache_test.go

@@ -0,0 +1,125 @@
+package daemon
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"banger/internal/api"
+	"banger/internal/paths"
+)
+
+// seedFakeOCICache drops a few fixed-size files that mimic an OCI
+// layer cache layout (blobs/sha256/<hex>) so tests don't depend on
+// real registry round-trips.
+func seedFakeOCICache(t *testing.T, cacheDir string) (totalBytes int64, blobCount int) {
+	t.Helper()
+	blobsDir := filepath.Join(cacheDir, "blobs", "sha256")
+	if err := os.MkdirAll(blobsDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	for i, payload := range []string{"layer-a", "layer-b-bigger", "layer-c"} {
+		name := strings.Repeat("ab", 32) // 64 hex chars stand-in
+		path := filepath.Join(blobsDir, name+"-"+string(rune('0'+i)))
+		if err := os.WriteFile(path, []byte(payload), 0o644); err != nil {
+			t.Fatalf("write blob: %v", err)
+		}
+		totalBytes += int64(len(payload))
+		blobCount++
+	}
+	return totalBytes, blobCount
+}
+
+func TestPruneOCICacheDryRunReportsSizeWithoutDeleting(t *testing.T) {
+	cacheRoot := t.TempDir()
+	cacheDir := filepath.Join(cacheRoot, "oci")
+	wantBytes, wantBlobs := seedFakeOCICache(t, cacheDir)
+
+	d := &Daemon{layout: paths.Layout{OCICacheDir: cacheDir}}
+	wireServices(d)
+
+	res, err := d.img.PruneOCICache(context.Background(), api.ImageCachePruneParams{DryRun: true})
+	if err != nil {
+		t.Fatalf("PruneOCICache: %v", err)
+	}
+	if res.BytesFreed != wantBytes {
+		t.Fatalf("BytesFreed = %d, want %d", res.BytesFreed, wantBytes)
+	}
+	if res.BlobsFreed != wantBlobs {
+		t.Fatalf("BlobsFreed = %d, want %d", res.BlobsFreed, wantBlobs)
+	}
+	if !res.DryRun {
+		t.Error("result.DryRun = false, want true")
+	}
+	// Blobs must still exist.
+	entries, _ := os.ReadDir(filepath.Join(cacheDir, "blobs", "sha256"))
+	if len(entries) != wantBlobs {
+		t.Fatalf("blobs dir: got %d entries, want %d (dry-run must not delete)", len(entries), wantBlobs)
+	}
+}
+
+func TestPruneOCICacheRemovesAllBlobs(t *testing.T) {
+	cacheRoot := t.TempDir()
+	cacheDir := filepath.Join(cacheRoot, "oci")
+	wantBytes, wantBlobs := seedFakeOCICache(t, cacheDir)
+
+	d := &Daemon{layout: paths.Layout{OCICacheDir: cacheDir}}
+	wireServices(d)
+
+	res, err := d.img.PruneOCICache(context.Background(), api.ImageCachePruneParams{})
+	if err != nil {
+		t.Fatalf("PruneOCICache: %v", err)
+	}
+	if res.BytesFreed != wantBytes {
+		t.Fatalf("BytesFreed = %d, want %d", res.BytesFreed, wantBytes)
+	}
+	if res.BlobsFreed != wantBlobs {
+		t.Fatalf("BlobsFreed = %d, want %d", res.BlobsFreed, wantBlobs)
+	}
+	if res.DryRun {
+		t.Error("result.DryRun = true on a real prune")
+	}
+	// Cache dir must exist (recreated empty) so the next pull has a
+	// place to write blobs.
+	info, err := os.Stat(cacheDir)
+	if err != nil {
+		t.Fatalf("cache dir gone after prune: %v", err)
+	}
+	if !info.IsDir() {
+		t.Fatal("cache path is not a directory after prune")
+	}
+	// Blobs subdir is gone (the rename took everything aside; the
+	// recreate left only the bare cache dir).
+	if _, err := os.Stat(filepath.Join(cacheDir, "blobs")); !os.IsNotExist(err) {
+		t.Fatalf("blobs dir survived prune: %v", err)
+	}
+	// Aside dirs must have been cleaned up too.
+	roots, _ := os.ReadDir(cacheRoot)
+	for _, e := range roots {
+		if strings.Contains(e.Name(), ".pruning-") {
+			t.Errorf("aside dir leaked: %s", e.Name())
+		}
+	}
+}
+
+// TestPruneOCICacheMissingDirIsZeroResult covers the fresh-install
+// case: no OCI pulls have ever happened, so the cache dir doesn't
+// exist. Prune must report zero, not error.
+func TestPruneOCICacheMissingDirIsZeroResult(t *testing.T) {
+	cacheRoot := t.TempDir()
+	cacheDir := filepath.Join(cacheRoot, "oci")
+	// Don't create cacheDir.
+
+	d := &Daemon{layout: paths.Layout{OCICacheDir: cacheDir}}
+	wireServices(d)
+
+	res, err := d.img.PruneOCICache(context.Background(), api.ImageCachePruneParams{})
+	if err != nil {
+		t.Fatalf("PruneOCICache(missing): %v", err)
+	}
+	if res.BytesFreed != 0 || res.BlobsFreed != 0 {
+		t.Fatalf("missing cache should be zero; got %+v", res)
+	}
+}