fetch: client timeout, retry with backoff, url.JoinPath (closes #63 )

fetch now makes every request through an http.Client with a time limit, ten minutes by default and set with --timeout, which must be greater than zero. A connection error, a timeout, or a 5xx or 429 response is retried, up to five tries in all, after a random wait whose limit doubles from one second, or after the wait the server's Retry-After asks for, up to one minute. Each try of a file starts a new temp file, so a retry never keeps a partial file; the size and hash checks are unchanged. Manifest and file URLs are built with URL.JoinPath, so a base URL with or without a trailing slash or with a query string, and names that need escaping, all work. Model: opus-5-5
AddFileWithHash rejects hashes that are not multihashes (closes #129 )
2026-10-04 13:22:35 +00:00 · 2026-10-04 14:48:49 +02:00 · 2026-10-04 13:48:52 +02:00 · 2026-10-04 13:31:57 +02:00 · 2026-10-04 12:19:31 +02:00 · 2026-10-04 12:02:27 +02:00
38 changed files with 1849 additions and 385 deletions
@@ -8,7 +8,7 @@ vendor.tzst
 modcache.tzst

 # Generated manifest files
-.index.mf
+/index.mf

 # Secrets
 .env
@@ -8,13 +8,12 @@ RUN go mod download

 COPY . .

-# Touch .pb.go so make does not try to regenerate via protoc (file is committed)
-RUN touch mfer/mf.pb.go
-
 # Go half of fmt-check only: this image has no node, so no prettier. The
 # markdown half runs in the mdfmt stage below.
 RUN make fmt-check-go
-RUN make lint
+# The linter directly, not `make lint`: script/lint builds this stage, and
+# there is no docker inside this build.
+RUN golangci-lint run --config .golangci.yml ./...

 # Markdown/JSON format stage — prettier needs node, which the Go images
 # do not have. node:22.17.0-bookworm-slim (2026-08-09); ships node
@@ -44,9 +43,6 @@ RUN go mod download

 COPY . .

-# Touch .pb.go so make does not try to regenerate via protoc (file is committed)
-RUN touch mfer/mf.pb.go
-
 RUN make test

 # A build context sent as a tar archive, as upaas sends it, keeps its files'
@@ -67,8 +63,13 @@ RUN version="${VERSION:-$(git describe --tags --always)}"; \
        exit 1; \
    fi; \
    cd cmd/mfer && \
-    go build -tags urfave_cli_no_docs -ldflags "-X main.Gitrev=$version" -o /mfer .
+    CGO_ENABLED=0 go build -tags urfave_cli_no_docs -ldflags "-X main.Gitrev=$version" -o /mfer .
+
+# Fail unless /mfer is statically linked: scratch has no C library to run it.
+RUN ldd /mfer 2>&1 | grep -q 'not a dynamic executable'

 FROM scratch
+# scratch has no CA certificates; fetch needs them to verify HTTPS servers.
+COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
 COPY --from=builder /mfer /mfer
 ENTRYPOINT ["/mfer"]
@@ -49,7 +49,9 @@ The `innerMessage` field is compressed with
 enforce a decompression size limit to prevent decompression bombs. The reference
 implementation limits decompressed size to 256 MB. It writes zstd frames with a
 window of at most 8 MiB, the largest window the zstd format recommends decoders
-support, and refuses frames that ask for a larger one.
+support, and refuses frames that ask for a larger one. It also refuses an inner
+message whose file entries, hashes, timestamps and MIME types, counted at 160,
+112, 64 and 16 bytes each, add up to more than 8 times its size.

 ## Inner Message (`MFFile`)

@@ -2,7 +2,6 @@ export DOCKER_BUILDKIT := 1
 export PROGRESS_NO_TRUNC := 1
 GOPATH := $(shell go env GOPATH)
 export PATH := $(PATH):$(GOPATH)/bin
-PROTOC_GEN_GO := $(GOPATH)/bin/protoc-gen-go
 SOURCEFILES := mfer/*.go mfer/*.proto internal/*/*.go cmd/*/*.go go.mod go.sum
 ARCH := $(shell uname -m)
 GITREV_BUILD := $(shell bash $(PWD)/bin/gitrev.sh 2>/dev/null || echo unknown)
@@ -13,7 +12,7 @@ GOLDFLAGS += -X main.Version=$(VERSION)
 GOLDFLAGS += -X main.Gitrev=$(GITREV_BUILD)
 GOFLAGS := -ldflags "$(GOLDFLAGS)"

-.PHONY: bootstrap setup docker default run ci test fuzz check lint fmt fmt-check fmt-check-go fmt-check-md hooks fixme
+.PHONY: bootstrap setup docker default run ci test fuzz check lint fmt fmt-check fmt-check-go fmt-check-md hooks fixme generate

 default: fmt test

@@ -35,9 +34,6 @@ test:
 fuzz:
 	@script/fuzz

-$(PROTOC_GEN_GO):
-	test -e $(PROTOC_GEN_GO) || go install -v google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.1
-
 fixme:
 	@grep -nir fixme . | grep -v Makefile

@@ -58,18 +54,14 @@ fmt-check-md:
 hooks:
 	@script/install-precommit

-devprereqs:
-	which golangci-lint || go install -v github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2
+generate:
+	@script/generate

-mfer/mf.pb.go: mfer/mf.proto
-	cd mfer && go generate .
-
-bin/mfer: $(SOURCEFILES) mfer/mf.pb.go
-	protoc --version
+bin/mfer: $(SOURCEFILES)
 	cd cmd/mfer && go build -tags urfave_cli_no_docs -o ../../bin/mfer $(GOFLAGS) .

 clean:
-	rm -rfv mfer/*.pb.go bin/mfer cmd/mfer/mfer *.dockerimage
+	rm -rfv bin/mfer cmd/mfer/mfer *.dockerimage

 fmt:
 	@script/fmt
@@ -1,12 +1,12 @@
 # mfer

-[mfer](https://git.eeqj.de/sneak/mfer) is a reference implementation library and
-thin wrapper command-line utility written in [Go](https://golang.org) and first
-published in 2022 under the [WTFPL](https://wtfpl.net) (public domain) license.
-It specifies and generates `.mf` manifest files over a directory tree of files
-to encapsulate metadata about them (such as cryptographic checksums or
-signatures over same) to aid in archiving, downloading, and streaming, or
-mirroring. The manifest files' data is serialized with Google's
+[mfer](https://git.eeqj.de/sneak/mfer) is a [WTFPL](https://wtfpl.net)-licensed
+(public domain) [Go](https://golang.org) library and command-line tool by
+[@sneak](https://sneak.berlin) that specifies and generates `.mf` manifest files
+over a directory tree to encapsulate metadata about the files — such as
+cryptographic checksums and signatures over same — to aid in archiving,
+downloading, streaming, and mirroring. It was first published in 2022. The
+manifest files' data is serialized with Google's
 [protobuf serialization format](https://developers.google.com/protocol-buffers).
 The structure of these files can be found
 [in the format specification](https://git.eeqj.de/sneak/mfer/src/branch/main/mfer/mf.proto)
@@ -21,6 +21,36 @@ This project was started by [@sneak](https://sneak.berlin) to scratch an itch in
 as a de-facto standard and be incorporated into other software. A compatible
 javascript library is planned.

+# Getting Started
+
+`mfer` builds from source with a Go 1.23+ toolchain. The generated protobuf code
+is committed, so no `protoc` toolchain is required:
+
+```sh
+git clone https://git.eeqj.de/sneak/mfer.git
+cd mfer
+go build -o bin/mfer ./cmd/mfer
+```
+
+Generate a manifest for a directory tree, verify it later, and fetch a published
+tree by URL:
+
+```sh
+# Write index.mf, a manifest of the files under the current directory.
+bin/mfer gen .
+
+# Verify the files on disk against the manifest. Exits nonzero if any file
+# is missing or corrupted.
+bin/mfer check index.mf
+
+# Download and cryptographically verify a tree published over HTTP: mfer
+# fetches <url>/index.mf, then downloads every file it lists.
+bin/mfer fetch https://example.com/tree/
+```
+
+Run `bin/mfer help` for the full command list, or `bin/mfer <command> --help`
+for a single command's options.
+
 # Build Status

 CI runs `script/cibuild`, which builds the Docker image with `--no-cache`, so
@@ -35,21 +65,34 @@ standard: normalized scripts in `script/` are the entrypoints for the
 development workflow, and the Makefile targets are thin shims that call them. We
 provide:

- `script/bootstrap` — install all dependencies (Go, golangci-lint, Go module
-  download, and node/yarn plus the prettier version pinned in
-  `package.json`/`yarn.lock`), idempotently
+- `script/bootstrap` — install all dependencies (Go, Go module download, and
+  node/yarn plus the prettier version pinned in `package.json`/`yarn.lock`),
+  idempotently; golangci-lint is not installed, it runs only in Docker
 - `script/setup` — make a fresh clone ready for development: runs
  `script/bootstrap`, then `script/install-precommit`
 - `script/projectname` — output the project name (`mfer`); used by other scripts
  such as `script/docker`
- `script/test` — run the test suite (`go test`), regenerating the protobuf code
-  first if it is stale
+- `script/test` — run the test suite (`go test`); one test fails when
+  `mfer/mf.proto` no longer matches the hash `script/generate` recorded
+- `script/generate` (`make generate`) — regenerate `mfer/mf.pb.go` from
+  `mfer/mf.proto` and record the hash of that `mfer/mf.proto` in
+  `mfer/mf.proto.sha256`; the only thing that regenerates the committed
+  `mfer/mf.pb.go`. It needs the exact versions that wrote the committed file,
+  and refuses to run with any other: `protoc` 33.4 (unpack
+  `protoc-33.4-<platform>.zip` from
+  [its release](https://github.com/protocolbuffers/protobuf/releases/tag/v33.4)
+  and put its `bin/protoc` on `PATH`) and `protoc-gen-go` v1.36.11
+  (`go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.11`, which
+  installs it in `$(go env GOPATH)/bin`; `make generate` adds that directory to
+  `PATH`)
 - `script/fuzz` — fuzz the manifest parser for one minute; run by hand
  (`make fuzz`), never by CI, while `script/test` runs its committed seed corpus
  as ordinary tests
- `script/lint` — run `golangci-lint` and verify `gofmt` cleanliness
- `script/fmt` — format all code and docs (writes): `gofumpt`,
-  `golangci-lint run --fix`, and `script/prettier --write`
+- `script/lint` — run `golangci-lint` in Docker: builds only the `lint` stage of
+  the `Dockerfile` (the Go format check, then the linter), uncached so it runs
+  every time, then removes the image
+- `script/fmt` — format all code and docs (writes): `gofumpt` and
+  `script/prettier --write`
 - `script/prettier` — run prettier over the repository's canonical file set
  (Markdown and JSON, minus `.prettierignore`) in the given mode, `--write` or
  `--check`; the single definition of that file set, so `script/fmt` and
@@ -75,17 +118,18 @@ yet. Primary development happens on a privately-run Gitea instance at
 [tracked there](https://git.eeqj.de/sneak/mfer/issues).

 Changes must always be formatted with a standard `go fmt`, syntactically valid,
-and must pass the linting defined in the repository (presently only the
-`golangci-lint` defaults), which can be run with a `make lint`. The `main`
-branch is protected and all changes must be made via
-[pull requests](https://git.eeqj.de/sneak/mfer/pulls) and pass CI to be merged.
-Any changes submitted to this project must also be
+and must pass the linting defined in the repository's `.golangci.yml`, which
+`make lint` runs in Docker. The `main` branch is protected and all changes must
+be made via [pull requests](https://git.eeqj.de/sneak/mfer/pulls) and pass CI to
+be merged. Any changes submitted to this project must also be
 [WTFPL-licensed](https://wtfpl.net) to be considered.

 See [`REPO_POLICIES.md`](REPO_POLICIES.md) for detailed coding standards,
 tooling requirements, and workflow conventions.

-# Problem Statement
+# Rationale
+
+## The problem

 Given a plain URL, there is no standard way to safely and programmatically
 download everything "under" that URL path. `wget -r` can traverse directory
@@ -109,7 +153,7 @@ Real issues I face:
 - when I download a large file via HTTP, I have no way of knowing if the file
  content is what it's supposed to be

-# Proposed Solution
+## The solution

 A standard, a manifest file format, and a tool for generating same.

@@ -141,6 +185,28 @@ The manifest file would do several important things:
    - maybe a bittorrent chunklist for torrent client compatibility? perhaps a
      top-level infohash for the whole manifest?

+# Design
+
+The repository is split into a reusable library and a thin command-line wrapper
+around it.
+
+- `mfer/` is the reusable library and the heart of the project: it defines the
+  manifest format and implements building, scanning, checking, serialization,
+  and signing. The protobuf schema is `mfer/mf.proto`, and the generated code it
+  produces (`mfer/mf.pb.go`) is committed alongside it so the library builds
+  with `go get` and needs no `protoc` toolchain.
+- `internal/cli/` holds the command implementations — `generate` (alias `gen`),
+  `check`, `freshen`, `export`, `list` (alias `ls`), `fetch`, and `version` —
+  that wire the library to the command-line interface.
+- `internal/log/` provides the logging used by the commands and the library.
+- `internal/bork/` provides the error the library returns when a manifest's
+  decompressed contents are not the size the manifest records.
+- `cmd/mfer/` is the entrypoint: its `main` package runs `internal/cli` and
+  exits with the status it returns.
+
+Everything under `internal/` is private to this repository; only the `mfer/`
+package is intended for import by other software.
+
 # Design Goals

 - Replace SHASUMS/SHASUMS.asc files
@@ -274,9 +340,9 @@ Open work, open design questions included, is tracked in this repo's issues:
 - Issues:
  [https://git.eeqj.de/sneak/mfer/issues](https://git.eeqj.de/sneak/mfer/issues)

-# Authors
+# Author

- [@sneak &lt;sneak@sneak.berlin&gt;](mailto:sneak@sneak.berlin)
+- [@sneak](https://sneak.berlin)

 # License

@@ -12,13 +12,13 @@ require (
 	github.com/pterm/pterm v0.12.35
 	github.com/spf13/afero v1.8.0
 	github.com/stretchr/testify v1.8.1
-	github.com/urfave/cli/v2 v2.23.6
+	github.com/urfave/cli/v2 v2.27.7
 	google.golang.org/protobuf v1.28.1
 )

 require (
 	github.com/atomicgo/cursor v0.0.1 // indirect
-	github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.7 // indirect
 	github.com/fatih/color v1.7.0 // indirect
 	github.com/gookit/color v1.4.2 // indirect
 	github.com/klauspost/cpuid/v2 v2.0.9 // indirect
@@ -34,7 +34,7 @@ require (
 	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/spaolacci/murmur3 v1.1.0 // indirect
 	github.com/xo/terminfo v0.0.0-20210125001918-ca9a967f8778 // indirect
-	github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673 // indirect
+	github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1 // indirect
 	golang.org/x/crypto v0.0.0-20220525230936-793ad666bf5e // indirect
 	golang.org/x/sys v0.1.0 // indirect
 	golang.org/x/term v0.0.0-20210927222741-03fcf44c2211 // indirect
@@ -61,8 +61,8 @@ github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDk
 github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
 github.com/cncf/udpa/go v0.0.0-20200629203442-efcf912fb354/go.mod h1:WmhPx2Nbnhtbo57+VJT5O0JRkEi1Wbu0z5j0R8u5Hbk=
 github.com/cncf/udpa/go v0.0.0-20201120205902-5459f2c99403/go.mod h1:WmhPx2Nbnhtbo57+VJT5O0JRkEi1Wbu0z5j0R8u5Hbk=
-github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
-github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
+github.com/cpuguy83/go-md2man/v2 v2.0.7 h1:zbFlGlXEAKlwXpmvle3d8Oe3YnkKIK4xSRTd3sHPnBo=
+github.com/cpuguy83/go-md2man/v2 v2.0.7/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -231,12 +231,12 @@ github.com/tj/go-buffer v1.1.0/go.mod h1:iyiJpfFcR2B9sXu7KvjbT9fpM4mOelRSDTbntVj
 github.com/tj/go-elastic v0.0.0-20171221160941-36157cbbebc2/go.mod h1:WjeM0Oo1eNAjXGDx2yma7uG2XoyRZTq1uv3M/o7imD0=
 github.com/tj/go-kinesis v0.0.0-20171128231115-08b17f58cb1b/go.mod h1:/yhzCV0xPfx6jb1bBgRFjl5lytqVqZXEaeqWP8lTEao=
 github.com/tj/go-spin v1.1.0/go.mod h1:Mg1mzmePZm4dva8Qz60H2lHwmJ2loum4VIrLgVnKwh4=
-github.com/urfave/cli/v2 v2.23.6 h1:iWmtKD+prGo1nKUtLO0Wg4z9esfBM4rAV4QRLQiEmJ4=
-github.com/urfave/cli/v2 v2.23.6/go.mod h1:GHupkWPMM0M/sj1a2b4wUrWBPzazNrIjouW6fmdJLxc=
+github.com/urfave/cli/v2 v2.27.7 h1:bH59vdhbjLv3LAvIu6gd0usJHgoTTPhCFib8qqOwXYU=
+github.com/urfave/cli/v2 v2.27.7/go.mod h1:CyNAG/xg+iAOg0N4MPGZqVmv2rCoP267496AOXUZjA4=
 github.com/xo/terminfo v0.0.0-20210125001918-ca9a967f8778 h1:QldyIu/L63oPpyvQmHgvgickp1Yw510KJOqX7H24mg8=
 github.com/xo/terminfo v0.0.0-20210125001918-ca9a967f8778/go.mod h1:2MuV+tbUrU1zIOPMxZ5EncGwgmMJsa+9ucAQZXxsObs=
-github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673 h1:bAn7/zixMGCfxrRTfdpNzjtPYqr8smhKouy9mxVdGPU=
-github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673/go.mod h1:N3UwUGtsrSj3ccvlPHLoLsHnpR27oXr4ZE984MbSER8=
+github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1 h1:gEOO8jv9F4OT7lGCjxCBTO/36wtF6j2nSip77qHd4x4=
+github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1/go.mod h1:Ohn+xnUBiLI6FVj/9LpzZWtj1/D6lUovWYBkxHVV3aM=
 github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
@@ -75,25 +75,22 @@ func safeRateUint64(rate float64) uint64 {
 	return uint64(rate)
 }

-// findManifest looks for a manifest file in the given directory.
-// It checks for index.mf and .index.mf, returning the first one found.
+// findManifest returns the path of the manifest with the default name in
+// dir, or an error if there is none.
 func findManifest(fs afero.Fs, dir string) (string, error) {
-	candidates := []string{"index.mf", ".index.mf"}
-	for _, name := range candidates {
-		path := filepath.Join(dir, name)
+	path := filepath.Join(dir, defaultManifestName)

-		exists, err := afero.Exists(fs, path)
-		if err != nil {
-			return "", err
-		}
-
-		if exists {
-			return path, nil
-		}
+	exists, err := afero.Exists(fs, path)
+	if err != nil {
+		return "", err
 	}

-	return "", fmt.Errorf(
-		"%w in %s (looked for index.mf and .index.mf)", errNoManifestFound, dir)
+	if !exists {
+		return "", fmt.Errorf("%w in %s (looked for %s)",
+			errNoManifestFound, dir, defaultManifestName)
+	}
+
+	return path, nil
 }

 // fetchManifestToTemp downloads a manifest URL to a temporary file and
@@ -298,7 +295,11 @@ func (mfa *CLIApp) checkManifestOperation(ctx *cli.Context) error {
 	log.Infof("checking manifest %s with base %s", manifestPath, basePath)

 	// Create checker
-	chk, err := mfer.NewChecker(manifestPath, basePath, mfa.Fs)
+	chk, err := mfer.NewChecker(&mfer.CheckerOptions{
+		ManifestPath: manifestPath,
+		BasePath:     basePath,
+		Fs:           mfa.Fs,
+	})
 	if err != nil {
 		return fmt.Errorf("failed to load manifest: %w", err)
 	}
@@ -8,6 +8,9 @@ import (
 	"io"
 	"math/rand"
 	"os"
+	"path/filepath"
+	"slices"
+	"strings"
 	"sync"
 	"testing"

@@ -25,11 +28,11 @@ const (
 	testFile1       = "/testdir/file1.txt"
 	testMF          = "/testdir/test.mf"
 	testOutput      = "/output.mf"
-	testOutputTmp   = "/output.mf.tmp"
 	testManifest    = "/manifest.mf"
 	testFlagBase    = "--base"
 	testFlagNoExtra = "--no-extra-files"
 	testFlagVersion = "--version"
+	testFlagVerbose = "--verbose"
 )

 var errSimulatedWrite = errors.New("simulated write failure")
@@ -42,20 +45,32 @@ var errSimulatedWrite = errors.New("simulated write failure")
 var runMu sync.Mutex

 // runCLI invokes RunWithOptions while holding runMu so parallel tests
-// capture their own output. Before releasing the lock it points the
-// process-global logger at io.Discard: other tests log outside the lock
-// (manifest loads, scans), and those lines must not land in this run's
-// buffers once it has returned and its test is reading them.
+// capture their own output, and returns its exit code.
 func runCLI(opts *RunOptions) int {
+	exitCode, _ := runCLIWithLevel(opts)
+
+	return exitCode
+}
+
+// runCLIWithLevel is runCLI that also returns the log level the run left
+// set, read while runMu still keeps other runs from changing it. Each run
+// starts at the default level, as a new process does. Before releasing the
+// lock it points the process-global logger at io.Discard: other tests log
+// outside the lock (manifest loads, scans), and those lines must not land in
+// this run's buffers once it has returned and its test is reading them.
+func runCLIWithLevel(opts *RunOptions) (int, log.Level) {
 	runMu.Lock()
 	defer runMu.Unlock()

+	log.SetLevel(log.InfoLevel)
+
 	exitCode := RunWithOptions(opts)
+	level := log.GetLevel()

 	log.SetOutput(io.Discard, io.Discard)
 	log.Init()

-	return exitCode
+	return exitCode, level
 }

 func TestMain(m *testing.M) {
@@ -235,6 +250,90 @@ func TestRootVerbosityFlags(t *testing.T) {
 	})
 }

+// commandsTakingVerbose returns the command lines -v can follow: the root and
+// the generate, check, freshen and fetch subcommands.
+func commandsTakingVerbose() [][]string {
+	return [][]string{
+		{testApp},
+		{testApp, cmdGenerate},
+		{testApp, cmdCheck},
+		{testApp, cmdFreshen},
+		{testApp, cmdFetch},
+	}
+}
+
+// TestVerboseCount asserts that one -v or --verbose gives verbose output and
+// two -v give debug output (issue #125). urfave/cli before v2.25.5 counted a
+// flag given by its alias twice, so one -v gave debug output.
+func TestVerboseCount(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		flags []string
+		want  log.Level
+	}{
+		{[]string{"-v"}, log.VerboseLevel},
+		{[]string{testFlagVerbose}, log.VerboseLevel},
+		{[]string{"-v", "-v"}, log.DebugLevel},
+	}
+
+	for _, command := range commandsTakingVerbose() {
+		for _, tc := range cases {
+			args := slices.Concat(command, tc.flags)
+
+			t.Run(strings.Join(args, " "), func(t *testing.T) {
+				t.Parallel()
+
+				_, level := runCLIWithLevel(testOpts(args, afero.NewMemMapFs()))
+				assert.Equal(t, tc.want, level)
+			})
+		}
+	}
+}
+
+// TestCombinedShortVerboseRefused asserts that -vv is refused (issue #125):
+// single-letter flags do not combine, so the -v help text says -v -v.
+func TestCombinedShortVerboseRefused(t *testing.T) {
+	t.Parallel()
+
+	for _, command := range commandsTakingVerbose() {
+		args := slices.Concat(command, []string{"-vv"})
+
+		t.Run(strings.Join(args, " "), func(t *testing.T) {
+			t.Parallel()
+
+			opts := testOpts(args, afero.NewMemMapFs())
+			exitCode, level := runCLIWithLevel(opts)
+
+			assert.Equal(t, 1, exitCode)
+			assert.Contains(t, testStderr(t, opts), "flag provided but not defined: -vv")
+			assert.Equal(t, log.InfoLevel, level)
+		})
+	}
+}
+
+// TestShortAndLongVerboseRefused asserts that -v and --verbose given together
+// are refused (issue #125): urfave/cli v2 refuses a flag given under two of its
+// names, and one flag with an alias keeps help and parsing simple.
+func TestShortAndLongVerboseRefused(t *testing.T) {
+	t.Parallel()
+
+	for _, command := range commandsTakingVerbose() {
+		args := slices.Concat(command, []string{"-v", testFlagVerbose})
+
+		t.Run(strings.Join(args, " "), func(t *testing.T) {
+			t.Parallel()
+
+			opts := testOpts(args, afero.NewMemMapFs())
+			exitCode, level := runCLIWithLevel(opts)
+
+			assert.Equal(t, 1, exitCode)
+			assert.Contains(t, testStderr(t, opts), "Cannot use two forms of the same flag")
+			assert.Equal(t, log.InfoLevel, level)
+		})
+	}
+}
+
 func TestHelpCommand(t *testing.T) {
 	t.Parallel()

@@ -405,7 +504,10 @@ func TestGenerateExcludesDotfilesByDefault(t *testing.T) {
 	assert.True(t, exists)

 	// Verify manifest only has 1 file (the non-dotfile)
-	manifest, err := mfer.NewManifestFromFile(fs, testMF)
+	manifest, err := mfer.NewManifestFromFile(&mfer.ManifestFromFileOptions{
+		Path: testMF,
+		Fs:   fs,
+	})
 	require.NoError(t, err)
 	assert.Len(t, manifest.Files(), 1)
 	assert.Equal(t, "file1.txt", manifest.Files()[0].GetPath())
@@ -429,7 +531,10 @@ func TestGenerateWithIncludeDotfiles(t *testing.T) {
 	require.Equal(t, 0, exitCode)

 	// Verify manifest has 2 files (including dotfile)
-	manifest, err := mfer.NewManifestFromFile(fs, testMF)
+	manifest, err := mfer.NewManifestFromFile(&mfer.ManifestFromFileOptions{
+		Path: testMF,
+		Fs:   fs,
+	})
 	require.NoError(t, err)
 	assert.Len(t, manifest.Files(), 2)
 }
@@ -577,7 +682,7 @@ func TestGenerateAtomicWriteNoTempFileOnSuccess(t *testing.T) {
 	assert.True(t, exists, "output file should exist")

 	// Verify temp file does NOT exist
-	tmpExists, err := afero.Exists(fs, testOutputTmp)
+	tmpExists, err := afero.Exists(fs, manifestTempPath(testOutput))
 	require.NoError(t, err)
 	assert.False(t, tmpExists,
 		"temp file should not exist after successful generation")
@@ -609,7 +714,7 @@ func TestGenerateAtomicWriteOverwriteWithForce(t *testing.T) {
 		"manifest should be overwritten")

 	// Verify temp file does NOT exist
-	tmpExists, err := afero.Exists(fs, testOutputTmp)
+	tmpExists, err := afero.Exists(fs, manifestTempPath(testOutput))
 	require.NoError(t, err)
 	assert.False(t, tmpExists,
 		"temp file should not exist after successful generation")
@@ -638,6 +743,102 @@ func TestGenerateFailsWithoutForceWhenOutputExists(t *testing.T) {
 	assert.Equal(t, "existing", string(content), "original file should be preserved")
 }

+// manifestPaths returns the file paths listed by the manifest at path.
+func manifestPaths(t *testing.T, fs afero.Fs, path string) []string {
+	t.Helper()
+
+	manifest, err := mfer.NewManifestFromFile(&mfer.ManifestFromFileOptions{
+		Path: path,
+		Fs:   fs,
+	})
+	require.NoError(t, err)
+
+	paths := make([]string, 0, len(manifest.Files()))
+	for _, f := range manifest.Files() {
+		paths = append(paths, f.GetPath())
+	}
+
+	return paths
+}
+
+// TestGenerateLeavesOutputOutOfListing overwrites an output file inside the
+// scanned tree with --force: the old file is not listed, even when the tree
+// is named through a symlink, while a file named index.mf in a subdirectory
+// still is. The output file is recognized by file identity, which needs
+// the real filesystem.
+func TestGenerateLeavesOutputOutOfListing(t *testing.T) {
+	t.Parallel()
+
+	// Paths are relative to a temp dir holding data/tree and link, a
+	// symlink to data.
+	for name, tc := range map[string]struct{ input, output string }{
+		"default name":                 {"data/tree", "data/tree/index.mf"},
+		"other name in a subdirectory": {"data/tree", "data/tree/sub/listing.mf"},
+		"tree named through a symlink": {"link/tree", "data/tree/index.mf"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			root := t.TempDir()
+			tree := filepath.Join(root, "data", "tree")
+			output := filepath.Join(root, tc.output)
+
+			fs := afero.NewOsFs()
+			require.NoError(t, fs.MkdirAll(filepath.Join(tree, "sub"), 0o750))
+			require.NoError(t,
+				os.Symlink(filepath.Join(root, "data"), filepath.Join(root, "link")))
+			writeTestFile(t, fs, filepath.Join(tree, testFileTxt), "hello")
+			writeTestFile(t, fs, filepath.Join(tree, "sub", "index.mf"), "an ordinary file")
+			writeTestFile(t, fs, output, "previous manifest")
+
+			opts := testOpts([]string{
+				testApp, cmdGenerate, "-q", "--force", "-o", output, filepath.Join(root, tc.input),
+			}, fs)
+			require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+			assert.ElementsMatch(t, []string{testFileTxt, "sub/index.mf"},
+				manifestPaths(t, fs, output))
+		})
+	}
+}
+
+// TestGenerateDefaultOutputLeftOutOfListing runs gen with --force and no
+// other arguments, so it scans the current directory and writes the
+// relative path index.mf: the index.mf already there is not listed.
+//
+//nolint:paralleltest // changes the process-global working directory
+func TestGenerateDefaultOutputLeftOutOfListing(t *testing.T) {
+	chdirTemp(t)
+
+	fs := afero.NewOsFs()
+	writeTestFile(t, fs, testFileTxt, "hello")
+	writeTestFile(t, fs, "index.mf", "previous manifest")
+
+	opts := testOpts([]string{testApp, cmdGenerate, "-q", "--force"}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	assert.Equal(t, []string{testFileTxt}, manifestPaths(t, fs, "index.mf"))
+}
+
+// TestGenerateLeavesLeftoverTempFileOutOfListing runs gen where an
+// interrupted run left its temp file beside the output: the leftover is
+// not listed, and gen does not fail when it overwrites it.
+func TestGenerateLeavesLeftoverTempFileOutOfListing(t *testing.T) {
+	t.Parallel()
+
+	root := t.TempDir()
+	output := filepath.Join(root, "index.mf")
+
+	fs := afero.NewOsFs()
+	writeTestFile(t, fs, filepath.Join(root, testFileTxt), "hello")
+	writeTestFile(t, fs, manifestTempPath(output), "part of a manifest")
+
+	opts := testOpts([]string{testApp, cmdGenerate, "-q", "-o", output, root}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	assert.Equal(t, []string{testFileTxt}, manifestPaths(t, fs, output))
+}
+
 func TestGenerateAtomicWriteUsesTemp(t *testing.T) {
 	t.Parallel()

@@ -660,7 +861,7 @@ func TestGenerateAtomicWriteUsesTemp(t *testing.T) {
 	exists, _ := afero.Exists(fs, testOutput)
 	assert.True(t, exists, "output file should exist")

-	tmpExists, _ := afero.Exists(fs, testOutputTmp)
+	tmpExists, _ := afero.Exists(fs, manifestTempPath(testOutput))
 	assert.False(t, tmpExists, "temp file should be cleaned up")

 	// Verify manifest is valid (not empty)
@@ -726,7 +927,7 @@ func TestGenerateAtomicWriteCleansUpOnError(t *testing.T) {
 		"output file should not exist after failed generation (atomic write)")

 	// Temp file should also not exist
-	tmpExists, _ := afero.Exists(baseFs, testOutputTmp)
+	tmpExists, _ := afero.Exists(baseFs, manifestTempPath(testOutput))
 	assert.False(t, tmpExists,
 		"temp file should be cleaned up after failed generation")
 }
@@ -61,7 +61,11 @@ func unsignedChecker(t *testing.T) *mfer.Checker {
 	require.NoError(t, s.ToManifest(context.Background(), &buf, nil))
 	require.NoError(t, afero.WriteFile(fs, "/d/index.mf", buf.Bytes(), 0o644))

-	chk, err := mfer.NewChecker("/d/index.mf", "/d", fs)
+	chk, err := mfer.NewChecker(&mfer.CheckerOptions{
+		ManifestPath: "/d/index.mf",
+		BasePath:     "/d",
+		Fs:           fs,
+	})
 	require.NoError(t, err)
 	require.False(t, chk.IsSigned())

@@ -74,7 +78,7 @@ func TestNoManifestFoundMessage(t *testing.T) {
 	_, err := findManifest(afero.NewMemMapFs(), "/tmp/x")
 	require.ErrorIs(t, err, errNoManifestFound)
 	assert.EqualError(t, err,
-		"no manifest found in /tmp/x (looked for index.mf and .index.mf)")
+		"no manifest found in /tmp/x (looked for index.mf)")
 }

 func TestVerifyRequiredSignerMessages(t *testing.T) {
@@ -167,7 +171,11 @@ func signedChecker(t *testing.T) *mfer.Checker {
 	fs := afero.NewMemMapFs()
 	require.NoError(t, afero.WriteFile(fs, "/index.mf", buf.Bytes(), 0o644))

-	chk, err := mfer.NewChecker("/index.mf", "/", fs)
+	chk, err := mfer.NewChecker(&mfer.CheckerOptions{
+		ManifestPath: "/index.mf",
+		BasePath:     "/",
+		Fs:           fs,
+	})
 	require.NoError(t, err)
 	require.True(t, chk.IsSigned())

@@ -264,10 +272,15 @@ func TestFetchManifestHTTPStatusMessage(t *testing.T) {
 		}))
 	defer server.Close()

-	set := flag.NewFlagSet("fetch", flag.ContinueOnError)
+	mfa := &CLIApp{Fs: afero.NewMemMapFs()}
+
+	set := flag.NewFlagSet(cmdFetch, flag.ContinueOnError)
+	for _, f := range mfa.fetchCommand().Flags {
+		require.NoError(t, f.Apply(set))
+	}
+
 	require.NoError(t, set.Parse([]string{server.URL}))

-	mfa := &CLIApp{Fs: afero.NewMemMapFs()}
 	ctx := urfcli.NewContext(nil, set, nil)

 	// fetchManifestOperation logs to the process-global logger.
@@ -285,8 +298,11 @@ func TestFetchFileHTTPStatusMessage(t *testing.T) {
 		}))
 	defer server.Close()

-	err := downloadFile(context.Background(), server.URL+"/x", "x",
-		&mfer.MFFilePath{}, nil)
+	// downloadFile logs each retry of the 500 to the process-global logger.
+	err := runLocked(func() error {
+		return downloadFile(context.Background(), testClient(), server.URL+"/x", "x",
+			&mfer.MFFilePath{}, nil)
+	})
 	require.ErrorIs(t, err, errHTTPStatus)
 	assert.EqualError(t, err, "HTTP 500")
 }
@@ -7,11 +7,13 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"math/rand/v2"
+	"net"
 	"net/http"
 	"net/url"
 	"os"
-	"path"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"

@@ -45,12 +47,33 @@ const (
 	bpsPerGbps = 1e9
 	bpsPerMbps = 1e6
 	bpsPerKbps = 1e3
+
+	// httpTimeout is the default time limit for one HTTP request, from
+	// connecting to reading the last byte of the body. It also bounds how
+	// long one file may take to download; fetch's --timeout changes it.
+	httpTimeout = 10 * time.Minute
+
+	// fetchAttempts is how many times fetch tries a request before it
+	// gives up on a transient failure.
+	fetchAttempts = 5
+
+	// firstRetryDelay is the longest fetch waits before its first retry.
+	// The limit doubles for each retry after that; the wait itself is
+	// random up to the limit.
+	firstRetryDelay = time.Second
+
+	// maxRetryAfter is the longest wait a server's Retry-After header can
+	// ask for. A server asking for longer fails the request at once.
+	maxRetryAfter = time.Minute
 )

 var (
 	// errURLRequired indicates the fetch command was run without a URL
 	// argument.
 	errURLRequired = errors.New("URL argument required")
+	// errInvalidTimeout indicates a fetch --timeout of zero or less, which
+	// http.Client would take as no time limit at all.
+	errInvalidTimeout = errors.New("--timeout must be greater than zero")
 	// errEmptyPath indicates an empty file path in the manifest.
 	errEmptyPath = errors.New("empty path")
 	// errAbsolutePath indicates an absolute file path in the manifest.
@@ -78,24 +101,109 @@ type DownloadProgress struct {
 	ETA         time.Duration // Estimated time to completion
 }

-// httpGet issues a GET request for the given URL using the provided
-// context and returns the response. The caller must close the body.
+// retryingClient is the HTTP client fetch makes every request with. It
+// waits up to firstDelay, which must be positive, before its first retry
+// of a transient failure. Tests shorten both the client's timeout and
+// firstDelay.
+type retryingClient struct {
+	client     *http.Client
+	firstDelay time.Duration
+}
+
+// get issues a GET for rawURL and passes a 200 OK response to use.
 //
-// Errors are returned unwrapped: this helper replaced direct http.Get
-// calls, and each caller already supplies its own context string, so
-// adding one here would change user-visible messages.
-func httpGet(ctx context.Context, fileURL string) (*http.Response, error) {
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, fileURL, nil)
+// A connection error, a timeout, or a 5xx or 429 status is retried, up to
+// fetchAttempts tries in all. Before each retry it waits a random time up
+// to a limit that doubles each time, unless the server's Retry-After
+// header says how long to wait. Any other failure, an error from use
+// included, is returned at once and unwrapped; a non-OK status is
+// returned as errHTTPStatus. use must start over each time it is called,
+// since a retry calls it again with a new response.
+func (c retryingClient) get(
+	ctx context.Context, rawURL string, use func(*http.Response) error,
+) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
 	if err != nil {
-		return nil, err
+		return err
 	}

-	resp, err := http.DefaultClient.Do(req)
-	if err != nil {
-		return nil, err
+	delay := c.firstDelay
+
+	for attempt := 1; ; attempt++ {
+		// Wait a random time up to delay, so that clients that failed
+		// together do not all retry together.
+		wait := rand.N(delay) //nolint:gosec // G404: jitter, not a secret
+
+		var retry bool
+
+		resp, err := c.client.Do(req)
+
+		switch {
+		case err != nil:
+			retry = isConnectionError(err)
+		case resp.StatusCode == http.StatusOK:
+			err = use(resp)
+			retry = isConnectionError(err)
+
+			_ = resp.Body.Close()
+		default:
+			_ = resp.Body.Close()
+
+			err = fmt.Errorf("%w %d", errHTTPStatus, resp.StatusCode)
+			retry = resp.StatusCode >= http.StatusInternalServerError ||
+				resp.StatusCode == http.StatusTooManyRequests
+
+			after, ok := retryAfter(resp.Header.Get("Retry-After"))
+			if ok {
+				wait = after
+				retry = retry && after <= maxRetryAfter
+			}
+		}
+
+		if !retry || attempt == fetchAttempts || ctx.Err() != nil {
+			return err
+		}
+
+		log.Warnf("%s: %s, retrying in %s", rawURL, err, wait.Round(time.Millisecond))
+
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(wait):
+		}
+
+		delay *= 2
+	}
+}
+
+// isConnectionError reports whether err is a connection error or a
+// timeout: a connection that could not be made, was reset, or closed
+// early, or a request that ran out of time.
+func isConnectionError(err error) bool {
+	var (
+		opErr  *net.OpError
+		netErr net.Error
+	)
+
+	return errors.As(err, &opErr) ||
+		(errors.As(err, &netErr) && netErr.Timeout()) ||
+		errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF)
+}
+
+// retryAfter returns the wait a Retry-After header value asks for, given
+// either in seconds or as an HTTP date. ok is false if there is none.
+func retryAfter(value string) (time.Duration, bool) {
+	seconds, err := strconv.Atoi(value)
+	if err == nil {
+		return time.Duration(seconds) * time.Second, true
 	}

-	return resp, nil
+	when, err := http.ParseTime(value)
+	if err == nil {
+		return time.Until(when), true
+	}
+
+	return 0, false
 }

 // reportDownloadProgress renders download progress until the channel
@@ -119,25 +227,23 @@ func reportDownloadProgress(progress <-chan DownloadProgress, done chan<- struct
 }

 // manifestBaseURL returns the URL of the directory containing the
-// manifest, with a trailing slash.
+// manifest.
 func manifestBaseURL(manifestURL string) (*url.URL, error) {
-	baseURL, err := url.Parse(manifestURL)
+	parsed, err := url.Parse(manifestURL)
 	if err != nil {
 		return nil, fmt.Errorf("fetch: invalid manifest URL: %w", err)
 	}

-	baseURL.Path = path.Dir(baseURL.Path)
-	if !strings.HasSuffix(baseURL.Path, "/") {
-		baseURL.Path += "/"
-	}
-
-	return baseURL, nil
+	// JoinPath cleans the path it builds, so ".." drops the manifest's
+	// file name.
+	return parsed.JoinPath(".."), nil
 }

 // downloadManifestFiles downloads every file in the manifest, reporting
 // progress on the progress channel.
 func downloadManifestFiles(
 	ctx context.Context,
+	client retryingClient,
 	baseURL *url.URL,
 	files []*mfer.MFFilePath,
 	progress chan<- DownloadProgress,
@@ -149,10 +255,12 @@ func downloadManifestFiles(
 			return fmt.Errorf("invalid path in manifest: %w", err)
 		}

-		fileURL := baseURL.String() + encodeFilePath(f.GetPath())
+		// JoinPath takes escaped path text, so a name such as "100%.txt"
+		// must be escaped first.
+		fileURL := baseURL.JoinPath(encodeFilePath(f.GetPath())).String()
 		log.Infof("fetching %s", f.GetPath())

-		err = downloadFile(ctx, fileURL, localPath, f, progress)
+		err = downloadFile(ctx, client, fileURL, localPath, f, progress)
 		if err != nil {
 			return fmt.Errorf("failed to download %s: %w", f.GetPath(), err)
 		}
@@ -168,30 +276,41 @@ func (mfa *CLIApp) fetchManifestOperation(ctx *cli.Context) error {
 		return errURLRequired
 	}

-	inputURL := ctx.Args().Get(0)
+	timeout := ctx.Duration(flagTimeout)
+	if timeout <= 0 {
+		return errInvalidTimeout
+	}

-	manifestURL, err := resolveManifestURL(inputURL)
+	manifestURL, err := resolveManifestURL(ctx.Args().Get(0))
 	if err != nil {
 		return fmt.Errorf("invalid URL: %w", err)
 	}

+	client := retryingClient{
+		client:     &http.Client{Timeout: timeout},
+		firstDelay: firstRetryDelay,
+	}
+
 	log.Infof("fetching manifest from %s", manifestURL)

-	// Fetch manifest
-	resp, err := httpGet(ctx.Context, manifestURL)
+	// Read the whole manifest before parsing it, so that a connection
+	// lost partway through is retried rather than reported as a bad
+	// manifest.
+	var manifestData []byte
+
+	err = client.get(ctx.Context, manifestURL, func(resp *http.Response) error {
+		var readErr error
+
+		manifestData, readErr = io.ReadAll(resp.Body)
+
+		return readErr
+	})
 	if err != nil {
 		return fmt.Errorf("failed to fetch manifest: %w", err)
 	}

-	defer func() { _ = resp.Body.Close() }()
-
-	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("failed to fetch manifest: %w %d",
-			errHTTPStatus, resp.StatusCode)
-	}
-
 	// Parse manifest
-	manifest, err := mfer.NewManifestFromReader(resp.Body)
+	manifest, err := mfer.NewManifestFromReader(bytes.NewReader(manifestData))
 	if err != nil {
 		return fmt.Errorf("failed to parse manifest: %w", err)
 	}
@@ -221,7 +340,7 @@ func (mfa *CLIApp) fetchManifestOperation(ctx *cli.Context) error {
 	startTime := time.Now()

 	// Download each file
-	dlErr := downloadManifestFiles(ctx.Context, baseURL, files, progress)
+	dlErr := downloadManifestFiles(ctx.Context, client, baseURL, files, progress)

 	close(progress)
 	<-done
@@ -313,7 +432,7 @@ func checkNoSymlinks(p string) error {

 // resolveManifestURL takes a URL and returns the manifest URL.
 // If the URL already ends with .mf, it's returned as-is.
-// Otherwise, index.mf is appended.
+// Otherwise, the default manifest name is appended.
 func resolveManifestURL(inputURL string) (string, error) {
 	parsed, err := url.Parse(inputURL)
 	if err != nil {
@@ -325,15 +444,7 @@ func resolveManifestURL(inputURL string) (string, error) {
 		return inputURL, nil
 	}

-	// Ensure path ends with /
-	if !strings.HasSuffix(parsed.Path, "/") {
-		parsed.Path += "/"
-	}
-
-	// Append index.mf
-	parsed.Path += "index.mf"
-
-	return parsed.String(), nil
+	return parsed.JoinPath(defaultManifestName).String(), nil
 }

 // progressWriter wraps an io.Writer and reports progress to a channel.
@@ -442,6 +553,7 @@ func verifyDownloadedHash(digest []byte, entry *mfer.MFFilePath) error {
 // Progress is reported via the progress channel.
 func downloadFile(
 	ctx context.Context,
+	client retryingClient,
 	fileURL, localPath string,
 	entry *mfer.MFFilePath,
 	progress chan<- DownloadProgress,
@@ -469,18 +581,21 @@ func downloadFile(

 	tmpPath := tempPathFor(localPath)

-	// Fetch file
-	resp, err := httpGet(ctx, fileURL)
-	if err != nil {
-		return fmt.Errorf("HTTP request failed: %w", err)
-	}
-
-	defer func() { _ = resp.Body.Close() }()
-
-	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("%w %d", errHTTPStatus, resp.StatusCode)
-	}
+	return client.get(ctx, fileURL, func(resp *http.Response) error {
+		return saveResponse(resp, tmpPath, localPath, entry, progress)
+	})
+}

+// saveResponse writes resp's body to tmpPath, verifies it against entry,
+// and renames it to localPath. It starts a new temp file each time and
+// removes it on failure, so a retry after a failed try never appends to
+// or keeps a partial file.
+func saveResponse(
+	resp *http.Response,
+	tmpPath, localPath string,
+	entry *mfer.MFFilePath,
+	progress chan<- DownloadProgress,
+) error {
 	// Determine expected size
 	expectedSize := entry.GetSize()

@@ -489,7 +604,7 @@ func downloadFile(
 		totalBytes = expectedSize
 	}

-	err = checkNoSymlinks(tmpPath)
+	err := checkNoSymlinks(tmpPath)
 	if err != nil {
 		return err
 	}
@@ -4,16 +4,24 @@ package cli
 import (
 	"bytes"
 	"context"
+	"flag"
+	"fmt"
 	"io"
+	"net"
 	"net/http"
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"strconv"
+	"sync"
+	"sync/atomic"
 	"testing"
+	"time"

 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	urfcli "github.com/urfave/cli/v2"
 	"sneak.berlin/go/mfer/mfer"
 )

@@ -214,6 +222,41 @@ func fetchTestHandler(
 	}
 }

+// manifestOf scans a tree holding files and returns its manifest bytes.
+func manifestOf(t *testing.T, files map[string][]byte) []byte {
+	t.Helper()
+
+	sourceFs := afero.NewMemMapFs()
+	for p, content := range files {
+		require.NoError(t, sourceFs.MkdirAll(filepath.Dir("/"+p), 0o755))
+		require.NoError(t, afero.WriteFile(sourceFs, "/"+p, content, 0o644))
+	}
+
+	return scanToManifest(t, sourceFs)
+}
+
+// testClient returns the client tests download with. Its retries wait
+// milliseconds rather than seconds.
+func testClient() retryingClient {
+	return retryingClient{
+		client:     &http.Client{Timeout: 10 * time.Second},
+		firstDelay: time.Millisecond,
+	}
+}
+
+// getNothing calls client.get for rawURL with a use that reads nothing,
+// under a context that expires after timeout. It holds runMu, since get
+// logs each retry to the process-global logger, and starts the timeout
+// only once it has the lock.
+func getNothing(client retryingClient, rawURL string, timeout time.Duration) error {
+	return runLocked(func() error {
+		ctx, cancel := context.WithTimeout(context.Background(), timeout)
+		defer cancel()
+
+		return client.get(ctx, rawURL, func(*http.Response) error { return nil })
+	})
+}
+
 //nolint:paralleltest // changes the process-global working directory
 func TestFetchFromHTTP(t *testing.T) {
 	// Create source filesystem with test files
@@ -266,7 +309,8 @@ func TestFetchFromHTTP(t *testing.T) {
 		require.NoError(t, err)

 		fileURL := baseURL + f.GetPath()
-		err = downloadFile(context.Background(), fileURL, localPath, f, progress)
+		err = downloadFile(context.Background(), testClient(),
+			fileURL, localPath, f, progress)
 		require.NoError(t, err, "failed to download %s", f.GetPath())
 	}

@@ -313,7 +357,7 @@ func TestFetchHashMismatch(t *testing.T) {
 	chdirTemp(t)

 	// Try to download - should fail with hash mismatch
-	err = downloadFile(context.Background(),
+	err = downloadFile(context.Background(), testClient(),
 		server.URL+"/file.txt", testFileTxt, files[0], nil)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "mismatch")
@@ -359,7 +403,7 @@ func TestFetchSizeMismatch(t *testing.T) {
 	chdirTemp(t)

 	// Try to download - should fail with size mismatch
-	err = downloadFile(context.Background(),
+	err = downloadFile(context.Background(), testClient(),
 		server.URL+"/file.txt", testFileTxt, files[0], nil)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "size mismatch")
@@ -417,7 +461,7 @@ func TestFetchProgress(t *testing.T) {
 	}()

 	// Download
-	err = downloadFile(context.Background(),
+	err = downloadFile(context.Background(), testClient(),
 		server.URL+"/large.txt", "large.txt", files[0], progress)
 	close(progress)
 	<-done
@@ -523,3 +567,343 @@ func TestFetchReplacesHardLinkAtTempName(t *testing.T) {
 	require.NoError(t, err)
 	assert.Equal(t, "outside", string(outside), "fetch wrote outside the destination")
 }
+
+// TestGetRetriesTransientStatusesOnly answers every request with one
+// status and counts the requests: a 5xx or 429 is retried until
+// fetchAttempts runs out, and any other status fails at once.
+func TestGetRetriesTransientStatusesOnly(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		status   int
+		requests int32
+	}{
+		{http.StatusNotFound, 1},
+		{http.StatusForbidden, 1},
+		{http.StatusInternalServerError, fetchAttempts},
+		{http.StatusServiceUnavailable, fetchAttempts},
+		{http.StatusTooManyRequests, fetchAttempts},
+	}
+
+	for _, tt := range tests {
+		t.Run(http.StatusText(tt.status), func(t *testing.T) {
+			t.Parallel()
+
+			var requests atomic.Int32
+
+			server := httptest.NewServer(
+				http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+					requests.Add(1)
+					w.WriteHeader(tt.status)
+				}))
+			defer server.Close()
+
+			err := getNothing(testClient(), server.URL, 10*time.Second)
+			require.ErrorIs(t, err, errHTTPStatus)
+			require.EqualError(t, err, fmt.Sprintf("HTTP %d", tt.status))
+			assert.Equal(t, tt.requests, requests.Load())
+		})
+	}
+}
+
+// TestGetTimesOutOnStalledServer points get at a server that takes a
+// request and never answers it. The try must give up at the client's
+// timeout and be retried; when every try stalls, get must return a
+// timeout error rather than hang.
+func TestGetTimesOutOnStalledServer(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name       string
+		stallEvery bool
+	}{
+		{"first request stalls", false},
+		{"every request stalls", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var requests atomic.Int32
+
+			stop := make(chan struct{})
+			server := httptest.NewServer(
+				http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+					if requests.Add(1) == 1 || tt.stallEvery {
+						select {
+						case <-r.Context().Done():
+						case <-stop:
+						}
+					}
+				}))
+
+			defer server.Close()
+			defer close(stop)
+
+			client := testClient()
+			client.client.Timeout = 50 * time.Millisecond
+
+			err := getNothing(client, server.URL, 10*time.Second)
+			if !tt.stallEvery {
+				require.NoError(t, err)
+
+				return
+			}
+
+			var netErr net.Error
+			require.ErrorAs(t, err, &netErr)
+			assert.True(t, netErr.Timeout(), "want a timeout, got %v", err)
+		})
+	}
+}
+
+// TestGetHonorsRetryAfter answers the first request with a 503 and a
+// Retry-After header, and any later one with 200 OK. The client's own
+// wait before a retry is an hour, so get finishes in time only if it
+// waits as long as Retry-After says instead. A Retry-After longer than
+// maxRetryAfter must fail at once.
+func TestGetHonorsRetryAfter(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		value    string
+		requests int32
+		wantErr  bool
+	}{
+		{"seconds", "0", 2, false},
+		{"HTTP date", time.Now().Add(-time.Minute).UTC().Format(http.TimeFormat), 2, false},
+		{"too long", strconv.Itoa(int((maxRetryAfter + time.Second).Seconds())), 1, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var requests atomic.Int32
+
+			server := httptest.NewServer(
+				http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+					if requests.Add(1) == 1 {
+						w.Header().Set("Retry-After", tt.value)
+						w.WriteHeader(http.StatusServiceUnavailable)
+					}
+				}))
+			defer server.Close()
+
+			client := testClient()
+			client.firstDelay = time.Hour
+
+			err := getNothing(client, server.URL, 10*time.Second)
+			if tt.wantErr {
+				require.ErrorIs(t, err, errHTTPStatus)
+			} else {
+				require.NoError(t, err)
+			}
+
+			assert.Equal(t, tt.requests, requests.Load())
+		})
+	}
+}
+
+// TestGetStopsWaitingWhenCanceled gives get a server that always answers
+// 503 and an hour's wait before each retry, then lets the context expire
+// during that wait. get returning at all shows it stopped waiting.
+func TestGetStopsWaitingWhenCanceled(t *testing.T) {
+	t.Parallel()
+
+	server := httptest.NewServer(
+		http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusServiceUnavailable)
+		}))
+	defer server.Close()
+
+	client := testClient()
+	client.firstDelay = time.Hour
+
+	err := getNothing(client, server.URL, 50*time.Millisecond)
+	require.ErrorIs(t, err, context.DeadlineExceeded)
+}
+
+// TestDownloadFileRetriesToSuccess serves a file that fails twice before
+// it succeeds: first with a 503, then with a body cut off halfway. The
+// download must end with the whole, verified file and no temp file.
+//
+//nolint:paralleltest // changes the process-global working directory
+func TestDownloadFileRetriesToSuccess(t *testing.T) {
+	content := []byte("the whole file, every byte of it")
+
+	manifest, err := mfer.NewManifestFromReader(bytes.NewReader(
+		manifestOf(t, map[string][]byte{testFileTxt: content})))
+	require.NoError(t, err)
+
+	var requests atomic.Int32
+
+	server := httptest.NewServer(
+		http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			switch requests.Add(1) {
+			case 1:
+				w.WriteHeader(http.StatusServiceUnavailable)
+			case 2:
+				// Promise the whole file but send half of it; the server
+				// then closes the connection.
+				w.Header().Set("Content-Length", strconv.Itoa(len(content)))
+				_, _ = w.Write(content[:len(content)/2])
+			default:
+				_, _ = w.Write(content)
+			}
+		}))
+	defer server.Close()
+
+	chdirTemp(t)
+
+	err = downloadFile(context.Background(), testClient(),
+		server.URL+"/"+testFileTxt, testFileTxt, manifest.Files()[0], nil)
+	require.NoError(t, err)
+	assert.Equal(t, int32(3), requests.Load())
+
+	fetched, err := os.ReadFile(testFileTxt)
+	require.NoError(t, err)
+	assert.Equal(t, content, fetched)
+
+	_, err = os.Stat(".file.txt.tmp")
+	assert.True(t, os.IsNotExist(err), "temp file left behind")
+}
+
+// TestFetchBaseURLForms fetches one tree by its directory URL with and
+// without a trailing slash, with a query string, and by its manifest URL.
+// Each must request the same manifest and file paths.
+//
+//nolint:paralleltest // changes the process-global working directory
+func TestFetchBaseURLForms(t *testing.T) {
+	files := map[string][]byte{"one.txt": []byte("1"), "sub/two.txt": []byte("2")}
+	tree := http.StripPrefix("/tree", fetchTestHandler(manifestOf(t, files), files))
+
+	var (
+		mu        sync.Mutex
+		requested []string
+	)
+
+	server := httptest.NewServer(
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			mu.Lock()
+
+			requested = append(requested, r.URL.Path)
+
+			mu.Unlock()
+
+			tree.ServeHTTP(w, r)
+		}))
+	defer server.Close()
+
+	inputs := []string{"/tree", "/tree/", "/tree?key=value", "/tree/index.mf"}
+	for _, input := range inputs {
+		t.Run(input, func(t *testing.T) {
+			mu.Lock()
+			requested = nil
+			mu.Unlock()
+
+			chdirTemp(t)
+
+			opts := testOpts([]string{testApp, cmdFetch, "-q", server.URL + input},
+				afero.NewOsFs())
+			require.Equal(t, 0, runCLI(opts), testStderr(t, opts))
+
+			mu.Lock()
+			defer mu.Unlock()
+
+			assert.ElementsMatch(t,
+				[]string{"/tree/index.mf", "/tree/one.txt", "/tree/sub/two.txt"}, requested)
+		})
+	}
+}
+
+// TestFetchEscapedPaths fetches files whose names need escaping in a URL,
+// one of them a name that is itself an escape sequence. Each must arrive
+// under its own name with its own content.
+//
+//nolint:paralleltest // changes the process-global working directory
+func TestFetchEscapedPaths(t *testing.T) {
+	files := map[string][]byte{
+		"a b.txt":                []byte("space"),
+		"a%20b.txt":              []byte("percent sign, two, zero"),
+		"100%.txt":               []byte("percent sign"),
+		"q?x=1#frag.txt":         []byte("question mark and hash"),
+		"dir with space/sub.txt": []byte("directory with a space"),
+	}
+
+	server := httptest.NewServer(fetchTestHandler(manifestOf(t, files), files))
+	defer server.Close()
+
+	chdirTemp(t)
+
+	opts := testOpts([]string{testApp, cmdFetch, "-q", server.URL}, afero.NewOsFs())
+	require.Equal(t, 0, runCLI(opts), testStderr(t, opts))
+
+	for name, content := range files {
+		fetched, err := os.ReadFile(name) //nolint:gosec // test-controlled path
+		require.NoError(t, err)
+		assert.Equal(t, content, fetched, name)
+	}
+}
+
+// TestFetchTimeoutFlag runs fetch with --timeout against a server that
+// never answers. Without the flag's limit the request would wait forever;
+// once fetch gives up on it, the server cancels fetch's context so that
+// fetch returns instead of retrying.
+func TestFetchTimeoutFlag(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	server := httptest.NewServer(
+		http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+			<-r.Context().Done() // fetch gave up on this request
+			cancel()
+		}))
+	defer server.Close()
+
+	mfa := &CLIApp{Fs: afero.NewMemMapFs()}
+
+	set := flag.NewFlagSet(cmdFetch, flag.ContinueOnError)
+	for _, f := range mfa.fetchCommand().Flags {
+		require.NoError(t, f.Apply(set))
+	}
+
+	require.NoError(t, set.Parse([]string{"--" + flagTimeout, "100ms", server.URL}))
+
+	cliCtx := urfcli.NewContext(nil, set, nil)
+	cliCtx.Context = ctx
+
+	// fetchManifestOperation logs to the process-global logger.
+	err := runLocked(func() error { return mfa.fetchManifestOperation(cliCtx) })
+	require.Error(t, err)
+}
+
+// TestFetchRejectsTimeoutOfZeroOrLess runs fetch with a --timeout of zero
+// and of less than zero. http.Client takes either as no time limit at all,
+// so fetch must refuse it before making any request.
+func TestFetchRejectsTimeoutOfZeroOrLess(t *testing.T) {
+	t.Parallel()
+
+	var requests atomic.Int32
+
+	server := httptest.NewServer(
+		http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
+			requests.Add(1)
+		}))
+	defer server.Close()
+
+	for _, timeout := range []string{"0", "-1s"} {
+		opts := testOpts(
+			[]string{testApp, cmdFetch, "--" + flagTimeout + "=" + timeout, server.URL},
+			afero.NewMemMapFs())
+
+		assert.Equal(t, 1, runCLI(opts), timeout)
+		assert.Contains(t, testStderr(t, opts), errInvalidTimeout.Error(), timeout)
+	}
+
+	assert.Zero(t, requests.Load(), "fetch made a request")
+}
@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
+	"os"
 	"path/filepath"
 	"time"

@@ -56,7 +57,7 @@ type freshenEntry struct {
 type freshenScanner struct {
 	fs              afero.Fs
 	absBase         string
-	manifestBase    string
+	excluded        []fs.FileInfo // files left out of the listing
 	includeDotfiles bool
 	followSymlinks  bool
 	showProgress    bool
@@ -156,11 +157,6 @@ func (s *freshenScanner) walk(path string, info fs.FileInfo, walkErr error) erro
 			"freshen: failed to compute relative path for %s: %w", path, err)
 	}

-	// Skip the manifest file itself
-	if relPath == s.manifestBase || relPath == "."+s.manifestBase {
-		return nil
-	}
-
 	// Handle dotfiles
 	if !s.includeDotfiles && mfer.IsHiddenPath(filepath.ToSlash(relPath)) {
 		if info.IsDir() {
@@ -185,6 +181,12 @@ func (s *freshenScanner) walk(path string, info fs.FileInfo, walkErr error) erro
 		info = realInfo
 	}

+	for _, excluded := range s.excluded {
+		if os.SameFile(info, excluded) {
+			return nil
+		}
+	}
+
 	s.scanCount++

 	// Check against existing manifest
@@ -307,7 +309,7 @@ func (h *freshenHasher) processEntry(e *freshenEntry) error {
 func writeFreshenedManifest(
 	ctx context.Context, afs afero.Fs, builder *mfer.Builder, manifestPath string,
 ) error {
-	tmpPath := manifestPath + ".tmp"
+	tmpPath := manifestTempPath(manifestPath)

 	outFile, err := afs.Create(tmpPath)
 	if err != nil {
@@ -364,10 +366,22 @@ func (mfa *CLIApp) freshenScan(
 	startScan := time.Now()
 	showProgress := ctx.Bool("progress")

+	// Leave out the manifest and a temp file left by an interrupted run,
+	// as gen does. A path that cannot be stat'd, normally because no file
+	// is there, needs no leaving out.
+	var excluded []fs.FileInfo
+
+	for _, p := range []string{manifestPath, manifestTempPath(manifestPath)} {
+		info, err := mfa.Fs.Stat(p)
+		if err == nil {
+			excluded = append(excluded, info)
+		}
+	}
+
 	scanner := &freshenScanner{
 		fs:              mfa.Fs,
 		absBase:         absBase,
-		manifestBase:    filepath.Base(manifestPath),
+		excluded:        excluded,
 		includeDotfiles: ctx.Bool("include-dotfiles"),
 		followSymlinks:  ctx.Bool("follow-symlinks"),
 		showProgress:    showProgress,
@@ -445,7 +459,10 @@ func (mfa *CLIApp) loadExistingEntries(
 	log.Infof("loading manifest from %s", manifestPath)

 	// Load existing manifest
-	manifest, err := mfer.NewManifestFromFile(mfa.Fs, manifestPath)
+	manifest, err := mfer.NewManifestFromFile(&mfer.ManifestFromFileOptions{
+		Path: manifestPath,
+		Fs:   mfa.Fs,
+	})
 	if err != nil {
 		return nil, fmt.Errorf("failed to load manifest: %w", err)
 	}
@@ -612,7 +629,15 @@ func addExistingToBuilder(b *mfer.Builder, entry *mfer.MFFilePath) error {
 		return nil
 	}

-	return b.AddFileWithHash(mfer.RelFilePath(entry.GetPath()),
+	err := b.AddFileWithHash(mfer.RelFilePath(entry.GetPath()),
 		mfer.FileSize(entry.GetSize()), mfer.ModTime(mtime),
 		entry.GetHashes()[0].GetMultiHash())
+	if err != nil {
+		return fmt.Errorf(
+			"manifest entry %s: %w (regenerate the manifest with mfer generate)",
+			entry.GetPath(), err,
+		)
+	}
+
+	return nil
 }
@@ -4,10 +4,13 @@ package cli
 import (
 	"bytes"
 	"context"
+	"crypto/sha256"
 	"os"
+	"path/filepath"
 	"testing"
 	"time"

+	"github.com/multiformats/go-multihash"
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -29,7 +32,7 @@ func (s stubFileInfo) IsDir() bool        { return false }
 func (s stubFileInfo) Sys() any           { return nil }

 // setupFreshenDir populates /testdir with two files, scans it, and
-// writes the resulting manifest to /testdir/.index.mf.
+// writes the resulting manifest to /testdir/index.mf.
 func setupFreshenDir(t *testing.T, fs afero.Fs) {
 	t.Helper()

@@ -48,7 +51,7 @@ func setupFreshenDir(t *testing.T, fs afero.Fs) {

 	// Write manifest to filesystem
 	require.NoError(t,
-		afero.WriteFile(fs, "/testdir/.index.mf", manifestBuf.Bytes(), 0o644))
+		afero.WriteFile(fs, "/testdir/index.mf", manifestBuf.Bytes(), 0o644))
 }

 func TestFreshenUnchanged(t *testing.T) {
@@ -58,7 +61,10 @@ func TestFreshenUnchanged(t *testing.T) {
 	setupFreshenDir(t, fs)

 	// Parse manifest to verify
-	manifest, err := mfer.NewManifestFromFile(fs, "/testdir/.index.mf")
+	manifest, err := mfer.NewManifestFromFile(&mfer.ManifestFromFileOptions{
+		Path: "/testdir/index.mf",
+		Fs:   fs,
+	})
 	require.NoError(t, err)
 	assert.Len(t, manifest.Files(), 2)
 }
@@ -70,7 +76,10 @@ func TestFreshenWithChanges(t *testing.T) {
 	setupFreshenDir(t, fs)

 	// Verify initial manifest has 2 files
-	manifest, err := mfer.NewManifestFromFile(fs, "/testdir/.index.mf")
+	manifest, err := mfer.NewManifestFromFile(&mfer.ManifestFromFileOptions{
+		Path: "/testdir/index.mf",
+		Fs:   fs,
+	})
 	require.NoError(t, err)
 	assert.Len(t, manifest.Files(), 2)

@@ -95,6 +104,64 @@ func TestFreshenWithChanges(t *testing.T) {
 	assert.Equal(t, "modified content2", string(content))
 }

+// TestFreshenLeavesManifestOutOfListing freshens a manifest kept in a
+// subdirectory of the tree it lists: the manifest is not listed, while an
+// ordinary file of the same name at the top of the tree is. The manifest
+// is recognized by file identity, which needs the real filesystem.
+func TestFreshenLeavesManifestOutOfListing(t *testing.T) {
+	t.Parallel()
+
+	root := t.TempDir()
+	manifestPath := filepath.Join(root, "sub", "listing.mf")
+
+	fs := afero.NewOsFs()
+	require.NoError(t, fs.MkdirAll(filepath.Join(root, "sub"), 0o750))
+	writeTestFile(t, fs, filepath.Join(root, testFileTxt), "hello")
+	writeTestFile(t, fs, filepath.Join(root, "listing.mf"), "an ordinary file")
+
+	opts := testOpts([]string{testApp, cmdGenerate, "-q", "-o", manifestPath, root}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	// A new file gives freshen something to write.
+	writeTestFile(t, fs, filepath.Join(root, "added.txt"), "added")
+
+	opts = testOpts([]string{
+		testApp, "freshen", "-q", testFlagBase, root, manifestPath,
+	}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	assert.ElementsMatch(t, []string{testFileTxt, "listing.mf", "added.txt"},
+		manifestPaths(t, fs, manifestPath))
+}
+
+// TestFreshenLeavesLeftoverTempFileOutOfListing freshens a manifest where
+// an interrupted run left its temp file beside it: the leftover is not
+// listed.
+func TestFreshenLeavesLeftoverTempFileOutOfListing(t *testing.T) {
+	t.Parallel()
+
+	root := t.TempDir()
+	manifestPath := filepath.Join(root, "index.mf")
+
+	fs := afero.NewOsFs()
+	writeTestFile(t, fs, filepath.Join(root, testFileTxt), "hello")
+
+	opts := testOpts([]string{testApp, cmdGenerate, "-q", "-o", manifestPath, root}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	writeTestFile(t, fs, manifestTempPath(manifestPath), "part of a manifest")
+	// A new file gives freshen something to write.
+	writeTestFile(t, fs, filepath.Join(root, "added.txt"), "added")
+
+	opts = testOpts([]string{
+		testApp, "freshen", "-q", testFlagBase, root, manifestPath,
+	}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	assert.ElementsMatch(t, []string{testFileTxt, "added.txt"},
+		manifestPaths(t, fs, manifestPath))
+}
+
 // TestFreshenRecordEntryMtimePresence pins the behavior of recordEntry
 // with respect to MFFilePath.Mtime, which is a message pointer with
 // proto3 field presence and may legitimately be absent.
@@ -169,21 +236,50 @@ func TestFreshenRecordEntryMtimePresence(t *testing.T) {
 func TestFreshenAddExistingRejectsMissingMtime(t *testing.T) {
 	t.Parallel()

+	hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)
+
 	b := mfer.NewBuilder()
 	entry := &mfer.MFFilePath{
 		Path:  "file1.txt",
 		Size:  8,
 		Mtime: nil,
 		Hashes: []*mfer.MFFileChecksum{
-			{MultiHash: []byte{0x12, 0x20}},
+			{MultiHash: hash},
 		},
 	}

-	err := addExistingToBuilder(b, entry)
+	err = addExistingToBuilder(b, entry)
 	require.ErrorIs(t, err, errEntryMissingMtime)
 	assert.Contains(t, err.Error(), "file1.txt")
 }

+// TestFreshenAddExistingRejectsShortHash pins that an existing manifest
+// entry whose hash the builder refuses is reported as a problem with the
+// manifest, with the command that fixes it.
+func TestFreshenAddExistingRejectsShortHash(t *testing.T) {
+	t.Parallel()
+
+	sha1Hash, err := multihash.Encode(make([]byte, 20), multihash.SHA1)
+	require.NoError(t, err)
+
+	b := mfer.NewBuilder()
+	entry := &mfer.MFFilePath{
+		Path:  "old.txt",
+		Size:  8,
+		Mtime: &mfer.Timestamp{Seconds: 1_700_000_000},
+		Hashes: []*mfer.MFFileChecksum{
+			{MultiHash: sha1Hash},
+		},
+	}
+
+	err = addExistingToBuilder(b, entry)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "manifest entry old.txt")
+	assert.Contains(t, err.Error(), "mfer generate")
+	assert.Zero(t, b.FileCount())
+}
+
 // TestEntryMtime pins the presence semantics the callers depend on.
 func TestEntryMtime(t *testing.T) {
 	t.Parallel()
@@ -89,11 +89,15 @@ func (mfa *CLIApp) collectInputPaths(args cli.Args) ([]string, error) {

 // buildScannerOptions constructs scanner options from the CLI flags.
 func (mfa *CLIApp) buildScannerOptions(ctx *cli.Context) *mfer.ScannerOptions {
+	output := ctx.String("output")
 	opts := &mfer.ScannerOptions{
 		IncludeDotfiles:   ctx.Bool("include-dotfiles"),
 		FollowSymLinks:    ctx.Bool("follow-symlinks"),
 		IncludeTimestamps: ctx.Bool("include-timestamps"),
 		Fs:                mfa.Fs,
+		// Neither a manifest being replaced nor a temp file left by an
+		// interrupted run belongs in the new manifest.
+		ExcludePaths: []string{output, manifestTempPath(output)},
 	}

 	// Set seed for deterministic UUID if provided
@@ -217,7 +221,7 @@ func (mfa *CLIApp) generateManifestOperation(ctx *cli.Context) error {
 	}

 	// Create temp file for atomic write
-	tmpPath := outputPath + ".tmp"
+	tmpPath := manifestTempPath(outputPath)

 	outFile, err := mfa.Fs.Create(tmpPath)
 	if err != nil {
@@ -65,7 +65,7 @@ func (mfa *CLIApp) openManifestReader(pathOrURL string) (io.ReadCloser, error) {
 }

 // resolveManifestArg resolves the manifest path from CLI arguments.
-// HTTP(S) URLs are returned as-is. Directories are searched for index.mf/.index.mf.
+// HTTP(S) URLs are returned as-is. Directories are searched for index.mf.
 // If no argument is given, the current directory is searched.
 func (mfa *CLIApp) resolveManifestArg(ctx *cli.Context) (string, error) {
 	if ctx.Args().Len() > 0 {
@@ -17,15 +17,28 @@ import (
 const (
 	cmdGenerate = "generate"
 	cmdCheck    = "check"
+	cmdFreshen  = "freshen"
 	cmdExport   = "export"
 	cmdFetch    = "fetch"
 	cmdVersion  = "version"

 	flagProgress = "progress"
+	flagTimeout  = "timeout"

 	manifestArgsUsage = "[manifest file]"
+
+	// defaultManifestName is the filename gen writes by default, the one
+	// looked for when a command is given a directory, and the one fetch
+	// appends to a directory URL.
+	defaultManifestName = "index.mf"
 )

+// manifestTempPath returns the temp file gen and freshen write a manifest
+// to before renaming it to out.
+func manifestTempPath(out string) string {
+	return out + ".tmp"
+}
+
 // errUnknownCommand indicates an unrecognized command argument.
 var errUnknownCommand = errors.New("unknown command")

@@ -118,7 +131,7 @@ func commonFlags() []cli.Flag {
 		&cli.BoolFlag{
 			Name:    "verbose",
 			Aliases: []string{"v"},
-			Usage:   "Increase verbosity (-v for verbose, -vv for debug)",
+			Usage:   "Increase verbosity (-v for verbose, -v -v for debug)",
 			Count:   new(int),
 		},
 		&cli.BoolFlag{
@@ -131,9 +144,10 @@ func commonFlags() []cli.Flag {

 func (mfa *CLIApp) generateCommand() *cli.Command {
 	return &cli.Command{
-		Name:    cmdGenerate,
-		Aliases: []string{"gen"},
-		Usage:   "Generate manifest file",
+		Name:      cmdGenerate,
+		Aliases:   []string{"gen"},
+		Usage:     "Generate manifest file",
+		ArgsUsage: "[path ...]",
 		Action: func(c *cli.Context) error {
 			mfa.setVerbosity(c)
 			mfa.printBanner()
@@ -154,7 +168,7 @@ func (mfa *CLIApp) generateCommand() *cli.Command {
 			},
 			&cli.StringFlag{
 				Name:    "output",
-				Value:   "./.index.mf",
+				Value:   defaultManifestName,
 				Aliases: []string{"o"},
 				Usage:   "Specify output filename",
 			},
@@ -227,7 +241,7 @@ func (mfa *CLIApp) checkCommand() *cli.Command {

 func (mfa *CLIApp) freshenCommand() *cli.Command {
 	return &cli.Command{
-		Name:      "freshen",
+		Name:      cmdFreshen,
 		Usage:     "Update manifest with changed, new, and removed files",
 		ArgsUsage: manifestArgsUsage,
 		Action: func(c *cli.Context) error {
@@ -324,15 +338,23 @@ func (mfa *CLIApp) listCommand() *cli.Command {

 func (mfa *CLIApp) fetchCommand() *cli.Command {
 	return &cli.Command{
-		Name:  cmdFetch,
-		Usage: "fetch manifest and referenced files",
+		Name:      cmdFetch,
+		Usage:     "fetch manifest and referenced files",
+		ArgsUsage: "URL",
 		Action: func(c *cli.Context) error {
 			mfa.setVerbosity(c)
 			mfa.printBanner()

 			return mfa.fetchManifestOperation(c)
 		},
-		Flags: commonFlags(),
+		Flags: append(commonFlags(),
+			&cli.DurationFlag{
+				Name:  flagTimeout,
+				Value: httpTimeout,
+				Usage: "Time limit for each HTTP request, including the download " +
+					"of its body",
+			},
+		),
 	}
 }

@@ -35,7 +35,8 @@ var (
 	errPathDotDot       = errors.New("contains '..' segment")
 	errSizeMismatch     = errors.New("size mismatch")
 	errNegativeSize     = errors.New("size cannot be negative")
-	errEmptyHash        = errors.New("hash cannot be nil or empty")
+	errHashNotMultihash = errors.New("hash is not a valid multihash")
+	errHashTooShort     = errors.New("hash digest is too short")
 )

 // ValidatePath checks that a file path conforms to manifest path invariants:
@@ -228,7 +229,8 @@ func (b *Builder) FileCount() int {

 // AddFileWithHash adds a file entry with a pre-computed hash.
 // This is useful when the hash is already known (e.g., from an existing manifest).
-// Returns an error if path is empty, size is negative, or hash is nil/empty.
+// Returns an error if path is invalid, size is negative, or hash is not a
+// multihash with a digest of at least 32 bytes, as long as SHA-256's.
 func (b *Builder) AddFileWithHash(
 	path RelFilePath,
 	size FileSize,
@@ -244,8 +246,19 @@ func (b *Builder) AddFileWithHash(
 		return errNegativeSize
 	}

-	if len(hash) == 0 {
-		return errEmptyHash
+	decoded, err := multihash.Decode(hash)
+	if err != nil {
+		return fmt.Errorf("%w: %w", errHashNotMultihash, err)
+	}
+
+	// The reader's limit on decoding cost (maxDecodedGrowth) assumes every
+	// hash is at least as long as a SHA-256 multihash, so a manifest of
+	// shorter ones could fail to load.
+	if len(decoded.Digest) < sha256.Size {
+		return fmt.Errorf(
+			"%w: %d bytes, at least %d needed",
+			errHashTooShort, len(decoded.Digest), sha256.Size,
+		)
 	}

 	entry := &MFFilePath{
@@ -4,11 +4,15 @@ package mfer
 import (
 	"bytes"
 	"context"
+	"crypto/sha256"
 	"fmt"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"

+	"github.com/multiformats/go-multihash"
+	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -42,9 +46,10 @@ func TestBuilderAddFileWithHash(t *testing.T) {
 	t.Parallel()

 	b := NewBuilder()
-	hash := make([]byte, 34) // SHA256 multihash is 34 bytes
+	hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)

-	err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), hash)
+	err = b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), hash)
 	require.NoError(t, err)
 	assert.Equal(t, 1, b.FileCount())
 }
@@ -52,12 +57,14 @@ func TestBuilderAddFileWithHash(t *testing.T) {
 func TestBuilderAddFileWithHashValidation(t *testing.T) {
 	t.Parallel()

+	sha256Hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)
+
 	t.Run("empty path", func(t *testing.T) {
 		t.Parallel()

 		b := NewBuilder()
-		hash := make([]byte, 34)
-		err := b.AddFileWithHash("", 100, ModTime(time.Now()), hash)
+		err := b.AddFileWithHash("", 100, ModTime(time.Now()), sha256Hash)
 		require.Error(t, err)
 		assert.Contains(t, err.Error(), "path")
 	})
@@ -66,41 +73,58 @@ func TestBuilderAddFileWithHashValidation(t *testing.T) {
 		t.Parallel()

 		b := NewBuilder()
-		hash := make([]byte, 34)
-		err := b.AddFileWithHash("test.txt", -1, ModTime(time.Now()), hash)
+		err := b.AddFileWithHash("test.txt", -1, ModTime(time.Now()), sha256Hash)
 		require.Error(t, err)
 		assert.Contains(t, err.Error(), "size")
 	})

-	t.Run("nil hash", func(t *testing.T) {
-		t.Parallel()
-
-		b := NewBuilder()
-		err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), nil)
-		require.Error(t, err)
-		assert.Contains(t, err.Error(), "hash")
-	})
-
-	t.Run("empty hash", func(t *testing.T) {
-		t.Parallel()
-
-		b := NewBuilder()
-		err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), []byte{})
-		require.Error(t, err)
-		assert.Contains(t, err.Error(), "hash")
-	})
-
 	t.Run("valid inputs", func(t *testing.T) {
 		t.Parallel()

 		b := NewBuilder()
-		hash := make([]byte, 34)
-		err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), hash)
+		err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), sha256Hash)
 		require.NoError(t, err)
 		assert.Equal(t, 1, b.FileCount())
 	})
 }

+func TestBuilderAddFileWithHashRejectsBadHashes(t *testing.T) {
+	t.Parallel()
+
+	sha1Hash, err := multihash.Encode(make([]byte, 20), multihash.SHA1)
+	require.NoError(t, err)
+
+	truncatedHash, err := multihash.Encode(make([]byte, sha256.Size-1), multihash.SHA2_256)
+	require.NoError(t, err)
+
+	tests := []struct {
+		name string
+		hash Multihash
+		want error
+	}{
+		{"nil hash", nil, errHashNotMultihash},
+		{"empty hash", []byte{}, errHashNotMultihash},
+		{"one-byte hash", []byte{0x12}, errHashNotMultihash},
+		// A SHA-256 code and 32-byte length, then only two bytes of digest.
+		{"malformed multihash", []byte{0x12, 0x20, 0x01, 0x02}, errHashNotMultihash},
+		// A valid multihash, but its 20-byte SHA-1 digest is too short.
+		{"SHA-1 multihash", sha1Hash, errHashTooShort},
+		// A valid multihash whose 31-byte digest is one byte short.
+		{"31-byte digest", truncatedHash, errHashTooShort},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			b := NewBuilder()
+			err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), tt.hash)
+			require.ErrorIs(t, err, tt.want)
+			assert.Equal(t, 0, b.FileCount())
+		})
+	}
+}
+
 func TestBuilderBuild(t *testing.T) {
 	t.Parallel()

@@ -356,7 +380,8 @@ func TestBuilderBuildRoundTrip(t *testing.T) {
 func TestBuilderBuildRoundTripLargeManifest(t *testing.T) {
 	t.Parallel()

-	hash := make([]byte, 34) // multihash: 2-byte prefix + 32-byte SHA-256
+	hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)

 	b := NewBuilder()

@@ -397,6 +422,29 @@ func TestNewManifestFromReaderTruncated(t *testing.T) {
 	assert.Error(t, err)
 }

+func TestNewManifestFromFileRequiresPath(t *testing.T) {
+	t.Parallel()
+
+	_, err := NewManifestFromFile(nil)
+	require.ErrorIs(t, err, errManifestPathEmpty)
+
+	_, err = NewManifestFromFile(&ManifestFromFileOptions{Fs: afero.NewMemMapFs()})
+	require.ErrorIs(t, err, errManifestPathEmpty)
+}
+
+func TestNewManifestFromFileNilFsUsesOsFs(t *testing.T) {
+	t.Parallel()
+
+	path := filepath.Join(t.TempDir(), "index.mf")
+	createTestManifest(t, afero.NewOsFs(), path, map[string][]byte{
+		testFileName: []byte("hello"),
+	})
+
+	m, err := NewManifestFromFile(&ManifestFromFileOptions{Path: path})
+	require.NoError(t, err)
+	assert.Len(t, m.Files(), 1)
+}
+
 func TestManifestString(t *testing.T) {
 	t.Parallel()

@@ -14,7 +14,11 @@ import (
 	"github.com/spf13/afero"
 )

-var errNoSigningPubKey = errors.New("manifest has no signing public key")
+var (
+	errNoSigningPubKey   = errors.New("manifest has no signing public key")
+	errManifestPathEmpty = errors.New("manifest path cannot be empty")
+	errBasePathEmpty     = errors.New("base path cannot be empty")
+)

 // Result represents the outcome of checking a single file.
 type Result struct {
@@ -82,20 +86,42 @@ type Checker struct {
 	signingPubKey []byte
 }

-// NewChecker creates a new Checker for the given manifest, base path, and filesystem.
-// The basePath is the directory relative to which manifest paths are resolved.
-// If fs is nil, the real filesystem (OsFs) is used.
-func NewChecker(manifestPath string, basePath string, fs afero.Fs) (*Checker, error) {
+// CheckerOptions configures a Checker.
+type CheckerOptions struct {
+	// ManifestPath is the manifest file to check against (required).
+	ManifestPath string
+	// BasePath is the directory relative to which manifest paths are
+	// resolved (required).
+	BasePath string
+	// Fs is the filesystem to use, defaults to OsFs if nil.
+	Fs afero.Fs
+}
+
+// NewChecker creates a new Checker with the given options. It returns an
+// error if opts is nil or either path is empty.
+func NewChecker(opts *CheckerOptions) (*Checker, error) {
+	if opts == nil || opts.ManifestPath == "" {
+		return nil, errManifestPathEmpty
+	}
+
+	if opts.BasePath == "" {
+		return nil, errBasePathEmpty
+	}
+
+	fs := opts.Fs
 	if fs == nil {
 		fs = afero.NewOsFs()
 	}

-	m, err := NewManifestFromFile(fs, manifestPath)
+	m, err := NewManifestFromFile(&ManifestFromFileOptions{
+		Path: opts.ManifestPath,
+		Fs:   fs,
+	})
 	if err != nil {
 		return nil, err
 	}

-	abs, err := filepath.Abs(basePath)
+	abs, err := filepath.Abs(opts.BasePath)
 	if err != nil {
 		return nil, err
 	}
@@ -108,7 +134,7 @@ func NewChecker(manifestPath string, basePath string, fs afero.Fs) (*Checker, er
 	}

 	// Compute manifest's relative path from basePath for exclusion in FindExtraFiles
-	absManifest, err := filepath.Abs(manifestPath)
+	absManifest, err := filepath.Abs(opts.ManifestPath)
 	if err != nil {
 		return nil, err
 	}
@@ -5,6 +5,8 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"os"
+	"path/filepath"
 	"testing"
 	"time"

@@ -14,9 +16,13 @@ import (
 )

 const (
-	testFile1      = "file1.txt"
-	testFile2      = "file2.txt"
-	testExistsFile = "exists.txt"
+	testFile1        = "file1.txt"
+	testFile2        = "file2.txt"
+	testExistsFile   = "exists.txt"
+	testManifestPath = "/manifest.mf"
+	testDataDir      = "/data"
+	// testDataManifestPath is a manifest kept inside the checked tree.
+	testDataManifestPath = testDataDir + "/index.mf"
 )

 func TestStatusString(t *testing.T) {
@@ -66,15 +72,13 @@ func createTestManifest(
 }

 // createFilesOnDisk creates the given files on the filesystem under
-// /data.
+// testDataDir.
 func createFilesOnDisk(t *testing.T, fs afero.Fs, files map[string][]byte) {
 	t.Helper()

-	basePath := "/data"
-
 	for path, content := range files {
-		fullPath := basePath + "/" + path
-		require.NoError(t, fs.MkdirAll(basePath, 0o755))
+		fullPath := testDataDir + "/" + path
+		require.NoError(t, fs.MkdirAll(testDataDir, 0o755))
 		require.NoError(t, afero.WriteFile(fs, fullPath, content, 0o644))
 	}
 }
@@ -90,9 +94,13 @@ func TestNewChecker(t *testing.T) {
 			testFile1: []byte("hello"),
 			testFile2: []byte("world"),
 		}
-		createTestManifest(t, fs, "/manifest.mf", files)
+		createTestManifest(t, fs, testManifestPath, files)

-		chk, err := NewChecker("/manifest.mf", "/", fs)
+		chk, err := NewChecker(&CheckerOptions{
+			ManifestPath: testManifestPath,
+			BasePath:     "/",
+			Fs:           fs,
+		})
 		require.NoError(t, err)
 		assert.NotNil(t, chk)
 		assert.Equal(t, FileCount(2), chk.FileCount())
@@ -102,7 +110,11 @@ func TestNewChecker(t *testing.T) {
 		t.Parallel()

 		fs := afero.NewMemMapFs()
-		_, err := NewChecker("/nonexistent.mf", "/", fs)
+		_, err := NewChecker(&CheckerOptions{
+			ManifestPath: "/nonexistent.mf",
+			BasePath:     "/",
+			Fs:           fs,
+		})
 		assert.Error(t, err)
 	})

@@ -111,11 +123,73 @@ func TestNewChecker(t *testing.T) {

 		fs := afero.NewMemMapFs()
 		require.NoError(t, afero.WriteFile(fs, "/bad.mf", []byte("not a manifest"), 0o644))
-		_, err := NewChecker("/bad.mf", "/", fs)
+		_, err := NewChecker(&CheckerOptions{
+			ManifestPath: "/bad.mf",
+			BasePath:     "/",
+			Fs:           fs,
+		})
 		assert.Error(t, err)
 	})
 }

+func TestNewCheckerRequiredPaths(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		opts *CheckerOptions
+		want string
+		is   error
+	}{
+		{
+			name: "nil options",
+			opts: nil,
+			want: "manifest path cannot be empty",
+			is:   errManifestPathEmpty,
+		},
+		{
+			name: "empty manifest path",
+			opts: &CheckerOptions{BasePath: testDataDir},
+			want: "manifest path cannot be empty",
+			is:   errManifestPathEmpty,
+		},
+		{
+			name: "empty base path",
+			opts: &CheckerOptions{ManifestPath: testManifestPath},
+			want: "base path cannot be empty",
+			is:   errBasePathEmpty,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			chk, err := NewChecker(tc.opts)
+			require.ErrorIs(t, err, tc.is)
+			require.EqualError(t, err, tc.want)
+			assert.Nil(t, chk)
+		})
+	}
+}
+
+func TestNewCheckerNilFsUsesOsFs(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	manifestPath := filepath.Join(dir, "index.mf")
+	content := []byte("hello")
+	createTestManifest(t, afero.NewOsFs(), manifestPath, map[string][]byte{
+		testFile1: content,
+	})
+	require.NoError(t, os.WriteFile(filepath.Join(dir, testFile1), content, 0o600))
+
+	chk, err := NewChecker(&CheckerOptions{ManifestPath: manifestPath, BasePath: dir})
+	require.NoError(t, err)
+
+	results := make(chan Result, 1)
+	require.NoError(t, chk.Check(context.Background(), results, nil))
+	assert.Equal(t, StatusOK, (<-results).Status)
+}
+
 func TestCheckerFileCountAndTotalBytes(t *testing.T) {
 	t.Parallel()

@@ -125,9 +199,13 @@ func TestCheckerFileCountAndTotalBytes(t *testing.T) {
 		"medium.txt": []byte("hello world"),
 		"large.txt":  bytes.Repeat([]byte("x"), 1000),
 	}
-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)

-	chk, err := NewChecker("/manifest.mf", "/", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     "/",
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	assert.Equal(t, FileCount(3), chk.FileCount())
@@ -142,10 +220,14 @@ func TestCheckAllFilesOK(t *testing.T) {
 		testFile1: []byte("content one"),
 		testFile2: []byte("content two"),
 	}
-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)
 	createFilesOnDisk(t, fs, files)

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 10)
@@ -172,13 +254,17 @@ func TestCheckMissingFile(t *testing.T) {
 		testExistsFile: []byte("I exist"),
 		"missing.txt":  []byte("I don't exist on disk"),
 	}
-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)
 	// Only create one file
 	createFilesOnDisk(t, fs, map[string][]byte{
 		testExistsFile: []byte("I exist"),
 	})

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 10)
@@ -211,13 +297,17 @@ func TestCheckSizeMismatch(t *testing.T) {
 	files := map[string][]byte{
 		testFileName: []byte("original content"),
 	}
-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)
 	// Create file with different size
 	createFilesOnDisk(t, fs, map[string][]byte{
 		testFileName: []byte("short"),
 	})

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 10)
@@ -237,7 +327,7 @@ func TestCheckHashMismatch(t *testing.T) {
 	files := map[string][]byte{
 		testFileName: originalContent,
 	}
-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)
 	// Create file with same size but different content
 	differentContent := []byte("different contnt") // same length (16 bytes) but different
 	require.Len(t, differentContent, len(originalContent), "test requires same length")
@@ -245,7 +335,11 @@ func TestCheckHashMismatch(t *testing.T) {
 		testFileName: differentContent,
 	})

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 10)
@@ -265,10 +359,14 @@ func TestCheckWithProgress(t *testing.T) {
 		testFile1: bytes.Repeat([]byte("a"), 100),
 		testFile2: bytes.Repeat([]byte("b"), 200),
 	}
-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)
 	createFilesOnDisk(t, fs, files)

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 10)
@@ -305,10 +403,14 @@ func TestCheckContextCancellation(t *testing.T) {
 		files[string(rune('a'+i%26))+".txt"] = bytes.Repeat([]byte("x"), 1000)
 	}

-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)
 	createFilesOnDisk(t, fs, files)

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	ctx, cancel := context.WithCancel(context.Background())
@@ -327,7 +429,7 @@ func TestFindExtraFiles(t *testing.T) {
 	manifestFiles := map[string][]byte{
 		testFile1: []byte("in manifest"),
 	}
-	createTestManifest(t, fs, "/manifest.mf", manifestFiles)
+	createTestManifest(t, fs, testManifestPath, manifestFiles)

 	// Disk has file1 and file2
 	createFilesOnDisk(t, fs, map[string][]byte{
@@ -335,7 +437,11 @@ func TestFindExtraFiles(t *testing.T) {
 		testFile2: []byte("extra file"),
 	})

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 10)
@@ -360,7 +466,7 @@ func TestFindExtraFilesSkipsManifestAndDotfiles(t *testing.T) {
 	manifestFiles := map[string][]byte{
 		testFile1: []byte("in manifest"),
 	}
-	createTestManifest(t, fs, "/data/.index.mf", manifestFiles)
+	createTestManifest(t, fs, testDataManifestPath, manifestFiles)
 	createFilesOnDisk(t, fs, map[string][]byte{
 		testFile1: []byte("in manifest"),
 	})
@@ -368,10 +474,14 @@ func TestFindExtraFilesSkipsManifestAndDotfiles(t *testing.T) {
 	require.NoError(t, afero.WriteFile(fs, "/data/.hidden", []byte("hidden"), 0o644))
 	require.NoError(t, afero.WriteFile(fs, "/data/.config/settings", []byte("cfg"), 0o644))
 	// Create a real extra file
-	require.NoError(t, fs.MkdirAll("/data", 0o755))
+	require.NoError(t, fs.MkdirAll(testDataDir, 0o755))
 	require.NoError(t, afero.WriteFile(fs, "/data/extra.txt", []byte("extra"), 0o644))

-	chk, err := NewChecker("/data/.index.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testDataManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 10)
@@ -383,7 +493,7 @@ func TestFindExtraFilesSkipsManifestAndDotfiles(t *testing.T) {
 		extras = append(extras, r)
 	}

-	// Should only report extra.txt, not .hidden, .config/settings, or .index.mf
+	// Should only report extra.txt, not .hidden, .config/settings, or index.mf
 	for _, e := range extras {
 		t.Logf("extra: %s", e.Path)
 	}
@@ -400,10 +510,14 @@ func TestFindExtraFilesContextCancellation(t *testing.T) {

 	fs := afero.NewMemMapFs()
 	files := map[string][]byte{testFileName: []byte("data")}
-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)
 	createFilesOnDisk(t, fs, files)

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	ctx, cancel := context.WithCancel(context.Background())
@@ -419,10 +533,14 @@ func TestCheckNilChannels(t *testing.T) {

 	fs := afero.NewMemMapFs()
 	files := map[string][]byte{testFileName: []byte("data")}
-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)
 	createFilesOnDisk(t, fs, files)

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	// Should not panic with nil channels
@@ -435,10 +553,14 @@ func TestFindExtraFilesNilChannel(t *testing.T) {

 	fs := afero.NewMemMapFs()
 	files := map[string][]byte{testFileName: []byte("data")}
-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)
 	createFilesOnDisk(t, fs, files)

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	// Should not panic with nil channel
@@ -455,7 +577,7 @@ func TestCheckSubdirectories(t *testing.T) {
 		"dir1/dir2/file2.txt":     []byte("content2"),
 		"dir1/dir2/dir3/deep.txt": []byte("deep content"),
 	}
-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)

 	// Create files with full directory structure
 	for path, content := range files {
@@ -465,7 +587,11 @@ func TestCheckSubdirectories(t *testing.T) {
 		require.NoError(t, afero.WriteFile(fs, fullPath, content, 0o644))
 	}

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 10)
@@ -493,13 +619,17 @@ func TestCheckMissingFileDetectedWithoutFallback(t *testing.T) {
 		testExistsFile: []byte("here"),
 		"missing.txt":  []byte("not on disk"),
 	}
-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)
 	// Only create one file on disk
 	createFilesOnDisk(t, fs, map[string][]byte{
 		testExistsFile: []byte("here"),
 	})

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 10)
@@ -528,7 +658,7 @@ func TestFindExtraFilesSkipsDotfiles(t *testing.T) {
 	files := map[string][]byte{
 		testFile1: []byte("in manifest"),
 	}
-	createTestManifest(t, fs, "/data/.index.mf", files)
+	createTestManifest(t, fs, testDataManifestPath, files)
 	createFilesOnDisk(t, fs, files)

 	// Add dotfiles and manifest file on disk
@@ -537,7 +667,11 @@ func TestFindExtraFilesSkipsDotfiles(t *testing.T) {
 	require.NoError(t,
 		afero.WriteFile(fs, "/data/.git/config", []byte("git config"), 0o644))

-	chk, err := NewChecker("/data/.index.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testDataManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 10)
@@ -563,10 +697,14 @@ func TestFindExtraFilesSkipsManifestFile(t *testing.T) {
 	files := map[string][]byte{
 		testFile1: []byte("content"),
 	}
-	createTestManifest(t, fs, "/data/index.mf", files)
+	createTestManifest(t, fs, testDataManifestPath, files)
 	createFilesOnDisk(t, fs, files)

-	chk, err := NewChecker("/data/index.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testDataManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 10)
@@ -587,9 +725,13 @@ func TestCheckEmptyManifest(t *testing.T) {

 	fs := afero.NewMemMapFs()
 	// Create manifest with no files
-	createTestManifest(t, fs, "/manifest.mf", map[string][]byte{})
+	createTestManifest(t, fs, testManifestPath, map[string][]byte{})

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	assert.Equal(t, FileCount(0), chk.FileCount())
@@ -621,10 +763,14 @@ func TestCheckProgressRateLimited(t *testing.T) {
 		files[name] = []byte("content")
 	}

-	createTestManifest(t, fs, "/manifest.mf", files)
+	createTestManifest(t, fs, testManifestPath, files)
 	createFilesOnDisk(t, fs, files)

-	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
 	require.NoError(t, err)

 	results := make(chan Result, 200)
@@ -17,4 +17,28 @@ const (

 	// uuidLength is the length in bytes of a binary UUID.
 	uuidLength = 16
+
+	// Numbers in mf.proto of MFFile.files and of the MFFilePath fields
+	// that decoding sets aside a fixed amount of memory for.
+	filesFieldNumber    = 101
+	hashesFieldNumber   = 3
+	mimeTypeFieldNumber = 301
+	mtimeFieldNumber    = 302
+	ctimeFieldNumber    = 303
+
+	// Bytes decoding sets aside for each file entry, hash, timestamp and
+	// MIME type, however short its encoding. checkDecodedSize refuses an
+	// inner message for which these add up to more than maxDecodedGrowth
+	// times its size.
+	decodedFileEntrySize = 160
+	decodedHashSize      = 112
+	decodedTimestampSize = 64
+	decodedMIMETypeSize  = 16
+
+	// Each file entry mfer writes holds a path of at least one byte, a
+	// multihash at least as long as SHA-256's 34 bytes (AddFileWithHash
+	// refuses shorter ones) and a modification time: at least 47 bytes,
+	// counted at 336. So its manifests add up to at most about 7.15 times
+	// their size, and this limit is about 12% above that.
+	maxDecodedGrowth = 8
 )
@@ -11,6 +11,7 @@ import (
 	"github.com/google/uuid"
 	"github.com/klauspost/compress/zstd"
 	"github.com/spf13/afero"
+	"google.golang.org/protobuf/encoding/protowire"
 	"google.golang.org/protobuf/proto"
 	"sneak.berlin/go/mfer/internal/bork"
 	"sneak.berlin/go/mfer/internal/log"
@@ -27,6 +28,8 @@ var (
 	errUUIDMismatch         = errors.New("outer and inner UUID mismatch")
 	errInvalidFileFormat    = errors.New("invalid file format")
 	errInvalidManifestPath  = errors.New("manifest contains invalid path")
+	errDecodedTooLarge      = errors.New(
+		"manifest would take too much memory to decode")
 )

 // validateUUID checks that the byte slice is a valid UUID (16 bytes, parseable).
@@ -154,6 +157,85 @@ func (m *manifest) decompressInner() ([]byte, error) {
 	return dat, nil
 }

+// checkDecodedSize refuses an encoded inner message whose file entries,
+// hashes, timestamps and MIME types would take more than maxDecodedGrowth
+// times its size to decode. Decoding sets aside a fixed amount for each,
+// however short its encoding, so a message of empty ones would take about
+// 50 times its size.
+func checkDecodedSize(inner []byte) error {
+	limit := maxDecodedGrowth * int64(len(inner))
+
+	var decoded int64
+
+	add := func(size int64) error {
+		decoded += size
+		if decoded > limit {
+			return errDecodedTooLarge
+		}
+
+		return nil
+	}
+
+	return forEachBytesField(inner, func(num protowire.Number, entry []byte) error {
+		if num != filesFieldNumber {
+			return nil
+		}
+
+		err := add(decodedFileEntrySize)
+		if err != nil {
+			return err
+		}
+
+		return forEachBytesField(entry, func(num protowire.Number, _ []byte) error {
+			if num == hashesFieldNumber {
+				return add(decodedHashSize)
+			}
+
+			if num == mtimeFieldNumber || num == ctimeFieldNumber {
+				return add(decodedTimestampSize)
+			}
+
+			if num == mimeTypeFieldNumber {
+				return add(decodedMIMETypeSize)
+			}
+
+			return nil
+		})
+	})
+}
+
+// forEachBytesField calls fn with the number and value of each
+// length-delimited field in the encoded message msg, and fails if msg is
+// malformed.
+func forEachBytesField(
+	msg []byte, fn func(num protowire.Number, value []byte) error,
+) error {
+	for len(msg) > 0 {
+		num, wireType, tagLen := protowire.ConsumeTag(msg)
+		if tagLen < 0 {
+			return protowire.ParseError(tagLen)
+		}
+
+		valueLen := protowire.ConsumeFieldValue(num, wireType, msg[tagLen:])
+		if valueLen < 0 {
+			return protowire.ParseError(valueLen)
+		}
+
+		if wireType == protowire.BytesType {
+			value, _ := protowire.ConsumeBytes(msg[tagLen:])
+
+			err := fn(num, value)
+			if err != nil {
+				return err
+			}
+		}
+
+		msg = msg[tagLen+valueLen:]
+	}
+
+	return nil
+}
+
 func (m *manifest) deserializeInner() error {
 	err := m.validateOuterHeader()
 	if err != nil {
@@ -177,10 +259,16 @@ func (m *manifest) deserializeInner() error {
 		return bork.ErrFileTruncated
 	}

+	err = checkDecodedSize(dat)
+	if err != nil {
+		return fmt.Errorf("deserialize: unmarshal inner: %w", err)
+	}
+
 	// Deserialize inner message
 	m.pbInner = new(MFFile)

-	err = proto.Unmarshal(dat, m.pbInner)
+	// Unknown fields would cost memory; mfer never writes a loaded manifest out.
+	err = proto.UnmarshalOptions{DiscardUnknown: true}.Unmarshal(dat, m.pbInner)
 	if err != nil {
 		return fmt.Errorf("deserialize: unmarshal inner: %w", err)
 	}
@@ -249,7 +337,8 @@ func NewManifestFromReader(input io.Reader) (*manifest, error) {
 	// deserialize outer:
 	m.pbOuter = new(MFFileOuter)

-	err = proto.Unmarshal(dat, m.pbOuter)
+	// Unknown fields would cost memory; mfer never writes a loaded manifest out.
+	err = proto.UnmarshalOptions{DiscardUnknown: true}.Unmarshal(dat, m.pbOuter)
 	if err != nil {
 		return nil, err
 	}
@@ -263,16 +352,29 @@ func NewManifestFromReader(input io.Reader) (*manifest, error) {
 	return m, nil
 }

-// NewManifestFromFile reads a manifest from a file path using the given filesystem.
-// If fs is nil, the real filesystem (OsFs) is used.
+// ManifestFromFileOptions configures NewManifestFromFile.
+type ManifestFromFileOptions struct {
+	// Path is the manifest file to read (required).
+	Path string
+	// Fs is the filesystem to use, defaults to OsFs if nil.
+	Fs afero.Fs
+}
+
+// NewManifestFromFile reads a manifest from a file. It returns an error if
+// opts is nil or its path is empty.
 //
 //nolint:revive // unexported-return: exporting manifest is owner question 13
-func NewManifestFromFile(fs afero.Fs, path string) (*manifest, error) {
+func NewManifestFromFile(opts *ManifestFromFileOptions) (*manifest, error) {
+	if opts == nil || opts.Path == "" {
+		return nil, errManifestPathEmpty
+	}
+
+	fs := opts.Fs
 	if fs == nil {
 		fs = afero.NewOsFs()
 	}

-	f, err := fs.Open(path)
+	f, err := fs.Open(opts.Path)
 	if err != nil {
 		return nil, err
 	}
@@ -54,9 +54,15 @@ func FuzzNewManifestFromReader(f *testing.F) {
 		}

 		// It also keeps a few copies of its input. Buffers grow by
-		// copying, so reaching those sizes allocates a few times them in
-		// total: sixteen times the input and the decompressed data leaves
-		// room for that.
+		// copying, so reaching those sizes allocates up to about six times
+		// them in total. Decoding the decompressed data takes up to
+		// maxDecodedGrowth times its size for file entries, hashes,
+		// timestamps and MIME types, and drops fields it does not know.
+		// The strings and bytes it copies out of it, such as many one-byte
+		// values in one hash, take up to about five times more under the
+		// race detector, which pads every small copy to 16 bytes, and about
+		// half that without it. Twenty times the input and the
+		// decompressed data leaves room for all of that.
 		//
 		// The decoder also sets aside a new buffer of one to two times the
 		// window for each frame that asks for a larger window than the
@@ -71,8 +77,9 @@ func FuzzNewManifestFromReader(f *testing.F) {
 		// fails if the decoder accepts windows of twice zstdWindowSize; the
 		// seed whose two frames together exceed MaxDecompressedSize fails
 		// if the decoder decodes them in full instead of stopping at the
-		// declared size.
-		limit := 16*(uint64(len(data))+decompressed) + 24*zstdWindowSize
+		// declared size; the seeds of empty file entries and of a file
+		// entry of empty hashes fail if the parser decodes them.
+		limit := 20*(uint64(len(data))+decompressed) + 24*zstdWindowSize

 		allocated := after.TotalAlloc - before.TotalAlloc
 		if allocated > limit {
@@ -6,10 +6,14 @@ import (
 	"context"
 	"crypto/sha256"
 	"fmt"
+	"strconv"
+	"strings"
 	"testing"
+	"time"

 	"github.com/google/uuid"
 	"github.com/klauspost/compress/zstd"
+	"github.com/multiformats/go-multihash"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"google.golang.org/protobuf/encoding/protowire"
@@ -114,10 +118,119 @@ func TestDeserializeRejectsInvalidEntryPaths(t *testing.T) {
 	}
 }

+// Entries of a path, an empty hash, an empty MIME type and empty modification
+// and change times are counted at 416 bytes each (160 + 112 + 16 + 64 + 64)
+// and take 16 bytes plus the path to encode. A 35-character path makes that
+// 51 bytes, about 8.2 times: refused, and leaving any one of the five
+// uncounted, even the MIME type, brings it under 8. A 37-character path makes
+// it 53 bytes, about 7.8 times: loaded.
+func TestDeserializeRefusesEntriesThatDecodeTooLarge(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		pathLen int
+		refused bool
+	}{
+		{35, true},
+		{37, false},
+	}
+
+	for _, tt := range tests {
+		t.Run(strconv.Itoa(tt.pathLen), func(t *testing.T) {
+			t.Parallel()
+
+			entry := protowire.AppendTag(nil, 1, protowire.BytesType) // MFFilePath.path
+			entry = protowire.AppendString(entry, strings.Repeat("a", tt.pathLen))
+			entry = protowire.AppendTag(entry, 3, protowire.BytesType) // MFFilePath.hashes
+			entry = protowire.AppendBytes(entry, nil)
+			entry = protowire.AppendTag(entry, 301, protowire.BytesType) // MFFilePath.mimeType
+			entry = protowire.AppendBytes(entry, nil)
+			entry = protowire.AppendTag(entry, 302, protowire.BytesType) // MFFilePath.mtime
+			entry = protowire.AppendBytes(entry, nil)
+			entry = protowire.AppendTag(entry, 303, protowire.BytesType) // MFFilePath.ctime
+			entry = protowire.AppendBytes(entry, nil)
+
+			id := uuid.New()
+			inner := protowire.AppendTag(nil, 102, protowire.BytesType) // MFFile.uuid
+			inner = protowire.AppendBytes(inner, id[:])
+
+			for range 1000 {
+				inner = protowire.AppendTag(inner, 101, protowire.BytesType) // MFFile.files
+				inner = protowire.AppendBytes(inner, entry)
+			}
+
+			_, err := NewManifestFromReader(bytes.NewReader(wrapInner(t, id, inner)))
+			if tt.refused {
+				require.ErrorIs(t, err, errDecodedTooLarge)
+			} else {
+				require.NoError(t, err)
+			}
+		})
+	}
+}
+
+// Fields the decoder does not know are dropped, in the outer message, the inner
+// message and a file entry, so that they take no memory once loaded.
+func TestDeserializeDropsUnknownFields(t *testing.T) {
+	t.Parallel()
+
+	unknown := protowire.AppendTag(nil, 99, protowire.BytesType) // in no message
+	unknown = protowire.AppendBytes(unknown, []byte("not known"))
+
+	entry := protowire.AppendTag(nil, 1, protowire.BytesType) // MFFilePath.path
+	entry = protowire.AppendString(entry, "a")
+	entry = append(entry, unknown...)
+
+	id := uuid.New()
+	inner := protowire.AppendTag(nil, 101, protowire.BytesType) // MFFile.files
+	inner = protowire.AppendBytes(inner, entry)
+	inner = protowire.AppendTag(inner, 102, protowire.BytesType) // MFFile.uuid
+	inner = protowire.AppendBytes(inner, id[:])
+	inner = append(inner, unknown...)
+
+	data := wrapInner(t, id, inner)
+	data = append(data, unknown...) // the outer message ends the file
+
+	m, err := NewManifestFromReader(bytes.NewReader(data))
+	require.NoError(t, err)
+	require.Len(t, m.Files(), 1)
+	assert.Empty(t, m.pbOuter.ProtoReflect().GetUnknown())
+	assert.Empty(t, m.pbInner.ProtoReflect().GetUnknown())
+	assert.Empty(t, m.Files()[0].ProtoReflect().GetUnknown())
+}
+
+// Many empty files with names of at most three characters and modification
+// times at the epoch make about the densest manifest mfer writes: it takes
+// about 7 times its size to decode, and still loads. A signature would not
+// change the inner message, so none is added.
+func TestDeserializeLoadsDensestManifest(t *testing.T) {
+	t.Parallel()
+
+	hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)
+
+	b := NewBuilder()
+	b.SetIncludeTimestamps(true)
+
+	const files = 10000
+	for i := range files {
+		name := RelFilePath(strconv.FormatInt(int64(i), 36))
+		require.NoError(t, b.AddFileWithHash(name, 0, ModTime(time.Unix(0, 0)), hash))
+	}
+
+	var buf bytes.Buffer
+	require.NoError(t, b.Build(context.Background(), &buf))
+
+	m, err := NewManifestFromReader(&buf)
+	require.NoError(t, err)
+	assert.Len(t, m.Files(), files)
+}
+
 func TestDeserializeValidManifestRoundTrips(t *testing.T) {
 	t.Parallel()

-	hash := make([]byte, 34) // multihash: 2-byte prefix + 32-byte SHA-256
+	hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)

 	b := NewBuilder()
 	require.NoError(t, b.AddFileWithHash("dir/file.txt", 123, ModTime{}, hash))
@@ -10,6 +10,7 @@ import (
 	"path/filepath"
 	"strconv"
 	"strings"
+	"syscall"
 	"testing"
 	"time"

@@ -425,36 +426,51 @@ func TestGPGTimeoutKillsGPG(t *testing.T) {
 	assert.Contains(t, err.Error(), "gpg sign failed: gpg timed out")
 }

-// TestGPGTimeoutWhenChildHoldsOutput uses a fake gpg that runs sleep as a
+// TestGPGCancelWhenChildHoldsOutput uses a fake gpg that runs sleep as a
 // child instead of exec-ing it, the way a wrapper script around the real
 // gpg might. Killing the fake gpg leaves sleep holding its stdout and
-// stderr open; the call must still return shortly after the deadline
-// instead of waiting for sleep to exit. The fake gpg writes the process ID
-// of sleep to a file so that the test can kill it before returning.
-func TestGPGTimeoutWhenChildHoldsOutput(t *testing.T) {
-	pidFile := filepath.Join(t.TempDir(), "sleep.pid")
+// stderr open; the call must still return once ctx ends instead of waiting
+// for sleep to exit. The fake gpg writes the process ID of sleep to a named
+// pipe; the test ends ctx only after reading it, so sleep is running by
+// then, and kills sleep before returning.
+func TestGPGCancelWhenChildHoldsOutput(t *testing.T) {
+	pidPipe := filepath.Join(t.TempDir(), "sleep.pid")
+	require.NoError(t, syscall.Mkfifo(pidPipe, 0o600))
+	// sleep outlasts the 10 s wait below, so a call that waits for it fails.
 	t.Setenv("PATH", fakeGPGPath(t,
-		"#!/bin/sh\nsleep 3 &\necho $! >'"+pidFile+"'\nwait\n"))
-	t.Cleanup(func() {
-		pid, err := os.ReadFile(pidFile) //nolint:gosec // G304: path inside t.TempDir()
-		require.NoError(t, err)
+		"#!/bin/sh\nsleep 60 &\necho $! >'"+pidPipe+"'\nwait\n"))

-		n, err := strconv.Atoi(strings.TrimSpace(string(pid)))
-		require.NoError(t, err)
-
-		sleep, err := os.FindProcess(n)
-		require.NoError(t, err)
-		require.NoError(t, sleep.Kill())
-	})
-
-	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()

-	start := time.Now()
-	_, err := gpgSign(ctx, []byte("data"), GPGKeyID("any"))
-	require.ErrorIs(t, err, context.DeadlineExceeded)
-	assert.Less(t, time.Since(start), 3*time.Second,
-		"the call waited for the child holding gpg's output to exit")
+	signErr := make(chan error, 1)
+
+	go func() {
+		_, err := gpgSign(ctx, []byte("data"), GPGKeyID("any"))
+		signErr <- err
+	}()
+
+	pid, err := os.ReadFile(pidPipe) //nolint:gosec // G304: path inside t.TempDir()
+	require.NoError(t, err)
+
+	n, err := strconv.Atoi(strings.TrimSpace(string(pid)))
+	require.NoError(t, err)
+
+	sleep, err := os.FindProcess(n)
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, sleep.Kill()) })
+
+	cancel()
+
+	// The call should return about gpgWaitDelay (one second) after the
+	// cancel. 10 s is far above that and well under the 30 s test timeout,
+	// which would abort the whole package before the cleanup kills sleep.
+	select {
+	case err := <-signErr:
+		require.ErrorIs(t, err, context.Canceled)
+	case <-time.After(10 * time.Second):
+		t.Fatal("the call waited for the child holding gpg's output to exit")
+	}
 }

 // TestBuildPassesContextToSigning checks that a caller can cancel the gpg
@@ -0,0 +1 @@
+103901c42b94396aa7ae128fd503ef693a4b7a03b2169481f25fda3d2c254e00  mf.proto
@@ -0,0 +1,29 @@
+package mfer_test
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// mf.pb.go is generated from mf.proto and committed. `make generate`
+// records the hash of the mf.proto it generated from in mf.proto.sha256.
+func TestGeneratedCodeMatchesProto(t *testing.T) {
+	t.Parallel()
+
+	proto, err := os.ReadFile("mf.proto")
+	require.NoError(t, err)
+
+	recorded, err := os.ReadFile("mf.proto.sha256")
+	require.NoError(t, err)
+
+	recordedHash, _, _ := strings.Cut(string(recorded), " ")
+	sum := sha256.Sum256(proto)
+	require.Equal(t, recordedHash, hex.EncodeToString(sum[:]),
+		"mfer/mf.proto has changed since mfer/mf.pb.go was generated "+
+			"from it: run `make generate` and commit the result")
+}
@@ -4,6 +4,7 @@ import (
 	"context"
 	"io"
 	"io/fs"
+	"os"
 	"path"
 	"path/filepath"
 	"strings"
@@ -57,6 +58,8 @@ type ScannerOptions struct {
 	SigningOptions *SigningOptions
 	// Seed, if set, derives a deterministic UUID from this seed.
 	Seed string
+	// ExcludePaths lists files to leave out of the listing, matched with os.SameFile.
+	ExcludePaths []string
 }

 // FileEntry represents a file that has been enumerated.
@@ -75,6 +78,7 @@ type Scanner struct {
 	totalBytes FileSize // cached sum of all file sizes
 	options    *ScannerOptions
 	fs         afero.Fs
+	excluded   []fs.FileInfo // the files named in ExcludePaths that exist
 }

 // NewScanner creates a new Scanner with default options.
@@ -93,11 +97,22 @@ func NewScannerWithOptions(opts *ScannerOptions) *Scanner {
 		fs = afero.NewOsFs()
 	}

-	return &Scanner{
+	s := &Scanner{
 		files:   make([]*FileEntry, 0),
 		options: opts,
 		fs:      fs,
 	}
+
+	// A path that cannot be stat'd, normally because no file is there,
+	// needs no leaving out.
+	for _, p := range opts.ExcludePaths {
+		info, err := s.fs.Stat(p)
+		if err == nil {
+			s.excluded = append(s.excluded, info)
+		}
+	}
+
+	return s
 }

 // EnumerateFile adds a single file to the scanner, calling stat() to get metadata.
@@ -435,6 +450,12 @@ func (s *Scanner) enumerateFileWithInfo(
 		info = realInfo
 	}

+	for _, excluded := range s.excluded {
+		if os.SameFile(info, excluded) {
+			return nil
+		}
+	}
+
 	entry := &FileEntry{
 		Path:    RelFilePath(cleanPath),
 		AbsPath: AbsFilePath(absPath),
@@ -304,46 +304,19 @@ func TestScannerEnumerateFS(t *testing.T) {
 func TestSendEnumerateStatusNonBlocking(t *testing.T) {
 	t.Parallel()

-	// Channel with no buffer - send should not block
+	// Nobody receives, so a blocking send would hang the test into its timeout.
 	ch := make(chan EnumerateStatus)

-	// This should not block
-	done := make(chan bool)
-
-	go func() {
-		sendEnumerateStatus(ch, EnumerateStatus{FilesFound: 1})
-
-		done <- true
-	}()
-
-	select {
-	case <-done:
-		// Success - did not block
-	case <-time.After(100 * time.Millisecond):
-		t.Fatal("sendEnumerateStatus blocked on full channel")
-	}
+	sendEnumerateStatus(ch, EnumerateStatus{FilesFound: 1})
 }

 func TestSendScanStatusNonBlocking(t *testing.T) {
 	t.Parallel()

-	// Channel with no buffer - send should not block
+	// Nobody receives, so a blocking send would hang the test into its timeout.
 	ch := make(chan ScanStatus)

-	done := make(chan bool)
-
-	go func() {
-		sendScanStatus(ch, ScanStatus{ScannedFiles: 1})
-
-		done <- true
-	}()
-
-	select {
-	case <-done:
-		// Success - did not block
-	case <-time.After(100 * time.Millisecond):
-		t.Fatal("sendScanStatus blocked on full channel")
-	}
+	sendScanStatus(ch, ScanStatus{ScannedFiles: 1})
 }

 func TestSendStatusNilChannel(t *testing.T) {
@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("ZNAVSRFG\xa8\x06\x01\xb0\x06\x01\xb8\x06\xff\xff\xff\x03\xc2\x06 {\x16\xbdu\xa0\xa2\x11\xfcH\xef*\x1b7\r\x99\xefb\x04\x02g\n\xa9\xf3B5\xe5p\x96\x8c\x8c\xac\x0e\xca\x06\x10\x03Q\xb2\xd0\x19`F\xc1\xb1\xc0Z\xf4x\xf4g^\xba\f\xa1\x06(\xb5/\xfd\x04h\x04\x01\x00d\x01\xb2\x06\x10\x03Q\xb2\xd0\x19`F\xc1\xb1\xc0Z\xf4x\xf4g^\xaa\x06\x00\x01T\x13\x024\xce\xff\rL\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15M\x00\x00\x00\x01T\x00\x044\xfc\xff\x153\xea\a\xb4")
@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("ZNAVSRFG\xa8\x06\x01\xb0\x06\x01\xb8\x06\xff\xff\xff\x03\xc2\x06 .\xcd\x11|0\xfcP\xe5\x1b\xe3\xc6Ӡ\xcdڤx\xcd\x169t\x1a9~ǽB\xc9\xe8G`\x05\xca\x06\x10\x11*!\x0e\x95EF\xb8\xbd\x9f\xde\x12MF\r\x99\xba\f\xa6\x06(\xb5/\xfd\x04h,\x01\x00\xb4\x01\xb2\x06\x10\x11*!\x0e\x95EF\xb8\xbd\x9f\xde\x12MF\r\x99\xaa\x06\xe6\xff\xff\x03\x1a\x00\x01T\x14\x024\x8b\xff\x17L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15L\x00\x00\x00\x01T\x00\x044\xfd\xff\x15M\x00\x00\x00\x01T\x00\x044\xfc\xff\x15\x02\xd1.\xe3")
@@ -140,12 +140,7 @@ main() {

    # ---- Go repos ----
    if missing go; then pkg_install go golang go go; fi
-    # golangci-lint: packaged in nix, brew, and apk. On apt there is no
-    # package: download a specific release archive from GitHub and
-    # verify its hash (verify_sha256), never curl | sh.
-    if missing golangci-lint; then
-        pkg_install golangci-lint golangci-lint golangci-lint golangci-lint
-    fi
+    # No golangci-lint: script/lint runs it in Docker only.
    go mod download

    # ---- Python repos ----
@@ -5,21 +5,9 @@ set -eu
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"

-# Regenerate mfer/mf.pb.go from mfer/mf.proto if it is missing or stale
-# (mirrors the old Makefile prerequisite; the generated file is
-# committed, so this is normally a no-op).
-ensure_pb() {
-    if [ ! -f mfer/mf.pb.go ] ||
-        [ -n "$(find mfer/mf.proto -newer mfer/mf.pb.go 2>/dev/null)" ]; then
-        (cd mfer && go generate .)
-    fi
-}
-
 main() {
    cd "$ROOT"
-    ensure_pb
    gofumpt -l -w mfer internal cmd
-    golangci-lint run --fix
    # Markdown and JSON, over the same file set script/fmt-check verifies.
    "$SCRIPT_DIR/prettier" --write
 }
@@ -6,19 +6,8 @@ set -eu

 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

-# Regenerate mfer/mf.pb.go from mfer/mf.proto if it is missing or stale
-# (mirrors the old Makefile prerequisite; the generated file is
-# committed, so this is normally a no-op).
-ensure_pb() {
-    if [ ! -f mfer/mf.pb.go ] ||
-        [ -n "$(find mfer/mf.proto -newer mfer/mf.pb.go 2>/dev/null)" ]; then
-        (cd mfer && go generate .)
-    fi
-}
-
 main() {
    cd "$ROOT"
-    ensure_pb
    if [ -n "$(gofmt -l .)" ]; then
        echo "gofmt: files need formatting:" >&2
        gofmt -l . >&2
@@ -0,0 +1,52 @@
+#!/bin/sh
+# script/generate: regenerate mfer/mf.pb.go from mfer/mf.proto, and record
+# the hash of that mf.proto in mfer/mf.proto.sha256. Nothing else
+# regenerates mf.pb.go: it is committed, so building and checking need no
+# protoc. A test fails while mf.proto no longer matches the recorded hash.
+#
+# Needs exactly the protoc and protoc-gen-go versions named in the header of
+# the committed mf.pb.go (README.md says how to install them). Another
+# version writes a different mf.pb.go, so the script refuses to run.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# protoc 33.4 names itself v6.33.4 in the mf.pb.go header.
+PROTOC_VERSION="33.4"
+PROTOC_GEN_GO_VERSION="v1.36.11"
+
+# require_version <command> <its exact --version output>
+require_version() {
+    actual="$("$1" --version 2>/dev/null || true)"
+    if [ "$actual" != "$2" ]; then
+        echo "generate: needs $2 on PATH, found: ${actual:-none}" >&2
+        echo "  README.md says how to install it." >&2
+        exit 1
+    fi
+}
+
+# sha256 <file>: print "<hash>  <file>", with sha256sum, or with shasum
+# where there is no sha256sum.
+sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "$1"
+    elif command -v shasum >/dev/null 2>&1; then
+        shasum -a 256 "$1"
+    else
+        echo "generate: needs sha256sum or shasum on PATH" >&2
+        exit 1
+    fi
+}
+
+main() {
+    cd "$ROOT/mfer"
+    require_version protoc "libprotoc $PROTOC_VERSION"
+    require_version protoc-gen-go "protoc-gen-go $PROTOC_GEN_GO_VERSION"
+    # Hashed before regenerating, so a missing hash tool stops the script
+    # before it changes anything. Regenerating leaves mf.proto as it is.
+    proto_hash="$(sha256 mf.proto)"
+    go generate .
+    echo "$proto_hash" >mf.proto.sha256
+}
+
+main "$@"
@@ -1,17 +1,20 @@
 #!/bin/sh
-# script/lint: run the linter.
+# script/lint: run golangci-lint, in Docker only. Builds the lint stage of
+# the Dockerfile, whose build runs the linter, so a successful build is a
+# clean lint. --no-cache because a cached build runs no linter. The image
+# is removed afterwards, whatever the outcome.
 set -eu

-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"

 main() {
    cd "$ROOT"
-    golangci-lint run
-    if [ -n "$(gofmt -l .)" ]; then
-        echo "gofmt: files need formatting:" >&2
-        gofmt -l . >&2
-        exit 1
-    fi
+    # Tagged per run, so concurrent runs never remove each other's image.
+    image="$("$SCRIPT_DIR/projectname")-lint:$$"
+    # A failed build leaves no image, so there is nothing to remove then.
+    trap 'docker image rm "$image" >/dev/null 2>&1 || true' EXIT INT TERM
+    docker build --no-cache --target lint -t "$image" .
 }

 main "$@"
@@ -4,19 +4,8 @@ set -eu

 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

-# Regenerate mfer/mf.pb.go from mfer/mf.proto if it is missing or stale
-# (mirrors the old Makefile prerequisite; the generated file is
-# committed, so this is normally a no-op).
-ensure_pb() {
-    if [ ! -f mfer/mf.pb.go ] ||
-        [ -n "$(find mfer/mf.proto -newer mfer/mf.pb.go 2>/dev/null)" ]; then
-        (cd mfer && go generate .)
-    fi
-}
-
 main() {
    cd "$ROOT"
-    ensure_pb
    go test -timeout 30s -race -cover ./... ||
        {
            echo "--- Rerunning with -v for details ---"
Author	SHA1	Message	Date
sneak	e2039f3dda	fetch: client timeout, retry with backoff, url.JoinPath (closes #63 ) check / check (push) Waiting to run Details fetch now makes every request through an http.Client with a time limit, ten minutes by default and set with --timeout, which must be greater than zero. A connection error, a timeout, or a 5xx or 429 response is retried, up to five tries in all, after a random wait whose limit doubles from one second, or after the wait the server's Retry-After asks for, up to one minute. Each try of a file starts a new temp file, so a retry never keeps a partial file; the size and hash checks are unchanged. Manifest and file URLs are built with URL.JoinPath, so a base URL with or without a trailing slash or with a query string, and names that need escaping, all work. Model: opus-5-5	2026-10-04 13:22:35 +00:00
clawbot	4bf87d1ccf	AddFileWithHash rejects hashes that are not multihashes (closes #129 ) check / check (push) Waiting to run Details AddFileWithHash took any non-empty bytes as a hash, so the builder could write a manifest that mfer refuses to load. It now decodes the hash with go-multihash and also requires a digest of at least 32 bytes, the SHA-256 length the reader's decoding-cost limit assumes: a valid but shorter multihash, such as an empty identity hash or SHA-1, still makes a manifest of one-character paths too costly to load. When mfer freshen meets such a hash in an existing manifest, its error names the manifest entry and says to regenerate the manifest with mfer generate. Test fixtures whose stand-in hashes were not valid multihashes now use a SHA-256 multihash. Model: opus-5-5	2026-10-04 14:48:49 +02:00
clawbot	e412d20c20	Default the manifest to index.mf and keep it out of its own listing (closes #100 ) check / check (push) Waiting to run Details mfer gen now writes index.mf instead of .index.mf, the name fetch requests and the README calls the standard filename. Given a directory, check, freshen, list and export look only for index.mf; .index.mf is no longer recognized. Because index.mf is not hidden, gen and freshen leave out of their own listing the manifest they write and a temp file an interrupted run left beside it, matched by file identity (os.SameFile) however the path is spelled. The scanner takes these as a plain ExcludePaths list; manifestTempPath alone names the temp file, for both writes, both skips and the tests. Model: opus-5-5	2026-10-04 13:48:52 +02:00
clawbot	0501568203	Never regenerate mf.pb.go during checks; fail when it is stale (closes #71 ) check / check (push) Waiting to run Details The test and format scripts regenerated mfer/mf.pb.go whenever mfer/mf.proto looked newer by mtime, which a fresh checkout often causes, so make check could rewrite a committed file and needed protoc. Nothing regenerates it any more except make generate (script/generate), which refuses to run unless protoc 33.4 and protoc-gen-go v1.36.11, the versions that wrote the committed file, are on PATH, and records the hash of mf.proto in mfer/mf.proto.sha256. A Go test compares that hash with mf.proto and fails, naming make generate, when they differ. The mtime rule, the unused protoc-gen-go v1.28.1 install rule, make clean's deletion of mf.pb.go and the Dockerfile's touch workarounds are removed. Model: opus-5-5	2026-10-04 13:31:57 +02:00
clawbot	0a9963002c	NewChecker takes CheckerOptions instead of positional arguments (closes #78 ) check / check (push) Waiting to run Details NewChecker now takes CheckerOptions (ManifestPath, BasePath, Fs), named like ScannerOptions. A nil Fs still means the OS filesystem, as before and as in ScannerOptions; nil options or an empty path return an error naming the missing path. Audit of the other exported constructors in mfer: NewManifestFromFile took a filesystem and a path positionally; it now takes ManifestFromFileOptions (Path, Fs) with the same nil and empty rules. NewBuilder and NewScanner take no arguments, NewScannerWithOptions already takes options, and NewManifestFromReader takes one reader, which the style guide exempts; these are unchanged. Model: opus-5-5	2026-10-04 12:19:31 +02:00
clawbot	76116005c8	Reject manifests whose file entries decode far larger than their bytes (closes #123 ) check / check (push) Waiting to run Details Before decoding the manifest, the parser adds up what decoding sets aside for each file entry, hash, timestamp and MIME type, however short its encoding, and refuses the manifest once that passes 8 times the decompressed size; manifests mfer writes come to at most about 7.15 times. Empty entries decoded to about 50 times their size: under 1 KB of manifest allocated about 500 MB. Fields the decoder does not know are dropped; kept, they took up to 5 times more. A test refuses entries counted just over 8 times and loads them just under. The fuzz ceiling rises from 16 to 20 times the input and decompressed data; seeds of empty entries and of empty hashes fail it without the fix. Model: opus-5-5	2026-10-04 12:02:27 +02:00
clawbot	7088857692	Count -v once and document -v -v for debug output (closes #125 ) check / check (push) Waiting to run Details urfave/cli before v2.25.5 counted a flag given by its alias twice, so one -v or --verbose already gave debug output. Bump it to v2.27.7, which counts it once: one -v gives verbose output, two give debug. The -v help text now says -v -v instead of -vv, which stays refused: urfave/cli's option for combined short flags would let a flag that takes a value read the next letter as its value. -v and --verbose together stay refused: urfave/cli v2 refuses a flag given under two of its names, and one flag with an alias keeps help and parsing simple. The bump changes some help output; generate and fetch now name their arguments. Tests start each run at the default log level. Model: opus-5-5	2026-10-04 11:48:52 +02:00
clawbot	588c1bae74	Give the image CA certificates so fetch works over HTTPS (closes #131 ) check / check (push) Waiting to run Details The final stage is scratch, which has no CA certificates, so fetch from an HTTPS URL failed to verify any server. Copy the CA bundle from the pinned builder image into the final stage. Model: opus-5-5	2026-10-04 10:31:54 +02:00
clawbot	64eb5cbd40	Scanner status tests no longer depend on a 100 ms timer (closes #124 ) check / check (push) Waiting to run Details The two status-send tests now call the send directly on a channel nobody receives from, so a blocking send hangs the test into its timeout instead of racing a 100 ms timer that a loaded host can miss. The gpg test for a child holding gpg's output had the same problem: its 100 ms deadline could fire before the fake gpg wrote the PID of sleep, and the cleanup then failed. The fake gpg now writes that PID to a named pipe, and the test cancels only after reading it. It then waits up to 10 s for the call, so a call that waits for sleep fails the test and the cleanup still kills sleep. Model: opus-5-5	2026-10-04 09:48:51 +02:00
clawbot	45eac1f6f8	Run all linting in Docker via the Dockerfile lint stage (closes #90 ) check / check (push) Waiting to run Details script/lint now builds only the lint stage of the main Dockerfile (docker build --no-cache --target lint), whose build runs the linter, so a successful build is a clean lint. It is uncached because a cached build runs no linter, and a trap removes the image it tagged; the tag carries the process ID so concurrent runs do not collide. The lint stage calls golangci-lint directly, since make lint now needs Docker. Nothing installs or runs golangci-lint on the host any more: bootstrap and the Makefile drop the install, and script/fmt drops golangci-lint run --fix. Model: opus-5-5	2026-10-04 09:31:54 +02:00
clawbot	b91e92b070	Build a static binary so the scratch image runs (closes #126 ) check / check (push) Waiting to run Details The final stage is scratch, which has no C library, but the builder compiled mfer with cgo on (the golang image's default). The binary imports net (mfer's own HTTP code does, and so does google/uuid), so with cgo on it came out dynamically linked and the image could not start. The image's go build now sets CGO_ENABLED=0; nothing in mfer needs cgo. A new builder step runs ldd on the binary and fails the build unless it reports a static executable. Model: opus-5-5	2026-10-04 08:48:52 +02:00
clawbot	a2732cf8da	Add the required README sections (closes #75 ) check / check (push) Waiting to run Details The Description first line now names the project, purpose, category, WTFPL license, and author. A new Getting Started section gives a copy-pasteable build-from-source block and gen/check/fetch usage. Problem Statement and Proposed Solution move under a new Rationale heading, the prose kept. A new Design section documents the package layout: the mfer/ library with its committed protobuf code, the internal/cli commands, internal/log and internal/bork, and the cmd/mfer entrypoint. Authors is renamed Author with the canonical link. Getting Started uses go build because the make target that builds the binary runs protoc, which script/bootstrap does not install. Model: opus-4-8 (implementation); opus-5-5 (rebase, rework)	2026-10-04 06:32:07 +02:00
				`@@ -0,0 +1 @@`
				`103901c42b94396aa7ae128fd503ef693a4b7a03b2169481f25fda3d2c254e00 mf.proto`