Fix other sentences that carry faults the review named

A search of the four documents, the help text and config.example.yml
for the review's faults found these.

- prune help, and snapshot purge and snapshot list in README.md: a
  snapshot is dropped or reported when its manifest is gone, not its
  metadata or directory.
- README.md, version: the date printed is the commit date.
- README.md, Configuration: names the commands that start without a
  config that loads.
- README.md, snapshot purge: "each such snapshot" named nothing.
- README.md and docs/DATAMODEL.md: a backup can upload unchanged
  content again, so "uploads only what changed" was false.
- docs/REPOSTRUCTURE.md: db.zst.age holds more than one snapshot's
  rows.
- ARCHITECTURE.md: "database records" read as a noun.

Model: fable-5-1

ARCHITECTURE.md

@@ -1,392 +1,401 @@
-# Vaultik Architecture
+# vaultik architecture
 
-This document describes the internal architecture of Vaultik, focusing on the data model, type instantiation, and the relationships between core modules.
+This document describes how the `vaultik` code is organised. It covers three
+things:
 
-## Overview
+- the packages
+- how they are wired together
+- what happens during a backup, a restore, a verify and a prune
 
-Vaultik is a backup system that uses content-defined chunking for deduplication and packs chunks into large, compressed, encrypted blobs for efficient cloud storage. The system is built around dependency injection using [uber-go/fx](https://github.com/uber-go/fx).
+Two other documents cover the stored data:
 
-## Data Flow
+- [docs/DATAMODEL.md](docs/DATAMODEL.md) describes the local index.
+- [docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md) describes the layout of the
+  destination.
+
+## Terms
+
+- **Snapshot**: one backup of the paths listed under one name in the config.
+- **Chunk**: a piece of a file's content. A chunk is named by the SHA-256 hash
+  of its content.
+- **Blob**: one object at the destination. It holds many chunks, compressed and
+  then encrypted.
+- **Local index**: the SQLite database on the backed-up machine.
+- **Destination**: the place the backups are stored.
+- **Manifest**: the unencrypted list of the blobs one snapshot uses.
+- **Remote key**: a hash of the snapshot ID. It names the snapshot's directory
+  at the destination.
+
+## How a backup moves data
 
 ```
-Source Files
+source files
      │
      ▼
-┌─────────────────┐
+  Scanner    walks the paths and finds the files that changed
-│    Scanner      │  Walks directories, detects changed files
+     │
-└────────┬────────┘
+     ▼
-         │
+  Chunker    cuts each changed file into chunks
-         ▼
+     │
-┌─────────────────┐
+     ▼
-│    Chunker      │  Splits files into variable-size chunks (FastCDC)
+  Packer     packs new chunks into a blob, compressed and encrypted
-└────────┬────────┘
+     │
-         │
+     ▼
-         ▼
+  Storer     uploads the blob to the destination
-┌─────────────────┐
-│    Packer       │  Accumulates chunks, compresses (zstd), encrypts (age)
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│   S3 Client     │  Uploads blobs to remote storage
-└─────────────────┘
 ```
 
-## Data Model
+## Packages
 
-### Core Entities
+- `cmd/vaultik`: the `main` function. It starts optional profiling and calls
+  `cli.Entry`.
+- `internal/cli`: the commands, their flags and their help text. It builds the
+  application, takes the lock and handles interrupts.
+- `internal/vaultik`: the code behind each command. `Vaultik` holds every
+  dependency a command uses.
+- `internal/snapshot`: the `Scanner`, which backs up one path, and the
+  `SnapshotManager`, which creates snapshot records and uploads their metadata.
+- `internal/chunker`: cuts a stream into chunks with the FastCDC algorithm.
+- `internal/blob`: the `Packer`, which collects chunks into blobs.
+- `internal/blobgen`: the writer that hashes, compresses and encrypts a blob,
+  and the reader that reverses it.
+- `internal/database`: the local index. It holds the schema and the repository
+  types that read and write the tables.
+  [docs/DATAMODEL.md](docs/DATAMODEL.md#code) says which type serves which
+  table.
+- `internal/storage`: the `Storer` interface and its three implementations, for
+  S3, a local directory and rclone.
+- `internal/s3`: the S3 client that the S3 `Storer` uses.
+- `internal/config`: loads and checks the config file.
+- `internal/ui`: formats the status lines, warnings and errors a user sees.
+- `internal/log`: the logger. It writes to stderr.
+- `internal/pidlock`: the lock that keeps two data-changing commands from
+  running at once.
+- `internal/globals`: the version, commit and commit date, set when the binary
+  is built.
+- `internal/types`: distinct types for IDs, hashes and paths.
 
-The database tracks five primary entities and their relationships:
+## Wiring
 
-```
+The application is assembled with [uber-go/fx](https://github.com/uber-go/fx), a
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+dependency injection library. `cli.NewApp` lists the providers:
-│   Snapshot   │────▶│     File     │────▶│    Chunk     │
-└──────────────┘     └──────────────┘     └──────────────┘
-       │                                         │
-       │                                         │
-       ▼                                         ▼
-┌──────────────┐                          ┌──────────────┐
-│     Blob     │◀─────────────────────────│  BlobChunk   │
-└──────────────┘                          └──────────────┘
-```
-
-### Entity Descriptions
-
-#### File (`database.File`)
-Represents a file, directory, or symlink in the backup system. Stores metadata needed for restoration:
-- Path, mtime
-- Size, mode, ownership (uid, gid)
-- Symlink target (if applicable)
-
-It also stores `source_path`, the source directory the scan found it under, made absolute and with symlinks resolved. Restore does not read it.
-
-#### Chunk (`database.Chunk`)
-A content-addressed unit of data. Files are split into variable-size chunks using the FastCDC algorithm:
-- `ChunkHash`: SHA256 hash of chunk content (primary key)
-- `Size`: Chunk size in bytes
-
-Chunk sizes vary between `avgChunkSize/4` and `avgChunkSize*4` (2.5MB-40MB for the 10MB default average).
-
-#### FileChunk (`database.FileChunk`)
-Maps files to their constituent chunks:
-- `FileID`: Reference to the file
-- `Idx`: Position of this chunk within the file (0-indexed)
-- `ChunkHash`: Reference to the chunk
-
-#### Blob (`database.Blob`)
-The final storage unit uploaded to S3. Contains many compressed and encrypted chunks:
-- `ID`: UUID assigned at creation
-- `Hash`: `hex(SHA256(SHA256(uncompressed blob contents)))`, computed before compression and encryption (see [docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#blobs-directory-blobs))
-- `UncompressedSize`: Total raw chunk data before compression
-- `CompressedSize`: Size after zstd compression and age encryption
-- `CreatedTS`, `FinishedTS`, `UploadedTS`: Lifecycle timestamps
-
-Blob creation process:
-1. Chunks are accumulated (up to MaxBlobSize, typically 10GB)
-2. As each chunk is added, its uncompressed bytes are fed to a running SHA-256
-3. Concurrently, the same bytes are compressed with zstd, then encrypted with age (recipients configured in config), and written to a temporary file
-4. On finalize, the blob's name is the double SHA-256 of the uncompressed contents — `hex(SHA256(SHA256(...)))` — not a hash of the compressed, encrypted bytes
-5. The finished file is uploaded to `blobs/{hash[0:2]}/{hash[2:4]}/{hash}` and then deleted
-
-A backup needs free temporary space, because each blob is written whole to a temporary file before it is uploaded (up to about `blob_size_limit`; an rclone destination that cannot stream uploads needs about twice that) and the metadata export writes copies of the local index. Temporary files go to `$TMPDIR` (default `/tmp`); with `TMPDIR` unset, SQLite writes one of those copies to `/var/tmp`.
-
-#### BlobChunk (`database.BlobChunk`)
-Maps chunks to their position within blobs:
-- `BlobID`: Reference to the blob
-- `ChunkHash`: Reference to the chunk
-- `Offset`: Byte offset within the uncompressed blob
-- `Length`: Chunk size
-
-#### Snapshot (`database.Snapshot`)
-Represents a point-in-time backup:
-- `ID`: Format is `{hostname}_{snapshot-name}_{RFC3339}` (e.g. `server1_home_2025-06-01T12:00:00Z`)
-- Tracks file count, chunk count, blob count, sizes, compression ratio
-- `CompletedAt`: Null until snapshot finishes successfully
-
-#### SnapshotFile / SnapshotBlob
-Join tables linking snapshots to their files and blobs.
-
-### Relationship Summary
-
-```
-Snapshot 1──────────▶ N SnapshotFile N ◀────────── 1 File
-Snapshot 1──────────▶ N SnapshotBlob N ◀────────── 1 Blob
-File     1──────────▶ N FileChunk    N ◀────────── 1 Chunk
-Blob     1──────────▶ N BlobChunk    N ◀────────── 1 Chunk
-```
-
-## Type Instantiation
-
-### Application Startup
-
-The CLI uses fx for dependency injection. Here's the instantiation order:
 
 ```go
-// cli/app.go: NewApp()
+fx.Supply(config.Path(opts.ConfigPath)),
-fx.New(
+fx.Supply(opts.LogOptions),
-    fx.Supply(config.Path(opts.ConfigPath)),         // 1. Config path
+fx.Provide(globals.New),
-    fx.Supply(opts.LogOptions),                      // 2. Log options
+fx.Provide(log.New),
-    fx.Provide(globals.New),                         // 3. Globals
+config.Module,
-    fx.Provide(log.New),                             // 4. Logger config
+database.Module,
-    config.Module,                                   // 5. Config
+log.Module,
-    database.Module,                                 // 6. Database + Repositories
+storage.Module,
-    log.Module,                                      // 7. Logger initialization
+snapshot.Module,
-    storage.Module,                                  // 8. Storage backend (S3/file/rclone)
+fx.Provide(vaultik.New),
-    snapshot.Module,                                 // 9. SnapshotManager + ScannerFactory
+fx.Invoke(setupGlobals),
-    fx.Provide(vaultik.New),                         // 10. Vaultik orchestrator
+fx.NopLogger,
-)
 ```
 
-### Key Type Instantiation Points
+Each module provides these:
 
-#### 1. Config (`config.Config`)
+- `config.Module` provides `*config.Config`, from `config.Load`.
-- **Created by**: `config.Module` via `config.LoadConfig()`
+- `database.Module` provides `*database.DB` and `*database.Repositories`. It
-- **When**: Application startup (fx DI)
+  creates the index file with mode `0600` when it does not exist.
-- **Contains**: All configuration from YAML file (S3 credentials, encryption keys, paths, etc.)
+- `storage.Module` provides the `storage.Storer` that the config selects.
+- `snapshot.Module` provides the `snapshot.ScannerFactory` and the
+  `*snapshot.SnapshotManager`.
+- `vaultik.New` provides `*vaultik.Vaultik`.
 
-#### 2. Database (`database.DB`)
+A command runs through `cli.RunOperation`. It works like this:
-- **Created by**: `database.Module` via `database.New()`
-- **When**: Application startup (fx DI)
-- **Contains**: SQLite connection, path reference
 
-#### 3. Repositories (`database.Repositories`)
+- `RunWithApp` takes the lock when the command changes data, and then starts the
-- **Created by**: `database.Module` via `database.NewRepositories()`
+  application.
-- **When**: Application startup (fx DI)
+- The command's function runs in its own goroutine.
-- **Contains**: All repository interfaces (Files, Chunks, Blobs, Snapshots, etc.)
+- When the function returns, it asks the application to shut down.
+- On `SIGINT` or `SIGTERM`, the stop hook cancels the `Vaultik` context. It then
+  waits for the function to return, so that its temporary files are removed.
+- The wait ends after 30 seconds at most.
 
-#### 4. Vaultik (`vaultik.Vaultik`)
+The `config` commands, `database delete`, `completion` and `version` do not
-- **Created by**: `vaultik.New(VaultikParams)`
+build the application.
-- **When**: Application startup (fx DI)
-- **Contains**: All dependencies for backup operations
 
-```go
+## Backup
-type Vaultik struct {
-    Globals         *globals.Globals
-    Config          *config.Config
-    DB              *database.DB
-    Repositories    *database.Repositories
-    Storage         storage.Storer
-    ScannerFactory  snapshot.ScannerFactory
-    SnapshotManager *snapshot.SnapshotManager
-    Shutdowner      fx.Shutdowner
-    Fs              afero.Fs
-    ctx             context.Context
-    cancel          context.CancelFunc
-}
-```
 
-#### 5. SnapshotManager (`snapshot.SnapshotManager`)
+`Vaultik.CreateSnapshot` runs a backup. It does these steps in order:
-- **Created by**: `snapshot.Module` via `snapshot.NewSnapshotManager()`
-- **When**: Application startup (fx DI)
-- **Responsibility**: Creates/completes snapshots, exports metadata to S3
 
-#### 6. Scanner (`snapshot.Scanner`)
+- `EnsureStorageBinding` checks that the local index belongs to the configured
-- **Created by**: `ScannerFactory(ScannerParams)`
+  destination.
-- **When**: Each `CreateSnapshot()` call
+- `markDestination` checks the marker file and then writes it.
-- **Contains**: Chunker, Packer, progress reporter
+- `PruneDatabase` removes unfinished snapshots and unused records from the
+  local index.
+- `createNamedSnapshot` runs once for each snapshot name.
+- With `--prune`, `runPostBackupPrune` removes old snapshots and unused data.
 
-```go
+`CreateSnapshot` calls `skipPostBackupPrune` instead of `runPostBackupPrune` in
-// vaultik/snapshot.go: CreateSnapshot()
+these cases:
-scanner := v.ScannerFactory(snapshot.ScannerParams{
-    EnableProgress: !opts.Cron,
-    Fs:             v.Fs,
-})
-```
 
-#### 7. Chunker (`chunker.Chunker`)
+- `--skip-errors` skipped a file or directory that could not be read.
-- **Created by**: `chunker.NewChunker(avgChunkSize)`
+- A configured path held nothing.
-- **When**: Inside `snapshot.NewScanner()`
+- An earlier snapshot of the same name found a mount point that this backup did
-- **Configuration**:
+  not find.
-  - `avgChunkSize`: From config (default 10MB)
-  - `minChunkSize`: avgChunkSize / 4
-  - `maxChunkSize`: avgChunkSize * 4
 
-#### 8. Packer (`blob.Packer`)
+`PruneDatabase` must succeed before anything is scanned. An unfinished snapshot
-- **Created by**: `blob.NewPacker(PackerConfig)`
+left in the index would make the backup skip files that were never fully
-- **When**: Inside `snapshot.NewScanner()`
+stored.
-- **Configuration**:
-  - `MaxBlobSize`: Maximum blob size before finalization (typically 10GB)
-  - `CompressionLevel`: zstd level (1-19)
-  - `Recipients`: age public keys for encryption
 
-```go
+### One snapshot
-// snapshot/scanner.go: NewScanner()
-packerCfg := blob.PackerConfig{
-    MaxBlobSize:      cfg.MaxBlobSize,
-    CompressionLevel: cfg.CompressionLevel,
-    Recipients:       cfg.AgeRecipients,
-    Repositories:     cfg.Repositories,
-    Fs:               cfg.FS,
-}
-packer, err := blob.NewPacker(packerCfg)
-```
 
-## Module Responsibilities
+`createNamedSnapshot` does these steps:
 
-### `internal/cli`
+- `resolveSnapshotPaths` makes each configured path absolute and resolves
-Entry point for fx application. Combines all modules and handles signal interrupts.
+  symlinks.
+- `SnapshotManager.CreateSnapshotWithName` creates the snapshot record. The
+  record is not yet marked complete.
+- `Scanner.Scan` backs up each path in turn.
+- `finalizeSnapshotMetadata` uploads the snapshot's metadata and marks the
+  snapshot complete.
 
-Key functions:
+A new `Scanner` is created for each snapshot, from `ScannerFactory`. It owns a
-- `NewApp(AppOptions)` → Creates fx.App with all modules
+`Chunker` and a `Packer`.
-- `RunApp(ctx, app)` → Starts app, handles graceful shutdown
-- `RunWithApp(ctx, opts)` → Convenience wrapper
 
-### `internal/vaultik`
+### Scanning one path
-Main orchestrator containing all dependencies and command implementations.
 
-Key methods:
+`Scanner.Scan` works in these steps:
-- `New(VaultikParams)` → Constructor (fx DI)
-- `CreateSnapshot(opts)` → Main backup operation
-- `ListSnapshots(jsonOutput)` → List available snapshots
-- `VerifySnapshot(id, deep)` → Verify snapshot integrity
-- `PurgeSnapshots(...)` → Remove old snapshots
 
-### `internal/chunker`
+- `repairInterruptedBlobs` deletes the records of blobs whose upload never
-Content-defined chunking using FastCDC algorithm.
+  finished. Their data is then stored again.
+- `loadDatabaseState` loads the known files and chunks into memory.
+- `scanPhase` walks the path. It sorts each entry into changed or unchanged.
+- `detectDeletedFiles` counts the files that the previous snapshot of this name
+  had and that are now gone.
+- `batchAddFilesToSnapshot` records the unchanged files in the new snapshot.
+- `recordDirectories` records every directory, and the mount points found.
+- `processPhase` reads each changed file and stores it.
 
-Key types:
+The walk handles each kind of entry differently:
-- `Chunk` → Hash, Data, Offset, Size
-- `Chunker` → avgChunkSize, minChunkSize, maxChunkSize
 
-Key methods:
+- A regular file or a symlink is compared with its record in the index.
-- `NewChunker(avgChunkSize)` → Constructor
+- A directory is recorded with its metadata. It has no content to store.
-- `ChunkReaderStreaming(reader, callback)` → Stream chunks with callback (preferred)
+- A device node, a named pipe or a socket is skipped.
-- `ChunkReader(reader)` → Return all chunks at once (memory-intensive)
+- An entry that matches an exclude pattern is skipped. For a directory, so is
+  everything in it.
 
-### `internal/blob`
+### Deduplication
-Blob packing: accumulates chunks, compresses, encrypts, tracks metadata.
 
-Key types:
+Data is stored once at two levels.
-- `Packer` → Thread-safe blob accumulator
-- `ChunkRef` → Hash + Data for adding to packer
-- `FinishedBlob` → Completed blob ready for upload
-- `BlobWithReader` → FinishedBlob + io.Reader for streaming upload
 
-Key methods:
+- **Files.** A file is not read again when its record in the index still matches
-- `NewPacker(PackerConfig)` → Constructor
+  it.
-- `AddChunk(ChunkRef)` → Add chunk to current blob
+- **Chunks.** A chunk is named by the SHA-256 hash of its content. A chunk whose
-- `FinalizeBlob()` → Compress, encrypt, hash current blob
+  hash is already in the index is not stored again.
-- `Flush()` → Finalize any in-progress blob
-- `SetBlobHandler(func)` → Set callback for upload
 
-### `internal/snapshot`
+A file's record matches when all of these are unchanged:
 
-#### Scanner
+- the size
-Orchestrates the backup process for a directory.
+- the modification time
+- the mode
+- the owner and group
+- the link target
 
-Key methods:
+One case overrides the file check. A file is read again when it lists a chunk
-- `NewScanner(ScannerConfig)` → Constructor (creates Chunker + Packer)
+that no uploaded blob holds. This happens when the only snapshot that used the
-- `Scan(ctx, path, snapshotID)` → Main scan operation
+blob holding that chunk is removed. `loadFilesToRechunk` finds these files.
 
-Scan phases:
+### Chunks
-1. **Phase 0**: Detect deleted files from previous snapshots
-2. **Phase 1**: Walk directory, identify files needing processing
-3. **Phase 2**: Process files (chunk → pack → upload)
 
-#### SnapshotManager
+`chunker.Chunker` cuts a file with the FastCDC algorithm. The cut points depend
-Manages snapshot lifecycle and metadata export.
+on the content, so an insertion early in a file moves only nearby chunks.
 
-Key methods:
+`chunk_size` sets the average chunk size. No chunk is larger than four times
-- `CreateSnapshot(ctx, hostname, version, commit)` → Create snapshot record
+this size. Only a file's last chunk can be smaller than a quarter of it. With
-- `PopulateSnapshotBlobs(ctx, snapshotID)` → Record every blob the snapshot references
+the default of 10 MB, those limits are 40 MB and 2.5 MB.
-- `ExportSnapshotMetadata(ctx, dbPath, snapshotID)` → Export to S3
-- `MarkSnapshotComplete(ctx, snapshotID)` → Record completion, only after a successful export
-- `CompleteSnapshot(ctx, snapshotID)` → Convenience: populate blobs, then mark complete (no export between)
 
-### `internal/database`
+`ChunkReaderStreaming` passes each chunk to a callback as it is found. The whole
-SQLite database for local index. Single-writer mode for thread safety.
+file is never held in memory.
 
-Key types:
+### Blobs
-- `DB` → Database connection wrapper
-- `Repositories` → Collection of all repository interfaces
 
-Repository interfaces:
+`blob.Packer` collects new chunks into a blob. For each blob it does this:
-- `FilesRepository` → CRUD for File records
-- `ChunksRepository` → CRUD for Chunk records
-- `BlobsRepository` → CRUD for Blob records
-- `SnapshotsRepository` → CRUD for Snapshot records
-- Plus join table repositories (FileChunks, BlobChunks, etc.)
 
-## Snapshot Creation Flow
+- It gives the blob a UUID and creates a temporary file.
+- It adds each chunk's bytes to a running SHA-256 hash.
+- In the same pass it compresses the bytes with zstd and encrypts them with
+  age. The result goes to the temporary file.
+- It records each chunk's offset and length within the blob.
+- It closes the blob when the next chunk would pass `blob_size_limit`, and at
+  the end of each path.
 
-```
+The blob's name is `hex(SHA256(SHA256(uncompressed contents)))`. It is computed
-CreateSnapshot(opts)
+from the chunk data before compression and encryption.
-    │
+[docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#blobs) says what follows from
-    ├─► PruneDatabase()   // Critical: avoid dedup errors
+that.
-    │
-    ├─► SnapshotManager.CreateSnapshot()   // Create DB record
-    │
-    ├─► For each source directory:
-    │       │
-    │       ├─► scanner.Scan(ctx, path, snapshotID)
-    │       │       │
-    │       │       ├─► Phase 0: detectDeletedFiles()
-    │       │       │
-    │       │       ├─► Phase 1: scanPhase()
-    │       │       │       Walk directory
-    │       │       │       Check file metadata changes
-    │       │       │       Build list of files to process
-    │       │       │
-    │       │       └─► Phase 2: processPhase()
-    │       │               For each file:
-    │       │                   chunker.ChunkReaderStreaming()
-    │       │                   For each chunk:
-    │       │                       packer.AddChunk()
-    │       │                       If blob full → FinalizeBlob()
-    │       │                           → handleBlobReady()
-    │       │                           → s3Client.PutObjectWithProgress()
-    │       │               packer.Flush()  // Final blob
-    │       │
-    │       └─► Accumulate statistics
-    │
-    ├─► SnapshotManager.PopulateSnapshotBlobs()   // record referenced blobs
-    │
-    ├─► SnapshotManager.UpdateSnapshotStatsExtended()
-    │
-    ├─► SnapshotManager.ExportSnapshotMetadata()
-    │       │
-    │       ├─► Copy database to temp file
-    │       ├─► Clean to only current snapshot data (VACUUM)
-    │       ├─► Compress binary SQLite with zstd
-    │       ├─► Encrypt with age
-    │       ├─► Upload db.zst.age to storage
-    │       └─► Upload manifest.json.zst to storage
-    │
-    └─► SnapshotManager.MarkSnapshotComplete()   // only after the export succeeds
-```
 
-## Deduplication Strategy
+When a blob is closed, `Scanner.handleBlobReady` stores it:
 
-1. **File-level**: Files unchanged since last backup are skipped (metadata comparison: size, mtime, mode, uid, gid), unless the file lists a chunk that no uploaded blob holds; such a file is re-chunked
+- It looks the blob up at the destination. A blob that is already there is not
+  uploaded again.
+- Otherwise it uploads the temporary file to
+  `blobs/<hash[0:2]>/<hash[2:4]>/<hash>`.
+- It records the upload in the index and links the blob to the snapshot.
+- It deletes the temporary file.
 
-2. **Chunk-level**: Chunks are content-addressed by SHA256 hash. If a chunk hash already exists in the database, the chunk data is not re-uploaded.
+A file's record is written to the index only after every blob that holds its
+chunks is uploaded.
 
-3. **Blob-level**: Blobs contain only unique chunks. Duplicate chunks within a blob are skipped.
+### Snapshot metadata
 
-## Storage Layout in S3
+`finalizeSnapshotMetadata` does these steps in order:
 
-```
+- `PopulateSnapshotBlobs` records every blob the snapshot uses.
-bucket/
+- `UpdateSnapshotStatsExtended` stores the snapshot's totals.
-├── blobs/
+- `ExportSnapshotMetadata` uploads the metadata.
-│   └── {hash[0:2]}/
+- `MarkSnapshotComplete` marks the snapshot complete.
-│       └── {hash[2:4]}/
-│           └── {full-hash}          # Compressed+encrypted blob
-│
-└── metadata/
-    └── {remote-key}/
-        ├── db.zst.age               # Encrypted binary SQLite database
-        └── manifest.json.zst        # Blob list (for pruning/verification)
-```
 
-The `{remote-key}` directory name is a one-way double SHA-256 hash of the human
+Completion is recorded last on purpose. A backup that stops during the upload
-snapshot ID, so the human ID (hostname, snapshot name, timestamp) is never
+leaves the snapshot unfinished, and the next backup removes it and stores its
-written to the store as a directory name. See
+data again.
-[docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#remote-key-derivation) for the
-derivation and a worked example.
 
-## Thread Safety
+`ExportSnapshotMetadata` works on a copy of the index, never on the index
+itself:
 
-- `Packer`: Thread-safe via mutex. Multiple goroutines can call `AddChunk()`.
+- It copies the index into a temporary directory with `VACUUM INTO`.
-- `Scanner`: Uses `packerMu` mutex to coordinate blob finalization.
+- It deletes the rows of every other snapshot from the copy. It also deletes the
-- `Database`: Single-writer mode (`MaxOpenConns=1`) ensures SQLite thread safety.
+  files and blobs that this snapshot does not use. It then deletes each chunk
-- `Repositories.WithTx()`: Handles transaction lifecycle automatically.
+  that no remaining file and no remaining blob uses.
+- It keeps the `local_meta` and `schema_migrations` tables as they are. The
+  uploaded database therefore names the destination, and lists the migrations
+  that have run.
+- It runs `VACUUM`, so that no deleted row is left in the file.
+- It compresses the copy with zstd and encrypts it with age.
+- It builds the manifest from the copy.
+- It uploads `metadata/<remote-key>/db.zst.age`, and then
+  `metadata/<remote-key>/manifest.json.zst`.
+
+The manifest is uploaded last. A directory under `metadata/` with no manifest
+therefore marks a backup that did not finish.
+
+## Restore
+
+`Vaultik.Restore` does these steps:
+
+- `restoreIdentities` parses the age private key. A missing or malformed key
+  stops the restore before anything is downloaded.
+- `downloadSnapshotDB` downloads and decrypts the snapshot's database into a
+  temporary directory.
+- `getFilesToRestore` selects the files, from the paths given.
+- `restoreAllFiles` downloads blobs and writes the files.
+- With `--verify`, `verifyRestoredFiles` reads each restored file and checks its
+  chunk hashes.
+
+The restore does not read the local index or the manifest. It finds each file's
+chunks and blobs through the downloaded database.
+
+### Checks on the downloaded database
+
+Decryption shows that a database is readable. It does not show that the
+database is honest. The restore therefore checks it:
+
+- `database.OpenReadOnly` opens the file read-only. It refuses a file that has a
+  trigger, a view or a virtual table, or that lacks an expected table.
+- `verifySnapshotDBIdentity` checks that the snapshot in the database hashes to
+  the remote key that was asked for.
+- `containedRestorePath` refuses a stored path that would leave the target
+  directory. It also refuses to write through a symlink below the target.
+- A blob is not decompressed beyond the size that the database gives for it.
+- Each downloaded blob is hashed. The hash must match the blob's name.
+
+### Order of work
+
+`restorePlan` orders the files so that few blobs are on disk at once:
+
+- Downloaded blobs are kept decrypted in a cache directory.
+- A file is restored once every blob it needs is in the cache.
+- When no file is ready, the restore downloads the blobs for the file that
+  needs the fewest.
+- `restoreSweeper` deletes a cached blob once no remaining file needs it.
+
+A regular file is created with mode `0600` and gets its stored mode after its
+content is written. A directory gets its stored mode, owner and modification
+time after the whole restore.
+
+## Verify
+
+`Vaultik.VerifySnapshotWithOptions` checks a snapshot without the private key:
+
+- It downloads the manifest.
+- It checks that the snapshot's encrypted database is present.
+- It checks that each listed blob is present with the listed size.
+
+`Vaultik.RunDeepVerify` needs the private key. It does these steps:
+
+- It downloads the manifest and the database. It checks the database as a
+  restore does.
+- `verifyManifestAgainstDatabase` checks that both list the same blobs with the
+  same sizes.
+- `verifyBlobExistenceFromDB` checks that every blob is present with the
+  recorded size.
+- `verifyBlob` downloads each blob, checks the hash of each chunk in it, and
+  checks the hash that names the blob.
+
+## Prune
+
+`Vaultik.Prune` does three steps:
+
+- `CleanupLocalSnapshots` drops from the local index each snapshot whose
+  manifest is gone from the destination.
+- `PruneDatabase` removes unfinished snapshots and unused records from the
+  local index.
+- `PruneBlobs` deletes unused data at the destination.
+
+`PruneBlobs` reads every manifest at the destination. It then deletes two kinds
+of object, once they are older than `prune_grace_period`:
+
+- a blob that no manifest lists
+- a directory under `metadata/` that has no manifest, and whose snapshot is not
+  in the local index
+
+It deletes nothing when any manifest cannot be read.
+[docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#pruning) explains why this is
+safe, and where it is not.
+
+## The destination
+
+`storage.Storer` is the only way the code reaches the destination. It has these
+methods:
+
+- `Put` and `PutWithProgress` store an object.
+- `Get` reads an object.
+- `Stat` reports an object's size.
+- `Delete` removes an object.
+- `List` and `ListStream` list the objects under a prefix.
+- `DeletePartialUploads` removes what an interrupted upload left behind.
+- `Info` describes the destination.
+
+`storage.NewStorer` picks the implementation from `storage_url`:
+
+- `s3://` gives the S3 implementation.
+- `file://` gives the local directory implementation.
+- `rclone://` gives the rclone implementation.
+
+With no `storage_url`, it builds the S3 implementation from the `s3` settings.
+
+## The marker file and the destination binding
+
+Two checks keep the local index and the destination in step.
+
+- `checkDestinationMarker` looks for `vaultik-destination.txt`. It fails when
+  the file is reported missing while the local index holds snapshots.
+- `EnsureStorageBinding` records the configured destination in the local index
+  on first use. Later it fails when the config names a different destination.
+
+Every command that changes data calls `EnsureStorageBinding` first.
+
+## Concurrency
+
+- The local index is opened with one connection, so its queries run one at a
+  time.
+- The index runs in SQLite's WAL mode. A second process can therefore read it
+  while a backup writes to it.
+- `Packer` guards its state with a mutex.
+- `Scanner` holds `packerMu` while a chunk is added to the packer and while a
+  blob is closed.
+- `Repositories.WithTx` runs a function in one transaction. It commits when the
+  function succeeds and rolls back when it fails.

Dockerfile

@@ -5,7 +5,16 @@
 FROM golangci/golangci-lint:v2.14.0@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f AS lint
 WORKDIR /src
 COPY go.mod go.sum ./
-RUN go mod download
+# Without the time limit a stalled connection to the module proxy holds
+# this step, and every build on the host sharing it, until the kernel
+# drops the connection, which can take an hour. The limit is well above
+# the three minutes a working download can take on a busy build host.
+RUN for attempt in 1 2 3; do \
+        timeout 300 go mod download && exit 0; \
+        echo "go mod download attempt $attempt failed or ran over 300s" >&2; \
+    done; \
+    echo "module download failed: giving up after 3 attempts" >&2; \
+    exit 1
 COPY . .
 # `golangci-lint run` silently ignores an unknown top-level key in
 # .golangci.yml, such as a misspelt `linters:`; `config verify` fails on it.
@@ -18,7 +27,13 @@ RUN golangci-lint run --config .golangci.yml ./...
 FROM golang:1.26.1@sha256:cd78d88e00afadbedd272f977d375a6247455f3a4b1178f8ae8bbcb201743a8a AS test
 WORKDIR /src
 COPY go.mod go.sum ./
-RUN go mod download
+# Limited and retried as in the lint phase above.
+RUN for attempt in 1 2 3; do \
+        timeout 300 go mod download && exit 0; \
+        echo "go mod download attempt $attempt failed or ran over 300s" >&2; \
+    done; \
+    echo "module download failed: giving up after 3 attempts" >&2; \
+    exit 1
 COPY . .
 RUN go test -timeout 90s -race -cover ./... || \
     { echo "--- Rerunning with -v for details ---"; \
@@ -36,7 +51,13 @@ RUN apk add --no-cache git
 RUN git config --system --add safe.directory /src
 WORKDIR /src
 COPY go.mod go.sum ./
-RUN go mod download
+# Limited and retried as in the lint phase above.
+RUN for attempt in 1 2 3; do \
+        timeout 300 go mod download && exit 0; \
+        echo "go mod download attempt $attempt failed or ran over 300s" >&2; \
+    done; \
+    echo "module download failed: giving up after 3 attempts" >&2; \
+    exit 1
 COPY . .
 
 # The VERSION build arg when one is given, otherwise

TODO.md

@@ -15,13 +15,370 @@ pre-1.0
 # Next Step
 
 The 1.0 work is complete on `next`: the scope settled on
-[issue #125](https://git.eeqj.de/sneak/vaultik/issues/125) was the work
+[issue #125](https://git.eeqj.de/sneak/vaultik/issues/125) has landed,
-already planned for 1.0, and all of it has landed. The mechanism to cut
+and so has every fix from the defect hunt before the release candidate
-the tag exists and is exercised; what is left is merging `next` to
+([issue #288](https://git.eeqj.de/sneak/vaultik/issues/288)). What is
-`main` and tagging, both the owner's.
+left is merging `next` to `main` and tagging the release, both the
+owner's; a `v*` tag runs the release build in
+`.gitea/workflows/release.yml`.
 
 # Completed Steps
 
+- 2026-10-15: Stopped `snapshot create --prune` pruning after a backup
+  in which a volume mounted below a configured path in an earlier
+  snapshot of the same name was not mounted
+  ([issue #395](https://git.eeqj.de/sneak/vaultik/issues/395)). Such a
+  prune could delete every snapshot still holding the volume's files.
+  Each snapshot now records in the local index the directories it found
+  on a different filesystem from their parent and found an entry in that
+  the backup does not exclude.
+
+- 2026-10-14: Stopped `snapshot create --prune` pruning after a backup
+  that found nothing in a configured path
+  ([issue #388](https://git.eeqj.de/sneak/vaultik/issues/388)), as in
+  the mount point of a volume that is not mounted. Such a prune could
+  delete every snapshot still holding that path's files. A configured
+  path that is a symlink whose target is gone, as one into such a
+  volume, now fails the backup, with or without `--prune`.
+
+- 2026-10-14: Stopped `snapshot create --prune` pruning after a backup
+  that skipped files it could not read
+  ([issue #382](https://git.eeqj.de/sneak/vaultik/issues/382)). Such a
+  prune could delete the only snapshot still holding those files.
+
+- 2026-10-14: Made `snapshot create --skip-errors` exit non-zero,
+  instead of 0, when it skips anything it cannot read
+  ([issue #310](https://git.eeqj.de/sneak/vaultik/issues/310)).
+
+- 2026-10-14: Kept the local index when `remote nuke` cannot list or
+  find the destination store
+  ([issue #292](https://git.eeqj.de/sneak/vaultik/issues/292)). Nuke
+  had cleared the local snapshot records anyway; it now fails before
+  removing anything.
+
+- 2026-10-14: Stopped counting directories and unchanged symlinks as
+  files to back up
+  ([issue #305](https://git.eeqj.de/sneak/vaultik/issues/305)).
+
+- 2026-10-14: Refused a backup destination that an unplugged volume
+  left empty, as the owner ruled
+  ([issue #239](https://git.eeqj.de/sneak/vaultik/issues/239)). Every
+  backup now writes `vaultik-destination.txt` at the destination root,
+  and while the local index holds snapshots stored there, a destination
+  without it is treated as not present.
+
+- 2026-10-14: Warned about restored ownership only when an entry's
+  owner or group differs from the recorded one
+  ([issue #316](https://git.eeqj.de/sneak/vaultik/issues/316)); a
+  restore by a non-root user had warned even when none did.
+
+- 2026-10-14: Made `snapshot list` report a changed destination instead
+  of advising `prune`, which refuses in that case
+  ([issue #317](https://git.eeqj.de/sneak/vaultik/issues/317)).
+
+- 2026-10-14: Counted a file as deleted by a backup only if the
+  previous snapshot of the same name listed it
+  ([issue #304](https://git.eeqj.de/sneak/vaultik/issues/304)); files
+  that snapshot did not list had been counted too.
+
+- 2026-10-14: Named each prefix once in restore, verify and purge
+  errors, some of which repeated it
+  ([issue #327](https://git.eeqj.de/sneak/vaultik/issues/327)). A deep
+  verify log line that named S3 whatever the destination now names
+  storage.
+
+- 2026-10-14: Refused credentials in a storage URL's endpoint or rclone
+  remote name, which were accepted and could then be printed
+  ([issue #322](https://git.eeqj.de/sneak/vaultik/issues/322)).
+
+- 2026-10-14: Ran `$EDITOR` through the shell in `config edit`, so a
+  value with arguments, such as `code --wait`, no longer fails
+  ([issue #315](https://git.eeqj.de/sneak/vaultik/issues/315)).
+
+- 2026-10-14: Made `snapshot remove` fail, instead of exiting 0, when
+  it cannot delete the metadata of a snapshot that is only on the
+  destination store
+  ([issue #340](https://git.eeqj.de/sneak/vaultik/issues/340)). The
+  README and the help now say when it prints the `vaultik prune`
+  follow-up.
+
+- 2026-10-14: Labelled the totals in the local index cleanup before
+  each backup as totals
+  ([issue #306](https://git.eeqj.de/sneak/vaultik/issues/306)). Each
+  was shown as `(N remain)`, which read as rows left to clean up.
+
+- 2026-10-13: Freed a cached blob once no file still to restore needs
+  it ([issue #324](https://git.eeqj.de/sneak/vaultik/issues/324)); one
+  also used by a file outside the selected paths had stayed in the
+  temporary cache until the restore ended.
+
+- 2026-10-13: Kept the whole startup error when it contains `): `
+  ([issue #320](https://git.eeqj.de/sneak/vaultik/issues/320)). Such
+  an error was cut at its last `): `, so the `blob_size_limit` one lost
+  the setting's name.
+
+- 2026-10-13: Silenced the status lines of `prune` and snapshot removal
+  under `--cron` and `--quiet`
+  ([issue #294](https://git.eeqj.de/sneak/vaultik/issues/294)).
+
+- 2026-10-13: Read the rclone config file that `RCLONE_CONFIG` names
+  ([issue #321](https://git.eeqj.de/sneak/vaultik/issues/321)); a
+  remote defined only there had been reported as not found.
+
+- 2026-10-13: Made `/**/` in an exclude pattern match zero directories,
+  as in gitignore
+  ([issue #338](https://git.eeqj.de/sneak/vaultik/issues/338));
+  `a/**/*.log` had missed `a/x.log`.
+
+- 2026-10-13: Made the `chunk_size` and `blob_size_limit` defaults and
+  the `chunk_size` minimum 1000-based, like the size parser and the
+  docs ([issue #313](https://git.eeqj.de/sneak/vaultik/issues/313)).
+
+- 2026-10-13: Kept a snapshot's remote metadata when `snapshot purge`
+  cannot remove it from the local index
+  ([issue #337](https://git.eeqj.de/sneak/vaultik/issues/337)); the
+  purge had deleted the metadata anyway and exited 0.
+
+- 2026-10-13: Made `snapshot restore` fail for a requested path that
+  matches nothing, which it had ignored
+  ([issue #309](https://git.eeqj.de/sneak/vaultik/issues/309)).
+
+- 2026-10-13: Made `remote nuke` delete every object under `metadata/`
+  and `blobs/`
+  ([issue #291](https://git.eeqj.de/sneak/vaultik/issues/291)); it had
+  left some, such as a stray `.DS_Store`, while reporting the store
+  empty.
+
+- 2026-10-13: Made `config set` create a list for an index under a
+  missing key
+  ([issue #308](https://git.eeqj.de/sneak/vaultik/issues/308)); it had
+  written a map, after which no command could load the config.
+
+- 2026-10-13: Listed a `file://` destination through a symlinked
+  `metadata/` or `blobs/`, which had listed as empty
+  ([issue #296](https://git.eeqj.de/sneak/vaultik/issues/296)). A link
+  to a missing target now fails the listing
+  ([issue #332](https://git.eeqj.de/sneak/vaultik/issues/332)).
+
+- 2026-10-13: Made `snapshot verify --deep --json` report its blob
+  counts ([issue #314](https://git.eeqj.de/sneak/vaultik/issues/314));
+  a failed run had reported 0 missing and 0 verified.
+
+- 2026-10-13: Limited and retried the module download in the Docker
+  build ([issue #351](https://git.eeqj.de/sneak/vaultik/issues/351)),
+  which had hung for as long as a stalled connection to the module
+  proxy lasted.
+
+- 2026-10-13: Recorded each snapshot's uncompressed size when its
+  backup runs
+  ([issue #360](https://git.eeqj.de/sneak/vaultik/issues/360)). A later
+  backup could change an older snapshot's UNCOMPRESSED SIZE in
+  `snapshot list`.
+
+- 2026-10-13: Stopped `snapshot restore --skip-errors --verify`
+  reporting a file that failed to restore again as a checksum failure
+  ([issue #323](https://git.eeqj.de/sneak/vaultik/issues/323)).
+
+- 2026-10-13: Recorded the stored size of a blob a backup finds already
+  stored, not the size of its local copy, which can differ, so
+  `snapshot verify` could fail on a good snapshot
+  ([issue #300](https://git.eeqj.de/sneak/vaultik/issues/300)).
+
+- 2026-10-13: Stopped the local index and the blob upload step ending
+  the process on a failed close of query results or a failed temp file
+  cleanup ([issue #345](https://git.eeqj.de/sneak/vaultik/issues/345));
+  both are now returned as errors.
+
+- 2026-10-13: Closed the snapshot database's storage reader too when
+  restore or deep verify is interrupted
+  ([issue #356](https://git.eeqj.de/sneak/vaultik/issues/356)).
+
+- 2026-10-13: Made `prune` and `remote nuke` fail when a delete on the
+  backup destination store fails
+  ([issue #290](https://git.eeqj.de/sneak/vaultik/issues/290)).
+
+- 2026-10-13: Made an S3 listing that the server cuts short an error
+  ([issue #297](https://git.eeqj.de/sneak/vaultik/issues/297)); `prune`
+  had taken it as complete and could delete blobs still in use.
+
+- 2026-10-13: Made shallow `snapshot verify` report a blob it could not
+  check apart from a missing one
+  ([issue #318](https://git.eeqj.de/sneak/vaultik/issues/318)); any
+  error checking a blob had counted as missing, its cause dropped.
+
+- 2026-10-13: Restored the other files when a file's chunk is in no
+  blob under `--skip-errors`
+  ([issue #326](https://git.eeqj.de/sneak/vaultik/issues/326)); that
+  file had stopped the restore before anything was restored.
+
+- 2026-10-13: Recorded each snapshot's new chunk size when its backup
+  runs ([issue #311](https://git.eeqj.de/sneak/vaultik/issues/311)).
+  `snapshot list` could show a NEW CHUNK SIZE of 0 B for a snapshot
+  whose change was a modified file.
+
+- 2026-10-13: Made a backup interrupted during a local index write exit
+  as interrupted
+  ([issue #301](https://git.eeqj.de/sneak/vaultik/issues/301)); it could
+  end with `FATAL: failed to rollback transaction` and exit 1 instead of
+  130.
+
+- 2026-10-13: Printed `snapshot list` and `snapshot purge` sizes like
+  every other command
+  ([issue #312](https://git.eeqj.de/sneak/vaultik/issues/312)). They,
+  and the `bytes` value in terminal log lines, were 1024-based but
+  labelled KB or MB, and now use 1000-based units.
+
+- 2026-10-13: Closed each blob's storage reader when restore or deep
+  verify is interrupted, which ends a stalled read unless it is stuck in
+  the kernel ([issue #325](https://git.eeqj.de/sneak/vaultik/issues/325)).
+
+- 2026-10-13: Made a mistyped subcommand under `snapshot`, `config`,
+  `remote`, `database` or `completion` an error
+  ([issue #319](https://git.eeqj.de/sneak/vaultik/issues/319)); each had
+  printed its help and exited 0.
+
+- 2026-10-13: Made an exclude pattern starting with `**/` match
+  directly under the snapshot path too, as in gitignore
+  ([issue #303](https://git.eeqj.de/sneak/vaultik/issues/303)).
+
+- 2026-10-13: Refused a relative `file://` storage URL and decoded its
+  percent-escapes
+  ([issue #299](https://git.eeqj.de/sneak/vaultik/issues/299)); a
+  relative path had moved with the working directory.
+
+- 2026-10-13: Removed the blob temp file when a backup stops part-way
+  ([issue #302](https://git.eeqj.de/sneak/vaultik/issues/302)); the
+  half-written blob had stayed in `$TMPDIR`.
+
+- 2026-10-13: Checked `--keep-newer-than` before a backup starts
+  ([issue #307](https://git.eeqj.de/sneak/vaultik/issues/307)); an
+  invalid value had been read only by the prune after the backup, so
+  retention never ran.
+
+- 2026-10-13: Stopped `remote info` counting a file under `blobs/` that
+  is not a blob as an orphaned blob
+  ([issue #295](https://git.eeqj.de/sneak/vaultik/issues/295)). A stray
+  file such as `.DS_Store` was reported as an orphaned blob and the
+  report advised running `prune`, which skips such a file and deleted
+  nothing. `remote info` now takes its blob list from the same listing
+  `prune` uses, in the table and in `--json`.
+
+- 2026-10-13: Made `snapshot remove` fail for a snapshot that does not
+  exist ([issue #293](https://git.eeqj.de/sneak/vaultik/issues/293)).
+  The command never checked the ID: it reported the snapshot removed
+  from the local database and from the destination store and exited 0,
+  under `--json`, `--dry-run` and `--local-only` too. An ID that names
+  no snapshot in the local index or on the destination store is now an
+  error; with `--local-only`, the snapshot must be in the local index.
+  The command now reports a removal from either side only when one
+  happened, and `remote_removed` is true only when metadata was deleted.
+
+- 2026-10-12: Bound the local index to the destination an `s3.*` config
+  names ([issue #298](https://git.eeqj.de/sneak/vaultik/issues/298)).
+  Only `storage_url` was checked, so after `s3.bucket` or `s3.prefix`
+  changed, the next backup treated every chunk as already stored,
+  uploaded nothing, and completed a snapshot that could not be restored.
+  Without `storage_url`, the local index is now bound to `s3.endpoint`,
+  `s3.bucket` and `s3.prefix`, and a change is refused as a changed
+  `storage_url` is.
+
+- 2026-10-12: Rejected a retention duration longer than about 292 years
+  ([issue #289](https://git.eeqj.de/sneak/vaultik/issues/289)). The
+  number given to `--older-than` or `--keep-newer-than` was multiplied
+  by the length of its unit with no limit, so from `293y`, `15251w`,
+  `3559mo` or `106752d`, or a sum of parts such as `200y200y`, the
+  result wrapped to a negative duration. The cutoff then lay in the
+  future, every snapshot of the name was deleted, the one just made
+  included, and the command exited 0. Such a duration is now rejected
+  as invalid and nothing is deleted.
+
+- 2026-10-08: Made a backup cancelled under `--skip-errors` stop at once
+  ([issue #286](https://git.eeqj.de/sneak/vaultik/issues/286)). After
+  Ctrl-C or SIGTERM, phase 2 treated the cancellation error from each
+  remaining file like an unreadable file: it opened the file, printed an
+  error line for it, counted it as failed and went on to the next one.
+  The run now stops at the first file after the cancellation, and no
+  file is counted as failed because of it.
+
+- 2026-10-08: Made `remote nuke` delete the `.partial` files that
+  uploads cut off part-way leave on the destination store
+  ([issue #281](https://git.eeqj.de/sneak/vaultik/issues/281)). The
+  file and rclone listings skip such a file, so the command left it in
+  place and still reported the store empty. It now removes them under
+  `metadata/` and `blobs/` as its last step.
+
+- 2026-10-08: Made a local index error while recording a directory or
+  symlink stop a backup under `--skip-errors`
+  ([issue #284](https://git.eeqj.de/sneak/vaultik/issues/284)). Phase 2
+  only records such an entry in the local index, since it has no data
+  to open or read, but an error doing so was skipped like an unreadable
+  file. The snapshot then completed without the entry, and a restore
+  did not recreate it. The error now stops the backup, as it does
+  without the flag.
+
+- 2026-10-08: Counted a file that a backup could not store as failed
+  ([issue #280](https://git.eeqj.de/sneak/vaultik/issues/280)). A file
+  that phase 1 counted and phase 2 could not open, because it was
+  unreadable under `--skip-errors` or removed in between, was reported
+  in the summary as unchanged with its bytes as backed up, and the
+  `snapshots` row's `file_count` and `total_size` included it. The
+  summary now counts it as failed, and its data total and the row leave
+  it out.
+
+- 2026-10-08: Made `remote info` report a snapshot's blob count and
+  blob size as unknown when its manifest cannot be read
+  ([issue #272](https://git.eeqj.de/sneak/vaultik/issues/272)). The
+  orphan figures were already unknown in that case, but the snapshot's
+  row still gave 0 blobs and 0 B, in the table and in `--json`. The row
+  now reads `unknown` and `--json` gives `null`. A directory with no
+  manifest still shows 0, since the orphan figures count its blobs as
+  orphaned.
+
+- 2026-10-08: Kept the progress line of a snapshot with more than one
+  path within 100%
+  ([issue #271](https://git.eeqj.de/sneak/vaultik/issues/271)). The
+  bytes and files processed counted every path, but the totals they
+  were divided by held only the current path's, so a second path
+  smaller than the first showed more than 100% and an ETA of `unknown`.
+  The totals now add up over the paths scanned so far. The rate behind
+  the ETA restarts when each path's scan phase ends, so that phase does
+  not lower the rate while the path is processed; until then the rate
+  is the previous path's.
+
+- 2026-10-08: Made a second `snapshot create` of one name succeed when
+  it starts in the same second as the first
+  ([issue #270](https://git.eeqj.de/sneak/vaultik/issues/270)). The
+  timestamp in a snapshot ID is in whole seconds, so the second run got
+  the first run's ID and failed with `UNIQUE constraint failed:
+  snapshots.id`. When the local index already has a snapshot with the
+  ID, the create now waits a second and takes a new timestamp.
+
+- 2026-10-07: Documented that `--json` skips the confirmation prompt of
+  `snapshot remove` and `prune`
+  ([issue #268](https://git.eeqj.de/sneak/vaultik/issues/268)). Both
+  commands delete without asking under `--json`, since a prompt on stdout
+  would break the JSON document, but the help and the README described
+  only `--force` as skipping it. The `--json` help of both commands and
+  their README entries now say so.
+
+- 2026-10-07: Made a symlink whose target cannot be read stop the backup
+  ([issue #269](https://git.eeqj.de/sneak/vaultik/issues/269)). It was
+  left out of the snapshot with only a debug log line, even without
+  `--skip-errors`. It now aborts the run, or with `--skip-errors` is
+  skipped with the `Failed to access` error line that any other entry
+  the scan cannot read gets.
+
+- 2026-10-07: Stopped a killed rclone upload from leaving a truncated
+  object under its key
+  ([issue #266](https://git.eeqj.de/sneak/vaultik/issues/266)). The
+  rclone backend wrote each object straight to its key, so killing an
+  upload to a local or sftp remote left a truncated object there; the
+  next backup found the key with `Stat`, skipped the upload and recorded
+  a snapshot that could not be restored. On a remote with a server-side
+  move, an object is now written under a temporary name ending in
+  `.partial` and moved into place, and listings skip such names. Remotes
+  without one are still written in place.
+
 - 2026-10-07: Made an interrupted command exit 130 and say so
   ([issue #267](https://git.eeqj.de/sneak/vaultik/issues/267)). Ctrl-C
   or SIGTERM during `snapshot create`, `snapshot restore` or `snapshot
@@ -959,5 +1316,64 @@ the tag exists and is exercised; what is left is merging `next` to
 
 # Future Steps
 
-Work planned after 1.0 is listed in the README
+Work planned after 1.0, loosely ordered by priority.
-[roadmap](README.md#roadmap).
+
+## Correctness and operability
+
+- **Outside security audit.** Before 1.0 the encryption and
+  blob-generation code was reviewed. Every bug the review found was
+  fixed. The risks it accepted are listed in
+  [Accepted risks](docs/REPOSTRUCTURE.md#accepted-risks). No outside
+  audit has been done. age, zstd and content-defined chunking are mostly
+  off-the-shelf pieces. The code that joins them needs an outside read:
+    - key handling
+    - recipient parsing
+    - manifest trust boundary
+    - restore-time identity validation
+- **Verify restored content end-to-end in CI.** The current integration
+  test does this for a small synthetic snapshot but not at scale. A
+  nightly job against a multi-GB representative snapshot would catch
+  silent regressions in the chunker, packer, or restore planner.
+
+## Performance
+
+- **Parallel blob downloads during restore.** A restore downloads one
+  blob at a time now. With a fast S3 endpoint and a multi-core machine,
+  restore speed is bound by the fetch, decryption and decompression of
+  each blob. Running several of those in parallel against the disk
+  cache would close most of the remaining gap. This needs to interact
+  correctly with the locality planner and the sweeper.
+- **Bandwidth limiting (`--bwlimit`).** For both upload and download.
+  It is useful for backing up over a shared link. It is tricky to make
+  work correctly with parallel downloads.
+- **Restart of interrupted restore.** Today a restore can be started
+  again, and it then overwrites the partial output. It does not resume
+  from where it stopped, and it does not skip files that are already
+  present. A `--resume` mode that checks targets before fetching blobs
+  would matter for very large restores.
+- **Daemon mode.** A long-running mode that watches for file changes,
+  so that frequent backups, such as hourly ones, skip the full scan. It
+  adds little for the usual backups from cron every 12 to 36 hours. See
+  [issue #204](https://git.eeqj.de/sneak/vaultik/issues/204).
+
+## Usability
+
+- **Man pages and richer `--help` examples.** Cobra generates basic
+  help. Man pages would be a separate target.
+- **`vaultik snapshot diff <a> <b>`.** Show which files changed between
+  two snapshots, without restoring either.
+- **Status reporting hook for `--cron`.** When a backup fails silently
+  in cron, the user has no idea. A configurable hook on completion, for
+  both success and failure, would close the loop. It could be a
+  webhook, an email or `notify-send`.
+
+## Infrastructure
+
+- **Schema migrations after 1.0.** Migrations are supported, but none
+  are added before 1.0 because there is no installed base yet. After
+  1.0, each schema change is a new migration, so an existing local
+  index is migrated when `vaultik` is updated. See
+  [`docs/DATAMODEL.md`](docs/DATAMODEL.md#schema-migrations).
+- **Storage backend coverage tests.** S3, `file://` and `rclone://` all
+  share the `Storer` interface, but the rclone path is the least
+  exercised in CI.

cmd/vaultik/dockermoddownload_test.go

@@ -0,0 +1,45 @@
+package main_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestDockerfileBoundsEveryModuleDownload fails unless every
+// `go mod download` in the Dockerfile runs under a time limit, is tried
+// a fixed number of times, and then fails the build with a message that
+// names the module download (issue #351). Like the version tests, this
+// parses the Dockerfile; that a stalled download really is cut off and
+// retried was checked by hand.
+func TestDockerfileBoundsEveryModuleDownload(t *testing.T) {
+	t.Parallel()
+
+	var downloads []string
+
+	for _, instruction := range instructions(t, productDockerfile) {
+		if strings.Contains(instruction, "go mod download") {
+			downloads = append(downloads, instruction)
+		}
+	}
+
+	require.NotEmpty(t, downloads, "%s must download modules",
+		productDockerfile)
+
+	for _, download := range downloads {
+		assert.Contains(t, download, "timeout 300 go mod download",
+			"%s: a module download must have a time limit: %s",
+			productDockerfile, download)
+		assert.Contains(t, download, "for attempt in 1 2 3",
+			"%s: a module download must be retried: %s",
+			productDockerfile, download)
+		assert.Contains(t, download, "module download failed",
+			"%s: a module download that never succeeds must say so: %s",
+			productDockerfile, download)
+		assert.True(t, strings.HasSuffix(download, "exit 1"),
+			"%s: a module download that never succeeds must fail the"+
+				" build: %s", productDockerfile, download)
+	}
+}

config.example.yml

@@ -1,16 +1,31 @@
 # vaultik configuration file example
-# This file shows all available configuration options with their default values
+# This file shows every configuration option. The values are examples, not
-# Copy this file and uncomment/modify the values you need
+# defaults; where an option has a default, its comment gives it.
+# Copy this file and change the values you need
 
 # Age recipient public keys for encryption
 # Backups are encrypted to these public keys. snapshot create needs at least
 # one; listing, verifying and restoring do not
-# Generate with: age-keygen | grep "public key"
+# Generate a key pair, and show its public key, with:
+#   age-keygen -o vaultik_backup_private_key.txt
+#   grep 'public key' vaultik_backup_private_key.txt
+# Keep the private key file: restoring needs it. Do not pipe age-keygen
+# straight into grep, which would discard the private key
 age_recipients:
   - age1cj2k2addawy294f6k2gr2mf9gps9r3syplryxca3nvxj3daqm96qfp84tz
 
+# Age private key for decryption
+# Only snapshot restore and snapshot verify --deep need it. The
+# VAULTIK_AGE_SECRET_KEY environment variable overrides this setting
+# Do not set it on a machine you back up: prefer the environment variable,
+# supplied only on the machine you restore on
+# Default: not set
+#age_secret_key: YOUR_AGE_PRIVATE_KEY
+
 # Named snapshots - each snapshot can contain multiple paths
 # Each snapshot gets its own ID and can have snapshot-specific excludes
+# Required: at least one snapshot with at least one path. Only the config
+# commands, version and completion run without one
 snapshots:
   testing:
     paths:
@@ -258,6 +273,11 @@ exclude:
 
 # Storage URL - use either this OR the s3 section below
 # Supports: s3://bucket/prefix, file:///path, rclone://remote/path
+# An s3:// URL also needs s3.access_key_id and s3.secret_access_key below
+# A file:// path must be absolute, and the directory must already exist:
+# vaultik never creates it
+# An rclone:// URL needs the remote to be defined in rclone's own config
+# (rclone config)
 storage_url: "rclone://myremote/path/to/backups"
 
 # S3-compatible storage configuration
@@ -283,6 +303,8 @@ storage_url: "rclone://myremote/path/to/backups"
 #  #region: us-east-1
 #
 #  # Use SSL/TLS for S3 connections
+#  # Only read when storage_url is not set and the endpoint has no scheme;
+#  # with an s3:// storage_url, use ?ssl=false in the URL instead
 #  # Default: true
 #  #use_ssl: true
 #
@@ -295,6 +317,7 @@ storage_url: "rclone://myremote/path/to/backups"
 
 # Path to local SQLite index database
 # This database tracks file state for incremental backups
+# The VAULTIK_INDEX_PATH environment variable overrides this setting
 # Default: the platform data directory, e.g.
 #   macOS: ~/Library/Application Support/vaultik/index.sqlite
 #   Linux: ~/.local/share/vaultik/index.sqlite
@@ -302,7 +325,8 @@ storage_url: "rclone://myremote/path/to/backups"
 
 # Average chunk size for content-defined chunking
 # Smaller chunks = better deduplication but more metadata
-# Supports: 10MB, 5M, 1GB, 500KB, 64MiB, etc.
+# Minimum 1MB
+# Supports: 10MB, 5M, 1GB, 64MiB, etc.
 # Default: 10MB
 #chunk_size: 10MB
 
@@ -327,6 +351,20 @@ storage_url: "rclone://myremote/path/to/backups"
 # Higher = better compression but slower
 # Default: 3
 compression_level: 5
+
+# How old a blob that no snapshot lists must be before prune deletes it, and
+# how old every object in a directory under metadata/ with no manifest must
+# be before prune deletes that directory
+# A backup uploads its blobs and its db.zst.age before its manifest, so on a
+# destination shared between hosts or users this must be longer than the
+# longest backup run
+# It does not protect a blob a backup reuses from an earlier run that stopped
+# before its manifest: that blob keeps the time of its first upload, so a
+# prune can delete it
+# Supports: 36h, 90m, etc.; 0s deletes such blobs and directories at once
+# Default: 24h
+#prune_grace_period: 24h
+
 # Hostname to use in backup metadata
 # Default: system hostname
 #hostname: myserver

docs/DATAMODEL.md

@@ -1,290 +1,418 @@
-# Vaultik Data Model
+# vaultik data model
 
-## Overview
+`vaultik` keeps a SQLite database on the backed-up machine, called the local
+index. This document describes its tables and how each command uses them.
 
-Vaultik uses a local SQLite database to track file metadata, chunk mappings, and blob associations during the backup process. This database serves as an index for incremental backups and enables efficient deduplication.
+The local index has two jobs:
 
-**Important Notes:**
+- It records which files, chunks and blobs are already stored. The next backup
+  then does not store them again.
+- It is the source of each snapshot's own database. A backup uploads a trimmed,
+  encrypted copy of the index with every snapshot.
 
-- **Version Compatibility**: In rare cases, you may need to use the same version
+A restore does not need the local index. It reads the copy that was uploaded
-  of Vaultik to restore a backup as was used to create it. This ensures
+with the snapshot.
-  compatibility with the metadata format stored in S3.
 
-## Schema Migrations
+## Terms
 
-Vaultik supports schema migrations. They are the numbered SQL files in
+- **Snapshot**: one backup of the paths listed under one name in the config.
-`internal/database/schema/`, embedded in the binary: `000.sql` creates the
+- **Chunk**: a piece of a file's content, named by the SHA-256 hash of that
-`schema_migrations` table, which records each migration that has run, and
+  content.
-`001.sql` creates the application tables. `database.New` opens a database and
+- **Blob**: one object at the destination. It holds many chunks, compressed and
-applies, in order, every migration that database has not yet recorded.
+  then encrypted.
+- **Destination**: the place the backups are stored.
+- **Manifest**: the unencrypted list of the blobs one snapshot uses.
+- **Remote key**: a hash of the snapshot ID. It names the snapshot's directory
+  at the destination.
 
-**Before 1.0** no migrations are added, because nothing is installed anywhere
+## Where the index is
-yet. A schema change edits `001.sql` (and the code that uses the affected
-tables) directly. A local database created before the change has already
-recorded `001.sql` as run, so it keeps the old schema and can become unusable;
-`vaultik database delete` followed by a full backup rebuilds it.
-
-**After 1.0** each schema change is a new numbered file, so an existing local
-database is migrated the first time an updated vaultik opens it. A file that
-has shipped in a release is never edited.
-
-## Database Tables
-
-### 1. `files`
-Stores metadata about files in the filesystem being backed up.
 
-**Columns:**
+The index is the file `index.sqlite` in the platform data directory. That is
-- `id` (TEXT PRIMARY KEY) - UUID for the file record
+`~/.local/share/vaultik/` on Linux and `~/Library/Application Support/vaultik/`
-- `path` (TEXT NOT NULL UNIQUE) - Absolute file path
+on macOS. The `index_path` setting and the `VAULTIK_INDEX_PATH` environment
-- `mtime` (INTEGER NOT NULL) - Modification time, whole seconds since the Unix epoch
+variable change the path.
-- `mtime_nsec` (INTEGER NOT NULL) - Nanoseconds within that second, 0 to 999999999
-- `size` (INTEGER NOT NULL) - File size in bytes
-- `mode` (INTEGER NOT NULL) - Unix file permissions and type
-- `uid` (INTEGER NOT NULL) - User ID of file owner
-- `gid` (INTEGER NOT NULL) - Group ID of file owner
-- `link_target` (TEXT) - Symlink target path (NULL for regular files)
 
-**Indexes:**
+The file is readable only by its owner, because it lists every backed-up path.
-- `idx_files_path` on `path` for efficient lookups
+`vaultik` sets that mode each time it opens the index.
-
-**Purpose:** Tracks file metadata to detect changes between backup runs. Used for incremental backup decisions. The UUID primary key provides stable references that don't change if files are moved.
 
-### 2. `chunks`
+## Schema migrations
-Stores information about content-defined chunks created from files.
 
-**Columns:**
+`vaultik` supports schema migrations. They are the numbered SQL files in
-- `chunk_hash` (TEXT PRIMARY KEY) - SHA256 hash of chunk content
+`internal/database/schema/`, which are built into the binary.
-- `size` (INTEGER NOT NULL) - Chunk size in bytes
 
-**Purpose:** Enables deduplication by tracking unique chunks across all files.
+- `000.sql` creates the `schema_migrations` table. That table records each
-
+  migration that has run.
-### 3. `file_chunks`
+- `001.sql` creates every other table.
-Maps files to their constituent chunks in order.
 
-**Columns:**
+`database.New` opens the index. It then applies, in order, every migration that
-- `file_id` (TEXT) - File ID (FK to files.id)
+the index has not recorded.
-- `idx` (INTEGER) - Chunk index within file (0-based)
-- `chunk_hash` (TEXT) - Chunk hash (FK to chunks.chunk_hash)
-- PRIMARY KEY (`file_id`, `idx`)
 
-**Purpose:** Allows reconstruction of files from chunks during restore.
+Before version 1.0, no migration is added, because nothing is installed anywhere
+yet. A schema change edits `001.sql` directly, with the code that uses the
+changed tables.
 
-### 4. `chunk_files`
+This has one consequence. An index created before such a change has already
-Reverse mapping showing which files contain each chunk.
+recorded `001.sql` as run, so it keeps the old schema and can become unusable.
+To rebuild it, run `vaultik database delete` and then a full backup.
 
-**Columns:**
+After version 1.0, each schema change is a new numbered file. An existing index
-- `chunk_hash` (TEXT) - Chunk hash (FK to chunks.chunk_hash)
+is then migrated the first time an updated `vaultik` opens it. A file that was
-- `file_id` (TEXT) - File ID (FK to files.id)
+part of a release is never edited.
-- `file_offset` (INTEGER) - Byte offset of chunk within file
-- `length` (INTEGER) - Length of chunk in bytes
-- PRIMARY KEY (`chunk_hash`, `file_id`)
 
-**Purpose:** Supports efficient queries for chunk usage and deduplication statistics.
+Migrations apply to the local index only. A snapshot's database at the
+destination is read as it was written. Each snapshot records the `vaultik`
+version that wrote it.
 
-### 5. `blobs`
+## Tables
-Stores information about packed, compressed, and encrypted blob files.
 
-**Columns:**
+Times are whole seconds since the Unix epoch, in UTC. The two exceptions are
-- `id` (TEXT PRIMARY KEY) - UUID assigned when blob creation starts
+noted at their columns.
-- `blob_hash` (TEXT UNIQUE) - `hex(SHA256(SHA256(uncompressed blob contents)))`, computed before compression and encryption (NULL until finalized); see [REPOSTRUCTURE.md](REPOSTRUCTURE.md#blobs-directory-blobs)
-- `created_ts` (INTEGER NOT NULL) - Creation timestamp
-- `finished_ts` (INTEGER) - Finalization timestamp (NULL if in progress)
-- `uncompressed_size` (INTEGER NOT NULL DEFAULT 0) - Total size of chunks before compression
-- `compressed_size` (INTEGER NOT NULL DEFAULT 0) - Size after compression and encryption
-- `uploaded_ts` (INTEGER) - Upload completion timestamp (NULL if not uploaded)
 
-**Purpose:** Tracks blob lifecycle from creation through upload. The UUID primary key allows immediate association of chunks with blobs.
+### `files`
 
-### 6. `blob_chunks`
+One row for each backed-up path: a regular file, a symlink or a directory.
-Maps chunks to the blobs that contain them.
-
-**Columns:**
-- `blob_id` (TEXT) - Blob ID (FK to blobs.id)
-- `chunk_hash` (TEXT) - Chunk hash (FK to chunks.chunk_hash)
-- `offset` (INTEGER) - Byte offset of chunk within blob (before compression)
-- `length` (INTEGER) - Length of chunk in bytes
-- PRIMARY KEY (`blob_id`, `chunk_hash`)
-
-**Purpose:** Enables chunk retrieval from blobs during restore operations.
-
-### 7. `snapshots`
-Tracks backup snapshots.
-
-**Columns:**
-- `id` (TEXT PRIMARY KEY) - Snapshot ID (format: `hostname_name_timestamp`, e.g. `server1_home_2025-06-01T12:00:00Z`: the hostname up to its first `.`, the snapshot name, and an RFC 3339 UTC timestamp)
-- `hostname` (TEXT) - Hostname where backup was created
-- `vaultik_version` (TEXT) - Version of Vaultik used
-- `vaultik_git_revision` (TEXT) - Git revision of Vaultik used
-- `started_at` (INTEGER) - Start timestamp
-- `completed_at` (INTEGER) - Completion timestamp (NULL if in progress)
-- `file_count` (INTEGER) - Number of files in snapshot
-- `chunk_count` (INTEGER) - Number of chunks this snapshot stored that were not stored before
-- `blob_count` (INTEGER) - Number of blobs this snapshot created
-- `total_size` (INTEGER) - Total size of all files
-- `blob_size` (INTEGER) - Total compressed size of all referenced blobs
-- `blob_uncompressed_size` (INTEGER) - Total uncompressed size of all referenced blobs
-- `compression_ratio` (REAL) - Compression ratio achieved
-- `compression_level` (INTEGER) - Compression level used for this snapshot
-- `upload_bytes` (INTEGER) - Total bytes uploaded during this snapshot
-- `upload_duration_ms` (INTEGER) - Total milliseconds spent uploading to S3
 
-**Purpose:** Provides snapshot metadata and statistics including version tracking for compatibility.
+- `id`: a UUID. Primary key.
+- `path`: the absolute path. Unique.
+- `source_path`: the configured path that the scan found this entry under. A
+  restore does not read it.
+- `mtime`: the modification time.
+- `mtime_nsec`: the nanoseconds within that second.
+- `size`: the size in bytes.
+- `mode`: the permission bits and the file type.
+- `uid`: the owner's user ID.
+- `gid`: the owner's group ID.
+- `link_target`: the target of a symlink. It is `NULL` for other entries.
 
-### 8. `snapshot_files`
+`idx_files_path` indexes `path`.
-Maps snapshots to the files they contain.
-
-**Columns:**
-- `snapshot_id` (TEXT) - Snapshot ID (FK to snapshots.id)
-- `file_id` (TEXT) - File ID (FK to files.id)
-- PRIMARY KEY (`snapshot_id`, `file_id`)
 
-**Purpose:** Records which files are included in each snapshot.
+There is one row for each path, and it is updated when the file changes. The
+row is shared by every snapshot in the local index that lists the path. An
+older snapshot's own view of the file is in that snapshot's database at the
+destination.
 
-### 9. `snapshot_blobs`
+### `chunks`
-Maps snapshots to the blobs they reference.
 
-**Columns:**
+One row for each distinct chunk.
-- `snapshot_id` (TEXT) - Snapshot ID (FK to snapshots.id)
-- `blob_id` (TEXT) - Blob ID (FK to blobs.id)
-- `blob_hash` (TEXT) - Denormalized blob hash for manifest generation
-- PRIMARY KEY (`snapshot_id`, `blob_id`)
 
-**Purpose:** Tracks blob dependencies for snapshots and enables manifest generation.
+- `chunk_hash`: the SHA-256 hash of the chunk's content, in hex. Primary key.
-
+- `size`: the size in bytes.
-### 10. `uploads`
-Tracks blob upload metrics.
-
-**Columns:**
-- `blob_hash` (TEXT PRIMARY KEY) - Hash of uploaded blob
-- `snapshot_id` (TEXT NOT NULL) - The snapshot that triggered this upload (FK to snapshots.id)
-- `uploaded_at` (INTEGER) - Upload timestamp
-- `size` (INTEGER) - Size of uploaded blob
-- `duration_ms` (INTEGER) - Upload duration in milliseconds
-
-**Purpose:** Performance monitoring and tracking which blobs were newly created (uploaded) during each snapshot.
-
-## Data Flow and Operations
-
-### 1. Backup Process
-
-1. **File Scanning**
-   - `INSERT OR REPLACE INTO files` - Update file metadata
-   - `SELECT * FROM files WHERE path = ?` - Check if file has changed
-   - `INSERT INTO snapshot_files` - Add file to current snapshot
-
-2. **Chunking** (for changed files)
-   - `INSERT OR IGNORE INTO chunks` - Store new chunks
-   - `INSERT INTO file_chunks` - Map chunks to file
-   - `INSERT INTO chunk_files` - Create reverse mapping
-
-3. **Blob Packing**
-   - `INSERT INTO blobs` - Create blob record with UUID (blob_hash NULL)
-   - `INSERT INTO blob_chunks` - Associate chunks with blob immediately
-   - `UPDATE blobs SET blob_hash = ?, finished_ts = ?` - Finalize blob after packing
-
-4. **Upload**
-   - `UPDATE blobs SET uploaded_ts = ?` - Mark blob as uploaded
-   - `INSERT INTO uploads` - Record upload metrics with snapshot_id
-   - `INSERT INTO snapshot_blobs` - Associate blob with snapshot
-
-5. **Snapshot Completion**
-   - `UPDATE snapshots SET completed_at = ?, stats...` - Finalize snapshot
-   - Generate and upload blob manifest from `snapshot_blobs`
-
-### 2. Incremental Backup
 
-1. **Change Detection**
+### `file_chunks`
-   - `SELECT * FROM files WHERE path = ?` - Get previous file metadata
-   - Compare mtime, size, mode to detect changes
-   - Re-chunk a file that lists a chunk no uploaded blob holds, even when its metadata is unchanged
-   - Skip unchanged files but still add to `snapshot_files`
-
-2. **Chunk Reuse**
-   - `SELECT * FROM blob_chunks WHERE chunk_hash = ?` - Find existing chunks
-   - `INSERT INTO snapshot_blobs` - Reference existing blobs for unchanged files
-
-### 3. Snapshot Metadata Export
 
-After a snapshot is completed:
+The chunks that make up each file, in order.
-1. Copy database to temporary file
-2. Clean temporary database to contain only current snapshot data
-3. VACUUM the trimmed database so deleted rows leave no pages behind
-4. Compress with zstd and encrypt with age
-5. Upload to S3 as `metadata/{remote-key}/db.zst.age`
-6. Generate blob manifest and upload as `metadata/{remote-key}/manifest.json.zst`
-
-The `{remote-key}` directory name is a one-way hash of the human snapshot ID, so the ID is never written to the store in plaintext. The hash uses no secret, so a guessed hostname and snapshot name can still be confirmed against a listing; see [REPOSTRUCTURE.md](REPOSTRUCTURE.md#remote-key-derivation) and its [Accepted Risks](REPOSTRUCTURE.md#accepted-risks).
-
-### 4. Restore Process
 
-The restore process doesn't use the local database. Instead:
+- `file_id`: the file. References `files.id`.
-1. Downloads and decrypts the snapshot's metadata database (`db.zst.age`) from S3
+- `idx`: the position of the chunk within the file, counted from 0.
-2. Downloads the blobs holding the chunks of the files being restored, found through that database's `blob_chunks` table; the manifest is not read
+- `chunk_hash`: the chunk. References `chunks.chunk_hash`.
-3. Reconstructs files from decrypted and decompressed chunks
 
-### 5. Pruning
+The primary key is (`file_id`, `idx`). `idx_file_chunks_chunk_hash` indexes
+`chunk_hash`.
 
-1. **Identify Unreferenced Blobs**
+### `chunk_files`
-   - Query blobs not referenced by any remaining snapshot
-   - Delete from S3 and local database
 
-### 6. Incomplete Snapshot Cleanup
+The reverse of `file_chunks`: the files that contain each chunk.
 
-Before each backup:
+- `chunk_hash`: the chunk. References `chunks.chunk_hash`.
-1. Query incomplete snapshots (where `completed_at IS NULL`)
+- `file_id`: the file. References `files.id`.
-2. Delete each one and all its associations, without checking S3 for its metadata
+- `file_offset`: the byte offset of the chunk within the file.
-3. Clean up orphaned files, chunks, and blobs
+- `length`: the length of the chunk in bytes.
 
-## Repository Pattern
+The primary key is (`chunk_hash`, `file_id`). `idx_chunk_files_file_id` indexes
+`file_id`.
 
-Vaultik uses a repository pattern for database access:
+### `blobs`
 
-- `FileRepository` - CRUD operations for files and file metadata
+One row for each blob.
-- `ChunkRepository` - CRUD operations for content chunks
-- `FileChunkRepository` - Manage file-to-chunk mappings
-- `ChunkFileRepository` - Manage chunk-to-file reverse mappings  
-- `BlobRepository` - Manage blob lifecycle (creation, finalization, upload)
-- `BlobChunkRepository` - Manage blob-to-chunk associations
-- `SnapshotRepository` - Manage snapshots and their relationships
-- `UploadRepository` - Track blob upload metrics
 
-Each repository provides methods like:
+- `id`: a UUID, given when packing of the blob starts. Primary key.
-- `Create()` - Insert new record
+- `blob_hash`: the name of the blob at the destination. Unique. Until the blob
-- `GetByID()` / `GetByPath()` / `GetByHash()` - Retrieve records
+  is closed, it holds a placeholder that starts with `temp-placeholder-`.
-- `Update()` - Update existing records
+- `created_ts`: when packing started.
-- `Delete()` - Remove records
+- `finished_ts`: when the blob was closed. It is `NULL` before that.
-- Specialized queries for each entity type (e.g., `DeleteOrphaned()`, `GetIncompleteByHostname()`)
+- `uncompressed_size`: the total size of the blob's chunks.
+- `compressed_size`: the size after compression and encryption.
+- `uploaded_ts`: when the upload finished. It is `NULL` before that.
 
-## Transaction Management
+`blob_hash` is `hex(SHA256(SHA256(uncompressed contents)))`. See
+[REPOSTRUCTURE.md](REPOSTRUCTURE.md#blobs).
 
-All database operations that modify multiple tables are wrapped in transactions:
+Once a blob is uploaded, `compressed_size` is the size of the object at the
+destination. A blob that was already there can have a different size from the
+local copy. That happens when it was written with another compression level or
+other recipients.
+
+### `blob_chunks`
+
+The chunks that each blob holds.
+
+- `blob_id`: the blob. References `blobs.id`.
+- `chunk_hash`: the chunk. References `chunks.chunk_hash`.
+- `offset`: the byte offset of the chunk within the uncompressed blob.
+- `length`: the length of the chunk in bytes.
+
+The primary key is (`blob_id`, `chunk_hash`). `idx_blob_chunks_chunk_hash`
+indexes `chunk_hash`.
+
+A restore finds the blob for each chunk through this table.
+
+### `snapshots`
+
+One row for each snapshot.
+
+- `id`: the snapshot ID. Primary key.
+- `hostname`: the hostname of the machine that made the backup.
+- `vaultik_version`: the `vaultik` version that made it.
+- `vaultik_git_revision`: the git commit of that version.
+- `started_at`: when the backup started.
+- `completed_at`: when the backup finished. It is `NULL` until then.
+- `file_count`: the number of files and symlinks in the snapshot. Directories
+  are not counted.
+- `chunk_count`: the number of chunks this snapshot stored that were not stored
+  before.
+- `new_chunk_size`: the total size of those chunks before compression.
+- `blob_count`: the number of blobs this snapshot created.
+- `total_size`: the total size of all files in the snapshot.
+- `uncompressed_chunk_size`: the total size, before compression, of the
+  distinct chunks the snapshot's files use.
+- `blob_size`: the total compressed size of the blobs the snapshot uses.
+- `blob_uncompressed_size`: the total uncompressed size of those blobs.
+- `compression_ratio`: the compression ratio of those blobs.
+- `compression_level`: the compression level the backup used.
+- `upload_bytes`: the bytes uploaded during the backup.
+- `upload_duration_ms`: the time spent uploading, in milliseconds.
+
+The snapshot ID has the form `<hostname>_<snapshot-name>_<timestamp>`. An
+example is `server1_home_2025-06-01T12:00:00Z`. It has three parts:
+
+- the hostname, up to its first `.`
+- the snapshot name
+- the start time, in UTC
+
+`snapshot list` shows `uncompressed_chunk_size` as `UNCOMPRESSED SIZE` and
+`new_chunk_size` as `NEW CHUNK SIZE`.
+
+A snapshot with `completed_at` set to `NULL` is unfinished. `snapshot list`
+does not show it. The next backup deletes it, and so does `prune`.
+
+### `snapshot_files`
+
+The files in each snapshot.
+
+- `snapshot_id`: the snapshot. References `snapshots.id`.
+- `file_id`: the file. References `files.id`.
+
+The primary key is (`snapshot_id`, `file_id`). `idx_snapshot_files_file_id`
+indexes `file_id`.
+
+### `snapshot_blobs`
+
+The blobs that each snapshot uses.
+
+- `snapshot_id`: the snapshot. References `snapshots.id`.
+- `blob_id`: the blob. References `blobs.id`.
+- `blob_hash`: a copy of the blob's hash.
+
+The primary key is (`snapshot_id`, `blob_id`). `idx_snapshot_blobs_blob_id`
+indexes `blob_id`.
+
+The manifest is built from this table.
+
+### `snapshot_mount_points`
+
+The mount points that a snapshot's backup found.
+
+- `snapshot_id`: the snapshot. References `snapshots.id`.
+- `path`: the absolute path of the directory.
+
+The primary key is (`snapshot_id`, `path`).
+
+A directory is recorded here when all of these hold:
+
+- It is at or below a configured path.
+- The backup found an entry in it that is not excluded.
+- It is on a different filesystem from its parent directory.
+
+The device number is read after the directory has been listed. Listing an
+automount point mounts its volume, so the number is that of the volume. An
+automount point whose volume cannot be mounted is not recorded, because the
+backup finds no entry in it.
+
+`snapshot create --prune` reads this table. It skips the prune when an earlier
+snapshot of the same name recorded a mount point that the new backup did not
+find. That happens when the volume is not mounted.
+
+### `uploads`
+
+One row for each blob that a backup uploaded.
+
+- `blob_hash`: the blob. References `blobs.blob_hash`. Primary key.
+- `snapshot_id`: the snapshot whose backup uploaded it. References
+  `snapshots.id`.
+- `uploaded_at`: when the upload started. It is written as a date and time, not
+  as seconds.
+- `size`: the size of the uploaded blob.
+- `duration_ms`: the duration of the upload, in milliseconds.
+
+`idx_uploads_snapshot_id` indexes `snapshot_id`.
+
+A blob that was already at the destination gets no row here.
+
+### `local_meta`
+
+Settings that belong to this copy of the index.
+
+- `key`: the name of the setting. Primary key.
+- `value`: its value.
+
+The only key is `storage_url`. It holds the destination that the index was
+first used with. A command that changes data refuses to run when the config
+names a different destination.
+
+### `schema_migrations`
+
+The migrations that have run.
+
+- `version`: the number of the migration. Primary key.
+- `applied_at`: when it ran. It is written as a date and time, not as seconds.
+
+## How commands use the tables
+
+### Backup
+
+A backup works on the tables in this order:
+
+- It deletes unfinished snapshots, and the rows that no snapshot uses.
+- It creates a row in `snapshots`, with `completed_at` set to `NULL`.
+- It deletes the `blobs` rows that were never uploaded.
+- It walks each path and compares every entry with its row in `files`.
+- It links each unchanged file to the snapshot in `snapshot_files`.
+- It records each mount point in `snapshot_mount_points`.
+- It reads each changed file and stores it. See below.
+- It fills `snapshot_blobs` with every blob the snapshot uses.
+- It stores the snapshot's totals in `snapshots`.
+- It uploads the snapshot's metadata.
+- It sets `completed_at`.
+
+A file counts as changed when its row in `files` differs from the file on disk
+in any of these:
+
+- size
+- modification time
+- mode
+- owner or group
+- link target
+
+A file is also read again when it lists a chunk that no uploaded blob holds.
+
+Storing a changed file writes these rows:
+
+- A row in `blobs`, when packing of a blob starts.
+- When the blob is closed, in one transaction:
+    - a row in `chunks` for each new chunk in the blob
+    - the blob's rows in `blob_chunks`
+    - the blob's `blob_hash`, sizes and `finished_ts`
+- When the blob is stored at the destination, in one transaction:
+    - `uploaded_ts` and `compressed_size` in `blobs`
+    - a row in `snapshot_blobs`
+    - a row in `uploads`, unless the blob was already at the destination
+- The row in `files`, with its `file_chunks`, `chunk_files` and
+  `snapshot_files` rows.
+
+The row in `files` is written last. It is written only after every blob that
+holds the file's new chunks is stored.
+
+### Snapshot metadata
+
+The metadata of a snapshot is made from a copy of the index:
+
+- The index is copied into a temporary directory with `VACUUM INTO`.
+- The rows of every other snapshot are deleted from the copy. So are the files
+  and blobs that this snapshot does not use. A chunk is then deleted when no
+  remaining file and no remaining blob uses it.
+- The `local_meta` and `schema_migrations` tables are kept as they are. The
+  uploaded database therefore names the destination, and lists the migrations
+  that have run.
+- `VACUUM` rewrites the copy, so that no deleted row is left in the file.
+- The copy is compressed with zstd and encrypted with age.
+- The manifest is built from the copy's `snapshot_blobs` table.
+- The copy is uploaded as `metadata/<remote-key>/db.zst.age`.
+- The manifest is uploaded as `metadata/<remote-key>/manifest.json.zst`.
+
+The copy is made through SQLite, not by copying the file. The index runs in WAL
+mode, so rows that are already committed can still be in the `-wal` file beside
+it.
+
+### Restore
+
+A restore does not use the local index.
+
+- It downloads and decrypts `db.zst.age` into a temporary directory.
+- It opens that file read-only. It applies no migration to it.
+- It reads the files to restore from `files`.
+- It finds each file's chunks in `file_chunks`.
+- It finds the blob and offset of each chunk in `blob_chunks`.
+- It finds the name of each blob in `blobs`.
+
+It does not read the manifest.
+
+### Prune
+
+`prune` changes the local index in two ways:
+
+- It deletes each snapshot whose manifest is gone from the destination.
+- It deletes unfinished snapshots, and the rows that no snapshot uses.
+
+The second step removes unused rows in this order:
+
+- files that are in no snapshot
+- blobs that are in no snapshot
+- `blob_chunks` rows whose chunk is gone
+- chunks that no file and no blob uses
+
+`prune` then deletes unused data at the destination. That step reads the
+manifests, not the local index. It reads the local index only to keep a
+directory under `metadata/` whose snapshot is still recorded there.
+
+## Code
+
+Each repository type in `internal/database` serves one or more tables:
+
+- `FileRepository`: `files`
+- `ChunkRepository`: `chunks`
+- `FileChunkRepository`: `file_chunks`
+- `ChunkFileRepository`: `chunk_files`
+- `BlobRepository`: `blobs`
+- `BlobChunkRepository`: `blob_chunks`
+- `SnapshotRepository`:
+    - `snapshots`
+    - `snapshot_files`
+    - `snapshot_blobs`
+    - `snapshot_mount_points`
+- `UploadRepository`: `uploads`
+- `LocalMetaRepository`: `local_meta`
+
+No repository type serves `schema_migrations`. The code that applies the
+migrations reads and writes it.
+
+`Repositories` holds one of each type.
+
+`Repositories.WithTx` runs a function in one transaction:
 
 ```go
 err := repos.WithTx(ctx, func(ctx context.Context, tx *sql.Tx) error {
-    // Multiple repository operations using tx
+    // several repository calls that use tx
 })
 ```
 
-This ensures consistency, especially important for operations like:
+The transaction commits when the function returns no error. Otherwise it is
-- Creating file-chunk mappings
+rolled back.
-- Associating chunks with blobs
-- Updating snapshot statistics
 
-## Performance Considerations
+## SQLite settings
 
-1. **Indexes**: 
+- The index runs in WAL mode. A command that only reads, such as
-   - Primary keys are automatically indexed
+  `snapshot list`, can read the index while a backup writes to it.
-   - `idx_files_path` on `files(path)` for efficient file lookups
+- A connection waits up to 10 seconds for a lock before it fails.
-
+- Foreign keys are enforced.
-2. **Prepared Statements**: All queries use prepared statements for performance and security
+- Each open database uses one connection, so its queries run one at a time.
-
+- Queries pass their values as parameters.
-3. **Batch Operations**: Where possible, operations are batched within transactions
-
-4. **Write-Ahead Logging**: The local index runs in SQLite WAL mode with a 10-second busy timeout, so a read-only command such as `snapshot list` can read it while a backup writes to it. Committed rows can sit in the `-wal` file beside the index until a checkpoint, so the metadata export copies the index through SQLite (`VACUUM INTO`), not as a file
-
-## Data Integrity
-
-1. **Foreign Keys**: Enforced through CASCADE DELETE and application-level repository methods
-2. **Unique Constraints**: Chunk hashes, file paths, and blob hashes are unique
-3. **Null Handling**: Nullable fields clearly indicate in-progress operations
-4. **Timestamp Tracking**: All major operations record timestamps for auditing

docs/REPOSTRUCTURE.md

@@ -1,177 +1,416 @@
-# Vaultik S3 Repository Structure
+# vaultik destination layout
 
-This document describes the structure and organization of data stored in the S3 bucket by Vaultik.
+This document describes what `vaultik` stores at the destination. It covers the
+layout, what the layout protects, and the risks it accepts.
 
-## Overview
+The destination is the place the backups are stored. It is an S3 bucket and
+prefix, a local directory or an rclone remote. The layout is the same on all
+three.
 
-Vaultik stores all backup data in an S3-compatible object store. The repository consists of two main components:
+## Terms
-1. **Blobs** - The actual backup data (content-addressed, encrypted)
-2. **Metadata** - Snapshot information and manifests (partially encrypted)
 
-## Directory Structure
+- **Snapshot**: one backup of the paths listed under one name in the config.
+- **Snapshot ID**: the name of a snapshot, in the form
+  `<hostname>_<snapshot-name>_<timestamp>`.
+- **Chunk**: a piece of a file's content, named by the SHA-256 hash of that
+  content.
+- **Blob**: one object under `blobs/`. It holds many chunks.
+- **Local index**: the SQLite database on the backed-up machine.
+- **Recipient**: an age public key that backups are encrypted to.
+
+## Layout
 
 ```
-<bucket>/<prefix>/
+<destination>/
+├── vaultik-destination.txt
 ├── blobs/
 │   └── <hash[0:2]>/
 │       └── <hash[2:4]>/
-│           └── <full-hash>
+│           └── <hash>
 └── metadata/
     └── <remote-key>/
         ├── db.zst.age
         └── manifest.json.zst
 ```
 
-The metadata subdirectory is named with the **remote key**, a one-way hash of the snapshot ID, not with the human-readable snapshot ID itself. See [Remote Key Derivation](#remote-key-derivation).
+The destination holds three things:
 
-## Blobs Directory (`blobs/`)
+- `vaultik-destination.txt`, the marker file
+- `blobs/`, which holds the file contents
+- `metadata/`, which holds one directory for each snapshot
 
-### Structure
+## The marker file
-- **Path format**: `blobs/<first-2-chars>/<next-2-chars>/<full-hash>`
-- **Example**: `blobs/ca/fe/cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678`
-- **Sharding**: The two-level directory structure (using the first 4 characters of the hash) prevents any single directory from containing too many objects
 
-### Content
+Every backup writes `vaultik-destination.txt` before it uploads anything else.
-- **What it contains**: Packed collections of content-defined chunks from files
+The file holds one fixed line of text. It names no host, path or time.
-- **Format**: Zstandard compressed, then Age encrypted
-- **Encryption**: Always encrypted with Age using the configured recipients
-- **Naming**: Content-addressed. The blob's name is `hex(SHA256(SHA256(uncompressed blob contents)))` — the double SHA-256 of the concatenated chunk data, computed before compression and encryption, not a hash of the stored (compressed, encrypted) bytes. One consequence: only a holder of the age private key can check a stored blob's integrity, because matching a blob to its name means decrypting and decompressing it first — which is what `restore` and `verify --deep` do. Implemented in `internal/blobgen` (`DoubleSHA256`). This is the canonical description of blob naming; other documents and comments point here.
 
-### Why Encrypted
+The marker tells an emptied or missing destination apart from a new one. An
-Blobs contain the actual file data from backups and must be encrypted for security. The content-addressing ensures deduplication while the encryption ensures privacy.
+unplugged volume leaves an empty directory at its mount point. Without the
+marker, that directory would look like a destination whose snapshots are all
+gone.
 
-## Metadata Directory (`metadata/`)
+The check applies while the local index holds snapshots. When the destination
+then answers that the marker does not exist, commands treat the destination as
+not present:
 
-Each snapshot has its own subdirectory. The directory is **not** named with the human-readable snapshot ID; it is named with the remote key — a one-way hash of that ID. The human ID is never written to the destination store as a directory name (see [Remote Key Derivation](#remote-key-derivation)).
+- `snapshot create` refuses to write to it.
+- `prune`, `snapshot purge` and `remote nuke` fail.
+- `snapshot list` shows the local index alone.
+- `snapshot remove` deletes nothing at the destination.
 
-### Snapshot ID Format
+The check is skipped when the look-up fails for any other reason. S3 refuses
+the look-up to credentials that can only write. A machine with such credentials
+therefore does not notice an emptied destination. Its next backup would not
+upload data that its local index says is stored. After a destination is emptied,
+run `vaultik database delete` on such a machine before it backs up again.
 
-The human-readable snapshot ID is used in CLI arguments, log lines, and the local database. It is not written to the destination store.
+`remote nuke` deletes the marker last.
-- **Format**: `<hostname>_<snapshot-name>_<RFC3339>` (or `<hostname>_<RFC3339>` if no
-  name was specified)
-- **Example**: `laptop_home_2024-01-15T14:30:52Z`
-- **Components**:
-  - Short hostname (everything before the first dot is stripped from the FQDN)
-  - Snapshot name from the configured `snapshots:` map (optional)
-  - RFC3339 UTC timestamp
 
-This ID reveals the hostname, the configured snapshot name, and the backup time, so it is never used as the on-disk directory name — the remote key is used instead.
+## Blobs
 
-### Remote Key Derivation
+A blob holds the content of many chunks, one after another.
 
-The remote key is `hex(SHA256(SHA256("vaultik|" + snapshot-id)))`: a double SHA-256 over the snapshot ID, with a `vaultik|` domain-separation prefix. The result is a 64-character hex string. The hash is not reversible, but it uses no secret: an observer who guesses a candidate hostname and snapshot name can hash it the same way and confirm whether that snapshot is present. The remote key keeps names out of a plain listing; it does not hide them from a guess. Implemented in `internal/snapshot/remotekey.go`.
+- **Path**: `blobs/<first 2 characters>/<next 2 characters>/<full hash>`.
+- **Example**:
+  `blobs/ca/fe/cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678`.
+- **Format**: the chunk data, compressed with zstd and then encrypted with age.
+- **Recipients**: the public keys in `age_recipients` when the blob was written.
+
+The two directory levels keep any one directory from holding too many objects.
+
+### Blob names
+
+A blob's name is `hex(SHA256(SHA256(uncompressed contents)))`. The contents are
+the chunk data, joined in order, before compression and encryption. The name is
+not a hash of the stored bytes.
+
+This has two consequences:
+
+- Checking a blob against its name needs the private key. The blob must be
+  decrypted and decompressed first. `snapshot restore` and
+  `snapshot verify --deep` do this.
+- Without the key, only a blob's presence and size can be checked.
+  `snapshot verify` does this.
+
+`blobgen.DoubleSHA256` in `internal/blobgen` computes the name.
+
+### Uploads
+
+A backup looks a blob up by name before it uploads it. It does not upload a
+blob that is already there.
+
+When the destination refuses the look-up, the backup uploads the blob. An
+object with that name is then replaced by one that holds the same chunk data.
+
+## Metadata
+
+Each snapshot has one directory under `metadata/`. The directory is named with
+the snapshot's remote key, not with its snapshot ID.
+
+### Snapshot IDs
+
+A snapshot ID has the form `<hostname>_<snapshot-name>_<timestamp>`. An example
+is `laptop_home_2024-01-15T14:30:52Z`. It has three parts:
+
+- the hostname, up to its first `.`
+- the snapshot name from the config
+- the time the backup started, in UTC
+
+The snapshot ID is used on the command line, in log records and in the local
+index. It reveals the hostname, the snapshot name and the backup time. It is
+therefore never written to the destination without encryption.
+
+### Remote keys
+
+The remote key is `hex(SHA256(SHA256("vaultik|" + snapshot ID)))`. It is 64 hex
+characters long. `internal/snapshot/remotekey.go` computes it.
+
+For example:
 
-Worked example:
 - Snapshot ID: `server1_home_2025-06-01T12:00:00Z`
 - Remote key: `17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa`
-- Directory: `metadata/17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa/`
+- Directory:
+  `metadata/17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa/`
 
-A plain listing of the destination store therefore shows only these hashes, not the hostname or snapshot name of any backup — but because the hash uses no secret, a guessed hostname and snapshot name can be hashed and confirmed against the listing. The same remote key is stored in the manifest's `snapshot_id` field.
+A listing of the destination therefore shows no hostname and no snapshot name.
 
-### Files in Each Snapshot Directory
+The hash cannot be reversed, but it uses no secret. Someone who guesses a
+snapshot ID can hash it the same way and see whether that snapshot exists. The
+remote key keeps names out of a listing. It does not hide them from a guess.
 
-#### `db.zst.age` - Encrypted Database
+### `db.zst.age`
-- **What it contains**: Pruned binary SQLite database for this snapshot
+
-- **Format**: Binary SQLite → Zstandard compressed → Age encrypted
+The snapshot's database. A restore needs it.
-- **Encryption**: Encrypted with Age
+
-- **Purpose**: Contains full file metadata, chunk mappings, and all relationships
+- **Contents**: a SQLite database. It is a copy of the local index without the
-- **Why encrypted**: Contains sensitive metadata like file paths, permissions, and ownership
+  rows of other snapshots. It lists every file in the snapshot with its
+  metadata, its chunks, and the blob that holds each chunk.
+- **Format**: the database file, compressed with zstd and then encrypted with
+  age.
+
+It is encrypted because it holds file paths, permissions and owners.
+[DATAMODEL.md](DATAMODEL.md) describes its tables.
+
+### `manifest.json.zst`
+
+The list of the blobs the snapshot uses.
+
+- **Format**: JSON, compressed with zstd. It is not encrypted.
 
-#### `manifest.json.zst` - Unencrypted Blob Manifest
-- **What it contains**: JSON list of all blob hashes referenced by this snapshot
-- **Format**: JSON → Zstandard compressed (NOT encrypted)
-- **Encryption**: NOT encrypted
-- **Purpose**: Enables pruning operations without requiring decryption keys
-- **Structure**:
 ```json
 {
-  "snapshot_id": "17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa",
+    "snapshot_id": "17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa",
-  "timestamp": "2025-06-01T12:00:00Z",
+    "timestamp": "2025-06-01T12:04:31Z",
-  "blob_count": 42,
+    "blob_count": 2,
-  "total_compressed_size": 1048576,
+    "total_compressed_size": 57344,
-  "blobs": [
+    "blobs": [
-    { "hash": "cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678", "compressed_size": 24576 },
+        {
-    { "hash": "deadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678", "compressed_size": 32768 }
+            "hash": "cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678",
-  ]
+            "compressed_size": 24576
+        },
+        {
+            "hash": "deadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
+            "compressed_size": 32768
+        }
+    ]
 }
 ```
-`snapshot_id` is the remote key (a hash), not the human ID; `timestamp` is written in the clear.
 
-### Why Manifest is Unencrypted
+- `snapshot_id`: the remote key, not the snapshot ID.
-The manifest must be readable without the private key to enable:
+- `timestamp`: when the manifest was written, at the end of the backup.
-1. **Pruning operations** - Identifying unreferenced blobs for deletion
+- `blob_count`: the number of blobs.
-2. **Storage analysis** - Understanding space usage without decryption
+- `total_compressed_size`: the total size of those blobs, in bytes.
-3. **Verification** - Checking blob existence without decryption
+- `blobs`: the hash and the size of each blob.
-4. **Cross-snapshot deduplication analysis** - Finding shared blobs between snapshots
 
-The manifest contains the remote key, the backup timestamp, the blob count and total compressed size, and each blob's hash and compressed size. It contains no file names, paths, or other decrypted metadata.
+The manifest holds no file name and no path.
 
-## Security Considerations
+The manifest is not encrypted so that these commands work without the private
+key:
 
-### What's Encrypted
+- `prune`, which must know which blobs are still in use
-- **All file content** (in blobs)
+- `snapshot verify`, which checks that each blob is present
-- **All file metadata** (paths, permissions, timestamps, ownership in db.zst.age)
+- `snapshot list` and `remote info`, which report what the destination holds
-- **File-to-chunk mappings** (in db.zst.age)
 
-### What's Not Encrypted
+## What is protected
-- **The remote key** — directory names and the manifest `snapshot_id`, a one-way hash of the snapshot ID (see [Remote Key Derivation](#remote-key-derivation))
-- **The backup timestamp** (in manifest.json.zst)
-- **Blob hashes and their compressed sizes** (in manifest.json.zst)
-- **Blob count and total compressed size per snapshot** (in manifest.json.zst)
 
-### Privacy Implications
+These are encrypted:
-From the unencrypted data, an observer of the destination store can determine:
-- **When each backup was taken** — not from the directory name, which is a one-way hash, but from the plaintext `timestamp` field in manifest.json.zst, which is published in the clear
-- How many blobs each snapshot references, and the total compressed size
-- The compressed size of each blob, and which blobs are shared between snapshots (deduplication patterns)
-- **Whether a guessed hostname and snapshot name are present** — the remote key is an unkeyed hash, so an observer holding candidate names can hash each one and match it against the directory listing. The human ID is never published, so it cannot be read off directly, but it can be confirmed by guessing.
 
-Together these give an observer a timing-and-size profile of every snapshot. This is an accepted, documented property of the format, not a defect: the manifest is unencrypted so that pruning can run without the private key, and the timing channel could not be closed by encrypting it anyway — object creation times and per-object sizes stay visible at the storage layer on both `s3://` and `file://` destinations regardless.
+- file contents, in the blobs
+- in `db.zst.age`:
+    - file names and paths
+    - permissions and owners
+    - modification times
+    - which chunks make up which file
 
-An observer cannot determine:
+These are not encrypted:
-- The hostname or snapshot name of any backup by reading it off the store — the directory name and the manifest `snapshot_id` are unkeyed hashes of the human ID, so the text is never published (though a guessed name can be confirmed, as above)
-- File names or paths
-- File contents
-- File permissions or ownership
-- Directory structure
-- Which chunks belong to which files
 
-### Accepted Risks
+- the remote key of each snapshot
+- the time each backup finished, in the manifest
+- the hash and the compressed size of each blob, in the manifest
+- the number of blobs and their total size for each snapshot, in the manifest
 
-These are known, deliberate properties of the format and the tooling, recorded so an operator can weigh them rather than discover them.
+Someone who can read the destination therefore learns these:
 
-1. **No proof of authorship.** Restore and `verify --deep` prove that data decrypts with the age private key and matches its unkeyed content hashes. They do not prove who wrote it: anyone who knows a recipient public key and can replace objects on the destination can substitute a snapshot they built. The recipient string is not stored at the destination, but a compromised backed-up host has it. Defences live on the destination side — bucket versioning or object lock, credentials for the source host that cannot delete or overwrite existing versions, and pruning from a trusted host. Note that S3 `PutObject` overwrites an existing key, so PUT permission alone is not append-only.
+- when each backup finished
-2. **Compression reveals sizes.** Blobs and `db.zst.age` are zstd-compressed then age-encrypted; the manifest is compressed only. age does not pad, so an object's size is the exact compressed length of its contents. All new chunks packed into one blob share a single zstd stream (8 MiB window, 4 MiB at compression levels 1-2), and a blob is closed at `blob_size_limit` and at the end of each configured path. Because a stored chunk is never packed again, someone who can write into a backed-up file and watch blob sizes learns something only when their controlled data and a secret land in the same chunk of a file that keeps changing. Advice: back up any outsider-writable directory as its own snapshot.
+- how many blobs each snapshot uses, and how large they are
-3. **Chunking uses no secret.** The FastCDC parameters are fixed and public. The default 10 MB average yields chunks between 2.5 MB and 40 MB, and any file of 2.5 MB or less is a single chunk. At the default 10 GB `blob_size_limit` a blob holds hundreds of chunks, so individual chunk lengths are not visible in the blob's size; lowering the limit toward the chunk size begins to expose them.
+- which blobs two snapshots share
-4. **Decrypted data on local disk.** Several commands stage plaintext under `$TMPDIR`: `snapshot restore` writes decrypted blobs under `vaultik-blobcache-*/` (no size cap) and the decrypted metadata database at `vaultik-restore-*/snapshot.db`; `verify --deep` writes that database at `vaultik-verify-*/snapshot.db`; `snapshot create` keeps a plaintext copy of the index at `vaultik-snapshot-*/snapshot.db`. These files are created `0600` and removed on success, but a `kill -9` or a power loss leaves them behind — delete any leftover `vaultik-*` directory under `$TMPDIR` by hand. `$TMPDIR` should be trusted to the same degree as the restore target.
+- whether a snapshot ID they guess exists
-5. **Store permissions differ per command.** The backed-up host needs only PUT to run `snapshot create`: it writes blobs and metadata and neither reads nor deletes them. Other commands need more — `snapshot verify`, `snapshot restore`, and `prune` list and read; `prune`, `snapshot purge`, `snapshot remove`, and `remote nuke` also delete. The recommended cron line uses `--prune`, which runs `prune` on the backed-up host, so granting that host `--prune` gives it credentials that can delete its own backups. To keep the source host to PUT only, prune from a separate trusted host instead.
-6. **Changing recipients does not re-encrypt existing data.** Deduplicated chunks and same-named blobs already on the destination stay encrypted to the recipients in force when they were written. A new snapshot that reuses them cannot be restored with a newly added recipient's key alone, because those reused objects were never encrypted to it. To make everything readable by a new key, run `vaultik database delete` and take a full backup to a fresh destination or prefix.
-7. **X25519 recipients only.** vaultik rejects age ssh and plugin recipients. Long-lived ciphertext held by a third party (the destination operator) has no fallback if X25519 is ever broken: there is no second recipient type and no post-quantum option.
 
-## Consistency Guarantees
+They do not learn these:
 
-1. **Blobs are immutable** - Once written, a blob is never modified
+- any hostname or snapshot name, unless they guess it
-2. **Blobs are written before metadata** - A snapshot's metadata is only written after all its blobs are successfully uploaded
+- file names or paths
-3. **Metadata is written atomically** - Both db.zst.age and manifest.json.zst are written as complete files
+- file contents
-4. **A snapshot is marked complete in the local DB only after its metadata is uploaded** - `finalizeSnapshotMetadata` runs `ExportSnapshotMetadata` first and records completion (`MarkSnapshotComplete`) only once the export succeeds (see the backup data flow in [ARCHITECTURE.md](../ARCHITECTURE.md)). A crash during the export therefore leaves the snapshot incomplete, so the next backup's `PruneDatabase` drops it and re-backs-up its data, rather than leaving a completed-looking row in the local index with no matching metadata on the destination store. (A crash in the brief moment after the export succeeds but before completion is recorded leaves a fully-restorable snapshot on the destination that the local index drops as incomplete on the next run; `snapshot list` then reports it honestly as remote-only, which is the safe direction: the destination copy stays restorable.)
+- permissions or owners
+- the directory structure
+- which chunks belong to which file
 
-## Pruning Safety
+The times and sizes could not be hidden by encrypting the manifest. The
+destination itself shows when each object was written and how large it is.
 
-The prune operation is safe because:
+## Accepted risks
-1. It keeps every blob listed in any snapshot's manifest and deletes only blobs that no manifest references
-2. Manifests are unencrypted and can be read without keys
-3. If any manifest cannot be downloaded or decoded, prune deletes nothing and exits with an error, rather than treating that snapshot's blobs as unreferenced
-4. Prune requires exclusive access to the destination: running it during a concurrent backup can race a snapshot whose manifest is not yet written, so do not prune while a backup is in progress
 
-## Restoration Requirements
+These are known properties of the format. They are written down so that you can
+weigh them.
 
-To restore from a backup, you need:
+### No proof of who wrote the data
-1. **The Age private key** - To decrypt blobs and database
-2. **The snapshot metadata** - Both files from the snapshot's metadata directory
-3. **All referenced blobs** - As listed in the manifest
 
-The restoration process:
+A restore and `snapshot verify --deep` prove two things. The data decrypts with
-1. Download and decrypt the database dump to understand file structure
+your private key, and it matches its hashes. They do not prove who wrote it.
-2. Download and decrypt the required blobs
+
-3. Reconstruct files from their chunks
+The hashes use no secret. Someone who knows a recipient's public key and can
-4. Restore file metadata (permissions, timestamps, etc.)
+replace objects at the destination can put a snapshot of their own there. The
+public key is not stored at the destination, but a backed-up machine that is
+broken into has it.
+
+The defences are on the destination's side:
+
+- object versioning or object lock on the bucket
+- credentials for the backed-up machine that cannot delete or overwrite
+- running `prune` from a trusted machine
+
+An S3 `PutObject` replaces an existing object. Permission to write alone
+therefore does not stop overwrites.
+
+### Sizes are visible
+
+An object's size follows exactly from the size of its compressed contents.
+
+All the new chunks in one blob share one zstd stream. The stream looks back 8
+MiB, or 4 MiB at compression levels 1 and 2. A blob is closed at
+`blob_size_limit` and at the end of each configured path. A chunk that is
+already stored is never packed again.
+
+Data that an outsider writes compresses smaller when it matches a secret in the
+same chunk, so the blob gets smaller. The blob's size therefore shows the
+outsider whether their data matched the secret.
+
+This works only when all of these hold:
+
+- The outsider can write into a backed-up file.
+- The outsider can see the blob sizes at the destination.
+- The outsider's data and the secret land in the same chunk.
+- The file keeps changing.
+
+Back up a directory that outsiders can write to as a snapshot of its own.
+
+### Chunk boundaries use no secret
+
+The FastCDC parameters are fixed and public. `chunk_size` sets the average chunk
+size. No chunk is larger than four times this size. Only a file's last chunk can
+be smaller than a quarter of it. With the default of 10 MB, those limits are 40
+MB and 2.5 MB. A file of 2.5 MB or less is one chunk.
+
+At the default `blob_size_limit` of 10 GB, a blob holds hundreds of chunks. The
+size of the blob then does not show the size of any one chunk. A limit close to
+`chunk_size` begins to show chunk sizes.
+
+### Decrypted data on the local disk
+
+These commands write unencrypted data to the temporary directory:
+
+- `snapshot restore` writes decrypted blobs under `vaultik-blobcache-*/`. There
+  is no limit on their total size.
+- `snapshot restore` writes the decrypted database to
+  `vaultik-restore-*/snapshot.db`.
+- `snapshot verify --deep` writes the decrypted database to
+  `vaultik-verify-*/snapshot.db`.
+- `snapshot create` writes a copy of the local index to
+  `vaultik-snapshot-*/snapshot.db`.
+
+These files are readable only by their owner, and are removed when the command
+ends. A `kill -9` or a power loss leaves them behind. Delete any leftover
+`vaultik-*` entry in the temporary directory yourself.
+
+Trust the temporary directory as much as the directory you restore into.
+
+### Commands need different permissions
+
+`snapshot create` needs only permission to write objects. Other commands need
+more:
+
+- `snapshot list`, `snapshot verify`, `snapshot restore` and `remote info` list
+  and read.
+- `snapshot purge`, `snapshot remove` and `remote nuke` list and delete.
+- `prune` lists, reads and deletes.
+
+`snapshot create --prune` runs a prune on the backed-up machine. That machine
+then holds credentials that can delete its own backups. To keep it to
+write-only credentials, run `prune` from a separate, trusted machine.
+
+### New recipients cannot read old data
+
+Changing `age_recipients` does not re-encrypt what is already stored. A chunk
+that is already stored is not written again, so it stays encrypted to the
+earlier recipients.
+
+A new snapshot that uses such chunks cannot be restored with a new recipient's
+key alone. To make everything readable by a new key, run
+`vaultik database delete` and take a full backup to a new destination.
+
+### X25519 recipients only
+
+`vaultik` accepts age X25519 public keys only. It rejects age SSH and plugin
+recipients.
+
+The encrypted data is held by a third party for a long time. There is no second
+kind of recipient to fall back on if X25519 is broken, and no post-quantum
+option.
+
+## Order of writes
+
+A backup writes in a fixed order:
+
+- the marker file
+- the blobs
+- `db.zst.age`
+- `manifest.json.zst`
+
+A snapshot's metadata is written only after all its blobs are uploaded. The
+manifest is written last. A directory under `metadata/` that has no manifest
+therefore belongs to a backup that did not finish.
+
+The local index marks a snapshot complete only after both metadata files are
+uploaded. A backup that stops during that upload leaves the snapshot
+unfinished. The next backup removes it from the local index and stores its data
+again.
+
+One short gap remains. A backup can stop after the upload and before the
+snapshot is marked complete. The destination then holds a snapshot that can be
+restored, and the local index does not list it. `snapshot list` shows it as
+remote only.
+
+An upload that is cut off leaves no partial object under the final name on S3
+or on a local directory. The same holds for an rclone remote that can move
+objects. An rclone remote that cannot move objects can keep a partial object.
+
+## Pruning
+
+`prune` deletes two kinds of object at the destination:
+
+- a blob that no manifest lists
+- a directory under `metadata/` that has no manifest
+
+It reads the manifests, which are not encrypted, so it needs no private key.
+
+These rules keep it from deleting data that is in use:
+
+- It keeps every blob that any manifest lists.
+- It deletes nothing when any manifest cannot be downloaded or decoded.
+- It deletes a blob only once the blob is older than `prune_grace_period`.
+- It deletes a directory only once every object in it is that old.
+- It keeps a directory whose snapshot is in the local index.
+- It leaves alone a directory whose name is not a remote key.
+
+`prune_grace_period` defaults to `24h`. It protects a backup that is still
+running. Such a backup has uploaded blobs and perhaps `db.zst.age`, but not yet
+its manifest. A prune from this machine or another keeps those objects, as long
+as no backup takes longer than the grace period.
+
+The grace period does not protect one case. A backup does not upload a blob
+that is already at the destination, so that blob keeps the time of its first
+upload. The blob can be left over from an earlier backup that stopped before
+its manifest. A prune that runs before the new manifest is written can then
+delete that blob. The new snapshot cannot be restored afterwards.
+
+To avoid this case, give each machine and each user its own destination.
+
+`remote nuke` applies none of these rules.
+
+## What a restore needs
+
+- the age private key
+- the snapshot's `db.zst.age`
+- the blobs that hold the files to restore
+
+A restore does not read the manifest and does not need the local index.
+
+It works in these steps:
+
+- It downloads and decrypts `db.zst.age`.
+- It checks that the database is the one for the snapshot that was asked for.
+- It downloads and decrypts the blobs it needs. It checks each blob against its
+  name.
+- It writes each file from its chunks.
+- It sets each file's permissions and times, and its owner when it runs as
+  root.

go.mod

@@ -22,6 +22,7 @@ require (
 	github.com/spf13/cobra v1.10.1
 	github.com/spf13/pflag v1.0.10
 	github.com/stretchr/testify v1.11.1
+	go.uber.org/dig v1.19.0
 	go.uber.org/fx v1.24.0
 	golang.org/x/sync v0.18.0
 	golang.org/x/sys v0.38.0
@@ -256,7 +257,6 @@ require (
 	go.opentelemetry.io/otel/metric v1.38.0 // indirect
 	go.opentelemetry.io/otel/trace v1.38.0 // indirect
 	go.shabbyrobe.org/gocovmerge v0.0.0-20230507111327-fa4f82cfbf4d // indirect
-	go.uber.org/dig v1.19.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
 	go.uber.org/zap v1.27.0 // indirect
 	go.yaml.in/yaml/v2 v2.4.3 // indirect

internal/blob/packer.go

@@ -245,6 +245,17 @@ func (p *Packer) Flush(ctx context.Context) error {
 	return nil
 }
 
+// DiscardCurrentBlob closes and removes the temp file of the blob being
+// packed, if any, and drops that blob. A caller that stops before Flush
+// must call it, or the temp file is left behind. Thread-safe.
+func (p *Packer) DiscardCurrentBlob() {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	p.cleanupTempFile()
+	p.currentBlob = nil
+}
+
 // FinalizeBlob finalizes the current blob being assembled.
 // This compresses the accumulated chunks, encrypts the result, and computes
 // the content-addressed hash. The finalized blob is either passed to the

internal/cli/app.go

@@ -8,12 +8,12 @@ import (
 	"errors"
 	"fmt"
 	"path/filepath"
-	"strings"
 	"sync"
 	"time"
 
 	"github.com/adrg/xdg"
 	"github.com/spf13/cobra"
+	"go.uber.org/dig"
 	"go.uber.org/fx"
 	"sneak.berlin/go/vaultik/internal/config"
 	"sneak.berlin/go/vaultik/internal/database"
@@ -146,16 +146,12 @@ func (e *startupError) Error() string {
 //	could not build arguments for function "Y" (file:line): failed to build U:
 //	received non-nil error from function "Z" (file:line): <real error>
 //
-// Users care about the real error, not the DI plumbing. We strip everything
+// Users care about the real error, not the DI plumbing. dig.RootCause,
-// up through the last "): " (which is always the close-paren of an fx
+// from the library fx is built on, unwraps those layers and returns the
-// function-location annotation followed by the wrapped error).
+// real error whole. Cutting the text at "): " instead would also cut a
+// real error that contains it, such as the blob_size_limit one.
 func cleanStartupError(err error) error {
-	msg := err.Error()
+	return &startupError{msg: dig.RootCause(err).Error()}
-	if idx := strings.LastIndex(msg, "): "); idx >= 0 {
-		msg = msg[idx+3:]
-	}
-
-	return &startupError{msg: msg}
 }
 
 // RunApp starts the fx application, blocks until it is asked to stop, and
@@ -225,16 +221,20 @@ var errInterrupted = errors.New("interrupted before the command finished")
 // op's cleanup (removing decrypted scratch files) runs before the
 // process exits; the wait is bounded by shutdownTimeout. report is
 // called with a failure so the caller can show it to the user before
-// it becomes errReported. An interrupted op is not reported, whatever
+// it becomes errReported.
-// it returned; RunOperation returns errInterrupted instead.
+//
+// The run counts as interrupted unless op returned, without an
+// interrupt having cancelled it, before RunWithApp returned. An
+// interrupted op is not reported, whatever it returned; RunOperation
+// returns errInterrupted instead.
 func RunOperation(
 	ctx context.Context, opts AppOptions,
 	op func(v *vaultik.Vaultik) error, report func(err error),
 ) error {
 	var (
-		mu          sync.Mutex
+		mu       sync.Mutex
-		failed      bool
+		finished bool // op returned before any interrupt cancelled it
-		interrupted bool
+		failed   bool // op finished with an error
 	)
 
 	opts.Invokes = append(opts.Invokes,
@@ -247,21 +247,19 @@ func RunOperation(
 						err := op(v)
 
 						// Only stop, called from OnStop below, cancels the
-						// Vaultik context; before op has returned, that
+						// Vaultik context, so a live context means no
-						// happens only on an interrupt. Check the context,
+						// interrupt cancelled op. Check the context, not
-						// not err: an interrupted op need not return
+						// err: an interrupted op need not return
 						// context.Canceled (`snapshot verify --json`
 						// returns a verification failure).
-						switch {
+						if v.Context().Err() == nil {
-						case v.Context().Err() != nil:
+							if err != nil {
-							mu.Lock()
+								report(err)
-							interrupted = true
+							}
-							mu.Unlock()
-						case err != nil:
-							report(err)
 
 							mu.Lock()
-							failed = true
+							finished = true
+							failed = err != nil
 							mu.Unlock()
 						}
 
@@ -282,12 +280,6 @@ func RunOperation(
 					if !stop(ctx) {
 						log.Warn("Shutdown timed out before the operation " +
 							"finished; decrypted temporary files may remain")
-
-						// op has not returned, so the app is stopping on
-						// an interrupt.
-						mu.Lock()
-						interrupted = true
-						mu.Unlock()
 					}
 
 					return nil
@@ -300,16 +292,17 @@ func RunOperation(
 		return err
 	}
 
-	// RunWithApp returns only after OnStop has waited for the goroutine
+	// RunWithApp returns only after the app was asked to stop, either by
-	// to return, whether the shutdown came from op finishing or from an
+	// an interrupt or by the goroutine's Shutdown call. When op finished
-	// interrupt, so the goroutine's write to failed or interrupted is in
+	// without being cancelled, the goroutine set finished before that
-	// place by the time we read it. If OnStop timed out, the goroutine
+	// call. So if finished is unset here, an interrupt stopped the app,
-	// may still be running, and OnStop has set interrupted itself.
+	// and op either returned after it was cancelled or is still running
+	// because the shutdown timed out.
 	mu.Lock()
 	defer mu.Unlock()
 
 	switch {
-	case interrupted:
+	case !finished:
 		return errInterrupted
 	case failed:
 		return errReported

internal/cli/app_test.go

@@ -2,58 +2,65 @@ package cli //nolint:testpackage // needs access to unexported cleanStartupError
 
 import (
 	"errors"
+	"os"
 	"path/filepath"
 	"testing"
 
+	"go.uber.org/fx"
+	"sneak.berlin/go/vaultik/internal/config"
 	"sneak.berlin/go/vaultik/internal/pidlock"
 )
 
+// TestCleanStartupError starts a real fx app whose config has a
+// blob_size_limit below the minimum. fx puts annotations naming the
+// functions it was building in front of the config error; only those
+// may be removed, although the config error itself contains "): ".
 func TestCleanStartupError(t *testing.T) {
 	t.Parallel()
 
-	tests := []struct {
+	path := filepath.Join(t.TempDir(), "config.yml")
-		name string
+
-		in   string
+	err := os.WriteFile(path, []byte("snapshots:\n"+
-		want string
+		"  test:\n"+
-	}{
+		"    paths: [/tmp/vaultik-test-source]\n"+
-		{
+		"storage_url: file:///tmp/vaultik-test-storage\n"+
-			name: "real fx error chain",
+		"chunk_size: 10MB\n"+
-			in: `could not build arguments for function ` +
+		"blob_size_limit: 30MB\n"), 0o600)
-				`"sneak.berlin/go/vaultik/internal/cli".newSnapshotCreateCommand.func1.1 ` +
+	if err != nil {
-				`(/Users/user/dev/vaultik/internal/cli/snapshot.go:71): ` +
+		t.Fatalf("write config: %v", err)
-				`failed to build *vaultik.Vaultik: ` +
-				`could not build arguments for function ` +
-				`"sneak.berlin/go/vaultik/internal/vaultik".New ` +
-				`(/Users/user/dev/vaultik/internal/vaultik/vaultik.go:59): ` +
-				`failed to build storage.Storer: ` +
-				`received non-nil error from function ` +
-				`"sneak.berlin/go/vaultik/internal/storage".NewStorer ` +
-				`(/Users/user/dev/vaultik/internal/storage/module.go:23): ` +
-				`creating base path: mkdir /Volumes/BACKUPS: permission denied`,
-			want: `creating base path: mkdir /Volumes/BACKUPS: permission denied`,
-		},
-		{
-			name: "no fx wrapping",
-			in:   "plain error",
-			want: "plain error",
-		},
-		{
-			name: "single fx wrapping",
-			in:   `received non-nil error from function "foo" (file.go:1): underlying problem`,
-			want: "underlying problem",
-		},
 	}
 
-	for _, tt := range tests {
+	app := fx.New(
-		t.Run(tt.name, func(t *testing.T) {
+		fx.NopLogger,
-			t.Parallel()
+		fx.Supply(config.Path(path)),
+		config.Module,
+		fx.Invoke(func(*config.Config) {}),
+	)
 
-			//nolint:err113 // test constructs errors from table input
+	err = app.Start(t.Context())
-			got := cleanStartupError(errors.New(tt.in)).Error()
+	if err == nil {
-			if got != tt.want {
+		t.Fatal("app started; want a blob_size_limit error")
-				t.Errorf("got %q, want %q", got, tt.want)
+	}
-			}
+
-		})
+	want := "failed to load config: invalid config: blob_size_limit must " +
+		"be at least the largest chunk the chunker can emit (chunk_size " +
+		"times the FastCDC size spread): need at least 40000000 bytes"
+
+	got := cleanStartupError(err).Error()
+	if got != want {
+		t.Errorf("got %q, want %q", got, want)
+	}
+}
+
+// TestCleanStartupErrorNotFromFx checks that an error fx did not wrap is
+// shown unchanged.
+func TestCleanStartupErrorNotFromFx(t *testing.T) {
+	t.Parallel()
+
+	//nolint:err113 // a one-off error standing in for a startup failure
+	got := cleanStartupError(errors.New("plain error")).Error()
+	if got != "plain error" {
+		t.Errorf("got %q, want %q", got, "plain error")
 	}
 }
 

internal/cli/config.go

@@ -8,6 +8,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"reflect"
+	"slices"
 	"strconv"
 	"strings"
 	"unicode/utf8"
@@ -44,6 +45,9 @@ var (
 	errNeedNumericIndex = errors.New("key is a list; use a numeric index")
 	errIndexOutOfRange  = errors.New("index out of range")
 	errNotMapOrList     = errors.New("key is not a map or list")
+	errWouldNotLoad     = errors.New(
+		"vaultik would not load the config after this change, " +
+			"so the file was not changed")
 )
 
 const defaultConfigTemplate = `# vaultik configuration
@@ -220,7 +224,7 @@ storage_url: ""
 
 # Average chunk size for content-defined chunking (FastCDC).
 # Smaller = better deduplication but more metadata overhead.
-# Accepts: 1MB, 10M, 64KB, etc.
+# Minimum 1MB. Accepts: 1MB, 10M, 64MiB, etc.
 # Default: 10MB
 # chunk_size: 10MB
 
@@ -235,6 +239,18 @@ storage_url: ""
 # Default: 3
 # compression_level: 3
 
+# How old a blob that no snapshot lists must be before prune deletes it,
+# and how old every object in a directory under metadata/ with no manifest
+# must be before prune deletes that directory. A backup uploads its blobs
+# and its db.zst.age before its manifest, so on a destination shared
+# between hosts or users this must be longer than the longest backup run.
+# It does not protect a blob a backup reuses from an earlier run that
+# stopped before its manifest: that blob keeps the time of its first
+# upload, so a prune can delete it.
+# Accepts: 36h, 90m, etc. 0s deletes such blobs and directories at once.
+# Default: 24h
+# prune_grace_period: 24h
+
 # Hostname used in snapshot IDs. Default: system hostname.
 # hostname: myserver
 
@@ -251,6 +267,12 @@ func NewConfigCommand() *cobra.Command {
 		Use:   "config",
 		Short: "Manage the configuration file",
 		Long:  "Commands for creating, editing, and querying the vaultik config file.",
+		// cobra checks Args only on a command that has a Run: without
+		// one, a mistyped subcommand printed help and exited 0.
+		Args: cobra.NoArgs,
+		Run: func(cmd *cobra.Command, _ []string) {
+			_ = cmd.Help()
+		},
 	}
 
 	cmd.AddCommand(newConfigInitCommand())
@@ -267,12 +289,14 @@ func newConfigInitCommand() *cobra.Command {
 		Use:   "init",
 		Short: "Write a default config file",
 		Long: `Creates a default configuration file with commented explanations
-for every setting. If a config file already exists at the target path,
+for the settings it lists. If a config file already exists at the target
-the command refuses to overwrite it.
+path, the command refuses to overwrite it. The file is created with mode
+0600, because it can hold credentials.
 
 The config is written to the path from --config, $VAULTIK_CONFIG, or
-the platform default config directory (e.g. ~/Library/Application Support/
+config.yml in the platform default config directory
-on macOS, ~/.config/ on Linux, /etc/vaultik/ as root).`,
+(~/Library/Application Support/vaultik/ on macOS, ~/.config/vaultik/ on
+Linux, /etc/vaultik/ as root).`,
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			path := configPathForInit()
@@ -310,7 +334,7 @@ on macOS, ~/.config/ on Linux, /etc/vaultik/ as root).`,
 func newConfigEditCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:   "edit",
-		Short: "Open the config file in $EDITOR",
+		Short: "Open the config file in $EDITOR (vi when it is not set)",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			path, err := ResolveConfigPath()
@@ -323,8 +347,15 @@ func newConfigEditCommand() *cobra.Command {
 				editor = "vi"
 			}
 
+			// Run $EDITOR through the shell, as git does, so a value
+			// with arguments such as "code --wait" works. The path
+			// goes in as an argument ("$@"), not into the command
+			// text, so a path with spaces or quotes arrives whole.
+			// sh -c takes the word after the command as $0, which
+			// is why editor appears twice.
 			//nolint:gosec // G204: launching the operator's own $EDITOR is the point
-			ed := exec.CommandContext(cmd.Context(), editor, path)
+			ed := exec.CommandContext(cmd.Context(),
+				"sh", "-c", editor+` "$@"`, editor, path)
 			ed.Stdin = os.Stdin
 			ed.Stdout = os.Stdout
 			ed.Stderr = os.Stderr
@@ -385,8 +416,17 @@ func newConfigSetCommand() *cobra.Command {
 		Use:   "set <key> <value>",
 		Short: "Set a config value by dotted path (e.g. compression_level 5)",
 		Long: `Sets a scalar config value addressed by dotted YAML path and writes
-the file back, preserving comments and formatting. Intermediate maps
+the file back, preserving comments and formatting. Missing keys along
-are created as needed.
+the path are created: as a list when the next path element is a
+number, otherwise as a map.
+
+If the config loads, a change after which it would not, such as
+compression_level 99, is refused and the file is left unchanged. A
+config that does not load, such as the one config init writes before
+storage_url is set or one with a ${ENV:...} reference to a variable
+not set here, is checked one setting at a time: only a change after
+which the changed setting cannot be read, such as one giving it the
+wrong type, is refused.
 
 Examples:
   vaultik config set storage_url "file:///mnt/backups"
@@ -416,7 +456,14 @@ func writeConfigSet(out *ui.Writer, path, key, value string) error {
 		return err
 	}
 
-	err = yamlPathSet(root, strings.Split(key, "."), value)
+	oldData, err := marshalConfigYAML(root)
+	if err != nil {
+		return fmt.Errorf("marshaling config: %w", err)
+	}
+
+	keys := strings.Split(key, ".")
+
+	err = yamlPathSet(root, keys, value)
 	if err != nil {
 		return err
 	}
@@ -426,6 +473,21 @@ func writeConfigSet(out *ui.Writer, path, key, value string) error {
 		return fmt.Errorf("marshaling config: %w", err)
 	}
 
+	setting, err := yamlPathOnly(root, keys)
+	if err != nil {
+		return err
+	}
+
+	settingData, err := marshalConfigYAML(setting)
+	if err != nil {
+		return fmt.Errorf("marshaling config: %w", err)
+	}
+
+	err = checkConfigChange(oldData, data, settingData)
+	if err != nil {
+		return fmt.Errorf("%w: %w", errWouldNotLoad, err)
+	}
+
 	err = os.WriteFile(path, data, configFileMode)
 	if err != nil {
 		return fmt.Errorf("writing config file: %w", err)
@@ -447,6 +509,58 @@ func writeConfigSet(out *ui.Writer, path, key, value string) error {
 	return nil
 }
 
+// checkConfigChange returns the reason vaultik would not load newData, the
+// config after a change, if the change brings that failure in. If oldData,
+// the config before it, loads, the new one must load too. A config that
+// does not load, such as one still being filled in or one with a ${...}
+// reference that cannot be filled in here, is checked one setting at a
+// time: settingData, the changed setting on its own, must decode into the
+// config type.
+func checkConfigChange(oldData, newData, settingData []byte) error {
+	oldCfg, err := config.Parse(oldData)
+	if err == nil && oldCfg.Validate() == nil {
+		newCfg, err := config.Parse(newData)
+		if err != nil {
+			return err
+		}
+
+		return newCfg.Validate()
+	}
+
+	_, err = config.Parse(settingData)
+
+	return err
+}
+
+// yamlPathOnly returns a document holding only the value at the dotted key
+// path in root, inside the maps and lists that lead to it there.
+func yamlPathOnly(root *yaml.Node, keys []string) (*yaml.Node, error) {
+	node, err := yamlPathGet(root, keys)
+	if err != nil {
+		return nil, err
+	}
+
+	for i, key := range slices.Backward(keys) {
+		parent, err := yamlPathGet(root, keys[:i])
+		if err != nil {
+			return nil, err
+		}
+
+		if parent.Kind == yaml.SequenceNode {
+			node = &yaml.Node{
+				Kind: yaml.SequenceNode, Content: []*yaml.Node{node},
+			}
+		} else {
+			keyNode := &yaml.Node{Kind: yaml.ScalarNode, Value: key}
+			node = &yaml.Node{
+				Kind: yaml.MappingNode, Content: []*yaml.Node{keyNode, node},
+			}
+		}
+	}
+
+	return &yaml.Node{Kind: yaml.DocumentNode, Content: []*yaml.Node{node}}, nil
+}
+
 // marshalConfigYAML renders a config document tree with 2-space indentation,
 // matching defaultConfigTemplate. yaml.Marshal defaults to 4 spaces, which
 // would reindent the whole file on the first `config set` despite the promise
@@ -553,8 +667,8 @@ func yamlPathGet(root *yaml.Node, keys []string) (*yaml.Node, error) {
 	return node, nil
 }
 
-// yamlPathSet navigates a dotted key path, creating intermediate maps as
+// yamlPathSet navigates a dotted key path, creating missing keys as needed,
-// needed, and sets the final key to the given scalar value. Numeric path
+// and sets the final key to the given scalar value. Numeric path
 // components index into sequences; an index equal to the sequence length
 // appends a new element (e.g. "age_recipients.1" on a 1-element list).
 func yamlPathSet(root *yaml.Node, keys []string, value string) error {
@@ -567,12 +681,12 @@ func yamlPathSet(root *yaml.Node, keys []string, value string) error {
 		node = node.Content[0]
 	}
 
-	for i, key := range keys {
+	for i := range keys {
 		last := i == len(keys)-1
 
 		switch node.Kind {
 		case yaml.MappingNode:
-			node = yamlSetInMapping(node, key, value, last)
+			node = yamlSetInMapping(node, keys, i, value, last)
 		case yaml.SequenceNode:
 			next, err := yamlSetInSequence(node, keys, i, value, last)
 			if err != nil {
@@ -641,14 +755,16 @@ func yamlField(typ reflect.Type, key string) (reflect.StructField, bool) {
 	return reflect.StructField{}, false
 }
 
-// yamlSetInMapping resolves (creating if needed) the value node for key
+// yamlSetInMapping resolves (creating if needed) the value node for the
-// within a mapping node, setting it to value when it is the final path
+// path element keys[i] within a mapping node, setting it to value when it
-// element, and returns the node to descend into.
+// is the final path element, and returns the node to descend into.
-func yamlSetInMapping(node *yaml.Node, key, value string, last bool) *yaml.Node {
+func yamlSetInMapping(
+	node *yaml.Node, keys []string, i int, value string, last bool,
+) *yaml.Node {
 	var valueNode *yaml.Node
 
 	for j := 0; j+1 < len(node.Content); j += 2 {
-		if node.Content[j].Value == key {
+		if node.Content[j].Value == keys[i] {
 			valueNode = node.Content[j+1]
 
 			break
@@ -656,13 +772,8 @@ func yamlSetInMapping(node *yaml.Node, key, value string, last bool) *yaml.Node
 	}
 
 	if valueNode == nil {
-		keyNode := &yaml.Node{Kind: yaml.ScalarNode, Value: key}
+		keyNode := &yaml.Node{Kind: yaml.ScalarNode, Value: keys[i]}
-
+		valueNode = newPathNode(keys, i, value)
-		valueNode = &yaml.Node{Kind: yaml.MappingNode}
-		if last {
-			valueNode = &yaml.Node{Kind: yaml.ScalarNode, Value: value}
-		}
-
 		node.Content = append(node.Content, keyNode, valueNode)
 	} else if last {
 		setScalar(valueNode, value)
@@ -690,12 +801,7 @@ func yamlSetInSequence(
 	}
 
 	if idx == len(node.Content) {
-		newNode := &yaml.Node{Kind: yaml.MappingNode}
+		node.Content = append(node.Content, newPathNode(keys, i, value))
-		if last {
-			newNode = &yaml.Node{Kind: yaml.ScalarNode, Value: value}
-		}
-
-		node.Content = append(node.Content, newNode)
 	} else if last {
 		setScalar(node.Content[idx], value)
 	}
@@ -703,6 +809,22 @@ func yamlSetInSequence(
 	return node.Content[idx], nil
 }
 
+// newPathNode returns the node to create for the missing path element
+// keys[i]: the value when it is the final path element, otherwise an empty
+// list when the next path element is a number and an empty map when not.
+func newPathNode(keys []string, i int, value string) *yaml.Node {
+	if i == len(keys)-1 {
+		return &yaml.Node{Kind: yaml.ScalarNode, Value: value}
+	}
+
+	_, err := strconv.Atoi(keys[i+1])
+	if err == nil {
+		return &yaml.Node{Kind: yaml.SequenceNode}
+	}
+
+	return &yaml.Node{Kind: yaml.MappingNode}
+}
+
 // setScalar overwrites a node in place with a plain scalar value.
 func setScalar(n *yaml.Node, value string) {
 	n.Kind = yaml.ScalarNode

internal/cli/config_test.go

@@ -58,14 +58,17 @@ func TestDefaultConfigTemplateParses(t *testing.T) {
 	}
 }
 
-// TestConfigSetRecipientOnFreshConfig follows the README quickstart: on the
+// testRecipient is a valid age public key.
-// file `config init` writes, `config set age_recipients.0` and
+const testRecipient = "age1278m9q7dp3chsh2dcy82qk27v047zywyvtxwnj4cvt0z65jw6a7q5dqhfj"
+
+// TestConfigSetRecipientOnFreshConfig follows the README's getting started
+// steps: on the file `config init` writes, `config set age_recipients.0` and
 // `config set storage_url` give a config that loads with that recipient.
+// Neither is refused, although the config does not load until both are set;
+// once it loads, a recipient that is not a valid key is.
 func TestConfigSetRecipientOnFreshConfig(t *testing.T) {
 	t.Parallel()
 
-	const recipient = "age1278m9q7dp3chsh2dcy82qk27v047zywyvtxwnj4cvt0z65jw6a7q5dqhfj"
-
 	path := filepath.Join(t.TempDir(), "config.yml")
 
 	err := os.WriteFile(path, []byte(defaultConfigTemplate), configFileMode)
@@ -75,7 +78,7 @@ func TestConfigSetRecipientOnFreshConfig(t *testing.T) {
 
 	out := ui.NewWithColor(&bytes.Buffer{}, false)
 
-	err = writeConfigSet(out, path, "age_recipients.0", recipient)
+	err = writeConfigSet(out, path, "age_recipients.0", testRecipient)
 	if err != nil {
 		t.Fatalf("config set age_recipients.0: %v", err)
 	}
@@ -90,8 +93,211 @@ func TestConfigSetRecipientOnFreshConfig(t *testing.T) {
 		t.Fatalf("config.Load: %v", err)
 	}
 
-	if len(cfg.AgeRecipients) != 1 || cfg.AgeRecipients[0] != recipient {
+	if len(cfg.AgeRecipients) != 1 || cfg.AgeRecipients[0] != testRecipient {
-		t.Errorf("age_recipients = %v, want [%s]", cfg.AgeRecipients, recipient)
+		t.Errorf("age_recipients = %v, want [%s]", cfg.AgeRecipients, testRecipient)
+	}
+
+	err = writeConfigSet(out, path, "age_recipients.0", "notakey")
+	if err == nil || !strings.Contains(err.Error(), "not a valid recipient") {
+		t.Errorf("config set age_recipients.0 notakey gives error %v, "+
+			"want one saying it is not a valid recipient", err)
+	}
+
+	_, err = config.Load(path)
+	if err != nil {
+		t.Errorf("config.Load after the refused change: %v", err)
+	}
+}
+
+// configWithoutRecipients loads, but has no age_recipients key and no
+// snapshot named work.
+const configWithoutRecipients = `storage_url: file:///mnt/backups
+snapshots:
+  home:
+    paths:
+      - "~"
+`
+
+// configWithUnsetReference loads only where VAULTIK_TEST_UNSET_SECRET is
+// set, as a backup job's environment might set it. No test sets it.
+const configWithUnsetReference = configWithoutRecipients + `s3:
+  secret_access_key: ${ENV:VAULTIK_TEST_UNSET_SECRET}
+`
+
+// configWithLevelReference returns configWithoutRecipients with a ${FILE:...}
+// reference on compression_level to a file holding 9, so that the config
+// loads once the reference is filled in.
+func configWithLevelReference(t *testing.T) string {
+	t.Helper()
+
+	levelPath := filepath.Join(t.TempDir(), "level")
+
+	err := os.WriteFile(levelPath, []byte("9"), configFileMode)
+	if err != nil {
+		t.Fatalf("write level: %v", err)
+	}
+
+	return configWithoutRecipients +
+		"compression_level: ${FILE:" + levelPath + "}\n"
+}
+
+// TestConfigSetIndexUnderMissingKey checks that a list index under a key
+// the file does not have creates a list, and that the result loads.
+func TestConfigSetIndexUnderMissingKey(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		key   string
+		value string
+		field func(cfg *config.Config) []string
+	}{
+		{"age_recipients.0", testRecipient,
+			func(cfg *config.Config) []string { return cfg.AgeRecipients }},
+		{"snapshots.work.paths.0", "/srv/work",
+			func(cfg *config.Config) []string { return cfg.Snapshots["work"].Paths }},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.key, func(t *testing.T) {
+			t.Parallel()
+
+			path := filepath.Join(t.TempDir(), "config.yml")
+
+			err := os.WriteFile(path, []byte(configWithoutRecipients), configFileMode)
+			if err != nil {
+				t.Fatalf("write config: %v", err)
+			}
+
+			err = writeConfigSet(ui.NewWithColor(&bytes.Buffer{}, false),
+				path, tt.key, tt.value)
+			if err != nil {
+				t.Fatalf("config set %s: %v", tt.key, err)
+			}
+
+			cfg, err := config.Load(path)
+			if err != nil {
+				t.Fatalf("config.Load: %v", err)
+			}
+
+			got := tt.field(cfg)
+			if len(got) != 1 || got[0] != tt.value {
+				t.Errorf("%s gives %v, want [%s]", tt.key, got, tt.value)
+			}
+		})
+	}
+}
+
+// TestConfigSetKeepsFileThatWouldNotLoad checks that config set refuses a
+// change after which the config would not load, with an error giving the
+// reason, and leaves the file as it was. On the file `config init` writes,
+// which does not load until storage_url is set, and on one that cannot be
+// read here, only a value of the wrong type is refused.
+func TestConfigSetKeepsFileThatWouldNotLoad(t *testing.T) {
+	t.Parallel()
+
+	levelReference := configWithLevelReference(t)
+
+	tests := []struct {
+		config string
+		key    string
+		value  string
+		reason string
+	}{
+		// Index 1 of the empty list the missing key gives.
+		{configWithoutRecipients, "age_recipients.1", testRecipient,
+			"index out of range"},
+		// A list set to a single value.
+		{configWithoutRecipients, "snapshots.home.paths", "/srv",
+			"into []string"},
+		{configWithoutRecipients, "chunk_size", "fast",
+			"invalid size format"},
+		// Values of the right type that fail validation.
+		{configWithoutRecipients, "compression_level", "99",
+			"compression_level must be between 1 and 19"},
+		{configWithoutRecipients, "chunk_size", "1KB",
+			"chunk_size must be at least 1MB"},
+		// With its reference filled in, the config loads.
+		{levelReference, "blob_size_limit", "1MB",
+			"blob_size_limit must be at least"},
+		// The type check on a config that does not load yet.
+		{defaultConfigTemplate, "snapshots.apps.paths", "/srv",
+			"into []string"},
+		// The type check on a config that cannot be read here.
+		{configWithUnsetReference, "snapshots.home.paths", "/x",
+			"cannot unmarshal !!str `/x`"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.key+" "+tt.value, func(t *testing.T) {
+			t.Parallel()
+
+			path := filepath.Join(t.TempDir(), "config.yml")
+
+			err := os.WriteFile(path, []byte(tt.config), configFileMode)
+			if err != nil {
+				t.Fatalf("write config: %v", err)
+			}
+
+			err = writeConfigSet(ui.NewWithColor(&bytes.Buffer{}, false),
+				path, tt.key, tt.value)
+			if err == nil || !strings.Contains(err.Error(), tt.reason) {
+				t.Errorf("config set %s %s gives error %v, want one saying %q",
+					tt.key, tt.value, err, tt.reason)
+			}
+
+			data, err := os.ReadFile(path) //nolint:gosec // G304: test-controlled path
+			if err != nil {
+				t.Fatalf("read config: %v", err)
+			}
+
+			if string(data) != tt.config {
+				t.Errorf("config set %s changed the file to:\n%s",
+					tt.key, data)
+			}
+		})
+	}
+}
+
+// TestConfigSetRefusesOnlyItsOwnFailure checks that setting another key
+// works on a config with a ${...} reference on compression_level, which
+// loads because loading fills the reference in, on one whose
+// compression_level already fails to load, and on one with a reference
+// that cannot be filled in here.
+func TestConfigSetRefusesOnlyItsOwnFailure(t *testing.T) {
+	t.Parallel()
+
+	configs := map[string]string{
+		"reference":       configWithLevelReference(t),
+		"failing":         configWithoutRecipients + "compression_level: fast\n",
+		"unset reference": configWithUnsetReference,
+	}
+
+	for name, configYAML := range configs {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			path := filepath.Join(t.TempDir(), "config.yml")
+
+			err := os.WriteFile(path, []byte(configYAML), configFileMode)
+			if err != nil {
+				t.Fatalf("write config: %v", err)
+			}
+
+			err = writeConfigSet(ui.NewWithColor(&bytes.Buffer{}, false),
+				path, "hostname", "myhost")
+			if err != nil {
+				t.Fatalf("config set hostname: %v", err)
+			}
+
+			data, err := os.ReadFile(path) //nolint:gosec // G304: test-controlled path
+			if err != nil {
+				t.Fatalf("read config: %v", err)
+			}
+
+			if !strings.Contains(string(data), "hostname: myhost") {
+				t.Errorf("config set hostname wrote:\n%s", data)
+			}
+		})
 	}
 }
 
@@ -441,6 +647,30 @@ func TestWriteConfigSetTightensMode(t *testing.T) {
 	}
 }
 
+// TestConfigEditEditorWithArgument checks that an $EDITOR carrying an
+// argument works and that a config path with a space reaches it whole.
+// The "editor" is cp with the replacement file as its argument, so the
+// config ends up with the replacement's content only if both arrived.
+func TestConfigEditEditorWithArgument(t *testing.T) {
+	dir := t.TempDir()
+	path := seedFile(t, dir, "my config.yml", "compression_level: 3\n")
+	edited := seedFile(t, dir, "edited.yml", "compression_level: 9\n")
+
+	setRootFlags(t, RootFlags{ConfigPath: path})
+	t.Setenv("EDITOR", "cp '"+edited+"'")
+
+	mustExecute(t, newConfigEditCommand())
+
+	data, err := os.ReadFile(path) //nolint:gosec // G304: test-controlled path
+	if err != nil {
+		t.Fatalf("reading config back: %v", err)
+	}
+
+	if string(data) != "compression_level: 9\n" {
+		t.Errorf("config after edit = %q, want the edited content", data)
+	}
+}
+
 func splitPath(s string) []string {
 	return strings.Split(s, ".")
 }

internal/cli/database.go

@@ -15,6 +15,12 @@ func NewDatabaseCommand() *cobra.Command {
 		Use:   "database",
 		Short: "Manage the local state database",
 		Long:  `Commands for managing the local SQLite state database.`,
+		// cobra checks Args only on a command that has a Run: without
+		// one, a mistyped subcommand printed help and exited 0.
+		Args: cobra.NoArgs,
+		Run: func(cmd *cobra.Command, _ []string) {
+			_ = cmd.Help()
+		},
 	}
 
 	cmd.AddCommand(

internal/cli/entry_prune_json_test.go

@@ -101,7 +101,8 @@ func TestEntryPruneJSONStdoutIsExactlyOneDocument(t *testing.T) {
 // writeHermeticPruneConfig builds a config over a temp directory with an
 // empty destination directory and, if seedStale is set, creates the
 // index database up front with one snapshot record that has no
-// counterpart on the destination store. Returns the config path.
+// counterpart on the destination store, and gives the destination the
+// marker a backup writes. Returns the config path.
 func writeHermeticPruneConfig(t *testing.T, seedStale bool) string {
 	t.Helper()
 
@@ -131,6 +132,11 @@ func writeHermeticPruneConfig(t *testing.T, seedStale bool) string {
 
 	if seedStale {
 		seedStaleSnapshotRecord(t, indexPath)
+
+		// While the local index holds a snapshot, prune fails on a
+		// destination that answers that it has no marker.
+		require.NoError(t, os.WriteFile(
+			filepath.Join(storeDir, "vaultik-destination.txt"), nil, 0o600))
 	}
 
 	return configPath

internal/cli/entry_prune_quiet_test.go

@@ -0,0 +1,127 @@
+package cli //nolint:testpackage // shares runEntry and the hermetic config helpers
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// flagCron is used to build the argument vectors below.
+const flagCron = "--cron"
+
+// plantUnreferencedBlob writes a blob that no snapshot references to the
+// destination store at storeDir, dated long before any prune grace period,
+// so that a prune deletes it. Returns its path.
+func plantUnreferencedBlob(t *testing.T, storeDir string) string {
+	t.Helper()
+
+	hash := strings.Repeat("b", 64)
+	path := filepath.Join(storeDir, "blobs", hash[:2], hash[2:4], hash)
+
+	require.NoError(t, os.MkdirAll(filepath.Dir(path), 0o750))
+	require.NoError(t, os.WriteFile(path, []byte("unreferenced"), 0o600))
+
+	longAgo := time.Unix(0, 0)
+	require.NoError(t, os.Chtimes(path, longAgo, longAgo))
+
+	return path
+}
+
+// TestEntrySnapshotCreatePruneIsSilent checks that a successful
+// `snapshot create --prune` under --cron or --quiet prints nothing on
+// stdout or stderr, whether or not the prune finds a blob to delete.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotCreatePruneIsSilent(t *testing.T) {
+	for _, testCase := range []struct {
+		name      string
+		args      []string
+		plantBlob bool
+	}{
+		{
+			name: "cron, no blob to delete",
+			args: []string{cmdSnapshot, cmdCreate, flagCron, flagPrune},
+		},
+		{
+			name:      "cron, blob to delete",
+			args:      []string{cmdSnapshot, cmdCreate, flagCron, flagPrune},
+			plantBlob: true,
+		},
+		{
+			name: "cron with keep-newer-than",
+			args: []string{
+				cmdSnapshot, cmdCreate, flagCron, flagPrune,
+				flagKeepNewerThan, "4w",
+			},
+			plantBlob: true,
+		},
+		{
+			name:      "quiet",
+			args:      []string{flagQuiet, cmdSnapshot, cmdCreate, flagPrune},
+			plantBlob: true,
+		},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			configPath, storeDir := writeBackupConfig(t)
+
+			var blob string
+			if testCase.plantBlob {
+				blob = plantUnreferencedBlob(t, storeDir)
+			}
+
+			code, stdout, stderr := runEntry(t,
+				append([]string{flagConfig, configPath}, testCase.args...)...)
+
+			assert.Equal(t, 0, code)
+			assert.Empty(t, stdout)
+			assert.Empty(t, stderr)
+
+			if testCase.plantBlob {
+				assert.NoFileExists(t, blob, "the prune must delete the blob")
+			}
+		})
+	}
+}
+
+// TestEntryPruneQuietIsSilent checks that a successful `prune --force`
+// under --quiet prints nothing on stdout or stderr, both when there is
+// nothing to remove and when it removes a stale local snapshot record
+// and an unreferenced blob.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntryPruneQuietIsSilent(t *testing.T) {
+	for _, testCase := range []struct {
+		name               string
+		staleRecordAndBlob bool
+	}{
+		{name: "nothing to remove"},
+		{name: "stale record and blob to remove", staleRecordAndBlob: true},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			configPath := writeHermeticPruneConfig(t, testCase.staleRecordAndBlob)
+
+			var blob string
+			if testCase.staleRecordAndBlob {
+				// writeHermeticPruneConfig puts the store beside the config.
+				blob = plantUnreferencedBlob(t,
+					filepath.Join(filepath.Dir(configPath), "store"))
+			}
+
+			code, stdout, stderr := runEntry(t,
+				flagConfig, configPath, flagQuiet, cmdPrune, flagForce)
+
+			assert.Equal(t, 0, code)
+			assert.Empty(t, stdout)
+			assert.Empty(t, stderr)
+
+			if testCase.staleRecordAndBlob {
+				assert.NoFileExists(t, blob, "the prune must delete the blob")
+			}
+		})
+	}
+}

internal/cli/entry_snapshot_create_prune_test.go

@@ -0,0 +1,185 @@
+package cli //nolint:testpackage // shares runEntry and the hermetic config helpers
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/database"
+)
+
+// Flags of `snapshot create` used to build argument vectors below.
+const (
+	flagPrune         = "--prune"
+	flagKeepNewerThan = "--keep-newer-than"
+)
+
+// TestEntrySnapshotCreateRejectsKeepNewerThanBeforeBackup checks that a
+// --keep-newer-than the post-backup prune could not use stops `snapshot
+// create` before the backup: the command fails and the destination
+// store stays empty. It used to be read only by the prune, after the
+// snapshot was uploaded, and without --prune it was ignored.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotCreateRejectsKeepNewerThanBeforeBackup(t *testing.T) {
+	for _, testCase := range []struct {
+		name string
+		args []string
+	}{
+		{
+			name: "decimal in a day count",
+			args: []string{flagPrune, flagKeepNewerThan, "1.5d"},
+		},
+		{
+			name: "unknown unit",
+			args: []string{flagPrune, flagKeepNewerThan, "4x"},
+		},
+		{
+			name: "without --prune",
+			args: []string{flagKeepNewerThan, "4w"},
+		},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			configPath, storeDir := writeBackupConfig(t)
+
+			code, _, _ := runEntry(t, append(
+				[]string{flagConfig, configPath, cmdSnapshot, cmdCreate},
+				testCase.args...)...)
+
+			assert.Equal(t, 1, code)
+
+			stored, err := os.ReadDir(storeDir)
+			require.NoError(t, err)
+			assert.Empty(t, stored, "nothing may be uploaded")
+		})
+	}
+}
+
+// TestEntrySnapshotCreateReportsPostBackupPruneFailure makes the
+// post-backup prune fail after a good backup, by planting a manifest
+// that cannot be decoded, and checks that the failure is reported as the
+// prune's and not as a failed snapshot creation.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotCreateReportsPostBackupPruneFailure(t *testing.T) {
+	configPath, storeDir := writeBackupConfig(t)
+
+	// A remote key is 64 lowercase hex characters. The prune reads every
+	// manifest on the store and fails on one it cannot decode.
+	plantedDir := filepath.Join(storeDir, "metadata", strings.Repeat("a", 64))
+	require.NoError(t, os.MkdirAll(plantedDir, 0o750))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(plantedDir, "manifest.json.zst"),
+		[]byte("not a valid manifest"), 0o600))
+
+	code, _, stderr := runEntry(t,
+		flagConfig, configPath, cmdSnapshot, cmdCreate, flagPrune)
+
+	assert.Equal(t, 1, code)
+	assert.Contains(t, stderr, "Backup completed, but post-backup prune failed")
+	assert.NotContains(t, stderr, "Snapshot creation failed")
+
+	snapshots, err := os.ReadDir(filepath.Join(storeDir, "metadata"))
+	require.NoError(t, err)
+	assert.Len(t, snapshots, 2,
+		"the new snapshot is on the store beside the planted one")
+}
+
+// TestEntrySnapshotCreatePruneExitsNonZeroWhenSourceIsEmpty backs up,
+// empties the source directory, as a volume that is not mounted leaves
+// its mount point, and runs `snapshot create --prune`. The command exits
+// non-zero and reports the backup as completed, not as a failed snapshot
+// creation. See https://git.eeqj.de/sneak/vaultik/issues/388.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotCreatePruneExitsNonZeroWhenSourceIsEmpty(t *testing.T) {
+	configPath, storeDir := writeBackupConfig(t)
+
+	code, _, _ := runEntry(t, flagConfig, configPath, cmdSnapshot, cmdCreate)
+	require.Equal(t, 0, code)
+
+	// writeBackupConfig puts the source directory beside the config file.
+	require.NoError(t, os.Remove(
+		filepath.Join(filepath.Dir(configPath), "source", "file.txt")))
+
+	code, _, stderr := runEntry(t,
+		flagConfig, configPath, cmdSnapshot, cmdCreate, flagPrune)
+
+	assert.Equal(t, 1, code)
+	assert.Contains(t, stderr,
+		"Backup completed, but 1 source path(s) were empty")
+	assert.NotContains(t, stderr, "Snapshot creation failed")
+
+	snapshots, err := os.ReadDir(filepath.Join(storeDir, "metadata"))
+	require.NoError(t, err)
+	assert.Len(t, snapshots, 2, "the older snapshot is kept")
+}
+
+// TestEntrySnapshotCreatePruneExitsNonZeroWhenMountPointIsMissing backs
+// up, records in the local index that this backup found the source
+// directory as a mount point, and runs `snapshot create --prune`, which
+// does not find it as one. The command exits non-zero, reports the
+// backup as completed, not as a failed snapshot creation, and keeps the
+// older snapshot. See https://git.eeqj.de/sneak/vaultik/issues/395.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotCreatePruneExitsNonZeroWhenMountPointIsMissing(
+	t *testing.T,
+) {
+	configPath, storeDir := writeBackupConfig(t)
+
+	code, _, _ := runEntry(t, flagConfig, configPath, cmdSnapshot, cmdCreate)
+	require.Equal(t, 0, code)
+
+	// writeBackupConfig puts the source directory and the local index
+	// beside the config file.
+	dir := filepath.Dir(configPath)
+	ctx := context.Background()
+
+	db, err := database.New(ctx, filepath.Join(dir, "index.sqlite"))
+	require.NoError(t, err)
+
+	repos := database.NewRepositories(db)
+
+	backedUp, err := repos.Snapshots.GetOnlySnapshot(ctx)
+	require.NoError(t, err)
+	require.NoError(t, repos.Snapshots.AddMountPoint(ctx, nil,
+		backedUp.ID.String(), filepath.Join(dir, "source")))
+	require.NoError(t, db.Close())
+
+	code, _, stderr := runEntry(t,
+		flagConfig, configPath, cmdSnapshot, cmdCreate, flagPrune)
+
+	assert.Equal(t, 1, code)
+	assert.Contains(t, stderr, "Backup completed, but 1 mount point(s) "+
+		"an earlier snapshot recorded were not found")
+	assert.NotContains(t, stderr, "Snapshot creation failed")
+
+	snapshots, err := os.ReadDir(filepath.Join(storeDir, "metadata"))
+	require.NoError(t, err)
+	assert.Len(t, snapshots, 2, "the older snapshot is kept")
+}
+
+// writeBackupConfig builds a hermetic config with one small file in its
+// source directory and an empty destination store directory. Returns the
+// config path and the store directory.
+func writeBackupConfig(t *testing.T) (string, string) {
+	t.Helper()
+
+	configPath := writeHermeticPruneConfig(t, false)
+
+	// writeHermeticPruneConfig puts the source and store directories
+	// beside the config file.
+	dir := filepath.Dir(configPath)
+	sourceDir := filepath.Join(dir, "source")
+
+	require.NoError(t, os.Mkdir(sourceDir, 0o750))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(sourceDir, "file.txt"), []byte("hello"), 0o600))
+
+	return configPath, filepath.Join(dir, "store")
+}

internal/cli/entry_snapshot_create_skip_errors_test.go

@@ -0,0 +1,30 @@
+package cli //nolint:testpackage // shares runEntry and the hermetic config helpers
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestEntrySnapshotCreateSkipErrorsExitsNonZeroWhenItSkips backs up,
+// under --skip-errors, a source directory that does not exist, which the
+// walk skips. The command exits non-zero and reports the backup as
+// completed, not as a failed snapshot creation. See
+// https://git.eeqj.de/sneak/vaultik/issues/310.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotCreateSkipErrorsExitsNonZeroWhenItSkips(t *testing.T) {
+	// writeBackupConfig would create the source directory.
+	configPath := writeHermeticPruneConfig(t, false)
+
+	code, stdout, stderr := runEntry(t,
+		flagConfig, configPath, "--skip-errors", cmdSnapshot, cmdCreate)
+
+	assert.Equal(t, 1, code)
+	assert.Contains(t, stdout,
+		"Files: 1 examined, 0 backed up, 0 unchanged, 1 failed.")
+	assert.NotContains(t, stdout, "Finished successfully.")
+	assert.Contains(t, stderr,
+		"Backup completed, but 1 file(s) could not be read")
+	assert.NotContains(t, stderr, "Snapshot creation failed")
+}

internal/cli/entry_snapshot_purge_test.go

@@ -0,0 +1,75 @@
+package cli //nolint:testpackage // shares runEntry and the hermetic config helpers
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/database"
+	"sneak.berlin/go/vaultik/internal/snapshot"
+)
+
+// Words and flags of `snapshot purge` used to build argument vectors
+// below.
+const (
+	cmdPurge      = "purge"
+	flagOlderThan = "--older-than"
+	flagForce     = "--force"
+)
+
+// TestEntrySnapshotPurgeKeepsMetadataWhenLocalIndexDeleteFails makes
+// the local index refuse to delete an old snapshot and checks that
+// `snapshot purge` exits non-zero and leaves that snapshot's metadata on
+// the destination store. It used to log the error, delete the metadata
+// and exit 0.
+//
+// `snapshot create --prune` runs the same purge, but cannot be driven
+// this way: the refusal also breaks the backup's metadata export, which
+// deletes the other snapshots from its copy of the local index.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotPurgeKeepsMetadataWhenLocalIndexDeleteFails(t *testing.T) {
+	configPath := writeHermeticPruneConfig(t, false)
+	dir := filepath.Dir(configPath)
+	indexPath := filepath.Join(dir, "index.sqlite")
+
+	// seedStaleSnapshotRecord writes an old snapshot to the local index
+	// only; the manifest planted here puts it on the destination store
+	// too, so the purge selects it rather than dropping it as stale.
+	seedStaleSnapshotRecord(t, indexPath)
+
+	// While the local index holds a snapshot, purge fails on a
+	// destination that answers that it has no marker.
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "store", "vaultik-destination.txt"), nil, 0o600))
+
+	manifestDir := filepath.Join(dir, "store", "metadata",
+		snapshot.RemoteSnapshotKey(stalePruneSnapshotID))
+	require.NoError(t, os.MkdirAll(manifestDir, 0o750))
+
+	manifestPath := filepath.Join(manifestDir, "manifest.json.zst")
+	require.NoError(t, os.WriteFile(manifestPath, []byte("stub"), 0o600))
+
+	ctx := context.Background()
+
+	db, err := database.New(ctx, indexPath)
+	require.NoError(t, err)
+
+	_, err = db.Conn().ExecContext(ctx, `
+		CREATE TRIGGER refuse_snapshot_delete BEFORE DELETE ON snapshots
+		BEGIN SELECT RAISE(ABORT, 'simulated index error'); END`)
+	require.NoError(t, err)
+	require.NoError(t, db.Close())
+
+	code, _, stderr := runEntry(t, flagConfig, configPath,
+		cmdSnapshot, cmdPurge, flagOlderThan, "30d", flagForce)
+
+	assert.Equal(t, 1, code)
+	assert.Contains(t, stderr, "simulated index error",
+		"the purge must fail at the local-index delete")
+	assert.FileExists(t, manifestPath,
+		"the snapshot is still in the local index, so its metadata must stay")
+}

internal/cli/entry_unknown_subcommand_test.go

@@ -0,0 +1,43 @@
+package cli //nolint:testpackage // shares runEntry and the command-word constants
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestEntryGroupRejectsUnknownSubcommand runs each group command with a
+// mistyped subcommand, as a crontab line might carry one. It must fail
+// with exit 1 and name the word, as `vaultik bogus` does at the top
+// level, instead of printing the group's help and exiting 0 having done
+// nothing. The group name alone still prints its help.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout and os.Stderr
+func TestEntryGroupRejectsUnknownSubcommand(t *testing.T) {
+	for _, testCase := range []struct {
+		group    string
+		mistyped string
+	}{
+		{group: cmdSnapshot, mistyped: "craete"},
+		{group: "config", mistyped: "inti"},
+		{group: cmdRemote, mistyped: "ifno"},
+		{group: "database", mistyped: "delte"},
+		{group: "completion", mistyped: "nosuchshell"},
+	} {
+		t.Run(testCase.group, func(t *testing.T) {
+			code, stdout, stderr := runEntry(t,
+				testCase.group, testCase.mistyped)
+
+			assert.Equal(t, 1, code)
+			assert.Empty(t, stdout)
+			assert.Contains(t, stderr,
+				`unknown command "`+testCase.mistyped+`"`)
+
+			code, stdout, _ = runEntry(t, testCase.group)
+
+			assert.Equal(t, 0, code)
+			assert.Contains(t, stdout,
+				programName+" "+testCase.group+" [command]")
+		})
+	}
+}

internal/cli/json_help_test.go

@@ -0,0 +1,24 @@
+package cli //nolint:testpackage // exercises the unexported command constructor
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+)
+
+// TestJSONHelpSaysConfirmationPromptIsSkipped checks that the --json help
+// of `snapshot remove` and `prune` says the flag skips the confirmation
+// prompt. Both delete without asking under --json, since a prompt on
+// stdout would break the JSON document.
+func TestJSONHelpSaysConfirmationPromptIsSkipped(t *testing.T) {
+	t.Parallel()
+
+	for _, cmd := range []*cobra.Command{
+		newSnapshotRemoveCommand(),
+		NewPruneCommand(),
+	} {
+		assert.Contains(t, cmd.Flags().Lookup("json").Usage,
+			"skips the confirmation prompt", cmd.Name())
+	}
+}

internal/cli/prune.go

@@ -13,14 +13,28 @@ func NewPruneCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "prune",
 		Short: "Tidy local database and remote storage",
-		Long: `Removes orphaned data from both the local index database and
+		Long: `Removes orphaned data from the local index database, and
-unreferenced blobs from the backup destination store.
+unreferenced blobs and directories under metadata/ with no manifest
+from the backup destination store.
 
-Local cleanup drops incomplete snapshots and any files, chunks, or
+Needs permission to list, read and delete objects on the destination
+store. It does not need the age private key.
+
+Local cleanup drops snapshots whose manifest is gone from the
+destination store, incomplete snapshots, and any files, chunks, or
 blobs no longer referenced by a completed snapshot. Remote cleanup
 scans every snapshot manifest in the destination store, builds the
 set of still-referenced blob hashes, and deletes any blob not in that
-set.
+set that is older than prune_grace_period (default 24h). A newer one
+is kept: it may belong to a backup still running, on this host or
+another sharing the destination store, that has not yet uploaded its
+manifest. The grace period does not protect a blob such a backup
+reuses from an earlier run that stopped before its manifest: that
+blob keeps the time of its first upload, so it can be deleted.
+Remote cleanup also deletes each directory under metadata/ with no
+manifest, as a backup that stopped before its manifest leaves, once
+all its objects are older than prune_grace_period and its snapshot is
+not in the local index.
 
 Snapshot create --prune runs the same cleanup automatically; this
 command is the manual entry point for the same work (e.g. after a
@@ -57,7 +71,8 @@ referenced.`,
 	}
 
 	cmd.Flags().BoolVar(&opts.Force, "force", false, "Skip confirmation prompt")
-	cmd.Flags().BoolVar(&opts.JSON, "json", false, "Output pruning stats as JSON")
+	cmd.Flags().BoolVar(&opts.JSON, "json", false,
+		"Output pruning stats as JSON; skips the confirmation prompt, as --force does")
 
 	return cmd
 }

internal/cli/remote.go

@@ -18,6 +18,12 @@ func NewRemoteCommand() *cobra.Command {
 		Use:   "remote",
 		Short: "Remote storage management commands",
 		Long:  "Commands for inspecting and managing remote storage",
+		// cobra checks Args only on a command that has a Run: without
+		// one, a mistyped subcommand printed help and exited 0.
+		Args: cobra.NoArgs,
+		Run: func(cmd *cobra.Command, _ []string) {
+			_ = cmd.Help()
+		},
 	}
 
 	// Add subcommands
@@ -34,11 +40,13 @@ func newRemoteNukeCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "nuke",
 		Short: "Delete ALL snapshot metadata and blobs from the backup destination store",
-		Long: `Removes every snapshot's metadata and every blob from remote
+		Long: `Removes every snapshot's metadata, every blob and the destination
-storage. After this command completes successfully the bucket prefix is
+marker from the backup destination store, and each removed snapshot from
-empty and the next backup starts from scratch.
+the local index. After this command completes successfully the bucket
+prefix is empty and the next backup starts from scratch.
 
-This is destructive and irreversible. Requires --force.`,
+This is destructive and irreversible. Requires --force, and permission
+to list and delete objects on the destination store.`,
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			if !force {
@@ -69,7 +77,10 @@ func newRemoteInfoCommand() *cobra.Command {
 - Size of all snapshot metadata (per snapshot and total)
 - Count and total size of all blobs
 - Count and size of referenced blobs (from all manifests)
-- Count and size of orphaned blobs (not referenced by any manifest)`,
+- Count and size of orphaned blobs (not referenced by any manifest)
+
+Needs permission to list and read the destination store. It does not
+need the age private key.`,
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			// Use unified config resolution

internal/cli/root.go

@@ -35,9 +35,10 @@ func NewRootCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "vaultik",
 		Short: "Secure incremental backup tool with asymmetric encryption",
-		Long: `vaultik is a secure incremental backup tool that encrypts data using age
+		Long: `vaultik is an incremental backup tool that encrypts data to age public
-public keys and uploads to S3-compatible storage. No private keys are needed
+keys and uploads it to an S3-compatible object store, a local directory or
-on the source system.`,
+an rclone remote. The backed-up machine needs no private key: only
+'snapshot restore' and 'snapshot verify --deep' need one.`,
 		SilenceUsage: true,
 		// Bare 'vaultik' (no subcommand): print help. The banner is
 		// printed once at process startup by Entry, before cobra
@@ -50,13 +51,15 @@ on the source system.`,
 
 	// Add global flags
 	cmd.PersistentFlags().StringVar(&rootFlags.ConfigPath, "config", "",
-		"Path to config file (default: $VAULTIK_CONFIG or platform config dir)")
+		"Path to config file (default: $VAULTIK_CONFIG, then the platform "+
+			"config directory, then /etc/vaultik/config.yml)")
 	cmd.PersistentFlags().BoolVarP(&rootFlags.Verbose, "verbose", "v", false,
 		"Enable verbose output")
 	cmd.PersistentFlags().BoolVar(&rootFlags.Debug, "debug", false,
 		"Enable debug output")
 	cmd.PersistentFlags().BoolVarP(&rootFlags.Quiet, "quiet", "q", false,
-		"Suppress non-error output")
+		"Suppress status output (warnings, errors, JSON documents, "+
+			"'config get' values and confirmation prompts are still printed)")
 	cmd.PersistentFlags().BoolVar(&rootFlags.SkipErrors, "skip-errors", false,
 		"Skip files that cannot be read when creating a snapshot, or "+
 			"that cannot be restored when restoring, instead of aborting "+
@@ -74,6 +77,21 @@ on the source system.`,
 		NewDatabaseCommand(),
 	)
 
+	// cobra adds the completion command only when Execute runs, and with
+	// no Run, so it skipped its own cobra.NoArgs and a mistyped shell name
+	// printed help and exited 0. Adding it here lets it have a Run. Its
+	// scripts go to os.Stdout as it is now: a later SetOut does not
+	// redirect them.
+	cmd.InitDefaultCompletionCmd()
+
+	for _, sub := range cmd.Commands() {
+		if sub.Name() == "completion" {
+			sub.Run = func(completion *cobra.Command, _ []string) {
+				_ = completion.Help()
+			}
+		}
+	}
+
 	return cmd
 }
 

internal/cli/snapshot.go

@@ -41,6 +41,12 @@ func NewSnapshotCommand() *cobra.Command {
 		Use:   "snapshot",
 		Short: "Snapshot management commands",
 		Long:  "Commands for creating, listing, and managing snapshots",
+		// cobra checks Args only on a command that has a Run: without
+		// one, a mistyped subcommand printed help and exited 0.
+		Args: cobra.NoArgs,
+		Run: func(cmd *cobra.Command, _ []string) {
+			_ = cmd.Help()
+		},
 	}
 
 	// Add subcommands
@@ -54,6 +60,21 @@ func NewSnapshotCommand() *cobra.Command {
 	return cmd
 }
 
+// snapshotCreateLong is the long help text of 'snapshot create'.
+const snapshotCreateLong = `Creates new snapshots of the configured directories.
+
+If snapshot names are provided, only those snapshots are created.
+If no names are provided, all configured snapshots are created.
+
+Needs at least one public key in age_recipients, and permission to write
+objects at the backup destination store. It does not need the age private
+key. With --prune it also needs permission to list, read and delete objects
+there.
+
+The config is read from the path given by --config or VAULTIK_CONFIG;
+otherwise from the platform config directory (~/.config/vaultik/config.yml
+on Linux), then /etc/vaultik/config.yml.`
+
 // newSnapshotCreateCommand creates the 'snapshot create' subcommand
 func newSnapshotCreateCommand() *cobra.Command {
 	opts := &vaultik.SnapshotCreateOptions{}
@@ -61,16 +82,14 @@ func newSnapshotCreateCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create [snapshot-names...]",
 		Short: "Create new snapshots",
-		Long: `Creates new snapshots of the configured directories.
+		Long:  snapshotCreateLong,
-
+		Args:  cobra.ArbitraryArgs,
-If snapshot names are provided, only those snapshots are created.
-If no names are provided, all configured snapshots are created.
-
-The config is read from the path given by --config or VAULTIK_CONFIG;
-otherwise from the platform config directory (~/.config/vaultik/config.yml
-on Linux), then /etc/vaultik/config.yml.`,
-		Args: cobra.ArbitraryArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
+			err := opts.Validate()
+			if err != nil {
+				return err
+			}
+
 			// Pass snapshot names from args
 			opts.Snapshots = args
 			// --skip-errors is a global flag on the root command.
@@ -97,6 +116,22 @@ on Linux), then /etc/vaultik/config.yml.`,
 			}, func(v *vaultik.Vaultik) error {
 				return v.CreateSnapshot(opts)
 			}, func(err error) {
+				if errors.Is(err, vaultik.ErrPostBackupPruneFailed) {
+					log.Error("Post-backup prune failed", "error", err)
+					ReportErrorf("Backup completed, but %v", err)
+
+					return
+				}
+
+				if errors.Is(err, vaultik.ErrFilesUnreadable) ||
+					errors.Is(err, vaultik.ErrSourcePathEmpty) ||
+					errors.Is(err, vaultik.ErrVolumeNotMounted) {
+					log.Error("Backup completed with an error", "error", err)
+					ReportErrorf("Backup completed, but %v", err)
+
+					return
+				}
+
 				log.Error("Snapshot creation failed", "error", err)
 				ReportErrorf("Snapshot creation failed: %v", err)
 			})
@@ -106,8 +141,13 @@ on Linux), then /etc/vaultik/config.yml.`,
 	cmd.Flags().BoolVar(&opts.Cron, "cron", false,
 		"Run in cron mode (silent unless warning or error)")
 	cmd.Flags().BoolVar(&opts.Prune, "prune", false,
-		"After backup, drop older snapshots of the same name and remove "+
+		"After backup, drop older snapshots of the same name, remove "+
-			"orphaned blobs")
+			"orphaned blobs older than prune_grace_period, and delete each "+
+			"directory under metadata/ with no manifest once all its "+
+			"objects are older than prune_grace_period and its snapshot is "+
+			"not in the local index (not after a backup that skipped "+
+			"unreadable files, found a configured path empty, or did not "+
+			"find a mount point an earlier snapshot found)")
 	cmd.Flags().StringVar(&opts.KeepNewerThan, "keep-newer-than", "",
 		"With --prune: keep snapshots newer than this duration "+
 			"(e.g. 30d, 4w, 6mo, 1y; m is minutes, mo is months) "+
@@ -124,8 +164,15 @@ func newSnapshotListCommand() *cobra.Command {
 		Use:     "list",
 		Aliases: []string{"ls"},
 		Short:   "List all snapshots",
-		Long:    "Lists all snapshots with their ID, timestamp, and compressed size",
+		Long: `Lists the snapshots in the local index and on the backup destination
-		Args:    cobra.NoArgs,
+store, with their ID, timestamp, and sizes.
+
+Needs permission to list and read the destination store. It does not need
+the age private key. A snapshot found only on the destination store is
+listed by its remote key, because its ID is stored only in the local index
+and in the snapshot's encrypted database. If the destination store cannot
+be listed, the command warns and lists the local index alone.`,
+		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return runVaultikApp(cmd, readOnly, false,
 				"Failed to list snapshots",
@@ -147,11 +194,19 @@ func newSnapshotPurgeCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "purge",
 		Short: "Purge old snapshots",
-		Long: `Removes snapshots based on age or count criteria.
+		Long: `Removes snapshots based on age or count criteria. Exactly one of
+--keep-latest and --older-than is required.
 
-Retention is per-snapshot-name: --keep-latest keeps the latest of each
+Retention is per-snapshot-name: --keep-latest keeps the latest snapshot of
-configured snapshot name, not the latest globally. Use --snapshot to
+each name, not the latest globally. Use --snapshot to restrict the
-restrict the operation to specific snapshot names.`,
+operation to specific snapshot names.
+
+Only snapshots in the local index are removed. Each one is removed from
+the local index and its metadata is deleted from the backup destination
+store. Blobs are not touched: run 'vaultik prune' afterwards.
+
+Needs permission to list and delete objects on the destination store. If
+the destination store cannot be listed, nothing is removed.`,
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			// Validate flags
@@ -190,14 +245,29 @@ func newSnapshotVerifyCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "verify <snapshot-id>",
 		Short: "Check a snapshot's blobs are present with the listed size",
-		Long: "Checks that every blob the snapshot's manifest lists is present\n" +
+		Long: `Checks that every blob the snapshot's manifest lists is present
-			"in storage with the size the manifest records, and that the\n" +
+in storage with the size the manifest records, and that the
-			"snapshot's encrypted database is present. It does not read blob\n" +
+snapshot's encrypted database is present. It does not read blob
-			"contents; use --deep to download, decrypt, and re-hash every blob\n" +
+contents and does not need the age private key.
-			"to detect corruption -- integrity, not who wrote it.\n\n" +
+
-			"The snapshot may be named by its ID or, on a host with no local\n" +
+Needs permission to read the backup destination store, and to list it
-			"index, by the remote key that 'snapshot list' prints for a\n" +
+when a remote key is given.
-			"remote-only snapshot (an unambiguous leading part is enough).",
+
+Use --deep to download, decrypt, and re-hash every blob to detect
+corruption -- integrity, not who wrote it.
+
+--deep requires the age private key, in the VAULTIK_AGE_SECRET_KEY
+environment variable or as age_secret_key in the config file; the
+environment variable wins. The variable may hold the whole age-keygen
+file, with its comments and all of its keys. Read the key from the
+file rather than typing it, so that it does not land in your shell
+history:
+
+  export VAULTIK_AGE_SECRET_KEY="$(cat vaultik_backup_private_key.txt)"
+
+The snapshot may be named by its ID or, on a host with no local
+index, by the remote key that 'snapshot list' prints for a
+remote-only snapshot (an unambiguous leading part is enough).`,
 		Args: requireSnapshotIDArg,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			snapshotID := args[0]
@@ -232,7 +302,10 @@ func newSnapshotVerifyCommand() *cobra.Command {
 		},
 	}
 
-	cmd.Flags().BoolVar(&opts.Deep, "deep", false, "Download and verify blob hashes")
+	cmd.Flags().BoolVar(&opts.Deep, "deep", false,
+		"Download, decrypt and re-hash every blob; requires the age private "+
+			"key in VAULTIK_AGE_SECRET_KEY, or as age_secret_key in the config "+
+			"file")
 	cmd.Flags().BoolVar(&opts.JSON, "json", false, "Output verification results as JSON")
 
 	return cmd
@@ -252,16 +325,25 @@ 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.
+
+The argument must be a snapshot ID: a remote key is not accepted. An ID
+that names no snapshot in the local index or on the destination store is
+an error. Needs permission to list and delete objects on the destination
+store, unless --local-only is given.
 
 Use --local-only to skip the remote half (e.g. when you want to forget a
-snapshot locally without touching the destination store).
+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.`,
@@ -280,7 +362,8 @@ nuke --force' — it is the single supported entry point for that.`,
 	cmd.Flags().BoolVarP(&opts.Force, "force", "f", false, "Skip confirmation prompt")
 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false,
 		"Show what would be removed without removing")
-	cmd.Flags().BoolVar(&opts.JSON, "json", false, "Output result as JSON")
+	cmd.Flags().BoolVar(&opts.JSON, "json", false,
+		"Output result as JSON; skips the confirmation prompt, as --force does")
 	cmd.Flags().BoolVar(&opts.LocalOnly, "local-only", false,
 		"Skip remote cleanup; only touch the local index")
 

internal/cli/snapshot_restore.go

@@ -30,18 +30,28 @@ This command will restore files from the specified snapshot to the
 target directory.
 If no paths are specified, all files are restored.
 If paths are specified, only matching files/directories are restored.
+A path that matches nothing in the snapshot is named in a warning, and
+the command exits non-zero after restoring the paths that match.
 
 The snapshot may be named by its ID or, when restoring on a host with no
 local index, by the remote key that 'snapshot list' prints for a
 remote-only snapshot (an unambiguous leading part is enough).
 
-Requires the age private key in the VAULTIK_AGE_SECRET_KEY environment
+Each file is restored under its original absolute path inside the target
-variable. The variable may hold the whole age-keygen file (comments and
+directory. File owners are restored only when the command runs as root.
-all of its identities are accepted); read it from the file rather than
+
-typing the key, so it does not land in your shell history:
+Requires the age private key, in the VAULTIK_AGE_SECRET_KEY environment
+variable or as age_secret_key in the config file; the environment
+variable wins. The variable may hold the whole age-keygen file, with its
+comments and all of its keys. Read the key from the file rather than
+typing it, so that it does not land in your shell history:
 
   export VAULTIK_AGE_SECRET_KEY="$(cat vaultik_backup_private_key.txt)"
 
+Also needs permission to read the backup destination store (and to list
+it when a remote key is given), and free space in the temporary directory
+for the decrypted blobs.
+
 Examples:
   # Restore entire snapshot
   vaultik snapshot restore myhost_docs_2025-01-01T12:00:00Z /restore

internal/config/config.go

@@ -4,12 +4,14 @@
 package config
 
 import (
+	"bytes"
 	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
 	"sort"
 	"strings"
+	"time"
 
 	"filippo.io/age"
 	"git.eeqj.de/sneak/smartconfig"
@@ -29,13 +31,16 @@ const appName = "vaultik"
 //nolint:gosec // G101: marker for detecting a pasted secret key, not a credential
 const secretKeyPrefix = "AGE-SECRET-KEY-"
 
-// Defaults and validation bounds for tunable settings.
+// Defaults and validation bounds for tunable settings. MB and GB are
+// 1000-based, as the size parser reads them; the S3 part sizes are S3's own
+// limits, which are 1024-based (MiB, GiB).
 const (
-	defaultBlobSizeLimit    = Size(10 * 1024 * 1024 * 1024) // 10GB
+	defaultBlobSizeLimit    = Size(10 * 1000 * 1000 * 1000) // 10GB
-	defaultChunkSize        = Size(10 * 1024 * 1024)        // 10MB
+	defaultChunkSize        = Size(10 * 1000 * 1000)        // 10MB
 	defaultS3PartSize       = Size(5 * 1024 * 1024)         // 5MiB
 	defaultCompressionLevel = 3
-	minChunkSize            = 1024 * 1024 // 1MB
+	defaultPruneGracePeriod = 24 * time.Hour
+	minChunkSize            = 1000 * 1000 // 1MB
 	minCompressionLevel     = 1
 	maxCompressionLevel     = 19
 	// S3 accepts a multipart upload part from 5MiB to 5GiB.
@@ -61,6 +66,11 @@ var (
 	errBadS3PartSize    = errors.New("s3.part_size must be between 5MiB and 5GiB")
 	errBadStorageScheme = errors.New(
 		"storage_url must start with s3://, file://, or rclone://")
+	errFileURLNotAbsolute = errors.New(
+		"a file:// storage_url needs an absolute path, " +
+			"as in file:///path/to/backup")
+	errNegativePruneGracePeriod = errors.New(
+		"prune_grace_period must not be negative")
 	errStorageNotConfigured = errors.New(
 		"storage not configured; set storage_url or provide s3.endpoint + " +
 			"s3.bucket + credentials")
@@ -181,6 +191,15 @@ type Config struct {
 	Snapshots        map[string]SnapshotConfig `yaml:"snapshots"`
 	CompressionLevel int                       `yaml:"compression_level"`
 
+	// PruneGracePeriod is how old a blob no manifest lists must be before
+	// a prune deletes it, and how old every object in a directory under
+	// metadata/ with no manifest must be before a prune deletes that
+	// directory. A backup writes its manifest only once it has uploaded
+	// all its blobs and its db.zst.age, so a younger blob or directory may
+	// belong to a backup still running, on this host or another sharing
+	// the destination store.
+	PruneGracePeriod time.Duration `yaml:"prune_grace_period"`
+
 	// StorageURL specifies the storage backend using a URL format.
 	// Takes precedence over S3Config if set.
 	// Supported formats:
@@ -230,14 +249,48 @@ func New(path Path) (*Config, error) {
 	return cfg, nil
 }
 
-// Load reads and parses the configuration file from the specified path.
+// Load reads the configuration file at path, parses it with Parse, warns
-// It applies default values for optional fields, performs environment variable
+// when others can read the file, and validates the configuration.
-// substitution using smartconfig, and validates the configuration.
+// Returns an error if the file cannot be read, parsed, or if validation
-// The configuration file should be in YAML format. Returns an error if the file
+// fails.
-// cannot be read, parsed, or if validation fails.
 func Load(path string) (*Config, error) {
+	data, err := os.ReadFile(path) //nolint:gosec // G304: config path is operator-supplied
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config file: %w", err)
+	}
+
+	cfg, err := Parse(data)
+	if err != nil {
+		return nil, err
+	}
+
+	// Check config file permissions (warn if world or group readable)
+	//nolint:gosec // G703: config path is operator-supplied by design
+	info, statErr := os.Stat(path)
+	if statErr == nil {
+		mode := info.Mode().Perm()
+		if mode&0044 != 0 { // group or world readable
+			log.Warn(cfg.readableByOthersWarning(),
+				"path", path,
+				"mode", fmt.Sprintf("%04o", mode),
+				"recommendation", "chmod 600 "+path)
+		}
+	}
+
+	err = cfg.Validate()
+	if err != nil {
+		return nil, fmt.Errorf("invalid config: %w", err)
+	}
+
+	return cfg, nil
+}
+
+// Parse reads YAML config data as Load does, without validating it. It
+// applies default values for optional fields, fills in ${...} references
+// using smartconfig, and expands ~ in paths.
+func Parse(data []byte) (*Config, error) {
 	// Load config using smartconfig for interpolation
-	sc, err := smartconfig.NewFromConfigPath(path)
+	sc, err := smartconfig.NewFromReader(bytes.NewReader(data))
 	if err != nil {
 		return nil, fmt.Errorf("failed to load config file: %w", err)
 	}
@@ -248,6 +301,7 @@ func Load(path string) (*Config, error) {
 		ChunkSize:        defaultChunkSize,
 		IndexPath:        filepath.Join(xdg.DataHome, appName, "index.sqlite"),
 		CompressionLevel: defaultCompressionLevel,
+		PruneGracePeriod: defaultPruneGracePeriod,
 		S3:               S3Config{PartSize: defaultS3PartSize},
 	}
 
@@ -299,24 +353,6 @@ func Load(path string) (*Config, error) {
 		cfg.S3.Region = "us-east-1"
 	}
 
-	// Check config file permissions (warn if world or group readable)
-	//nolint:gosec // G703: config path is operator-supplied by design
-	info, statErr := os.Stat(path)
-	if statErr == nil {
-		mode := info.Mode().Perm()
-		if mode&0044 != 0 { // group or world readable
-			log.Warn(cfg.readableByOthersWarning(),
-				"path", path,
-				"mode", fmt.Sprintf("%04o", mode),
-				"recommendation", "chmod 600 "+path)
-		}
-	}
-
-	err = cfg.Validate()
-	if err != nil {
-		return nil, fmt.Errorf("invalid config: %w", err)
-	}
-
 	return cfg, nil
 }
 
@@ -334,6 +370,7 @@ func Load(path string) (*Config, error) {
 //     exceeds the configured limit
 //   - Compression level must be between 1 and 19
 //   - S3 part size must be between 5MiB and 5GiB, the part sizes S3 accepts
+//   - Prune grace period must not be negative
 //
 // Returns an error describing the first validation failure encountered.
 func (c *Config) Validate() error {
@@ -383,6 +420,10 @@ func (c *Config) Validate() error {
 		return errBadS3PartSize
 	}
 
+	if c.PruneGracePeriod < 0 {
+		return errNegativePruneGracePeriod
+	}
+
 	return nil
 }
 
@@ -461,11 +502,18 @@ func (c *Config) validateStorage() error {
 
 // validateStorageURL validates URL-based storage configuration. File and
 // rclone URLs need no credentials; S3 URLs require the legacy s3.*
-// credential fields.
+// credential fields. A file URL must name an absolute path: a relative one
+// would resolve against the working directory, so the destination would
+// move with it.
 func (c *Config) validateStorageURL() error {
 	switch {
 	case strings.HasPrefix(c.StorageURL, "file://"):
-		// File storage doesn't need S3 credentials
+		// storage.ParseStorageURL applies the same rule, but config
+		// cannot import storage, which imports config.
+		if !strings.HasPrefix(c.StorageURL, "file:///") {
+			return errFileURLNotAbsolute
+		}
+
 		return nil
 	case strings.HasPrefix(c.StorageURL, "rclone://"):
 		// Rclone storage uses rclone's own config

internal/config/config_test.go

@@ -6,6 +6,7 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"
 
 	"sneak.berlin/go/vaultik/internal/chunker"
 	"sneak.berlin/go/vaultik/internal/log"
@@ -337,6 +338,178 @@ func TestLoadS3PartSize(t *testing.T) {
 	})
 }
 
+// TestDocumentedSizeDefaults checks that the defaults are the documented
+// chunk_size 10MB and blob_size_limit 10GB as the parser reads those values
+// (1000-based), so writing a default out in the config file changes nothing.
+func TestDocumentedSizeDefaults(t *testing.T) {
+	t.Parallel()
+
+	cfg, err := Parse([]byte("chunk_size: 10MB\nblob_size_limit: 10GB\n"))
+	if err != nil {
+		t.Fatalf("Parse() unexpected error: %v", err)
+	}
+
+	if cfg.ChunkSize != defaultChunkSize {
+		t.Errorf("chunk_size: 10MB is %d bytes, the default is %d",
+			cfg.ChunkSize, defaultChunkSize)
+	}
+
+	if cfg.BlobSizeLimit != defaultBlobSizeLimit {
+		t.Errorf("blob_size_limit: 10GB is %d bytes, the default is %d",
+			cfg.BlobSizeLimit, defaultBlobSizeLimit)
+	}
+}
+
+// TestDocumentedSizeExamples checks the 1MB minimum chunk_size and that
+// every size the README, config.example.yml and the config init template
+// list as an example is accepted.
+func TestDocumentedSizeExamples(t *testing.T) {
+	t.Parallel()
+
+	const withoutSizes = "snapshots:\n" +
+		"  test:\n" +
+		"    paths: [/tmp/vaultik-test-source]\n" +
+		"storage_url: file:///tmp/vaultik-test-storage\n"
+
+	tests := []struct {
+		setting string
+		wantErr error
+	}{
+		{"chunk_size: 1MB", nil},
+		{"chunk_size: 999999", errChunkSizeTooSmall},
+		{"chunk_size: 5M", nil},
+		{"chunk_size: 10M", nil},
+		{"chunk_size: 10MB", nil},
+		{"chunk_size: 64MiB", nil},
+		{"chunk_size: 1GB", nil},
+		// Four times the default chunk_size, the documented minimum.
+		{"blob_size_limit: 40MB", nil},
+		{"blob_size_limit: 500MB", nil},
+		{"blob_size_limit: 1GB", nil},
+		{"blob_size_limit: 1GiB", nil},
+		{"blob_size_limit: 10G", nil},
+		{"blob_size_limit: 10GB", nil},
+		{"s3: {part_size: 5MiB}", nil},
+		{"s3: {part_size: 10MB}", nil},
+		{"s3: {part_size: 16MiB}", nil},
+		{"s3: {part_size: 100MiB}", nil},
+		{"s3: {part_size: 5GiB}", nil},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.setting, func(t *testing.T) {
+			t.Parallel()
+
+			cfg, err := Parse([]byte(withoutSizes + tt.setting + "\n"))
+			if err != nil {
+				t.Fatalf("Parse() unexpected error: %v", err)
+			}
+
+			err = cfg.Validate()
+			if !errors.Is(err, tt.wantErr) {
+				t.Fatalf("Validate() error = %v, want %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+// TestValidatePruneGracePeriod checks that a negative prune_grace_period
+// is refused rather than acting like 0s, which deletes unreferenced blobs
+// and directories under metadata/ with no manifest at once, and that 0s
+// and the documented examples are accepted.
+func TestValidatePruneGracePeriod(t *testing.T) {
+	t.Parallel()
+
+	const withoutGracePeriod = "snapshots:\n" +
+		"  test:\n" +
+		"    paths: [/tmp/vaultik-test-source]\n" +
+		"storage_url: file:///tmp/vaultik-test-storage\n"
+
+	tests := []struct {
+		setting string
+		wantErr error
+	}{
+		{"prune_grace_period: 0s", nil},
+		{"prune_grace_period: 90m", nil},
+		{"prune_grace_period: 36h", nil},
+		{"prune_grace_period: -1h", errNegativePruneGracePeriod},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.setting, func(t *testing.T) {
+			t.Parallel()
+
+			cfg, err := Parse([]byte(withoutGracePeriod + tt.setting + "\n"))
+			if err != nil {
+				t.Fatalf("Parse() unexpected error: %v", err)
+			}
+
+			err = cfg.Validate()
+			if !errors.Is(err, tt.wantErr) {
+				t.Fatalf("Validate() error = %v, want %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+// TestLoadPruneGracePeriod checks that a config file without
+// prune_grace_period loads with the documented 24h. The value is written out
+// here rather than taken from defaultPruneGracePeriod, so that a change of the
+// default fails this test.
+func TestLoadPruneGracePeriod(t *testing.T) {
+	t.Parallel()
+
+	const withoutGracePeriod = "snapshots:\n" +
+		"  test:\n" +
+		"    paths: [/tmp/vaultik-test-source]\n" +
+		"storage_url: file:///tmp/vaultik-test-storage\n"
+
+	path := filepath.Join(t.TempDir(), "config.yml")
+
+	err := os.WriteFile(path, []byte(withoutGracePeriod), 0o600)
+	if err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load() unexpected error: %v", err)
+	}
+
+	if cfg.PruneGracePeriod != 24*time.Hour {
+		t.Errorf("prune_grace_period = %s, want 24h", cfg.PruneGracePeriod)
+	}
+}
+
+// TestLoadRejectsRelativeFileURL checks that a file:// storage_url with a
+// relative path fails at load. Accepted, it would resolve against the
+// working directory, so a backup run from another directory would write
+// to a different destination and still succeed.
+func TestLoadRejectsRelativeFileURL(t *testing.T) {
+	t.Parallel()
+
+	const relativeConfig = "snapshots:\n" +
+		"  test:\n" +
+		"    paths: [/tmp/vaultik-test-source]\n" +
+		"storage_url: file://dest\n"
+
+	path := filepath.Join(t.TempDir(), "config.yml")
+
+	err := os.WriteFile(path, []byte(relativeConfig), 0o600)
+	if err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	_, err = Load(path)
+	if !errors.Is(err, errFileURLNotAbsolute) {
+		t.Fatalf("Load() error = %v, want errFileURLNotAbsolute", err)
+	}
+
+	if !strings.Contains(err.Error(), "absolute path") {
+		t.Errorf("error %q does not say to use an absolute path", err.Error())
+	}
+}
+
 // TestValidateAgeRecipients checks that recipients are parsed at config load
 // (a bad entry fails immediately, not mid-backup) and that no invalid entry —
 // least of all a pasted secret key — is echoed in the error. An empty list

internal/database/blob_chunks.go

@@ -58,12 +58,7 @@ func (r *BlobChunkRepository) GetByBlobID(
 		return nil, fmt.Errorf("querying blob chunks: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	var blobChunks []*BlobChunk
 

internal/database/blobs.go

@@ -83,12 +83,7 @@ func (r *BlobRepository) GetAll(ctx context.Context) (map[string]*Blob, error) {
 		return nil, fmt.Errorf("querying blobs: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	out := make(map[string]*Blob)
 
@@ -159,13 +154,16 @@ func (r *BlobRepository) UpdateFinished(
 	return nil
 }
 
-// UpdateUploaded marks a blob as uploaded
+// UpdateUploaded marks a blob as uploaded and records the size of the
+// stored object as its compressed size. That size can differ from the
+// local copy's when an identical blob was already stored with another
+// compression level or other recipients.
 func (r *BlobRepository) UpdateUploaded(
-	ctx context.Context, tx *sql.Tx, id string,
+	ctx context.Context, tx *sql.Tx, id string, storedSize int64,
 ) error {
 	query := `
-		UPDATE blobs 
+		UPDATE blobs
-		SET uploaded_ts = ?
+		SET uploaded_ts = ?, compressed_size = ?
 		WHERE id = ?
 	`
 
@@ -173,9 +171,9 @@ func (r *BlobRepository) UpdateUploaded(
 
 	var err error
 	if tx != nil {
-		_, err = tx.ExecContext(ctx, query, now, id)
+		_, err = tx.ExecContext(ctx, query, now, storedSize, id)
 	} else {
-		_, err = r.db.ExecWithLog(ctx, query, now, id)
+		_, err = r.db.ExecWithLog(ctx, query, now, storedSize, id)
 	}
 
 	if err != nil {

internal/database/blobs_test.go

@@ -122,8 +122,8 @@ func TestBlobRepositoryUpdates(t *testing.T) {
 		t.Errorf("expected compressed size 500, got %d", updated.CompressedSize)
 	}
 
-	// Test UpdateUploaded
+	// Test UpdateUploaded, with a stored object larger than the local copy
-	err = repo.UpdateUploaded(ctx, nil, blob.ID.String())
+	err = repo.UpdateUploaded(ctx, nil, blob.ID.String(), 600)
 	if err != nil {
 		t.Fatalf("failed to update blob as uploaded: %v", err)
 	}
@@ -141,6 +141,10 @@ func TestBlobRepositoryUpdates(t *testing.T) {
 	if uploaded.UploadedTS.Before(now.Add(-1 * time.Second)) {
 		t.Error("uploaded timestamp should be around test time")
 	}
+
+	if uploaded.CompressedSize != 600 {
+		t.Errorf("expected the stored size 600, got %d", uploaded.CompressedSize)
+	}
 }
 
 func TestBlobRepositoryDuplicate(t *testing.T) {

internal/database/chunk_files.go

@@ -61,12 +61,7 @@ func (r *ChunkFileRepository) GetByChunkHash(
 		return nil, fmt.Errorf("querying chunk files: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	return r.scanChunkFiles(rows)
 }
@@ -87,12 +82,7 @@ func (r *ChunkFileRepository) GetByFilePath(
 		return nil, fmt.Errorf("querying chunk files: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	return r.scanChunkFiles(rows)
 }
@@ -112,12 +102,7 @@ func (r *ChunkFileRepository) GetByFileID(
 		return nil, fmt.Errorf("querying chunk files: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	return r.scanChunkFiles(rows)
 }

internal/database/chunks.go

@@ -107,12 +107,7 @@ func (r *ChunkRepository) GetByHashes(
 		return nil, fmt.Errorf("querying chunks: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	var chunks []*Chunk
 
@@ -152,12 +147,7 @@ func (r *ChunkRepository) ListUnpacked(
 		return nil, fmt.Errorf("querying unpacked chunks: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	var chunks []*Chunk
 

internal/database/chunks_ext.go

@@ -38,12 +38,7 @@ func (r *ChunkRepository) list(ctx context.Context, query string) ([]*Chunk, err
 		return nil, fmt.Errorf("querying chunks: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	var chunks []*Chunk
 

internal/database/errors.go

@@ -1,12 +0,0 @@
-package database
-
-import (
-	"fmt"
-	"os"
-)
-
-// Fatalf prints an error message to stderr and exits with status 1
-func Fatalf(format string, args ...any) {
-	fmt.Fprintf(os.Stderr, "FATAL: "+format+"\n", args...)
-	os.Exit(1)
-}

internal/database/file_chunks.go

@@ -62,12 +62,7 @@ func (r *FileChunkRepository) GetByPath(
 		return nil, fmt.Errorf("querying file chunks: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	return r.scanFileChunks(rows)
 }
@@ -88,12 +83,7 @@ func (r *FileChunkRepository) GetByFileID(
 		return nil, fmt.Errorf("querying file chunks: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	return r.scanFileChunks(rows)
 }
@@ -117,12 +107,7 @@ func (r *FileChunkRepository) GetByPathTx(
 		return nil, fmt.Errorf("querying file chunks: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	fileChunks, err := r.scanFileChunks(rows)
 	LogSQL("GetByPathTx", "Complete", path, "count", len(fileChunks))

internal/database/files.go

@@ -175,12 +175,7 @@ func (r *FileRepository) ListModifiedSince(
 		return nil, fmt.Errorf("querying files: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	var files []*File
 
@@ -256,12 +251,46 @@ func (r *FileRepository) ListUnderPath(
 		return nil, fmt.Errorf("querying files: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
+
+	var files []*File
+
+	for rows.Next() {
+		file, err := r.scanFileRows(rows)
 		if err != nil {
-			Fatalf("failed to close rows: %v", err)
+			return nil, fmt.Errorf("scanning file: %w", err)
 		}
-	}()
+
+		files = append(files, file)
+	}
+
+	return files, rows.Err()
+}
+
+// ListUnderPathInSnapshot returns the files that ListUnderPath returns
+// for path and that the snapshot lists, in no particular order.
+func (r *FileRepository) ListUnderPathInSnapshot(
+	ctx context.Context, path, snapshotID string,
+) ([]*File, error) {
+	path = strings.TrimRight(path, "/")
+	dirPrefix := path + "/"
+
+	query := `
+		SELECT f.id, f.path, f.source_path, f.mtime, f.mtime_nsec, f.size,
+			f.mode, f.uid, f.gid, f.link_target
+		FROM files f
+		JOIN snapshot_files sf ON sf.file_id = f.id
+		WHERE sf.snapshot_id = ?
+		  AND (f.path = ? OR substr(f.path, 1, length(?)) = ?)
+	`
+
+	rows, err := r.db.conn.QueryContext(ctx, query,
+		snapshotID, path, dirPrefix, dirPrefix)
+	if err != nil {
+		return nil, fmt.Errorf("querying files: %w", err)
+	}
+
+	defer func() { _ = rows.Close() }()
 
 	var files []*File
 
@@ -304,12 +333,7 @@ func (r *FileRepository) ListIDsWithChunksNotInUploadedBlobs(
 		return nil, fmt.Errorf("querying files: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	var ids []types.FileID
 
@@ -340,12 +364,7 @@ func (r *FileRepository) ListAll(ctx context.Context) ([]*File, error) {
 		return nil, fmt.Errorf("querying files: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	var files []*File
 

internal/database/files_test.go

@@ -212,6 +212,65 @@ func TestFileRepositoryListUnderPath(t *testing.T) {
 	}
 }
 
+// ListUnderPathInSnapshot leaves out files outside path and files the
+// snapshot does not list, though another snapshot lists them.
+func TestFileRepositoryListUnderPathInSnapshot(t *testing.T) {
+	t.Parallel()
+
+	db, cleanup := setupTestDB(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	files := database.NewFileRepository(db)
+	snapshots := database.NewSnapshotRepository(db)
+
+	listed := map[string][]string{
+		"one": {"/src/a.txt", "/src2/c.txt"},
+		"two": {"/src/b.txt"},
+	}
+
+	for snapshotID, paths := range listed {
+		err := snapshots.Create(ctx, nil, &database.Snapshot{
+			ID:        types.SnapshotID(snapshotID),
+			Hostname:  "host",
+			StartedAt: time.Now(),
+		})
+		if err != nil {
+			t.Fatalf("failed to create snapshot %s: %v", snapshotID, err)
+		}
+
+		for _, path := range paths {
+			err := files.Create(ctx, nil, &database.File{
+				Path:  types.FilePath(path),
+				MTime: time.Now().Truncate(time.Second),
+				Mode:  0644,
+			})
+			if err != nil {
+				t.Fatalf("failed to create %s: %v", path, err)
+			}
+
+			err = snapshots.AddFile(ctx, nil, snapshotID, path)
+			if err != nil {
+				t.Fatalf("failed to add %s to %s: %v", path, snapshotID, err)
+			}
+		}
+	}
+
+	found, err := files.ListUnderPathInSnapshot(ctx, "/src", "one")
+	if err != nil {
+		t.Fatalf("failed to list files: %v", err)
+	}
+
+	got := make([]string, 0, len(found))
+	for _, f := range found {
+		got = append(got, f.Path.String())
+	}
+
+	if !slices.Equal(got, []string{"/src/a.txt"}) {
+		t.Errorf("got %q, want only /src/a.txt", got)
+	}
+}
+
 func TestFileRepositorySymlink(t *testing.T) {
 	t.Parallel()
 

internal/database/repositories.go

@@ -3,6 +3,7 @@ package database
 import (
 	"context"
 	"database/sql"
+	"errors"
 	"fmt"
 )
 
@@ -60,22 +61,24 @@ func (r *Repositories) WithTx(ctx context.Context, fn TxFunc) error {
 
 	defer func() {
 		if p := recover(); p != nil {
-			rollbackErr := tx.Rollback()
+			// The panic is the failure to report, so a rollback error
-			if rollbackErr != nil {
+			// is dropped.
-				Fatalf("failed to rollback transaction: %v", rollbackErr)
+			_ = tx.Rollback()
-			}
 
 			panic(p)
-		} else if err != nil {
-			rollbackErr := tx.Rollback()
-			if rollbackErr != nil {
-				Fatalf("failed to rollback transaction: %v", rollbackErr)
-			}
 		}
 	}()
 
 	err = fn(ctx, tx)
 	if err != nil {
+		// Once ctx is cancelled, database/sql rolls the transaction
+		// back itself and Rollback returns sql.ErrTxDone.
+		rollbackErr := tx.Rollback()
+		if rollbackErr != nil && !errors.Is(rollbackErr, sql.ErrTxDone) {
+			return fmt.Errorf("%w; rolling back transaction: %w",
+				err, rollbackErr)
+		}
+
 		return err
 	}
 
@@ -103,22 +106,24 @@ func (r *Repositories) WithReadTx(ctx context.Context, fn TxFunc) error {
 
 	defer func() {
 		if p := recover(); p != nil {
-			rollbackErr := tx.Rollback()
+			// The panic is the failure to report, so a rollback error
-			if rollbackErr != nil {
+			// is dropped.
-				Fatalf("failed to rollback transaction: %v", rollbackErr)
+			_ = tx.Rollback()
-			}
 
 			panic(p)
-		} else if err != nil {
-			rollbackErr := tx.Rollback()
-			if rollbackErr != nil {
-				Fatalf("failed to rollback transaction: %v", rollbackErr)
-			}
 		}
 	}()
 
 	err = fn(ctx, tx)
 	if err != nil {
+		// Once ctx is cancelled, database/sql rolls the transaction
+		// back itself and Rollback returns sql.ErrTxDone.
+		rollbackErr := tx.Rollback()
+		if rollbackErr != nil && !errors.Is(rollbackErr, sql.ErrTxDone) {
+			return fmt.Errorf("%w; rolling back transaction: %w",
+				err, rollbackErr)
+		}
+
 		return err
 	}
 

internal/database/repositories_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"errors"
+	"strings"
 	"testing"
 	"time"
 
@@ -235,6 +236,125 @@ func TestRepositoriesTransactionRollback(t *testing.T) {
 	}
 }
 
+// When the context is cancelled during the body, database/sql rolls the
+// transaction back itself, so WithTx's own rollback finds it already
+// done. WithTx must return the body's error alone, without that rollback.
+func TestRepositoriesTransactionContextCancelled(t *testing.T) {
+	t.Parallel()
+
+	db, cleanup := setupTestDB(t)
+	defer cleanup()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	repos := database.NewRepositories(db)
+
+	err := repos.WithTx(ctx, func(ctx context.Context, tx *sql.Tx) error {
+		file := &database.File{
+			Path:  "/test/cancelled_file.txt",
+			MTime: time.Now().Truncate(time.Second),
+			Size:  1024,
+			Mode:  0644,
+			UID:   1000,
+			GID:   1000,
+		}
+
+		err := repos.Files.Create(ctx, tx, file)
+		if err != nil {
+			return err
+		}
+
+		cancel()
+
+		// database/sql rolls back from a goroutine of its own; wait
+		// until it has, so the test does not depend on that race.
+		for {
+			_, err = tx.ExecContext(context.WithoutCancel(ctx), "SELECT 1")
+			if errors.Is(err, sql.ErrTxDone) {
+				return ctx.Err()
+			}
+
+			time.Sleep(time.Millisecond)
+		}
+	})
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("expected context.Canceled, got: %v", err)
+	}
+
+	if errors.Is(err, sql.ErrTxDone) {
+		t.Fatalf("the already-done rollback was reported: %v", err)
+	}
+
+	file, err := repos.Files.GetByPath(
+		context.Background(), "/test/cancelled_file.txt",
+	)
+	if err != nil {
+		t.Fatalf("error checking for file: %v", err)
+	}
+
+	if file != nil {
+		t.Error("file should not exist after the cancelled transaction")
+	}
+}
+
+// A body that ends the transaction itself with ROLLBACK makes WithTx's
+// own rollback fail. WithTx must return that failure together with the
+// body's error.
+func TestRepositoriesTransactionRollbackFails(t *testing.T) {
+	t.Parallel()
+
+	db, cleanup := setupTestDB(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	repos := database.NewRepositories(db)
+
+	err := repos.WithTx(ctx, func(ctx context.Context, tx *sql.Tx) error {
+		_, err := tx.ExecContext(ctx, "ROLLBACK")
+		if err != nil {
+			return err
+		}
+
+		return errIntentionalRollback
+	})
+	if !errors.Is(err, errIntentionalRollback) {
+		t.Fatalf("expected the body's error, got: %v", err)
+	}
+
+	if !strings.Contains(err.Error(), "rolling back transaction") {
+		t.Errorf("expected the failed rollback in the error, got: %v", err)
+	}
+}
+
+// When the body ends the transaction itself with ROLLBACK and then
+// panics, WithTx's own rollback fails; the panic must still reach the
+// caller.
+func TestRepositoriesTransactionPanicRollbackFails(t *testing.T) {
+	t.Parallel()
+
+	db, cleanup := setupTestDB(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	repos := database.NewRepositories(db)
+
+	defer func() {
+		if recover() == nil {
+			t.Error("expected the body's panic to reach the caller")
+		}
+	}()
+
+	_ = repos.WithTx(ctx, func(ctx context.Context, tx *sql.Tx) error {
+		_, err := tx.ExecContext(ctx, "ROLLBACK")
+		if err != nil {
+			return err
+		}
+
+		panic(errIntentionalRollback)
+	})
+}
+
 func TestRepositoriesReadTransaction(t *testing.T) {
 	t.Parallel()
 
@@ -291,3 +411,41 @@ func TestRepositoriesReadTransaction(t *testing.T) {
 		t.Error("expected to retrieve file in read transaction")
 	}
 }
+
+// When the context is cancelled during a read transaction's body,
+// database/sql rolls the transaction back itself, so WithReadTx's own
+// rollback finds it already done. WithReadTx must return the body's error
+// alone, without that rollback.
+func TestRepositoriesReadTransactionContextCancelled(t *testing.T) {
+	t.Parallel()
+
+	db, cleanup := setupTestDB(t)
+	defer cleanup()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	repos := database.NewRepositories(db)
+
+	err := repos.WithReadTx(ctx, func(ctx context.Context, tx *sql.Tx) error {
+		cancel()
+
+		// database/sql rolls back from a goroutine of its own; wait
+		// until it has, so the test does not depend on that race.
+		for {
+			_, err := tx.ExecContext(context.WithoutCancel(ctx), "SELECT 1")
+			if errors.Is(err, sql.ErrTxDone) {
+				return ctx.Err()
+			}
+
+			time.Sleep(time.Millisecond)
+		}
+	})
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("expected context.Canceled, got: %v", err)
+	}
+
+	if errors.Is(err, sql.ErrTxDone) {
+		t.Fatalf("the already-done rollback was reported: %v", err)
+	}
+}

internal/database/schema/001.sql

@@ -86,8 +86,10 @@ CREATE TABLE IF NOT EXISTS snapshots (
     completed_at INTEGER,
     file_count INTEGER NOT NULL DEFAULT 0,
     chunk_count INTEGER NOT NULL DEFAULT 0,
+    new_chunk_size INTEGER NOT NULL DEFAULT 0,
     blob_count INTEGER NOT NULL DEFAULT 0,
     total_size INTEGER NOT NULL DEFAULT 0,
+    uncompressed_chunk_size INTEGER NOT NULL DEFAULT 0,
     blob_size INTEGER NOT NULL DEFAULT 0,
     blob_uncompressed_size INTEGER NOT NULL DEFAULT 0,
     compression_ratio REAL NOT NULL DEFAULT 1.0,
@@ -121,6 +123,16 @@ CREATE TABLE IF NOT EXISTS snapshot_blobs (
 -- Index for efficient blob lookups (used in orphan detection)
 CREATE INDEX IF NOT EXISTS idx_snapshot_blobs_blob_id ON snapshot_blobs(blob_id);
 
+-- Snapshot mount points table: the directories at or below a configured
+-- path that the snapshot's backup found on a different filesystem from
+-- their parent directory, as a mount point is, and found an entry in
+CREATE TABLE IF NOT EXISTS snapshot_mount_points (
+    snapshot_id TEXT NOT NULL,
+    path TEXT NOT NULL,
+    PRIMARY KEY (snapshot_id, path),
+    FOREIGN KEY (snapshot_id) REFERENCES snapshots(id) ON DELETE CASCADE
+);
+
 -- Uploads table: tracks blob upload metrics
 CREATE TABLE IF NOT EXISTS uploads (
     blob_hash TEXT PRIMARY KEY,

internal/database/snapshots.go

@@ -24,7 +24,8 @@ var (
 )
 
 // SnapshotRepository provides access to the snapshots table and its
-// snapshot_files / snapshot_blobs association tables.
+// snapshot_files / snapshot_blobs association tables, and to the mount
+// points each snapshot's backup found (snapshot_mount_points).
 type SnapshotRepository struct {
 	db *DB
 }
@@ -120,7 +121,11 @@ func (r *SnapshotRepository) UpdateCounts(
 	return nil
 }
 
-// UpdateExtendedStats updates extended statistics for a snapshot
+// UpdateExtendedStats updates extended statistics for a snapshot. It also
+// records the total plaintext size of the distinct chunks the snapshot's
+// files reference. Only the snapshot's own backup can take that total: a
+// file's row is shared by every snapshot that lists it, and a later
+// backup of a changed file rewrites the row with the new chunks.
 func (r *SnapshotRepository) UpdateExtendedStats(
 	ctx context.Context,
 	tx *sql.Tx,
@@ -129,6 +134,7 @@ func (r *SnapshotRepository) UpdateExtendedStats(
 	compressionLevel int,
 	uploadBytes int64,
 	uploadDurationMs int64,
+	newChunkSize int64,
 ) error {
 	compressionRatio, err := r.extendedCompressionRatio(
 		ctx, tx, snapshotID, blobUncompressedSize,
@@ -143,18 +149,29 @@ func (r *SnapshotRepository) UpdateExtendedStats(
 		    compression_ratio = ?,
 		    compression_level = ?,
 		    upload_bytes = ?,
-		    upload_duration_ms = ?
+		    upload_duration_ms = ?,
+		    new_chunk_size = ?,
+		    uncompressed_chunk_size = (
+		        SELECT COALESCE(SUM(c.size), 0)
+		        FROM (
+		            SELECT DISTINCT fc.chunk_hash
+		            FROM snapshot_files sf
+		            JOIN file_chunks fc ON sf.file_id = fc.file_id
+		            WHERE sf.snapshot_id = snapshots.id
+		        ) sc
+		        JOIN chunks c ON sc.chunk_hash = c.chunk_hash
+		    )
 		WHERE id = ?
 	`
 
 	if tx != nil {
 		_, err = tx.ExecContext(ctx, query,
 			blobUncompressedSize, compressionRatio, compressionLevel,
-			uploadBytes, uploadDurationMs, snapshotID)
+			uploadBytes, uploadDurationMs, newChunkSize, snapshotID)
 	} else {
 		_, err = r.db.ExecWithLog(ctx, query,
 			blobUncompressedSize, compressionRatio, compressionLevel,
-			uploadBytes, uploadDurationMs, snapshotID)
+			uploadBytes, uploadDurationMs, newChunkSize, snapshotID)
 	}
 
 	if err != nil {
@@ -239,12 +256,7 @@ func (r *SnapshotRepository) GetOnlySnapshot(ctx context.Context) (*Snapshot, er
 		return nil, fmt.Errorf("querying snapshots: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	snapshots, err := r.scanSnapshotRows(rows)
 	if err != nil {
@@ -279,12 +291,7 @@ func (r *SnapshotRepository) ListRecent(
 		return nil, fmt.Errorf("querying snapshots: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	return r.scanSnapshotRows(rows)
 }
@@ -488,38 +495,63 @@ func (r *SnapshotRepository) GetBlobHashes(
 	ctx context.Context, snapshotID string,
 ) ([]string, error) {
 	query := `
-		SELECT sb.blob_hash 
+		SELECT sb.blob_hash
 		FROM snapshot_blobs sb
 		WHERE sb.snapshot_id = ?
 		ORDER BY sb.blob_hash
 	`
 
-	rows, err := r.db.conn.QueryContext(ctx, query, snapshotID)
+	blobs, err := r.queryStrings(ctx, query, snapshotID)
 	if err != nil {
 		return nil, fmt.Errorf("querying blob hashes: %w", err)
 	}
 
-	defer func() {
+	return blobs, nil
-		err := rows.Close()
+}
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
-	var blobs []string
+// AddMountPoint records dir as a directory that the backup of a snapshot
+// found on a different filesystem from its parent directory, as a mount
+// point is, using tx when non-nil.
+func (r *SnapshotRepository) AddMountPoint(
+	ctx context.Context, tx *sql.Tx, snapshotID string, dir string,
+) error {
+	query := `
+		INSERT OR IGNORE INTO snapshot_mount_points (snapshot_id, path)
+		VALUES (?, ?)
+	`
 
-	for rows.Next() {
+	var err error
-		var blobHash string
+	if tx != nil {
-
+		_, err = tx.ExecContext(ctx, query, snapshotID, dir)
-		err := rows.Scan(&blobHash)
+	} else {
-		if err != nil {
+		_, err = r.db.ExecWithLog(ctx, query, snapshotID, dir)
-			return nil, fmt.Errorf("scanning blob hash: %w", err)
-		}
-
-		blobs = append(blobs, blobHash)
 	}
 
-	return blobs, rows.Err()
+	if err != nil {
+		return fmt.Errorf("adding mount point to snapshot: %w", err)
+	}
+
+	return nil
+}
+
+// GetMountPoints returns the directories AddMountPoint recorded for a
+// snapshot, sorted.
+func (r *SnapshotRepository) GetMountPoints(
+	ctx context.Context, snapshotID string,
+) ([]string, error) {
+	query := `
+		SELECT path
+		FROM snapshot_mount_points
+		WHERE snapshot_id = ?
+		ORDER BY path
+	`
+
+	dirs, err := r.queryStrings(ctx, query, snapshotID)
+	if err != nil {
+		return nil, fmt.Errorf("querying mount points: %w", err)
+	}
+
+	return dirs, nil
 }
 
 // GetSnapshotTotalCompressedSize returns the total compressed size of all
@@ -568,71 +600,42 @@ func (r *SnapshotRepository) GetSnapshotBlobSizes(
 	return compressed, uncompressed, nil
 }
 
-// GetSnapshotUncompressedChunkSize returns the sum of plaintext sizes of all unique
+// GetSnapshotUncompressedChunkSize returns the total plaintext size of the
-// chunks referenced by a snapshot (via snapshot_files → file_chunks → chunks).
+// distinct chunks the snapshot's files reference, as the snapshot's backup
+// recorded it (see UpdateExtendedStats).
 func (r *SnapshotRepository) GetSnapshotUncompressedChunkSize(
 	ctx context.Context, snapshotID string,
 ) (int64, error) {
-	query := `
+	query := `SELECT uncompressed_chunk_size FROM snapshots WHERE id = ?`
-		SELECT COALESCE(SUM(c.size), 0)
-		FROM (
-			SELECT DISTINCT fc.chunk_hash
-			FROM snapshot_files sf
-			JOIN file_chunks fc ON sf.file_id = fc.file_id
-			WHERE sf.snapshot_id = ?
-		) sc
-		JOIN chunks c ON sc.chunk_hash = c.chunk_hash
-	`
 
-	var totalSize int64
+	var uncompressedChunkSize int64
 
-	err := r.db.conn.QueryRowContext(ctx, query, snapshotID).Scan(&totalSize)
+	err := r.db.conn.QueryRowContext(ctx, query, snapshotID).Scan(&uncompressedChunkSize)
 	if err != nil {
 		return 0, fmt.Errorf("querying uncompressed chunk size: %w", err)
 	}
 
-	return totalSize, nil
+	return uncompressedChunkSize, nil
 }
 
-// GetSnapshotNewChunkSize returns the sum of plaintext sizes of chunks that are
+// GetSnapshotNewChunkSize returns the total plaintext size of the chunks the
-// referenced by this snapshot but not by any earlier completed snapshot known to
+// snapshot's backup stored that were not stored before, as the backup
-// the local database. The result is the marginal uncompressed data this snapshot
+// recorded it. It is not derived from the snapshot's files: a file's row is
-// added to the dedup pool — i.e., the delta from prior snapshots.
+// shared by every snapshot that lists it and is rewritten when the file
+// changes, so it shows only the file's latest chunks.
 func (r *SnapshotRepository) GetSnapshotNewChunkSize(
 	ctx context.Context, snapshotID string,
 ) (int64, error) {
-	query := `
+	query := `SELECT new_chunk_size FROM snapshots WHERE id = ?`
-		WITH this_snap_chunks AS (
-			SELECT DISTINCT fc.chunk_hash
-			FROM snapshot_files sf
-			JOIN file_chunks fc ON sf.file_id = fc.file_id
-			WHERE sf.snapshot_id = ?
-		),
-		prior_chunks AS (
-			SELECT DISTINCT fc.chunk_hash
-			FROM snapshots s
-			JOIN snapshot_files sf ON sf.snapshot_id = s.id
-			JOIN file_chunks fc ON fc.file_id = sf.file_id
-			WHERE s.completed_at IS NOT NULL
-			  AND s.id != ?
-			  AND s.started_at < (SELECT started_at FROM snapshots WHERE id = ?)
-		)
-		SELECT COALESCE(SUM(c.size), 0)
-		FROM chunks c
-		JOIN this_snap_chunks t ON c.chunk_hash = t.chunk_hash
-		WHERE c.chunk_hash NOT IN (SELECT chunk_hash FROM prior_chunks)
-	`
 
-	var totalSize int64
+	var newChunkSize int64
 
-	err := r.db.conn.QueryRowContext(
+	err := r.db.conn.QueryRowContext(ctx, query, snapshotID).Scan(&newChunkSize)
-		ctx, query, snapshotID, snapshotID, snapshotID,
-	).Scan(&totalSize)
 	if err != nil {
 		return 0, fmt.Errorf("querying new chunk size: %w", err)
 	}
 
-	return totalSize, nil
+	return newChunkSize, nil
 }
 
 // GetIncompleteSnapshots returns all snapshots that haven't been completed
@@ -653,12 +656,7 @@ func (r *SnapshotRepository) GetIncompleteSnapshots(
 		return nil, fmt.Errorf("querying incomplete snapshots: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	return r.scanSnapshotRows(rows)
 }
@@ -681,12 +679,7 @@ func (r *SnapshotRepository) GetIncompleteByHostname(
 		return nil, fmt.Errorf("querying incomplete snapshots: %w", err)
 	}
 
-	defer func() {
+	defer func() { _ = rows.Close() }()
-		err := rows.Close()
-		if err != nil {
-			Fatalf("failed to close rows: %v", err)
-		}
-	}()
 
 	// Same column set as every other multi-row snapshot query, so the
 	// shared scanner applies — including its timestamp normalization.
@@ -747,6 +740,34 @@ func (r *SnapshotRepository) DeleteSnapshotUploads(
 	return nil
 }
 
+// queryStrings runs query, which selects one text column, and returns
+// its values in the order of the rows.
+func (r *SnapshotRepository) queryStrings(
+	ctx context.Context, query string, args ...any,
+) ([]string, error) {
+	rows, err := r.db.conn.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, err
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	var values []string
+
+	for rows.Next() {
+		var value string
+
+		err := rows.Scan(&value)
+		if err != nil {
+			return nil, err
+		}
+
+		values = append(values, value)
+	}
+
+	return values, rows.Err()
+}
+
 // extendedCompressionRatio computes the compression ratio for a snapshot
 // from its stored blob_size and the given uncompressed size. Returns 1.0
 // when the uncompressed size is zero.

internal/database/snapshots_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"math"
+	"slices"
 	"testing"
 	"time"
 
@@ -422,3 +423,52 @@ func TestSnapshotRepositoryDuplicate(t *testing.T) {
 		t.Error("expected error for duplicate snapshot")
 	}
 }
+
+// Deleting a snapshot from the local index deletes the mount points its
+// backup recorded, and no other snapshot's. See
+// https://git.eeqj.de/sneak/vaultik/issues/395.
+func TestSnapshotRepositoryDeleteRemovesMountPoints(t *testing.T) {
+	t.Parallel()
+
+	db, cleanup := setupTestDB(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	repo := database.NewSnapshotRepository(db)
+
+	for _, id := range []types.SnapshotID{"kept", "deleted"} {
+		err := repo.Create(ctx, nil, &database.Snapshot{
+			ID:             id,
+			Hostname:       testHostname,
+			VaultikVersion: testVersion,
+			StartedAt:      time.Now().Truncate(time.Second),
+		})
+		if err != nil {
+			t.Fatalf("failed to create snapshot: %v", err)
+		}
+
+		err = repo.AddMountPoint(ctx, nil, id.String(), "/data/nas")
+		if err != nil {
+			t.Fatalf("failed to add mount point: %v", err)
+		}
+	}
+
+	err := repo.Delete(ctx, "deleted")
+	if err != nil {
+		t.Fatalf("failed to delete snapshot: %v", err)
+	}
+
+	for id, want := range map[string][]string{
+		"kept":    {"/data/nas"},
+		"deleted": nil,
+	} {
+		got, err := repo.GetMountPoints(ctx, id)
+		if err != nil {
+			t.Fatalf("failed to read mount points: %v", err)
+		}
+
+		if !slices.Equal(got, want) {
+			t.Errorf("mount points of %s: got %v, want %v", id, got, want)
+		}
+	}
+}

internal/log/tty_handler.go

@@ -10,6 +10,8 @@ import (
 	"sync"
 	"time"
 	"unicode"
+
+	"github.com/dustin/go-humanize"
 )
 
 // groupSeparator joins an open group path to an attribute key. This
@@ -304,18 +306,13 @@ func formatDuration(d time.Duration) string {
 	}
 }
 
-// formatBytes formats bytes in a human-readable way
+// formatBytes formats a byte count with humanize.Bytes, as every command
+// prints one. humanize.Bytes takes no negative count, so one is printed
+// as it is.
 func formatBytes(b int64) string {
-	const unit = 1024
+	if b < 0 {
-	if b < unit {
 		return fmt.Sprintf("%d B", b)
 	}
 
-	div, exp := int64(unit), 0
+	return humanize.Bytes(uint64(b))
-	for n := b / unit; n >= unit; n /= unit {
-		div *= unit
-		exp++
-	}
-
-	return fmt.Sprintf("%.1f %cB", float64(b)/float64(div), "KMGTPE"[exp])
 }

internal/log/tty_handler_test.go

@@ -200,7 +200,8 @@ func TestTTYHandlerWithGroupQualifiesKeys(t *testing.T) {
 func TestTTYHandlerByteFormattingSurvivesGrouping(t *testing.T) {
 	t.Parallel()
 
-	const oneAndAHalfKiB = 1536
+	// Printed as "1.0 MB", in powers of 1000 like every other byte count.
+	const oneMegabyte = 1_000_000
 
 	for name, testCase := range map[string]struct {
 		derive func(*slog.Logger) *slog.Logger
@@ -223,13 +224,13 @@ func TestTTYHandlerByteFormattingSurvivesGrouping(t *testing.T) {
 			var buf bytes.Buffer
 
 			logger := slog.New(log.NewTTYHandler(&buf, debugHandlerOptions()))
-			testCase.derive(logger).Info("uploaded", "bytes", oneAndAHalfKiB)
+			testCase.derive(logger).Info("uploaded", "bytes", oneMegabyte)
 
 			line := ansiEscape.ReplaceAllString(buf.String(), "")
 
-			assert.Contains(t, line, testCase.key+"=1.5 KB",
+			assert.Contains(t, line, testCase.key+"=1.0 MB",
 				"a byte count must be human-readable however it is qualified")
-			assert.NotContains(t, line, strconv.Itoa(oneAndAHalfKiB),
+			assert.NotContains(t, line, strconv.Itoa(oneMegabyte),
 				"the raw number must not survive the formatting")
 		})
 	}

internal/s3/client.go

@@ -8,6 +8,7 @@ import (
 	"io"
 	"strings"
 	"sync/atomic"
+	"time"
 
 	"github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/aws/aws-sdk-go-v2/config"
@@ -18,6 +19,13 @@ import (
 	"github.com/aws/smithy-go/logging"
 )
 
+// ErrNoContinuationToken is returned by ListObjects and ListObjectsStream
+// when the server marks a page of a listing truncated but sends no
+// continuation token to fetch the rest with, as a server answering V2
+// listings V1-style does.
+var ErrNoContinuationToken = errors.New(
+	"server marked the listing truncated but sent no continuation token")
+
 // Client wraps the AWS S3 client for vaultik operations.
 // It provides a simplified interface for S3 operations with automatic
 // prefix handling and connection management. All operations are performed
@@ -214,7 +222,7 @@ func (c *Client) ListObjects(ctx context.Context, prefix string) ([]string, erro
 	})
 
 	for paginator.HasMorePages() {
-		page, err := paginator.NextPage(ctx)
+		page, err := nextListPage(ctx, paginator)
 		if err != nil {
 			return nil, err
 		}
@@ -235,6 +243,26 @@ func (c *Client) ListObjects(ctx context.Context, prefix string) ([]string, erro
 	return keys, nil
 }
 
+// nextListPage fetches the next page of a listing. The SDK paginator takes
+// a page marked truncated without a continuation token for the last page
+// and stops without an error, so such a page is ErrNoContinuationToken
+// here instead.
+func nextListPage(
+	ctx context.Context, paginator *s3.ListObjectsV2Paginator,
+) (*s3.ListObjectsV2Output, error) {
+	page, err := paginator.NextPage(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	truncated := aws.ToBool(page.IsTruncated)
+	if truncated && aws.ToString(page.NextContinuationToken) == "" {
+		return nil, ErrNoContinuationToken
+	}
+
+	return page, nil
+}
+
 // HeadObject checks if an object exists in S3.
 // Returns true if the object exists, false otherwise.
 // The key is automatically prefixed with the configured prefix.
@@ -275,7 +303,10 @@ func IsNotFound(err error) bool {
 type ObjectInfo struct {
 	Key  string
 	Size int64
-	Err  error
+	// ModTime is the object's LastModified time. Only ListObjectsStream
+	// sets it.
+	ModTime time.Time
+	Err     error
 }
 
 // ListObjectsStream lists objects with the given prefix and returns a channel.
@@ -300,7 +331,7 @@ func (c *Client) ListObjectsStream(
 		})
 
 		for paginator.HasMorePages() {
-			page, err := paginator.NextPage(ctx)
+			page, err := nextListPage(ctx, paginator)
 			if err != nil {
 				ch <- ObjectInfo{Err: err}
 
@@ -316,8 +347,9 @@ func (c *Client) ListObjectsStream(
 					}
 
 					ch <- ObjectInfo{
-						Key:  key,
+						Key:     key,
-						Size: *obj.Size,
+						Size:    *obj.Size,
+						ModTime: aws.ToTime(obj.LastModified),
 					}
 				}
 			}

internal/snapshot/blob_temp_file_test.go

@@ -0,0 +1,62 @@
+//nolint:testpackage // exercises the unexported cleanupBlobTempFile
+package snapshot
+
+import (
+	"errors"
+	"os"
+	"testing"
+
+	"github.com/spf13/afero"
+	"sneak.berlin/go/vaultik/internal/blob"
+)
+
+// A blob temp file that cannot be closed or removed must make the cleanup
+// return an error, not end the process.
+func TestCleanupBlobTempFileReturnsErrors(t *testing.T) {
+	t.Parallel()
+
+	fs := afero.NewOsFs()
+	s := &Scanner{fs: fs}
+
+	tests := []struct {
+		name string
+		// prepare runs before the cleanup and makes its close or remove
+		// fail.
+		prepare func(tempFile afero.File) error
+		want    error
+	}{
+		{
+			name:    "close fails",
+			prepare: func(tempFile afero.File) error { return tempFile.Close() },
+			want:    os.ErrClosed,
+		},
+		{
+			name: "remove fails",
+			prepare: func(tempFile afero.File) error {
+				return fs.Remove(tempFile.Name())
+			},
+			want: os.ErrNotExist,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			tempFile, err := afero.TempFile(fs, t.TempDir(), "blob-*.tmp")
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			err = tt.prepare(tempFile)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			err = s.cleanupBlobTempFile(&blob.WithReader{TempFile: tempFile})
+			if !errors.Is(err, tt.want) {
+				t.Fatalf("expected an error wrapping %v, got: %v", tt.want, err)
+			}
+		})
+	}
+}

internal/snapshot/device_number_test.go

@@ -0,0 +1,40 @@
+//nolint:testpackage // exercises the unexported deviceNumberFromStat
+package snapshot
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// The device number a real backup reads is the same for a directory and
+// a file in it, and differs between the temp directory and /dev.
+// Without it no mount point is ever found. See
+// https://git.eeqj.de/sneak/vaultik/issues/395.
+func TestDeviceNumberFromStat(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	file := filepath.Join(dir, "file.txt")
+	require.NoError(t, os.WriteFile(file, nil, 0o600))
+
+	deviceOf := func(path string) uint64 {
+		t.Helper()
+
+		info, err := os.Stat(path)
+		require.NoError(t, err)
+
+		device, ok := deviceNumberFromStat(info)
+		require.True(t, ok, "no device number read for %s", path)
+
+		return device
+	}
+
+	assert.Equal(t, deviceOf(dir), deviceOf(file))
+
+	// /dev is a different filesystem from the temp dir on Linux, macOS and in Docker.
+	assert.NotEqual(t, deviceOf(dir), deviceOf("/dev"))
+}

internal/snapshot/exclude_test.go

@@ -531,3 +531,101 @@ func TestExcludePatterns_UnanchoredPatternFile(t *testing.T) {
 	require.Equal(t, 1, result.FilesScanned,
 		"Unanchored pattern for file should match anywhere")
 }
+
+func TestExcludePatterns_DoubleStarDirectoryAtEveryDepth(t *testing.T) {
+	t.Parallel()
+
+	// As in gitignore, a leading **/ also matches directly under the source dir
+	fs := setupAnchoredTestFS(t)
+
+	scanner, repos, cleanup := createTestScanner(t, fs, []string{"**/projectname"})
+	defer cleanup()
+
+	ctx := context.Background()
+	createSnapshotRecord(ctx, t, repos, "test-snapshot")
+
+	result, err := scanner.Scan(ctx, "/backup", "test-snapshot")
+	require.NoError(t, err)
+
+	// **/projectname should exclude BOTH:
+	// - /backup/projectname/file.txt
+	// - /backup/otherproject/projectname/file.txt
+	// Total files: 4, excluded: 2
+	require.Equal(t, 2, result.FilesScanned,
+		"**/ directory pattern should match at the top level and nested")
+}
+
+func TestExcludePatterns_DoubleStarFileAtEveryDepth(t *testing.T) {
+	t.Parallel()
+
+	// As in gitignore, a leading **/ also matches directly under the source dir
+	fs := setupAnchoredTestFS(t)
+
+	scanner, repos, cleanup := createTestScanner(t, fs, []string{"**/*.txt"})
+	defer cleanup()
+
+	ctx := context.Background()
+	createSnapshotRecord(ctx, t, repos, "test-snapshot")
+
+	result, err := scanner.Scan(ctx, "/backup", "test-snapshot")
+	require.NoError(t, err)
+
+	// **/*.txt should exclude ALL .txt files:
+	// - /backup/file.txt
+	// - /backup/projectname/file.txt
+	// - /backup/otherproject/projectname/file.txt
+	// Total files: 4, excluded: 3
+	require.Equal(t, 1, result.FilesScanned,
+		"**/ file pattern should match at the top level and nested")
+}
+
+func TestExcludePatterns_AnchoredDoubleStarAtEveryDepth(t *testing.T) {
+	t.Parallel()
+
+	// As in gitignore, /**/ also matches directly under the source dir
+	fs := setupAnchoredTestFS(t)
+
+	scanner, repos, cleanup := createTestScanner(t, fs, []string{"/**/projectname"})
+	defer cleanup()
+
+	ctx := context.Background()
+	createSnapshotRecord(ctx, t, repos, "test-snapshot")
+
+	result, err := scanner.Scan(ctx, "/backup", "test-snapshot")
+	require.NoError(t, err)
+
+	// /**/projectname should exclude BOTH:
+	// - /backup/projectname/file.txt
+	// - /backup/otherproject/projectname/file.txt
+	// Total files: 4, excluded: 2
+	require.Equal(t, 2, result.FilesScanned,
+		"/**/ pattern should match at the top level and nested")
+}
+
+func TestExcludePatterns_DoubleStarInMiddleMatchesZeroDirectories(t *testing.T) {
+	t.Parallel()
+
+	// As in gitignore, a/**/b matches a/b as well as a/c/b. The last part
+	// is a glob: with a plain name the glob library already matched a/b.
+	fs := &afero.MemMapFs{}
+	files := []string{"/backup/a/x.log", "/backup/a/c/y.log", "/backup/a/c/kept.txt"}
+
+	for _, path := range files {
+		require.NoError(t, fs.MkdirAll(filepath.Dir(path), 0755))
+		require.NoError(t, afero.WriteFile(fs, path, []byte(path), 0644))
+	}
+
+	scanner, repos, cleanup := createTestScanner(t, fs, []string{"a/**/*.log"})
+	defer cleanup()
+
+	ctx := context.Background()
+	createSnapshotRecord(ctx, t, repos, "test-snapshot")
+
+	result, err := scanner.Scan(ctx, "/backup", "test-snapshot")
+	require.NoError(t, err)
+
+	// a/**/*.log should exclude /backup/a/x.log and /backup/a/c/y.log
+	// Total files: 3, excluded: 2
+	require.Equal(t, 1, result.FilesScanned,
+		"a/**/*.log should match a/x.log as well as a/c/y.log")
+}

internal/snapshot/module.go

@@ -1,6 +1,8 @@
 package snapshot
 
 import (
+	"os"
+
 	"github.com/spf13/afero"
 	"go.uber.org/fx"
 	"sneak.berlin/go/vaultik/internal/config"
@@ -16,6 +18,12 @@ type ScannerParams struct {
 	Fs             afero.Fs
 	Exclude        []string // Exclude patterns (combined global + snapshot-specific)
 	SkipErrors     bool     // Skip file read errors (log loudly but continue)
+	// PreviousSnapshotID is the most recent completed snapshot of the
+	// same name, "" for none.
+	PreviousSnapshotID string
+	// DeviceNumber is ScannerConfig.DeviceNumber; nil reads it from the
+	// file's stat.
+	DeviceNumber func(info os.FileInfo) (uint64, bool)
 }
 
 // Module exports backup functionality as an fx module.
@@ -44,17 +52,19 @@ func provideScannerFactory(
 		}
 
 		return NewScanner(ScannerConfig{
-			FS:               params.Fs,
+			FS:                 params.Fs,
-			ChunkSize:        cfg.ChunkSize.Int64(),
+			ChunkSize:          cfg.ChunkSize.Int64(),
-			Repositories:     repos,
+			Repositories:       repos,
-			Storage:          storer,
+			Storage:            storer,
-			MaxBlobSize:      cfg.BlobSizeLimit.Int64(),
+			MaxBlobSize:        cfg.BlobSizeLimit.Int64(),
-			CompressionLevel: cfg.CompressionLevel,
+			CompressionLevel:   cfg.CompressionLevel,
-			AgeRecipients:    cfg.AgeRecipients,
+			AgeRecipients:      cfg.AgeRecipients,
-			EnableProgress:   params.EnableProgress,
+			EnableProgress:     params.EnableProgress,
-			UI:               params.UI,
+			UI:                 params.UI,
-			Exclude:          excludes,
+			Exclude:            excludes,
-			SkipErrors:       params.SkipErrors,
+			SkipErrors:         params.SkipErrors,
+			PreviousSnapshotID: params.PreviousSnapshotID,
+			DeviceNumber:       params.DeviceNumber,
 		})
 	}
 }

internal/snapshot/mount_point_test.go

@@ -0,0 +1,245 @@
+package snapshot_test
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"syscall"
+	"testing"
+
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/database"
+	"sneak.berlin/go/vaultik/internal/snapshot"
+)
+
+// A scan records with the snapshot each directory on a different device
+// from its parent directory that the walk found an entry in, as a mount
+// point is, the scanned path included. A filesystem that gives no device
+// numbers, as the in-memory one, records none. See
+// https://git.eeqj.de/sneak/vaultik/issues/395.
+func TestScanRecordsMountPoints(t *testing.T) {
+	t.Parallel()
+
+	const (
+		scannedPath = "/data/source"
+		snapshotID  = "mount-points"
+	)
+
+	tests := []struct {
+		name string
+		// onVolume names the directories on the volume's device; every
+		// other directory is on another one. nil leaves the device
+		// numbers to the in-memory filesystem, which has none.
+		onVolume []string
+		want     []string
+	}{
+		{
+			name:     "volume below the scanned path",
+			onVolume: []string{"nas"},
+			want:     []string{scannedPath + "/nas"},
+		},
+		{
+			name:     "volume at the scanned path",
+			onVolume: []string{"source", "nas"},
+			want:     []string{scannedPath},
+		},
+		{name: "no device numbers", want: nil},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx := context.Background()
+			fs := afero.NewMemMapFs()
+
+			for _, path := range []string{
+				scannedPath + "/notes.txt", scannedPath + "/nas/a.txt",
+			} {
+				require.NoError(t, fs.MkdirAll(filepath.Dir(path), 0o755))
+				require.NoError(t, afero.WriteFile(fs, path, []byte(path), 0o644))
+			}
+
+			db, err := database.NewTestDB()
+			require.NoError(t, err)
+			t.Cleanup(func() { _ = db.Close() })
+
+			repos := database.NewRepositories(db)
+			createTestSnapshotRecord(ctx, t, repos, snapshotID)
+
+			cfg := snapshot.ScannerConfig{
+				FS:               fs,
+				ChunkSize:        int64(1024 * 16),
+				Repositories:     repos,
+				MaxBlobSize:      int64(1024 * 1024),
+				CompressionLevel: 3,
+				AgeRecipients:    []string{testAgePublicKey},
+			}
+			if tt.onVolume != nil {
+				cfg.DeviceNumber = func(info os.FileInfo) (uint64, bool) {
+					if slices.Contains(tt.onVolume, info.Name()) {
+						return 2, true
+					}
+
+					return 1, true
+				}
+			}
+
+			_, err = snapshot.NewScanner(cfg).Scan(ctx, scannedPath, snapshotID)
+			require.NoError(t, err)
+
+			got, err := repos.Snapshots.GetMountPoints(ctx, snapshotID)
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+// automountFs is an in-memory filesystem with a volume at mountPoint
+// that is mounted on first access: opening mountPoint to list it mounts
+// the volume or, if it cannot be mounted, fails with "no such file or
+// directory", as with the autofs daemon. Stat records the device an
+// entry is on at that moment, as a real stat does: unmountedDevice for
+// mountPoint until the volume is mounted; the volume's, 2, for
+// mountPoint once it is and for everything in it; 1 for everything else.
+type automountFs struct {
+	afero.Fs
+
+	mountPoint      string
+	unmountedDevice uint64
+	canMount        bool
+	mounted         bool
+}
+
+//nolint:ireturn // afero.Fs.Open is defined to return the interface.
+func (fs *automountFs) Open(name string) (afero.File, error) {
+	if name == fs.mountPoint && !fs.canMount {
+		return nil, &os.PathError{Op: "open", Path: name, Err: syscall.ENOENT}
+	}
+
+	if name == fs.mountPoint {
+		fs.mounted = true
+	}
+
+	return fs.Fs.Open(name)
+}
+
+func (fs *automountFs) Stat(name string) (os.FileInfo, error) {
+	info, err := fs.Fs.Stat(name)
+	if err != nil {
+		return nil, err
+	}
+
+	device := uint64(1)
+
+	switch {
+	case name == fs.mountPoint && !fs.mounted:
+		device = fs.unmountedDevice
+	case name == fs.mountPoint || strings.HasPrefix(name, fs.mountPoint+"/"):
+		device = 2
+	}
+
+	return statWithDevice{FileInfo: info, device: device}, nil
+}
+
+// statWithDevice is an entry automountFs.Stat looked up, with the device
+// it was on then.
+type statWithDevice struct {
+	os.FileInfo
+
+	device uint64
+}
+
+// deviceAtLookup returns the device automountFs.Stat recorded for info.
+func deviceAtLookup(info os.FileInfo) (uint64, bool) {
+	stat, ok := info.(statWithDevice)
+
+	return stat.device, ok
+}
+
+// A volume mounted on first access is mounted when the walk lists its
+// mount point. Until then the mount point is on the automounter's own
+// device (a systemd automount) or on its parent's (an autofs map that
+// shows its mount points before mounting them). Either way only the
+// mount point is recorded, by the backup that mounts the volume and by a
+// later one that finds it mounted. Listing an automount point whose
+// volume cannot be mounted fails; it is not recorded, because the walk
+// finds no entry in it. See https://git.eeqj.de/sneak/vaultik/issues/395.
+func TestScanRecordsOnlyTheMountPointOfAnAutomountedVolume(t *testing.T) {
+	t.Parallel()
+
+	const scannedPath = "/data/source"
+
+	mountPoint := scannedPath + "/nas"
+
+	tests := []struct {
+		name            string
+		unmountedDevice uint64
+		canMount        bool
+		want            []string
+	}{
+		{
+			name:            "on the automounter's device until listed",
+			unmountedDevice: 3, canMount: true, want: []string{mountPoint},
+		},
+		{
+			name:            "on its parent's device until listed",
+			unmountedDevice: 1, canMount: true, want: []string{mountPoint},
+		},
+		{
+			name:            "volume that cannot be mounted",
+			unmountedDevice: 1, canMount: false, want: nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx := context.Background()
+			fs := &automountFs{
+				Fs: afero.NewMemMapFs(), mountPoint: mountPoint,
+				unmountedDevice: tt.unmountedDevice, canMount: tt.canMount,
+			}
+
+			require.NoError(t, fs.MkdirAll(mountPoint+"/photos", 0o755))
+
+			for _, path := range []string{
+				scannedPath + "/notes.txt", mountPoint + "/photos/a.jpg",
+			} {
+				require.NoError(t, afero.WriteFile(fs, path, []byte(path), 0o644))
+			}
+
+			db, err := database.NewTestDB()
+			require.NoError(t, err)
+			t.Cleanup(func() { _ = db.Close() })
+
+			repos := database.NewRepositories(db)
+
+			for _, snapshotID := range []string{"first", "later"} {
+				createTestSnapshotRecord(ctx, t, repos, snapshotID)
+
+				scanner := snapshot.NewScanner(snapshot.ScannerConfig{
+					FS:               fs,
+					ChunkSize:        int64(1024 * 16),
+					Repositories:     repos,
+					MaxBlobSize:      int64(1024 * 1024),
+					CompressionLevel: 3,
+					AgeRecipients:    []string{testAgePublicKey},
+					DeviceNumber:     deviceAtLookup,
+				})
+
+				_, err = scanner.Scan(ctx, scannedPath, snapshotID)
+				require.NoError(t, err)
+
+				got, err := repos.Snapshots.GetMountPoints(ctx, snapshotID)
+				require.NoError(t, err)
+				assert.Equal(t, tt.want, got, "mount points of the %s backup", snapshotID)
+			}
+		})
+	}
+}

internal/snapshot/progress.go

@@ -56,23 +56,27 @@ const (
 
 // ProgressStats holds atomic counters for progress tracking
 type ProgressStats struct {
-	FilesScanned     atomic.Int64 // Total files seen during scan (includes skipped)
+	FilesScanned   atomic.Int64 // Total files seen during scan (includes skipped)
-	FilesProcessed   atomic.Int64 // Files actually processed in phase 2
+	FilesProcessed atomic.Int64 // Files actually processed in phase 2
-	FilesSkipped     atomic.Int64 // Files skipped due to no changes
+	FilesSkipped   atomic.Int64 // Files skipped due to no changes
-	BytesScanned     atomic.Int64 // Bytes from new/changed files only
+	BytesScanned   atomic.Int64 // Bytes from new/changed files only
-	BytesSkipped     atomic.Int64 // Bytes from unchanged files
+	BytesSkipped   atomic.Int64 // Bytes from unchanged files
-	BytesProcessed   atomic.Int64 // Actual bytes processed (for ETA calculation)
+	BytesProcessed atomic.Int64 // Actual bytes processed (for ETA calculation)
-	ChunksCreated    atomic.Int64
+	ChunksCreated  atomic.Int64
-	BlobsCreated     atomic.Int64
+	BlobsCreated   atomic.Int64
-	BlobsUploaded    atomic.Int64
+	BlobsUploaded  atomic.Int64
-	BytesUploaded    atomic.Int64
+	BytesUploaded  atomic.Int64
-	CurrentFile      atomic.Value // stores string
+	CurrentFile    atomic.Value // stores string
-	TotalSize        atomic.Int64 // Total size to process (set after scan phase)
+	TotalSize      atomic.Int64 // Size to process in the paths scanned so far
-	TotalFiles       atomic.Int64 // Total files to process in phase 2
+	TotalFiles     atomic.Int64 // Files to process in the paths scanned so far
-	ProcessStartTime atomic.Value // stores time.Time when processing starts
+	StartTime      time.Time
-	StartTime        time.Time
+	mu             sync.RWMutex
-	mu               sync.RWMutex
+	lastDetailTime time.Time
-	lastDetailTime   time.Time
+
+	// Guarded by mu: when the last scan phase ended, and
+	// BytesProcessed at that moment.
+	processStartTime  time.Time
+	processStartBytes int64
 
 	// Upload tracking
 	CurrentUpload    atomic.Value // stores *UploadInfo
@@ -148,10 +152,36 @@ func (pr *ProgressReporter) GetStats() *ProgressStats {
 	return pr.stats
 }
 
-// SetTotalSize sets the total size to process (after scan phase)
+// AddTotalSize adds the size one path of the snapshot has to process to
-func (pr *ProgressReporter) SetTotalSize(size int64) {
+// the total, once that path's scan phase is done, and starts measuring
-	pr.stats.TotalSize.Store(size)
+// the processing rate again. The processed counts run across every path,
-	pr.stats.ProcessStartTime.Store(time.Now().UTC())
+// so the total does too. Restarting the rate keeps a path's scan phase,
+// which processes nothing, out of the rate while that path is processed.
+// During a later path's scan phase the rate is still the previous
+// path's, and falls as that scan goes on.
+func (pr *ProgressReporter) AddTotalSize(size int64) {
+	pr.stats.TotalSize.Add(size)
+
+	pr.stats.mu.Lock()
+	defer pr.stats.mu.Unlock()
+
+	pr.stats.processStartTime = time.Now().UTC()
+	pr.stats.processStartBytes = pr.stats.BytesProcessed.Load()
+}
+
+// processRate returns the bytes processed per second since the last scan
+// phase ended, or 0 before the first path's scan phase is done.
+func (s *ProgressStats) processRate() float64 {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	if s.processStartTime.IsZero() {
+		return 0
+	}
+
+	processed := s.BytesProcessed.Load() - s.processStartBytes
+
+	return float64(processed) / time.Since(s.processStartTime).Seconds()
 }
 
 // Helper functions
@@ -357,19 +387,12 @@ func (pr *ProgressReporter) printSummaryStatus() {
 	// Calculate ETA if we have total size and are processing
 	etaStr := ""
 
-	if totalSize > 0 && bytesProcessed > 0 {
+	processRate := pr.stats.processRate()
-		processStart, ok := pr.stats.ProcessStartTime.Load().(time.Time)
+	if totalSize > 0 && processRate > 0 {
-		if ok && !processStart.IsZero() {
+		remainingBytes := totalSize - bytesProcessed
-			processElapsed := time.Since(processStart)
+		remainingSeconds := float64(remainingBytes) / processRate
-
+		eta := time.Duration(remainingSeconds * float64(time.Second))
-			rate := float64(bytesProcessed) / processElapsed.Seconds()
+		etaStr = " | ETA: " + formatDuration(eta)
-			if rate > 0 {
-				remainingBytes := totalSize - bytesProcessed
-				remainingSeconds := float64(remainingBytes) / rate
-				eta := time.Duration(remainingSeconds * float64(time.Second))
-				etaStr = " | ETA: " + formatDuration(eta)
-			}
-		}
 	}
 
 	rate := float64(bytesScanned+bytesSkipped) / elapsed.Seconds()
@@ -421,25 +444,18 @@ func (pr *ProgressReporter) printDetailedStatus() {
 	log.Info("Elapsed time", "duration", formatDuration(elapsed))
 
 	// Calculate and show ETA if we have data
-	if totalSize > 0 && bytesProcessed > 0 {
+	processRate := pr.stats.processRate()
-		processStart, ok := pr.stats.ProcessStartTime.Load().(time.Time)
+	if totalSize > 0 && processRate > 0 {
-		if ok && !processStart.IsZero() {
+		remainingBytes := totalSize - bytesProcessed
-			processElapsed := time.Since(processStart)
+		remainingSeconds := float64(remainingBytes) / processRate
-
+		eta := time.Duration(remainingSeconds * float64(time.Second))
-			processRate := float64(bytesProcessed) / processElapsed.Seconds()
+		percentComplete := float64(bytesProcessed) / float64(totalSize) * percentScale
-			if processRate > 0 {
+		log.Info("Overall progress",
-				remainingBytes := totalSize - bytesProcessed
+			"percent", fmt.Sprintf("%.1f%%", percentComplete),
-				remainingSeconds := float64(remainingBytes) / processRate
+			"processed", humanize.Bytes(safeUint64(bytesProcessed)),
-				eta := time.Duration(remainingSeconds * float64(time.Second))
+			"total", humanize.Bytes(safeUint64(totalSize)),
-				percentComplete := float64(bytesProcessed) / float64(totalSize) * percentScale
+			"rate", humanize.Bytes(uint64(processRate))+"/s",
-				log.Info("Overall progress",
+			"eta", formatDuration(eta))
-					"percent", fmt.Sprintf("%.1f%%", percentComplete),
-					"processed", humanize.Bytes(safeUint64(bytesProcessed)),
-					"total", humanize.Bytes(safeUint64(totalSize)),
-					"rate", humanize.Bytes(uint64(processRate))+"/s",
-					"eta", formatDuration(eta))
-			}
-		}
 	}
 
 	log.Info("Files processed",

internal/snapshot/progress_rate_test.go

@@ -0,0 +1,54 @@
+//nolint:testpackage // exercises the unexported processRate helper
+package snapshot
+
+import (
+	"testing"
+	"time"
+)
+
+// TestProcessRateNotLoweredByLaterScanPhase feeds the reporter two paths
+// that each take 10 seconds to process, the second after a 30-second scan
+// phase. That scan phase processes nothing, so the rate while the second
+// path is processed must be that path's own.
+func TestProcessRateNotLoweredByLaterScanPhase(t *testing.T) {
+	t.Parallel()
+
+	const (
+		pathSize       = 1000
+		processingTime = 10 * time.Second
+		scanTime       = 30 * time.Second
+	)
+
+	// Never started, but Stop releases its tickers and signal handler.
+	progress := NewProgressReporter()
+	defer progress.Stop()
+
+	stats := progress.GetStats()
+
+	// Moves the processing start time back instead of sleeping.
+	elapse := func(d time.Duration) {
+		stats.mu.Lock()
+		defer stats.mu.Unlock()
+
+		stats.processStartTime = stats.processStartTime.Add(-d)
+	}
+
+	progress.AddTotalSize(pathSize)
+	stats.BytesProcessed.Add(pathSize)
+	elapse(processingTime)
+
+	elapse(scanTime)
+	progress.AddTotalSize(pathSize)
+	stats.BytesProcessed.Add(pathSize)
+	elapse(processingTime)
+
+	want := pathSize / processingTime.Seconds()
+	got := stats.processRate()
+
+	// The test's own run time adds to the elapsed time, so got is a hair
+	// under want.
+	if got > want || got < want*0.99 {
+		t.Errorf("rate while the second path is processed is %.1f bytes/s, "+
+			"want %.1f", got, want)
+	}
+}

internal/snapshot/progress_test.go

@@ -0,0 +1,93 @@
+package snapshot_test
+
+import (
+	"context"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/spf13/afero"
+	"sneak.berlin/go/vaultik/internal/database"
+	"sneak.berlin/go/vaultik/internal/snapshot"
+)
+
+// TestProgressPercentWithSecondPathSmaller backs up two paths with one
+// scanner, as a snapshot with two paths does, the second path smaller
+// than the first. The progress line divides the bytes processed by the
+// total size, so both must count both paths to stay within 100%.
+func TestProgressPercentWithSecondPathSmaller(t *testing.T) {
+	t.Parallel()
+
+	fs := afero.NewMemMapFs()
+	files := map[string]string{
+		"/large/one.txt":   strings.Repeat("1", 4000),
+		"/large/two.txt":   strings.Repeat("2", 4000),
+		"/small/three.txt": strings.Repeat("3", 1000),
+	}
+
+	for path, content := range files {
+		err := fs.MkdirAll(filepath.Dir(path), 0755)
+		if err != nil {
+			t.Fatalf("mkdir: %v", err)
+		}
+
+		err = afero.WriteFile(fs, path, []byte(content), 0644)
+		if err != nil {
+			t.Fatalf("write %s: %v", path, err)
+		}
+	}
+
+	db, err := database.NewTestDB()
+	if err != nil {
+		t.Fatalf("create test db: %v", err)
+	}
+
+	t.Cleanup(func() {
+		cerr := db.Close()
+		if cerr != nil {
+			t.Errorf("close db: %v", cerr)
+		}
+	})
+
+	repos := database.NewRepositories(db)
+
+	scanner := snapshot.NewScanner(snapshot.ScannerConfig{
+		FS:               fs,
+		ChunkSize:        int64(1024 * 16),
+		Repositories:     repos,
+		MaxBlobSize:      int64(1024 * 1024),
+		CompressionLevel: 3,
+		AgeRecipients:    []string{testAgePublicKey},
+		EnableProgress:   true,
+	})
+
+	// Never started, but Stop releases its tickers and signal handler.
+	progress := scanner.GetProgress()
+	defer progress.Stop()
+
+	ctx := context.Background()
+	snapshotID := "test-snapshot-progress"
+	createTestSnapshotRecord(ctx, t, repos, snapshotID)
+
+	for _, path := range []string{"/large", "/small"} {
+		_, err := scanner.Scan(ctx, path, snapshotID)
+		if err != nil {
+			t.Fatalf("scanning %s: %v", path, err)
+		}
+	}
+
+	stats := progress.GetStats()
+
+	// With both paths counted, the percentage must not exceed 100%.
+	percent := float64(stats.BytesProcessed.Load()) /
+		float64(stats.TotalSize.Load()) * 100
+	if percent > 100 {
+		t.Errorf("progress after both paths is %.1f%%, want at most 100%%",
+			percent)
+	}
+
+	if stats.FilesProcessed.Load() != stats.TotalFiles.Load() {
+		t.Errorf("progress after both paths is %d of %d files, want all",
+			stats.FilesProcessed.Load(), stats.TotalFiles.Load())
+	}
+}

internal/snapshot/scanner_estimate_test.go

@@ -0,0 +1,28 @@
+//nolint:testpackage // exercises the unexported countNonDirectories helper
+package snapshot
+
+import (
+	"os"
+	"testing"
+
+	"sneak.berlin/go/vaultik/internal/database"
+)
+
+// The walk counts regular files and symlinks, not directories, so the
+// estimate of its count made from the local index's records leaves the
+// directories out. See https://git.eeqj.de/sneak/vaultik/issues/305.
+func TestCountNonDirectories(t *testing.T) {
+	t.Parallel()
+
+	known := map[string]*database.File{
+		"/src":       {Mode: uint32(os.ModeDir | 0o755)},
+		"/src/sub":   {Mode: uint32(os.ModeDir | 0o755)},
+		"/src/a.txt": {Mode: 0o644},
+		"/src/link":  {Mode: uint32(os.ModeSymlink | 0o777), LinkTarget: "a.txt"},
+	}
+
+	got := countNonDirectories(known)
+	if got != 2 {
+		t.Errorf("countNonDirectories = %d, want 2", got)
+	}
+}

internal/snapshot/skip_errors_test.go

@@ -3,6 +3,7 @@ package snapshot_test
 import (
 	"context"
 	"errors"
+	"io"
 	"os"
 	"path/filepath"
 	"strings"
@@ -13,6 +14,7 @@ import (
 	"github.com/spf13/afero"
 	"sneak.berlin/go/vaultik/internal/database"
 	"sneak.berlin/go/vaultik/internal/snapshot"
+	"sneak.berlin/go/vaultik/internal/ui"
 )
 
 // errSimTempFail is the one-time temp-file creation failure blobTempFailFs
@@ -80,6 +82,56 @@ func (f *readFailFs) Open(name string) (afero.File, error) {
 	return file, nil
 }
 
+// cancelOnOpenFs cancels the run when the scanner opens the target file to
+// back it up, as Ctrl-C partway through processing would, and records each
+// file opened after that.
+type cancelOnOpenFs struct {
+	afero.Fs
+
+	target            string
+	cancel            context.CancelFunc
+	cancelled         bool
+	openedAfterCancel []string
+}
+
+//nolint:ireturn // afero.Fs.Open is defined to return the interface.
+func (f *cancelOnOpenFs) Open(name string) (afero.File, error) {
+	if f.cancelled {
+		f.openedAfterCancel = append(f.openedAfterCancel, name)
+	}
+
+	if name == f.target {
+		f.cancel()
+		f.cancelled = true
+	}
+
+	return f.Fs.Open(name)
+}
+
+// linkRemovedAfterLstatFs is the real filesystem, except that the symlink at
+// target is removed right after the walk lstats it, as happens when a link is
+// deleted during a backup. The scanner's readlink of it then fails.
+type linkRemovedAfterLstatFs struct {
+	afero.OsFs
+
+	t      *testing.T
+	target string
+}
+
+func (f *linkRemovedAfterLstatFs) LstatIfPossible(
+	name string,
+) (os.FileInfo, bool, error) {
+	info, lstatCalled, err := f.OsFs.LstatIfPossible(name)
+	if err == nil && name == f.target {
+		rmErr := os.Remove(name)
+		if rmErr != nil {
+			f.t.Errorf("removing %s: %v", name, rmErr)
+		}
+	}
+
+	return info, lstatCalled, err
+}
+
 // writeSkipErrorTestFile writes one file into fs with a fixed mtime.
 func writeSkipErrorTestFile(t *testing.T, fs afero.Fs, path, content string) {
 	t.Helper()
@@ -102,14 +154,16 @@ func writeSkipErrorTestFile(t *testing.T, fs afero.Fs, path, content string) {
 	}
 }
 
-// runSkipErrorScan scans /source on fs with the given skip-errors setting and
+// runSkipErrorScan scans source on fs under ctx with the given skip-errors
+// setting, printing user-facing messages to uiw (nil discards them), and
 // returns the repositories (for inspection) and the scan error.
 func runSkipErrorScan(
-	t *testing.T, fs afero.Fs, skipErrors bool,
+	ctx context.Context, t *testing.T, fs afero.Fs, source string,
+	skipErrors bool, uiw *ui.Writer,
 ) (*database.Repositories, error) {
 	t.Helper()
 
-	db, err := database.NewTestDB()
+	db, err := database.New(ctx, ":memory:")
 	if err != nil {
 		t.Fatalf("create test db: %v", err)
 	}
@@ -130,14 +184,14 @@ func runSkipErrorScan(
 		MaxBlobSize:      int64(1024 * 1024),
 		CompressionLevel: 3,
 		AgeRecipients:    []string{testAgePublicKey},
+		UI:               uiw,
 		SkipErrors:       skipErrors,
 	})
 
-	ctx := context.Background()
 	snapshotID := "test-snapshot-skip-errors"
 	createTestSnapshotRecord(ctx, t, repos, snapshotID)
 
-	_, err = scanner.Scan(ctx, "/source", snapshotID)
+	_, err = scanner.Scan(ctx, source, snapshotID)
 
 	return repos, err
 }
@@ -157,7 +211,7 @@ func TestScannerPackingFailureAbortsUnderSkipErrors(t *testing.T) {
 	writeSkipErrorTestFile(t, fs, "/source/file1.txt", "first file content")
 	writeSkipErrorTestFile(t, fs, "/source/file2.txt", "second file content")
 
-	repos, err := runSkipErrorScan(t, fs, true)
+	repos, err := runSkipErrorScan(context.Background(), t, fs, "/source", true, nil)
 	if err == nil {
 		t.Fatal("expected scan to abort on the packer error, got nil")
 	}
@@ -184,7 +238,7 @@ func TestScannerReadErrorAbortsWithoutSkipErrors(t *testing.T) {
 	fs := &readFailFs{Fs: afero.NewMemMapFs(), target: target}
 	writeSkipErrorTestFile(t, fs, target, "content that cannot be read")
 
-	_, err := runSkipErrorScan(t, fs, false)
+	_, err := runSkipErrorScan(context.Background(), t, fs, "/source", false, nil)
 	if err == nil {
 		t.Fatal("expected scan to fail on the read error, got nil")
 	}
@@ -200,7 +254,7 @@ func TestScannerReadErrorSkippedWithSkipErrors(t *testing.T) {
 	fs := &readFailFs{Fs: afero.NewMemMapFs(), target: target}
 	writeSkipErrorTestFile(t, fs, target, "content that cannot be read")
 
-	repos, err := runSkipErrorScan(t, fs, true)
+	repos, err := runSkipErrorScan(context.Background(), t, fs, "/source", true, nil)
 	if err != nil {
 		t.Fatalf("expected scan to complete with --skip-errors, got %v", err)
 	}
@@ -214,3 +268,173 @@ func TestScannerReadErrorSkippedWithSkipErrors(t *testing.T) {
 		t.Fatalf("expected unreadable file skipped, got %d chunks", len(chunks))
 	}
 }
+
+// writeSymlinkSource creates a source directory on disk holding one symlink
+// and returns the directory and the symlink's path.
+func writeSymlinkSource(t *testing.T) (string, string) {
+	t.Helper()
+
+	sourceDir := t.TempDir()
+	linkPath := filepath.Join(sourceDir, "link")
+
+	err := os.Symlink("target.txt", linkPath)
+	if err != nil {
+		t.Fatalf("creating symlink: %v", err)
+	}
+
+	return sourceDir, linkPath
+}
+
+// TestScannerUnreadableSymlinkAbortsWithoutSkipErrors checks that a symlink
+// whose target cannot be read aborts the run when --skip-errors is not set.
+func TestScannerUnreadableSymlinkAbortsWithoutSkipErrors(t *testing.T) {
+	t.Parallel()
+
+	sourceDir, linkPath := writeSymlinkSource(t)
+	fs := &linkRemovedAfterLstatFs{t: t, target: linkPath}
+
+	_, err := runSkipErrorScan(context.Background(), t, fs, sourceDir, false, nil)
+	if !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("expected scan to fail on the removed symlink, got %v", err)
+	}
+}
+
+// TestScannerUnreadableSymlinkSkippedWithSkipErrors checks that a symlink
+// whose target cannot be read is skipped with an error line, and the run
+// completes, when --skip-errors is set.
+func TestScannerUnreadableSymlinkSkippedWithSkipErrors(t *testing.T) {
+	t.Parallel()
+
+	sourceDir, linkPath := writeSymlinkSource(t)
+	fs := &linkRemovedAfterLstatFs{t: t, target: linkPath}
+	uiw := ui.NewWithColor(io.Discard, false)
+
+	repos, err := runSkipErrorScan(context.Background(), t, fs, sourceDir, true, uiw)
+	if err != nil {
+		t.Fatalf("expected scan to complete with --skip-errors, got %v", err)
+	}
+
+	if uiw.ErrorCount() != 1 {
+		t.Fatalf("expected one error line for the symlink, got %d",
+			uiw.ErrorCount())
+	}
+
+	file, err := repos.Files.GetByPath(context.Background(), linkPath)
+	if err != nil {
+		t.Fatalf("getting %s: %v", linkPath, err)
+	}
+
+	if file != nil {
+		t.Fatalf("expected %s not to be recorded", linkPath)
+	}
+}
+
+// TestScannerCancelStopsSkipErrorsRun checks that a --skip-errors backup
+// cancelled partway through processing returns the cancellation error,
+// opens no further file, and reports no file as failed.
+func TestScannerCancelStopsSkipErrorsRun(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name          string
+		targetContent string
+	}{
+		// The cancellation lands while the target is being read.
+		{name: "while reading a file", targetContent: "first file content"},
+		// An empty target has no chunks, so the cancellation goes unnoticed
+		// until the run moves on to the next file.
+		{name: "between files", targetContent: ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			const target = "/source/a.txt"
+
+			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+
+			fs := &cancelOnOpenFs{
+				Fs: afero.NewMemMapFs(), target: target, cancel: cancel,
+			}
+			writeSkipErrorTestFile(t, fs, target, tt.targetContent)
+			writeSkipErrorTestFile(t, fs, "/source/b.txt", "second file content")
+			writeSkipErrorTestFile(t, fs, "/source/c.txt", "third file content")
+
+			uiw := ui.NewWithColor(io.Discard, false)
+
+			_, err := runSkipErrorScan(ctx, t, fs, "/source", true, uiw)
+			if !errors.Is(err, context.Canceled) {
+				t.Fatalf("expected the cancellation error, got %v", err)
+			}
+
+			if len(fs.openedAfterCancel) != 0 {
+				t.Fatalf("expected no file opened after the cancellation, got %v",
+					fs.openedAfterCancel)
+			}
+
+			if uiw.ErrorCount() != 0 {
+				t.Fatalf("expected no file reported as failed, got %d error lines",
+					uiw.ErrorCount())
+			}
+		})
+	}
+}
+
+// TestScannerRemovesBlobTempFileWhenRunStops checks that a run stopped
+// part-way, by a file it cannot read or by a cancellation, removes the
+// temp file of the blob it was packing.
+func TestScannerRemovesBlobTempFileWhenRunStops(t *testing.T) {
+	t.Parallel()
+
+	// a.txt is backed up first and starts a blob; the run stops at b.txt.
+	const target = "/source/b.txt"
+
+	tests := []struct {
+		name  string
+		newFs func(cancel context.CancelFunc) afero.Fs
+	}{
+		{
+			name: "file cannot be read",
+			newFs: func(context.CancelFunc) afero.Fs {
+				return &readFailFs{Fs: afero.NewMemMapFs(), target: target}
+			},
+		},
+		{
+			name: "cancelled",
+			newFs: func(cancel context.CancelFunc) afero.Fs {
+				return &cancelOnOpenFs{
+					Fs: afero.NewMemMapFs(), target: target, cancel: cancel,
+				}
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+
+			fs := tt.newFs(cancel)
+			writeSkipErrorTestFile(t, fs, "/source/a.txt", "first file content")
+			writeSkipErrorTestFile(t, fs, target, "second file content")
+
+			_, err := runSkipErrorScan(ctx, t, fs, "/source", false, nil)
+			if err == nil {
+				t.Fatal("expected the scan to stop with an error, got nil")
+			}
+
+			left, err := afero.Glob(fs, filepath.Join(os.TempDir(), "vaultik-blob-*"))
+			if err != nil {
+				t.Fatalf("listing blob temp files: %v", err)
+			}
+
+			if len(left) != 0 {
+				t.Fatalf("expected no blob temp file left, got %v", left)
+			}
+		})
+	}
+}

internal/snapshot/snapshot.go

@@ -115,20 +115,37 @@ func ShortHostname(hostname string) string {
 
 // CreateSnapshotWithName creates a new snapshot record with an optional
 // snapshot name. The snapshot ID format is: hostname_name_timestamp or
-// hostname_timestamp if name is empty.
+// hostname_timestamp if name is empty. The timestamp is in whole seconds.
+// If the local index already has a snapshot with that ID, from a run of the
+// same name that started in the same second, it waits a second and takes a
+// new timestamp.
 func (sm *SnapshotManager) CreateSnapshotWithName(
 	ctx context.Context, hostname, name, version, gitRevision string,
 ) (string, error) {
 	shortHostname := ShortHostname(hostname)
 
-	// Build snapshot ID with optional name
-	timestamp := time.Now().UTC().Format("2006-01-02T15:04:05Z")
-
 	var snapshotID string
-	if name != "" {
+
-		snapshotID = fmt.Sprintf("%s_%s_%s", shortHostname, name, timestamp)
+	for {
-	} else {
+		// Build snapshot ID with optional name
-		snapshotID = fmt.Sprintf("%s_%s", shortHostname, timestamp)
+		timestamp := time.Now().UTC().Format("2006-01-02T15:04:05Z")
+
+		if name != "" {
+			snapshotID = fmt.Sprintf("%s_%s_%s", shortHostname, name, timestamp)
+		} else {
+			snapshotID = fmt.Sprintf("%s_%s", shortHostname, timestamp)
+		}
+
+		existing, err := sm.repos.Snapshots.GetByID(ctx, snapshotID)
+		if err != nil {
+			return "", fmt.Errorf("looking up snapshot %s: %w", snapshotID, err)
+		}
+
+		if existing == nil {
+			break
+		}
+
+		time.Sleep(time.Second)
 	}
 
 	snapshot := &database.Snapshot{
@@ -182,6 +199,7 @@ func (sm *SnapshotManager) UpdateSnapshotStatsExtended(
 			stats.CompressionLevel,
 			stats.BytesUploaded,
 			stats.UploadDurationMs,
+			stats.NewChunkSize,
 		)
 	})
 }
@@ -500,8 +518,8 @@ type CleanupStats struct {
 //
 // The cleanup is performed in a specific order to maintain referential integrity:
 //  1. Delete other snapshots
-//  2. Delete orphaned snapshot associations (snapshot_files, snapshot_blobs)
+//  2. Delete orphaned snapshot associations (snapshot_files, snapshot_blobs,
-//     for deleted snapshots
+//     snapshot_mount_points) for deleted snapshots
 //  3. Delete orphaned files (not in the current snapshot)
 //  4. Delete orphaned chunk-to-file mappings (references to deleted files)
 //  5. Delete orphaned blobs (not in the current snapshot)
@@ -875,7 +893,7 @@ func (sm *SnapshotManager) getFileSize(path string) int64 {
 // BackupStats contains statistics from a backup operation
 type BackupStats struct {
 	FilesScanned  int
-	TotalSize     int64 // Total size of all files examined
+	TotalSize     int64 // Total size of the files in the snapshot
 	ChunksCreated int
 	BlobsCreated  int
 	BytesUploaded int64
@@ -889,6 +907,7 @@ type ExtendedBackupStats struct {
 	BlobUncompressedSize int64 // Total uncompressed size of all referenced blobs
 	CompressionLevel     int   // Compression level used for this snapshot
 	UploadDurationMs     int64 // Total milliseconds spent uploading to S3
+	NewChunkSize         int64 // Total size of the chunks counted in ChunksCreated
 }
 
 // deleteOtherSnapshots deletes all snapshots except the current one
@@ -929,8 +948,8 @@ func (sm *SnapshotManager) deleteOtherSnapshots(
 	return nil
 }
 
-// deleteOrphanedSnapshotAssociations deletes snapshot_files and
+// deleteOrphanedSnapshotAssociations deletes snapshot_files,
-// snapshot_blobs for deleted snapshots
+// snapshot_blobs and snapshot_mount_points for deleted snapshots
 func (sm *SnapshotManager) deleteOrphanedSnapshotAssociations(
 	ctx context.Context, tx *sql.Tx, currentSnapshotID string,
 ) error {
@@ -964,6 +983,19 @@ func (sm *SnapshotManager) deleteOrphanedSnapshotAssociations(
 	log.Debug("[Temp DB Cleanup] Deleted snapshot_blobs associations",
 		"count", rowsAffected)
 
+	// Delete the mount points other snapshots recorded
+	query := "DELETE FROM snapshot_mount_points WHERE snapshot_id != ?"
+	database.LogSQL("Execute", query, currentSnapshotID)
+
+	result, err = tx.ExecContext(ctx, query, currentSnapshotID)
+	if err != nil {
+		return fmt.Errorf("deleting orphaned snapshot_mount_points: %w", err)
+	}
+
+	rowsAffected, _ = result.RowsAffected()
+	log.Debug("[Temp DB Cleanup] Deleted snapshot_mount_points rows",
+		"count", rowsAffected)
+
 	return nil
 }
 

internal/snapshot/snapshot_test.go

@@ -7,12 +7,14 @@ import (
 	"database/sql"
 	"io"
 	"path/filepath"
+	"slices"
 	"testing"
 
 	"github.com/spf13/afero"
 	"sneak.berlin/go/vaultik/internal/config"
 	"sneak.berlin/go/vaultik/internal/database"
 	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/types"
 )
 
 const (
@@ -386,3 +388,107 @@ func TestCleanSnapshotDBNonExistentSnapshot(t *testing.T) {
 		t.Fatalf("unexpected error: %v", err)
 	}
 }
+
+// The exported metadata database keeps only the mount points that the
+// exported snapshot recorded. See
+// https://git.eeqj.de/sneak/vaultik/issues/395.
+func TestCleanSnapshotDBKeepsOnlyTheSnapshotsMountPoints(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	dbPath := filepath.Join(t.TempDir(), "export.db")
+
+	db, err := database.New(ctx, dbPath)
+	if err != nil {
+		t.Fatalf("failed to create database: %v", err)
+	}
+
+	repos := database.NewRepositories(db)
+
+	for _, id := range []types.SnapshotID{"exported", "other"} {
+		err = repos.Snapshots.Create(ctx, nil, &database.Snapshot{ID: id})
+		if err != nil {
+			t.Fatalf("failed to create snapshot: %v", err)
+		}
+
+		err = repos.Snapshots.AddMountPoint(ctx, nil, id.String(), "/data/"+id.String())
+		if err != nil {
+			t.Fatalf("failed to add mount point: %v", err)
+		}
+	}
+
+	err = db.Close()
+	if err != nil {
+		t.Fatalf("failed to close database: %v", err)
+	}
+
+	sm := &SnapshotManager{
+		config: &config.Config{
+			CompressionLevel: 3,
+			AgeRecipients:    []string{testAgeRecipient},
+		},
+		fs: afero.NewOsFs(),
+	}
+
+	_, err = sm.cleanSnapshotDB(ctx, dbPath, "exported")
+	if err != nil {
+		t.Fatalf("failed to clean snapshot database: %v", err)
+	}
+
+	cleaned, err := database.New(ctx, dbPath)
+	if err != nil {
+		t.Fatalf("failed to open cleaned database: %v", err)
+	}
+
+	defer func() { _ = cleaned.Close() }()
+
+	cleanedRepos := database.NewRepositories(cleaned)
+
+	for id, want := range map[string][]string{
+		"exported": {"/data/exported"},
+		"other":    nil,
+	} {
+		got, err := cleanedRepos.Snapshots.GetMountPoints(ctx, id)
+		if err != nil {
+			t.Fatalf("failed to read mount points: %v", err)
+		}
+
+		if !slices.Equal(got, want) {
+			t.Errorf("mount points of %s: got %v, want %v", id, got, want)
+		}
+	}
+}
+
+// Two creates of one snapshot name back to back start within one second,
+// the resolution of the timestamp in a snapshot ID. See
+// https://git.eeqj.de/sneak/vaultik/issues/270.
+func TestCreateSnapshotWithNameTwiceBackToBack(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+
+	db, err := database.New(ctx, filepath.Join(t.TempDir(), "index.sqlite"))
+	if err != nil {
+		t.Fatalf("failed to create database: %v", err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	sm := &SnapshotManager{repos: database.NewRepositories(db)}
+
+	first, err := sm.CreateSnapshotWithName(ctx, "test-host", "data", "v", "g")
+	if err != nil {
+		t.Fatalf("first create failed: %v", err)
+	}
+
+	second, err := sm.CreateSnapshotWithName(ctx, "test-host", "data", "v", "g")
+	if err != nil {
+		t.Fatalf("second create failed: %v", err)
+	}
+
+	if first == second {
+		t.Fatalf("both creates returned snapshot ID %s", first)
+	}
+}

internal/storage/conformance_test.go

@@ -8,25 +8,29 @@ import (
 	"reflect"
 	"sort"
 	"testing"
+	"time"
 
 	"sneak.berlin/go/vaultik/internal/storage"
 )
 
 // runStorerConformance is the shared Storer contract. Every backend that
 // can run in-process is expected to pass it: TestFileStorer runs it against
-// file://, TestS3Storer against s3://. A new backend inherits this coverage
+// file://, TestS3Storer against s3://, TestRcloneStorer against rclone's
-// by passing its own constructor, so the contract is defined once.
+// local backend. A new backend inherits this coverage by passing its own
+// constructor, so the contract is defined once.
 //
 // It exercises the public Storer interface: round-trip, stat, list with
-// prefix filtering, overwrite, delete, delete-of-missing, and not-found on
+// prefix filtering, the modification time ListStream reports, overwrite,
-// Get and Stat. Each section takes its own fresh backend instance, so the
+// delete, delete-of-missing, and not-found on Get and Stat. Each section
-// order of sections never matters and no section sees another's objects.
+// takes its own fresh backend instance, so the order of sections never
+// matters and no section sees another's objects.
 func runStorerConformance(t *testing.T, newStorer func(*testing.T) storage.Storer) {
 	t.Helper()
 
 	conformanceRoundTrip(t, newStorer(t))
 	conformanceOverwrite(t, newStorer(t))
 	conformanceList(t, newStorer(t))
+	conformanceListStreamModTime(t, newStorer(t))
 	conformanceDelete(t, newStorer(t))
 	conformanceNotFound(t, newStorer(t))
 }
@@ -117,6 +121,35 @@ func conformanceList(t *testing.T, s storage.Storer) {
 	}
 }
 
+// conformanceListStreamModTime checks that ListStream gives an object
+// just written a modification time of about now, which prune compares
+// with its grace period.
+func conformanceListStreamModTime(t *testing.T, s storage.Storer) {
+	t.Helper()
+
+	ctx := context.Background()
+
+	err := s.Put(ctx, "blobs/dd/written-now", bytes.NewReader([]byte("data")))
+	if err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+
+	var listed []storage.ObjectInfo
+
+	for info := range s.ListStream(ctx, "blobs/") {
+		listed = append(listed, info)
+	}
+
+	if len(listed) != 1 || listed[0].Err != nil {
+		t.Fatalf("ListStream(\"blobs/\") = %v, want the one object", listed)
+	}
+
+	if time.Since(listed[0].ModTime).Abs() > time.Minute {
+		t.Errorf("ListStream ModTime = %v, want within a minute of now",
+			listed[0].ModTime)
+	}
+}
+
 // conformanceDelete checks that Delete removes an object and that deleting
 // a missing key is not an error.
 func conformanceDelete(t *testing.T, s storage.Storer) {

internal/storage/faultstore/faultstore.go

@@ -1,15 +1,18 @@
 // Package faultstore provides a storage.Storer wrapper that injects
 // faults on demand, so tests can reproduce the failure modes a real
 // backend exhibits: an upload that fails partway, a backend that reports
-// success while storing nothing, and reads that return corrupt or
+// success while storing nothing, reads that return corrupt or truncated
-// truncated bytes. It is the seam called for by the fault-injection
+// bytes, and a delete or a stat the backend refuses. It is the seam
-// tests (sneak/vaultik issue 72) and is meant to be reused by future
+// called for by the fault-injection tests (sneak/vaultik issue 72) and
-// tests rather than re-implemented per case.
+// is meant to be reused by future tests rather than re-implemented per
+// case.
 //
-// The wrapper delegates every method to the inner Storer. Two hooks
+// The wrapper delegates every method to the inner Storer. Four hooks
-// change that: OnPut decides the fate of each write, and OnGet decides
+// change that: OnPut decides the fate of each write, OnGet decides how
-// how each read's bytes are returned. Both are keyed by the object key,
+// each read's bytes are returned, OnDelete decides whether each delete
-// so a test can fault only blobs, only metadata, or a single object.
+// fails, and OnStat whether each stat fails. All are keyed by the object
+// key, so a test can fault only blobs, only metadata, or a single
+// object.
 package faultstore
 
 import (
@@ -25,6 +28,15 @@ import (
 // ErrInjectedUpload is returned by a Put the OnPut hook chose to fail.
 var ErrInjectedUpload = errors.New("faultstore: injected upload failure")
 
+// ErrInjectedDelete is returned by a Delete the OnDelete hook chose to
+// fail.
+var ErrInjectedDelete = errors.New("faultstore: injected delete failure")
+
+// ErrInjectedStat is returned by a Stat the OnStat hook chose to fail.
+// It is not storage.ErrNotFound: the backend refused the request, as S3
+// refuses a HEAD to credentials that allow only PUT.
+var ErrInjectedStat = errors.New("faultstore: injected stat failure")
+
 // PutAction is the disposition OnPut assigns to a write.
 type PutAction int
 
@@ -66,6 +78,15 @@ type Storer struct {
 	// OnGet, when set, is consulted for every Get with the object key
 	// and damages the returned bytes accordingly.
 	OnGet func(key string) GetFault
+
+	// OnDelete, when set, is consulted before every Delete with the
+	// object key. Returning true fails the delete and leaves the object
+	// in place.
+	OnDelete func(key string) bool
+
+	// OnStat, when set, is consulted before every Stat with the object
+	// key. Returning true fails the stat with ErrInjectedStat.
+	OnStat func(key string) bool
 }
 
 // New wraps inner. inner must be non-nil.
@@ -149,13 +170,21 @@ func damage(fault GetFault, data []byte) []byte {
 	return out
 }
 
-// Stat delegates unchanged.
+// Stat returns the object's info unless OnStat fails the stat.
 func (f *Storer) Stat(ctx context.Context, key string) (*storage.ObjectInfo, error) {
+	if f.OnStat != nil && f.OnStat(key) {
+		return nil, fmt.Errorf("%w for %q", ErrInjectedStat, key)
+	}
+
 	return f.inner.Stat(ctx, key)
 }
 
-// Delete delegates unchanged.
+// Delete removes the object unless OnDelete fails the delete.
 func (f *Storer) Delete(ctx context.Context, key string) error {
+	if f.OnDelete != nil && f.OnDelete(key) {
+		return fmt.Errorf("%w for %q", ErrInjectedDelete, key)
+	}
+
 	return f.inner.Delete(ctx, key)
 }
 
@@ -171,6 +200,11 @@ func (f *Storer) ListStream(
 	return f.inner.ListStream(ctx, prefix)
 }
 
+// DeletePartialUploads delegates unchanged.
+func (f *Storer) DeletePartialUploads(ctx context.Context, prefix string) error {
+	return f.inner.DeletePartialUploads(ctx, prefix)
+}
+
 // Info delegates unchanged.
 func (f *Storer) Info() storage.Info {
 	return f.inner.Info()

internal/storage/file.go

@@ -21,9 +21,13 @@ type FileStorer struct {
 // NewFileStorer creates a new filesystem storage backend.
 //
 // Construction is intentionally cheap and does not touch the filesystem.
-// The basePath is recorded; the directory is created lazily on first
+// The backend never creates basePath: the user does, so that when
-// write. Write operations (Put/PutWithProgress) call MkdirAll for the
+// basePath is a directory on an unplugged volume, a write fails instead
-// per-blob parent directory, which also covers basePath on first use.
+// of landing on the disk under the mount point. This does not hold when
+// basePath is the mount point itself, which stays behind when its volume
+// is unplugged.
+// Put and PutWithProgress fail on a missing basePath and create the
+// directories below it as needed.
 // Get and Stat report a key under a missing basePath as ErrNotFound.
 // List and ListStream fail on a missing basePath, because listing it as
 // an empty store would make `prune` drop every local snapshot record.
@@ -50,9 +54,10 @@ const storageDirPerm = 0o755
 // temp file carrying this suffix and only renames it onto the real key once
 // the whole object is on disk, so an interrupted write can never leave a
 // truncated object at the key a later run would Stat and trust as a complete
-// blob. List and ListStream skip these files, so a leftover from an
+// blob. The rclone backend's upload does the same on remotes with a
-// interrupted write is never listed or trusted as a blob; it is otherwise
+// server-side move. List and ListStream skip these files, so a leftover from
-// harmless and is overwritten when the same key is written again.
+// an interrupted write is never listed or trusted as a blob; it is otherwise
+// harmless.
 const tempSuffix = ".partial"
 
 // Put stores data at the specified key.
@@ -119,9 +124,10 @@ func (f *FileStorer) Delete(_ context.Context, key string) error {
 	return nil
 }
 
-// List returns all keys with the given prefix. It fails when the
+// List returns all keys with the given prefix, reading through symlinked
-// destination directory is missing; a missing prefix under it is an
+// directories. It fails when the destination directory is missing, or
-// empty listing.
+// when the prefix or a directory above it is a symlink whose target is
+// missing; a prefix that is truly missing is an empty listing.
 func (f *FileStorer) List(ctx context.Context, prefix string) ([]string, error) {
 	var keys []string
 
@@ -132,8 +138,7 @@ func (f *FileStorer) List(ctx context.Context, prefix string) ([]string, error)
 
 	basePath := f.fullPath(prefix)
 
-	// Check if the prefix exists
+	exists, err := f.prefixExists(prefix)
-	exists, err := afero.Exists(f.fs, basePath)
 	if err != nil {
 		return nil, fmt.Errorf("checking path: %w", err)
 	}
@@ -142,7 +147,7 @@ func (f *FileStorer) List(ctx context.Context, prefix string) ([]string, error)
 		return keys, nil // Empty list for non-existent prefix
 	}
 
-	err = afero.Walk(f.fs, basePath, func(path string, info os.FileInfo, err error) error {
+	err = f.walk(basePath, func(path string, info os.FileInfo, err error) error {
 		if err != nil {
 			return err
 		}
@@ -175,7 +180,9 @@ func (f *FileStorer) List(ctx context.Context, prefix string) ([]string, error)
 }
 
 // ListStream returns a channel of ObjectInfo for large result sets. Like
-// List, it sends an error when the destination directory is missing.
+// List, it reads through symlinked directories and sends an error when
+// the destination directory is missing, or when the prefix or a directory
+// above it is a symlink whose target is missing.
 func (f *FileStorer) ListStream(ctx context.Context, prefix string) <-chan ObjectInfo {
 	ch := make(chan ObjectInfo)
 
@@ -191,8 +198,7 @@ func (f *FileStorer) ListStream(ctx context.Context, prefix string) <-chan Objec
 
 		basePath := f.fullPath(prefix)
 
-		// Check if the prefix exists
+		exists, err := f.prefixExists(prefix)
-		exists, err := afero.Exists(f.fs, basePath)
 		if err != nil {
 			ch <- ObjectInfo{Err: fmt.Errorf("checking path: %w", err)}
 
@@ -203,7 +209,7 @@ func (f *FileStorer) ListStream(ctx context.Context, prefix string) <-chan Objec
 			return // Empty channel for non-existent prefix
 		}
 
-		_ = afero.Walk(f.fs, basePath, func(path string, info os.FileInfo, err error) error {
+		_ = f.walk(basePath, func(path string, info os.FileInfo, err error) error {
 			// Check context cancellation
 			select {
 			case <-ctx.Done():
@@ -229,8 +235,9 @@ func (f *FileStorer) ListStream(ctx context.Context, prefix string) <-chan Objec
 				// Normalize path separators
 				relPath = strings.ReplaceAll(relPath, string(filepath.Separator), "/")
 				ch <- ObjectInfo{
-					Key:  relPath,
+					Key:     relPath,
-					Size: info.Size(),
+					Size:    info.Size(),
+					ModTime: info.ModTime(),
 				}
 			}
 
@@ -241,6 +248,43 @@ func (f *FileStorer) ListStream(ctx context.Context, prefix string) <-chan Objec
 	return ch
 }
 
+// DeletePartialUploads removes every file under prefix whose name ends in
+// tempSuffix. Like List, it reads through symlinked directories and fails
+// on one whose target is missing. A missing prefix has none to remove.
+func (f *FileStorer) DeletePartialUploads(ctx context.Context, prefix string) error {
+	basePath := f.fullPath(prefix)
+
+	exists, err := f.prefixExists(prefix)
+	if err != nil {
+		return fmt.Errorf("checking path: %w", err)
+	}
+
+	if !exists {
+		return nil
+	}
+
+	err = f.walk(basePath, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+
+		if info.IsDir() || !strings.HasSuffix(info.Name(), tempSuffix) {
+			return nil
+		}
+
+		return f.fs.Remove(path)
+	})
+	if err != nil {
+		return fmt.Errorf("walking directory: %w", err)
+	}
+
+	return nil
+}
+
 // Info returns human-readable storage location information.
 func (f *FileStorer) Info() Info {
 	return Info{
@@ -260,7 +304,19 @@ func (f *FileStorer) writeAtomic(
 	path := f.fullPath(key)
 	dir := filepath.Dir(path)
 
-	err := f.fs.MkdirAll(dir, storageDirPerm)
+	// Checked on every write, so a destination that disappears part-way
+	// through a backup fails it rather than being recreated by MkdirAll.
+	_, err := f.fs.Stat(f.basePath)
+	if os.IsNotExist(err) {
+		return fmt.Errorf("destination directory does not exist; "+
+			"create it, or mount the volume it is on: %w", err)
+	}
+
+	if err != nil {
+		return fmt.Errorf("checking destination directory: %w", err)
+	}
+
+	err = f.fs.MkdirAll(dir, storageDirPerm)
 	if err != nil {
 		return fmt.Errorf("creating directories: %w", err)
 	}
@@ -315,6 +371,54 @@ func (f *FileStorer) writeAtomic(
 	return nil
 }
 
+// walk is afero.Walk, except that it reads through a symlinked directory
+// the way Get and Stat do, where afero.Walk reports the link as one file.
+// afero.Walk uses Lstat, which does not follow a link, whenever the
+// filesystem has one; the struct below carries only the afero.Fs methods,
+// so the walk uses Stat instead. A link back up the tree is followed until
+// the operating system refuses the path for too many levels of links, and
+// the walk then fails.
+func (f *FileStorer) walk(root string, fn filepath.WalkFunc) error {
+	return afero.Walk(struct{ afero.Fs }{f.fs}, root, fn)
+}
+
+// prefixExists reports whether prefix exists under the destination
+// directory. It checks each directory on the way down to prefix in turn,
+// and the first one Stat cannot find decides: if it is not there at all,
+// prefix is missing; if it is a symlink whose target is missing, such as
+// a link to a volume that is not mounted, prefixExists fails, since
+// listing it as empty would let prune delete every blob.
+func (f *FileStorer) prefixExists(prefix string) (bool, error) {
+	lstater, canLstat := f.fs.(afero.Lstater)
+	path := f.basePath
+
+	for name := range strings.SplitSeq(prefix, "/") {
+		path = filepath.Join(path, name)
+
+		_, err := f.fs.Stat(path)
+		if err == nil {
+			continue
+		}
+
+		if !os.IsNotExist(err) {
+			return false, err
+		}
+
+		// Lstat does not follow a symlink at path, so it finds the link
+		// that Stat could not follow.
+		if canLstat {
+			_, _, lstatErr := lstater.LstatIfPossible(path)
+			if lstatErr == nil {
+				return false, err
+			}
+		}
+
+		return false, nil
+	}
+
+	return true, nil
+}
+
 // fullPath returns the full filesystem path for a key.
 func (f *FileStorer) fullPath(key string) string {
 	return filepath.Join(f.basePath, key)

internal/storage/file_atomic_test.go

@@ -14,6 +14,9 @@ import (
 // errStreamInterrupted stands in for an upload cut off mid-stream.
 var errStreamInterrupted = errors.New("connection reset mid-upload")
 
+// testBlobKey is a key laid out as a blob's key is.
+const testBlobKey = "blobs/aa/bb/aabbccddeeff"
+
 // failingReader yields its data once, then fails.
 type failingReader struct {
 	data []byte
@@ -43,7 +46,7 @@ func TestFileStorer_InterruptedWriteLeavesNoTrustedObject(t *testing.T) {
 	}
 
 	ctx := context.Background()
-	key := "blobs/aa/bb/aabbccddeeff"
+	key := testBlobKey
 
 	err = f.PutWithProgress(ctx, key, &failingReader{data: []byte("partial")}, 4096, nil)
 	if err == nil {
@@ -79,7 +82,7 @@ func TestFileStorer_ListSkipsPartialFiles(t *testing.T) {
 	}
 
 	ctx := context.Background()
-	realKey := "blobs/aa/bb/aabbccddeeff"
+	realKey := testBlobKey
 
 	err = f.Put(ctx, realKey, strings.NewReader("blob-bytes"))
 	if err != nil {
@@ -117,3 +120,45 @@ func TestFileStorer_ListSkipsPartialFiles(t *testing.T) {
 		t.Fatalf("ListStream should return only the real key, got %v", streamed)
 	}
 }
+
+// TestFileStorer_DeletePartialUploads checks that a leftover temp file is
+// removed and the object at the real key is kept.
+func TestFileStorer_DeletePartialUploads(t *testing.T) {
+	t.Parallel()
+
+	base := t.TempDir()
+
+	f, err := storage.NewFileStorer(base)
+	if err != nil {
+		t.Fatalf("NewFileStorer: %v", err)
+	}
+
+	ctx := context.Background()
+
+	err = f.Put(ctx, testBlobKey, strings.NewReader("blob-bytes"))
+	if err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+
+	leftover := filepath.Join(base, testBlobKey+"-123456.partial")
+
+	err = os.WriteFile(leftover, []byte("half"), 0o600)
+	if err != nil {
+		t.Fatalf("writing leftover temp file: %v", err)
+	}
+
+	err = f.DeletePartialUploads(ctx, "blobs/")
+	if err != nil {
+		t.Fatalf("DeletePartialUploads: %v", err)
+	}
+
+	_, err = os.Stat(leftover)
+	if !os.IsNotExist(err) {
+		t.Errorf("leftover temp file was not removed: %v", err)
+	}
+
+	_, err = f.Stat(ctx, testBlobKey)
+	if err != nil {
+		t.Errorf("Stat of the real key: %v", err)
+	}
+}

internal/storage/file_backend_test.go

@@ -4,7 +4,10 @@ import (
 	"context"
 	"errors"
 	"io/fs"
+	"os"
 	"path/filepath"
+	"reflect"
+	"strings"
 	"testing"
 
 	"sneak.berlin/go/vaultik/internal/storage"
@@ -60,3 +63,272 @@ func TestFileStorerListMissingDestination(t *testing.T) {
 		t.Errorf("ListStream error = %v, want a not-exist error", streamErr)
 	}
 }
+
+// The two directories at the top of a destination, either of which the
+// tests below replace with a symlink.
+const (
+	metadataDir = "metadata"
+	blobsDir    = "blobs"
+)
+
+// moveBehindSymlink moves base/dir to a directory elsewhere and puts a
+// symlink to it in its place.
+func moveBehindSymlink(t *testing.T, base, dir string) {
+	t.Helper()
+
+	linkPath := filepath.Join(base, dir)
+	movedPath := filepath.Join(t.TempDir(), dir)
+
+	err := os.Rename(linkPath, movedPath)
+	if err != nil {
+		t.Fatalf("moving %s away: %v", dir, err)
+	}
+
+	err = os.Symlink(movedPath, linkPath)
+	if err != nil {
+		t.Fatalf("linking %s: %v", dir, err)
+	}
+}
+
+// TestFileStorerListsThroughSymlinkedDirectory checks that List and
+// ListStream read through a symlinked metadata/ or blobs/ directory, as Get
+// and Stat do, instead of listing the link as one key. Listing the whole
+// destination meets the link part-way through the walk; listing its prefix
+// starts the walk at the link. A prefix missing behind the link lists as
+// empty.
+func TestFileStorerListsThroughSymlinkedDirectory(t *testing.T) {
+	t.Parallel()
+
+	for _, dir := range []string{metadataDir, blobsDir} {
+		t.Run(dir, func(t *testing.T) {
+			t.Parallel()
+
+			base := t.TempDir()
+			key := dir + "/aa/bb/object"
+
+			s, err := storage.NewFileStorer(base)
+			if err != nil {
+				t.Fatalf("NewFileStorer: %v", err)
+			}
+
+			err = s.Put(context.Background(), key, strings.NewReader("data"))
+			if err != nil {
+				t.Fatalf("Put: %v", err)
+			}
+
+			moveBehindSymlink(t, base, dir)
+
+			want := []string{key}
+
+			for _, prefix := range []string{"", dir + "/"} {
+				got := listSorted(t, s, prefix)
+				if !reflect.DeepEqual(got, want) {
+					t.Errorf("List(%q) = %v, want %v", prefix, got, want)
+				}
+
+				got = listStreamKeys(t, s, prefix)
+				if !reflect.DeepEqual(got, want) {
+					t.Errorf("ListStream(%q) = %v, want %v", prefix, got, want)
+				}
+			}
+
+			absent := dir + "/absent/"
+
+			if got := listSorted(t, s, absent); len(got) != 0 {
+				t.Errorf("List(%q) = %v, want empty", absent, got)
+			}
+
+			if got := listStreamKeys(t, s, absent); len(got) != 0 {
+				t.Errorf("ListStream(%q) = %v, want empty", absent, got)
+			}
+		})
+	}
+}
+
+// TestFileStorerListFailsOnSymlinkWithMissingTarget checks that List and
+// ListStream fail on a symlinked metadata/ or blobs/ directory whose target
+// is missing, such as a link to a volume that is not mounted, as they do on
+// a missing destination directory, instead of listing it as empty. That
+// holds for a prefix below the link too.
+func TestFileStorerListFailsOnSymlinkWithMissingTarget(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+
+	for _, dir := range []string{metadataDir, blobsDir} {
+		t.Run(dir, func(t *testing.T) {
+			t.Parallel()
+
+			base := t.TempDir()
+
+			s, err := storage.NewFileStorer(base)
+			if err != nil {
+				t.Fatalf("NewFileStorer: %v", err)
+			}
+
+			unmounted := filepath.Join(t.TempDir(), "unmounted")
+
+			err = os.Symlink(unmounted, filepath.Join(base, dir))
+			if err != nil {
+				t.Fatalf("Symlink: %v", err)
+			}
+
+			for _, prefix := range []string{"", dir + "/", dir + "/aa/"} {
+				keys, err := s.List(ctx, prefix)
+				if !errors.Is(err, fs.ErrNotExist) {
+					t.Errorf("List(%q) = %v, %v; want a not-exist error",
+						prefix, keys, err)
+				}
+
+				var streamErr error
+
+				for object := range s.ListStream(ctx, prefix) {
+					if object.Err != nil {
+						streamErr = object.Err
+					}
+				}
+
+				if !errors.Is(streamErr, fs.ErrNotExist) {
+					t.Errorf("ListStream(%q) error = %v, want a not-exist error",
+						prefix, streamErr)
+				}
+			}
+		})
+	}
+}
+
+// TestFileStorerListFailsOnSymlinkLoop checks that a symlink pointing back
+// at the destination makes List and ListStream fail instead of walking it
+// forever.
+func TestFileStorerListFailsOnSymlinkLoop(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	base := t.TempDir()
+
+	s, err := storage.NewFileStorer(base)
+	if err != nil {
+		t.Fatalf("NewFileStorer: %v", err)
+	}
+
+	err = s.Put(ctx, testBlobKey, strings.NewReader("data"))
+	if err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+
+	err = os.Symlink(base, filepath.Join(base, "blobs", "loop"))
+	if err != nil {
+		t.Fatalf("Symlink: %v", err)
+	}
+
+	keys, err := s.List(ctx, "blobs/")
+	if err == nil {
+		t.Errorf("List = %d keys and no error, want an error", len(keys))
+	}
+
+	var streamErr error
+
+	for object := range s.ListStream(ctx, "blobs/") {
+		if object.Err != nil {
+			streamErr = object.Err
+		}
+	}
+
+	if streamErr == nil {
+		t.Error("ListStream sent no error, want one")
+	}
+}
+
+// TestFileStorerDeletePartialUploadsThroughSymlinkedDirectory checks that
+// DeletePartialUploads, which remote nuke uses, removes a leftover temp
+// file behind a symlinked metadata/ or blobs/ directory and keeps the
+// object at the real key.
+func TestFileStorerDeletePartialUploadsThroughSymlinkedDirectory(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+
+	for _, dir := range []string{metadataDir, blobsDir} {
+		t.Run(dir, func(t *testing.T) {
+			t.Parallel()
+
+			base := t.TempDir()
+			key := dir + "/aa/bb/object"
+
+			s, err := storage.NewFileStorer(base)
+			if err != nil {
+				t.Fatalf("NewFileStorer: %v", err)
+			}
+
+			err = s.Put(ctx, key, strings.NewReader("data"))
+			if err != nil {
+				t.Fatalf("Put: %v", err)
+			}
+
+			leftover := filepath.Join(base, key+"-123456.partial")
+
+			err = os.WriteFile(leftover, []byte("half"), 0o600)
+			if err != nil {
+				t.Fatalf("writing leftover temp file: %v", err)
+			}
+
+			moveBehindSymlink(t, base, dir)
+
+			err = s.DeletePartialUploads(ctx, dir+"/")
+			if err != nil {
+				t.Fatalf("DeletePartialUploads: %v", err)
+			}
+
+			// leftover runs through the link.
+			_, err = os.Stat(leftover)
+			if !os.IsNotExist(err) {
+				t.Errorf("leftover temp file was not removed: %v", err)
+			}
+
+			_, err = s.Stat(ctx, key)
+			if err != nil {
+				t.Errorf("Stat of the real key: %v", err)
+			}
+		})
+	}
+}
+
+// TestFileStorerPutMissingDestination checks that a write fails when the
+// destination directory has gone, even after earlier writes to it
+// succeeded, and that it does not create the directory again.
+func TestFileStorerPutMissingDestination(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	base := filepath.Join(t.TempDir(), "usbstick")
+
+	err := os.Mkdir(base, 0o750)
+	if err != nil {
+		t.Fatalf("Mkdir: %v", err)
+	}
+
+	s, err := storage.NewFileStorer(base)
+	if err != nil {
+		t.Fatalf("NewFileStorer: %v", err)
+	}
+
+	err = s.Put(ctx, "blobs/aa/bb/first", strings.NewReader("first"))
+	if err != nil {
+		t.Fatalf("first Put: %v", err)
+	}
+
+	err = os.Rename(base, base+"-unplugged")
+	if err != nil {
+		t.Fatalf("Rename: %v", err)
+	}
+
+	err = s.Put(ctx, "blobs/aa/bb/second", strings.NewReader("second"))
+	if !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("Put = %v, want a not-exist error", err)
+	}
+
+	_, err = os.Stat(base)
+	if !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("Put created the destination directory again (Stat = %v)", err)
+	}
+}

internal/storage/rclone.go

@@ -3,13 +3,16 @@ package storage
 import (
 	"bytes"
 	"context"
+	"crypto/rand"
 	"errors"
 	"fmt"
 	"io"
+	"os"
 	"strings"
 	"time"
 
 	"github.com/rclone/rclone/fs"
+	"github.com/rclone/rclone/fs/config"
 	"github.com/rclone/rclone/fs/config/configfile"
 	"github.com/rclone/rclone/fs/operations"
 
@@ -32,6 +35,15 @@ type RcloneStorer struct {
 // The remote parameter is the rclone remote name (as configured via `rclone config`).
 // The path parameter is the path within the remote.
 func NewRcloneStorer(ctx context.Context, remote, path string) (*RcloneStorer, error) {
+	// rclone reads RCLONE_CONFIG only as the value of its --config flag,
+	// which vaultik does not have, so it is applied here as that flag would.
+	if configPath, ok := os.LookupEnv("RCLONE_CONFIG"); ok {
+		err := config.SetConfigPath(configPath)
+		if err != nil {
+			return nil, fmt.Errorf("using RCLONE_CONFIG %q: %w", configPath, err)
+		}
+	}
+
 	// Install the default config file handler
 	configfile.Install()
 
@@ -41,6 +53,14 @@ func NewRcloneStorer(ctx context.Context, remote, path string) (*RcloneStorer, e
 		rclonePath += path
 	}
 
+	// On S3, Swift and some other remotes rclone keeps a time of its own in
+	// each object's metadata, which costs one request per object to read.
+	// rclone's use_server_modtime setting makes ModTime the time the
+	// listing gives instead: when the object was stored, which is what
+	// prune compares with prune_grace_period.
+	ctx, ci := fs.AddConfig(ctx)
+	ci.UseServerModTime = true
+
 	// Create the rclone filesystem
 	fsys, err := fs.NewFs(ctx, rclonePath)
 	if err != nil {
@@ -68,14 +88,7 @@ func (r *RcloneStorer) Put(ctx context.Context, key string, data io.Reader) erro
 		return fmt.Errorf("reading data: %w", err)
 	}
 
-	// Upload the object
+	return r.upload(ctx, key, bytes.NewReader(buf))
-	_, err = operations.Rcat(ctx, r.fsys, key,
-		io.NopCloser(bytes.NewReader(buf)), time.Now(), nil)
-	if err != nil {
-		return fmt.Errorf("uploading object: %w", err)
-	}
-
-	return nil
 }
 
 // PutWithProgress stores data with progress reporting.
@@ -89,13 +102,7 @@ func (r *RcloneStorer) PutWithProgress(
 		callback: progress,
 	}
 
-	// Upload the object
+	return r.upload(ctx, key, pr)
-	_, err := operations.Rcat(ctx, r.fsys, key, io.NopCloser(pr), time.Now(), nil)
-	if err != nil {
-		return fmt.Errorf("uploading object: %w", err)
-	}
-
-	return nil
 }
 
 // Get retrieves data from the specified key.
@@ -173,6 +180,10 @@ func (r *RcloneStorer) List(ctx context.Context, prefix string) ([]string, error
 
 	err := operations.ListFn(ctx, r.fsys, func(obj fs.Object) {
 		key := obj.Remote()
+		if strings.HasSuffix(key, tempSuffix) {
+			return
+		}
+
 		if prefix == "" || strings.HasPrefix(key, prefix) {
 			keys = append(keys, key)
 		}
@@ -202,10 +213,15 @@ func (r *RcloneStorer) ListStream(
 			}
 
 			key := obj.Remote()
+			if strings.HasSuffix(key, tempSuffix) {
+				return
+			}
+
 			if prefix == "" || strings.HasPrefix(key, prefix) {
 				ch <- ObjectInfo{
-					Key:  key,
+					Key:     key,
-					Size: obj.Size(),
+					Size:    obj.Size(),
+					ModTime: obj.ModTime(ctx),
 				}
 			}
 		})
@@ -217,6 +233,31 @@ func (r *RcloneStorer) ListStream(
 	return ch
 }
 
+// DeletePartialUploads removes every object under prefix whose name ends
+// in tempSuffix.
+func (r *RcloneStorer) DeletePartialUploads(ctx context.Context, prefix string) error {
+	var partial []fs.Object
+
+	err := operations.ListFn(ctx, r.fsys, func(obj fs.Object) {
+		key := obj.Remote()
+		if strings.HasPrefix(key, prefix) && strings.HasSuffix(key, tempSuffix) {
+			partial = append(partial, obj)
+		}
+	})
+	if err != nil {
+		return fmt.Errorf("listing objects: %w", err)
+	}
+
+	for _, obj := range partial {
+		err = obj.Remove(ctx)
+		if err != nil {
+			return fmt.Errorf("removing object: %w", err)
+		}
+	}
+
+	return nil
+}
+
 // Info returns human-readable storage location information.
 func (r *RcloneStorer) Info() Info {
 	location := r.remote
@@ -230,6 +271,59 @@ func (r *RcloneStorer) Info() Info {
 	}
 }
 
+// upload writes data to key. Where the remote has a server-side move, it
+// writes under a temporary name ending in tempSuffix and moves the object
+// onto key once it is complete, so a killed upload cannot leave a truncated
+// object at key; a remote without one is written in place. List and
+// ListStream skip a temporary object left behind.
+//
+// rclone's own copy does this only where the remote also sets
+// PartialUploads. That flag is not checked here: hdfs, for one, shows a
+// file while it is written without setting it.
+func (r *RcloneStorer) upload(ctx context.Context, key string, data io.Reader) error {
+	if r.fsys.Features().Move == nil {
+		_, err := operations.Rcat(ctx, r.fsys, key, io.NopCloser(data), time.Now(), nil)
+		if err != nil {
+			return fmt.Errorf("uploading object: %w", err)
+		}
+
+		return nil
+	}
+
+	tempKey := key + "-" + rand.Text() + tempSuffix
+
+	obj, err := operations.Rcat(ctx, r.fsys, tempKey, io.NopCloser(data), time.Now(), nil)
+	if err != nil {
+		// Rcat returns the object it wrote when the written data fails its check.
+		if obj != nil {
+			_ = obj.Remove(ctx)
+		}
+
+		return fmt.Errorf("uploading object: %w", err)
+	}
+
+	// On drive, dropbox, onedrive and others the remote's own move does not
+	// replace an object already at key. operations.Move removes the object
+	// it is given first, and copies where the remote refuses the move.
+	existing, err := r.fsys.NewObject(ctx, key)
+	if errors.Is(err, fs.ErrorObjectNotFound) {
+		existing = nil
+	} else if err != nil {
+		_ = obj.Remove(ctx)
+
+		return fmt.Errorf("looking up existing object: %w", err)
+	}
+
+	_, err = operations.Move(ctx, r.fsys, existing, key, obj)
+	if err != nil {
+		_ = obj.Remove(ctx)
+
+		return fmt.Errorf("moving object into place: %w", err)
+	}
+
+	return nil
+}
+
 // progressReader wraps an io.Reader to track read progress.
 type progressReader struct {
 	reader   io.Reader

internal/storage/rclone_test.go

@@ -1,28 +1,54 @@
 package storage_test
 
 import (
+	"bytes"
 	"context"
 	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
 	"testing"
+	"time"
 
+	"github.com/johannesboyne/gofakes3"
+	"github.com/johannesboyne/gofakes3/backend/s3mem"
+	"github.com/rclone/rclone/fs"
+	"github.com/rclone/rclone/fs/config"
+	"github.com/rclone/rclone/fs/config/configmap"
 	"sneak.berlin/go/vaultik/internal/storage"
 )
 
-// The rclone backend is a thin adapter over the rclone library: it turns a
-// (remote, path) pair into rclone's "remote:path" string, hands it to
-// rclone, and maps rclone's own results back to the Storer interface. What
-// can be tested in-process, without a configured remote or network, is that
-// adapter layer — how the arguments are shaped and how construction errors
-// are reported. The data-plane operations (Put/Get/List/Delete) are rclone's
-// own, exercised against a real provider (drive, s3-via-rclone, ...), which
-// needs a configured remote with credentials and network access and so is
-// out of reach of a unit test. The shared Storer conformance suite therefore
-// runs against the in-process file and s3 backends; the rclone backend
-// inherits that contract once a remote is configured.
-//
 // These tests use rclone's ":local:" on-the-fly backend, which addresses the
-// local filesystem directly without any configured remote, so construction
+// local filesystem directly without any configured remote, so they run
-// runs entirely in-process.
+// entirely in-process. A remote that needs credentials and network access
+// (drive, s3 via rclone, ...) is out of reach of a unit test.
+
+// newRcloneStorer builds an rclone backend on rclone's local backend,
+// rooted at a fresh temp directory.
+//
+//nolint:ireturn // conformance runs against the Storer interface by design
+func newRcloneStorer(t *testing.T) storage.Storer {
+	t.Helper()
+
+	s, err := storage.NewRcloneStorer(context.Background(), ":local", t.TempDir())
+	if err != nil {
+		t.Fatalf("NewRcloneStorer: %v", err)
+	}
+
+	return s
+}
+
+// TestRcloneStorer runs the shared Storer contract against the rclone
+// backend.
+//
+//nolint:paralleltest // NewRcloneStorer installs the process-global rclone config
+func TestRcloneStorer(t *testing.T) {
+	runStorerConformance(t, newRcloneStorer)
+}
 
 // TestNewRcloneStorerConstruction checks that a valid remote constructs a
 // backend and that Info() reports the shaped "remote:path" location.
@@ -44,6 +70,321 @@ func TestNewRcloneStorerConstruction(t *testing.T) {
 	}
 }
 
+// unbufferedUploadContext returns a context in which rclone neither reads
+// ahead of the write nor holds a small upload in memory. Without it, a
+// progress callback runs before anything is written to the remote.
+func unbufferedUploadContext() context.Context {
+	ctx, ci := fs.AddConfig(context.Background())
+	ci.BufferSize = 0
+	ci.StreamingUploadCutoff = 0
+
+	return ctx
+}
+
+// objectAtKeyDuringUpload uploads data to testBlobKey and reports whether
+// an object was at the key before the upload finished. It fails the test
+// unless the key then reads back as the uploaded data.
+func objectAtKeyDuringUpload(
+	ctx context.Context, t *testing.T, s *storage.RcloneStorer,
+) bool {
+	t.Helper()
+
+	data := bytes.Repeat([]byte("blob-bytes"), 1000)
+	seen := false
+
+	err := s.PutWithProgress(ctx, testBlobKey, bytes.NewReader(data),
+		int64(len(data)), func(int64) error {
+			_, statErr := s.Stat(ctx, testBlobKey)
+			if statErr == nil {
+				seen = true
+			}
+
+			return nil
+		})
+	if err != nil {
+		t.Fatalf("PutWithProgress: %v", err)
+	}
+
+	got := readObject(ctx, t, s, testBlobKey)
+	if !bytes.Equal(got, data) {
+		t.Errorf("object read back as %d bytes, want the %d uploaded",
+			len(got), len(data))
+	}
+
+	return seen
+}
+
+// readObject returns the contents of the object at key.
+func readObject(
+	ctx context.Context, t *testing.T, s *storage.RcloneStorer, key string,
+) []byte {
+	t.Helper()
+
+	rc, err := s.Get(ctx, key)
+	if err != nil {
+		t.Fatalf("Get: %v", err)
+	}
+
+	defer func() { _ = rc.Close() }()
+
+	got, err := io.ReadAll(rc)
+	if err != nil {
+		t.Fatalf("reading object: %v", err)
+	}
+
+	return got
+}
+
+// TestRcloneStorerObjectAppearsOnlyWhenComplete checks that on a remote
+// with a server-side move, such as local, nothing is at the key until the
+// upload has finished, so a killed upload cannot leave a truncated object
+// there.
+//
+//nolint:paralleltest // NewRcloneStorer installs the process-global rclone config
+func TestRcloneStorerObjectAppearsOnlyWhenComplete(t *testing.T) {
+	ctx := unbufferedUploadContext()
+
+	s, err := storage.NewRcloneStorer(ctx, ":local", t.TempDir())
+	if err != nil {
+		t.Fatalf("NewRcloneStorer: %v", err)
+	}
+
+	if objectAtKeyDuringUpload(ctx, t, s) {
+		t.Error("object was at its key before the upload finished")
+	}
+}
+
+// TestRcloneStorerListSkipsPartialFiles checks that a temporary file left
+// by a killed upload is never listed as a key.
+//
+//nolint:paralleltest // NewRcloneStorer installs the process-global rclone config
+func TestRcloneStorerListSkipsPartialFiles(t *testing.T) {
+	dir := t.TempDir()
+	ctx := context.Background()
+
+	s, err := storage.NewRcloneStorer(ctx, ":local", dir)
+	if err != nil {
+		t.Fatalf("NewRcloneStorer: %v", err)
+	}
+
+	realKey := testBlobKey
+
+	err = s.Put(ctx, realKey, strings.NewReader("blob-bytes"))
+	if err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+
+	leftover := filepath.Join(dir, realKey+"-123456.partial")
+
+	err = os.WriteFile(leftover, []byte("half"), 0o600)
+	if err != nil {
+		t.Fatalf("writing leftover temp file: %v", err)
+	}
+
+	keys, err := s.List(ctx, "blobs/")
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+
+	if len(keys) != 1 || keys[0] != realKey {
+		t.Fatalf("List should return only the real key, got %v", keys)
+	}
+
+	var streamed []string
+
+	for obj := range s.ListStream(ctx, "blobs/") {
+		if obj.Err != nil {
+			t.Fatalf("ListStream: %v", obj.Err)
+		}
+
+		streamed = append(streamed, obj.Key)
+	}
+
+	if len(streamed) != 1 || streamed[0] != realKey {
+		t.Fatalf("ListStream should return only the real key, got %v", streamed)
+	}
+}
+
+// TestRcloneStorerDeletePartialUploads checks that a temporary file left
+// by a killed upload is removed and the object at the real key is kept.
+//
+//nolint:paralleltest // NewRcloneStorer installs the process-global rclone config
+func TestRcloneStorerDeletePartialUploads(t *testing.T) {
+	dir := t.TempDir()
+	ctx := context.Background()
+
+	s, err := storage.NewRcloneStorer(ctx, ":local", dir)
+	if err != nil {
+		t.Fatalf("NewRcloneStorer: %v", err)
+	}
+
+	err = s.Put(ctx, testBlobKey, strings.NewReader("blob-bytes"))
+	if err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+
+	leftover := filepath.Join(dir, testBlobKey+"-123456.partial")
+
+	err = os.WriteFile(leftover, []byte("half"), 0o600)
+	if err != nil {
+		t.Fatalf("writing leftover temp file: %v", err)
+	}
+
+	err = s.DeletePartialUploads(ctx, "blobs/")
+	if err != nil {
+		t.Fatalf("DeletePartialUploads: %v", err)
+	}
+
+	_, err = os.Stat(leftover)
+	if !os.IsNotExist(err) {
+		t.Errorf("leftover temp file was not removed: %v", err)
+	}
+
+	_, err = s.Stat(ctx, testBlobKey)
+	if err != nil {
+		t.Errorf("Stat of the real key: %v", err)
+	}
+}
+
+// newRcloneStorerOnWrappedLocal registers name as rclone's local backend
+// wrapped by wrap, and builds an rclone backend on it rooted at a fresh
+// temp directory. wrap changes the features the local backend reports, so
+// that it behaves like a remote a unit test cannot reach.
+func newRcloneStorerOnWrappedLocal(
+	ctx context.Context, t *testing.T, name string, wrap func(fs.Fs) fs.Fs,
+) *storage.RcloneStorer {
+	t.Helper()
+
+	fs.Register(&fs.RegInfo{
+		Name: name,
+		NewFs: func(
+			ctx context.Context, _, root string, _ configmap.Mapper,
+		) (fs.Fs, error) {
+			local, err := fs.NewFs(ctx, ":local:"+root)
+			if err != nil {
+				return nil, err
+			}
+
+			return wrap(local), nil
+		},
+	})
+
+	s, err := storage.NewRcloneStorer(ctx, ":"+name, t.TempDir())
+	if err != nil {
+		t.Fatalf("NewRcloneStorer: %v", err)
+	}
+
+	return s
+}
+
+// withoutPartialUploads is rclone's local backend with the PartialUploads
+// flag cleared. Like hdfs, it then has a server-side move and shows a file
+// while it is written, without setting that flag.
+type withoutPartialUploads struct {
+	fs.Fs
+}
+
+func (f *withoutPartialUploads) Features() *fs.Features {
+	features := *f.Fs.Features()
+	features.PartialUploads = false
+
+	return &features
+}
+
+// TestRcloneStorerMovesIntoPlaceWithoutPartialUploads checks that on a
+// remote with a server-side move nothing is at the key until the upload has
+// finished, even when rclone does not mark the remote as showing partial
+// uploads.
+//
+//nolint:paralleltest // NewRcloneStorer installs the process-global rclone config
+func TestRcloneStorerMovesIntoPlaceWithoutPartialUploads(t *testing.T) {
+	ctx := unbufferedUploadContext()
+	s := newRcloneStorerOnWrappedLocal(ctx, t, "withoutpartialuploads",
+		func(local fs.Fs) fs.Fs { return &withoutPartialUploads{Fs: local} })
+
+	if objectAtKeyDuringUpload(ctx, t, s) {
+		t.Error("object was at its key before the upload finished")
+	}
+}
+
+// withoutMove is rclone's local backend reporting no server-side move.
+type withoutMove struct {
+	fs.Fs
+}
+
+func (f *withoutMove) Features() *fs.Features {
+	features := *f.Fs.Features()
+	features.Move = nil
+
+	return &features
+}
+
+// TestRcloneStorerWritesInPlaceWithoutMove checks that on a remote with no
+// server-side move an object is written straight to its key and reads back
+// from there.
+//
+//nolint:paralleltest // NewRcloneStorer installs the process-global rclone config
+func TestRcloneStorerWritesInPlaceWithoutMove(t *testing.T) {
+	ctx := unbufferedUploadContext()
+	s := newRcloneStorerOnWrappedLocal(ctx, t, "withoutmove",
+		func(local fs.Fs) fs.Fs { return &withoutMove{Fs: local} })
+
+	if !objectAtKeyDuringUpload(ctx, t, s) {
+		t.Error("object was not at its key while it was uploaded")
+	}
+}
+
+var errNameConflict = errors.New("an object with this name already exists")
+
+// moveRefusesExisting is rclone's local backend with a server-side move
+// that, like dropbox's or onedrive's, refuses to move onto an existing
+// object.
+type moveRefusesExisting struct {
+	fs.Fs
+}
+
+func (f *moveRefusesExisting) Features() *fs.Features {
+	features := *f.Fs.Features()
+	features.Move = f.move
+
+	return &features
+}
+
+//nolint:ireturn // the signature is rclone's
+func (f *moveRefusesExisting) move(
+	ctx context.Context, src fs.Object, remote string,
+) (fs.Object, error) {
+	_, err := f.NewObject(ctx, remote)
+	if err == nil {
+		return nil, errNameConflict
+	}
+
+	return f.Fs.Features().Move(ctx, src, remote)
+}
+
+// TestRcloneStorerOverwritesWhereMoveRefusesExisting checks that writing a
+// key twice replaces the object on a remote whose server-side move will not
+// replace an existing object.
+//
+//nolint:paralleltest // NewRcloneStorer installs the process-global rclone config
+func TestRcloneStorerOverwritesWhereMoveRefusesExisting(t *testing.T) {
+	ctx := context.Background()
+	s := newRcloneStorerOnWrappedLocal(ctx, t, "moverefusesexisting",
+		func(local fs.Fs) fs.Fs { return &moveRefusesExisting{Fs: local} })
+
+	for _, content := range []string{"first", "second"} {
+		err := s.Put(ctx, testBlobKey, strings.NewReader(content))
+		if err != nil {
+			t.Fatalf("Put %q: %v", content, err)
+		}
+	}
+
+	got := readObject(ctx, t, s, testBlobKey)
+	if string(got) != "second" {
+		t.Errorf("object = %q, want %q", got, "second")
+	}
+}
+
 // TestNewRcloneStorerUnknownRemote checks that a remote that is not in the
 // rclone config fails construction with the ErrRemoteNotFound sentinel,
 // rather than silently returning a backend pointed nowhere.
@@ -56,3 +397,110 @@ func TestNewRcloneStorerUnknownRemote(t *testing.T) {
 		t.Errorf("NewRcloneStorer error = %v, want ErrRemoteNotFound", err)
 	}
 }
+
+// TestNewRcloneStorerReadsRcloneConfigEnv checks that a remote defined only
+// in the file RCLONE_CONFIG names is found and written to, as rclone itself
+// would.
+func TestNewRcloneStorerReadsRcloneConfigEnv(t *testing.T) {
+	// rclone keeps the config file path in a process-global variable, which
+	// NewRcloneStorer leaves pointing at this test's file.
+	previous := config.GetConfigPath()
+
+	t.Cleanup(func() { _ = config.SetConfigPath(previous) })
+
+	confFile := filepath.Join(t.TempDir(), "rclone.conf")
+
+	err := os.WriteFile(confFile, []byte("[loc]\ntype = local\n"), 0o600)
+	if err != nil {
+		t.Fatalf("writing rclone config: %v", err)
+	}
+
+	t.Setenv("RCLONE_CONFIG", confFile)
+
+	dir := t.TempDir()
+	ctx := context.Background()
+
+	s, err := storage.NewRcloneStorer(ctx, "loc", dir)
+	if err != nil {
+		t.Fatalf("NewRcloneStorer: %v", err)
+	}
+
+	err = s.Put(ctx, testBlobKey, strings.NewReader("blob-bytes"))
+	if err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+
+	_, err = os.Stat(filepath.Join(dir, testBlobKey))
+	if err != nil {
+		t.Errorf("object is not in the remote's directory: %v", err)
+	}
+}
+
+// TestRcloneListStreamOnS3MakesNoRequestPerObject checks that listing an
+// rclone S3 remote takes each object's time from the listing itself. By
+// default rclone reads the time it keeps in each object's metadata, one
+// request per object, and every command that lists the destination store
+// would slow down as it grows.
+//
+//nolint:paralleltest // NewRcloneStorer installs the process-global rclone config
+func TestRcloneListStreamOnS3MakesNoRequestPerObject(t *testing.T) {
+	backend := s3mem.New()
+
+	err := backend.CreateBucket(s3TestBucket)
+	if err != nil {
+		t.Fatalf("create bucket: %v", err)
+	}
+
+	const body = "blob-bytes"
+
+	_, err = backend.PutObject(s3TestBucket, testBlobKey, nil,
+		strings.NewReader(body), int64(len(body)))
+	if err != nil {
+		t.Fatalf("seed object: %v", err)
+	}
+
+	var headRequests atomic.Int64
+
+	fakeS3 := gofakes3.New(backend).Server()
+	srv := httptest.NewServer(http.HandlerFunc(
+		func(w http.ResponseWriter, r *http.Request) {
+			if r.Method == http.MethodHead {
+				headRequests.Add(1)
+			}
+
+			fakeS3.ServeHTTP(w, r)
+		}))
+	t.Cleanup(srv.Close)
+
+	remote := ":s3,provider=Other" +
+		",access_key_id=" + s3TestAccessKeyID +
+		",secret_access_key=" + s3TestSecretAccessKey +
+		",endpoint='" + srv.URL + "'"
+	ctx := context.Background()
+
+	s, err := storage.NewRcloneStorer(ctx, remote, s3TestBucket)
+	if err != nil {
+		t.Fatalf("NewRcloneStorer: %v", err)
+	}
+
+	headRequests.Store(0)
+
+	var listed []storage.ObjectInfo
+
+	for info := range s.ListStream(ctx, "blobs/") {
+		listed = append(listed, info)
+	}
+
+	if len(listed) != 1 || listed[0].Err != nil {
+		t.Fatalf("ListStream(\"blobs/\") = %v, want the one object", listed)
+	}
+
+	if time.Since(listed[0].ModTime).Abs() > time.Minute {
+		t.Errorf("ListStream ModTime = %v, want within a minute of now",
+			listed[0].ModTime)
+	}
+
+	if n := headRequests.Load(); n != 0 {
+		t.Errorf("ListStream made %d HEAD request(s), want none", n)
+	}
+}

internal/storage/s3.go

@@ -89,9 +89,10 @@ func (s *S3Storer) ListStream(ctx context.Context, prefix string) <-chan ObjectI
 
 		for info := range s.client.ListObjectsStream(ctx, prefix, false) {
 			ch <- ObjectInfo{
-				Key:  info.Key,
+				Key:     info.Key,
-				Size: info.Size,
+				Size:    info.Size,
-				Err:  info.Err,
+				ModTime: info.ModTime,
+				Err:     info.Err,
 			}
 		}
 	}()
@@ -99,6 +100,12 @@ func (s *S3Storer) ListStream(ctx context.Context, prefix string) <-chan ObjectI
 	return ch
 }
 
+// DeletePartialUploads has nothing to remove: S3 shows an object only once
+// its upload has completed, so an upload cut off part-way leaves none.
+func (s *S3Storer) DeletePartialUploads(_ context.Context, _ string) error {
+	return nil
+}
+
 // Info returns human-readable storage location information.
 func (s *S3Storer) Info() Info {
 	return Info{

internal/storage/s3_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"errors"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"slices"
@@ -22,13 +23,16 @@ import (
 // s3TestBucket is the bucket created for each in-process S3 server.
 const s3TestBucket = "test-bucket"
 
-// Credentials for the tests that build a storer from a config.Config. The
+// Credentials for the tests' S3 clients. The test servers accept any.
-// in-process S3 server accepts any.
 const (
 	s3TestAccessKeyID     = "key"
 	s3TestSecretAccessKey = "secret"
 )
 
+// s3TestRegion is the region of the S3 clients built here with
+// s3.NewClient. The test servers ignore it.
+const s3TestRegion = "us-east-1"
+
 // newS3Storer builds an s3:// backend backed by a fresh in-process
 // S3 server. It reuses the same in-memory S3 harness (gofakes3 + s3mem
 // over httptest) that internal/s3 and the not-found regression test use,
@@ -55,7 +59,7 @@ func newS3Storer(t *testing.T) storage.Storer {
 		Bucket:          s3TestBucket,
 		AccessKeyID:     "test",
 		SecretAccessKey: "test",
-		Region:          "us-east-1",
+		Region:          s3TestRegion,
 	})
 	if err != nil {
 		t.Fatalf("new client: %v", err)
@@ -93,8 +97,71 @@ func TestS3StorerMissingKeyMapsToErrNotFound(t *testing.T) {
 	}
 }
 
+// TestS3ListingCutShortIsAnError checks that List and ListStream fail on a
+// listing page marked truncated that carries no continuation token, as a
+// server answering V2 listings V1-style sends it. Taken as the last page,
+// it would hide every later key: prune would treat the blobs of the
+// snapshots listed there as unreferenced, and a directory under metadata/
+// whose manifest is listed there as one with no manifest.
+func TestS3ListingCutShortIsAnError(t *testing.T) {
+	t.Parallel()
+
+	const (
+		prefix        = "metadata/"
+		truncatedPage = `<?xml version="1.0" encoding="UTF-8"?>
+<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+  <Name>test-bucket</Name>
+  <Prefix>metadata/</Prefix>
+  <KeyCount>1</KeyCount>
+  <MaxKeys>1</MaxKeys>
+  <IsTruncated>true</IsTruncated>
+  <Contents>
+    <Key>metadata/snap/manifest.json.zst</Key>
+    <Size>8</Size>
+  </Contents>
+</ListBucketResult>`
+	)
+
+	srv := httptest.NewServer(http.HandlerFunc(
+		func(w http.ResponseWriter, _ *http.Request) {
+			_, _ = io.WriteString(w, truncatedPage)
+		}))
+	t.Cleanup(srv.Close)
+
+	client, err := s3.NewClient(context.Background(), s3.Config{
+		Endpoint:        srv.URL,
+		Bucket:          s3TestBucket,
+		AccessKeyID:     s3TestAccessKeyID,
+		SecretAccessKey: s3TestSecretAccessKey,
+		Region:          s3TestRegion,
+	})
+	if err != nil {
+		t.Fatalf("new client: %v", err)
+	}
+
+	storer := storage.NewS3Storer(client)
+	ctx := context.Background()
+
+	keys, err := storer.List(ctx, prefix)
+	if !errors.Is(err, s3.ErrNoContinuationToken) {
+		t.Errorf("List = %q, %v; want ErrNoContinuationToken", keys, err)
+	}
+
+	var streamErr error
+
+	for obj := range storer.ListStream(ctx, prefix) {
+		if obj.Err != nil {
+			streamErr = obj.Err
+		}
+	}
+
+	if !errors.Is(streamErr, s3.ErrNoContinuationToken) {
+		t.Errorf("ListStream error = %v, want ErrNoContinuationToken", streamErr)
+	}
+}
+
 // TestS3URLPrefixKeyLayout pins the bucket keys an s3:// URL reads and
-// writes: the README's remote storage layout, with the prefix joined to
+// writes: the layout in docs/REPOSTRUCTURE.md, with the prefix joined to
 // each key by one "/". s3://b/p and s3://b/p/ must be the same
 // destination, or a host that writes the URL the other way finds no
 // snapshots. The listed object is put straight into the bucket, as

internal/storage/storer.go

@@ -14,6 +14,7 @@ import (
 	"context"
 	"errors"
 	"io"
+	"time"
 )
 
 // ErrNotFound is returned when an object does not exist.
@@ -27,7 +28,10 @@ type ProgressCallback func(bytesTransferred int64) error
 type ObjectInfo struct {
 	Key  string // Object key/path
 	Size int64  // Size in bytes
-	Err  error  // Error for streaming results (nil on success)
+	// ModTime is when the object was written, as the store reports it.
+	// Only ListStream sets it; Stat leaves it zero.
+	ModTime time.Time
+	Err     error // Error for streaming results (nil on success)
 }
 
 // Info provides human-readable storage configuration.
@@ -41,7 +45,8 @@ type Info struct {
 // directory for filesystem).
 type Storer interface {
 	// Put stores data at the specified key.
-	// Parent directories are created automatically for filesystem backends.
+	// The filesystem backend fails when its destination directory does
+	// not exist, and creates the directories below it as needed.
 	Put(ctx context.Context, key string, data io.Reader) error
 
 	// PutWithProgress stores data with progress reporting.
@@ -66,11 +71,18 @@ type Storer interface {
 	// For large result sets, prefer ListStream.
 	List(ctx context.Context, prefix string) ([]string, error)
 
-	// ListStream returns a channel of ObjectInfo for large result sets.
+	// ListStream returns a channel of ObjectInfo, with each object's key,
+	// size and modification time, for large result sets.
 	// The channel is closed when listing completes.
 	// If an error occurs during listing, the final item will have Err set.
 	ListStream(ctx context.Context, prefix string) <-chan ObjectInfo
 
+	// DeletePartialUploads removes every object under prefix that an
+	// upload cut off part-way left under a temporary name ending in
+	// `.partial`. The file and rclone backends' List and ListStream skip
+	// such an object.
+	DeletePartialUploads(ctx context.Context, prefix string) error
+
 	// Info returns human-readable storage location information.
 	Info() Info
 }

internal/storage/url.go

@@ -17,8 +17,10 @@ const (
 
 // Sentinel errors for storage URL parsing.
 var (
-	ErrEmptyStorageURL   = errors.New("storage URL is empty")
+	ErrEmptyStorageURL  = errors.New("storage URL is empty")
-	ErrEmptyFilePath     = errors.New("file URL path is empty")
+	ErrEmptyFilePath    = errors.New("file URL path is empty")
+	ErrRelativeFilePath = errors.New(
+		"file URL needs an absolute path, as in file:///path/to/backup")
 	ErrMissingBucket     = errors.New("s3 URL missing bucket name")
 	ErrMissingRemote     = errors.New("rclone URL missing remote name")
 	ErrUnsupportedScheme = errors.New(
@@ -28,6 +30,12 @@ var (
 		"storage URL must not carry credentials; " +
 			"set s3.access_key_id and s3.secret_access_key in the config instead")
 	ErrURLUnknownParam = errors.New("unknown query parameter in storage URL")
+	ErrURLBadQuery     = errors.New(
+		"storage URL query cannot be decoded; " +
+			"check it for a ; or a % not followed by two hex digits")
+	ErrRcloneRemoteParams = errors.New(
+		"rclone URL must not carry parameters in the remote name; " +
+			"set them on the remote with rclone config instead")
 )
 
 // URL represents a parsed storage URL.
@@ -51,17 +59,8 @@ func ParseStorageURL(rawURL string) (*URL, error) {
 		return nil, ErrEmptyStorageURL
 	}
 
-	// Handle file:// URLs
 	if after, ok := strings.CutPrefix(rawURL, "file://"); ok {
-		path := after
+		return parseFileURL(after)
-		if path == "" {
-			return nil, ErrEmptyFilePath
-		}
-
-		return &URL{
-			Scheme: schemeFile,
-			Prefix: path,
-		}, nil
 	}
 
 	if strings.HasPrefix(rawURL, "s3://") {
@@ -75,9 +74,31 @@ func ParseStorageURL(rawURL string) (*URL, error) {
 	return nil, ErrUnsupportedScheme
 }
 
+// parseFileURL parses the path that follows file://. The path must be
+// absolute: a relative one would resolve against the working directory,
+// so the destination would move with it. Percent-escapes are decoded, so
+// my%20stick names the directory "my stick"; a literal space is kept.
+func parseFileURL(rawPath string) (*URL, error) {
+	if rawPath == "" {
+		return nil, ErrEmptyFilePath
+	}
+
+	if !strings.HasPrefix(rawPath, "/") {
+		return nil, ErrRelativeFilePath
+	}
+
+	path, err := url.PathUnescape(rawPath)
+	if err != nil {
+		return nil, fmt.Errorf("invalid file URL path: %w", err)
+	}
+
+	return &URL{Scheme: schemeFile, Prefix: path}, nil
+}
+
 // parseS3URL parses an s3://bucket/prefix URL. It rejects credentials in
-// the userinfo and any query parameter other than endpoint, region and
+// the userinfo or in the endpoint parameter's userinfo, a query that
-// ssl, so a credential-bearing URL is never stored or echoed.
+// cannot be decoded, and any query parameter other than endpoint, region
+// and ssl, so a credential-bearing URL is never stored or echoed.
 func parseS3URL(rawURL string) (*URL, error) {
 	u, err := url.Parse(rawURL)
 	if err != nil {
@@ -93,13 +114,26 @@ func parseS3URL(rawURL string) (*URL, error) {
 		return nil, ErrMissingBucket
 	}
 
-	query := u.Query()
+	// u.Query() would silently drop a part it cannot decode, endpoint
+	// included. The decode error is not wrapped: it can quote the value.
+	query, err := url.ParseQuery(u.RawQuery)
+	if err != nil {
+		return nil, ErrURLBadQuery
+	}
 
 	err = rejectUnknownParams(query, "endpoint", "region", "ssl")
 	if err != nil {
 		return nil, err
 	}
 
+	// A host name never contains "@", so one in an endpoint, with or
+	// without a scheme, can only introduce userinfo.
+	for _, endpoint := range query["endpoint"] {
+		if strings.Contains(endpoint, "@") {
+			return nil, ErrURLCredentials
+		}
+	}
+
 	return &URL{
 		Scheme:   schemeS3,
 		Bucket:   bucket,
@@ -111,9 +145,23 @@ func parseS3URL(rawURL string) (*URL, error) {
 }
 
 // parseRcloneURL parses an rclone://remote/path URL. rclone:// takes no
-// query parameters, so credentials in the userinfo and any parameter at
+// query parameters, so credentials in the userinfo, parameters in the
+// remote name, a query that cannot be decoded and any query parameter at
 // all are rejected rather than silently ignored.
 func parseRcloneURL(rawURL string) (*URL, error) {
+	// The remote name runs up to the first "/", "?" or "#". It never
+	// contains a comma; one starts rclone's remote,param=value form,
+	// whose values can be credentials. This is checked before url.Parse,
+	// whose error for such a name can print part of it.
+	remote := strings.TrimPrefix(rawURL, "rclone://")
+	if end := strings.IndexAny(remote, "/?#"); end >= 0 {
+		remote = remote[:end]
+	}
+
+	if strings.Contains(remote, ",") {
+		return nil, ErrRcloneRemoteParams
+	}
+
 	u, err := url.Parse(rawURL)
 	if err != nil {
 		return nil, wrapParseError(err)
@@ -123,12 +171,19 @@ func parseRcloneURL(rawURL string) (*URL, error) {
 		return nil, ErrURLCredentials
 	}
 
-	remote := u.Host
+	remote = u.Host
 	if remote == "" {
 		return nil, ErrMissingRemote
 	}
 
-	err = rejectUnknownParams(u.Query())
+	// As in parseS3URL: u.Query() would drop a part it cannot decode, and
+	// the decode error can quote the value.
+	query, err := url.ParseQuery(u.RawQuery)
+	if err != nil {
+		return nil, ErrURLBadQuery
+	}
+
+	err = rejectUnknownParams(query)
 	if err != nil {
 		return nil, err
 	}

internal/storage/url_parse_test.go

@@ -14,7 +14,10 @@ import (
 func TestParseStorageURLValid(t *testing.T) {
 	t.Parallel()
 
-	const bucket = "mybucket"
+	const (
+		bucket     = "mybucket"
+		fileScheme = "file"
+	)
 
 	cases := []struct {
 		name string
@@ -24,7 +27,17 @@ func TestParseStorageURLValid(t *testing.T) {
 		{
 			name: "file absolute path",
 			raw:  "file:///var/backups/vaultik",
-			want: &storage.URL{Scheme: "file", Prefix: "/var/backups/vaultik"},
+			want: &storage.URL{Scheme: fileScheme, Prefix: "/var/backups/vaultik"},
+		},
+		{
+			name: "file percent-escaped path is decoded",
+			raw:  "file:///Volumes/my%20stick/backup",
+			want: &storage.URL{Scheme: fileScheme, Prefix: "/Volumes/my stick/backup"},
+		},
+		{
+			name: "file path with a literal space",
+			raw:  "file:///Volumes/my stick/backup",
+			want: &storage.URL{Scheme: fileScheme, Prefix: "/Volumes/my stick/backup"},
 		},
 		{
 			name: "s3 bucket and prefix, ssl defaults on",
@@ -90,6 +103,7 @@ func TestParseStorageURLErrors(t *testing.T) {
 	}{
 		{"empty url", "", storage.ErrEmptyStorageURL},
 		{"file empty path", "file://", storage.ErrEmptyFilePath},
+		{"file relative path", "file://dest", storage.ErrRelativeFilePath},
 		{"s3 missing bucket", "s3://", storage.ErrMissingBucket},
 		{"s3 missing bucket with path", "s3:///justprefix", storage.ErrMissingBucket},
 		{"rclone missing remote", "rclone://", storage.ErrMissingRemote},
@@ -136,6 +150,19 @@ func TestParseStorageURLRejectsCredentials(t *testing.T) {
 			wantErr: storage.ErrURLCredentials,
 			secrets: []string{key, secret, "mybucket"},
 		},
+		{
+			name: "s3 userinfo in endpoint",
+			raw: "s3://mybucket?endpoint=https://" +
+				key + ":" + secret + "@minio.example.com",
+			wantErr: storage.ErrURLCredentials,
+			secrets: []string{key, secret},
+		},
+		{
+			name:    "s3 userinfo in endpoint without scheme",
+			raw:     "s3://mybucket?endpoint=" + key + ":" + secret + "@minio.example.com",
+			wantErr: storage.ErrURLCredentials,
+			secrets: []string{key, secret},
+		},
 		{
 			name:    "s3 unknown query param",
 			raw:     "s3://mybucket?access_key=" + key + "&secret=" + secret,
@@ -189,6 +216,112 @@ func TestParseStorageURLRejectsCredentials(t *testing.T) {
 	}
 }
 
+// TestParseStorageURLRejectsRcloneRemoteParams checks that an rclone
+// remote name carrying parameters (rclone's "remote,param=value" form,
+// which can hold a credential) is rejected without echoing the value,
+// including the URLs that url.Parse itself refuses.
+func TestParseStorageURLRejectsRcloneRemoteParams(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name    string
+		raw     string
+		secrets []string // must not appear in the error message
+	}{
+		{
+			name:    "configured remote",
+			raw:     "rclone://gdrive,client_secret=topsecret/backups",
+			secrets: []string{"topsecret"},
+		},
+		{
+			name:    "remote defined inline",
+			raw:     "rclone://:s3,access_key_id=KEY,secret_access_key=SECRET/bucket",
+			secrets: []string{"KEY", "SECRET"},
+		},
+		{
+			name:    "colon in a parameter value",
+			raw:     "rclone://gdrive,client_secret=ab:cd/backups",
+			secrets: []string{"cd"},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := storage.ParseStorageURL(tc.raw)
+			if !errors.Is(err, storage.ErrRcloneRemoteParams) {
+				t.Fatalf("ParseStorageURL(%q) error = %v, want %v",
+					tc.raw, err, storage.ErrRcloneRemoteParams)
+			}
+
+			for _, secret := range tc.secrets {
+				if strings.Contains(err.Error(), secret) {
+					t.Errorf("error message leaked %q: %v", secret, err.Error())
+				}
+			}
+		})
+	}
+}
+
+// TestParseStorageURLRejectsUndecodableQuery checks that an s3 or rclone
+// URL whose query cannot be decoded is rejected, not read with that part
+// of the query left out, and that the error does not echo it.
+func TestParseStorageURLRejectsUndecodableQuery(t *testing.T) {
+	t.Parallel()
+
+	const (
+		key    = "AKIAKEY"
+		secret = "topsecret"
+	)
+
+	cases := []struct {
+		name string
+		raw  string
+	}{
+		{
+			name: "semicolon",
+			raw: "s3://mybucket/prefix?endpoint=https://" + key + ":" + secret +
+				"@minio.example.com:9000;region=us-east-1",
+		},
+		{
+			name: "bad percent escape",
+			raw: "s3://mybucket/prefix?endpoint=https://" + key + ":" + secret +
+				"%zz@minio.example.com:9000",
+		},
+		{
+			name: "rclone semicolon",
+			raw:  "rclone://gdrive/backups?token=" + secret + ";x=1",
+		},
+		{
+			name: "rclone bad percent escape",
+			raw:  "rclone://gdrive/backups?token=" + secret + "%zz",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := storage.ParseStorageURL(tc.raw)
+			if err == nil {
+				t.Fatalf("ParseStorageURL(%q) returned no error", tc.raw)
+			}
+
+			if !errors.Is(err, storage.ErrURLBadQuery) {
+				t.Errorf("ParseStorageURL(%q) error = %v, want %v",
+					tc.raw, err, storage.ErrURLBadQuery)
+			}
+
+			for _, s := range []string{key, secret, "minio.example.com"} {
+				if strings.Contains(err.Error(), s) {
+					t.Errorf("error message leaked %q: %v", s, err.Error())
+				}
+			}
+		})
+	}
+}
+
 // TestParseStorageURLParseFailureHidesURL checks that when url.Parse
 // itself fails, the wrapped error carries only the inner cause, not the
 // *url.Error whose text embeds the raw (possibly credential-bearing) URL.

internal/vaultik/blob_fetch.go

@@ -103,6 +103,9 @@ func (v *Vaultik) FetchAndDecryptBlob(
 }
 
 // FetchBlob downloads a blob and returns a reader for the encrypted data.
+// The reader is closed as soon as ctx is cancelled, which ends a read
+// blocked inside it. A storage error is returned as is: restore and deep
+// verify name the blob in their own errors.
 func (v *Vaultik) FetchBlob(
 	ctx context.Context, blobHash string,
 ) (io.ReadCloser, error) {
@@ -117,8 +120,50 @@ func (v *Vaultik) FetchBlob(
 
 	rc, err := v.Storage.Get(ctx, blobPath)
 	if err != nil {
-		return nil, fmt.Errorf("downloading blob %s: %w", shortHash(blobHash), err)
+		return nil, err
 	}
 
-	return rc, nil
+	return newCloseOnCancelReader(ctx, rc), nil
+}
+
+// closeOnCancelReader closes the reader it wraps when ctx is cancelled.
+// Not every backend's reader stops on cancel by itself (the file
+// backend's does not), and a read stalled on a slow or hung source would
+// otherwise outlast the shutdown timeout, so the process would exit
+// before restore or deep verify removed its decrypted temporary files.
+type closeOnCancelReader struct {
+	io.ReadCloser
+
+	ctx  context.Context //nolint:containedctx // Read reports its error
+	stop func() bool
+}
+
+func newCloseOnCancelReader(
+	ctx context.Context, rc io.ReadCloser,
+) *closeOnCancelReader {
+	return &closeOnCancelReader{
+		ReadCloser: rc,
+		ctx:        ctx,
+		stop:       context.AfterFunc(ctx, func() { _ = rc.Close() }),
+	}
+}
+
+// Read returns the context's error, not the closed reader's, once ctx
+// has been cancelled.
+func (r *closeOnCancelReader) Read(p []byte) (int, error) {
+	n, err := r.ReadCloser.Read(p)
+	if err != nil && r.ctx.Err() != nil {
+		return n, r.ctx.Err()
+	}
+
+	return n, err
+}
+
+// Close closes the wrapped reader, unless the cancel already closed it.
+func (r *closeOnCancelReader) Close() error {
+	if !r.stop() {
+		return nil
+	}
+
+	return r.ReadCloser.Close()
 }

internal/vaultik/blobcache.go

@@ -39,9 +39,9 @@ type blobDiskCacheEntry struct {
 // internally and will fall back to LRU eviction if curBytes exceeds
 // maxBytes. Restore passes math.MaxInt64 as maxBytes and drives
 // eviction itself via Delete() through restoreSweeper, which deletes
-// each blob the moment every file that references its chunks has been
+// each blob once no file still to be restored in this run needs it.
-// written. LRU never fires under that configuration; it is kept as a
+// LRU never fires under that configuration; it is kept as a safety net
-// safety net for callers that don't manage eviction themselves.
+// for callers that don't manage eviction themselves.
 //
 // Get/ReadAt/peak-Len counters are debugging instrumentation used by
 // tests to assert that the restore code path uses ReadAt rather than

internal/vaultik/changed_file_restore_test.go

@@ -137,7 +137,7 @@ func TestBackupAfterRemovingNewestSnapshotRestoresChangedFile(t *testing.T) {
 	fs := afero.NewOsFs()
 	tempDir := t.TempDir()
 	dataDir := filepath.Join(tempDir, "src")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	restoreDir := filepath.Join(tempDir, "restored")
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 	changedPath := filepath.Join(dataDir, "appended.bin")
@@ -184,7 +184,7 @@ func TestBackupAfterInterruptedRunRestoresChangedFile(t *testing.T) {
 	fs := afero.NewOsFs()
 	tempDir := t.TempDir()
 	dataDir := filepath.Join(tempDir, "src")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	restoreDir := filepath.Join(tempDir, "restored")
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 	changedPath := filepath.Join(dataDir, "appended.bin")

internal/vaultik/deep_verify_test.go

@@ -1,15 +1,20 @@
 package vaultik_test
 
 import (
+	"bytes"
 	"context"
+	"crypto/rand"
 	"io"
 	"os"
+	"path"
 	"path/filepath"
 	"testing"
 
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/config"
 	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/storage"
 	"sneak.berlin/go/vaultik/internal/ui"
 	"sneak.berlin/go/vaultik/internal/vaultik"
 )
@@ -30,7 +35,7 @@ func TestDeepVerifyAcceptsHealthyAndRejectsCorruptBlob(t *testing.T) {
 	tempDir := t.TempDir()
 
 	dataDir := filepath.Join(tempDir, "source")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 
 	chunkSize := int64(64 * 1024)
@@ -77,6 +82,180 @@ func TestDeepVerifyAcceptsHealthyAndRejectsCorruptBlob(t *testing.T) {
 		"deep verify should fail on a corrupted blob")
 }
 
+// TestDeepVerifyJSONCountsBlobs checks the verified and missing counts
+// that deep verify reports under --json: on a healthy snapshot, with a
+// damaged blob, and with missing blobs. Deep verify stops at the first
+// damaged blob, so the blobs read before it are the ones verified; when
+// blobs are missing it reads no blob contents, but counts every missing
+// blob.
+func TestDeepVerifyJSONCountsBlobs(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	fs := afero.NewOsFs()
+	ctx := context.Background()
+	storeDir := t.TempDir()
+
+	cfg, storer, snapshotID, keys := backUpSeveralBlobs(ctx, t, storeDir)
+
+	healthy, err := deepVerifyJSON(ctx, t, cfg, storer, snapshotID)
+	require.NoError(t, err)
+	require.Equal(t, "ok", healthy.Status)
+	require.Len(t, keys, healthy.BlobCount)
+	require.Equal(t, healthy.BlobCount, healthy.Verified)
+	require.Zero(t, healthy.Missing)
+
+	// Damage the last blob read, keeping its length, so every blob before
+	// it is read and passes first.
+	lastPath := filepath.Join(storeDir, keys[len(keys)-1])
+	blob, err := afero.ReadFile(fs, lastPath)
+	require.NoError(t, err)
+
+	blob[len(blob)/2] ^= 0xff
+	require.NoError(t, afero.WriteFile(fs, lastPath, blob, 0o600))
+
+	got, err := deepVerifyJSON(ctx, t, cfg, storer, snapshotID)
+	require.Error(t, err)
+	require.Equal(t, "failed", got.Status)
+	require.Equal(t, healthy.BlobCount-1, got.Verified)
+	require.Zero(t, got.Missing)
+
+	// Delete the first blob and the damaged last one: both must be
+	// counted as missing, not only the first one found.
+	var deletedSize int64
+
+	for _, key := range []string{keys[0], keys[len(keys)-1]} {
+		info, statErr := storer.Stat(ctx, key)
+		require.NoError(t, statErr)
+
+		deletedSize += info.Size
+
+		require.NoError(t, storer.Delete(ctx, key))
+	}
+
+	got, err = deepVerifyJSON(ctx, t, cfg, storer, snapshotID)
+	require.Error(t, err)
+	require.Equal(t, "failed", got.Status)
+	require.Equal(t, 2, got.Missing)
+	require.Equal(t, deletedSize, got.MissingSize)
+	require.Zero(t, got.Verified)
+}
+
+// TestDeepVerifyJSONCountsWrongSizeBlob checks that under --deep --json a
+// blob of the wrong size is counted in mismatched and fails the run, and
+// that the check goes on past it to count a missing blob after it. The
+// store is on disk, so the message must not call it S3.
+func TestDeepVerifyJSONCountsWrongSizeBlob(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	fs := afero.NewOsFs()
+	ctx := context.Background()
+	storeDir := t.TempDir()
+
+	cfg, storer, snapshotID, keys := backUpSeveralBlobs(ctx, t, storeDir)
+
+	// Make the first blob checked longer, and delete the last one.
+	firstPath := filepath.Join(storeDir, keys[0])
+	blob, err := afero.ReadFile(fs, firstPath)
+	require.NoError(t, err)
+
+	blob = append(blob, []byte("extra")...)
+	require.NoError(t, afero.WriteFile(fs, firstPath, blob, 0o600))
+	require.NoError(t, storer.Delete(ctx, keys[len(keys)-1]))
+
+	got, err := deepVerifyJSON(ctx, t, cfg, storer, snapshotID)
+	require.Error(t, err)
+	require.Equal(t, "failed", got.Status)
+	require.Equal(t, 1, got.Mismatched)
+	require.Equal(t, 1, got.Missing)
+	require.Zero(t, got.Verified)
+	require.Contains(t, got.ErrorMessage, "with the wrong size")
+	require.NotContains(t, got.ErrorMessage, "S3")
+}
+
+// TestDeepVerifyStopsOnBlobThatCannotBeChecked checks that a blob that is
+// present in storage but cannot be checked is not counted as missing:
+// deep verify stops and fails, saying it could not check the blob, with
+// the storage error.
+func TestDeepVerifyStopsOnBlobThatCannotBeChecked(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := t.TempDir()
+
+	cfg, storer, snapshotID, keys := backUpSeveralBlobs(ctx, t, storeDir)
+	failing := statFailingStorer{Storer: storer, failKeys: []string{keys[0]}}
+
+	got, err := deepVerifyJSON(ctx, t, cfg, failing, snapshotID)
+	require.Error(t, err)
+	require.Equal(t, "failed", got.Status)
+	require.Zero(t, got.Missing)
+	require.Contains(t, got.ErrorMessage,
+		"could not check blob "+path.Base(keys[0]))
+	require.Contains(t, got.ErrorMessage, errStatDenied.Error())
+}
+
+// backUpSeveralBlobs backs up random data, which does not compress or
+// deduplicate, so it fills at least three blobs in a store on disk at
+// storeDir. It returns the blobs' storage keys sorted, which is hash
+// order, the order deep verify reads them in.
+func backUpSeveralBlobs(
+	ctx context.Context, t *testing.T, storeDir string,
+) (*config.Config, *storage.FileStorer, string, []string) {
+	t.Helper()
+
+	fs := afero.NewOsFs()
+	tempDir := t.TempDir()
+	dataDir := filepath.Join(tempDir, "source")
+	dbPath := filepath.Join(tempDir, "index.sqlite")
+
+	chunkSize := int64(32 * 1024)
+	maxBlobSize := int64(128 * 1024)
+
+	data := make([]byte, maxBlobSize*4)
+	_, err := rand.Read(data)
+	require.NoError(t, err)
+	require.NoError(t, fs.MkdirAll(dataDir, 0o755))
+	require.NoError(t, afero.WriteFile(fs,
+		filepath.Join(dataDir, "data.bin"), data, 0o644))
+
+	cfg, storer, snapshotID := runFileStorageBackup(
+		ctx, t, fs, dataDir, storeDir, dbPath, chunkSize, maxBlobSize)
+
+	keys := storedBlobKeys(t, storeDir)
+	require.GreaterOrEqual(t, len(keys), 3)
+
+	return cfg, storer, snapshotID, keys
+}
+
+// deepVerifyJSON runs deep verify with --json on snapshotID and returns
+// the decoded result and the error RunDeepVerify returned.
+func deepVerifyJSON(
+	ctx context.Context, t *testing.T,
+	cfg *config.Config, storer storage.Storer, snapshotID string,
+) (vaultik.VerifyResult, error) {
+	t.Helper()
+
+	var out bytes.Buffer
+
+	v := &vaultik.Vaultik{
+		Config:  cfg,
+		Storage: storer,
+		Fs:      afero.NewOsFs(),
+		Stdout:  &out,
+		Stderr:  io.Discard,
+		UI:      ui.NewWithColor(io.Discard, false),
+	}
+	v.SetContext(ctx)
+
+	err := v.RunDeepVerify(snapshotID,
+		&vaultik.VerifyOptions{Deep: true, JSON: true})
+
+	return decodeVerifyResult(t, out.Bytes()), err
+}
+
 // corruptOneBlob flips a middle byte of the first blob file found under
 // blobsDir, leaving the file length unchanged.
 func corruptOneBlob(t *testing.T, fs afero.Fs, blobsDir string) {

internal/vaultik/destination_marker.go

@@ -0,0 +1,103 @@
+package vaultik
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/storage"
+)
+
+// destinationMarkerKey is the object every backup writes at the root of
+// the backup destination store. While the local index holds a snapshot
+// stored there, a destination that answers a look-up of it with not
+// found is treated as not present: an unplugged volume leaves an empty
+// directory at its mount point, which would otherwise read as a store
+// whose snapshots are all gone.
+const destinationMarkerKey = "vaultik-destination.txt"
+
+// destinationMarkerText is the whole content of the marker. It names no
+// host, path or time.
+const destinationMarkerText = "This is a vaultik backup destination store.\n"
+
+// errDestinationNotPresent is returned when the local index holds a
+// snapshot stored on the backup destination store and the store answers
+// that it has no marker.
+var errDestinationNotPresent = errors.New("backup destination store is not present")
+
+// checkDestinationMarker returns errDestinationNotPresent when the local
+// index holds a snapshot stored on the backup destination store and the
+// store answers that it has no marker. With no snapshot in the local
+// index, as on a first backup or on another machine, there is nothing to
+// check; nor when the local index is bound to a different destination
+// than the configured one, since its snapshots are stored there.
+//
+// A look-up of the marker that fails for any other reason than not
+// found is logged and otherwise ignored, because the check could not be
+// made: S3 refuses it to credentials that allow only PUT, which is all
+// a backup needs. The check exists for a file:// volume's empty mount
+// point, which always answers not found, and a destination that cannot
+// be reached fails on the next request made to it, such as the backup's
+// PUT of the marker.
+func (v *Vaultik) checkDestinationMarker() error {
+	ids, err := v.localSnapshotIDs()
+	if err != nil {
+		return fmt.Errorf("listing local snapshots: %w", err)
+	}
+
+	if len(ids) == 0 {
+		return nil
+	}
+
+	// Config is nil only in tests, which then record no binding (see
+	// EnsureStorageBinding).
+	if v.Config != nil {
+		stored, configured, err := v.storageBinding()
+		if err != nil {
+			return err
+		}
+
+		if stored != "" && stored != configured {
+			return nil
+		}
+	}
+
+	_, err = v.Storage.Stat(v.ctx, destinationMarkerKey)
+	if errors.Is(err, storage.ErrNotFound) {
+		return fmt.Errorf("%w: %s has no %s, but the local index holds "+
+			"snapshots stored there; mount the volume if it is removable, "+
+			"or if the destination was emptied on purpose, run "+
+			"'vaultik database delete' and back up again",
+			errDestinationNotPresent, v.Storage.Info().Location,
+			destinationMarkerKey)
+	}
+
+	// Info, not a warning: --cron must stay silent on a successful
+	// backup from a host whose credentials allow only PUT.
+	if err != nil {
+		log.Info("Could not check the backup destination store for its marker",
+			"key", destinationMarkerKey, "error", err)
+	}
+
+	return nil
+}
+
+// markDestination checks the backup destination store with
+// checkDestinationMarker and then writes the marker, so a first backup
+// marks its destination and a later one writes the same text again.
+func (v *Vaultik) markDestination() error {
+	err := v.checkDestinationMarker()
+	if err != nil {
+		return err
+	}
+
+	err = v.Storage.Put(v.ctx, destinationMarkerKey,
+		strings.NewReader(destinationMarkerText))
+	if err != nil {
+		return fmt.Errorf("writing %s to the backup destination store: %w",
+			destinationMarkerKey, err)
+	}
+
+	return nil
+}

internal/vaultik/destination_marker_test.go

@@ -0,0 +1,331 @@
+package vaultik_test
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"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/storage"
+	"sneak.berlin/go/vaultik/internal/storage/faultstore"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// These tests cover https://git.eeqj.de/sneak/vaultik/issues/239: a
+// file:// destination at a volume's mount point leaves an empty directory
+// behind when the volume is unplugged. While the local index holds
+// snapshots, a destination that answers that it has no
+// vaultik-destination.txt is not present, so no command may write to it
+// or conclude from it that the local snapshots are gone.
+
+// markerFile is the name of the file a backup writes at the root of the
+// destination.
+const markerFile = "vaultik-destination.txt"
+
+// backUpThenUnplugMountPoint backs up to a file:// destination, then
+// moves the destination directory away and leaves an empty directory in
+// its place, as unplugging a volume mounted there would. It returns the
+// path of that empty directory.
+func backUpThenUnplugMountPoint(
+	ctx context.Context, t *testing.T,
+) (*vaultik.Vaultik, *database.Repositories, *bytes.Buffer, string) {
+	t.Helper()
+
+	storeDir := filepath.Join(t.TempDir(), "mnt")
+	v, repos, out := backUpToFileDestination(ctx, t, storeDir)
+
+	require.NoError(t, os.Rename(storeDir, storeDir+"-unplugged"))
+	require.NoError(t, os.Mkdir(storeDir, 0o750))
+
+	return v, repos, out, storeDir
+}
+
+// assertUntouched checks that the local index still holds its one
+// snapshot and that nothing was written to the empty mount point.
+func assertUntouched(
+	ctx context.Context, t *testing.T,
+	repos *database.Repositories, storeDir string,
+) {
+	t.Helper()
+
+	snapshots, err := repos.Snapshots.ListRecent(ctx, listRecentTestLimit)
+	require.NoError(t, err)
+	assert.Len(t, snapshots, 1, "no local snapshot record may be deleted")
+
+	entries, err := os.ReadDir(storeDir)
+	require.NoError(t, err)
+	assert.Empty(t, entries, "nothing may be written to the empty mount point")
+}
+
+// TestFirstBackupWritesMarker checks that a backup writes the marker
+// file at the root of the destination.
+func TestFirstBackupWritesMarker(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	storeDir := t.TempDir()
+	backUpToFileDestination(context.Background(), t, storeDir)
+
+	assert.FileExists(t, filepath.Join(storeDir, markerFile))
+}
+
+// TestBackupRefusesDestinationWithoutMarker checks that snapshot create
+// --prune writes nothing and drops no local snapshot record when the
+// destination has no marker.
+func TestBackupRefusesDestinationWithoutMarker(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	v, repos, _, storeDir := backUpThenUnplugMountPoint(ctx, t)
+
+	err := v.CreateSnapshot(&vaultik.SnapshotCreateOptions{
+		Cron:  true,
+		Prune: true,
+	})
+	require.ErrorContains(t, err, markerFile)
+
+	assertUntouched(ctx, t, repos, storeDir)
+}
+
+// TestBackupGoesOnWhenMarkerCannotBeChecked checks that a backup goes on
+// and writes the marker when looking it up fails with an error other
+// than not found, as S3 answers credentials that allow only PUT
+// (https://git.eeqj.de/sneak/vaultik/issues/389), and that a marker
+// that is not found still stops it.
+func TestBackupGoesOnWhenMarkerCannotBeChecked(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := t.TempDir()
+	v, repos, _ := backUpToFileDestination(ctx, t, storeDir)
+
+	// Removed so the test sees the backup write it again: with the
+	// look-up failing, the backup cannot tell that it is gone.
+	markerPath := filepath.Join(storeDir, markerFile)
+	require.NoError(t, os.Remove(markerPath))
+
+	store := faultstore.New(v.Storage)
+	store.OnStat = func(key string) bool { return key == markerFile }
+	v.Storage = store
+
+	require.NoError(t, backUp(v, "second"))
+	localSnapshotID(ctx, t, repos, "second")
+	assert.FileExists(t, markerPath)
+
+	require.NoError(t, os.Remove(markerPath))
+
+	store.OnStat = nil
+
+	require.ErrorContains(t, backUp(v, "third"), markerFile)
+}
+
+// TestBackupChecksMarkerBeforeDroppingIncompleteSnapshots checks that
+// snapshot create writes nothing when the local index holds only an
+// incomplete snapshot and the destination has no marker. The backup drops
+// incomplete snapshots before it scans; checked after that, the local
+// index would hold none and nothing would be checked.
+func TestBackupChecksMarkerBeforeDroppingIncompleteSnapshots(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := t.TempDir()
+	v, repos := newFileDestinationVaultik(ctx, t, storeDir)
+
+	require.NoError(t, repos.Snapshots.Create(ctx, nil, &database.Snapshot{
+		ID:        "host_first_2026-01-02T03:04:05Z",
+		Hostname:  "host",
+		StartedAt: time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC),
+	}))
+
+	err := backUp(v, "first")
+	require.ErrorContains(t, err, markerFile)
+
+	assertUntouched(ctx, t, repos, storeDir)
+}
+
+// TestPruneRefusesDestinationWithoutMarker checks that prune fails and
+// deletes no local snapshot record when the destination has no marker.
+func TestPruneRefusesDestinationWithoutMarker(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	v, repos, _, storeDir := backUpThenUnplugMountPoint(ctx, t)
+
+	err := v.Prune(&vaultik.PruneOptions{Force: true})
+	require.ErrorContains(t, err, markerFile)
+
+	assertUntouched(ctx, t, repos, storeDir)
+}
+
+// TestPurgeRefusesDestinationWithoutMarker checks that snapshot purge
+// fails and deletes no local snapshot record when the destination has no
+// marker.
+func TestPurgeRefusesDestinationWithoutMarker(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	v, repos, _, storeDir := backUpThenUnplugMountPoint(ctx, t)
+
+	err := v.PurgeSnapshotsWithOptions(&vaultik.SnapshotPurgeOptions{
+		KeepLatest: true,
+		Force:      true,
+	})
+	require.ErrorContains(t, err, markerFile)
+
+	assertUntouched(ctx, t, repos, storeDir)
+}
+
+// TestNukeRemoteRefusesDestinationWithoutMarker checks that remote nuke
+// fails, deletes no local snapshot record, and neither reports the
+// destination empty nor advises running nuke again when the destination
+// has no marker.
+func TestNukeRemoteRefusesDestinationWithoutMarker(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	v, repos, out, storeDir := backUpThenUnplugMountPoint(ctx, t)
+
+	err := v.NukeRemote(true)
+	require.ErrorContains(t, err, markerFile)
+	assert.NotContains(t, out.String(), "now empty")
+	assert.NotContains(t, out.String(), "vaultik remote nuke --force")
+
+	assertUntouched(ctx, t, repos, storeDir)
+}
+
+// TestRemoveSnapshotWarnsWhenDestinationHasNoMarker checks that snapshot
+// remove warns that the metadata could not be removed from a destination
+// without a marker, instead of reporting that it was.
+func TestRemoveSnapshotWarnsWhenDestinationHasNoMarker(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	v, repos, out, _ := backUpThenUnplugMountPoint(ctx, t)
+
+	result, err := v.RemoveSnapshot(localSnapshotID(ctx, t, repos, "first"),
+		&vaultik.RemoveOptions{Force: true})
+	require.NoError(t, err)
+
+	assert.False(t, result.RemoteRemoved)
+	assert.Contains(t, out.String(),
+		"Could not remove snapshot metadata from remote")
+	assert.Contains(t, out.String(), markerFile)
+	assert.NotContains(t, out.String(),
+		"Removed snapshot metadata from remote storage")
+}
+
+// TestRemoveSnapshotOnlyOnDestinationFailsWithoutMarker checks that
+// snapshot remove, for a snapshot that is only on the destination, fails
+// saying the destination is not present when it has no marker, instead
+// of saying the snapshot does not exist.
+func TestRemoveSnapshotOnlyOnDestinationFailsWithoutMarker(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := filepath.Join(t.TempDir(), "mnt")
+	v, repos, _ := backUpToFileDestination(ctx, t, storeDir)
+	require.NoError(t, backUp(v, "second"))
+
+	id := localSnapshotID(ctx, t, repos, "first")
+	_, err := v.RemoveSnapshot(id,
+		&vaultik.RemoveOptions{Force: true, LocalOnly: true})
+	require.NoError(t, err)
+
+	// Unplug the volume: an empty directory stays at its mount point.
+	require.NoError(t, os.Rename(storeDir, storeDir+"-unplugged"))
+	require.NoError(t, os.Mkdir(storeDir, 0o750))
+
+	_, err = v.RemoveSnapshot(id, &vaultik.RemoveOptions{Force: true})
+	require.ErrorContains(t, err, markerFile)
+	require.ErrorContains(t, err, "mount the volume")
+
+	assertUntouched(ctx, t, repos, storeDir)
+}
+
+// TestListSnapshotsWarnsWhenDestinationHasNoMarker checks that snapshot
+// list warns and shows the local index alone when the destination has no
+// marker, without reporting the local snapshot as missing from it.
+func TestListSnapshotsWarnsWhenDestinationHasNoMarker(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	v, repos, out, _ := backUpThenUnplugMountPoint(ctx, t)
+	id := localSnapshotID(ctx, t, repos, "first")
+
+	require.NoError(t, v.ListSnapshots(false))
+
+	assert.Contains(t, out.String(), "Could not list backup destination store")
+	assert.Contains(t, out.String(), markerFile)
+	assert.Contains(t, out.String(), id)
+	assert.NotContains(t, out.String(), "not found in backup destination store")
+}
+
+// TestListSnapshotsAfterStorageURLChangeToEmptyDirectory checks that
+// snapshot list, after storage_url is changed to an empty directory,
+// warns only that the local index is bound to a different destination:
+// the local snapshots are stored at the old one, so the new one's lack
+// of a marker says nothing. With --json the local row is not on the new
+// destination, so remote_present is false, not unknown.
+func TestListSnapshotsAfterStorageURLChangeToEmptyDirectory(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	v, repos, out := backUpToFileDestination(ctx, t, t.TempDir())
+	id := localSnapshotID(ctx, t, repos, "first")
+
+	newDir := t.TempDir()
+	store, err := storage.NewFileStorer(newDir)
+	require.NoError(t, err)
+
+	v.Storage = store
+	v.Config.StorageURL = "file://" + newDir
+
+	require.NoError(t, v.ListSnapshots(false))
+
+	assert.Contains(t, out.String(), id)
+	assert.Contains(t, out.String(),
+		"local index is bound to a different backup destination")
+	assert.NotContains(t, out.String(), "Could not list backup destination store")
+	assert.NotContains(t, out.String(), markerFile)
+
+	out.Reset()
+	require.NoError(t, v.ListSnapshots(true))
+
+	rows := decodeListJSON(t, out.String())
+	require.Len(t, rows, 1)
+	require.NotNil(t, rows[0].RemotePresent)
+	assert.False(t, *rows[0].RemotePresent)
+}
+
+// TestBackupAfterNukeRemoteSucceeds checks that remote nuke leaves the
+// destination ready for a new first backup, which writes the marker
+// again.
+func TestBackupAfterNukeRemoteSucceeds(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	storeDir := t.TempDir()
+	v, _, _ := backUpToFileDestination(context.Background(), t, storeDir)
+
+	require.NoError(t, v.NukeRemote(true))
+	assert.NoFileExists(t, filepath.Join(storeDir, markerFile))
+
+	require.NoError(t, backUp(v, "second"))
+	assert.FileExists(t, filepath.Join(storeDir, markerFile))
+}

internal/vaultik/destination_validation_test.go

@@ -161,13 +161,14 @@ func TestVerifyManifestBlobsRejectsShortHash(t *testing.T) {
 		Blobs: []snapshot.BlobInfo{{Hash: "abc", CompressedSize: 1}},
 	}
 
-	verified, missing, mismatched, missingSize, err :=
+	verified, missing, mismatched, missingSize, unchecked, err :=
 		v.verifyManifestBlobs(manifest, &VerifyOptions{JSON: true})
 	require.ErrorIs(t, err, errInvalidBlobHash)
 	require.Zero(t, verified)
 	require.Zero(t, missing)
 	require.Zero(t, mismatched)
 	require.Zero(t, missingSize)
+	require.Empty(t, unchecked)
 }
 
 // TestVerifyBlobChunksRejectsNegativeLength proves a blob_chunks row with a
@@ -257,6 +258,10 @@ func (s *stubLister) List(_ context.Context, _ string) ([]string, error) {
 	return nil, errStubUnused
 }
 
+func (s *stubLister) DeletePartialUploads(_ context.Context, _ string) error {
+	return errStubUnused
+}
+
 func (s *stubLister) Info() storage.Info {
 	return storage.Info{}
 }

internal/vaultik/fault_injection_test.go

@@ -192,7 +192,7 @@ func assertRestoreRejectsDamagedBlob(
 	fs := afero.NewOsFs()
 	tempDir := t.TempDir()
 	dataDir := filepath.Join(tempDir, "src")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	restoreDir := filepath.Join(tempDir, "restored")
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 
@@ -238,7 +238,7 @@ func TestDeepVerifyCatchesLyingBackend(t *testing.T) {
 	fs := afero.NewOsFs()
 	tempDir := t.TempDir()
 	dataDir := filepath.Join(tempDir, "src")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 
 	ctx := context.Background()
@@ -290,7 +290,7 @@ func TestInterruptedBlobUploadRecordsNoUploadedBlob(t *testing.T) {
 	fs := afero.NewOsFs()
 	tempDir := t.TempDir()
 	dataDir := filepath.Join(tempDir, "src")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 
 	ctx := context.Background()
@@ -298,10 +298,6 @@ func TestInterruptedBlobUploadRecordsNoUploadedBlob(t *testing.T) {
 
 	writeFaultSourceTree(t, fs, dataDir)
 
-	// No upload succeeds, so nothing creates the destination directory.
-	// It must exist for the listing below to show that no blob survived.
-	require.NoError(t, os.Mkdir(storeDir, 0o750))
-
 	inner, err := storage.NewFileStorer(storeDir)
 	require.NoError(t, err)
 
@@ -365,7 +361,7 @@ func TestBackupRetryAfterInterruptedUploadIsRestorable(t *testing.T) {
 	fs := afero.NewOsFs()
 	tempDir := t.TempDir()
 	dataDir := filepath.Join(tempDir, "src")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	restoreDir := filepath.Join(tempDir, "restored")
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 
@@ -429,7 +425,7 @@ func TestBackupSurvivesMetadataExportInterruption(t *testing.T) {
 	fs := afero.NewOsFs()
 	tempDir := t.TempDir()
 	dataDir := filepath.Join(tempDir, "src")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 
 	ctx := context.Background()
@@ -445,6 +441,10 @@ func TestBackupSurvivesMetadataExportInterruption(t *testing.T) {
 
 	repos := database.NewRepositories(db)
 
+	// snapshot create writes the marker; this backup runs its steps one
+	// by one, so the marker is written here.
+	require.NoError(t, inner.Put(ctx, markerFile, strings.NewReader("")))
+
 	// Back up and complete with a working backend.
 	sm := newFaultSnapshotManager(fs, inner, cfg, repos)
 	scanner := newFaultScanner(fs, inner, cfg, repos)
@@ -493,8 +493,14 @@ func TestBackupSurvivesMetadataExportInterruption(t *testing.T) {
 		"shallow verify must report the missing manifest")
 
 	// snapshot list must not crash on the partial snapshot.
+	var listOut strings.Builder
+
+	reader.UI = ui.NewWithColor(&listOut, false)
 	require.NoError(t, reader.ListSnapshots(false),
 		"snapshot list must tolerate a partially-exported snapshot")
+	assert.NotContains(t, listOut.String(),
+		"Could not list backup destination store",
+		"snapshot list must read the partial snapshot from the destination")
 }
 
 // Scenario 2, repair: the process dies during the metadata export of a
@@ -511,7 +517,7 @@ func TestBackupCompletesOnlyAfterMetadataExport(t *testing.T) {
 	fs := afero.NewOsFs()
 	tempDir := t.TempDir()
 	dataDir := filepath.Join(tempDir, "src")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	restoreDir := filepath.Join(tempDir, "restored")
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 
@@ -661,17 +667,19 @@ func faultScannerFactory(
 ) snapshot.ScannerFactory {
 	return func(params snapshot.ScannerParams) *snapshot.Scanner {
 		return snapshot.NewScanner(snapshot.ScannerConfig{
-			FS:               params.Fs,
+			FS:                 params.Fs,
-			Storage:          storer,
+			Storage:            storer,
-			ChunkSize:        faultChunkSize,
+			ChunkSize:          faultChunkSize,
-			MaxBlobSize:      faultMaxBlobSize,
+			MaxBlobSize:        faultMaxBlobSize,
-			CompressionLevel: cfg.CompressionLevel,
+			CompressionLevel:   cfg.CompressionLevel,
-			AgeRecipients:    cfg.AgeRecipients,
+			AgeRecipients:      cfg.AgeRecipients,
-			Repositories:     repos,
+			Repositories:       repos,
-			EnableProgress:   params.EnableProgress,
+			EnableProgress:     params.EnableProgress,
-			UI:               params.UI,
+			UI:                 params.UI,
-			Exclude:          params.Exclude,
+			Exclude:            params.Exclude,
-			SkipErrors:       params.SkipErrors,
+			SkipErrors:         params.SkipErrors,
+			PreviousSnapshotID: params.PreviousSnapshotID,
+			DeviceNumber:       params.DeviceNumber,
 		})
 	}
 }
@@ -686,7 +694,7 @@ func TestRestoreReportsDiskFull(t *testing.T) {
 	osFS := afero.NewOsFs()
 	tempDir := t.TempDir()
 	dataDir := filepath.Join(tempDir, "src")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	restoreDir := filepath.Join(tempDir, "restored")
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 

internal/vaultik/helpers.go

@@ -3,6 +3,7 @@ package vaultik
 import (
 	"errors"
 	"fmt"
+	"math"
 	"regexp"
 	"strconv"
 	"strings"
@@ -47,6 +48,10 @@ const (
 	year  = 365 * day
 )
 
+// maxDuration is the largest value a time.Duration can hold, about 292
+// years.
+const maxDuration = time.Duration(math.MaxInt64)
+
 // A snapshot ID split on "_" has at least a hostname and a trailing
 // timestamp.
 const minSnapshotIDParts = 2
@@ -84,22 +89,6 @@ type SnapshotInfo struct {
 	RemotePresent    *bool            `json:"remote_present"`
 }
 
-// formatBytes formats bytes in a human-readable format
-func formatBytes(bytes int64) string {
-	const unit = 1024
-	if bytes < unit {
-		return fmt.Sprintf("%d B", bytes)
-	}
-
-	div, exp := int64(unit), 0
-	for n := bytes / unit; n >= unit; n /= unit {
-		div *= unit
-		exp++
-	}
-
-	return fmt.Sprintf("%.1f %cB", float64(bytes)/float64(div), "KMGTPE"[exp])
-}
-
 // parseSnapshotTimestamp extracts the timestamp from a snapshot ID
 // Format: hostname_snapshotname_2026-01-12T14:41:15Z
 func parseSnapshotTimestamp(snapshotID string) (time.Time, error) {
@@ -145,10 +134,10 @@ func parseSnapshotName(snapshotID, hostname string) string {
 // parseDuration parses a duration string with support for human-friendly units:
 // d/day/days, w/week/weeks, mo/month/months, y/year/years, plus standard Go
 // duration units. Following Go, m is minutes and mo is months. A bare number,
-// an unknown unit, and a negative value are all rejected. Outside the Go
+// an unknown unit, a negative value, and a total longer than maxDuration are
-// units the input must be whole numbers each followed directly by a unit
+// all rejected. Outside the Go units the input must be whole numbers each
-// (2w3d), so 1.0y and 30 days are errors; decimals work only in Go units
+// followed directly by a unit (2w3d), so 1.0y and 30 days are errors;
-// (1.5h).
+// decimals work only in Go units (1.5h).
 func parseDuration(s string) (time.Duration, error) {
 	if strings.HasPrefix(strings.TrimSpace(s), "-") {
 		return 0, errNegativeDuration
@@ -181,19 +170,30 @@ func parseDuration(s string) (time.Duration, error) {
 			return 0, fmt.Errorf("invalid number %q: %w", match[1], err)
 		}
 
+		var unitLength time.Duration
+
 		unit := strings.ToLower(match[2])
 		switch unit {
 		case "d", "day", "days":
-			total += time.Duration(n) * day
+			unitLength = day
 		case "w", "week", "weeks":
-			total += time.Duration(n) * week
+			unitLength = week
 		case "mo", "month", "months":
-			total += time.Duration(n) * month
+			unitLength = month
 		case "y", "year", "years":
-			total += time.Duration(n) * year
+			unitLength = year
 		default:
 			return 0, fmt.Errorf("%w %q", errUnknownTimeUnit, unit)
 		}
+
+		// Past maxDuration the sum wraps to a negative value, which would
+		// put the purge cutoff in the future.
+		if time.Duration(n) > (maxDuration-total)/unitLength {
+			return 0, fmt.Errorf("%w: %q is longer than about 292 years",
+				errInvalidDuration, s)
+		}
+
+		total += time.Duration(n) * unitLength
 	}
 
 	return total, nil

internal/vaultik/helpers_test.go

@@ -111,6 +111,17 @@ func TestParseDuration(t *testing.T) {
 		{"30 days", 0, true},
 		{"30 days ago", 0, true},
 		{"x7d", 0, true},
+		// The largest time.Duration is about 292 years. A larger value
+		// must be rejected, not wrapped to a negative one, which would
+		// put the cutoff in the future and select every snapshot.
+		{"292y", 292 * 365 * 24 * time.Hour, false},
+		{"293y", 0, true},
+		{"3559mo", 0, true},
+		{"15251w", 0, true},
+		{"106752d", 0, true},
+		{"2562048h", 0, true},
+		{"200y200y", 0, true},
+		{"292y6mo", 0, true},
 	}
 
 	for _, tt := range tests {

internal/vaultik/info.go

@@ -167,10 +167,6 @@ const (
 	// metadataKeyParts is the minimum "/"-separated segment count of a
 	// metadata object key (metadata/<snapshot-id>/<filename>).
 	metadataKeyParts = 3
-
-	// blobKeyParts is the minimum "/"-separated segment count of a blob
-	// object key (blobs/<aa>/<bb>/<hash>).
-	blobKeyParts = 4
 )
 
 // SnapshotMetadataInfo contains information about a single snapshot's metadata
@@ -181,8 +177,11 @@ type SnapshotMetadataInfo struct {
 	ManifestSize int64  `json:"manifest_size"`
 	DatabaseSize int64  `json:"database_size"`
 	TotalSize    int64  `json:"total_size"`
-	BlobCount    int    `json:"blob_count"`
+
-	BlobsSize    int64  `json:"blobs_size"`
+	// Both stay nil (null in the JSON) when the snapshot's manifest was
+	// listed but could not be read.
+	BlobCount *int   `json:"blob_count"`
+	BlobsSize *int64 `json:"blobs_size"`
 
 	// Set when the listing holds this snapshot's manifest.json.zst. A
 	// backup interrupted before its manifest upload leaves a directory
@@ -380,6 +379,10 @@ func (v *Vaultik) collectReferencedBlobsFromManifests(
 	for _, snapshotID := range snapshotIDs {
 		info := snapshotMetadata[snapshotID]
 		if !info.hasManifest {
+			// The orphan figures count this directory's blobs as
+			// orphaned, so it references none.
+			info.BlobCount, info.BlobsSize = new(int), new(int64)
+
 			continue
 		}
 
@@ -395,7 +398,7 @@ func (v *Vaultik) collectReferencedBlobsFromManifests(
 			continue
 		}
 
-		info.BlobCount = manifest.BlobCount
+		blobCount := manifest.BlobCount
 
 		var blobsSize int64
 
@@ -404,7 +407,8 @@ func (v *Vaultik) collectReferencedBlobsFromManifests(
 			blobsSize += blob.CompressedSize
 		}
 
-		info.BlobsSize = blobsSize
+		info.BlobCount = &blobCount
+		info.BlobsSize = &blobsSize
 	}
 
 	return referencedBlobs, unreadable
@@ -446,23 +450,16 @@ func (v *Vaultik) scanRemoteBlobStorage(
 		v.stdoutf("Scanning blobs...\n")
 	}
 
-	blobCh := v.Storage.ListStream(v.ctx, "blobs/")
+	// Use prune's listing, so a file under blobs/ that prune would never
-	allBlobs := make(map[string]int64)
+	// delete is not counted as a blob, and so not as an orphaned one.
+	allBlobs, err := v.listAllRemoteBlobs()
+	if err != nil {
+		return err
+	}
 
-	for obj := range blobCh {
+	for _, blob := range allBlobs {
-		if obj.Err != nil {
-			return fmt.Errorf("listing blobs: %w", obj.Err)
-		}
-
-		parts := strings.Split(obj.Key, "/")
-		if len(parts) < blobKeyParts {
-			continue
-		}
-
-		hash := parts[3]
-		allBlobs[hash] = obj.Size
 		result.TotalBlobCount++
-		result.TotalBlobSize += obj.Size
+		result.TotalBlobSize += blob.Size
 	}
 
 	// A blob named only by a manifest that could not be read, or by one
@@ -477,10 +474,10 @@ func (v *Vaultik) scanRemoteBlobStorage(
 		orphanedSize  int64
 	)
 
-	for hash, size := range allBlobs {
+	for hash, blob := range allBlobs {
 		if _, referenced := referencedBlobs[hash]; !referenced {
 			orphanedCount++
-			orphanedSize += size
+			orphanedSize += blob.Size
 		}
 	}
 
@@ -516,13 +513,23 @@ func (v *Vaultik) printRemoteInfoTable(result *RemoteInfoResult) {
 		v.stdoutf("%s", separator)
 
 		for _, info := range result.Snapshots {
+			blobCount := unknownText
+			if info.BlobCount != nil {
+				blobCount = humanize.Comma(int64(*info.BlobCount))
+			}
+
+			blobsSize := unknownText
+			if info.BlobsSize != nil {
+				blobsSize = ubytes(*info.BlobsSize)
+			}
+
 			v.stdoutf(rowFormat,
 				truncateString(info.SnapshotID, snapshotIDColWidth),
 				ubytes(info.ManifestSize),
 				ubytes(info.DatabaseSize),
 				ubytes(info.TotalSize),
-				humanize.Comma(int64(info.BlobCount)),
+				blobCount,
-				ubytes(info.BlobsSize),
+				blobsSize,
 			)
 		}
 

internal/vaultik/integration_test.go

@@ -155,6 +155,12 @@ func (m *MockStorer) ListStream(
 	return ch
 }
 
+// DeletePartialUploads has nothing to remove: Put stores each object
+// under its key at once.
+func (m *MockStorer) DeletePartialUploads(_ context.Context, _ string) error {
+	return nil
+}
+
 func (m *MockStorer) Info() storage.Info {
 	return storage.Info{
 		Type:     "mock",
@@ -765,7 +771,7 @@ func TestEndToEndFileStorage(t *testing.T) {
 	tempDir := t.TempDir()
 
 	dataDir := filepath.Join(tempDir, "source")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	restoreDir := filepath.Join(tempDir, "restored")
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 
@@ -958,7 +964,7 @@ func TestDedupOnlySnapshotRestores(t *testing.T) {
 	tempDir := t.TempDir()
 
 	dataDir := filepath.Join(tempDir, "source")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	restoreDir := filepath.Join(tempDir, "restored")
 	dbPath := filepath.Join(tempDir, "index.sqlite")
 

internal/vaultik/missing_destination_test.go

@@ -24,13 +24,11 @@ import (
 // that is not plugged in, cannot be listed. It is not an empty store, so
 // no command may conclude from it that the local snapshots are gone.
 
-// backUpToFileDestination backs up the snapshot named "first" to a
+// newFileDestinationVaultik returns a Vaultik that backs up the
-// file:// destination at storeDir, which need not exist yet. Everything
+// snapshot named "first" to a file:// destination at storeDir.
-// the returned Vaultik prints after the backup goes to the returned
+func newFileDestinationVaultik(
-// buffer.
-func backUpToFileDestination(
 	ctx context.Context, t *testing.T, storeDir string,
-) (*vaultik.Vaultik, *database.Repositories, *bytes.Buffer) {
+) (*vaultik.Vaultik, *database.Repositories) {
 	t.Helper()
 
 	osFs := afero.NewOsFs()
@@ -49,8 +47,22 @@ func backUpToFileDestination(
 
 	repos := database.NewRepositories(db)
 	cfg := changedFileConfig(dataDir, dbPath)
-	v := newBackupVaultik(ctx, cfg, store, repos, db, osFs)
 
+	return newBackupVaultik(ctx, cfg, store, repos, db, osFs), repos
+}
+
+// backUpToFileDestination creates the directory storeDir, as a user must
+// before the first backup, and backs up the snapshot named "first" to a
+// file:// destination there. Everything the returned Vaultik prints
+// after the backup goes to the returned buffer.
+func backUpToFileDestination(
+	ctx context.Context, t *testing.T, storeDir string,
+) (*vaultik.Vaultik, *database.Repositories, *bytes.Buffer) {
+	t.Helper()
+
+	require.NoError(t, os.MkdirAll(storeDir, 0o750))
+
+	v, repos := newFileDestinationVaultik(ctx, t, storeDir)
 	require.NoError(t, backUp(v, "first"))
 
 	out := &bytes.Buffer{}
@@ -75,21 +87,28 @@ func backUpThenUnplug(
 	return v, repos, out
 }
 
-// TestFirstBackupCreatesDestinationDirectory checks that a first backup
+// TestBackupFailsWhenDestinationDirectoryMissing checks that a backup to
-// to a destination directory that does not exist yet creates it, and
+// a file:// destination whose directory does not exist fails before it
-// that the destination can be listed afterwards.
+// records a snapshot, and does not create the directory.
-func TestFirstBackupCreatesDestinationDirectory(t *testing.T) {
+func TestBackupFailsWhenDestinationDirectoryMissing(t *testing.T) {
 	log.Initialize(log.Config{})
 	t.Parallel()
 
 	ctx := context.Background()
-	storeDir := filepath.Join(t.TempDir(), "volume", "backup")
+	volume := filepath.Join(t.TempDir(), "volume")
-	v, _, out := backUpToFileDestination(ctx, t, storeDir)
+	v, repos := newFileDestinationVaultik(ctx, t, filepath.Join(volume, "backup"))
 
-	require.NoError(t, v.ListSnapshots(false))
+	err := backUp(v, "first")
+	require.ErrorIs(t, err, fs.ErrNotExist)
+	require.ErrorContains(t, err, "create it, or mount the volume it is on")
 
-	assert.NotContains(t, out.String(), "Could not list backup destination store")
+	_, err = os.Stat(volume)
-	assert.NotContains(t, out.String(), "not found in backup destination store")
+	require.ErrorIs(t, err, fs.ErrNotExist,
+		"the backup must not create the destination directory")
+
+	snapshots, err := repos.Snapshots.ListRecent(ctx, listRecentTestLimit)
+	require.NoError(t, err)
+	assert.Empty(t, snapshots)
 }
 
 // TestListSnapshotsWarnsWhenDestinationMissing checks that snapshot list
@@ -169,3 +188,41 @@ func TestPurgeSaysListingFailedOnceWhenDestinationMissing(t *testing.T) {
 	assert.Equal(t, 1, strings.Count(err.Error(), "listing remote snapshots"),
 		err.Error())
 }
+
+// TestNukeRemoteKeepsLocalIndexWhenDestinationMissing checks that remote
+// nuke fails on a destination it cannot list, leaves the local index
+// unchanged, and neither reports the destination empty nor advises
+// running nuke again.
+func TestNukeRemoteKeepsLocalIndexWhenDestinationMissing(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	v, repos, out := backUpThenUnplug(ctx, t)
+
+	filesBefore, err := repos.Files.ListAll(ctx)
+	require.NoError(t, err)
+	require.NotEmpty(t, filesBefore)
+
+	blobsBefore, err := repos.Blobs.GetAll(ctx)
+	require.NoError(t, err)
+	require.NotEmpty(t, blobsBefore)
+
+	err = v.NukeRemote(true)
+	require.ErrorIs(t, err, fs.ErrNotExist)
+	require.ErrorContains(t, err, "listing remote snapshots")
+	assert.NotContains(t, out.String(), "now empty")
+	assert.NotContains(t, out.String(), "vaultik remote nuke --force")
+
+	snapshots, err := repos.Snapshots.ListRecent(ctx, listRecentTestLimit)
+	require.NoError(t, err)
+	assert.Len(t, snapshots, 1, "nuke must delete no local snapshot record")
+
+	files, err := repos.Files.ListAll(ctx)
+	require.NoError(t, err)
+	assert.Len(t, files, len(filesBefore), "nuke must delete no local file record")
+
+	blobs, err := repos.Blobs.GetAll(ctx)
+	require.NoError(t, err)
+	assert.Len(t, blobs, len(blobsBefore), "nuke must delete no local blob record")
+}

internal/vaultik/new_chunk_size_test.go

@@ -0,0 +1,133 @@
+package vaultik_test
+
+import (
+	"bytes"
+	"context"
+	"maps"
+	"path/filepath"
+	"testing"
+
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/chunker"
+	"sneak.berlin/go/vaultik/internal/database"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/storage"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// TestNewChunkSizeOfChangedFileStaysFixed covers
+// https://git.eeqj.de/sneak/vaultik/issues/311. A backup whose only change
+// is a modified file lists the size of the chunks that change added as its
+// NEW CHUNK SIZE, and a later backup that changes the file again leaves
+// every earlier snapshot's figure as it was. The file's row in the local
+// index is shared by all three snapshots and rewritten by each backup.
+func TestNewChunkSizeOfChangedFileStaysFixed(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	fs := afero.NewOsFs()
+	tempDir := t.TempDir()
+	dataDir := filepath.Join(tempDir, "src")
+	dbPath := filepath.Join(tempDir, "index.sqlite")
+	changedPath := filepath.Join(dataDir, "changed.bin")
+
+	ctx := context.Background()
+	files := writeFaultSourceTree(t, fs, dataDir)
+	cfg := changedFileConfig(dataDir, dbPath)
+
+	appendRandomBytes(t, fs, files, changedPath, appendedFileSize)
+
+	store, err := storage.NewFileStorer(t.TempDir())
+	require.NoError(t, err)
+
+	db, err := database.New(ctx, dbPath)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = db.Close() })
+
+	repos := database.NewRepositories(db)
+	v := newBackupVaultik(ctx, cfg, store, repos, db, fs)
+
+	require.NoError(t, backUp(v, "first"))
+
+	firstFiles := maps.Clone(files)
+	firstID := localSnapshotID(ctx, t, repos, "first")
+
+	appendRandomBytes(t, fs, files, changedPath, faultChunkSize)
+	require.NoError(t, backUp(v, "second"))
+
+	secondID := localSnapshotID(ctx, t, repos, "second")
+	secondAdded := sizeOfNewChunks(t, files, firstFiles)
+	require.Positive(t, secondAdded)
+	assert.Equal(t, secondAdded, listedNewChunkSizes(t, v)[secondID],
+		"the second snapshot must count the chunks the change added")
+
+	appendRandomBytes(t, fs, files, changedPath, faultChunkSize)
+	require.NoError(t, backUp(v, "third"))
+
+	sizes := listedNewChunkSizes(t, v)
+	assert.Equal(t, sizeOfNewChunks(t, firstFiles, nil), sizes[firstID],
+		"a later backup must not change the first snapshot's figure")
+	assert.Equal(t, secondAdded, sizes[secondID],
+		"a later backup must not change the second snapshot's figure")
+}
+
+// sizeOfNewChunks returns the total size of the distinct chunks of the
+// files in after that no file in before has, cut the way the backup cuts
+// them.
+func sizeOfNewChunks(t *testing.T, after, before map[string][]byte) int64 {
+	t.Helper()
+
+	known := make(map[string]bool)
+	for _, chunk := range chunksOf(t, before) {
+		known[chunk.Hash] = true
+	}
+
+	var total int64
+
+	for _, chunk := range chunksOf(t, after) {
+		if !known[chunk.Hash] {
+			known[chunk.Hash] = true
+			total += chunk.Size
+		}
+	}
+
+	return total
+}
+
+// chunksOf returns the chunks of every file in files.
+func chunksOf(t *testing.T, files map[string][]byte) []chunker.Chunk {
+	t.Helper()
+
+	c := chunker.NewChunker(faultChunkSize)
+
+	var all []chunker.Chunk
+
+	for _, content := range files {
+		chunks, err := c.ChunkReader(bytes.NewReader(content))
+		require.NoError(t, err)
+
+		all = append(all, chunks...)
+	}
+
+	return all
+}
+
+// listedNewChunkSizes runs `snapshot list --json` and returns each listed
+// snapshot's new_chunk_size by snapshot ID.
+func listedNewChunkSizes(t *testing.T, v *vaultik.Vaultik) map[string]int64 {
+	t.Helper()
+
+	var out bytes.Buffer
+
+	v.Stdout = &out
+	require.NoError(t, v.ListSnapshots(true))
+
+	sizes := make(map[string]int64)
+	for _, row := range decodeListJSON(t, out.String()) {
+		sizes[row.ID] = row.NewChunkSize
+	}
+
+	return sizes
+}

internal/vaultik/nuke_remote_test.go

@@ -0,0 +1,201 @@
+package vaultik_test
+
+import (
+	"context"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/snapshot"
+	"sneak.berlin/go/vaultik/internal/storage/faultstore"
+)
+
+// TestNukeRemoteLeavesNoFiles checks that remote nuke leaves no file
+// under a file:// destination, including the `.partial` files uploads
+// killed part-way leave next to a snapshot's metadata and next to where a
+// blob would have been, a snapshot's database whose manifest was never
+// uploaded, and a file under blobs/ whose name is not a blob hash.
+func TestNukeRemoteLeavesNoFiles(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := filepath.Join(t.TempDir(), "store")
+	v, repos, out := backUpToFileDestination(ctx, t, storeDir)
+
+	snapshots, err := repos.Snapshots.ListRecent(ctx, listRecentTestLimit)
+	require.NoError(t, err)
+	require.Len(t, snapshots, 1)
+
+	snapshotKey := snapshot.RemoteSnapshotKey(snapshots[0].ID.String())
+	hash := testBlobHashA
+	leftovers := []string{
+		filepath.Join(storeDir, "metadata", snapshotKey,
+			"db.zst.age-123456.partial"),
+		filepath.Join(storeDir, "blobs", hash[:2], hash[2:4],
+			hash+"-123456.partial"),
+		filepath.Join(storeDir, "metadata",
+			snapshot.RemoteSnapshotKey("no-manifest"), "db.zst.age"),
+		filepath.Join(storeDir, "blobs", "0b", "01", ".DS_Store"),
+	}
+
+	for _, leftover := range leftovers {
+		require.NoError(t, os.MkdirAll(filepath.Dir(leftover), 0o750))
+		require.NoError(t, os.WriteFile(leftover, []byte("half an upload"), 0o600))
+	}
+
+	require.NoError(t, v.NukeRemote(true))
+
+	var files []string
+
+	err = filepath.WalkDir(storeDir,
+		func(path string, entry fs.DirEntry, err error) error {
+			if err != nil {
+				return err
+			}
+
+			if !entry.IsDir() {
+				files = append(files, path)
+			}
+
+			return nil
+		})
+	require.NoError(t, err)
+	assert.Empty(t, files)
+
+	// Nuke deletes the blobs itself, so advice to run prune is wrong.
+	assert.Contains(t, out.String(), "Backup destination store is now empty.")
+	assert.NotContains(t, out.String(), "vaultik prune")
+}
+
+// TestNukeRemoteFailsWhenADeleteFails checks that remote nuke returns an
+// error when a snapshot's metadata or a blob cannot be deleted, does not
+// report the store empty, and advises running nuke again: prune deletes
+// no snapshot metadata that has its manifest.
+func TestNukeRemoteFailsWhenADeleteFails(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	for _, refusedPrefix := range []string{"metadata/", "blobs/"} {
+		t.Run(refusedPrefix, func(t *testing.T) {
+			t.Parallel()
+
+			ctx := context.Background()
+			storeDir := filepath.Join(t.TempDir(), "store")
+			v, _, out := backUpToFileDestination(ctx, t, storeDir)
+
+			store := faultstore.New(v.Storage)
+			store.OnDelete = func(key string) bool {
+				return strings.HasPrefix(key, refusedPrefix)
+			}
+			v.Storage = store
+
+			require.Error(t, v.NukeRemote(true))
+
+			assert.NotContains(t, out.String(), "now empty")
+			assert.Contains(t, out.String(), "vaultik remote nuke --force")
+			assert.NotContains(t, out.String(), "vaultik prune")
+		})
+	}
+}
+
+// TestNukeRemoteKeepsLocalSnapshotWhoseMetadataIsNotDeleted checks that
+// remote nuke keeps a snapshot in the local index while its metadata
+// cannot be deleted from the destination store: dropped from the local
+// index, it would be left there as a remote-only snapshot without its
+// name.
+func TestNukeRemoteKeepsLocalSnapshotWhoseMetadataIsNotDeleted(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := filepath.Join(t.TempDir(), "store")
+	v, repos, _ := backUpToFileDestination(ctx, t, storeDir)
+
+	store := faultstore.New(v.Storage)
+	store.OnDelete = func(key string) bool {
+		return strings.HasPrefix(key, "metadata/")
+	}
+	v.Storage = store
+
+	require.Error(t, v.NukeRemote(true))
+
+	snapshots, err := repos.Snapshots.ListRecent(ctx, listRecentTestLimit)
+	require.NoError(t, err)
+	assert.Len(t, snapshots, 1)
+}
+
+// TestNukeRemoteNamesWhatIsLeft checks that remote nuke, when an object
+// it does not recognise cannot be deleted, does not report the store
+// empty but names that object and fails.
+func TestNukeRemoteNamesWhatIsLeft(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := filepath.Join(t.TempDir(), "store")
+	v, _, out := backUpToFileDestination(ctx, t, storeDir)
+
+	const leftKey = "blobs/0b/01/.DS_Store"
+
+	leftPath := filepath.Join(storeDir, filepath.FromSlash(leftKey))
+	require.NoError(t, os.MkdirAll(filepath.Dir(leftPath), 0o750))
+	require.NoError(t, os.WriteFile(leftPath, []byte("finder"), 0o600))
+
+	store := faultstore.New(v.Storage)
+	store.OnDelete = func(key string) bool { return key == leftKey }
+	v.Storage = store
+
+	require.Error(t, v.NukeRemote(true))
+
+	assert.Contains(t, out.String(), leftKey)
+	assert.NotContains(t, out.String(), "now empty")
+	assert.Contains(t, out.String(), "vaultik remote nuke --force")
+}
+
+// TestNukeRemoteRefusesAnotherDestinationWithoutRetryAdvice checks that
+// remote nuke, when the local index belongs to a different destination
+// than the configured one, fails without advising to run nuke again:
+// that run would fail the same way.
+func TestNukeRemoteRefusesAnotherDestinationWithoutRetryAdvice(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := filepath.Join(t.TempDir(), "store")
+	v, _, out := backUpToFileDestination(ctx, t, storeDir)
+
+	v.Config.StorageURL = "file://" + filepath.Join(t.TempDir(), "elsewhere")
+
+	err := v.NukeRemote(true)
+
+	require.ErrorContains(t, err, "bound to a different backup destination")
+	assert.NotContains(t, out.String(), "vaultik remote nuke --force")
+}
+
+// TestNukeRemoteFailsWhenALocalSnapshotCannotBeRemoved checks that a
+// snapshot remote nuke cannot remove from the local index fails the
+// run, and that nuke then does not report the destination store empty.
+func TestNukeRemoteFailsWhenALocalSnapshotCannotBeRemoved(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := filepath.Join(t.TempDir(), "store")
+	v, _, out := backUpToFileDestination(ctx, t, storeDir)
+
+	_, err := v.DB.Conn().ExecContext(ctx, `
+		CREATE TRIGGER refuse_snapshot_delete BEFORE DELETE ON snapshots
+		BEGIN SELECT RAISE(ABORT, 'simulated index error'); END`)
+	require.NoError(t, err)
+
+	require.Error(t, v.NukeRemote(true))
+
+	assert.NotContains(t, out.String(), "now empty")
+	assert.Contains(t, out.String(), "vaultik remote nuke --force")
+}

internal/vaultik/prune.go

@@ -4,9 +4,13 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"sort"
 	"strings"
+	"time"
 
 	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/snapshot"
+	"sneak.berlin/go/vaultik/internal/storage"
 )
 
 // PruneOptions contains options for the prune command
@@ -19,13 +23,39 @@ type PruneOptions struct {
 var errNukeRequiresForce = errors.New(
 	"nuke requires --force (this deletes ALL remote snapshots and blobs)")
 
+// errBlobDeleteFailed reports unreferenced blobs prune could not delete.
+var errBlobDeleteFailed = errors.New("blob(s) could not be deleted")
+
+// errMetadataDirDeleteFailed reports directories under metadata/ with no
+// manifest that prune could not delete.
+var errMetadataDirDeleteFailed = errors.New(
+	"metadata director(ies) with no manifest could not be deleted")
+
+// errObjectsLeft reports objects remote nuke still finds on the backup
+// destination store after deleting.
+var errObjectsLeft = errors.New(
+	"object(s) still on the backup destination store")
+
+// nukeCommandHint is the command suggested when a remote nuke could not
+// delete everything: running it again deletes what is left, which
+// `vaultik prune` does not do for snapshot metadata that has its
+// manifest.
+const nukeCommandHint = "vaultik remote nuke --force"
+
 // metadataDirName is the top-level remote directory holding snapshot
 // metadata.
 const metadataDirName = "metadata"
 
-// NukeRemote deletes every snapshot's metadata and every blob from remote
+// blobKeyParts is the "/"-separated segment count of a blob object key
-// storage. After this returns successfully the bucket prefix is empty and
+// (blobs/<aa>/<bb>/<hash>).
-// the next backup starts from scratch.
+const blobKeyParts = 4
+
+// NukeRemote deletes every object under metadata/ and blobs/ in remote
+// storage, whatever its name, along with any object an upload cut off
+// part-way left under a temporary `.partial` name, and last the
+// destination marker. It returns successfully only when a listing
+// afterwards finds nothing left under metadata/ and blobs/, and the next
+// backup then starts from scratch.
 //
 // Refuses to run unless force is true. The caller is responsible for
 // confirming with the user.
@@ -34,6 +64,37 @@ func (v *Vaultik) NukeRemote(force bool) error {
 		return errNukeRequiresForce
 	}
 
+	// Checked before anything is deleted: running nuke again would fail
+	// the same way, so the advice below must not follow these errors.
+	// The listing also fails on a destination that answers that it has
+	// no marker while the local index holds snapshots.
+	err := v.EnsureStorageBinding()
+	if err != nil {
+		return err
+	}
+
+	_, err = v.listAllRemoteSnapshotKeys()
+	if err != nil {
+		return err
+	}
+
+	err = v.emptyDestinationStore()
+	if err != nil {
+		v.UI.Warningf("Run '%s' again to delete what is left on the "+
+			"backup destination store.", nukeCommandHint)
+
+		return err
+	}
+
+	v.UI.Completef("Backup destination store is now empty.")
+
+	return nil
+}
+
+// emptyDestinationStore does the deleting for NukeRemote and stops at
+// the first step that fails. It also fails when objects are still
+// listed at the end, naming each one.
+func (v *Vaultik) emptyDestinationStore() error {
 	v.UI.Beginf("Removing all snapshot metadata from backup destination store.")
 
 	_, err := v.RemoveAllSnapshots(&RemoveOptions{Force: true})
@@ -41,18 +102,69 @@ func (v *Vaultik) NukeRemote(force bool) error {
 		return fmt.Errorf("removing all snapshots: %w", err)
 	}
 
-	v.UI.Beginf("Removing any blobs still present in backup destination store.")
+	v.UI.Beginf("Removing everything still present in backup destination store.")
 
-	err = v.PruneBlobs(&PruneOptions{Force: true})
+	var left []string
-	if err != nil {
+
-		return fmt.Errorf("pruning blobs: %w", err)
+	for _, prefix := range []string{"metadata/", "blobs/"} {
+		keys, err := v.deleteEverythingUnder(prefix)
+		if err != nil {
+			return err
+		}
+
+		left = append(left, keys...)
 	}
 
-	v.UI.Completef("Backup destination store is now empty.")
+	for _, key := range left {
+		v.UI.Warningf("Still on the backup destination store: %s", key)
+	}
+
+	if len(left) > 0 {
+		return fmt.Errorf("%d %w", len(left), errObjectsLeft)
+	}
+
+	// Last, once the local snapshot records are gone: the next backup
+	// then has none and writes the marker again.
+	err = v.Storage.Delete(v.ctx, destinationMarkerKey)
+	if err != nil {
+		return fmt.Errorf("deleting %s: %w", destinationMarkerKey, err)
+	}
 
 	return nil
 }
 
+// deleteEverythingUnder deletes every object under prefix, whatever its
+// name, and returns the keys a listing afterwards still finds. A delete
+// that fails is logged and the others still run; that object then
+// shows up in the listing afterwards.
+func (v *Vaultik) deleteEverythingUnder(prefix string) ([]string, error) {
+	keys, err := v.Storage.List(v.ctx, prefix)
+	if err != nil {
+		return nil, fmt.Errorf("listing %s: %w", prefix, err)
+	}
+
+	for _, key := range keys {
+		err = v.Storage.Delete(v.ctx, key)
+		if err != nil {
+			log.Error("Failed to delete object", "key", key, "error", err)
+		}
+	}
+
+	// The file and rclone listings skip `.partial` objects, so the
+	// deletes above never reach them.
+	err = v.Storage.DeletePartialUploads(v.ctx, prefix)
+	if err != nil {
+		return nil, fmt.Errorf("deleting partial uploads: %w", err)
+	}
+
+	left, err := v.Storage.List(v.ctx, prefix)
+	if err != nil {
+		return nil, fmt.Errorf("listing %s: %w", prefix, err)
+	}
+
+	return left, nil
+}
+
 // PruneBlobsResult contains the result of a blob prune operation
 //
 //nolint:tagliatelle // snake_case is the established JSON output format
@@ -61,14 +173,24 @@ type PruneBlobsResult struct {
 	BlobsDeleted int   `json:"blobs_deleted"`
 	BlobsFailed  int   `json:"blobs_failed,omitempty"`
 	BytesFreed   int64 `json:"bytes_freed"`
+	// BlobsTooNew counts the unreferenced blobs kept because they are
+	// newer than the prune grace period, or of unknown age. BlobsFound
+	// does not include them.
+	BlobsTooNew int `json:"blobs_too_new"`
+	// MetadataDirsDeleted counts the directories under metadata/ with no
+	// manifest that prune deleted, and MetadataDirsFailed those it could
+	// not delete.
+	MetadataDirsDeleted int `json:"metadata_dirs_deleted"`
+	MetadataDirsFailed  int `json:"metadata_dirs_failed,omitempty"`
 }
 
-// Prune removes orphaned data from the local index database AND
+// Prune removes orphaned data from the local index database AND, from the
-// unreferenced blobs from the backup destination store. This is the
+// backup destination store, unreferenced blobs and the directories under
-// single user-facing prune entry point — the split between local and
+// metadata/ with no manifest. This is the single user-facing prune entry
-// remote cleanup is an implementation detail. Calling code should
+// point — the split between local and remote cleanup is an
-// prefer this method over PruneDatabase or PruneBlobs individually
+// implementation detail. Calling code should prefer this method over
-// unless it specifically wants one half.
+// PruneDatabase or PruneBlobs individually unless it specifically wants
+// one half.
 func (v *Vaultik) Prune(opts *PruneOptions) error {
 	err := v.EnsureStorageBinding()
 	if err != nil {
@@ -92,11 +214,17 @@ func (v *Vaultik) Prune(opts *PruneOptions) error {
 	return v.PruneBlobs(opts)
 }
 
-// PruneBlobs removes unreferenced blobs from storage
+// PruneBlobs removes unreferenced blobs from storage, and each directory
+// under metadata/ that a backup left with no manifest.
 func (v *Vaultik) PruneBlobs(opts *PruneOptions) error {
 	log.Info("Starting prune operation")
 
-	allBlobsReferenced, err := v.collectReferencedBlobs()
+	metadataObjects, err := v.listMetadataObjects()
+	if err != nil {
+		return err
+	}
+
+	allBlobsReferenced, err := v.collectReferencedBlobs(metadataObjects)
 	if err != nil {
 		return err
 	}
@@ -106,81 +234,187 @@ func (v *Vaultik) PruneBlobs(opts *PruneOptions) error {
 		return err
 	}
 
-	unreferencedBlobs, totalSize := v.findUnreferencedBlobs(allBlobs, allBlobsReferenced)
+	unreferencedBlobs, totalSize, tooNew := v.findUnreferencedBlobs(
+		allBlobs, allBlobsReferenced)
 
-	result := &PruneBlobsResult{BlobsFound: len(unreferencedBlobs)}
+	dirsWithoutManifest, err := v.findMetadataDirsWithoutManifest(metadataObjects)
+	if err != nil {
+		return err
+	}
 
-	if len(unreferencedBlobs) == 0 {
+	result := &PruneBlobsResult{
+		BlobsFound:  len(unreferencedBlobs),
+		BlobsTooNew: tooNew,
+	}
+
+	v.reportBlobsTooNew(tooNew, opts)
+
+	if len(unreferencedBlobs) == 0 && len(dirsWithoutManifest) == 0 {
 		log.Info("No unreferenced blobs found")
 
 		if opts.JSON {
 			return v.outputPruneBlobsJSON(result)
 		}
 
-		v.printlnStdout("No unreferenced blobs to remove.")
+		v.UI.Infof("No unreferenced blobs to remove.")
 
 		return nil
 	}
 
 	log.Info("Found unreferenced blobs",
-		"count", len(unreferencedBlobs), "total_size", ubytes(totalSize))
+		"count", len(unreferencedBlobs), "total_size", ubytes(totalSize),
+		"metadata_dirs_without_manifest", len(dirsWithoutManifest))
 
-	if !opts.JSON {
+	if !v.confirmPrune(opts, len(unreferencedBlobs), totalSize,
-		v.stdoutf("Found %d unreferenced blob(s) totaling %s\n",
+		dirsWithoutManifest) {
-			len(unreferencedBlobs), ubytes(totalSize))
+		return nil
-	}
-
-	if !opts.Force && !opts.JSON {
-		v.stdoutf("\nDelete %d unreferenced blob(s)? [y/N] ", len(unreferencedBlobs))
-
-		var confirm string
-
-		_, err = v.scanStdin(&confirm)
-		if err != nil {
-			v.printlnStdout("Cancelled")
-
-			return nil //nolint:nilerr // read failure means no confirmation
-		}
-
-		if strings.ToLower(confirm) != "y" {
-			v.printlnStdout("Cancelled")
-
-			return nil
-		}
 	}
 
 	v.deleteUnreferencedBlobs(unreferencedBlobs, allBlobs, result)
+	v.deleteMetadataDirs(dirsWithoutManifest, result)
 
 	if opts.JSON {
-		return v.outputPruneBlobsJSON(result)
+		err = v.outputPruneBlobsJSON(result)
+		if err != nil {
+			return err
+		}
+	} else {
+		v.reportPruneDeletions(result, len(dirsWithoutManifest))
 	}
 
-	v.stdoutf("\nDeleted %d blob(s) totaling %s\n",
+	var failures []error
-		result.BlobsDeleted, ubytes(result.BytesFreed))
 
 	if result.BlobsFailed > 0 {
-		v.stdoutf("Failed to delete %d blob(s)\n", result.BlobsFailed)
+		failures = append(failures,
+			fmt.Errorf("%d %w", result.BlobsFailed, errBlobDeleteFailed))
 	}
 
-	return nil
+	if result.MetadataDirsFailed > 0 {
+		failures = append(failures, fmt.Errorf("%d %w",
+			result.MetadataDirsFailed, errMetadataDirDeleteFailed))
+	}
+
+	return errors.Join(failures...)
 }
 
-// collectReferencedBlobs downloads all manifests and returns the set of
+// confirmPrune states what prune found to delete, unreferenced blobs and
-// referenced blob hashes.
+// directories under metadata/ with no manifest, naming each directory by
+// its remote key, and, unless --force is given, asks the operator to
+// confirm. Under --json it prints nothing and does not ask. It reports
+// whether to go ahead.
+func (v *Vaultik) confirmPrune(
+	opts *PruneOptions, blobCount int, blobsSize int64, dirs []string,
+) bool {
+	if opts.JSON {
+		return true
+	}
+
+	dirCount := len(dirs)
+	blobsFound := fmt.Sprintf("Found %d unreferenced blob(s) totaling %s.",
+		blobCount, ubytes(blobsSize))
+	dirsFound := fmt.Sprintf("Found %d metadata director(ies) left by "+
+		"backups that stopped before their manifest:", dirCount)
+
+	if opts.Force {
+		if blobCount > 0 {
+			v.UI.Infof("%s", blobsFound)
+		}
+
+		if dirCount > 0 {
+			v.UI.Infof("%s", dirsFound)
+
+			for _, remoteKey := range dirs {
+				v.UI.Detailf("metadata/%s/", remoteKey)
+			}
+		}
+
+		return true
+	}
+
+	// The counts, the names, the prompt and its answer bypass the UI:
+	// they are an interactive exchange the operator must see, so --quiet
+	// does not silence them.
+	if blobCount > 0 {
+		v.stdoutf("%s\n", blobsFound)
+	}
+
+	if dirCount > 0 {
+		v.stdoutf("%s\n", dirsFound)
+
+		for _, remoteKey := range dirs {
+			v.stdoutf("  metadata/%s/\n", remoteKey)
+		}
+	}
+
+	switch {
+	case dirCount == 0:
+		v.stdoutf("\nDelete %d unreferenced blob(s)? [y/N] ", blobCount)
+	case blobCount == 0:
+		v.stdoutf("\nDelete %d metadata director(ies)? [y/N] ", dirCount)
+	default:
+		v.stdoutf("\nDelete %d unreferenced blob(s) and %d metadata "+
+			"director(ies)? [y/N] ", blobCount, dirCount)
+	}
+
+	var confirm string
+
+	// A failure to read the answer means no confirmation.
+	_, err := v.scanStdin(&confirm)
+	if err != nil || strings.ToLower(confirm) != "y" {
+		v.printlnStdout("Cancelled")
+
+		return false
+	}
+
+	return true
+}
+
+// reportPruneDeletions says how many blobs and metadata directories
+// prune deleted, naming each kind only when it found some to delete.
+func (v *Vaultik) reportPruneDeletions(result *PruneBlobsResult, dirCount int) {
+	if result.BlobsFound > 0 {
+		v.UI.Infof("Deleted %d blob(s) totaling %s.",
+			result.BlobsDeleted, ubytes(result.BytesFreed))
+	}
+
+	if dirCount > 0 {
+		v.UI.Infof("Deleted %d metadata director(ies) with no manifest.",
+			result.MetadataDirsDeleted)
+	}
+}
+
+// listMetadataObjects lists every object under metadata/ on the
+// destination store.
+func (v *Vaultik) listMetadataObjects() ([]storage.ObjectInfo, error) {
+	log.Info("Listing remote snapshots")
+
+	var objects []storage.ObjectInfo
+
+	for object := range v.Storage.ListStream(v.ctx, "metadata/") {
+		if object.Err != nil {
+			return nil, fmt.Errorf("listing metadata objects: %w", object.Err)
+		}
+
+		objects = append(objects, object)
+	}
+
+	return objects, nil
+}
+
+// collectReferencedBlobs downloads every manifest among the listed
+// metadata objects and returns the set of referenced blob hashes.
 //
 // Every manifest must be read successfully. A manifest that cannot be
 // downloaded or decoded means its snapshot's blobs are unknown, so
 // treating them as unreferenced would let prune delete data a snapshot
 // still needs. Rather than risk that silent loss, any failure returns an
 // error naming the remote key and prune deletes nothing.
-func (v *Vaultik) collectReferencedBlobs() (map[string]bool, error) {
+func (v *Vaultik) collectReferencedBlobs(
-	log.Info("Listing remote snapshots")
+	metadataObjects []storage.ObjectInfo,
-	// IDs returned by listUniqueSnapshotIDs are remote keys (hashed
+) (map[string]bool, error) {
+	// IDs returned by uniqueSnapshotIDs are remote keys (hashed
 	// subdirectories under metadata/), not human snapshot IDs.
-	remoteKeys, err := v.listUniqueSnapshotIDs()
+	remoteKeys := uniqueSnapshotIDs(metadataObjects)
-	if err != nil {
-		return nil, fmt.Errorf("listing snapshot keys: %w", err)
-	}
 
 	log.Info("Found manifests in remote storage", "count", len(remoteKeys))
 
@@ -205,18 +439,14 @@ func (v *Vaultik) collectReferencedBlobs() (map[string]bool, error) {
 	return allBlobsReferenced, nil
 }
 
-// listUniqueSnapshotIDs returns deduplicated snapshot IDs from remote metadata
+// uniqueSnapshotIDs returns deduplicated snapshot IDs from the listed
-func (v *Vaultik) listUniqueSnapshotIDs() ([]string, error) {
+// metadata objects.
-	objectCh := v.Storage.ListStream(v.ctx, "metadata/")
+func uniqueSnapshotIDs(metadataObjects []storage.ObjectInfo) []string {
 	seen := make(map[string]bool)
 
 	var snapshotIDs []string
 
-	for object := range objectCh {
+	for _, object := range metadataObjects {
-		if object.Err != nil {
-			return nil, fmt.Errorf("listing metadata objects: %w", object.Err)
-		}
-
 		parts := strings.Split(object.Key, "/")
 		if len(parts) >= minSnapshotIDParts &&
 			parts[0] == metadataDirName && parts[1] != "" {
@@ -231,14 +461,15 @@ func (v *Vaultik) listUniqueSnapshotIDs() ([]string, error) {
 		}
 	}
 
-	return snapshotIDs, nil
+	return snapshotIDs
 }
 
-// listAllRemoteBlobs returns a map of all blob hashes to their sizes in remote storage
+// listAllRemoteBlobs returns a map of all blob hashes in remote storage
-func (v *Vaultik) listAllRemoteBlobs() (map[string]int64, error) {
+// to their listing entries.
+func (v *Vaultik) listAllRemoteBlobs() (map[string]storage.ObjectInfo, error) {
 	log.Info("Listing all blobs in storage")
 
-	allBlobs := make(map[string]int64)
+	allBlobs := make(map[string]storage.ObjectInfo)
 	blobObjectCh := v.Storage.ListStream(v.ctx, "blobs/")
 
 	for object := range blobObjectCh {
@@ -262,7 +493,7 @@ func (v *Vaultik) listAllRemoteBlobs() (map[string]int64, error) {
 			continue
 		}
 
-		allBlobs[parts[3]] = object.Size
+		allBlobs[parts[3]] = object
 	}
 
 	log.Info("Found blobs in storage", "count", len(allBlobs))
@@ -270,30 +501,135 @@ func (v *Vaultik) listAllRemoteBlobs() (map[string]int64, error) {
 	return allBlobs, nil
 }
 
-// findUnreferencedBlobs returns blob hashes not referenced by any
+// findUnreferencedBlobs returns the hashes of the blobs no manifest
-// manifest and their total size.
+// references that are older than the prune grace period, and their total
+// size. It also returns how many unreferenced blobs it left out for
+// being newer than that, or of unknown age because the listing gave no
+// time for them.
 func (v *Vaultik) findUnreferencedBlobs(
-	allBlobs map[string]int64, referenced map[string]bool,
+	allBlobs map[string]storage.ObjectInfo, referenced map[string]bool,
-) ([]string, int64) {
+) ([]string, int64, int) {
 	var (
 		unreferenced []string
 		totalSize    int64
+		tooNew       int
 	)
 
-	for hash, size := range allBlobs {
+	cutoff := time.Now().UTC().Add(-v.Config.PruneGracePeriod)
-		if !referenced[hash] {
+
-			unreferenced = append(unreferenced, hash)
+	for hash, blob := range allBlobs {
-			totalSize += size
+		if referenced[hash] {
+			continue
+		}
+
+		if blob.ModTime.IsZero() || blob.ModTime.After(cutoff) {
+			tooNew++
+
+			continue
+		}
+
+		unreferenced = append(unreferenced, hash)
+		totalSize += blob.Size
+	}
+
+	return unreferenced, totalSize, tooNew
+}
+
+// findMetadataDirsWithoutManifest returns the remote key of each
+// directory under metadata/ that has no manifest.json.zst, such as one a
+// backup leaves when its manifest upload fails after db.zst.age was
+// uploaded. It leaves out a directory a local snapshot record claims,
+// and one holding an object newer than the prune grace period, or of
+// unknown age because the listing gave no time for it: a backup still
+// running may be writing there. A name that is not a remote key is
+// never returned.
+func (v *Vaultik) findMetadataDirsWithoutManifest(
+	metadataObjects []storage.ObjectInfo,
+) ([]string, error) {
+	localIDs, err := v.localSnapshotIDs()
+	if err != nil {
+		return nil, fmt.Errorf("listing local snapshots: %w", err)
+	}
+
+	keep := make(map[string]bool, len(localIDs))
+	for _, id := range localIDs {
+		keep[snapshot.RemoteSnapshotKey(id)] = true
+	}
+
+	cutoff := time.Now().UTC().Add(-v.Config.PruneGracePeriod)
+	listed := make(map[string]bool)
+
+	for _, object := range metadataObjects {
+		parts := strings.Split(object.Key, "/")
+		if len(parts) < metadataKeyParts || !isBlobHash(parts[1]) {
+			continue
+		}
+
+		remoteKey := parts[1]
+		listed[remoteKey] = true
+
+		if parts[2] == "manifest.json.zst" ||
+			object.ModTime.IsZero() || object.ModTime.After(cutoff) {
+			keep[remoteKey] = true
 		}
 	}
 
-	return unreferenced, totalSize
+	var remoteKeys []string
+
+	for remoteKey := range listed {
+		if !keep[remoteKey] {
+			remoteKeys = append(remoteKeys, remoteKey)
+		}
+	}
+
+	sort.Strings(remoteKeys)
+
+	return remoteKeys, nil
+}
+
+// deleteMetadataDirs deletes everything in the given directories under
+// metadata/ and counts in the result the directories deleted and those
+// it could not delete.
+func (v *Vaultik) deleteMetadataDirs(
+	remoteKeys []string, result *PruneBlobsResult,
+) {
+	for _, remoteKey := range remoteKeys {
+		_, err := v.deleteRemoteSnapshotByKey(remoteKey)
+		if err != nil {
+			log.Error("Failed to delete metadata directory with no manifest",
+				"remote_key", remoteKey, "error", err)
+
+			result.MetadataDirsFailed++
+
+			continue
+		}
+
+		log.Info("Deleted metadata directory with no manifest",
+			"remote_key", remoteKey)
+
+		result.MetadataDirsDeleted++
+	}
+}
+
+// reportBlobsTooNew says how many unreferenced blobs prune kept for being
+// newer than the grace period or of unknown age. Under --json the
+// document carries the count instead.
+func (v *Vaultik) reportBlobsTooNew(tooNew int, opts *PruneOptions) {
+	if tooNew == 0 || opts.JSON {
+		return
+	}
+
+	v.UI.Infof("Kept %d unreferenced blob(s) newer than "+
+		"prune_grace_period (%s), or of unknown age: a backup still "+
+		"running may need them.",
+		tooNew, v.Config.PruneGracePeriod)
 }
 
 // deleteUnreferencedBlobs deletes the given blobs from storage and
 // populates the result.
 func (v *Vaultik) deleteUnreferencedBlobs(
-	unreferencedBlobs []string, allBlobs map[string]int64, result *PruneBlobsResult,
+	unreferencedBlobs []string, allBlobs map[string]storage.ObjectInfo,
+	result *PruneBlobsResult,
 ) {
 	log.Info("Deleting unreferenced blobs")
 
@@ -308,7 +644,7 @@ func (v *Vaultik) deleteUnreferencedBlobs(
 		}
 
 		result.BlobsDeleted++
-		result.BytesFreed += allBlobs[hash]
+		result.BytesFreed += allBlobs[hash].Size
 
 		if (i+1)%progressLogEvery == 0 || i == len(unreferencedBlobs)-1 {
 			log.Info("Deletion progress",

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
@@ -42,7 +46,7 @@ func TestTableCountForReportSurfacesReadFailure(t *testing.T) {
 	assert.Nil(t, missing, "a failed read is unknown, not a count")
 
 	// The rendered count for a failed read must say unknown, never 0.
-	assert.Equal(t, countUnknown, countText(missing))
+	assert.Equal(t, unknownText, countText(missing))
 	assert.NotEqual(t, "0", countText(missing))
 }
 
@@ -57,7 +61,7 @@ func TestCountTextDistinguishesEmptyFromUnknown(t *testing.T) {
 
 	assert.Equal(t, "0", countText(&zero))
 	assert.Equal(t, "7", countText(&seven))
-	assert.Equal(t, countUnknown, countText(nil))
+	assert.Equal(t, unknownText, countText(nil))
 }
 
 // TestCountDiffUnknownWhenEitherSideUnknown checks that a delta computed
@@ -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/prune_delete_failure_test.go

@@ -0,0 +1,98 @@
+package vaultik_test
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/storage/faultstore"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// refuseBlobDeletes is an OnDelete hook that fails every blob delete.
+func refuseBlobDeletes(key string) bool {
+	return strings.HasPrefix(key, "blobs/")
+}
+
+// TestPruneBlobs_FailedDeleteReturnsError checks that prune returns an
+// error, so the command exits non-zero, when an unreferenced blob cannot
+// be deleted.
+func TestPruneBlobs_FailedDeleteReturnsError(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+
+	// The store holds no manifest, so nothing references this blob.
+	addBlob(t, env.store.testStorer, testBlobHashA)
+
+	store := faultstore.New(env.store)
+	store.OnDelete = refuseBlobDeletes
+	env.v.Storage = store
+
+	err := env.v.PruneBlobs(&vaultik.PruneOptions{Force: true})
+
+	require.ErrorContains(t, err, "1 blob(s) could not be deleted")
+}
+
+// TestPruneBlobs_JSONFailedDeleteReturnsError checks that prune --json
+// prints its document and then returns an error when an unreferenced
+// blob cannot be deleted.
+func TestPruneBlobs_JSONFailedDeleteReturnsError(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+	addBlob(t, env.store.testStorer, testBlobHashA)
+
+	store := faultstore.New(env.store)
+	store.OnDelete = refuseBlobDeletes
+	env.v.Storage = store
+
+	err := env.v.PruneBlobs(&vaultik.PruneOptions{JSON: true})
+
+	require.Error(t, err, "prune must fail when a blob cannot be deleted")
+
+	var result vaultik.PruneBlobsResult
+
+	require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &result),
+		"stdout must hold the JSON document, got:\n%s", env.stdout.String())
+	assert.Equal(t, 1, result.BlobsFailed)
+	assert.Equal(t, 0, result.BlobsDeleted)
+}
+
+// TestCreateSnapshotPrune_FailedBlobDeleteReturnsError checks that the
+// prune step of snapshot create --prune fails the run when an
+// unreferenced blob cannot be deleted.
+func TestCreateSnapshotPrune_FailedBlobDeleteReturnsError(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := filepath.Join(t.TempDir(), "store")
+	v, _, _ := backUpToFileDestination(ctx, t, storeDir)
+
+	// No snapshot references this blob, so the prune step deletes it.
+	orphan := filepath.Join(storeDir, "blobs", testBlobHashA[:2],
+		testBlobHashA[2:4], testBlobHashA)
+	require.NoError(t, os.MkdirAll(filepath.Dir(orphan), 0o750))
+	require.NoError(t, os.WriteFile(orphan, []byte("orphan"), 0o600))
+
+	store := faultstore.New(v.Storage)
+	store.OnDelete = refuseBlobDeletes
+	v.Storage = store
+
+	err := v.CreateSnapshot(&vaultik.SnapshotCreateOptions{
+		Cron:  true,
+		Prune: true,
+	})
+
+	require.ErrorContains(t, err, "1 blob(s) could not be deleted")
+	assert.FileExists(t, orphan)
+}

internal/vaultik/prune_grace_period_test.go

@@ -0,0 +1,168 @@
+package vaultik_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/config"
+	"sneak.berlin/go/vaultik/internal/database"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/storage"
+	"sneak.berlin/go/vaultik/internal/storage/faultstore"
+	"sneak.berlin/go/vaultik/internal/ui"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// TestPruneDuringBackupKeepsItsBlobs runs a prune from another host
+// sharing the destination store at the moment a backup has uploaded its
+// blobs and its db.zst.age but not yet its manifest, so no manifest lists
+// those blobs. The prune must leave the blobs and the db.zst.age, and the
+// backup must then restore.
+func TestPruneDuringBackupKeepsItsBlobs(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	fs := afero.NewOsFs()
+	tempDir := t.TempDir()
+	dataDir := filepath.Join(tempDir, "src")
+	storeDir := t.TempDir()
+	restoreDir := filepath.Join(tempDir, "restored")
+	dbPath := filepath.Join(tempDir, "index.sqlite")
+
+	ctx := context.Background()
+	cfg := faultTestConfig()
+	testFiles := writeFaultSourceTree(t, fs, dataDir)
+
+	inner, err := storage.NewFileStorer(storeDir)
+	require.NoError(t, err)
+
+	otherHostCfg := faultTestConfig()
+	otherHostCfg.PruneGracePeriod = time.Hour
+	otherHost := newReaderVaultik(ctx, otherHostCfg, inner, nil, fs)
+
+	var (
+		pruned   bool
+		pruneErr error
+	)
+
+	store := faultstore.New(inner)
+	store.OnPut = func(key string) faultstore.PutAction {
+		if strings.HasSuffix(key, "/manifest.json.zst") {
+			pruned = true
+			pruneErr = otherHost.PruneBlobs(&vaultik.PruneOptions{Force: true})
+		}
+
+		return faultstore.PutNormal
+	}
+
+	db, err := database.New(ctx, dbPath)
+	require.NoError(t, err)
+
+	repos := database.NewRepositories(db)
+
+	id := fullFaultBackup(ctx, t, fs, store, cfg, repos, dataDir, dbPath, "shared")
+	require.NoError(t, db.Close())
+
+	require.True(t, pruned, "the prune must run before the manifest upload")
+	require.NoError(t, pruneErr)
+
+	v := newReaderVaultik(ctx, cfg, inner, nil, fs)
+	require.NoError(t, v.Restore(&vaultik.RestoreOptions{
+		SnapshotID: id,
+		TargetDir:  restoreDir,
+		Verify:     true,
+	}), "a prune during the backup must not delete the backup's blobs "+
+		"or its db.zst.age")
+
+	assertRestoredTree(t, fs, restoreDir, testFiles)
+}
+
+// TestPruneKeepsUnreferencedBlobWithNoTime checks that a blob no
+// manifest lists, whose listing gives no modification time (as an S3
+// listing entry without LastModified does), is kept and counted with
+// the blobs too new to delete: its age is unknown.
+func TestPruneKeepsUnreferencedBlobWithNoTime(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+
+	// Written into the mock store's map directly rather than through
+	// Put, so its listing gives no time.
+	blobKey := "blobs/" + testBlobHashA[:2] + "/" + testBlobHashA[2:4] +
+		"/" + testBlobHashA
+	env.store.data[blobKey] = []byte("blob")
+
+	require.NoError(t, env.v.PruneBlobs(&vaultik.PruneOptions{JSON: true}))
+
+	assert.True(t, env.store.hasKey(blobKey),
+		"a blob of unknown age must be kept")
+
+	var result vaultik.PruneBlobsResult
+
+	require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &result))
+	assert.Equal(t, 0, result.BlobsDeleted)
+	assert.Equal(t, 1, result.BlobsTooNew)
+}
+
+// TestPruneDeletesUnreferencedBlobOlderThanGracePeriod checks that the
+// grace period only delays deletion: a blob no manifest lists is deleted
+// once it is older than the grace period, and kept and counted until
+// then.
+func TestPruneDeletesUnreferencedBlobOlderThanGracePeriod(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := t.TempDir()
+
+	store, err := storage.NewFileStorer(storeDir)
+	require.NoError(t, err)
+
+	oldKey := "blobs/" + testBlobHashA[:2] + "/" + testBlobHashA[2:4] +
+		"/" + testBlobHashA
+	newKey := "blobs/" + testBlobHashB[:2] + "/" + testBlobHashB[2:4] +
+		"/" + testBlobHashB
+
+	for _, key := range []string{oldKey, newKey} {
+		require.NoError(t, store.Put(ctx, key, strings.NewReader("blob")))
+	}
+
+	gracePeriod := time.Hour
+	beforeGracePeriod := time.Now().Add(-gracePeriod - time.Minute)
+	require.NoError(t, os.Chtimes(filepath.Join(storeDir, oldKey),
+		beforeGracePeriod, beforeGracePeriod))
+
+	stdout := &bytes.Buffer{}
+	v := &vaultik.Vaultik{
+		Config:  &config.Config{PruneGracePeriod: gracePeriod},
+		Storage: store,
+		Stdout:  stdout,
+		UI:      ui.NewWithColor(stdout, false),
+	}
+	v.SetContext(ctx)
+
+	require.NoError(t, v.PruneBlobs(&vaultik.PruneOptions{JSON: true}))
+
+	_, err = store.Stat(ctx, oldKey)
+	require.ErrorIs(t, err, storage.ErrNotFound,
+		"a blob older than the grace period must be deleted")
+
+	_, err = store.Stat(ctx, newKey)
+	require.NoError(t, err, "a blob newer than the grace period must be kept")
+
+	var result vaultik.PruneBlobsResult
+
+	require.NoError(t, json.Unmarshal(stdout.Bytes(), &result))
+	assert.Equal(t, 1, result.BlobsDeleted)
+	assert.Equal(t, 1, result.BlobsTooNew)
+}

internal/vaultik/prune_json_test.go

@@ -0,0 +1,40 @@
+package vaultik_test
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// TestPruneBlobs_JSONDeletesWithoutAsking checks that prune with --json
+// and without --force deletes an unreferenced blob without the
+// confirmation prompt. Stdin is empty, so a prompt would read no answer
+// and cancel, and its text would come before the JSON document.
+func TestPruneBlobs_JSONDeletesWithoutAsking(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+
+	// The store holds no manifest, so nothing references this blob.
+	addBlob(t, env.store.testStorer, testBlobHashA)
+
+	err := env.v.PruneBlobs(&vaultik.PruneOptions{JSON: true})
+	require.NoError(t, err)
+
+	blobKey := "blobs/" + testBlobHashA[:2] + "/" + testBlobHashA[2:4] +
+		"/" + testBlobHashA
+	assert.False(t, env.store.hasKey(blobKey),
+		"the unreferenced blob must be deleted")
+
+	var result vaultik.PruneBlobsResult
+
+	require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &result),
+		"stdout must hold only the JSON document, got:\n%s",
+		env.stdout.String())
+	assert.Equal(t, 1, result.BlobsDeleted)
+}

internal/vaultik/prune_metadata_dir_test.go

@@ -0,0 +1,225 @@
+package vaultik_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/config"
+	"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/ui"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// metadataObjectKey returns the key of the named file in the metadata
+// directory of the snapshot with the given human ID.
+func metadataObjectKey(snapshotID, name string) string {
+	return "metadata/" + snapshot.RemoteSnapshotKey(snapshotID) + "/" + name
+}
+
+// TestPruneDeletesMetadataDirWithoutManifestOlderThanGracePeriod checks
+// that prune deletes a directory under metadata/ holding only
+// db.zst.age, as a backup leaves when its manifest upload fails, once it
+// is older than the grace period, and keeps one newer than that. A
+// directory with a manifest is never deleted, however old.
+func TestPruneDeletesMetadataDirWithoutManifestOlderThanGracePeriod(
+	t *testing.T,
+) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := t.TempDir()
+
+	store, err := storage.NewFileStorer(storeDir)
+	require.NoError(t, err)
+
+	const (
+		oldID      = "testhost_home_2026-01-01T00:00:00Z"
+		newID      = "testhost_home_2026-01-02T00:00:00Z"
+		completeID = "testhost_home_2026-01-03T00:00:00Z"
+	)
+
+	oldDB := metadataObjectKey(oldID, "db.zst.age")
+	newDB := metadataObjectKey(newID, "db.zst.age")
+	completeDB := metadataObjectKey(completeID, "db.zst.age")
+	completeManifest := metadataObjectKey(completeID, "manifest.json.zst")
+
+	manifest, err := snapshot.EncodeManifest(&snapshot.Manifest{
+		SnapshotID: snapshot.RemoteSnapshotKey(completeID),
+	}, 3)
+	require.NoError(t, err)
+
+	for _, key := range []string{oldDB, newDB, completeDB} {
+		require.NoError(t, store.Put(ctx, key, strings.NewReader("db")))
+	}
+
+	require.NoError(t, store.Put(ctx, completeManifest,
+		bytes.NewReader(manifest)))
+
+	gracePeriod := time.Hour
+	beforeGracePeriod := time.Now().Add(-gracePeriod - time.Minute)
+
+	for _, key := range []string{oldDB, completeDB, completeManifest} {
+		require.NoError(t, os.Chtimes(filepath.Join(storeDir, key),
+			beforeGracePeriod, beforeGracePeriod))
+	}
+
+	stdout := &bytes.Buffer{}
+	v := &vaultik.Vaultik{
+		Config:  &config.Config{PruneGracePeriod: gracePeriod},
+		Storage: store,
+		Stdout:  stdout,
+		UI:      ui.NewWithColor(stdout, false),
+	}
+	v.SetContext(ctx)
+
+	require.NoError(t, v.PruneBlobs(&vaultik.PruneOptions{JSON: true}))
+
+	_, err = store.Stat(ctx, oldDB)
+	require.ErrorIs(t, err, storage.ErrNotFound,
+		"a directory with no manifest older than the grace period "+
+			"must be deleted")
+
+	for _, key := range []string{newDB, completeDB, completeManifest} {
+		_, err = store.Stat(ctx, key)
+		require.NoError(t, err, "%s must be kept", key)
+	}
+
+	var result vaultik.PruneBlobsResult
+
+	require.NoError(t, json.Unmarshal(stdout.Bytes(), &result))
+	assert.Equal(t, 1, result.MetadataDirsDeleted)
+}
+
+// TestPruneKeepsMetadataDirClaimedUnknownAgeOrNotRemoteKey checks that
+// prune --force keeps a directory under metadata/ with no manifest when a
+// local snapshot record claims it, when the listing gives no time for an
+// object in it, or when its name is not a remote key. A fourth such
+// directory is named, deleted and reported, although there are no
+// unreferenced blobs to delete.
+func TestPruneKeepsMetadataDirClaimedUnknownAgeOrNotRemoteKey(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	env := newListEnv(t)
+
+	const (
+		claimedID = "testhost_home_2026-01-01T00:00:00Z"
+		leftID    = "testhost_home_2026-01-03T00:00:00Z"
+	)
+
+	env.addLocal(t, claimedID, time.Now().Add(-time.Hour))
+
+	claimedDB := metadataObjectKey(claimedID, "db.zst.age")
+	unknownAgeDB := metadataObjectKey("testhost_home_2026-01-02T00:00:00Z",
+		"db.zst.age")
+	leftDB := metadataObjectKey(leftID, "db.zst.age")
+	notRemoteKeyDB := "metadata/not-a-remote-key/db.zst.age"
+
+	for _, key := range []string{claimedDB, leftDB, notRemoteKeyDB} {
+		require.NoError(t, env.store.Put(ctx, key, strings.NewReader("db")))
+	}
+
+	// Written into the mock store's map directly rather than through
+	// Put, so its listing gives no time.
+	env.store.data[unknownAgeDB] = []byte("db")
+
+	require.NoError(t, env.v.PruneBlobs(&vaultik.PruneOptions{Force: true}))
+
+	assert.True(t, env.store.hasKey(claimedDB),
+		"a directory a local snapshot record claims must be kept")
+	assert.True(t, env.store.hasKey(unknownAgeDB),
+		"a directory holding an object of unknown age must be kept")
+	assert.True(t, env.store.hasKey(notRemoteKeyDB),
+		"a directory whose name is not a remote key must be kept")
+	assert.False(t, env.store.hasKey(leftDB),
+		"a directory with no manifest, unclaimed and old, must be deleted")
+
+	output := env.stdout.String()
+
+	assert.Contains(t, output, "Found 1 metadata director(ies) left by "+
+		"backups that stopped before their manifest:")
+	assert.Contains(t, output,
+		"metadata/"+snapshot.RemoteSnapshotKey(leftID)+"/")
+	assert.NotContains(t, output, "not-a-remote-key")
+	assert.Contains(t, output,
+		"Deleted 1 metadata director(ies) with no manifest.")
+	assert.NotContains(t, output, "No unreferenced blobs to remove.")
+}
+
+// TestPruneDeclinedKeepsMetadataDirWithoutManifest checks that the prompt
+// names a directory under metadata/ with no manifest that prune is about
+// to delete, and that answering no keeps it.
+func TestPruneDeclinedKeepsMetadataDirWithoutManifest(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+
+	const leftID = "testhost_home_2026-01-01T00:00:00Z"
+
+	leftDB := metadataObjectKey(leftID, "db.zst.age")
+	require.NoError(t, env.store.Put(context.Background(), leftDB,
+		strings.NewReader("db")))
+
+	env.v.Stdin = strings.NewReader("n\n")
+
+	require.NoError(t, env.v.PruneBlobs(&vaultik.PruneOptions{}))
+
+	assert.True(t, env.store.hasKey(leftDB),
+		"a declined prune must keep the directory")
+
+	output := env.stdout.String()
+
+	assert.Contains(t, output,
+		"  metadata/"+snapshot.RemoteSnapshotKey(leftID)+"/\n")
+	assert.Contains(t, output, "Delete 1 metadata director(ies)? [y/N] ")
+	assert.Contains(t, output, "Cancelled")
+	assert.NotContains(t, output, "Deleted")
+}
+
+// TestPruneFailedMetadataDirDeleteReturnsError checks that prune --json
+// counts a directory under metadata/ with no manifest that it cannot
+// delete, and then returns an error, so the command exits non-zero.
+func TestPruneFailedMetadataDirDeleteReturnsError(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+
+	leftDB := metadataObjectKey("testhost_home_2026-01-01T00:00:00Z",
+		"db.zst.age")
+	require.NoError(t, env.store.Put(context.Background(), leftDB,
+		strings.NewReader("db")))
+
+	store := faultstore.New(env.store)
+	store.OnDelete = func(key string) bool {
+		return strings.HasPrefix(key, "metadata/")
+	}
+	env.v.Storage = store
+
+	err := env.v.PruneBlobs(&vaultik.PruneOptions{JSON: true})
+
+	require.ErrorContains(t, err,
+		"1 metadata director(ies) with no manifest could not be deleted")
+	assert.True(t, env.store.hasKey(leftDB))
+
+	var result vaultik.PruneBlobsResult
+
+	require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &result),
+		"stdout must hold the JSON document, got:\n%s", env.stdout.String())
+	assert.Equal(t, 1, result.MetadataDirsFailed)
+	assert.Equal(t, 0, result.MetadataDirsDeleted)
+}

internal/vaultik/purge_local_remote_consistency_test.go

@@ -14,6 +14,7 @@ import (
 	"sneak.berlin/go/vaultik/internal/log"
 	"sneak.berlin/go/vaultik/internal/snapshot"
 	"sneak.berlin/go/vaultik/internal/types"
+	"sneak.berlin/go/vaultik/internal/ui"
 	"sneak.berlin/go/vaultik/internal/vaultik"
 )
 
@@ -34,6 +35,9 @@ func setupConsistencyTest(
 	repos := database.NewRepositories(db)
 	mockStorage := NewMockStorer()
 
+	// A backup wrote to this destination, so it carries the marker.
+	require.NoError(t, mockStorage.Put(ctx, markerFile, strings.NewReader("")))
+
 	for _, id := range snapshotIDs {
 		parts := strings.Split(id, "_")
 		startedAt, err := time.Parse(time.RFC3339, parts[len(parts)-1])
@@ -58,13 +62,16 @@ func setupConsistencyTest(
 		require.NoError(t, err)
 	}
 
+	stdout := &bytes.Buffer{}
+
 	v := &vaultik.Vaultik{
 		Storage:      mockStorage,
 		Repositories: repos,
 		DB:           db,
-		Stdout:       &bytes.Buffer{},
+		Stdout:       stdout,
 		Stderr:       &bytes.Buffer{},
 		Stdin:        &bytes.Buffer{},
+		UI:           ui.NewWithColor(stdout, false),
 	}
 	v.SetContext(ctx)
 

internal/vaultik/purge_per_name_test.go

@@ -14,6 +14,7 @@ import (
 	"sneak.berlin/go/vaultik/internal/log"
 	"sneak.berlin/go/vaultik/internal/snapshot"
 	"sneak.berlin/go/vaultik/internal/types"
+	"sneak.berlin/go/vaultik/internal/ui"
 	"sneak.berlin/go/vaultik/internal/vaultik"
 )
 
@@ -44,6 +45,9 @@ func setupPurgeTest(
 	repos := database.NewRepositories(db)
 	mockStorage := NewMockStorer()
 
+	// A backup wrote to this destination, so it carries the marker.
+	require.NoError(t, mockStorage.Put(ctx, markerFile, strings.NewReader("")))
+
 	// Insert each snapshot into the DB and create remote metadata stubs.
 	// Use timestamps parsed from snapshot IDs for realistic ordering.
 	for _, id := range snapshotIDs {
@@ -86,6 +90,7 @@ func setupPurgeTest(
 		Stdout:       stdout,
 		Stderr:       stderr,
 		Stdin:        stdin,
+		UI:           ui.NewWithColor(stdout, false),
 	}
 	v.SetContext(ctx)
 
@@ -267,6 +272,30 @@ func TestPurgeOlderThan_WithNameFilter(t *testing.T) {
 	assert.Contains(t, remaining, snapHomeT0)
 }
 
+func TestPurgeOlderThan_TooLargeDeletesNothing(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	snapshotIDs := []string{snapHomeT0, snapHomeT1}
+
+	v := setupPurgeTest(t, snapHostname, snapshotIDs)
+
+	err := v.PurgeSnapshotsWithOptions(&vaultik.SnapshotPurgeOptions{
+		OlderThan: "1000y",
+		Force:     true,
+	})
+	require.EqualError(t, err,
+		`invalid duration: "1000y" is longer than about 292 years`)
+
+	err = v.PurgeSnapshotsWithOptions(&vaultik.SnapshotPurgeOptions{
+		OlderThan: "292y",
+		Force:     true,
+	})
+	require.NoError(t, err)
+
+	assert.ElementsMatch(t, snapshotIDs, listRemainingSnapshots(t, v))
+}
+
 func TestPurgeKeepLatest_ThreeNames(t *testing.T) {
 	log.Initialize(log.Config{})
 	t.Parallel()

internal/vaultik/remote_info_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"strings"
 	"testing"
 	"time"
 
@@ -69,6 +70,74 @@ func TestRemoteInfo_UnreadableManifestLeavesOrphansUnknown(t *testing.T) {
 	assert.Equal(t, []any{unreadableKey}, doc["unreadable_manifests"])
 }
 
+// TestRemoteInfo_UnreadableManifestLeavesSnapshotBlobsUnknown checks
+// that the row of a snapshot whose manifest cannot be read gives its
+// blob count and blob size as unknown in the table and as null in
+// --json, not as 0. A directory without a manifest still shows 0: the
+// orphan figures count its blobs as orphaned, so it references none.
+func TestRemoteInfo_UnreadableManifestLeavesSnapshotBlobsUnknown(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+	readableKey := env.addRemote(t, listRemoteID,
+		time.Date(2026, 3, 2, 0, 0, 0, 0, time.UTC))
+
+	unreadableKey := snapshot.RemoteSnapshotKey(listLocalID)
+	require.NoError(t, env.store.Put(context.Background(),
+		"metadata/"+unreadableKey+"/manifest.json.zst",
+		bytes.NewReader([]byte("not a valid manifest"))))
+
+	noManifestKey := snapshot.RemoteSnapshotKey("testhost_home_2026-03-03T10:00:00Z")
+	require.NoError(t, env.store.Put(context.Background(),
+		"metadata/"+noManifestKey+"/db.zst.age",
+		bytes.NewReader([]byte("not a valid database"))))
+
+	require.NoError(t, env.v.RemoteInfo(false))
+
+	// The table truncates the remote key, so a row is found by a prefix.
+	wantUnknown := map[string]int{readableKey: 0, unreadableKey: 2, noManifestKey: 0}
+	for key, want := range wantUnknown {
+		var row string
+
+		for line := range strings.SplitSeq(env.stdout.String(), "\n") {
+			if strings.HasPrefix(line, key[:16]) {
+				row = line
+			}
+		}
+
+		require.NotEmpty(t, row, "no table row for %s", key)
+		assert.Equal(t, want, strings.Count(row, "unknown"), "row: %q", row)
+	}
+
+	env.stdout.Reset()
+	require.NoError(t, env.v.RemoteInfo(true))
+
+	var doc struct {
+		Snapshots []map[string]any `json:"snapshots"`
+	}
+
+	require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &doc))
+	require.Len(t, doc.Snapshots, len(wantUnknown))
+
+	for _, entry := range doc.Snapshots {
+		switch entry["snapshot_id"] {
+		case readableKey:
+			assert.InDelta(t, 1, entry["blob_count"], 0)
+			assert.InDelta(t, fiveMegabytes, entry["blobs_size"], 0)
+		case noManifestKey:
+			assert.InDelta(t, 0, entry["blob_count"], 0)
+			assert.InDelta(t, 0, entry["blobs_size"], 0)
+		default:
+			assert.Equal(t, unreadableKey, entry["snapshot_id"])
+			assert.Contains(t, entry, "blob_count")
+			assert.Nil(t, entry["blob_count"])
+			assert.Contains(t, entry, "blobs_size")
+			assert.Nil(t, entry["blobs_size"])
+		}
+	}
+}
+
 // TestRemoteInfo_SkipsNonConformingMetadataName checks that a directory
 // under metadata/ whose name is not a remote key is left out of the
 // report, and that the orphan figures are unknown when it holds a
@@ -116,6 +185,39 @@ func TestRemoteInfo_SkipsNonConformingMetadataName(t *testing.T) {
 	assert.NotContains(t, doc, "unreadable_manifests")
 }
 
+// TestRemoteInfo_DoesNotCountNonBlobFileUnderBlobs checks that a file
+// under blobs/ whose name is not a blob hash is not counted as a blob.
+// prune never deletes such a file, so counting it as an orphaned blob
+// would advise a prune that removes nothing.
+func TestRemoteInfo_DoesNotCountNonBlobFileUnderBlobs(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+	env.addRemote(t, listRemoteID, time.Date(2026, 3, 2, 0, 0, 0, 0, time.UTC))
+	addBlob(t, env.store.testStorer, testBlobHashA)
+	require.NoError(t, env.store.Put(context.Background(),
+		"blobs/"+testBlobHashA[:2]+"/"+testBlobHashA[2:4]+"/.DS_Store",
+		bytes.NewReader([]byte("junk"))))
+
+	require.NoError(t, env.v.RemoteInfo(false))
+
+	text := env.stdout.String()
+	assert.Contains(t, text, "Total blobs on remote:      1 (")
+	assert.Contains(t, text, "Orphaned (unreferenced):    0 (")
+	assert.NotContains(t, text, "vaultik prune")
+
+	env.stdout.Reset()
+	require.NoError(t, env.v.RemoteInfo(true))
+
+	var doc map[string]any
+
+	require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &doc))
+	assert.InDelta(t, 1, doc["total_blob_count"], 0)
+	assert.InDelta(t, 0, doc["orphaned_blob_count"], 0)
+	assert.InDelta(t, 0, doc["orphaned_blob_size"], 0)
+}
+
 // TestRemoteInfo_DirectoryWithoutManifestLeavesOrphansKnown checks that
 // a directory under metadata/ holding no manifest.json.zst, such as one
 // left by a backup interrupted before its manifest upload, leaves the

internal/vaultik/remove_quiet_test.go

@@ -0,0 +1,152 @@
+package vaultik_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/ui"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// TestPurgeSnapshots_QuietSuppressesReport checks that `snapshot purge
+// --keep-latest --force` under --quiet deletes the older snapshot and
+// prints nothing.
+func TestPurgeSnapshots_QuietSuppressesReport(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	v := setupPurgeTest(t, snapHostname, []string{snapHomeT0, snapHomeT1})
+
+	var out bytes.Buffer
+
+	v.Stdout = &out
+	v.UI = ui.NewWithColor(&out, false)
+	v.UI.SetQuiet(true)
+
+	require.NoError(t, v.PurgeSnapshotsWithOptions(&vaultik.SnapshotPurgeOptions{
+		KeepLatest: true,
+		Force:      true,
+	}))
+
+	assert.Equal(t, []string{snapHomeT1}, listRemainingSnapshots(t, v))
+	assert.Empty(t, out.String())
+}
+
+// TestPurgeSnapshots_QuietPromptListsSnapshots checks that `snapshot
+// purge --keep-latest` without --force still lists the snapshots its
+// prompt asks to delete under --quiet.
+func TestPurgeSnapshots_QuietPromptListsSnapshots(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	v := setupPurgeTest(t, snapHostname, []string{snapHomeT0, snapHomeT1})
+
+	var out bytes.Buffer
+
+	v.Stdout = &out
+	v.UI = ui.NewWithColor(&out, false)
+	v.UI.SetQuiet(true)
+
+	// Stdin is empty, so the prompt reads no answer and cancels.
+	require.NoError(t, v.PurgeSnapshotsWithOptions(&vaultik.SnapshotPurgeOptions{
+		KeepLatest: true,
+	}))
+
+	assert.Contains(t, out.String(), snapHomeT0)
+	assert.Contains(t, out.String(), "Delete 1 snapshot(s)? [y/N]")
+	assert.Len(t, listRemainingSnapshots(t, v), 2)
+}
+
+// TestPruneBlobs_QuietPromptShowsBlobTotal checks that `prune` without
+// --force still states the count and total size of the blobs its prompt
+// asks to delete under --quiet.
+func TestPruneBlobs_QuietPromptShowsBlobTotal(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+	env.v.UI.SetQuiet(true)
+
+	// The store holds no manifest, so nothing references this blob.
+	addBlob(t, env.store.testStorer, testBlobHashA)
+
+	// Stdin is empty, so the prompt reads no answer and cancels.
+	require.NoError(t, env.v.PruneBlobs(&vaultik.PruneOptions{}))
+
+	assert.Contains(t, env.stdout.String(),
+		"Found 1 unreferenced blob(s) totaling")
+	assert.Contains(t, env.stdout.String(),
+		"Delete 1 unreferenced blob(s)? [y/N]")
+}
+
+// TestRemoveSnapshot_QuietSuppressesReport checks that `snapshot remove`
+// under --quiet prints nothing with --dry-run or with --force, and that
+// the --json document still prints.
+func TestRemoveSnapshot_QuietSuppressesReport(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	newQuietRemover := func() (*vaultik.TestVaultik, *testStorer) {
+		store := newTestStorer()
+		addManifest(t, store, "snapshot-001", nil)
+
+		// A backup wrote to this destination, so it carries the marker.
+		require.NoError(t, store.Put(context.Background(), markerFile,
+			bytes.NewReader(nil)))
+
+		tv := vaultik.NewForTesting(store)
+		tv.Repositories = newLocalIndex(t, "snapshot-001")
+		tv.UI.SetQuiet(true)
+
+		return tv, store
+	}
+
+	tv, store := newQuietRemover()
+
+	_, err := tv.RemoveSnapshot("snapshot-001",
+		&vaultik.RemoveOptions{DryRun: true})
+	require.NoError(t, err)
+	assert.Empty(t, tv.Stdout.String(),
+		"--dry-run must print nothing under --quiet")
+
+	_, err = tv.RemoveSnapshot("snapshot-001",
+		&vaultik.RemoveOptions{Force: true})
+	require.NoError(t, err)
+	assert.False(t, store.hasKey(remoteKeyPath("snapshot-001")))
+	assert.Empty(t, tv.Stdout.String(),
+		"--force must print nothing under --quiet")
+
+	tv, _ = newQuietRemover()
+
+	_, err = tv.RemoveSnapshot("snapshot-001",
+		&vaultik.RemoveOptions{JSON: true})
+	require.NoError(t, err)
+
+	var result vaultik.RemoveResult
+
+	require.NoError(t, json.Unmarshal(tv.Stdout.Bytes(), &result),
+		"the --json document must still print under --quiet")
+	assert.True(t, result.RemoteRemoved)
+}
+
+// TestNukeRemote_QuietSuppressesReport checks that `remote nuke --force`
+// under --quiet prints nothing while it removes a snapshot's metadata
+// and its blobs.
+func TestNukeRemote_QuietSuppressesReport(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := filepath.Join(t.TempDir(), "store")
+	v, _, out := backUpToFileDestination(ctx, t, storeDir)
+	v.UI.SetQuiet(true)
+
+	require.NoError(t, v.NukeRemote(true))
+	assert.Empty(t, out.String())
+}

internal/vaultik/remove_snapshot_test.go

@@ -3,17 +3,22 @@ package vaultik_test
 import (
 	"bytes"
 	"context"
+	"database/sql"
 	"io"
 	"strings"
 	"sync"
 	"testing"
+	"time"
 
 	"github.com/klauspost/compress/zstd"
 	"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/storage"
+	"sneak.berlin/go/vaultik/internal/storage/faultstore"
+	"sneak.berlin/go/vaultik/internal/types"
 	"sneak.berlin/go/vaultik/internal/vaultik"
 )
 
@@ -21,11 +26,14 @@ import (
 type testStorer struct {
 	mu   sync.Mutex
 	data map[string][]byte
+	// putTimes holds when Put stored each object; ListStream reports it.
+	putTimes map[string]time.Time
 }
 
 func newTestStorer() *testStorer {
 	return &testStorer{
-		data: make(map[string][]byte),
+		data:     make(map[string][]byte),
+		putTimes: make(map[string]time.Time),
 	}
 }
 
@@ -39,6 +47,7 @@ func (s *testStorer) Put(_ context.Context, key string, reader io.Reader) error
 	}
 
 	s.data[key] = data
+	s.putTimes[key] = time.Now().UTC()
 
 	return nil
 }
@@ -82,6 +91,7 @@ func (s *testStorer) Delete(_ context.Context, key string) error {
 	defer s.mu.Unlock()
 
 	delete(s.data, key)
+	delete(s.putTimes, key)
 
 	return nil
 }
@@ -115,8 +125,9 @@ func (s *testStorer) ListStream(
 		for key, data := range s.data {
 			if prefix == "" || strings.HasPrefix(key, prefix) {
 				ch <- storage.ObjectInfo{
-					Key:  key,
+					Key:     key,
-					Size: int64(len(data)),
+					Size:    int64(len(data)),
+					ModTime: s.putTimes[key],
 				}
 			}
 		}
@@ -125,6 +136,12 @@ func (s *testStorer) ListStream(
 	return ch
 }
 
+// DeletePartialUploads has nothing to remove: Put stores each object
+// under its key at once.
+func (s *testStorer) DeletePartialUploads(_ context.Context, _ string) error {
+	return nil
+}
+
 func (s *testStorer) Info() storage.Info {
 	return storage.Info{
 		Type:     testLabel,
@@ -208,6 +225,37 @@ func addBlob(t *testing.T, store *testStorer, hash string) {
 	require.NoError(t, err)
 }
 
+// newLocalIndex returns an in-memory local index holding a completed
+// snapshot row for each of ids.
+func newLocalIndex(t *testing.T, ids ...string) *database.Repositories {
+	t.Helper()
+
+	ctx := context.Background()
+
+	db, err := database.New(ctx, ":memory:")
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = db.Close() })
+
+	repos := database.NewRepositories(db)
+
+	for _, id := range ids {
+		completedAt := time.Now().UTC()
+		snap := &database.Snapshot{
+			ID:          types.SnapshotID(id),
+			Hostname:    snapHostname,
+			StartedAt:   completedAt,
+			CompletedAt: &completedAt,
+		}
+
+		err = repos.WithTx(ctx, func(ctx context.Context, tx *sql.Tx) error {
+			return repos.Snapshots.Create(ctx, tx, snap)
+		})
+		require.NoError(t, err)
+	}
+
+	return repos
+}
+
 // ============================================================================
 // Unit Tests for RemoveSnapshot
 // ============================================================================
@@ -227,6 +275,7 @@ func TestRemoveSnapshot_LocalOnly_PreservesRemote(t *testing.T) {
 	addBlob(t, store, blobA)
 
 	tv := vaultik.NewForTesting(store)
+	tv.Repositories = newLocalIndex(t, "snapshot-001")
 
 	opts := &vaultik.RemoveOptions{Force: true, LocalOnly: true}
 	result, err := tv.RemoveSnapshot("snapshot-001", opts)
@@ -261,7 +310,12 @@ func TestRemoveSnapshot_DefaultRemovesMetadataNotBlobs(t *testing.T) {
 	addBlob(t, store, blobUnique)
 	addBlob(t, store, blobShared)
 
+	// A backup wrote to this destination, so it carries the marker.
+	require.NoError(t, store.Put(context.Background(), markerFile,
+		bytes.NewReader(nil)))
+
 	tv := vaultik.NewForTesting(store)
+	tv.Repositories = newLocalIndex(t, "snapshot-001", "snapshot-002")
 
 	opts := &vaultik.RemoveOptions{Force: true}
 	result, err := tv.RemoveSnapshot("snapshot-001", opts)
@@ -307,7 +361,128 @@ func TestRemoveSnapshot_DryRun(t *testing.T) {
 	assert.True(t, store.hasKey("blobs/aa/aa/"+blobA))
 	assert.True(t, store.hasKey(remoteKeyPath("snapshot-001")))
 
-	assert.Contains(t, tv.Stdout.String(), "[Dry run - no changes made]")
+	assert.Contains(t, tv.Stdout.String(), "Dry run: no changes made.")
+}
+
+// TestRemoveSnapshot_UnknownIDIsError checks that an ID naming no
+// snapshot in the local index or on the destination store is an error
+// under every option, and that nothing is reported as removed.
+func TestRemoveSnapshot_UnknownIDIsError(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	for name, opts := range map[string]vaultik.RemoveOptions{
+		"force":      {Force: true},
+		"json":       {JSON: true},
+		"dry-run":    {Force: true, DryRun: true},
+		"local-only": {Force: true, LocalOnly: true},
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			store := newTestStorer()
+			addManifest(t, store, "snapshot-001", nil)
+
+			// A backup wrote to this destination, so it carries the marker.
+			require.NoError(t, store.Put(context.Background(), markerFile,
+				bytes.NewReader(nil)))
+
+			tv := vaultik.NewForTesting(store)
+			tv.Repositories = newLocalIndex(t, "snapshot-001")
+
+			result, err := tv.RemoveSnapshot("snapshot-999", &opts)
+
+			require.ErrorContains(t, err, "snapshot not found")
+			assert.False(t, result.RemoteRemoved)
+			assert.Empty(t, tv.Stdout.String())
+			assert.True(t, store.hasKey(remoteKeyPath("snapshot-001")))
+		})
+	}
+}
+
+// TestRemoveSnapshot_NoMetadataOnDestination checks that removing a
+// snapshot whose metadata is not on the destination store does not
+// report metadata removed from it.
+func TestRemoveSnapshot_NoMetadataOnDestination(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	// A backup wrote to this destination, so it carries the marker.
+	store := newTestStorer()
+	require.NoError(t, store.Put(context.Background(), markerFile,
+		bytes.NewReader(nil)))
+
+	tv := vaultik.NewForTesting(store)
+	tv.Repositories = newLocalIndex(t, "snapshot-001")
+
+	result, err := tv.RemoveSnapshot("snapshot-001",
+		&vaultik.RemoveOptions{Force: true})
+
+	require.NoError(t, err)
+	assert.False(t, result.RemoteRemoved)
+
+	out := tv.Stdout.String()
+	assert.Contains(t, out, "Removed snapshot 'snapshot-001' from local database")
+	assert.NotContains(t, out, "Removed snapshot metadata from remote storage")
+}
+
+// TestRemoveSnapshot_NotInLocalIndex checks that removing a snapshot
+// only the destination store holds removes its metadata there without
+// reporting a removal from the local database.
+func TestRemoveSnapshot_NotInLocalIndex(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	store := newTestStorer()
+	addManifest(t, store, "snapshot-001", nil)
+
+	tv := vaultik.NewForTesting(store)
+	tv.Repositories = newLocalIndex(t)
+
+	result, err := tv.RemoveSnapshot("snapshot-001",
+		&vaultik.RemoveOptions{Force: true})
+
+	require.NoError(t, err)
+	assert.True(t, result.RemoteRemoved)
+	assert.False(t, store.hasKey(remoteKeyPath("snapshot-001")))
+
+	out := tv.Stdout.String()
+	assert.NotContains(t, out, "from local database")
+	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) {
@@ -355,7 +530,8 @@ func TestRemoveAllSnapshots_WithForce(t *testing.T) {
 	out := tv.Stdout.String()
 	assert.Contains(t, out, "Removed 2 snapshot(s)")
 	assert.Contains(t, out, "Removed snapshot metadata from remote storage")
-	assert.Contains(t, out, "vaultik prune")
+	// Remote nuke, the only caller, deletes the blobs next itself.
+	assert.NotContains(t, out, "vaultik prune")
 }
 
 func TestRemoveAllSnapshots_DryRun(t *testing.T) {
@@ -382,7 +558,7 @@ func TestRemoveAllSnapshots_DryRun(t *testing.T) {
 
 	assert.Equal(t, initialCount, store.keyCount())
 
-	assert.Contains(t, tv.Stdout.String(), "[Dry run - no changes made]")
+	assert.Contains(t, tv.Stdout.String(), "Dry run: no changes made.")
 }
 
 func TestRemoveAllSnapshots_NoSnapshots(t *testing.T) {

internal/vaultik/restore.go

@@ -12,6 +12,7 @@ import (
 	"path/filepath"
 	"slices"
 	"strings"
+	"syscall"
 	"time"
 
 	"filippo.io/age"
@@ -27,6 +28,7 @@ import (
 // Sentinel errors for restore failures.
 var (
 	errFilesFailedRestore    = errors.New("file(s) failed to restore")
+	errPathsNotInSnapshot    = errors.New("requested path(s) not in the snapshot")
 	errFilesFailedVerify     = errors.New("files failed verification")
 	errDecryptionKeyRequired = errors.New(
 		"decryption key required for restore\n\n" +
@@ -103,11 +105,12 @@ type RestoreResult struct {
 	BlobsDownloaded int
 	BytesDownloaded int64
 	Duration        time.Duration
+	FilesFailed     int
+	FailedFiles     []string // Paths of files that failed to restore
 	// Verification results (only populated if Verify option is set)
-	FilesVerified int
+	FilesVerified     int
-	BytesVerified int64
+	BytesVerified     int64
-	FilesFailed   int
+	VerifyFailedFiles []string // Paths of restored files that failed verification
-	FailedFiles   []string // Paths of files that failed verification
 }
 
 // Restore restores files from a snapshot to the target directory
@@ -149,16 +152,20 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 	repos := database.NewRepositories(tempDB)
 
 	// Step 2: Get list of files to restore
-	files, err := v.getFilesToRestore(v.ctx, repos, opts.Paths)
+	files, unmatched, err := v.getFilesToRestore(v.ctx, repos, opts.Paths)
 	if err != nil {
 		return fmt.Errorf("getting files to restore: %w", err)
 	}
 
+	// Named before anything is restored, so the names are shown even
+	// when the restore stops on an error.
+	unmatchedErr := v.reportUnmatchedPaths(unmatched)
+
 	if len(files) == 0 {
 		log.Warn("No files found to restore")
 		v.UI.Warningf("No files found to restore.")
 
-		return nil
+		return unmatchedErr
 	}
 
 	log.Info("Found files to restore", "count", len(files))
@@ -184,6 +191,20 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 
 	result.Duration = time.Since(startTime)
 
+	return v.finishRestore(repos, files, unmatchedErr, opts, result)
+}
+
+// finishRestore prints the restore summary and the post-restore
+// warnings, runs optional verification, and converts any failed-file
+// count into an error. Otherwise it returns unmatchedErr, the error for
+// the requested paths that matched nothing (nil when there are none).
+func (v *Vaultik) finishRestore(
+	repos *database.Repositories,
+	files []*database.File,
+	unmatchedErr error,
+	opts *RestoreOptions,
+	result *RestoreResult,
+) error {
 	log.Info("Restore complete",
 		"files_restored", result.FilesRestored,
 		"bytes_restored", ubytes(result.BytesRestored),
@@ -198,21 +219,8 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 		v.UI.Duration(result.Duration),
 	)
 
-	return v.finishRestore(repos, files, opts, result)
-}
-
-// finishRestore emits the post-restore warnings, runs optional
-// verification, and converts any failed-file count into an error.
-func (v *Vaultik) finishRestore(
-	repos *database.Repositories,
-	files []*database.File,
-	opts *RestoreOptions,
-	result *RestoreResult,
-) error {
 	if os.Geteuid() != 0 {
-		v.UI.Warningf("Restore did not preserve file ownership: chown(2) " +
+		v.warnIfOwnershipNotPreserved(files, opts.TargetDir)
-			"requires root. Re-run as root (e.g. with sudo) if you need " +
-			"original UID/GID preserved.")
 	}
 
 	if result.FilesFailed > 0 {
@@ -235,7 +243,60 @@ func (v *Vaultik) finishRestore(
 		return fmt.Errorf("%d %w", result.FilesFailed, errFilesFailedRestore)
 	}
 
-	return nil
+	return unmatchedErr
+}
+
+// warnIfOwnershipNotPreserved warns once if some entry restored under
+// targetDir has another owner or group on disk than the snapshot
+// records. It is meant for a restore by a normal user, which changes no
+// owner or group: a new entry is owned by that user, and its group is
+// that user's, or the group of the directory it is created in on macOS
+// and in a setgid directory on Linux. An entry that is not on disk, or
+// whose filesystem reports no owner, is skipped.
+func (v *Vaultik) warnIfOwnershipNotPreserved(
+	files []*database.File, targetDir string,
+) {
+	for _, file := range files {
+		targetPath, err := containedRestorePath(
+			v.Fs, targetDir, file.Path.String())
+		if err != nil {
+			continue
+		}
+
+		info, err := lstatIfPossible(v.Fs, targetPath)
+		if err != nil {
+			continue
+		}
+
+		owner, ok := info.Sys().(*syscall.Stat_t)
+		if !ok {
+			continue
+		}
+
+		if owner.Uid != file.UID || owner.Gid != file.GID {
+			v.UI.Warningf("Restore did not preserve file ownership: chown(2) " +
+				"requires root. Re-run as root (e.g. with sudo) if you need " +
+				"original UID/GID preserved.")
+
+			return
+		}
+	}
+}
+
+// reportUnmatchedPaths warns, by name, about each requested path that
+// matched nothing in the snapshot, and returns an error counting them,
+// or nil when there are none.
+func (v *Vaultik) reportUnmatchedPaths(unmatched []string) error {
+	if len(unmatched) == 0 {
+		return nil
+	}
+
+	for _, path := range unmatched {
+		log.Warn("Requested path matches nothing in the snapshot", "path", path)
+		v.UI.Warningf("%s matches nothing in the snapshot.", v.UI.Path(path))
+	}
+
+	return fmt.Errorf("%d %w", len(unmatched), errPathsNotInSnapshot)
 }
 
 // restoreIdentities parses the configured age secret key once into every
@@ -298,22 +359,33 @@ func (v *Vaultik) restoreAllFiles(
 		_ = blobCache.Close()
 	}()
 
-	// Per-restore sweep state: every blob_size_limit/100 bytes written,
-	// scan the cache and delete any blob whose remaining file references
-	// are all already restored.
-	sweeper := newRestoreSweeper(v.ctx, repos, blobCache,
-		v.Config.BlobSizeLimit.Int64()/sweepIntervalDivisor)
-
 	blobByHash, blobIDToHash, err := v.buildBlobIndexes(repos)
 	if err != nil {
 		return nil, err
 	}
 
-	plan, err := newRestorePlan(v.ctx, repos, files, chunkToBlobMap, blobIDToHash)
+	plan, unplanned, err := newRestorePlan(
+		v.ctx, repos, files, chunkToBlobMap, blobIDToHash)
 	if err != nil {
 		return nil, fmt.Errorf("building restore plan: %w", err)
 	}
 
+	// Per-restore sweep state: every blob_size_limit/100 bytes written,
+	// scan the cache and delete any blob that no pending file in the
+	// plan references.
+	sweeper := newRestoreSweeper(plan, blobCache,
+		v.Config.BlobSizeLimit.Int64()/sweepIntervalDivisor)
+
+	// Ranging over files rather than the map reports them in a stable order.
+	for _, file := range files {
+		if planErr, ok := unplanned[file.ID]; ok {
+			err = v.handleRestoreFileError(plan, opts, result, file, file.ID, planErr)
+			if err != nil {
+				return nil, err
+			}
+		}
+	}
+
 	filesByID, totalBytesExpected := indexRestoreFiles(files)
 
 	v.UI.Beginf("Restoring %s files (%s) to %s.",
@@ -391,10 +463,8 @@ func (v *Vaultik) runRestoreLoop(
 			continue
 		}
 
-		// Record the file as restored so the sweeper can free blobs
+		// Drop the file from the plan's indexes so future picks ignore
-		// once all referencing files are done, and drop it from the
+		// it and the sweeper can free blobs no pending file needs.
-		// plan's indexes so future picks ignore it.
-		session.sweeper.fileRestored(fileID.String())
 		plan.finishFile(fileID)
 
 		processed++
@@ -647,20 +717,34 @@ func (v *Vaultik) handleRestoreVerification(
 	opts *RestoreOptions,
 	result *RestoreResult,
 ) error {
-	err := v.verifyRestoredFiles(v.ctx, repos, files, opts.TargetDir, result)
+	// A file that failed to restore was not written and is already
+	// reported as such, so it is not verified.
+	failedToRestore := make(map[string]bool, len(result.FailedFiles))
+	for _, path := range result.FailedFiles {
+		failedToRestore[path] = true
+	}
+
+	restored := make([]*database.File, 0, len(files))
+	for _, file := range files {
+		if !failedToRestore[file.Path.String()] {
+			restored = append(restored, file)
+		}
+	}
+
+	err := v.verifyRestoredFiles(v.ctx, repos, restored, opts.TargetDir, result)
 	if err != nil {
 		return fmt.Errorf("verification failed: %w", err)
 	}
 
-	if result.FilesFailed > 0 {
+	if len(result.VerifyFailedFiles) > 0 {
 		v.UI.Errorf("Verification failed: %s files did not match expected checksums.",
-			v.UI.Count(result.FilesFailed))
+			v.UI.Count(len(result.VerifyFailedFiles)))
 
-		for _, path := range result.FailedFiles {
+		for _, path := range result.VerifyFailedFiles {
 			v.UI.Detailf("%s", v.UI.Path(path))
 		}
 
-		return fmt.Errorf("%d %w", result.FilesFailed, errFilesFailedVerify)
+		return fmt.Errorf("%d %w", len(result.VerifyFailedFiles), errFilesFailedVerify)
 	}
 
 	v.UI.Completef("Verified %s files (%s).",
@@ -691,6 +775,8 @@ func (v *Vaultik) downloadSnapshotDB(
 		return nil, "", fmt.Errorf("downloading %s: %w", dbKey, err)
 	}
 
+	reader = newCloseOnCancelReader(v.ctx, reader)
+
 	defer func() { _ = reader.Close() }()
 
 	// Decrypt and decompress straight from the storage stream, then stream
@@ -812,27 +898,34 @@ func (v *Vaultik) materializeSnapshotDB(
 	return db, tempDir, nil
 }
 
-// getFilesToRestore returns the list of files to restore based on path filters
+// getFilesToRestore returns the list of files to restore based on path
+// filters, and the filters, as given, that matched no file.
 func (v *Vaultik) getFilesToRestore(
 	ctx context.Context, repos *database.Repositories, pathFilters []string,
-) ([]*database.File, error) {
+) ([]*database.File, []string, error) {
 	// If no filters, get all files
 	if len(pathFilters) == 0 {
-		return repos.Files.ListAll(ctx)
+		files, err := repos.Files.ListAll(ctx)
+
+		return files, nil, err
 	}
 
 	// Get files matching the path filters
-	var result []*database.File
+	var (
+		result    []*database.File
+		unmatched []string
+	)
 
 	seen := make(map[string]bool)
 
 	for _, filter := range pathFilters {
-		// Normalize the filter path
+		files, err := repos.Files.ListUnderPath(ctx, filepath.Clean(filter))
-		filter = filepath.Clean(filter)
-
-		files, err := repos.Files.ListUnderPath(ctx, filter)
 		if err != nil {
-			return nil, fmt.Errorf("listing files under %s: %w", filter, err)
+			return nil, nil, fmt.Errorf("listing files under %s: %w", filter, err)
+		}
+
+		if len(files) == 0 {
+			unmatched = append(unmatched, filter)
 		}
 
 		for _, file := range files {
@@ -843,7 +936,7 @@ func (v *Vaultik) getFilesToRestore(
 		}
 	}
 
-	return result, nil
+	return result, unmatched, nil
 }
 
 // buildChunkToBlobMap creates a mapping from chunk hash to blob information
@@ -908,8 +1001,9 @@ type restoreSession struct {
 	// root can chown a file to an arbitrary UID/GID — non-root chown
 	// always fails with EPERM. Attempting it anyway produces N
 	// guaranteed-failed syscalls + N noisy debug lines, so we skip
-	// the call entirely as non-root and emit one warning at the end
+	// the call entirely as non-root; warnIfOwnershipNotPreserved warns
-	// of the restore explaining that ownership was not preserved.
+	// once at the end of the restore if that left any owner or group
+	// other than recorded.
 	runningAsRoot bool
 	// directories holds every restored directory, for
 	// applyDirectoryMetadata to finish after the restore loop.
@@ -1420,8 +1514,8 @@ func (v *Vaultik) verifyRestoredFiles(
 		if err != nil {
 			log.Error("File verification failed", "path", file.Path, "error", err)
 
-			result.FilesFailed++
+			result.VerifyFailedFiles = append(
-			result.FailedFiles = append(result.FailedFiles, file.Path.String())
+				result.VerifyFailedFiles, file.Path.String())
 		}
 
 		bytesProcessed += file.Size
@@ -1437,7 +1531,7 @@ func (v *Vaultik) verifyRestoredFiles(
 	log.Info("Verification complete",
 		"files_verified", result.FilesVerified,
 		"bytes_verified", ubytes(result.BytesVerified),
-		"files_failed", result.FilesFailed,
+		"files_failed", len(result.VerifyFailedFiles),
 	)
 
 	return nil

internal/vaultik/restore_another_machine_test.go

@@ -42,7 +42,7 @@ func TestRestoreOnAnotherMachine(t *testing.T) {
 	tempDir := t.TempDir()
 
 	dataDir := filepath.Join(tempDir, "source")
-	storeDir := filepath.Join(tempDir, "remote")
+	storeDir := t.TempDir()
 	restoreDir := filepath.Join(tempDir, "restored")
 	dbPath := filepath.Join(tempDir, "index.sqlite")