Make snapshot list report a changed destination instead of advising prune (closes #317)

When the local index is bound to a different destination than the
configured one, snapshot list now gives the warning prune, snapshot
purge and snapshot remove refuse with: both destinations and the two
ways out (revert the configuration, or run vaultik database delete).
Below the table it replaces the local-only note and its prune advice.
With --json it goes to stderr through the logger, so stdout stays the
document, whose local rows show remote_present false.

Reading the binding moves out of EnsureStorageBinding into
storageBinding, which records nothing, so the read-only list can call
it without binding a fresh index.

Model: opus-5-5

README.md

@@ -323,7 +323,11 @@ read from the manifest.
 
 Snapshots in the local index with no counterpart on the destination
 store are reported below the table as drift, with the `vaultik prune`
-invocation that reconciles them.
+invocation that reconciles them. If the local index is bound to a
+different destination than the configured one (after a change to
+`storage_url`, or `s3.endpoint`, `s3.bucket` or `s3.prefix`), the
+command says so instead and gives the same two ways out that `prune`
+gives: revert the configuration, or run `vaultik database delete`.
 
 If the destination store cannot be listed (unmounted volume,
 permission denied, network down), the command warns, falls back to the
@@ -332,9 +336,11 @@ local index alone, and still exits zero.
   (whether the snapshot is in the local index), `remote_key` (the full
   64-character storage key), and `remote_present` (whether it was seen
   on the destination store, or `null` if the destination could not be
-  listed). Warnings about an unlistable destination, unreadable
+  listed). Warnings about an unlistable destination, a local index
-  manifests, and a truncated listing all go to stderr through the
+  bound to a different destination (with both destinations and the
-  logger, so stdout stays a single parseable document.
+  same two ways out), unreadable manifests, and a truncated listing all
+  go to stderr through the logger, so stdout stays a single parseable
+  document.
 
 **`snapshot verify`**: Verify snapshot integrity.
 * Default (shallow): checks that every blob the manifest lists is present in
@@ -360,16 +366,20 @@ snapshot from the local index and strips the snapshot's metadata from
 the backup destination store. Blobs are NOT touched — deleting blobs
 requires reading every remaining remote manifest (the destination store
 may hold snapshots this host doesn't know about), which is what
-`vaultik prune` does. On success the command prints the exact `vaultik
+`vaultik prune` does. The command prints the `vaultik prune` invocation
-prune` invocation to run as a follow-up. An ID that names no snapshot in
+to run as a follow-up only when it removed the snapshot's metadata from
-the local index or on the destination store is an error; with
+the destination store, and never under `--json`. An ID that names no
-`--local-only`, the snapshot must be in the local index. Local row
+snapshot in the local index or on the destination store is an error;
+with `--local-only`, the snapshot must be in the local index. Local row
 cleanup (files, chunks, blobs the snapshot was the last referrer for)
-runs automatically. If the destination store is unreachable, the local-DB
+runs automatically. If removing the snapshot's metadata from the
-removal still completes and a warning is emitted; run `vaultik snapshot
+destination store fails (for example because the store is unreachable),
-remove <snapshot-id>` again once the store is reachable to remove the
+the local-DB removal still completes and a warning is emitted; run
-snapshot's metadata from it (`vaultik prune` does not). To wipe everything
+`vaultik snapshot remove <snapshot-id>` again once the store is reachable
-on the destination in one go, use `vaultik remote nuke --force`.
+to remove the snapshot's metadata from it (`vaultik prune` does not). For
+a snapshot that is only on the destination store, that failure is an
+error. To wipe everything on the destination in one go, use `vaultik
+remote nuke --force`.
 * `--local-only`: Skip remote cleanup; only touch the local index
 * `--dry-run`: Show what would be deleted without deleting
 * `--force`: Skip confirmation prompt

internal/cli/snapshot.go

@@ -270,8 +270,9 @@ By default, this removes the snapshot from the local index database and
 strips the snapshot's metadata from the backup destination store. Blobs
 are NOT touched: deleting them requires reading every remaining remote
 manifest (the destination store may hold snapshots this host doesn't
-know about), which is what 'vaultik prune' does. On success the command
+know about), which is what 'vaultik prune' does. The command prints the
-prints the exact 'vaultik prune' invocation to run as a follow-up.
+'vaultik prune' invocation to run as a follow-up only when it removed the
+snapshot's metadata from the destination store, and never under --json.
 
 An ID that names no snapshot in the local index or on the destination
 store is an error.
@@ -280,10 +281,12 @@ Use --local-only to skip the remote half (e.g. when you want to forget a
 snapshot locally without touching the destination store); the snapshot
 must then be in the local index.
 
-If the remote is unreachable, the local-database removal still completes
+If removing the snapshot's metadata from the destination store fails (for
-and a warning is emitted; run 'vaultik snapshot remove <snapshot-id>' again
+example because the remote is unreachable), the local-database removal
-once the destination store is reachable to remove the snapshot's metadata
+still completes and a warning is emitted; run 'vaultik snapshot remove
-from it ('vaultik prune' does not).
+<snapshot-id>' again once the destination store is reachable to remove
+the snapshot's metadata from it ('vaultik prune' does not). For a
+snapshot that is only on the destination store, that failure is an error.
 
 To wipe the entire destination store and start over, use 'vaultik remote
 nuke --force' — it is the single supported entry point for that.`,

internal/vaultik/prune_count_test.go

@@ -1,13 +1,17 @@
 package vaultik //nolint:testpackage // exercises unexported count helpers
 
 import (
+	"bytes"
 	"context"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"sneak.berlin/go/vaultik/internal/database"
 	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/snapshot"
+	"sneak.berlin/go/vaultik/internal/ui"
 )
 
 // TestTableCountForReportSurfacesReadFailure is the regression guard for
@@ -76,3 +80,59 @@ func TestCountDiffUnknownWhenEitherSideUnknown(t *testing.T) {
 	assert.Nil(t, countDiff(&before, nil), "unknown after yields unknown delta")
 	assert.Nil(t, countDiff(nil, nil))
 }
+
+// TestPruneDatabaseSummaryLabelsTotals removes the only incomplete
+// snapshot from an index that also holds a complete one. The figure in
+// brackets is every snapshot left in the local index, so the line must
+// say so rather than read as incomplete snapshots that remain.
+func TestPruneDatabaseSummaryLabelsTotals(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+
+	db, err := database.New(ctx, ":memory:")
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = db.Close() })
+
+	repos := database.NewRepositories(db)
+
+	startedAt := time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC)
+	completedAt := startedAt.Add(time.Minute)
+
+	require.NoError(t, repos.Snapshots.Create(ctx, nil, &database.Snapshot{
+		ID:          "host_complete_2026-01-02T03:04:05Z",
+		Hostname:    "host",
+		StartedAt:   startedAt,
+		CompletedAt: &completedAt,
+	}))
+	require.NoError(t, repos.Snapshots.Create(ctx, nil, &database.Snapshot{
+		ID:        "host_incomplete_2026-01-02T03:04:05Z",
+		Hostname:  "host",
+		StartedAt: startedAt,
+	}))
+
+	var out bytes.Buffer
+
+	v := &Vaultik{
+		DB:           db,
+		Repositories: repos,
+		SnapshotManager: snapshot.NewSnapshotManager(
+			snapshot.SnapshotManagerParams{Repos: repos}),
+		UI: ui.NewWithColor(&out, false),
+	}
+	v.SetContext(ctx)
+
+	result, err := v.PruneDatabase()
+	require.NoError(t, err)
+	require.Equal(t, int64(1), result.SnapshotsDeleted)
+
+	assert.Contains(t, out.String(), "Incomplete snapshots: 1 removed "+
+		"(total snapshots left in the local index: 1).")
+	assert.Contains(t, out.String(), "Orphaned files: 0 removed "+
+		"(total files left in the local index: 0).")
+	assert.Contains(t, out.String(), "Orphaned chunks: 0 removed "+
+		"(total chunks left in the local index: 0).")
+	assert.Contains(t, out.String(), "Orphaned blobs: 0 removed "+
+		"(total blobs left in the local index: 0).")
+}

internal/vaultik/remove_snapshot_test.go

@@ -17,6 +17,7 @@ import (
 	"sneak.berlin/go/vaultik/internal/log"
 	"sneak.berlin/go/vaultik/internal/snapshot"
 	"sneak.berlin/go/vaultik/internal/storage"
+	"sneak.berlin/go/vaultik/internal/storage/faultstore"
 	"sneak.berlin/go/vaultik/internal/types"
 	"sneak.berlin/go/vaultik/internal/vaultik"
 )
@@ -431,6 +432,40 @@ func TestRemoveSnapshot_NotInLocalIndex(t *testing.T) {
 	assert.Contains(t, out, "Removed snapshot metadata from remote storage")
 }
 
+// TestRemoveSnapshot_NotInLocalIndexDeleteFails checks that removing a
+// snapshot only the destination store holds fails when its metadata
+// cannot be deleted there, under --force and under --json: nothing was
+// removed, so the command must not succeed.
+func TestRemoveSnapshot_NotInLocalIndexDeleteFails(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	for name, opts := range map[string]vaultik.RemoveOptions{
+		"force": {Force: true},
+		"json":  {JSON: true},
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			store := newTestStorer()
+			addManifest(t, store, "snapshot-001", nil)
+
+			faulty := faultstore.New(store)
+			faulty.OnDelete = func(string) bool { return true }
+
+			tv := vaultik.NewForTesting(faulty)
+			tv.Repositories = newLocalIndex(t)
+
+			result, err := tv.RemoveSnapshot("snapshot-001", &opts)
+
+			require.ErrorIs(t, err, faultstore.ErrInjectedDelete)
+			assert.False(t, result.RemoteRemoved)
+			assert.True(t, store.hasKey(remoteKeyPath("snapshot-001")))
+			assert.Empty(t, tv.Stdout.String())
+		})
+	}
+}
+
 func TestRemoveAllSnapshots_RequiresForce(t *testing.T) {
 	log.Initialize(log.Config{})
 	t.Parallel()

internal/vaultik/snapshot.go

@@ -1228,9 +1228,11 @@ const snapshotRemoveCommandHint = "vaultik snapshot remove"
 // destination store. Blobs are NOT touched: removing a snapshot's
 // blobs requires reading every remaining remote manifest (the remote
 // may hold snapshots this host doesn't know about), which is what
-// `vaultik prune` is for — the command prints the prune invocation to
+// `vaultik prune` is for — when metadata was removed from the
-// run as a follow-up. When the remote is unreachable the command still
+// destination store, the text output names the prune invocation to run
-// completes the local-DB removal and warns.
+// as a follow-up. When removing the metadata fails, a snapshot in the
+// local index is still removed from it, with a warning; a snapshot
+// only on the destination store is an error.
 func (v *Vaultik) RemoveSnapshot(
 	snapshotID string, opts *RemoveOptions,
 ) (*RemoveResult, error) {
@@ -1265,8 +1267,10 @@ func (v *Vaultik) RemoveSnapshot(
 		}
 	}
 
-	if !opts.LocalOnly {
+	result.RemoteRemoved, err = v.removeSnapshotRemote(
-		result.RemoteRemoved = v.removeSnapshotRemote(snapshotID, opts)
+		snapshotID, inLocalIndex, opts)
+	if err != nil {
+		return result, err
 	}
 
 	if v.SnapshotManager != nil {
@@ -1391,19 +1395,33 @@ func (v *Vaultik) confirmRemoveSnapshot(snapshotID string, opts *RemoveOptions)
 }
 
 // removeSnapshotRemote strips the snapshot's metadata from the
-// destination store, warning and proceeding on failure: the local-DB
+// destination store. It returns true only when the delete finished
-// removal has already happened, so the user is told the remote half
+// without an error and removed at least one object; under LocalOnly it
-// didn't finish and to run `vaultik snapshot remove` for the snapshot
+// does nothing. When the snapshot is only on the destination store, a
-// again once the destination store is reachable (`vaultik prune` never
+// failure is returned as an error, because that removal is all the
-// removes snapshot metadata). Returns true when the remote removal
+// command does. When the snapshot was in the local index, its removal
-// succeeded and deleted something.
+// there has already happened, so a failure is only a warning telling the
-func (v *Vaultik) removeSnapshotRemote(snapshotID string, opts *RemoveOptions) bool {
+// user to run `vaultik snapshot remove` for the snapshot again once the
+// destination store is reachable (`vaultik prune` never removes snapshot
+// metadata).
+func (v *Vaultik) removeSnapshotRemote(
+	snapshotID string, inLocalIndex bool, opts *RemoveOptions,
+) (bool, error) {
+	if opts.LocalOnly {
+		return false, nil
+	}
+
 	log.Info("Removing snapshot metadata from remote storage",
 		"snapshot_id", snapshotID)
 
 	remoteKey := snapshot.RemoteSnapshotKey(snapshotID)
 
 	deleted, err := v.deleteRemoteSnapshotByKey(remoteKey)
+	if err != nil && !inLocalIndex {
+		return false, fmt.Errorf(
+			"removing snapshot metadata from destination store: %w", err)
+	}
+
 	if err != nil {
 		log.Warn("Could not remove snapshot metadata from remote storage; "+
 			"run '"+snapshotRemoveCommandHint+"' with the snapshot's ID "+
@@ -1418,10 +1436,10 @@ func (v *Vaultik) removeSnapshotRemote(snapshotID string, opts *RemoveOptions) b
 				err, snapshotRemoveCommandHint, snapshotID)
 		}
 
-		return false
+		return false, nil
 	}
 
-	return deleted > 0
+	return deleted > 0, nil
 }
 
 // RemoveAllSnapshots removes every snapshot known to the local
@@ -1902,13 +1920,17 @@ func (v *Vaultik) PruneDatabase() (*PruneResult, error) {
 	snapshotsRemain := countDiff(snapshotCountBefore, &result.SnapshotsDeleted)
 
 	v.UI.Completef("Pruned local index database.")
-	v.UI.Detailf("Incomplete snapshots: %s removed (%s remain).",
+	v.UI.Detailf("Incomplete snapshots: %s removed "+
+		"(total snapshots left in the local index: %s).",
 		countText(&result.SnapshotsDeleted), countText(snapshotsRemain))
-	v.UI.Detailf("Orphaned files: %s removed (%s remain).",
+	v.UI.Detailf("Orphaned files: %s removed "+
+		"(total files left in the local index: %s).",
 		countText(result.FilesDeleted), countText(fileCountAfter))
-	v.UI.Detailf("Orphaned chunks: %s removed (%s remain).",
+	v.UI.Detailf("Orphaned chunks: %s removed "+
+		"(total chunks left in the local index: %s).",
 		countText(result.ChunksDeleted), countText(chunkCountAfter))
-	v.UI.Detailf("Orphaned blobs: %s removed (%s remain).",
+	v.UI.Detailf("Orphaned blobs: %s removed "+
+		"(total blobs left in the local index: %s).",
 		countText(result.BlobsDeleted), countText(blobCountAfter))
 
 	return result, nil

internal/vaultik/snapshot_list.go

@@ -61,7 +61,9 @@ const tabPadding = 3
 // attempt is made to recover or fabricate the human ID.
 //
 // Snapshots in the local index with no counterpart on the destination
-// store are reported as drift below the table.
+// store are reported as drift below the table, unless the local index
+// is bound to a different destination than the configured one: that is
+// reported instead.
 //
 // If remote listing fails (unmounted volume, permission denied,
 // network), we degrade to local-only with a warning. List never fails
@@ -103,7 +105,26 @@ func (v *Vaultik) ListSnapshots(jsonOutput bool) error {
 		return snapshots[i].Timestamp.After(snapshots[j].Timestamp)
 	})
 
+	stored, configured, err := v.storageBinding()
+	if err != nil {
+		return err
+	}
+
+	// A local index bound to another destination describes that one, so
+	// its records are expected to be missing here, and prune refuses to
+	// run. The binding is reported instead of advising prune.
+	boundElsewhere := stored != "" && stored != configured
+
 	if jsonOutput {
+		// stdout holds only the document, so this goes to the logger.
+		if boundElsewhere {
+			log.Warn("Local index is bound to a different backup "+
+				"destination; to proceed, revert storage_url (or the s3.* "+
+				"endpoint, bucket and prefix) to the bound destination, "+
+				"or run 'vaultik database delete'",
+				"bound_to", stored, "configured", configured)
+		}
+
 		if remoteErr == nil {
 			v.reportJSONListingLimits(listing)
 		}
@@ -125,8 +146,13 @@ func (v *Vaultik) ListSnapshots(jsonOutput bool) error {
 		}
 	}
 
+	if boundElsewhere {
+		v.UI.Warningf("%v\n%s", errStorageBindingMismatch,
+			buildBindingMismatchMessage(stored, configured))
+	}
+
 	if remoteErr == nil {
-		v.reportListDrift(snapshots, listing)
+		v.reportListDrift(snapshots, listing, boundElsewhere)
 	}
 
 	return nil
@@ -432,7 +458,9 @@ func (v *Vaultik) snapshotInfoFromLocal(ls *database.Snapshot) SnapshotInfo {
 // reportListDrift prints the reconciliation notes the merged table
 // cannot express on its own: local records with no counterpart on the
 // destination store, plus counts of remote snapshots that were
-// unreadable or omitted.
+// unreadable or omitted. Local records are not reported when
+// boundElsewhere is set: ListSnapshots has already said why they are
+// missing.
 //
 // This is what remains of the old reportRemoteDrift, and it no longer
 // touches the destination store. Its remote-only half collapsed into
@@ -441,6 +469,7 @@ func (v *Vaultik) snapshotInfoFromLocal(ls *database.Snapshot) SnapshotInfo {
 // so `snapshot list` lists the destination exactly once per invocation.
 func (v *Vaultik) reportListDrift(
 	snapshots []SnapshotInfo, listing *remoteSnapshotListing,
+	boundElsewhere bool,
 ) {
 	var localOnly []string
 
@@ -450,7 +479,7 @@ func (v *Vaultik) reportListDrift(
 		}
 	}
 
-	if len(localOnly) > 0 {
+	if len(localOnly) > 0 && !boundElsewhere {
 		v.UI.Warningf("%d local snapshot record(s) not found in backup "+
 			"destination store:", len(localOnly))
 

internal/vaultik/snapshot_list_test.go

@@ -421,6 +421,74 @@ func TestListSnapshots_LocalOnlyReportedAsDrift(t *testing.T) {
 	assert.NotContains(t, out, "snapshot cleanup")
 }
 
+// TestListSnapshots_BoundElsewhereDoesNotAdvisePrune covers a changed
+// storage_url: the local index is still bound to the old destination,
+// so its records are missing from the new one. prune refuses to run in
+// that state, so the listing must give the choices prune gives instead
+// of advising it.
+func TestListSnapshots_BoundElsewhereDoesNotAdvisePrune(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	const (
+		oldURL = "file:///mnt/backups/old"
+		newURL = "file:///mnt/backups/new"
+	)
+
+	env := newListEnv(t)
+	env.v.Config.StorageURL = newURL
+	require.NoError(t, env.v.Repositories.LocalMeta.Set(context.Background(),
+		database.LocalMetaKeyStorageURL, oldURL))
+	env.addLocal(t, listLocalID, time.Date(2026, 3, 1, 10, 0, 0, 0, time.UTC))
+
+	err := env.v.ListSnapshots(false)
+	require.NoError(t, err)
+
+	out := env.stdout.String()
+
+	assert.Contains(t, out, listLocalID)
+	assert.Contains(t, out,
+		"local index is bound to a different backup destination")
+	assert.Contains(t, out, oldURL)
+	assert.Contains(t, out, newURL)
+	assert.Contains(t, out, "revert storage_url")
+	assert.Contains(t, out, "vaultik database delete")
+	assert.NotContains(t, out, "vaultik prune")
+}
+
+// TestListSnapshots_JSONReportsBoundElsewhere is the --json side of the
+// test above. Every local row comes out with remote_present false, which
+// a script reads as stale local records unless it is told, on stderr,
+// that the local index is bound to a different destination.
+//
+//nolint:paralleltest // captureProcessStderr replaces os.Stderr
+func TestListSnapshots_JSONReportsBoundElsewhere(t *testing.T) {
+	const (
+		oldURL = "file:///mnt/backups/old"
+		newURL = "file:///mnt/backups/new"
+	)
+
+	env := newListEnv(t)
+	env.v.Config.StorageURL = newURL
+	require.NoError(t, env.v.Repositories.LocalMeta.Set(context.Background(),
+		database.LocalMetaKeyStorageURL, oldURL))
+	env.addLocal(t, listLocalID, time.Date(2026, 3, 1, 10, 0, 0, 0, time.UTC))
+
+	stderr := captureProcessStderr(t, func() {
+		require.NoError(t, env.v.ListSnapshots(true))
+	})
+
+	rows := decodeListJSON(t, env.stdout.String())
+	require.Len(t, rows, 1)
+	assert.Equal(t, listLocalID, rows[0].ID)
+
+	assert.Contains(t, stderr, "bound to a different backup destination")
+	assert.Contains(t, stderr, oldURL)
+	assert.Contains(t, stderr, newURL)
+	assert.Contains(t, stderr, "revert storage_url")
+	assert.Contains(t, stderr, "vaultik database delete")
+}
+
 // TestListSnapshots_UnreachableRemoteDegrades covers the promise in the
 // doc comment: an unreachable destination is a warning plus local-only
 // output, never a failure.

internal/vaultik/storage_bind.go

@@ -45,17 +45,9 @@ func (v *Vaultik) EnsureStorageBinding() error {
 		return nil
 	}
 
-	configured := v.Config.StorageURL
+	stored, configured, err := v.storageBinding()
-	if configured == "" {
-		// The s3.* form: bind on its endpoint, bucket and prefix,
-		// written the way storage_url would name the same destination.
-		s3 := v.Config.S3
-		configured = "s3://" + s3.Bucket + "/" + s3.Prefix + "?endpoint=" + s3.Endpoint
-	}
-
-	stored, err := v.Repositories.LocalMeta.Get(v.ctx, database.LocalMetaKeyStorageURL)
 	if err != nil {
-		return fmt.Errorf("reading local storage binding: %w", err)
+		return err
 	}
 
 	if stored == "" {
@@ -78,6 +70,27 @@ func (v *Vaultik) EnsureStorageBinding() error {
 		errStorageBindingMismatch, buildBindingMismatchMessage(stored, configured))
 }
 
+// storageBinding returns the destination the local index is bound to
+// ("" when no binding is recorded yet), then the configured destination
+// written the same way. It records nothing, so a read-only command can
+// call it.
+func (v *Vaultik) storageBinding() (string, string, error) {
+	configured := v.Config.StorageURL
+	if configured == "" {
+		// The s3.* form: bind on its endpoint, bucket and prefix,
+		// written the way storage_url would name the same destination.
+		s3 := v.Config.S3
+		configured = "s3://" + s3.Bucket + "/" + s3.Prefix + "?endpoint=" + s3.Endpoint
+	}
+
+	stored, err := v.Repositories.LocalMeta.Get(v.ctx, database.LocalMetaKeyStorageURL)
+	if err != nil {
+		return "", "", fmt.Errorf("reading local storage binding: %w", err)
+	}
+
+	return stored, configured, nil
+}
+
 // buildBindingMismatchMessage assembles the multi-line explanation
 // shown when the local index is bound to a different destination than
 // the currently-configured one (the first line lives in the