scan: show each phase as N of M, with progress, elapsed time and ETA, also while it waits (closes #112)

Every scan display names its phase and its place among the five, as
"[2/5] walk", with its progress, elapsed time and ETA. load counts the
records first; the walk estimates its total from the records under the
operands; the content phase adds up the sizes of the matching groups
and says it is searching until the first record returns. Each display
redraws every 100 ms on a terminal and every 5 seconds in plain mode.

On a terminal no line reaches the last column: a line too wide drops
its rate, then its bar. After the terminal is made narrower than the
widest line drawn, the display makes a new library object, whose erase
fits.

Judgement call: load and the content checks draw the bar too, once their totals are known.
Judgement call: the bar is 10 columns wide, not the width the line leaves.

Model: opus-5-5

.claude/settings.json

@@ -1,5 +0,0 @@
-{
-    "worktree": {
-        "bgIsolation": "none"
-    }
-}

.dockerignore

@@ -1,12 +1,79 @@
+# .dockerignore does NOT use .gitignore semantics. Docker matches with
+# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross
+# `/` and an unprefixed pattern is anchored at the context root. Every
+# depth-independent pattern therefore needs `**/`, or `config/.env` and
+# `certs/server.key` still ship while this file reads as solved. Only
+# genuinely root-anchored entries go unprefixed. Never transplant these
+# into .gitignore, where `**/` is wrong.
+#
+# Matching is case-sensitive, so secrets use character ranges rather
+# than an ALL-CAPS twin, which would still miss `Server.Key`.
+#
+# Extend with this repo's own host-built artifacts, written anchored:
+# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
+# deletes the package directory from the context.
+
 # .git is sent without its config. Without a VERSION build argument the
 # stage that compiles runs `git describe --tags --always` on .git, which
 # does not need .git/config; that file can hold a credential, such as a
 # password in a remote URL or the token the CI checkout step stores there.
-.git/config
+# Each submodule keeps a config with the same exposure in its git directory
+# under .git/modules/, nested again for a submodule's own submodules, or in
+# its own .git directory when it keeps one.
+# KNOWN GAP: a submodule whose name has a `config` segment (`config`,
+# `deploy/config`, `config/lib`) loses its whole git directory, because
+# `**/.git/modules/**/config` also matches that segment's directory
+# under .git/modules/. Go's version stamping then fails the build;
+# nothing leaks. Name such a submodule without that segment:
+# `git submodule add --name`.
+**/.git/config
+**/.git/modules/**/config
 
+# Agent scratch: one full checkout of the repo per in-flight agent.
+# Anchored because it occurs once where agents run at the repo root.
+# KNOWN GAP: a repo running agents in subdirectories still ships
+# `services/api/.claude/` and must add its own anchored entry.
 .claude
-.DS_Store
+
-sfdupes
+# Environment files. `*.env` covers bare `.env` and the `prod.env`
-*.log
+# convention. Re-include a committed template with a negation if the
-*.out
+# build needs one: `!docs/example.env`.
-*.test
+**/*.[eE][nN][vV]
+**/.[eE][nN][vV].*
+**/.[eE][nN][vV][rR][cC]
+
+# Private keys and the bundles carrying them. Public certificates
+# (*.crt, *.cer) are deliberately absent: they are legitimate inputs.
+**/*.[pP][eE][mM]
+**/*.[kK][eE][yY]
+**/*.[pP]12
+**/*.[pP][fF][xX]
+**/[iI][dD]_[rR][sS][aA]
+**/[iI][dD]_[dD][sS][aA]
+**/[iI][dD]_[eE][cC][dD][sS][aA]
+**/[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
+**/[iI][dD]_[eE][dD]25519
+**/[iI][dD]_[eE][dD]25519_[sS][kK]
+
+# Dependencies: restored inside the image, never copied in.
+**/node_modules
+
+# OS metadata.
+**/.DS_Store
+**/Thumbs.db
+
+# Editor state: never a build input, and it churns COPY.
+**/*.swp
+**/*.swo
+**/*~
+**/*.bak
+**/.idea
+**/.vscode
+**/*.sublime-*
+
+# This repository's host-built artifacts: the binary `make build` writes,
+# and test binaries, coverage output and logs.
+/sfdupes
+/*.test
+/*.out
+/*.log

.editorconfig

@@ -13,3 +13,6 @@ indent_style = tab
 
 [*.go]
 indent_style = tab
+
+# This repository's own sections, such as one for another language it
+# uses, go below this comment, and a re-vendor keeps them.

.gitea/workflows/check.yml

@@ -1,11 +1,20 @@
 name: check
 on: [push]
+# Free the shared runner: a new push cancels only the same branch's older run.
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
 jobs:
     check:
         runs-on: ubuntu-latest
+        # Free the shared runner from a hung build.
+        timeout-minutes: 20
         steps:
             # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+              # script/cibuild needs no token, so none is left in .git/config.
               with:
+                  persist-credentials: false
+                  # All history and tags, so git describe finds the version tag.
                   fetch-depth: 0
             - run: script/cibuild

.gitignore

@@ -11,25 +11,50 @@ Thumbs.db
 .vscode/
 *.sublime-*
 
+# Agent scratch (worktrees of this repo, created and destroyed by
+# in-flight tooling). Unanchored: .gitignore patterns already match at
+# every depth, so no prefix is wanted here. This is not a .dockerignore
+# entry and must not be given a `**/` prefix on the way into one.
+.claude/
+
 # Node
 node_modules/
 
-# Environment / secrets
+# Secrets. Unanchored like every entry above, so each matches at every
-.env
+# depth. Matching is case-sensitive on Linux, so names use character
-.env.*
+# ranges rather than a lowercase form that misses `Server.Key`.
-*.pem
-*.key
 
-# Go build artifacts
+# Environment files. `*.env` covers bare `.env` and the `prod.env`
+# convention. Only the templates `example.env` and `sample.env` are
+# re-included below. A repository that commits any other template adds
+# its own negation at the end of this file, for example `!.env.example`.
+*.[eE][nN][vV]
+.[eE][nN][vV].*
+.[eE][nN][vV][rR][cC]
+!example.env
+!sample.env
+
+# Private keys and the bundles carrying them.
+*.[pP][eE][mM]
+*.[kK][eE][yY]
+*.[pP]12
+*.[pP][fF][xX]
+[iI][dD]_[rR][sS][aA]
+[iI][dD]_[dD][sS][aA]
+[iI][dD]_[eE][cC][dD][sS][aA]
+[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
+[iI][dD]_[eE][dD]25519
+[iI][dD]_[eE][dD]25519_[sS][kK]
+
+# This repository's own entries, such as its build outputs, go below
+# this comment, and a re-vendor keeps them. Anchor a binary built at the
+# root: `/myapp`, never `myapp`, which also ignores `cmd/myapp/`.
 /sfdupes
-*.test
-*.out
 *.log
+*.out
+*.test
 
-# Local scan data
+# A scan database lists every path it scanned.
 *.sqlite
 *.sqlite-shm
 *.sqlite-wal
-
-# Agent worktrees
-.claude/worktrees/

.golangci.yml

@@ -10,14 +10,23 @@ run:
 
 linters:
   default: all
+  enable:
+    # Successor to the deprecated gomodguard. Named explicitly, rather than
+    # left to `default: all`, because it carries the module policy below.
+    - gomodguard_v2
   disable:
     # Genuinely incompatible with project patterns
     - exhaustruct      # Requires all struct fields
-    - depguard         # Dependency allow/block lists
+    - exhaustruct_v5   # Requires all struct fields (successor to exhaustruct)
     - godot            # Requires comments to end with periods
-    - wsl              # Deprecated, replaced by wsl_v5
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go
+    # Deprecated: the warning is attached to the old name, so it is
+    # silenced by disabling that name, not by enabling the successor.
+    - wsl              # Deprecated, replaced by wsl_v5
+    - gomodguard       # Deprecated, replaced by gomodguard_v2
+    # Misses findings at random in v2.14.0; back once a pinned release fixes it
+    - canonicalheader
   settings:
     lll:
       line-length: 88
@@ -28,6 +37,64 @@ linters:
       max-complexity: 15
     dupl:
       threshold: 100
+    depguard:
+      # Test-support code must not be compiled into the shipped binary. A
+      # test-support package exists to hand a test privileges the program
+      # itself must never have, so a file that is not a test must not import
+      # one. Test files, and the files inside a package whose directory name
+      # ends in `test`, are where that code belongs, and are exempt.
+      #
+      # The deny list below is the one part of this file a repository is
+      # expected to extend, and the only part it may. depguard matches an
+      # import path against a list of prefixes, so it cannot be told "any path
+      # whose last segment ends in test"; a repository's own test-support
+      # packages have to be named here one at a time, by full import path,
+      # under a module path that differs from repository to repository. Add
+      # them; change nothing else.
+      rules:
+        test-support:
+          list-mode: lax
+          files:
+            - "$all"
+            - "!$test"
+            - "!**/*test/**"
+          deny:
+            - pkg: net/http/httptest
+              desc: >-
+                Test-support code belongs in test files and in packages whose
+                directory name ends in test, not in the shipped binary.
+    # Only decisions already recorded in the Go package defaults are
+    # listed here. Every entry matches the module path exactly.
+    gomodguard_v2:
+      blocked:
+        - module: github.com/rs/zerolog
+          recommendations:
+            - log/slog
+          reason: "Structured logging is stdlib log/slog."
+        # One entry per pre-fork module path, because the later releases
+        # are separate paths. A prefix match would be shorter but would
+        # also reach github.com/go-redis/redismock, the test double for
+        # the successor these entries recommend.
+        - module: github.com/go-redis/redis
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v7
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v8
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/sergi/go-diff
+          recommendations:
+            - github.com/aymanbagabas/go-udiff
+          reason: "No unified diff output; use go-udiff."
+        - module: github.com/hexops/gotextdiff
+          recommendations:
+            - github.com/aymanbagabas/go-udiff
+          reason: "Unmaintained fork; use go-udiff."
 
 issues:
   max-issues-per-linter: 0

.prettierignore

@@ -0,0 +1,2 @@
+node_modules/
+yarn.lock

.prettierrc

@@ -0,0 +1,4 @@
+{
+    "tabWidth": 4,
+    "proseWrap": "always"
+}

Dockerfile

@@ -1,138 +1,80 @@
-# Lint stage — fast feedback on formatting and lint issues
+# Every stage declares ARG CACHEBUST first: script/ passes a new value
-# golangci/golangci-lint:v2.12.2, 2026-08-07
+# on every build, which reruns every RUN step after it. The steps that
-FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS lint
+# compile mount Go's build cache, which survives from build to build.
+
+# Lint phase, built alone by script/lint. The tools are invoked directly
+# rather than through `make lint`, which runs docker itself and so cannot
+# run inside a build step.
+# golangci/golangci-lint:v2.14.0, 2026-10-07
+FROM golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f AS lint
+ARG CACHEBUST
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 
-# Cache-buster for the gate layers, and only for them. Docker
+# The gofmt half of `make fmt-check`. gofmt's output is assigned to a
-# invalidates COPY only when the copied content changes, so on an
+# variable first so that its own exit status, as when it cannot parse a
-# unchanged tree the gates below would be served from cache and the
+# file, still fails the step.
-# build would exit 0 having run nothing. script/cibuild and
+RUN files="$(gofmt -s -l .)" && \
-# script/docker pass a fresh CHECK_EPOCH on every invocation.
+    if [ -n "$files" ]; then \
-#
+        echo "gofmt: files not formatted:" >&2; echo "$files" >&2; exit 1; \
-# Two properties this depends on. ARG is per-stage, so the build stage
+    fi
-# below declares it again; one declaration here would leave that
-# stage's gate cacheable. And each gate RUN must reference the value,
-# because BuildKit hashes the expanded command: a declared but
-# unreferenced ARG invalidates nothing.
-#
-# It sits below the dependency layers deliberately. Everything above it
-# (the pinned base image, go mod download) keeps its cache; only the
-# gates go cold.
-ARG CHECK_EPOCH
 
-# The linter is invoked directly here, not through `make lint`. That
+# Validates .golangci.yml against the schema the pinned binary embeds.
-# target now runs `docker build -f Dockerfile.lint`, and a docker build
+RUN golangci-lint config verify --config .golangci.yml
-# cannot run a docker build: routing the gate through make would mean
+RUN --mount=type=cache,target=/root/.cache/go-build \
-# nesting docker inside this image. Same reason `make check` is gone
-# from the build stage below. `make fmt-check` stays as it is — it is a
-# gate, not the aggregate, and it shells out to nothing.
-RUN echo "gate fmt-check, epoch ${CHECK_EPOCH}" && make fmt-check
-
-# The FROM above and the one in Dockerfile.lint pin the same linter
-# twice, and nothing else keeps them in sync; this fails the build when
-# they disagree. See the script for why it restates neither pin.
-RUN echo "gate lint-image-pin, epoch ${CHECK_EPOCH}" && \
-    script/verify-lint-image-pin
-
-# Same config-schema check Dockerfile.lint runs, kept here so this build
-# gates on exactly what script/lint gates on. It validates against a
-# schema the pinned binary embeds, so it needs no network.
-RUN echo "gate config verify, epoch ${CHECK_EPOCH}" && \
-    golangci-lint config verify --config .golangci.yml
-
-RUN echo "gate lint, epoch ${CHECK_EPOCH}" && \
     golangci-lint run --config .golangci.yml ./...
 
-# Build stage
+# Test phase, built alone by script/test. -race needs cgo and so a C
+# compiler, which the Debian Go image ships and the alpine one does not.
+# -count=1 because the mounted cache also holds test results, which go
+# test would otherwise replay.
+#
+# The tests run as nobody: several of them make a file unreadable and
+# expect reading it to fail, and root reads it anyway. nobody has no home
+# directory, so HOME is /tmp, and Go keeps its build cache in
+# /tmp/.cache/go-build. That is where the cache is mounted, owned by
+# nobody (65534) so the tests can write to it.
+# golang:1.25-trixie, 2026-10-04
+FROM golang@sha256:2c4c60ef415fbfa5e90300722293bef36c5e63fae17570ce18f580af933dbd73 AS test
+ARG CACHEBUST
+USER nobody
+ENV HOME=/tmp
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN --mount=type=cache,target=/tmp/.cache/go-build,uid=65534,gid=65534 \
+    go test -count=1 -timeout 90s -race -cover ./... || \
+    { echo "--- Rerunning with -v for details ---"; \
+      go test -count=1 -timeout 90s -race -v ./...; exit 1; }
+
+# Build stage. Nothing is wanted from either phase above; the copies are
+# what make BuildKit build them first, so this stage cannot run unless
+# lint and test passed.
 # golang:1.25-alpine, 2026-07-23
 FROM golang@sha256:56961d79ea8129efddcc0b8643fd8a5416b4e6228cfd477e3fd61deb2672c587 AS builder
-
+ARG CACHEBUST
-# We never build or run as root. Create an unprivileged user and point
-# HOME and the build cache at its home so go build and go test can write
-# it when we drop to it below. $GOPATH/bin is deliberately not on PATH:
-# script/bootstrap no longer `go install`s anything (the linter runs
-# from a pinned image, never from a host install), so nothing lands
-# there and adding it would only widen what this image resolves.
-#
-# The module cache is kept outside that home, at the base image's
-# default /go/pkg/mod, and belongs to root: script/bootstrap fills it as
-# root. Do not move it into the home and hand it over with `chown -R`:
-# that walks every file in it, which took from about 80 s to over ten
-# minutes on a shared host, depending on load.
-RUN adduser -D -u 1000 builder
-ENV HOME=/home/builder
-ENV GOPATH=/home/builder/go
-ENV GOMODCACHE=/go/pkg/mod
-ENV GOCACHE=/home/builder/.cache/go-build
-
-WORKDIR /src
-
-# No-op file copy whose only purpose is the build-graph edge: it is what
-# makes this stage depend on the lint stage, and so what forces BuildKit
-# to finish fmt-check, the pin guard and lint before compilation and
-# tests start. Remove it and the fail-fast design dies silently — the
-# build stops gating on lint and still exits 0. It replaces a copy of
-# the linter binary itself, which is no longer wanted here: nothing in
-# this stage runs the linter, because `make lint` is now a docker build
-# and a docker build cannot run inside one.
 COPY --from=lint /src/go.sum /dev/null
-
+COPY --from=test /src/go.sum /dev/null
-# Install development prerequisites the same way a developer does,
+RUN apk add --no-cache git make
-# rather than duplicating the installs inline. Only script/ and the
+# A tar-stream context keeps the sender's file owners, which git refuses.
-# dependency manifests are copied first, nothing else, so this layer
+RUN git config --system --add safe.directory /src
-# stays cached until the scripts or the dependencies change — bootstrap
+WORKDIR /src
-# ends in `go mod download`, which is why there is no separate
-# invocation of it here.
-COPY script/ script/
 COPY go.mod go.sum ./
-RUN script/bootstrap
+RUN go mod download
-
+COPY . .
-# Hand builder only what it writes to, without walking the module cache.
-# This layer stays cached with bootstrap.
-# - /src itself: make build writes the binary into it, and git refuses
-#   a repository whose top directory belongs to another user.
-# - the module cache's cache/download directory itself, not what is in
-#   it: Go only reads the downloaded modules, but make build saves its
-#   lookup of this module's own version from git there, in a new
-#   directory named after the module path.
-# - builder's home: the go commands bootstrap ran as root left Go's
-#   telemetry files there, a few small files.
-RUN chown builder:builder /src /go/pkg/mod/cache/download && \
-    chown -R builder:builder /home/builder
-
-# The sources are handed to builder as they are copied, so no layer has
-# to walk them. Then drop root before running any checks or builds.
-COPY --chown=builder:builder . .
-USER builder
-
-# Fail the build unless the branch is green. Runs as non-root so the
-# permission-denied test paths are exercised legitimately (root would
-# bypass the chmod(0) the tests rely on).
-#
-# The gates are the individual targets, not `make check`: that aggregate
-# runs `script/lint`, which is now a docker build, and nothing inside an
-# image build may shell out to docker. Lint is not skipped by this — it
-# ran in the lint stage above, which this stage's COPY --from makes a
-# prerequisite. `make`, not the scripts directly, because the Makefile's
-# `export CGO_ENABLED = 0` applies only to what it invokes.
-#
-# Second per-stage declaration of the gate cache-buster; see the lint
-# stage above for why one is not enough. It is placed after USER so the
-# drop to the unprivileged user still happens before the checks run.
-ARG CHECK_EPOCH
-RUN echo "gate test, epoch ${CHECK_EPOCH}" && make test
-RUN echo "gate fmt-check, epoch ${CHECK_EPOCH}" && make fmt-check
 
 # The version stamped into the binary: the VERSION build argument when
 # one is given, otherwise `git describe --tags --always` of the .git in
-# the build context (git is installed by script/bootstrap above). A
+# the build context. A context that carries .git and still yields no
-# context that carries .git and still yields no version fails the build;
+# version fails the build; with neither, as from a source tarball, it is
-# with neither, as from a source tarball, it is "dev".
+# "dev". `make build` rather than `go build`, so the image and a host
+# build share one compile recipe, cgo disabled included.
 ARG VERSION
-RUN version="${VERSION:-$(git describe --tags --always || echo dev)}"; \
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    version="${VERSION:-$(git describe --tags --always || echo dev)}"; \
     if [ -e .git ] && { [ -z "$version" ] || [ "$version" = dev ] || \
         [ "$version" = unknown ]; }; then \
         echo "no version could be derived although the build context carries .git" >&2; \
@@ -140,9 +82,11 @@ RUN version="${VERSION:-$(git describe --tags --always || echo dev)}"; \
     fi; \
     make build VERSION="$version"
 
-# Runtime stage
+# Runtime stage, and the last one: a plain `docker build .` builds this
+# stage's chain and nothing else.
 # alpine:3.22, 2026-07-23
 FROM alpine@sha256:14358309a308569c32bdc37e2e0e9694be33a9d99e68afb0f5ff33cc1f695dce
+ARG CACHEBUST
 
 COPY --from=builder /src/sfdupes /usr/local/bin/sfdupes
 

Dockerfile.lint

@@ -1,59 +0,0 @@
-# Lint-only image: this is how the linter runs, everywhere. The repo is
-# COPYed into the pinned golangci-lint image and the linter runs as a
-# build step, so a successful build IS a clean lint. golangci-lint is
-# never installed on a host — one toolchain, pinned by digest, identical
-# on a laptop and in CI — and this works even when the docker daemon is
-# remote and bind mounts are impossible.
-#
-# script/lint builds this file. It is a separate image from the lint
-# stage of the main Dockerfile because script/lint must not depend on
-# the rest of that build; the two FROM lines are kept identical by
-# script/verify-lint-image-pin, run as a gate below.
-# golangci/golangci-lint:v2.12.2, 2026-08-07
-FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240
-
-WORKDIR /src
-
-# Dependency layers first, so they stay cached across lint runs.
-COPY go.mod go.sum ./
-RUN go mod download
-
-COPY . .
-
-# Cache-buster for the gate layers, and only for them. Caching of the
-# lint run is waived by ruling: COPY is invalidated only by changed
-# content, so on an unchanged tree the gates below would be served from
-# cache and this build would exit 0 in under a second having run no
-# linter at all. That exact false green has bitten this repo twice
-# already (#32, #39). script/lint passes a fresh value on every
-# invocation.
-#
-# Each gate RUN must reference the value, because BuildKit hashes the
-# expanded command and not the ARG declaration: a declared but
-# unreferenced ARG invalidates nothing. The ARG sits below the
-# dependency layers deliberately — everything above it keeps its cache,
-# only the gates go cold.
-ARG CHECK_EPOCH
-
-# The linter version is pinned in two places, here and in the main
-# Dockerfile's lint stage. Nothing else keeps them in sync, so a
-# half-applied bump is a build failure; see the script.
-RUN echo "gate lint-image-pin, epoch ${CHECK_EPOCH}" && \
-    script/verify-lint-image-pin
-
-# Validates .golangci.yml against golangci-lint's JSON schema. The
-# concern about this step was that it fetches that schema over a live,
-# unpinned HTTPS call; measured on the pinned image, it does not. The
-# binary carries the schema for its own version, so under
-# `--network none` this both passes on a valid config and still rejects
-# an invalid one with the jsonschema error. That holds for the gate
-# steps generally — none of them makes a network call — but not for
-# this build as a whole: `go mod download` above needs the network on a
-# cold cache, and under `--network none` a first build fails there
-# before reaching any gate. That layer stays cached, so only a warm
-# cache lints offline, until go.mod or go.sum changes.
-RUN echo "gate config verify, epoch ${CHECK_EPOCH}" && \
-    golangci-lint config verify --config .golangci.yml
-
-RUN echo "gate lint, epoch ${CHECK_EPOCH}" && \
-    golangci-lint run --config .golangci.yml ./...

REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-07-06
+last_modified: 2026-10-15
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -54,21 +54,37 @@ style conventions are in separate documents:
   `cibuild`. `script/bootstrap` installs all dependencies idempotently and
   assumes nothing is present: base tools come from nix, apt, brew, or apk
   (detected in that order; apt runs noninteractive). For node it uses the
-  installed node if present; otherwise it installs a PINNED node version via
+  installed node only when its major version is the pinned one; otherwise (node
-  nvm, first installing nvm itself if missing — from a hash-verified GitHub
+  missing, or another major, such as the node 24 the CI runner image ships) it
-  release archive (never `curl | sh`), with bash installed as an explicit
+  installs the PINNED node version via nvm and installs yarn and the packages
-  prerequisite since nvm requires bash. yarn is then pinned via
+  under it. nvm itself is installed first if missing, from a hash-verified
-  `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
+  GitHub release archive (never `curl | sh`), with bash installed as an explicit
-  always exact versions. `script/cibuild` runs the CI build: it changes to the
+  prerequisite since nvm requires bash. Only the major version is compared
-  repo root and runs `docker build .`; the Gitea workflow calls it. Four further
+  because the `Dockerfile` stages start from a node image whose exact version is
-  scripts are our own extensions to the standard: `script/check` runs
+  not the pin, and nvm cannot install a prebuilt node on alpine. yarn is pinned
-  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
+  via `corepack prepare yarn@<version> --activate`. Never install "latest" or
-  what the git pre-commit hook runs, and it calls `script/check`;
+  "lts"; always exact versions. `script/cibuild` runs the CI build: it changes
-  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
+  to the repo root, runs `script/bootstrap`, runs `script/check`, and builds the
-  target shims to it); and `script/projectname` (literally that filename) simply
+  image with the version; the Gitea workflow calls it. **`script/cibuild` runs
-  outputs the project's name. Scripts that need the name call
+  `script/bootstrap` first**, because the workflow checks out the repo and runs
-  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
+  nothing else, while `script/fmt-check` runs the formatter on the host: on a
-  so those scripts stay byte-identical across all repos. Repo-type-specific
+  pristine checkout with nothing installed the run dies there, after the
+  containerised gates have passed. **The bootstrap alone is not enough**: when
+  `script/bootstrap` installs node and yarn under nvm it leaves neither on the
+  `PATH` of the shell that called it, so a bare `yarn` either exits 127 or runs
+  under another node. The host entrypoints that need yarn — `script/fmt` and
+  `script/fmt-check` — therefore use the same test as `script/bootstrap`: when
+  the node on `PATH` has the pinned major version they run the `yarn` on `PATH`,
+  and otherwise they load nvm through `$HOME/.nvm/nvm.sh` and run yarn under the
+  pinned node. A runner carrying nothing but docker and git then gets through
+  `script/check`. Four further scripts are our own extensions to the standard:
+  `script/check` runs `script/test`, `script/lint` and `script/fmt-check`;
+  `script/precommit` is what the git pre-commit hook runs, and it calls
+  `script/check`; `script/install-precommit` installs the git pre-commit hook
+  (the `make hooks` target shims to it); and `script/projectname` (literally
+  that filename) simply outputs the project's name. Scripts that need the name
+  call `script/projectname` — e.g. `script/docker` assembles its image tag from
+  it — so those scripts stay byte-identical across all repos. Repo-type-specific
   pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
   `script/precommit`, not in the hook itself. Model scripts are at
   `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
@@ -89,87 +105,257 @@ style conventions are in separate documents:
   contributor should be able to understand the entire development workflow by
   reading the Makefile.
 
-- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
+- Every repo should have a `Dockerfile`, and it carries the repo's gates: a
-  as a build step so the build fails if the branch is not green. For non-server
+  `lint` phase and a `test` phase, with the final stage depending on both so the
-  repos, the Dockerfile should bring up a development environment and run
+  image cannot be built unless they pass. For non-server repos the final stage
-  `make check`. For server repos, `make check` should run as an early build
+  brings up a development environment; for server repos it is the runtime image.
-  stage before the final image is assembled. Dockerfiles install development
+  The gate phases and the build stage start from their pinned base images and
-  prerequisites by running `script/bootstrap` rather than duplicating installs
+  install what those images lack either inline, as the canonical Go `Dockerfile`
-  inline; COPY `script/` and the dependency manifests (`package.json` +
+  below does for `git`, or by running `script/bootstrap`, as the `prompts`
-  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
+  repo's own `Dockerfile` does for its yarn packages. The development
-  layer stays cached until dependencies change.
+  environment stage installs development prerequisites by running
+  `script/bootstrap` rather than duplicating its installs inline. A stage that
+  runs `script/bootstrap` COPYs `script/` and the dependency manifests
+  (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it.
 
-- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
+- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
-  repos use a multistage build where linting runs in an independent stage based
+  no separate lint file. `script/lint` and `script/test` each build one phase
-  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
+  and nothing else:
-  `make fmt-check` and `make lint` before the full build begins. The build stage
-  then declares an explicit dependency on the lint stage via
-  `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
-  linting before proceeding to compilation and tests. This ensures lint failures
-  surface in seconds rather than minutes, without blocking on dependency
-  download or compilation in the build stage.
 
-    The standard pattern for a Go repo Dockerfile is:
+    ```sh
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
+        --target lint --output type=cacheonly .
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
+        --target test --output type=cacheonly .
+    ```
+
+    **A stage that is not the last one in the file is built only when the final
+    stage's chain depends on it, or when `--target` names it.** That is why the
+    two gates are always invoked by name here, and why the final stage carries a
+    `COPY --from=` of a harmless file from each of them: without that edge a
+    plain `docker build .` builds the last stage alone and exits 0 having linted
+    and tested nothing.
+
+    **The gate builds write no image.** With `--output type=cacheonly` the phase
+    runs and a failing step fails the build, but the result is not exported.
+    Nothing uses those images, and writing one out is slow: a Go test phase's
+    image holds the toolchain. A build given neither `--output` nor `-t` writes
+    an untagged image and leaves it dangling, on every developer host and every
+    CI runner. `script/cibuild` and `script/docker` build the image that ships
+    and tag it, so each build replaces the previous image; each assigns the tag
+    on its own line before the build, so `set -e` stops it where
+    `script/projectname` fails.
+
+    Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
+    `eslint`, `prettier` — never through `make lint` or `script/test`, which are
+    themselves a `docker build` and would recurse into a daemon that does not
+    exist in a build step. Formatting is the exception and stays on the host:
+    `script/fmt` writes the working tree, and `script/fmt-check` is its
+    read-only twin.
+
+    **No lint verdict may come from a host invocation of the linter.** On a
+    shared host golangci-lint reads a result cache keyed on file content rather
+    than location, so a second checkout of the same content is served the first
+    one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
+    exit non-zero with `parallel golangci-lint is running` — a status a caller
+    cannot tell from real findings. Both have produced wrong verdicts in this
+    org, in both directions. A container has its own golangci-lint cache, its
+    own `TMPDIR` and a digest-pinned binary, so neither is reachable.
+
+- **Any build that runs checks is given a new `CACHEBUST` value.** Docker
+  invalidates a `COPY` layer only when the copied content changes, so on an
+  unchanged tree the check `RUN` is served from cache, nothing executes, and the
+  build still exits 0. Every `docker build` in `script/` therefore passes
+  `--build-arg CACHEBUST="$(date +%s)-$$"`, the time and the script's process
+  id, so no two builds share a value, not even the three in one
+  `script/cibuild`. `script/lint`, `script/test`, `script/cibuild` and
+  `script/docker` are the four, and there is no fifth — `script/check` runs the
+  two gate phases and `script/fmt-check`, and builds no image of its own. Every
+  stage of the `Dockerfile` declares `ARG CACHEBUST` as its first line after
+  `FROM`, and a new value reruns every `RUN` step after that line; `COPY` steps
+  are compared by content and need nothing. A stage without the `ARG` line is
+  served from cache on an unchanged tree, so a repository re-vendors the scripts
+  and adds the `ARG` lines in one commit. The scripts do not pass `--no-cache`:
+  it reruns every step too, but it also empties every cache mount, and Go's
+  build cache, which the canonical Go `Dockerfile` below mounts so that compiled
+  packages survive between check builds, would start empty every time. A bare
+  `docker build .` is not evidence that anything ran: a sub-second build
+  reporting success is a cache hit, not a result. Never invalidate by pruning —
+  `docker builder prune` and friends destroy a build cache shared with every
+  other build on the host. When a check is added or changed, prove it works by
+  planting a defect it must catch and watching the run fail on it, then revert
+  the defect. A green run alone shows neither that the check ran nor that it
+  covers what it should.
+
+- **The gate phases are separate stages, and the build stage depends on both.**
+  The lint phase is based on the `golangci/golangci-lint` image (pinned by
+  hash), so lint failures surface in seconds rather than after a full compile,
+  and the test phase is based on the Debian Go image. The canonical Go repo
+  `Dockerfile`:
 
     ```dockerfile
-    # Lint stage — fast feedback on formatting and lint issues
+    # Every stage declares ARG CACHEBUST first: script/ passes a new value
+    # on every build, which reruns every RUN step after it. The steps that
+    # compile mount Go's build cache, which survives from build to build.
+
+    # Lint phase
     # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
     FROM golangci/golangci-lint@sha256:... AS lint
+    ARG CACHEBUST
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make fmt-check
+    RUN --mount=type=cache,target=/root/.cache/go-build \
-    RUN make lint
+        golangci-lint run --config .golangci.yml ./...
 
-    # Build stage
+    # Test phase. -race needs cgo and so a C compiler, which the Debian Go
+    # image ships and the alpine one does not. -count=1 because the mounted
+    # cache also holds test results, which go test would otherwise replay.
+    # golang:1.x, YYYY-MM-DD
+    FROM golang@sha256:... AS test
+    ARG CACHEBUST
+    WORKDIR /src
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
+    RUN --mount=type=cache,target=/root/.cache/go-build \
+        go test -count=1 -timeout 90s -race -cover ./... || \
+        { echo "--- Rerunning with -v for details ---"; \
+          go test -count=1 -timeout 90s -race -v ./...; exit 1; }
+
+    # Build stage. Nothing is wanted from either phase above; the copies
+    # are what make BuildKit build them first, so this stage cannot run
+    # unless lint and test passed.
     # golang:1.x-alpine, YYYY-MM-DD
     FROM golang@sha256:... AS builder
-    WORKDIR /src
+    ARG CACHEBUST
-
-    # Force BuildKit to run the lint stage before proceeding
     COPY --from=lint /src/go.sum /dev/null
-
+    COPY --from=test /src/go.sum /dev/null
+    RUN apk add --no-cache git
+    # A tar-stream context keeps the sender's file owners, which git refuses.
+    RUN git config --system --add safe.directory /src
+    WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make test
 
-    ARG VERSION=dev
+    # The VERSION build arg when one is given, otherwise
-    RUN CGO_ENABLED=0 go build -trimpath \
+    # `git describe --tags --always` on the .git in the build context. With
-        -ldflags="-s -w -X main.Version=${VERSION}" \
+    # .git present, a version that is still empty, dev or unknown fails the
-        -o /app ./cmd/app/
+    # build: git is missing or could not read the checkout.
+    ARG VERSION
+    RUN --mount=type=cache,target=/root/.cache/go-build \
+        VERSION="${VERSION:-$(git describe --tags --always)}"; \
+        if [ -e .git ]; then \
+            case "$VERSION" in ""|dev|unknown) \
+                echo "version is '$VERSION' although .git is present" >&2; \
+                exit 1 ;; \
+            esac; \
+        fi; \
+        CGO_ENABLED=0 go build -trimpath \
+            -ldflags="-s -w -X main.Version=${VERSION}" \
+            -o /app ./cmd/app/
 
-    # Runtime stage
+    # Runtime stage, and the last one
     FROM alpine@sha256:...
+    ARG CACHEBUST
     COPY --from=builder /app /usr/local/bin/app
     ENTRYPOINT ["app"]
     ```
 
     Key points:
-    - The lint stage uses the `golangci/golangci-lint` image directly (it
+    - The lint phase uses the `golangci/golangci-lint` image directly (it has
-      includes both Go and the linter), so there is no need to install the
+      both Go and the linter), so nothing needs installing.
-      linter separately.
+    - `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
-    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
+      purpose is the ordering edge. BuildKit runs stages in parallel by default,
-      a stage dependency. BuildKit runs stages in parallel by default; without
+      and a stage nothing depends on is not built at all, so without these two
-      this line, the build stage would not wait for lint to finish and a lint
+      lines a red gate would not fail the build.
-      failure might not fail the overall build.
+    - Keep the runtime stage last, and if you add a stage after it, give it the
+      same two copies. A plain `docker build .` builds the last stage's chain
+      and nothing else.
+    - Only Go's build cache is mounted (`/root/.cache/go-build`, where Go keeps
+      it for root), and only on the steps that compile: `golangci-lint run`,
+      both `go test` runs and `go build`. It keeps compiled packages between
+      check builds, and Go reuses one only when all its inputs are unchanged, so
+      it saves the compile without skipping a check. Nothing else is kept:
+      golangci-lint's own cache would replay stored findings in place of a lint
+      run, and Go builds from whatever files a kept module cache holds without
+      checking them again (only `go mod verify` does), so a file changed there
+      would go unnoticed. Go's build cache also holds test results, which is why
+      both `go test` runs carry `-count=1`.
     - If the project uses `//go:embed` directives that reference build artifacts
-      (e.g. a web frontend compiled in a separate stage), the lint stage must
+      (e.g. a web frontend compiled in a separate stage), the lint phase must
       create placeholder files so the embed directives resolve. Example:
       `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
-      The lint stage should not depend on the actual build output — it exists to
+    - If the project requires CGO or system libraries for linting, install them
-      fail fast.
+      in the lint phase. The `golangci/golangci-lint` image is Debian-based and
-    - If the project requires CGO or system libraries for linting (e.g.
+      has no `apk`, so install with `apt-get` under the Debian package name
-      `vips-dev`), install them in the lint stage with `apk add`.
+      (`libvips-dev`, where alpine says `vips-dev`), and delete the package
-    - The build stage runs `make test` after compilation setup. Tests run in the
+      lists in the same `RUN`, so the layer does not keep them:
-      build stage, not the lint stage, because they may require compiled
+
-      artifacts or heavier dependencies.
+        ```dockerfile
+        RUN apt-get update \
+            && apt-get install -y --no-install-recommends libvips-dev \
+            && rm -rf /var/lib/apt/lists/*
+        ```
+
+    - `.dockerignore` lets `.git` into the build context. It keeps out every git
+      `config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): the
+      repository's own, each submodule's under `.git/modules/`, and that of a
+      submodule keeping its own `.git` directory. `git describe` does not need
+      them, and each can hold a credential: a password in a remote URL, or the
+      token the CI checkout step stores there. A submodule whose name has a
+      `config` segment (`config`, `deploy/config`, `config/lib`) loses its whole
+      git directory to `**/.git/modules/**/config`, and Go's version stamping
+      then fails the build: give it a name without that segment
+      (`git submodule add --name`). The stage that compiles has `git` (the
+      Debian Go image has it; an alpine one needs `apk add --no-cache git`) and
+      takes the version from the `VERSION` build argument when one is given,
+      otherwise from `git describe --tags --always`. That gives the tag on a
+      tagged commit; on a later commit, the tag, the number of commits since it
+      and the short commit (`v1.2.3-4-gabc1234`); and the short commit when no
+      tag is reachable. The stage that compiles also marks its working directory
+      safe for git (`git config --system --add safe.directory /src`): a context
+      sent as a tar stream keeps the sender's file owners, and git refuses a
+      checkout owned by another user, so the version would come out empty.
+      `ARG VERSION` has no default, and the build fails if the context carries
+      `.git` and the version still comes out empty, `dev` or `unknown`. A plain
+      `docker build .` with no build arguments must succeed; a Dockerfile that
+      refuses an empty build argument drops that refusal and keeps the argument.
+      A checkout whose `.git` is a file (a linked worktree, or a repository
+      checked out as a submodule) is the exception: that file points to a git
+      directory outside the build context, so the build cannot read the version
+      and a plain `docker build .` fails; pass the version with
+      `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already
+      do.
 
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `script/cibuild` (which runs `docker build .`) on push. Since the
+  runs `script/cibuild` on push, and checks out the repo as its only other step,
-  Dockerfile already runs `make check`, a successful build implies all checks
+  with `persist-credentials: false`: `script/cibuild` needs no token, and
-  pass.
+  without it the checkout leaves the job's token in `.git/config` for every
+  later step. The checkout step also sets `fetch-depth: 0`, which fetches the
+  tags `git describe` needs: by default it clones shallow with no tags, and a
+  tagged repository's CI build would stamp a bare short commit id. The
+  workflow's `concurrency` block groups runs by workflow and branch
+  (`${{ github.workflow }}-${{ github.ref }}`) with `cancel-in-progress: true`,
+  so a new push cancels the older run on the same branch, queued or running, and
+  no other: runs for replaced commits do not hold up the shared runner.
+  `script/cibuild` bootstraps, runs the gate phases, and then builds the image,
+  so a successful run means every check passed; a bare `docker build .` does not
+  carry the same guarantee, because its gate phases may come from the cache. The
+  image build gets a `CACHEBUST` value of its own and so runs the gate phases a
+  second time. That is the price of the rule above, and it is worth paying: the
+  image that ships is built from a run of its own gates rather than from a cache
+  entry. The `check` job sets `timeout-minutes: 20`, so a hung build frees the
+  shared runner after 20 minutes. That allows for the three Docker builds
+  described above (the test phase, the lint phase, then the image), each held to
+  the 5-minute Docker build limit below, plus the bootstrap. A separate workflow
+  limited to `main` by a `branches` list under `on: push` cannot be checked by
+  review: to try a change to it, add the feature branch to that list and push,
+  then remove the branch from the list again before merging. Keep any job in it
+  that publishes behind `if: github.ref_name == 'main'`, so the run from the
+  feature branch publishes nothing.
 
 - Use platform-standard formatters: `black` for Python, `prettier` for
   JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -189,14 +375,21 @@ style conventions are in separate documents:
   module under test to verify it compiles/parses. There is no excuse for
   `make test` to be a no-op.
 
-- `make test` must complete in under 20 seconds. Add a 30-second timeout in the
+- `make test` must complete in under 60 seconds. That is the hard cap, and a
-  Makefile.
+  suite that exceeds it fails. Under 20 seconds is the target. A suite between
+  20 and 60 seconds is still green, but the overage must be filed as an
+  improvement bug against that repo. Add a 90-second timeout to the test
+  invocation (`go test -timeout 90s`). The backstop deliberately sits above the
+  hard cap so that it catches a genuinely hung test rather than a merely slow
+  one.
 
-- **`make test` should use the conditional verbose rerun pattern.** Run tests
+- **The test command should use the conditional verbose rerun pattern.** Run
-  without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
+  tests without `-v` (verbose) first. If tests fail, automatically rerun with
-  show full output. This keeps CI logs and `docker build` output clean on
+  `-v` to show full output. This keeps CI logs and `docker build` output clean
-  success (just package/suite summaries) while providing full diagnostic detail
+  on success (just package/suite summaries) while providing full diagnostic
-  on failure (every test case, every assertion). The general shell pattern:
+  detail on failure (every test case, every assertion). The command lives in the
+  `test` phase of the `Dockerfile`, since `script/test` builds that phase; the
+  Makefile form below is the same pattern for any repo-local invocation:
 
     ```makefile
     test:
@@ -209,11 +402,25 @@ style conventions are in separate documents:
 
     ```makefile
     test:
-    	@go test -timeout 30s -race -cover ./... || \
+    	@go test -count=1 -timeout 90s -race -cover ./... || \
     		{ echo "--- Rerunning with -v for details ---"; \
-    		  go test -timeout 30s -race -v ./...; exit 1; }
+    		  go test -count=1 -timeout 90s -race -v ./...; exit 1; }
     ```
 
+    `-count=1` is required on both invocations: it defeats Go's test _result_
+    cache, so neither run can report a stored pass in place of running the
+    tests. It leaves the build cache alone, so it costs the runtime of the suite
+    and no recompilation.
+
+    That cache is Go's own, separate from Docker's layer cache. Go stores a
+    passing result in its cache directory (`GOCACHE`), and when the same tests
+    run again on unchanged code it prints that result, marked `(cached)`,
+    without running them. The directory lasts from one run to the next on a
+    developer's machine, where this target runs, and in the `test` phase of the
+    `Dockerfile`, which mounts it to keep compiled packages between check
+    builds, so the phase's `go test` runs carry `-count=1` too. A new
+    `CACHEBUST` value (above) is what makes that step run on an unchanged tree.
+
     Python example:
 
     ```makefile
@@ -239,10 +446,89 @@ style conventions are in separate documents:
   must be in `.gitignore`. No exceptions.
 
 - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
-  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
+  editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
-  Fetch the standard `.gitignore` from
+  `node_modules/`, and the repo's own build outputs. Fetch the standard
+  `.gitignore` from
   `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
-  a new repo.
+  a new repo. A repo's `.gitignore` is the standard file followed by the repo's
+  own entries, such as its binaries; a re-vendor replaces the standard part and
+  keeps those entries. These patterns are written to `.gitignore`'s own
+  semantics, in which an unanchored pattern already matches at every depth; they
+  are not a `.dockerignore` and must not be transplanted into one unmodified.
+
+- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
+  across unmodified leaves secrets in the build context.** Docker matches with
+  `moby/patternmatcher`: `filepath.Match` semantics plus a `**` extension, so
+  `*` does not cross `/` and a pattern without a leading `**/` is anchored at
+  the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
+  therefore excludes only the copies at the repository root, while `config/.env`
+  and `certs/server.key` still reach the context and can land in an image layer
+  — which is more dangerous than a short file with no secret patterns at all,
+  because it reads as solved and stops anyone looking. Give every
+  depth-independent pattern the `**/` prefix and leave only genuinely
+  root-anchored entries unprefixed: `.claude`, and the repo's own host-built
+  binary, written `/myapp` and never `**/myapp`, which would also match
+  `cmd/myapp/` and delete the package directory from the context. Matching is
+  case-sensitive, and an ALL-CAPS twin per pattern still misses `Server.Key`, so
+  secret names use character ranges — `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`,
+  and likewise for `.envrc` and the extensionless SSH keys. Where such a pattern
+  also catches something the build needs, re-include it with a negation
+  (`!docs/example.env`); deleting the pattern reopens the exposure for every
+  other file it covers. Fetch the standard `.dockerignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
+  it with the repo's own artifacts.
+
+- **In-repo agent scratch belongs in both files, written to each file's own
+  semantics.** `.claude/` holds one worktree per in-flight agent — an entire
+  additional checkout of the repo — so under `COPY . .` the build context
+  inflates by a multiple of the repo and another session's unreviewed work can
+  be copied into an image layer. In `.gitignore` the entry is `.claude/`,
+  unanchored. In `.dockerignore` it is `.claude`, anchored and with **no** `**/`
+  prefix, because the prefixed form would also delete any nested directory of
+  that name from the build. Anchoring carries a known gap that the canonical
+  `.dockerignore` states in its own comment, since consuming repos receive the
+  file and not the tracker: the directory is created in the agent's working
+  directory, so a repo running agents in subdirectories still ships
+  `services/api/.claude/` and must add its own anchored entry there.
+
+- **A plain `docker build .` of a clone stamps the version that
+  `git describe --tags --always` gives**, derived from the `.git` in the build
+  context as the canonical `Dockerfile` above shows. Without its failure check,
+  a missing `git` or an unreadable checkout would leave `-X main.Version=` empty
+  and the build would still exit 0. `script/docker` and `script/cibuild` pass
+  the version they compute on the host; it takes precedence. They do this
+  byte-identically across repos:
+
+    ```sh
+    # The version and the tag each get their own line: a failing command
+    # substitution inside an argument does not trip `set -e`, so the inline
+    # form degrades to an empty constant.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    tag="$(script/projectname)"
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
+        --build-arg VERSION="$version" \
+        -t "$tag" .
+    ```
+
+    `--always` makes an untagged repo yield an abbreviated commit hash rather
+    than failing, and the `[ -n "$version" ]` line is the single place the
+    fallback is applied — a live check that fires on a build from an export with
+    no `.git` and on a repository with no commits yet. Do not fold it into the
+    substitution as `|| echo unknown`, which makes the guard unreachable. The
+    Dockerfile's side is `ARG VERSION` in the stage that compiles, declared
+    there because `ARG` is stage-scoped; passing `VERSION` to a repo whose
+    Dockerfile declares no such `ARG` is ignored and costs nothing, which is why
+    the scripts stay byte-identical. One consequence for CI: the standard
+    checkout action clones shallow and fetches no tags, so the canonical
+    `.gitea/workflows/check.yml` sets `fetch-depth: 0` on its checkout step.
+
+- **Verify `.dockerignore` by enumerating the image, not by reading the
+  patterns.** Plant files at the root _and_ at least two directories deep, build
+  a probe image that does `COPY . .`, and list what actually landed
+  (`docker run --rm --entrypoint find IMAGE /app`). The `transferring context`
+  size is not a substitute: a nested secret is a few bytes, and BuildKit
+  transfers only the delta from the previous build.
 
 - **No build artifacts in version control.** Code-derived data (compiled
   bundles, minified output, generated assets) must never be committed to the
@@ -258,9 +544,61 @@ style conventions are in separate documents:
 - Make all changes on a feature branch. You can do whatever you want on a
   feature branch.
 
-- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
+- `.golangci.yml` is standardized. The vendored copy in a consuming repo must
-  manually by the user. Fetch from
+  _NEVER_ be modified by an agent: fetch it from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and keep it
+  byte-identical, so that no repo can quietly loosen its own linting. Linter
+  configuration changes are made to the canonical copy in the `prompts` repo and
+  reach consuming repos by re-vendoring; an agent may open a PR against
+  canonical, which only the user merges. One list is exempt from byte-identity,
+  because it cannot be written once for every repo: the `deny` list of the
+  `test-support` depguard rule, where a repo names its own test-support packages
+  by full import path. A repo adds entries there and changes nothing else, and a
+  re-vendor carries its entries forward. The canonical golangci-lint version is
+  v2.14.0 (released 2026-09-24), pinned as the digest of the lint phase's base
+  image
+  (`golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f`,
+  which reports `2.14.0 built with go1.27.0 from 114493f9`). A module's `go`
+  directive must not name a newer Go minor version than the one golangci-lint
+  was built with, or golangci-lint refuses to lint it: this release lints
+  `go 1.27.1` but not `go 1.28`. That digest is the only pin, since no repo
+  installs golangci-lint on the host. A repo sets the lint phase digest to the
+  one named here and re-vendors `.golangci.yml` in the same commit, whichever of
+  the two prompted the change: the canonical copy can name linters that an older
+  golangci-lint rejects, and a newer golangci-lint can add linters that
+  `default: all` switches on until the canonical copy disables them.
+
+- **`script/bootstrap` installs a pinned tool by comparing versions, never by
+  testing presence.** An `if ! command -v <tool>; then install; fi` guard tests
+  `PATH` only, so on an already-provisioned machine the pin is inert and a
+  version bump is a silent no-op — while the Dockerfile, installing into a clean
+  image, gets the pinned version, so a local `make check` and `make docker` can
+  disagree about what the tool even is. The canonical form:
+    - compares the installed version against the pin over the **whole** version
+      token; a parser that stops at the first `-` reports `2.12.2` for a host
+      running `2.12.2-rc1` and skips the install;
+    - treats absent, non-zero, empty or unrecognised `--version` output as a
+      mismatch, so the failure direction is a redundant install and never a
+      skipped one;
+    - after installing, re-resolves the binary the way callers do — `hash -r`,
+      then through `PATH`, not through the directory the installer wrote to —
+      and fails naming the resolved path, since an install that a shadowing
+      binary hides succeeds while changing nothing any caller sees;
+    - is actually called, and prints the version on both success paths: a
+      function defined and never invoked has the same exit status and the same
+      empty output as one that worked.
+
+    Node is the exception to the whole-token comparison: the canonical
+    `script/bootstrap` compares only its major version, because the node 22
+    alpine image the `Dockerfile` stages start from is not the exact pin, and
+    nvm cannot install a prebuilt node on alpine.
+
+    Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
+
+    A Go tool a repo needs on the host is installed with `go install` pinned to
+    a commit hash (`go install <package>@<commit hash>`). It is never tracked as
+    a `go.mod` tool dependency or through a `tools.go` file, either of which
+    pulls the tool's own dependencies into the repo's `go.mod` and `go.sum`.
 
 - When pinning images or packages by hash, add a comment above the reference
   with the version and date (YYYY-MM-DD).
@@ -371,15 +709,21 @@ style conventions are in separate documents:
       Never edit existing migrations after release.
 
 - All repos should have an `.editorconfig` enforcing the project's indentation
-  settings.
+  settings: the standard file from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`, which sets
+  tabs for `Makefile` and Go files, followed by the repo's own sections, such as
+  one for another language it uses. A re-vendor replaces the standard part and
+  keeps those sections.
 
 - Avoid putting files in the repo root unless necessary. Root should contain
-  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
+  only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
-  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
+  `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
-  language-specific config). Everything else goes in a subdirectory. Canonical
+  and language-specific config). Everything else goes in a subdirectory.
-  subdirectory names:
+  Canonical subdirectory names:
     - `bin/` — executable scripts and tools
-    - `cmd/` — Go command entrypoints
+    - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
+      body is a single call into `internal/` or `pkg/`, no project logic in
+      `cmd/`
     - `configs/` — configuration templates and examples
     - `deploy/` — deployment manifests (k8s, compose, terraform)
     - `docs/` — documentation and markdown (README.md stays in root)
@@ -406,3 +750,7 @@ style conventions are in separate documents:
     - Go: `go.mod`, `go.sum`, `.golangci.yml`
     - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
     - Python: `pyproject.toml`
+
+- Guidance for coding agents lives in one `AGENTS.md` at the repository root. It
+  is never committed under a file or directory named after one agent tool, such
+  as `CLAUDE.md` or `.claude/`, and never split into separate memory files.

TODO.md

@@ -1,507 +1,423 @@
 # Workflow
 
-- take an issue from the `1.0.0` milestone on the tracker; work not
+- take an issue from the `1.0.0` milestone on the tracker; work not yet on the
-  yet on the tracker gets filed as an issue first
+  tracker gets filed as an issue first
-- branch (from `main`)
+- branch from `next`
 - do the work, with tests, in small focused commits
-- record it at the top of Completed Steps (`TODO.md` changes in the
+- record it at the top of Completed Steps (`TODO.md` changes in the same commit
-  same commit as the work)
+  as the work)
-- push the branch and open a PR whose title ends with
+- push the branch and open a PR against `next` whose title ends with
   ` (closes #N)`
-- an independent review gates the merge; every finding is addressed
+- an independent review gates each merge to `next`; every finding is addressed
   or explicitly rebutted on the PR
-- merge to `main` once the review passes
+- only the owner merges `next` to `main`
 
 # Status
 
 - pre-1.0
-- the Gitea tracker is authoritative for the pre-1.0 backlog: the
+- the Gitea tracker is authoritative for the pre-1.0 backlog: the open issues
-  open issues under the `1.0.0` milestone are what remains before
+  under the `1.0.0` milestone are what remains before the tag, and this file
-  the tag, and this file records history and process, not the queue
+  records history and process, not the queue
 
 # Next Step
 
 - take the next issue from the `1.0.0` milestone on the tracker:
-  https://git.eeqj.de/sneak/sfdupes/milestone/17 — the milestone is
+  https://git.eeqj.de/sneak/sfdupes/milestone/17 — the milestone is the source
-  the source of truth for what is left before 1.0.0. Individual
+  of truth for what is left before 1.0.0. Individual issues are deliberately not
-  issues are deliberately not restated here; a copy in this file
+  restated here; a copy in this file drifts out of date the moment the tracker
-  drifts out of date the moment the tracker moves
+  moves
 
 # Completed Steps
 
-- refuse an unversioned database that already has a `files` table with
+- each `scan` phase's progress display names the phase and its place among the
-  a clear schema-version error (2026-10-04,
+  five, as `[2/5] walk`, from the moment it starts, with its progress, elapsed
+  time and ETA: `load` counts the records first, the walk's total is estimated
+  from the records under the operands, and the content phase counts the records
+  it checks from SQLite's grouping alone, then says it is searching the database
+  until the first one is returned. On a terminal a phase with an exact total
+  draws its line followed by the library's bar, and any other a spinner followed
+  by the line; every display is drawn again several times a second. No line
+  reaches the terminal's last column, however narrow, also after the terminal is
+  made narrower during a phase: a line too wide leaves out its rate, then its
+  bar, keeping the phase, progress, elapsed time and ETA whole, and is cut short
+  only when those alone do not fit, as below about 70 columns late in a large
+  scan. In plain mode the line is printed every 5 seconds whether or not an item
+  completed (2026-10-16, https://git.eeqj.de/sneak/sfdupes/issues/112)
+
+- `scan`, `report` and `trees` first print a line on stderr naming the database
+  they use, as an absolute path, and whether that path is the default or comes
+  from `SFDUPES_DATABASE`; `scan` says when the database is new. README
+  "Database" says when `scan` writes each file (2026-10-16,
+  https://git.eeqj.de/sneak/sfdupes/issues/111)
+
+- re-vendor the canonical files and model scripts from `sneak/prompts` `next` at
+  `e3f79c4`: golangci-lint v2.14.0; lint and test are phases of the `Dockerfile`
+  that write no image, and `make test` runs the suite under the race detector,
+  so `Dockerfile.lint`, `script/verify-lint-image-pin` and `make test-race` are
+  gone; every `docker build` in `script/` passes a new `CACHEBUST` value, which
+  every stage of the `Dockerfile` declares first, so every `RUN` step runs on
+  every build, while the steps that compile keep Go's build cache and the tests
+  run with `-count=1`; prettier runs on the host, from the node and yarn
+  `script/bootstrap` installs, so the `prettier` and `markdown` stages are gone
+  and the build stage installs `git` and `make` itself; a new push cancels the
+  workflow's older run on the same branch, and a run stops after 20 minutes;
+  `.claude/settings.json` is deleted (2026-10-15,
+  https://git.eeqj.de/sneak/sfdupes/issues/95)
+
+- with `-x`, an operand under another operand is walked on its own instead of
+  being dropped when a directory from it (from its directory, for a regular
+  file) up to but not including that operand is on a different filesystem than
+  that operand, whose walk then cannot reach it, and the records of files gone
+  from below it are deleted (2026-10-14,
+  https://git.eeqj.de/sneak/sfdupes/issues/106)
+
+- with `-x`, `scan` keeps the records below a directory on another filesystem
+  under its operand, and counts their sizes in the size census, instead of
+  deleting them (2026-10-14, https://git.eeqj.de/sneak/sfdupes/issues/99)
+
+- the hash and content phases open each file without blocking and check that it
+  is still a regular file, so one replaced by a FIFO or device node after it was
+  statted is warned about and skipped instead of hanging the scan (2026-10-14,
+  https://git.eeqj.de/sneak/sfdupes/issues/100)
+
+- the scan lock file is named from the database's path with symlinks resolved,
+  after `scan` creates the database file if it is missing, so a scan through a
+  symlink to the database fails while another scan holds the lock (2026-10-14,
+  https://git.eeqj.de/sneak/sfdupes/issues/101)
+
+- on a terminal, a warning for the last file of a phase no longer erases the
+  phase's finished bar: the bar is drawn again below the warning (2026-10-14,
+  https://git.eeqj.de/sneak/sfdupes/issues/102)
+
+- `scan` records mtime to the nanosecond, as whole seconds in `mtime` plus
+  `mtime_nsec`, and compares it at that resolution, so a same-size rewrite
+  within the same second is re-hashed (2026-10-07,
+  https://git.eeqj.de/sneak/sfdupes/issues/12)
+
+- cut the narration from `TODO.md` Completed Steps and from the comments in
+  `script/`, `Dockerfile` and `Dockerfile.lint` (gone since
+  https://git.eeqj.de/sneak/sfdupes/issues/95); §Workflow now branches from and
+  merges to `next` (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/49)
+
+- `make test-race` ran the test suite under the race detector in a cgo-enabled
+  container, outside `make check` (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/18). Since
+  https://git.eeqj.de/sneak/sfdupes/issues/95 `make test` itself runs the suite
+  under the race detector, in the `Dockerfile`'s Debian-based `test` phase, and
+  `make test-race` is gone
+
+- a bare `docker build .` failed, naming `script/cibuild` and `script/docker`,
+  rather than serve the gates from cache (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/39). Since
+  https://git.eeqj.de/sneak/sfdupes/issues/95 a bare build succeeds, as
+  `REPO_POLICIES.md` requires, and may serve the gates from cache; the builds in
+  `script/` pass a new `CACHEBUST` value, so theirs always run
+
+- `make fmt` and `make fmt-check` run prettier over all Markdown, and CI checks
+  it; all Markdown reformatted (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/19)
+
+- `script/lint` writes no image, so a run no longer leaves an untagged one
+  behind (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/48)
+
+- tests cover a missing database, `scan` keeping stdout empty, its skip warning,
+  the `report` and `trees` summary lines, and every subcommand going through
+  `runE` (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/16)
+
+- `.golangci.yml` replaced with the current canonical copy, which uses
+  `gomodguard_v2`, so lint no longer prints a deprecation warning (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/26)
+
+- a test fails when either `hashWorker` cancellation check in `scan.go` is
+  removed (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/83)
+
+- a database path holding `?`, `#` or `%` opens exactly the file it names
+  (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/55)
+
+- `scan` rejects `--workers` below 1 as a usage error instead of running
+  single-threaded (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/10)
+
+- a test fails when either walk cancellation check in `scan.go` is removed
+  (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/81)
+
+- test that `scan` refuses a database with another schema version (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/64)
+
+- correct four inaccurate comments in `cancel_test.go` and rename
+  `walkCancelInFlightDirs` to `walkCancelInFlightFiles` (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/33)
+
+- test the `-x` filesystem-boundary rules in `subdirJob` (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/17)
+
+- `scan` creates the schema in one transaction; a version-0 database with a
+  `files` table is refused with a clear schema-version error (2026-10-04,
   https://git.eeqj.de/sneak/sfdupes/issues/11)
 
-- the `Dockerfile` build stage keeps the Go module cache out of `builder`'s
+- README documents install, Docker, a daily cron scan and how to read and check
-  home and copies the sources with `--chown`, so no `chown -R` walks them
+  the reports (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/54)
-  (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/43)
+
+- the `Dockerfile` build stage kept the Go module cache out of `builder`'s home
+  and copied the sources with `--chown`, so no `chown -R` walked them
+  (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/43). Since
+  https://git.eeqj.de/sneak/sfdupes/issues/95 there is no `builder` user and
+  nothing changes owner: the build stage only compiles, as root, and the tests
+  run as `nobody` in the `test` phase
 
 - `--version` prints `sfdupes VERSION` to stdout; README documents it and
   `--help` (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/15)
 
-- `scan` stops cleanly on `SIGINT` or `SIGTERM`: commits what it has
+- `scan` stops cleanly on `SIGINT` or `SIGTERM`: commits what it has hashed,
-  hashed, deletes nothing more, exits 1 (2026-10-04,
+  deletes nothing more, exits 1 (2026-10-04,
   https://git.eeqj.de/sneak/sfdupes/issues/5)
 
-- `report` and `trees` stream the records instead of holding them all in
+- `report` and `trees` stream the records instead of holding them all in memory;
-  memory; the schema gains the `files_signature` index (2026-10-04,
+  the schema gains the `files_signature` index (2026-10-04,
   https://git.eeqj.de/sneak/sfdupes/issues/14)
 
-- progress prints at once on a non-terminal, uses a real terminal test,
+- progress prints at once on a non-terminal, uses a real terminal test, and
-  and prints warnings through a spinner instead of racing its redraw
+  prints warnings through a spinner instead of racing its redraw (2026-10-03,
-  (2026-10-03, https://git.eeqj.de/sneak/sfdupes/issues/13)
+  https://git.eeqj.de/sneak/sfdupes/issues/13)
 
-- warn about and skip symlink, socket, FIFO, device and `.zfs`
+- warn about and skip symlink, socket, FIFO, device and `.zfs` operands, keeping
-  operands, keeping the records beneath them (2026-10-03,
+  the records beneath them (2026-10-03,
   https://git.eeqj.de/sneak/sfdupes/issues/9)
 
-- `scan` holds a lock on a lock file beside the database for its whole run,
+- `scan` holds a lock on a lock file beside the database for its whole run, so a
-  so a second `scan` fails at once with exit 1 (2026-10-03,
+  second `scan` fails at once with exit 1 (2026-10-03,
   https://git.eeqj.de/sneak/sfdupes/issues/53)
 
 - test stdout write failures in `report` and `trees`; README states that
   `| head` ends sfdupes by `SIGPIPE` and `>&-` writes to `/dev/null`
   (2026-10-03, https://git.eeqj.de/sneak/sfdupes/issues/30)
 
-- `report` and `trees` open the database read-only, and `scan` leaves it
+- `report` and `trees` open the database read-only, and `scan` leaves it out of
-  out of WAL mode, so reading needs only read access (2026-10-03, closes
+  WAL mode, so reading needs only read access (2026-10-03, closes
   https://git.eeqj.de/sneak/sfdupes/issues/8)
 
-- escape tabs, newlines, carriage returns and backslashes in report,
+- escape tabs, newlines, carriage returns and backslashes in report, trees and
-  trees and warning paths; the root directory's path is `/`
+  warning paths; the root directory's path is `/` (2026-10-03,
-  (2026-10-03, https://git.eeqj.de/sneak/sfdupes/issues/7)
+  https://git.eeqj.de/sneak/sfdupes/issues/7)
 
-- stamp the git tag or short commit in a plain `docker build .`
+- stamp the git tag or short commit in a plain `docker build .` instead of `dev`
-  instead of `dev` (2026-10-02, branch `next`, closes
+  (2026-10-02, branch `next`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/67): `.dockerignore` now
+  https://git.eeqj.de/sneak/sfdupes/issues/67): `.dockerignore` sends `.git`
-  sends `.git`, without `.git/config`, and the `Dockerfile` build
+  without `.git/config`; the build stage stamps the `VERSION` build argument,
-  stage takes the `VERSION` build argument when one is given,
+  else `git describe --tags --always`, and fails if the context carries `.git`
-  otherwise `git describe --tags --always` of that `.git`. The build
+  and the version is still empty, `dev` or `unknown`. CI checks out the full
-  fails if the context carries `.git` and the version still comes out
+  history (`fetch-depth: 0`) so it stamps the same value as `make build`.
-  empty, `dev` or `unknown`. The CI checkout step fetches the full
-  history (`fetch-depth: 0`) so CI sees the tag and stamps the same
-  value as `make build`.
 
-- replace the 1 KiB end-window sampling with the head/tail plus
+- replace the 1 KiB end-window sampling with the head/tail plus content-hash
-  content-hash ladder (2026-09-22, branch `next`, closes
+  ladder (2026-09-22, branch `next`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/61): a file under 10 MiB is
+  https://git.eeqj.de/sneak/sfdupes/issues/61); README "Duplicate detection"
-  hashed in full and compared directly, with no end-window step — its
+  documents every rung. A file under 10 MiB is hashed in full, and its `head`,
-  `head`, `tail`, and `content` all hold the whole-file hash. A file at
+  `tail` and `content` all hold that hash. A larger file gets only its 64 KiB
-  10 MiB or above gets only the 64 KiB `head` and `tail` in the hash
+  `head` and `tail` in the hash phase; the content phase, after the update
-  phase; a new content phase, after the update phase, reads it for its
+  phase, reads it for `content` (the whole file below 50 MiB, gigabyte-spaced 1
-  `content` hash — the whole file below 50 MiB, gigabyte-spaced 1 MiB
+  MiB samples at or above) only when its size, `head` and `tail` match another
-  samples at or above — only when its size, `head`, and `tail` match
+  record's from this scan or an earlier one, and never reads a file gone or
-  another record's, from the same scan or stored by an earlier one, so
+  changed since its record was written. `report` and `trees` leave out any
-  a stored file gains its content hash when it gains a match. A file
+  record without a `content` hash. The `content` column is part of the version 1
-  that is gone or has changed since its record was written is not
+  schema.
-  read. The `content` column is part of the version 1 schema. `report`
-  and `trees` group by the extended signature and leave out any record
-  without a `content` hash, so the ladder is applied across the whole
-  database. README "Duplicate detection" documents every rung including
-  the probabilistic large-file path.
 
-- remove the dead `files.dat` references from `Makefile`, `.gitignore`
+- remove the dead `files.dat` references from `Makefile`, `.gitignore` and
-  and `.dockerignore` (2026-09-21, branch `next`, closes
+  `.dockerignore` (2026-09-21, branch `next`, closes
   https://git.eeqj.de/sneak/sfdupes/issues/22)
 
 - fix the lint-image pin comments and `FROM` form in `Dockerfile` and
   `Dockerfile.lint` (2026-08-10, branch `next`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/25): dropped the false
+  https://git.eeqj.de/sneak/sfdupes/issues/25): both pins became the policy
-  `(Debian-based)` parenthetical (v2.12.1 was Debian too) and the
+  `# image:vX.Y.Z, YYYY-MM-DD` comment over a bare `FROM image@sha256:...`,
-  redundant tag, so both pins are the policy `# image:vX.Y.Z,
+  without the false `(Debian-based)` note or the tag. Since
-  YYYY-MM-DD` comment over a bare `FROM image@sha256:...`. Digest
+  https://git.eeqj.de/sneak/sfdupes/issues/95 the `Dockerfile`'s `lint` phase
-  unchanged. `script/verify-lint-image-pin` parses those `FROM` lines
+  holds the only golangci-lint pin, in that form, so `Dockerfile.lint` and
-  and still matches the tagless form; its advice line lost the now
+  `script/verify-lint-image-pin`, which compared the two pins, are gone.
-  meaningless "tag and digest". With no tag in either reference, a
-  tag-only disagreement no longer exists — a one-sided tag is caught as
-  a plain mismatch.
 
-- run all linting in Docker via `Dockerfile.lint` and `script/lint`
+- run all linting in Docker via `Dockerfile.lint` and `script/lint` (2026-08-10,
-  (2026-08-10, branch `next`, closes
+  branch `next`, closes https://git.eeqj.de/sneak/sfdupes/issues/46): per the
-  https://git.eeqj.de/sneak/sfdupes/issues/46): per the owner ruling, the
+  owner ruling the linter is never installed on a host, and
-  linter runs inside a container invoked through the `script/`
+  `golangci-lint config verify` runs before `golangci-lint run`.
-  entrypoint and is never installed on a host. New root
+  `script/bootstrap` stopped installing or pinning the linter, and
-  `Dockerfile.lint` COPYs the repo into the digest-pinned
+  `script/verify-linter-pin` was retired. Since
-  `golangci/golangci-lint:v2.12.2` image and runs
+  https://git.eeqj.de/sneak/sfdupes/issues/95 both commands run in the
-  `golangci-lint config verify` and `golangci-lint run` as build
+  `Dockerfile`'s `lint` phase, which `script/lint` builds alone and the build
-  steps, so a successful build IS a clean lint; `script/lint` is
+  stage depends on through `COPY --from=lint /src/go.sum /dev/null`;
-  reduced to building it. `script/bootstrap` loses the `go install`,
+  `Dockerfile.lint` and `script/verify-lint-image-pin` are gone. Nothing inside
-  the pin constants, the version parser and `verify_golangci_lint`
+  an image build may run docker, so the phase calls `golangci-lint` directly.
-  outright rather than hardening them — with nothing linting on the
-  host, the `$GOPATH/bin` versus `PATH` problem that motivated them has
-  no subject — and now warns rather than fails when `docker` is absent.
-  Two traps handled. A lint build on an unchanged tree returns success
-  in well under a second having run no linter, which is
-  https://git.eeqj.de/sneak/sfdupes/issues/32 and
-  https://git.eeqj.de/sneak/sfdupes/issues/39 again, so
-  `Dockerfile.lint` carries `ARG CHECK_EPOCH` referenced
-  inside every gate `RUN` (BuildKit hashes the expanded command, not
-  the declaration) and `script/lint` passes `"$(date +%s)-$$"` — the
-  PID matters because two lint runs land inside the same second easily.
-  And nothing inside an image build may shell out to docker, so the
-  main `Dockerfile`'s lint stage now invokes `golangci-lint` directly
-  instead of `make lint`, and its build stage runs `make test` and
-  `make fmt-check` instead of the `make check` aggregate (`make`, not
-  the scripts bare, because the Makefile's `export CGO_ENABLED = 0`
-  only reaches what it invokes). `COPY --from=lint`
-  `/usr/bin/golangci-lint` is replaced by
-  `COPY --from=lint /src/go.sum /dev/null`: the copied binary was the
-  only edge forcing BuildKit to finish linting before the build stage
-  starts, and dropping it without replacing the edge would have ended
-  fail-fast linting silently under a still-green build. That is
-  canonical `REPO_POLICIES.md:107`'s ordering edge, restored.
-  `ENV PATH=/home/builder/go/bin:$PATH` is gone with the `go install`
-  that justified it. `script/verify-linter-pin` is retired, deleted
-  along with its README entry, because both of its subjects ceased to
-  exist in the same change: it compared a linter binary against
-  `GOLANGCI_LINT_VERSION` in `script/bootstrap`, and there is now
-  neither a binary crossing between stages nor a version pin in
-  bootstrap. The drift it guarded has not gone away, it has moved — the
-  linter is still pinned twice, now as the `FROM` line of
-  `Dockerfile.lint` and the `FROM` line of the `Dockerfile` lint stage,
-  with nothing syncing them, which is exactly what
-  https://git.eeqj.de/sneak/sfdupes/issues/42 made a build failure. Its
-  replacement is one new `script/verify-lint-image-pin`,
-  run as a gate in both files, which compares the two references to
-  each other and deliberately restates neither: a hardcoded expected
-  digest would be a third copy and the same drift one file further out.
-  `golangci-lint config verify` is included per the ruling, and the
-  concern about its unpinned live HTTPS schema fetch was measured
-  rather than assumed — under `--network none` the pinned binary both
-  passes a valid config and rejects an invalid one with the jsonschema
-  error, so it validates from an embedded schema and makes no network
-  call of its own. The README scopes that to the gate steps rather
-  than to linting as a whole: `Dockerfile.lint` runs `go mod download`
-  above them, so a cold cache still needs the network and only a warm
-  one lints offline. Verified: `make lint` green with every `PATH`
-  directory containing a `golangci-lint` removed
-  (`/home/user/go/bin`, `/home/user/.local/bin`, `/usr/local/bin`;
-  `command -v golangci-lint` empty); two consecutive `script/lint` runs
-  on an untouched tree both executed the linter, 27.7s and 28.7s in the
-  lint step under distinct epochs with the `COPY . .` layer `CACHED`
-  above them, at 42.2s and 41.8s wall clock — the no-cache rule was not
-  weakened to shorten that. Negative control: a planted
-  `var unusedIssue46Sentinel = 1` failed `script/lint` with
-  `report.go:173:5: var unusedIssue46Sentinel is unused (unused)`, and
-  failed `make docker` at `[lint 9/9]` with the build stage stopped at
-  `[builder 3/12]` — `COPY --from=lint`, `script/bootstrap`, the test
-  gate and `make build` all zero occurrences — then reverted clean. The
-  drift guard fails on a tag-only disagreement, on a digest-only
-  disagreement, and on an unreadable reference, naming both sides.
-  `make docker` green in 5m35s with all six gates executing under one
-  epoch (lint 37.6s, test 25.2s reporting
-  `ok sneak.berlin/go/sfdupes 1.938s coverage: 88.5%`, not `(cached)`).
-  The non-root quirk still holds: in the builder image with the Go test
-  cache off, `--user 0:0` fails `TestScanHardlinkRunFailsTogether`
-  (exit 1) where the unprivileged user passes (exit 0). Noted for
-  follow-up, not fixed here: `golangci-lint` warns that the
-  `gomodguard` linter is deprecated since v2.12.0 in favour of
-  `gomodguard_v2`.
 
-- install the Docker build stage's prerequisites by running
+- install the Docker build stage's prerequisites by running `script/bootstrap`
-  `script/bootstrap` instead of `apk add --no-cache make` inline
+  instead of `apk add --no-cache make` inline (2026-08-09, branch
-  (2026-08-09, branch `dockerfile-bootstrap`, closes #42): canonical
+  `dockerfile-bootstrap`, closes https://git.eeqj.de/sneak/sfdupes/issues/42),
-  `REPO_POLICIES.md:97` requires it, and the inline install left the
+  with `script/verify-linter-pin` failing the build unless the linter copied
-  build stage maintaining its own notion of the toolchain — exactly
+  from the lint stage was the version `script/bootstrap` pinned. Builds then
-  the divergence #24 exists to close, one layer down. The stage now
+  took up to 5m14s cold, mostly in a `chown -R` of the module cache, filed as
-  copies `script/` plus `go.mod`/`go.sum` and runs `script/bootstrap`,
+  https://git.eeqj.de/sneak/sfdupes/issues/43. Since
-  which ends in `go mod download`, so the separate invocation of that
+  https://git.eeqj.de/sneak/sfdupes/issues/95 the build stage installs `git` and
-  is gone. `COPY --from=lint /usr/bin/golangci-lint` stays, and moves
+  `make` with `apk add --no-cache` and only compiles; the `lint` and `test`
-  above the bootstrap layer. It is the only edge making this stage
+  phases are the gates
-  depend on the lint stage, so deleting it as redundant would end
+- bust the Docker layer cache for the gate steps, so `script/cibuild` and
-  fail-fast linting silently. Letting bootstrap install its own linter
+  `script/docker` cannot report a green they did not earn (2026-08-09, branch
-  here would have reintroduced the second toolchain and paid for a
+  `cibuild-cache-bust`, closes https://git.eeqj.de/sneak/sfdupes/issues/32): the
-  from-source build of it. What makes the two stages provably one
+  `Dockerfile` copies the tree before its gates, so on an unchanged tree Docker
-  toolchain rather than two that happen to agree is a new
+  served them from cache and the build exited 0 having run nothing. The fix was
-  `script/verify-linter-pin`, run in the build stage on the binary
+  a `CHECK_EPOCH` build argument; since
-  that arrives from the lint stage, before bootstrap: it fails the
+  https://git.eeqj.de/sneak/sfdupes/issues/95 every `docker build` in `script/`
-  build naming both versions unless that binary is the version
+  passes a new `CACHEBUST` value instead, which every stage of the `Dockerfile`
-  `script/bootstrap` pins. Bootstrap's own check could not serve that
+  declares first. Run as root, the tests fail
-  purpose — it reinstalls its pin from source and then verifies
+  `TestScanHardlinkRunFailsTogether`, because root reads through the `chmod(0)`
-  whatever `PATH` resolves, so drift self-heals silently and a lint
+  the test relies on, so the `test` phase runs them as `nobody`
-  stage image bumped on its own would lint at the new version while
+- check the installed golangci-lint version in `script/bootstrap` instead of
-  `make check` ran at the old one, green. The linter version is pinned
+  only its presence (2026-08-09, branch `bootstrap-version-check`, closes
-  in two independent places (the lint stage image digest and
+  https://git.eeqj.de/sneak/sfdupes/issues/24): the version lives only in
-  `GOLANGCI_LINT_VERSION`) and nothing else keeps them in sync, so a
+  `GOLANGCI_LINT_VERSION`, with the `go install` module ref derived from it, and
-  half-applied bump is now a build failure. The pin is read out of
+  any installed version that is not the pin — older, newer, absent or
-  `script/bootstrap`, which stays the single source of truth; a pin
+  unparseable — is reinstalled. `go install` writes into `GOBIN` (or
-  that cannot be read is a hard failure, not a skip. The check needs
+  `GOPATH/bin`) while `make lint` runs the first `golangci-lint` on `PATH`, so
-  no `CHECK_EPOCH`: its only inputs are the copied binary and
+  bootstrap re-reads the effective version after installing and, on a mismatch,
-  `script/`, so Docker invalidates the layer exactly when a cached
+  prints both paths and both versions and exits non-zero; it does not reorder
-  result would stop being true, and it is documented with the other
+  `PATH` or delete anyone's binary. The `--version` call keeps its stderr and is
-  entrypoints in the README. `$GOPATH/bin` joins `PATH` because
+  bounded by `timeout(1)` where that exists. `git`, `make` and `go` keep
-  that is where bootstrap's `go install` lands and bootstrap verifies
+  presence-only checks. Verified by bootstrapping this host from v2.10.1 to
-  its installs against what `PATH` resolves — nothing in the image is
+  v2.12.2 and again to a no-op, and by stub runs of the script under `dash`
-  shadowed by it, the directory does not exist until bootstrap runs.
+  covering a thirteen-input version-parse matrix, a shadowed install that must
-  Everything added sits above `ARG CHECK_EPOCH`, and the `chown` and
+  exit non-zero, an install destination not on `PATH`, `GOBIN` set, and a wedged
-  `USER builder` still precede `make check`. Verified: the guard fails
+  binary that must hit the timeout; `make check` and `make lint` are clean at
-  the build with both versions named when the lint stage's linter is
+  v2.12.2, so v2.10.1 was not hiding any findings on `main`
-  faked to a different version, and an unmodified build still passes
-  it; bootstrap runs clean under Alpine's `sh` and its `apk` branch,
-  installing `git` and `make` and finding the copied
-  linter already at the pin; a second build served the bootstrap and
-  dependency layers `CACHED` while both gates ran with a fresh epoch;
-  a planted `unused` finding failed the build at the lint gate in
-  48.9s with the build stage's `make check` never starting; and the
-  suite run in the image as `--user 0:0` fails
-  `TestScanHardlinkRunFailsTogether`, so the drop to the unprivileged
-  user is still load-bearing. That last check needs the Go test cache
-  disabled — the first attempt reported `ok ... (cached)` as root,
-  reusing the result the build-time run had left in the shared cache,
-  which would have read as a pass. Build wall time, on a shared host
-  running many concurrent builds and so noisy: 2m13s on an unchanged
-  tree, 2m17s and 4m29s for two builds after a source change, 5m14s
-  cold. Only the cold one breaches the policy ceiling, and not because
-  of this change — `chown -R builder:builder /src /home/builder` walks
-  the module cache and re-runs on every source change, and it alone
-  varied between 77s and 210s across those four builds, which is also
-  the whole spread in the totals. The same cold measurement against
-  `main` is 5m03s with a 209s `chown`. Filed as #43
-- bust the Docker layer cache for the gate steps, so `script/cibuild`
-  and `script/docker` cannot report a green they did not earn
-  (2026-08-09, branch `cibuild-cache-bust`, closes #32): both scripts
-  were bare `docker build` invocations with no cache control, and the
-  `Dockerfile` copies the tree before running its gates, so on an
-  unchanged tree Docker served those layers from cache and the build
-  exited 0 having executed nothing. That is not hypothetical here —
-  every merge this repo has done is a non-fast-forward merge of an
-  undiverged branch, so each merge commit's tree is byte-identical to
-  the branch head's and each merge CI run was almost certainly a full
-  cache hit; and PR #31's reviewer found `make docker` returning
-  success as a 17-layer cache hit, catching it only by being
-  suspicious. The fix is `ARG CHECK_EPOCH` with the scripts passing
-  `--build-arg CHECK_EPOCH="$(date +%s)"`. Two details make or break
-  it. `ARG` is scoped per stage and this `Dockerfile` has three gates
-  across two — `make fmt-check` and `make lint` in the lint stage,
-  `make check` in the build stage — so a single declaration would have
-  left one stage silently cacheable; it is declared in both. And
-  BuildKit hashes the expanded command, not the declaration, so a
-  declared-but-unreferenced `ARG` invalidates nothing: each gate `RUN`
-  echoes the epoch, which also puts the value in the build log as
-  evidence the layer really ran. Placement is below the dependency
-  layers on purpose — a build that goes cold every time would be a
-  different bug, not a fix. Verified by running each script twice back
-  to back on an unchanged tree under `BUILDKIT_PROGRESS=plain`: all
-  three gates executed on all four runs, each with a fresh epoch in
-  the log (`script/cibuild` 78.8s then 61.1s; `script/docker` 61.1s
-  then 53.4s), and twelve steps were still served `CACHED` in the
-  steady state — both `go mod download`s, `apk add`, `adduser`, the
-  `chown`, every `go.mod`/`go.sum` and source copy, the linter copy
-  out of the lint stage, and the binary copy into the runtime stage.
-  The lint stage still gates the build stage: with a deliberate
-  `unused` finding planted in the tree, the build failed at
-  `make lint` in 36.1s and the build-stage `make check` never started.
-  The build stage also still drops to the unprivileged `builder` user
-  before `make check`, which the suite depends on rather than merely
-  prefers: forcing the same image to run the tests as root fails
-  `TestScanHardlinkRunFailsTogether`, because root reads straight
-  through the `chmod(0)` the test uses to prove hard links are read
-  once. This is the local fix only; propagating it to the canonical
-  templates is `prompts` #26
-- check the installed golangci-lint version in `script/bootstrap`
-  instead of only its presence (2026-08-09, branch
-  `bootstrap-version-check`, closes #24): `missing golangci-lint` meant
-  any linter already on `PATH` satisfied the check, so the pin was never
-  consulted and the v2.12.2 bump from #3 was inert on every host that
-  already had one — this host ran v2.10.1 against a v2.12.2 pin,
-  `make check` went green, and `make docker` then rejected the same
-  commit with findings the local gate never saw. The version now lives
-  in one place, `GOLANGCI_LINT_VERSION`, with the `go install` module
-  ref derived from it so a bump cannot half-apply; a
-  `golangci_lint_version` helper parses `golangci-lint --version`
-  (taking the field after the word `version` and tolerating an optional
-  leading `v`, which the module ref carries and the binary's output does
-  not), and any version that is not the pin — older, newer, absent or
-  unparseable — is reinstalled. The install is then verified against the
-  binary `PATH` actually resolves: `go install` writes into `GOBIN` (or
-  `GOPATH/bin`) while `make lint` runs whichever `golangci-lint` comes
-  first on `PATH`, so a wrong-version one sitting ahead of it — nix,
-  apt, brew, apk, or the `/usr/local/bin` copy the `Dockerfile` builder
-  stage makes — would swallow the install and leave the local gate
-  disagreeing with CI under an affirmative `bootstrap complete`.
-  Bootstrap now re-reads the effective version after installing and, on
-  a mismatch, prints both paths and both versions to stderr and exits
-  non-zero instead of claiming success; it does not reorder anyone's
-  `PATH` or delete their binary. The `--version` call keeps its stderr
-  connected, so a present-but-broken binary says why rather than
-  reinstalling forever in silence, and is bounded by `timeout(1)` where
-  that exists, so a wedged binary cannot hang bootstrap. `git`, `make`
-  and `go` keep their presence-only checks and now say why in a
-  comment: they are host package-manager tools the repo deliberately
-  does not pin, with `go.mod` governing the language version and the
-  digest-pinned images covering reproducible builds. Verified on this
-  host by bootstrapping from v2.10.1 to v2.12.2 and running it again to
-  a no-op, plus stub runs of the real script under `dash` covering a
-  thirteen-input parse matrix (absent, older, newer, host-style,
-  image-style, leading-`v`, stderr-only, empty, non-zero exit, impostor
-  binary, `(devel)`, trailing `version`), a shadowed install that must
-  exit non-zero, an install destination not on `PATH` at all, `GOBIN`
-  set, and a wedged binary that must hit the timeout; `make check` and
-  `make lint` are clean at v2.12.2, so v2.10.1 was not hiding any
-  findings on `main`
 - unwind the hash worker pool on the error path (2026-08-09, branch
-  `hash-pool-cleanup`, closes #6): `hashPhase` used to return the
+  `hash-pool-cleanup`, closes https://git.eeqj.de/sneak/sfdupes/issues/6): the
-  moment `recordRun` failed and abandon the pool — the feeder parked
+  pool is now an owned, context-aware `hashPool`: every blocking send in the
-  forever on a full `jobs` channel and every worker on a full
+  feeder and the workers selects on `ctx.Done()`, `jobs` is closed on every path
-  `results` channel. That only stopped being invisible when #4 landed
+  out, and `hashPhase` defers `pool.stop()`, which cancels and then drains
-  and `runScan` began unwinding instead of calling `os.Exit`. The
+  `results` until the last goroutine has exited — draining is what frees a
-  pool is now an owned, context-aware `hashPool`: every blocking send
+  worker already parked on a send. `ctx` is threaded from `cmd.Context()`
-  in the feeder and the workers selects on `ctx.Done()`, `jobs` is
+  through `runScan`, `syncScan`, both worker pools and the whole database layer,
-  closed on every path out, and `hashPhase` defers `pool.stop()`,
+  as the first parameter everywhere. The walk pool gets the same treatment plus
-  which cancels and then drains `results` until the last goroutine
+  a `ctx.Err()` guard after the walk: a cancelled walk yields a partial size
-  has exited — draining is what frees a worker already parked on a
+  census, and every file it never reached looks vanished to the update phase.
-  send. `ctx` is threaded from `cmd.Context()` through `runScan`,
+  That phase's own `BeginTx` also fails on the cancelled context before deleting
-  `syncScan`, both worker pools and the whole database layer (it is
+  anything, but the guard is the barrier that still holds once an interrupted
-  the first parameter everywhere), so #5 can hand this path a signal
+  scan may commit what it has. Tests drive `run(scan)` against a database whose
-  and needs to add nothing else. The walk pool never leaked, because
+  insert trigger aborts and assert that the scan fails instead of hanging and
-  `walkPhase` always drains its events to close, but it has the same
+  that `runtime.NumGoroutine()` polls back to its pre-scan baseline; others
-  unbounded-send shape and #5 will give it an early return, so it
+  cancel a scan part-way through the walk, deterministically, by counting its
-  gets the same treatment plus a `ctx.Err()` guard after the walk: a
+  own consultations of `ctx.Done()`, and assert that it stops at the guard
-  cancelled walk yields a partial size census, and every file it never
+  holding a partial census and a still-populated record index, with every record
-  reached looks vanished to the update phase. That phase's own
+  intact. Direct tests of `sendEvent`, the walk workers, `dispatchDirs`,
-  `BeginTx` fails on the same cancelled context before deleting
+  `feedHashJobs`, `hashWorker` and `hashPhase` cover the remaining cancellation
-  anything, so the guard is defence in depth rather than the only
+  branches of both pools
-  barrier — but it is the one that survives #5 deciding an interrupted
+- guarantee the database is closed on every fatal exit path (2026-08-09, branch
-  scan may commit what it has. Tests drive `run(scan)` against a
+  `db-close-on-fatal`, closes https://git.eeqj.de/sneak/sfdupes/issues/4):
-  database whose insert trigger aborts, and assert both that the scan
+  `fatalf` and its `os.Exit(1)` are gone, so the deferred `db.Close()` — and
-  fails instead of hanging and that `runtime.NumGoroutine()` polls
+  with it the SQLite WAL checkpoint — now actually runs when a subcommand fails;
-  back to its pre-scan baseline; a second set cancels a scan part-way
+  `runScan`, `runReport`, `runTrees`, `loadRecords` and `resolveRoots` return
-  through the walk — deterministically, by counting the scan's own
+  errors instead. The single exit point is `run` in `main.go`: it maps a
-  consultations of `ctx.Done()` rather than racing a timer — and
+  `fatalError` (anything a subcommand returned) to exit 1 and cobra's own
-  asserts that it stops at the guard holding a partial census and a
+  argument and flag errors to exit 2, which keeps a runtime failure from being
-  still-populated record index, with every record intact. The
+  reported as a usage error or printing the usage text. New `main_test.go`
-  remaining cancellation branches of both pools are covered by direct
+  drives the CLI in-process and asserts the exit codes from README §Error
-  tests of `sendEvent`, the walk workers, `dispatchDirs`,
+  handling plus the stdout/stderr split, including that a fatal error raised
-  `feedHashJobs`, `hashWorker` and `hashPhase`
+  after the database is open leaves no `-wal`/`-shm` sidecar behind for `scan`,
-- guarantee the database is closed on every fatal exit path
+  `report` or `trees`
-  (2026-08-09, branch `db-close-on-fatal`, closes #4): `fatalf` and
+- update golangci-lint to v2.12.2 with the canonical config (2026-08-09, branch
-  its `os.Exit(1)` are gone, so the deferred `db.Close()` — and with
+  `golangci-v2.12.2`, merged as `38a01bd`, closes
-  it the SQLite WAL checkpoint — now actually runs when a subcommand
+  https://git.eeqj.de/sneak/sfdupes/issues/3): bumped the pinned linter in the
-  fails; `runScan`, `runReport`, `runTrees`, `loadRecords` and
+  `Dockerfile` lint stage and `script/bootstrap` from v2.12.1 to v2.12.2, and
-  `resolveRoots` return errors instead. The single exit point is `run`
+  replaced `.golangci.yml` with the canonical file — the linter settings (`lll`,
-  in `main.go`: it maps a `fatalError` (anything a subcommand
+  `funlen`, `cyclop`, `dupl` thresholds) now live under `linters.settings` per
-  returned) to exit 1 and cobra's own argument and flag errors to exit
+  the v2 schema, so they are actually applied; no new lint findings surfaced
-  2, which keeps a runtime failure from being reported as a usage
+- convert Makefile targets to scripts-to-rule-them-all `script/` entrypoints
-  error or printing the usage text. New `main_test.go` drives the CLI
+  like the other managed repos (2026-07-26, commit `3abeacf`, closes
-  in-process and asserts the exit codes from README §Error handling
+  https://git.eeqj.de/sneak/sfdupes/issues/1): all 12 `script/` entrypoints
-  plus the stdout/stderr split, including that a fatal error raised
+  exist (`bootstrap`, `setup`, `projectname`, `test`, `lint`, `fmt`,
-  after the database is open leaves no `-wal`/`-shm` sidecar behind
+  `fmt-check`, `check`, `docker`, `cibuild`, `precommit`, `install-precommit`)
-  for `scan`, `report` or `trees`
+  and every Makefile target is now a thin shim over them
-- update golangci-lint to v2.12.2 with the canonical config
-  (2026-08-09, branch `golangci-v2.12.2`, merged as `38a01bd`,
-  closes #3): bumped the pinned linter in the `Dockerfile` lint
-  stage and `script/bootstrap` from v2.12.1 to v2.12.2, and replaced
-  `.golangci.yml` with the canonical file — the linter settings
-  (`lll`, `funlen`, `cyclop`, `dupl` thresholds) now live under
-  `linters.settings` per the v2 schema, so they are actually
-  applied; no new lint findings surfaced
-- convert Makefile targets to scripts-to-rule-them-all `script/`
-  entrypoints like the other managed repos (2026-07-26, commit
-  `3abeacf`, closes #1): all 12 `script/` entrypoints exist
-  (`bootstrap`, `setup`, `projectname`, `test`, `lint`, `fmt`,
-  `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
-  `install-precommit`) and every Makefile target is now a thin shim
-  over them, matching the other managed repos
 - make the binary the default Make target (2026-07-24, branch
-  `make-default-target`): plain `make` now builds `sfdupes`
+  `make-default-target`): plain `make` now builds `sfdupes` (previously it ran
-  (previously it ran `check` plus `build`); `make build` remains as
+  `check` plus `build`); `make build` remains as an alias
-  an alias
+- scan-wide phases, concurrent operands, batched updates (2026-07-24, branch
-- scan-wide phases, concurrent operands, batched updates (2026-07-24,
+  `scan-wide-phases`): all operands seed the shared walk pool and every pass
-  branch `scan-wide-phases`): all operands seed the shared walk pool
+  runs once over the whole scan, so totals and ETAs are scan-global; the
-  and every pass runs once over the whole scan, so totals and ETAs
+  per-operand walk/hash/update cycles and their stderr announcements are gone;
-  are scan-global; the per-operand walk/hash/update cycles and their
+  the update pass commits in batched transactions — the filesystem is
-  stderr announcements are gone; the update pass commits in batched
+  authoritative and the database an eventually-consistent reflection, so
-  transactions — the filesystem is authoritative and the database an
+  scan-level atomicity is not required
-  eventually-consistent reflection, so scan-level atomicity is not
-  required
 - split the stat pass back out of the walk (2026-07-24, branch
-  `parallel-phases`): phases are strictly sequential again — walk,
+  `parallel-phases`): phases are strictly sequential again — walk, stat, hash,
-  stat, hash, update per operand — with parallelism only inside each
+  update per operand — with parallelism only inside each phase; the walk
-  phase; the walk enumerates paths with per-directory workers and the
+  enumerates paths with per-directory workers and the stat pass lstats them with
-  stat pass lstats them with per-file workers, restoring the exact
+  per-file workers, restoring the exact total/ETA stat bar
-  total/ETA stat bar
+- announce each operand on stderr before its passes (2026-07-24, branch
-- announce each operand on stderr before its passes (2026-07-24,
+  `scan-operand-progress`): with per-operand walk/hash/update cycles, a
-  branch `scan-operand-progress`): with per-operand walk/hash/update
+  multi-operand run (e.g. `scan /srv/*`) showed pass totals that looked like the
-  cycles, a multi-operand run (e.g. `scan /srv/*`) showed pass totals
+  whole run's
-  that looked like the whole run's — an operator watching operand 3 of
+- parallel walk (2026-07-24, branch `parallel-walk`): the walk pass was a single
-  14 hash 300k files concluded 20M files were being skipped
+  goroutine and took hours at ~20M files on a busy pool (observed: 22M files in
-- parallel walk (2026-07-24, branch `parallel-walk`): the walk pass
+  4h on a ZFS server); it is now a per-directory worker-pool traversal that
-  was a single goroutine and took hours at ~20M files on a busy pool
+  records size/mtime during the walk (folding away the separate stat pass,
-  (observed: 22M files in 4h on a ZFS server); it is now a
+  halving metadata I/O), and each `PATH` operand commits in its own transaction
-  per-directory worker-pool traversal that records size/mtime during
+  so an interrupted scan keeps completed operands
-  the walk (folding away the separate stat pass, halving metadata
-  I/O), and each `PATH` operand commits in its own transaction so an
-  interrupted scan keeps completed operands
 
-- persistent scan database (2026-07-24, branch `persistent-database`):
+- persistent scan database (2026-07-24, branch `persistent-database`): `scan`
-  `scan` now maintains a SQLite database (`modernc.org/sqlite`, pure
+  now maintains a SQLite database (`modernc.org/sqlite`, pure Go, cgo stays
-  Go, cgo stays disabled) keyed by absolute path that survives between
+  disabled) keyed by absolute path that survives between runs — a rescan hashes
-  runs — a rescan hashes only new or changed files (by mtime/size),
+  only new or changed files (by mtime/size), deletes records for files vanished
-  deletes records for files vanished from under the scanned operands,
+  from under the scanned operands, and leaves records outside them untouched, so
-  and leaves records outside them untouched, so `scan` can be cronned
+  `scan` can be cronned daily; `report` and `trees` read the database (no
-  daily; `report` and `trees` read the database (no positional
+  positional arguments) instead of a scan stream. Database at
-  arguments) instead of a scan stream. Database at
+  `/var/lib/sfdupes/db.sqlite`, overridable via `SFDUPES_DATABASE`; WAL
-  `/var/lib/sfdupes/db.sqlite`, overridable via `SFDUPES_DATABASE`;
+  journaling plus a single-transaction update keep a report run during a scan
-  WAL journaling plus a single-transaction update keep a report run
+  safe
-  during a scan safe
+- add the `origin` remote (`git@git.eeqj.de:sneak/sfdupes.git`), tag `v0.0.1`,
-- add the `origin` remote (`git@git.eeqj.de:sneak/sfdupes.git`), tag
+  and push `main` plus tags (2026-07-23)
-  `v0.0.1`, and push `main` plus tags (2026-07-23)
 - `scan` CLI rework (2026-07-23, branch `scan-required-paths`): required
-  `PATH...` operands via cobra flags replacing the `/srv` `-root`
+  `PATH...` operands via cobra flags replacing the `/srv` `-root` default; new
-  default; new `-x`/`--one-file-system` flag (GNU convention) to stop
+  `-x`/`--one-file-system` flag (GNU convention) to stop at filesystem
-  at filesystem boundaries, which are crossed by default
+  boundaries, which are crossed by default
 - bring the repo into full policy compliance (2026-07-23, branch
   `repo-policy-compliance`; checklist below)
-- `git init` with README-only first commit; code baseline committed on
+- `git init` with README-only first commit; code baseline committed on `main`
-  `main` (2026-07-22)
+  (2026-07-22)
 - implement `scan`, `report`, and `trees` subcommands (pre-git history)
 
 # Future Steps
 
-- possible later features (explicitly out of scope per README):
+- possible later features (explicitly out of scope per README): full-content
-  full-content verification of candidates, removal-script helpers
+  verification of candidates, removal-script helpers
 
 # Repo Policy Compliance
 
-Audited 2026-07-22 against `REPO_POLICIES.md` (2026-07-06), the existing
+Audited 2026-07-22 against `REPO_POLICIES.md` (2026-07-06), the existing repo
-repo checklist, and the Go styleguide. Code is already gofmt-clean, so no
+checklist, and the Go styleguide. Code is already gofmt-clean, so no standalone
-standalone formatting commit is needed.
+formatting commit is needed.
 
-- [x] `.gitignore` missing — the compiled `sfdupes` binary and
+- [x] `.gitignore` missing — the compiled `sfdupes` binary and `files.dat` sit
-      `files.dat` sit untracked in the tree; needs OS/editor/Go
+      untracked in the tree; needs OS/editor/Go artifacts plus secrets patterns
-      artifacts plus secrets patterns
 - [x] `.editorconfig` missing
-- [x] `LICENSE` missing and README has no License section (MIT assumed
+- [x] `LICENSE` missing and README has no License section (MIT assumed from
-      from house convention — user to confirm)
+      house convention — user to confirm)
 - [x] `REPO_POLICIES.md` missing from repo root
-- [x] `.golangci.yml` missing (install canonical copy); code must then
+- [x] `.golangci.yml` missing (install canonical copy); code must then pass
-      pass `make lint` (150 findings fixed; `make lint` is clean)
+      `make lint` (150 findings fixed; `make lint` is clean)
-- [x] `Makefile` lacks required targets `test`, `lint`, `fmt`,
+- [x] `Makefile` lacks required targets `test`, `lint`, `fmt`, `fmt-check`,
-      `fmt-check`, `docker`, `hooks`; `check` currently depends on
+      `docker`, `hooks`; `check` currently depends on `build`, which writes the
-      `build`, which writes the binary (`make check` must not modify
+      binary (`make check` must not modify files)
-      files)
+- [x] no tests — `go test ./...` has nothing to run; policy requires real tests
-- [x] no tests — `go test ./...` has nothing to run; policy requires
+      with a 30-second timeout and the conditional `-v` rerun pattern (suite
-      real tests with a 30-second timeout and the conditional `-v`
+      covers parsing, grouping, digests, suppression, hashing, and the scan
-      rerun pattern (suite covers parsing, grouping, digests,
+      pipeline; 64% coverage)
-      suppression, hashing, and the scan pipeline; 64% coverage)
+- [x] `Dockerfile` missing — Go multistage with hash-pinned images: fail-fast
-- [x] `Dockerfile` missing — Go multistage with hash-pinned images:
+      lint stage, build stage running `make check`
-      fail-fast lint stage, build stage running `make check`
 - [x] `.dockerignore` missing
-- [x] `.gitea/workflows/check.yml` missing (`docker build .` on push,
+- [x] `.gitea/workflows/check.yml` missing (`docker build .` on push, checkout
-      checkout action pinned by commit SHA)
+      action pinned by commit SHA)
 - [x] README lacks required sections: Description first line
-      (name/purpose/category/license/author), Getting Started,
+      (name/purpose/category/license/author), Getting Started, Rationale, TODO,
-      Rationale, TODO, License, Author
+      License, Author
-- [x] README non-goal "no git repository setup and no CI" is stale now
+- [x] README non-goal "no git repository setup and no CI" is stale now that the
-      that the repo is under git with CI
+      repo is under git with CI
-- [x] pre-commit hook not installed (`make hooks` once the target
+- [x] pre-commit hook not installed (`make hooks` once the target exists)
-      exists)
 
 Accepted divergences (no action):
 
-- flat single-package layout with `.go` files in the repo root — fine
+- flat single-package layout with `.go` files in the repo root — fine for a
-  for a small single-binary tool per the Go styleguide; the tracker
+  small single-binary tool per the Go styleguide; the tracker audit agrees
-  audit agrees
-- `go test` runs without `-race` — the repo mandates `CGO_ENABLED=0`
-  (pure-Go builds) and the race detector requires cgo

cancel_test.go

@@ -18,11 +18,21 @@ import (
 	"time"
 )
 
-// poolUnwind bounds how long a goroutine is given to leave a pool
+// This file gathers the tests for scan cancellation and worker-pool
-// after its context is cancelled. Only a failing run ever waits this
+// unwinding. Everything it exercises lives in scan.go, so by the repo's
-// long: a pool that ignored its cancellation parks forever, and this
+// convention of one test file per source file it would belong in
-// is what turns that into a failed assertion instead of a suite that
+// scan_test.go. It is kept separate on purpose: cancellation behaviour
-// hangs until the test binary's own timeout.
+// cuts across both the walk pool and the hash pool as a single concern,
+// and scan_test.go is already over 1,600 lines. That is the deliberate
+// exception the convention otherwise expects to be stated.
+
+// poolUnwind bounds how long a test waits for a cancellation to take
+// effect: for a goroutine to return or a channel to close once its
+// context is cancelled, or for a signal to cancel the scan's context.
+// Only a failing run waits this long, and the bound is what makes that
+// failure an assertion instead of a hang. A call made without it, as
+// most of this file's scans are, has no bound: a regression that parks
+// it is caught only as the test binary's own timeout.
 const poolUnwind = 2 * time.Second
 
 // walkClock is a context whose cancellation is driven by the scan's
@@ -33,9 +43,14 @@ const poolUnwind = 2 * time.Second
 //
 // The accounting behind the n chosen by each test: every blocking
 // channel operation in the walk selects on Done, so the walk spends
-// one consultation per file event plus a couple per directory, while
+// one consultation per file event plus a couple per directory. The
-// the index load that runs ahead of it spends a small fixed number
+// index load that runs ahead of it also consults Done, but a bounded
-// (three) whatever the record count.
+// number of times that does not grow with the record count. The tests
+// depend on that property, not on the bound's exact value: each test
+// sets n from the consultations of the walk, plus those of the hash
+// phase when it cancels mid-hash, far from both ends of the phase it
+// interrupts, so the cancellation lands inside that phase whatever the
+// record count.
 type walkClock struct {
 	n    int64
 	seen atomic.Int64
@@ -91,11 +106,14 @@ func (c *walkClock) Value(_ any) any {
 // directory still queued and only the handful already in flight can
 // emit anything more.
 const (
-	walkCancelDirs         = 100
+	walkCancelDirs        = 100
-	walkCancelFilesPerDir  = 20
+	walkCancelFilesPerDir = 20
-	walkCancelFiles        = walkCancelDirs * walkCancelFilesPerDir
+	walkCancelFiles       = walkCancelDirs * walkCancelFilesPerDir
-	walkCancelWorkers      = 4
+	walkCancelWorkers     = 4
-	walkCancelInFlightDirs = walkCancelWorkers * walkCancelFilesPerDir
+	// The most files the walkCancelWorkers directories already in
+	// flight when the scan is cancelled can still emit, at
+	// walkCancelFilesPerDir each. A file count, not a directory count.
+	walkCancelInFlightFiles = walkCancelWorkers * walkCancelFilesPerDir
 )
 
 // walkCancelAtDone is the consultation on which the fixture's context
@@ -158,6 +176,11 @@ func assertRecordsIntact(t *testing.T, db *sql.DB, before []string) {
 // unreachable, makes the scan carry its truncated view into the update
 // phase, which counts every record the walk never reached for removal.
 //
+// The syncScan call here is not bounded by poolUnwind: a regression
+// that left a worker pool parked would hang it, and that regression is
+// caught only by the test binary's own timeout, not by a quick
+// assertion.
+//
 //nolint:paralleltest // counts goroutines: must not run beside others
 func TestSyncScanCancelledMidWalkKeepsRecords(t *testing.T) {
 	dir := buildWalkCancelTree(t)
@@ -209,10 +232,11 @@ func assertWalkGuardAborted(t *testing.T, st scanStats, err error) {
 	}
 
 	// The workers drop every directory still queued once the scan is
-	// cancelled, so only the directories already in flight can add to
+	// cancelled, so only the files in the directories already in flight
-	// the census after the fact. A census beyond that bound would mean
+	// can add to the census after the fact. A census beyond that bound
-	// the cancellation was not observed where it should have been.
+	// would mean the cancellation was not observed where it should have
-	limit := walkCancelAtDone + walkCancelInFlightDirs
+	// been.
+	limit := walkCancelAtDone + walkCancelInFlightFiles
 	if st.unchanged > limit {
 		t.Errorf("census covers %d files, want at most %d: the walk kept "+
 			"taking directories off the queue after cancellation",
@@ -320,13 +344,15 @@ func storedPaths(t *testing.T, path string) []string {
 
 // TestRunScanInterrupted calls the scan entrypoint with a context that
 // is already cancelled, as when a signal arrives at once. It must return
-// errInterrupted promptly with its one line on stderr, leave the
+// errInterrupted promptly, with its line on stderr after the one naming
-// database valid and as it was, and leave nothing in the way of the
+// the database and nothing on stdout, leave the database valid and as
-// next scan, which must bring the database up to date.
+// it was, and leave nothing in the way of the next scan, which must
+// bring the database up to date.
 func TestRunScanInterrupted(t *testing.T) {
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
+	stdout := captureStdout(t)
 	stderr := captureStderr(t)
 	dir := buildSmokeTree(t)
 
@@ -364,11 +390,16 @@ func TestRunScanInterrupted(t *testing.T) {
 			err, errInterrupted)
 	}
 
-	want := "scan: interrupted after 0 files\n"
+	want := "scan: database " + path + " (from " + databaseEnv + ")\n" +
+		"scan: interrupted after 0 files\n"
 	if got := stderr()[shown:]; got != want {
 		t.Errorf("stderr = %q, want %q", got, want)
 	}
 
+	if got := stdout(); got != "" {
+		t.Errorf("stdout = %q, want nothing (data only)", got)
+	}
+
 	assertNoSidecars(t, path)
 
 	if got := storedPaths(t, path); !slices.Equal(got, before) {
@@ -391,12 +422,13 @@ func TestRunScanInterrupted(t *testing.T) {
 // TestRunScanInterruptedMidHash interrupts the scan entrypoint part-way
 // through its hash phase, after the database is open. It must return
 // errInterrupted, release the lock, end stderr with its line counting
-// every file the walk reached, close the database out of WAL mode, and
+// every file the walk reached, write nothing to stdout, close the
-// keep the records it hashed.
+// database out of WAL mode, and keep the records it hashed.
 func TestRunScanInterruptedMidHash(t *testing.T) {
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
+	stdout := captureStdout(t)
 	stderr := captureStderr(t)
 	dir := buildWalkCancelTree(t)
 
@@ -414,6 +446,10 @@ func TestRunScanInterruptedMidHash(t *testing.T) {
 		t.Errorf("stderr = %q, want it to end with %q", got, want)
 	}
 
+	if got := stdout(); got != "" {
+		t.Errorf("stdout = %q, want nothing (data only)", got)
+	}
+
 	assertNoSidecars(t, path)
 
 	db, err := openReportDatabase(t.Context(), path)
@@ -562,20 +598,49 @@ func TestSendEventAbandonsBlockedSend(t *testing.T) {
 	awaitReturn(t, done, "sendEvent")
 }
 
-// TestWalkWorkersDropQueuedDirs checks that cancelled walk workers keep
+// TestWalkOneDirStopsWhenCancelled checks that a cancelled scan stops
-// reading jobs and drop the directories rather than stopping their
+// reading a directory instead of going through the rest of its
-// read: the range over jobs has to run out for the pool to tear down
+// entries. A walk that kept going would return the subdirectory below
-// and close its event stream.
+// to descend into. Unlike a file event, that return is not a send the
-func TestWalkWorkersDropQueuedDirs(t *testing.T) {
+// cancellation can abandon, so the test catches the regression every
+// time.
+func TestWalkOneDirStopsWhenCancelled(t *testing.T) {
 	t.Parallel()
 
 	dir := t.TempDir()
-	writeEmptyFiles(t, dir, walkCancelFilesPerDir)
+
+	err := os.Mkdir(filepath.Join(dir, "sub"), 0o750)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Unbuffered and unread: on a cancelled scan every send gives up.
+	events := make(chan walkEvent)
+
+	subs := walkOneDir(cancelledContext(t), dirJob{path: dir}, false, events)
+	if len(subs) != 0 {
+		t.Errorf("cancelled walkOneDir returned %+v to descend into, "+
+			"want none", subs)
+	}
+}
+
+// TestWalkWorkersDropQueuedDirs checks that cancelled walk workers keep
+// reading jobs and drop the directories rather than stopping their
+// read: the range over jobs has to run out for the pool to tear down
+// and close its event stream. The queued directory does not exist, so
+// a worker that walked it anyway would send a warning before
+// walkOneDir's own cancellation check could stop it. On a cancelled
+// scan that send delivers or gives up at random, so with 64 jobs
+// queued the regression has a one in 2^64 chance of passing.
+func TestWalkWorkersDropQueuedDirs(t *testing.T) {
+	t.Parallel()
+
+	missing := filepath.Join(t.TempDir(), "missing")
 
 	jobs, _, events := startWalkWorkers(cancelledContext(t), 2, false)
 
-	for range 4 {
+	for range 64 {
-		jobs <- dirJob{path: dir}
+		jobs <- dirJob{path: missing}
 	}
 
 	close(jobs)
@@ -646,7 +711,11 @@ func TestDispatchDirsClosesJobsWhenCancelled(t *testing.T) {
 
 // TestFeedHashJobsClosesJobsWhenCancelled checks that the hash feeder
 // abandons the runs it has not queued yet and still closes the job
-// channel, which is what lets the workers' range terminate.
+// channel, which is what lets the workers' range terminate. The
+// receive on jobs below is not bounded: a feeder that returned without
+// closing jobs would leave that receive with no sender and no close, so
+// this regression is caught by the test binary's timeout rather than by
+// a bounded assertion.
 func TestFeedHashJobsClosesJobsWhenCancelled(t *testing.T) {
 	t.Parallel()
 
@@ -672,41 +741,84 @@ func TestFeedHashJobsClosesJobsWhenCancelled(t *testing.T) {
 // TestHashWorkerDropsQueuedRuns checks that a cancelled hash worker
 // keeps reading jobs and drops the runs rather than reading files
 // nobody wants the hashes of — while still letting the range run out
-// so the pool tears down. The queued run names a file that does not
+// so the pool tears down. The hash function records that it was
-// exist, so a worker that hashed it anyway would produce a result.
+// called, so a worker that hashed the queued run anyway is caught
+// every time.
 func TestHashWorkerDropsQueuedRuns(t *testing.T) {
 	t.Parallel()
 
 	done := make(chan struct{})
 	jobs := make(chan []fileRec, 1)
-	results := make(chan hashResult, 1)
+	results := make(chan hashResult)
 
-	run := []fileRec{{path: filepath.Join(t.TempDir(), "missing"), size: 1}}
+	jobs <- []fileRec{{path: filepath.Join(t.TempDir(), "missing"), size: 1}}
-
-	jobs <- run
 
 	close(jobs)
 
+	var hashed atomic.Bool
+
+	hash := func(path string, size int64) (string, string, string, error) {
+		hashed.Store(true)
+
+		return hashSignature(path, size)
+	}
+
 	go func() {
 		defer close(done)
 
-		hashWorker(cancelledContext(t), jobs, results, hashSignature)
+		hashWorker(cancelledContext(t), jobs, results, hash)
 	}()
 
 	awaitReturn(t, done, "hashWorker")
 
-	select {
+	if hashed.Load() {
-	case r := <-results:
+		t.Error("cancelled hash worker hashed the queued run, want it dropped")
-		t.Errorf("cancelled hash worker produced %+v, want the run dropped",
-			r)
-	default:
 	}
 }
 
+// TestHashWorkerAbandonsBlockedSend checks that a hash worker with a
+// result to deliver and nobody to deliver it to leaves once the scan
+// is cancelled, instead of holding the pool open. The scan tests do
+// not catch this: stop drains results, which frees a parked worker
+// anyway.
+func TestHashWorkerAbandonsBlockedSend(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	done := make(chan struct{})
+	jobs := make(chan []fileRec, 1)
+	// Unbuffered and unread, with jobs left open: the worker's only way
+	// out is the cancellation case beside its send.
+	results := make(chan hashResult)
+
+	jobs <- []fileRec{{path: filepath.Join(t.TempDir(), "missing"), size: 1}}
+
+	// The scan is cancelled while the worker hashes, so the worker has
+	// already passed the check that drops queued runs.
+	hash := func(path string, size int64) (string, string, string, error) {
+		cancel()
+
+		return hashSignature(path, size)
+	}
+
+	go func() {
+		defer close(done)
+
+		hashWorker(ctx, jobs, results, hash)
+	}()
+
+	awaitReturn(t, done, "hashWorker")
+}
+
 // TestHashPhaseCancelledReturnsContextError checks the result loop's
 // own exit: with the pool cancelled, no result will ever arrive, and
 // the loop must leave through the cancellation rather than wait for a
-// receive that cannot happen.
+// receive that cannot happen. This call is not bounded by poolUnwind: a
+// loop that dropped its cancellation case would block on that receive,
+// so the regression surfaces as the test binary's timeout rather than
+// as a bounded assertion.
 func TestHashPhaseCancelledReturnsContextError(t *testing.T) {
 	t.Parallel()
 

db.go

@@ -6,10 +6,13 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
+	"net/url"
 	"os"
 	"path/filepath"
 	"slices"
 	"strconv"
+	"strings"
+	"time"
 
 	"golang.org/x/sys/unix"
 	// The pure-Go SQLite driver, registered as "sqlite"; keeps cgo
@@ -33,21 +36,28 @@ const schemaVersion = 1
 // scan.
 const dbDirPerm = 0o755
 
+// dbFilePerm is the mode for a database file created by scan, the mode
+// SQLite gives a database file it creates.
+const dbFilePerm = 0o644
+
 // lockFilePerm is the mode for the scan lock file. Anyone who can open
 // the file can hold the lock and keep every scan from running, so it
 // is open to its owner only.
 const lockFilePerm = 0o600
 
 // createTableSQL is the schema applied to a fresh database. Paths are
-// BLOBs because Unix paths are raw bytes, not guaranteed UTF-8.
+// BLOBs because Unix paths are raw bytes, not guaranteed UTF-8. mtime
+// holds whole Unix seconds and mtime_nsec the nanoseconds within that
+// second.
 const createTableSQL = `
 CREATE TABLE files (
-    path    BLOB PRIMARY KEY,
+    path       BLOB PRIMARY KEY,
-    size    INTEGER NOT NULL,
+    size       INTEGER NOT NULL,
-    mtime   INTEGER NOT NULL,
+    mtime      INTEGER NOT NULL,
-    head    TEXT NOT NULL,
+    mtime_nsec INTEGER NOT NULL,
-    tail    TEXT NOT NULL,
+    head       TEXT NOT NULL,
-    content TEXT NOT NULL
+    tail       TEXT NOT NULL,
+    content    TEXT NOT NULL
 ) WITHOUT ROWID
 `
 
@@ -60,10 +70,11 @@ CREATE INDEX files_signature ON files (size, head, tail, content)
 // upsertSQL inserts one file record, replacing any existing record for
 // the same path.
 const upsertSQL = `
-INSERT INTO files (path, size, mtime, head, tail, content)
+INSERT INTO files (path, size, mtime, mtime_nsec, head, tail, content)
-VALUES (?, ?, ?, ?, ?, ?)
+VALUES (?, ?, ?, ?, ?, ?, ?)
 ON CONFLICT (path) DO UPDATE SET
     size = excluded.size, mtime = excluded.mtime,
+    mtime_nsec = excluded.mtime_nsec,
     head = excluded.head, tail = excluded.tail,
     content = excluded.content
 `
@@ -81,13 +92,36 @@ var errSchemaVersion = errors.New("unsupported database schema version")
 var errScanRunning = errors.New("another scan is running")
 
 // databasePath resolves the database location: SFDUPES_DATABASE when
-// set and non-empty, the compiled-in default otherwise.
+// set and non-empty, the compiled-in default otherwise. It returns the
-func databasePath() string {
+// path, with the working directory, its symlinks resolved, put in front
+// of it when it is relative, and where the path came from, "default" or
+// "from SFDUPES_DATABASE", for the line each subcommand prints first on
+// stderr.
+func databasePath() (string, string, error) {
+	path, source := defaultDatabasePath, "default"
 	if p := os.Getenv(databaseEnv); p != "" {
-		return p
+		path, source = p, "from "+databaseEnv
 	}
 
-	return defaultDatabasePath
+	if filepath.IsAbs(path) {
+		return path, source, nil
+	}
+
+	// The working directory as the kernel reports it, with no symlink
+	// in it. os.Getwd may return PWD instead, which can name it through
+	// a symlink; a ".." after that symlink then leads somewhere else
+	// once the path is cleaned, as scan cleans it to create the
+	// database's directory.
+	wd, err := unix.Getwd()
+	if err != nil {
+		return "", "", fmt.Errorf("resolve database path %s: %w", path, err)
+	}
+
+	// Not filepath.Abs or filepath.Join: they clean the path, which
+	// drops each ".." together with the directory name before it. When
+	// that directory is a symlink, the cleaned path names another file.
+	// The working directory ends in "/" only when it is the root.
+	return strings.TrimSuffix(wd, "/") + "/" + path, source, nil
 }
 
 // scanParams are the connection parameters for scan: read-write, with
@@ -107,7 +141,19 @@ const reportParams = "mode=ro" +
 // openDB opens the SQLite database at path with the connection
 // parameters params. It does not create or verify the schema.
 func openDB(path, params string) (*sql.DB, error) {
-	db, err := sql.Open("sqlite", "file:"+path+"?"+params)
+	// The path is escaped into a file: URI, so ?, # and % in it stay
+	// part of the file name. SQLite reads what follows file:// up to
+	// the next / as a host name, so an absolute path goes after an
+	// empty host (file:///abs) and a relative path goes without one
+	// (file:rel).
+	uri := url.URL{
+		Scheme:   "file",
+		OmitHost: !filepath.IsAbs(path),
+		Path:     path,
+		RawQuery: params,
+	}
+
+	db, err := sql.Open("sqlite", uri.String())
 	if err != nil {
 		return nil, fmt.Errorf("open database %s: %w", path, err)
 	}
@@ -122,19 +168,37 @@ func openDB(path, params string) (*sql.DB, error) {
 
 // lockScanDatabase takes the lock that keeps a second scan off the
 // database at path: an exclusive flock(2) on the file beside it named
-// path with ".lock" appended, created along with the database's parent
+// by the database's path with symlinks resolved and ".lock" appended,
-// directory if missing. A lock held by another scan fails at once
+// so every path to one database names the same lock file. If missing,
-// instead of waiting. The lock lasts until the returned file is closed
+// the database's parent directory and an empty database file are
-// or the process ends. The file is never deleted: a scan that deleted
+// created first, so the lock file is named the same way before the
-// it would let the next scan lock a new file while another still holds
+// database is set up as after. A lock held by another scan fails at
-// the old one.
+// once instead of waiting. The lock lasts until the returned file is
+// closed or the process ends. The lock file is never deleted: a scan
+// that deleted it would let the next scan lock a new file while
+// another still holds the old one.
 func lockScanDatabase(path string) (*os.File, error) {
 	err := os.MkdirAll(filepath.Dir(path), dbDirPerm)
 	if err != nil {
 		return nil, fmt.Errorf("create database directory: %w", err)
 	}
 
-	lockPath := path + ".lock"
+	// Like SQLite, this follows a symlink at path and creates its
+	// target. SQLite opens an empty file as a new database.
+	//nolint:gosec // the operator chooses the database path
+	dbFile, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE, dbFilePerm)
+	if err != nil {
+		return nil, fmt.Errorf("create database: %w", err)
+	}
+
+	_ = dbFile.Close()
+
+	resolved, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		return nil, fmt.Errorf("resolve database path: %w", err)
+	}
+
+	lockPath := resolved + ".lock"
 
 	//nolint:gosec // the operator chooses the database path
 	f, err := os.OpenFile(lockPath, os.O_RDWR|os.O_CREATE, lockFilePerm)
@@ -266,10 +330,10 @@ func initSchema(ctx context.Context, db *sql.DB) error {
 }
 
 // checkUnversioned checks a database at user_version 0 before it is
-// taken for an empty one. A database that already has a files table
+// taken for an empty one. createSchema creates the files table and
-// was not created by this build: a foreign or partially initialized
+// sets the version together, so a files table at version 0 was made by
-// file. Adopting it could corrupt unrelated data, so that is a
+// something else. Adopting it could corrupt unrelated data, so that is
-// schema-version error telling the operator to remove the file and
+// a schema-version error telling the operator to remove the file and
 // rescan.
 func checkUnversioned(ctx context.Context, db *sql.DB) error {
 	var name string
@@ -291,24 +355,39 @@ func checkUnversioned(ctx context.Context, db *sql.DB) error {
 }
 
 // createSchema applies the schema to a fresh database and stamps the
-// schema version.
+// schema version in one transaction, so a creation stopped partway, by
+// an interrupt or an error, leaves an empty database the next scan
+// sets up, never a files table at version 0, which checkUnversioned
+// refuses.
 func createSchema(ctx context.Context, db *sql.DB) error {
-	_, err := db.ExecContext(ctx, createTableSQL)
+	tx, err := db.BeginTx(ctx, nil)
 	if err != nil {
 		return fmt.Errorf("create schema: %w", err)
 	}
 
-	_, err = db.ExecContext(ctx, createIndexSQL)
+	defer func() { _ = tx.Rollback() }()
+
+	_, err = tx.ExecContext(ctx, createTableSQL)
 	if err != nil {
 		return fmt.Errorf("create schema: %w", err)
 	}
 
-	_, err = db.ExecContext(ctx,
+	_, err = tx.ExecContext(ctx, createIndexSQL)
+	if err != nil {
+		return fmt.Errorf("create schema: %w", err)
+	}
+
+	_, err = tx.ExecContext(ctx,
 		"PRAGMA user_version = "+strconv.Itoa(schemaVersion))
 	if err != nil {
 		return fmt.Errorf("set schema version: %w", err)
 	}
 
+	err = tx.Commit()
+	if err != nil {
+		return fmt.Errorf("create schema: %w", err)
+	}
+
 	return nil
 }
 
@@ -328,8 +407,8 @@ func userVersion(ctx context.Context, db *sql.DB) (int, error) {
 // which is the order of the primary key, so SQLite does not sort.
 func loadFileRows(ctx context.Context, db *sql.DB, fn func(r scanRec)) error {
 	rows, err := db.QueryContext(ctx,
-		"SELECT path, size, mtime, head, tail, content FROM files "+
+		"SELECT path, size, mtime, mtime_nsec, head, tail, content "+
-			"ORDER BY path")
+			"FROM files ORDER BY path")
 	if err != nil {
 		return fmt.Errorf("read records: %w", err)
 	}
@@ -338,17 +417,19 @@ func loadFileRows(ctx context.Context, db *sql.DB, fn func(r scanRec)) error {
 
 	for rows.Next() {
 		var (
-			path []byte
+			path      []byte
-			r    scanRec
+			sec, nsec int64
+			r         scanRec
 		)
 
-		err = rows.Scan(&path, &r.size, &r.mtime, &r.head, &r.tail,
+		err = rows.Scan(&path, &r.size, &sec, &nsec, &r.head, &r.tail,
 			&r.content)
 		if err != nil {
 			return fmt.Errorf("read record: %w", err)
 		}
 
 		r.path = string(path)
+		r.mtime = time.Unix(sec, nsec)
 		fn(r)
 	}
 
@@ -433,15 +514,27 @@ func loadDupeRows(ctx context.Context, db *sql.DB,
 	return records, nil
 }
 
+// countRecords returns the number of records in the database.
+func countRecords(ctx context.Context, db *sql.DB) (int64, error) {
+	var n int64
+
+	err := db.QueryRowContext(ctx, "SELECT COUNT(*) FROM files").Scan(&n)
+	if err != nil {
+		return 0, fmt.Errorf("count records: %w", err)
+	}
+
+	return n, nil
+}
+
 // loadFileMeta streams every record's path, size, mtime, and whether
 // it carries hashes to fn. Scan change detection needs no hash
 // values, and skipping the hash columns keeps the scan's in-memory
 // index small on multi-million-file databases.
 func loadFileMeta(ctx context.Context, db *sql.DB,
-	fn func(path string, size, mtime int64, hashed bool),
+	fn func(path string, size int64, mtime time.Time, hashed bool),
 ) error {
 	rows, err := db.QueryContext(ctx,
-		"SELECT path, size, mtime, head <> '' FROM files")
+		"SELECT path, size, mtime, mtime_nsec, head <> '' FROM files")
 	if err != nil {
 		return fmt.Errorf("read records: %w", err)
 	}
@@ -450,17 +543,17 @@ func loadFileMeta(ctx context.Context, db *sql.DB,
 
 	for rows.Next() {
 		var (
-			path        []byte
+			path            []byte
-			size, mtime int64
+			size, sec, nsec int64
-			hashed      int64
+			hashed          int64
 		)
 
-		err = rows.Scan(&path, &size, &mtime, &hashed)
+		err = rows.Scan(&path, &size, &sec, &nsec, &hashed)
 		if err != nil {
 			return fmt.Errorf("read record: %w", err)
 		}
 
-		fn(string(path), size, mtime, hashed != 0)
+		fn(string(path), size, time.Unix(sec, nsec), hashed != 0)
 	}
 
 	err = rows.Err()
@@ -471,26 +564,46 @@ func loadFileMeta(ctx context.Context, db *sql.DB,
 	return nil
 }
 
-// contentCandidatesSQL selects every record of at least headTailMin
+// contentGroupsSQL selects each group (the records sharing a size,
-// bytes whose size, head, and tail equal another record's, in each
+// head, and tail) of records of at least headTailMin bytes that has more
-// group (the records sharing a size, head, and tail) where at least one
+// than one record and at least one record without a content hash, with
-// record has no content hash, with whether each record has one. SQLite
+// the number of its records.
-// does the grouping, so no other record's hashes are loaded into
+const contentGroupsSQL = `
-// memory; the rows come ordered by size, head, and tail, so each
+SELECT size, head, tail, COUNT(*) AS records
-// group's rows arrive together.
+FROM files
+WHERE size >= ? AND head <> ''
+GROUP BY size, head, tail
+HAVING COUNT(*) > 1 AND SUM(content = '') > 0
+`
+
+// contentCandidatesSQL selects every record of the groups
+// contentGroupsSQL selects, with whether each record has a content
+// hash. SQLite does the grouping, so no other record's hashes are
+// loaded into memory; the rows come ordered by size, head, and tail, so
+// each group's rows arrive together.
 const contentCandidatesSQL = `
-SELECT f.path, f.size, f.mtime, f.head, f.tail, f.content <> ''
+SELECT f.path, f.size, f.mtime, f.mtime_nsec, f.head, f.tail, f.content <> ''
 FROM files AS f
-JOIN (
+JOIN (` + contentGroupsSQL + `) AS g USING (size, head, tail)
-    SELECT size, head, tail
-    FROM files
-    WHERE size >= ? AND head <> ''
-    GROUP BY size, head, tail
-    HAVING COUNT(*) > 1 AND SUM(content = '') > 0
-) AS g USING (size, head, tail)
 ORDER BY size, head, tail
 `
 
+// countContentCandidates returns the number of rows of
+// contentCandidatesSQL, adding up the records of the groups
+// contentGroupsSQL selects, so it neither joins nor sorts.
+func countContentCandidates(ctx context.Context, db *sql.DB) (int64, error) {
+	var n int64
+
+	err := db.QueryRowContext(ctx,
+		"SELECT COALESCE(SUM(records), 0) FROM ("+contentGroupsSQL+")",
+		headTailMin).Scan(&n)
+	if err != nil {
+		return 0, fmt.Errorf("count content candidates: %w", err)
+	}
+
+	return n, nil
+}
+
 // loadContentCandidates streams the rows of contentCandidatesSQL to fn:
 // each record, without its content hash, and whether it has one.
 func loadContentCandidates(ctx context.Context, db *sql.DB,
@@ -505,17 +618,20 @@ func loadContentCandidates(ctx context.Context, db *sql.DB,
 
 	for rows.Next() {
 		var (
-			path   []byte
+			path      []byte
-			r      scanRec
+			sec, nsec int64
-			hashed int64
+			r         scanRec
+			hashed    int64
 		)
 
-		err = rows.Scan(&path, &r.size, &r.mtime, &r.head, &r.tail, &hashed)
+		err = rows.Scan(&path, &r.size, &sec, &nsec, &r.head, &r.tail,
+			&hashed)
 		if err != nil {
 			return fmt.Errorf("read record: %w", err)
 		}
 
 		r.path = string(path)
+		r.mtime = time.Unix(sec, nsec)
 		fn(r, hashed != 0)
 	}
 
@@ -599,8 +715,8 @@ func execUpserts(ctx context.Context, tx *sql.Tx, upserts []scanRec,
 	defer func() { _ = st.Close() }()
 
 	for _, r := range upserts {
-		_, err = st.ExecContext(ctx,
+		_, err = st.ExecContext(ctx, []byte(r.path), r.size,
-			[]byte(r.path), r.size, r.mtime, r.head, r.tail, r.content)
+			r.mtime.Unix(), r.mtime.Nanosecond(), r.head, r.tail, r.content)
 		if err != nil {
 			return fmt.Errorf("upsert %s: %w", r.path, err)
 		}

db_test.go

@@ -10,13 +10,22 @@ import (
 	"slices"
 	"strings"
 	"testing"
+	"time"
 )
 
-// testDBPath returns a database path inside a fresh temp dir.
+// testDBPath returns a database path inside a fresh temp dir, with
+// symlinks resolved as the scan lock resolves them, so the lock file
+// is this path plus ".lock" even where the temp dir is reached through
+// a symlink.
 func testDBPath(t *testing.T) string {
 	t.Helper()
 
-	return filepath.Join(t.TempDir(), "db.sqlite")
+	dir, err := filepath.EvalSymlinks(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return filepath.Join(dir, "db.sqlite")
 }
 
 // openTestDB creates a fresh scan database in a temp dir.
@@ -34,16 +43,47 @@ func openTestDB(t *testing.T) *sql.DB {
 }
 
 func TestDatabasePath(t *testing.T) {
-	t.Setenv(databaseEnv, "")
+	// README §Database: SFDUPES_DATABASE when set and non-empty, the
-
+	// default otherwise, with the working directory, its symlinks
-	if got := databasePath(); got != defaultDatabasePath {
+	// resolved, put in front of a relative path. Nothing is cleaned, so
-		t.Errorf("databasePath() = %q, want %q", got, defaultDatabasePath)
+	// a ".." stays.
+	dir, err := filepath.EvalSymlinks(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
 	}
 
-	t.Setenv(databaseEnv, "/custom/place.sqlite")
+	t.Chdir(dir)
 
-	if got := databasePath(); got != "/custom/place.sqlite" {
+	fromEnv := "from " + databaseEnv
-		t.Errorf("databasePath() = %q, want the env override", got)
+	cases := []struct {
+		env, path, source string
+	}{
+		{"", defaultDatabasePath, "default"},
+		{"/custom/place.sqlite", "/custom/place.sqlite", fromEnv},
+		{"/custom/link/../place.sqlite", "/custom/link/../place.sqlite",
+			fromEnv},
+		{"sub/place.sqlite", dir + "/sub/place.sqlite", fromEnv},
+		{"link/../place.sqlite", dir + "/link/../place.sqlite", fromEnv},
+	}
+
+	for _, tc := range cases {
+		t.Setenv(databaseEnv, tc.env)
+
+		path, source, err := databasePath()
+		if err != nil || path != tc.path || source != tc.source {
+			t.Errorf("databasePath() with %s=%q = %q, %q, %v; want %q, %q",
+				databaseEnv, tc.env, path, source, err, tc.path, tc.source)
+		}
+	}
+
+	// In the root directory the path gets one slash in front, not two.
+	t.Chdir("/")
+	t.Setenv(databaseEnv, "place.sqlite")
+
+	path, _, err := databasePath()
+	if err != nil || path != "/place.sqlite" {
+		t.Errorf("databasePath() in / = %q, %v; want %q",
+			path, err, "/place.sqlite")
 	}
 }
 
@@ -114,6 +154,40 @@ func TestOpenDatabaseUnversionedForeign(t *testing.T) {
 	}
 }
 
+func TestSchemaCreationStoppedPartway(t *testing.T) {
+	t.Parallel()
+
+	// A first scan stopped while creating the schema must leave a
+	// database the next scan accepts. max_page_count(2) leaves room for
+	// the files table but not its index, so schema creation fails right
+	// after CREATE TABLE, a point an interrupt could also stop it at.
+	path := testDBPath(t)
+
+	db, err := openDB(path, scanParams+"&_pragma=max_page_count(2)")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = initSchema(t.Context(), db)
+	_ = db.Close()
+
+	if err == nil {
+		t.Fatal("initSchema with no room for the index succeeded")
+	}
+
+	db, err = openScanDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatalf("next scan: %v", err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	v, err := userVersion(t.Context(), db)
+	if err != nil || v != schemaVersion {
+		t.Fatalf("userVersion = %d, %v; want %d, nil", v, err, schemaVersion)
+	}
+}
+
 func TestOpenReportDatabaseMissing(t *testing.T) {
 	t.Parallel()
 
@@ -123,9 +197,11 @@ func TestOpenReportDatabaseMissing(t *testing.T) {
 	}
 }
 
-func TestOpenReportDatabaseVersionMismatch(t *testing.T) {
+func TestOpenDatabaseVersionMismatch(t *testing.T) {
 	t.Parallel()
 
+	// A database stamped with a schema version other than 0 and
+	// schemaVersion. report, trees and scan must all refuse it.
 	path := testDBPath(t)
 
 	db, err := openScanDatabase(t.Context(), path)
@@ -142,7 +218,12 @@ func TestOpenReportDatabaseVersionMismatch(t *testing.T) {
 
 	_, err = openReportDatabase(t.Context(), path)
 	if !errors.Is(err, errSchemaVersion) {
-		t.Fatalf("err = %v, want errSchemaVersion", err)
+		t.Fatalf("report: err = %v, want errSchemaVersion", err)
+	}
+
+	_, err = openScanDatabase(t.Context(), path)
+	if !errors.Is(err, errSchemaVersion) {
+		t.Fatalf("scan: err = %v, want errSchemaVersion", err)
 	}
 }
 
@@ -219,14 +300,19 @@ func TestApplyChangesRoundTrip(t *testing.T) {
 	// written.
 	recs := []scanRec{
 		{
-			size: 2, mtime: 20, head: "h2", tail: "t2", content: "c2",
+			size: 2, mtime: time.Unix(20, 999_999_999), head: "h2", tail: "t2",
-			path: "/a/tab\tnew\nline",
+			content: "c2", path: "/a/tab\tnew\nline",
+		},
+		{
+			size: 1, mtime: time.Unix(10, 0), head: "h1", tail: "t1",
+			content: "c1", path: "/a/x",
 		},
-		{size: 1, mtime: 10, head: "h1", tail: "t1", content: "c1", path: "/a/x"},
 	}
 
-	err := applyChanges(t.Context(), db, recs, nil,
+	prog := newProgress(progressParams{label: "update", total: 4})
-		newProgress("update", 2))
+	defer prog.finish()
+
+	err := applyChanges(t.Context(), db, recs, nil, prog)
 	if err != nil {
 		t.Fatalf("applyChanges: %v", err)
 	}
@@ -240,11 +326,12 @@ func TestApplyChangesRoundTrip(t *testing.T) {
 	// An upsert for an existing path updates in place; a delete
 	// removes exactly its path.
 	upd := scanRec{
-		size: 3, mtime: 30, head: "h3", tail: "t3", content: "c3", path: "/a/x",
+		size: 3, mtime: time.Unix(30, 0), head: "h3", tail: "t3", content: "c3",
+		path: "/a/x",
 	}
 
 	err = applyChanges(t.Context(), db, []scanRec{upd},
-		[]string{"/a/tab\tnew\nline"}, newProgress("update", 2))
+		[]string{"/a/tab\tnew\nline"}, prog)
 	if err != nil {
 		t.Fatalf("applyChanges: %v", err)
 	}
@@ -267,13 +354,15 @@ func TestApplyChangesBatching(t *testing.T) {
 	recs := make([]scanRec, 0, n)
 	for i := range n {
 		recs = append(recs, scanRec{
-			size: int64(i), mtime: 1, head: "h", tail: "t",
+			size: int64(i), mtime: time.Unix(1, 0), head: "h", tail: "t",
 			path: fmt.Sprintf("/batch/%07d", i),
 		})
 	}
 
-	err := applyChanges(t.Context(), db, recs, nil,
+	prog := newProgress(progressParams{label: "update", total: int64(2 * n)})
-		newProgress("update", int64(n)))
+	defer prog.finish()
+
+	err := applyChanges(t.Context(), db, recs, nil, prog)
 	if err != nil {
 		t.Fatalf("applyChanges: %v", err)
 	}
@@ -287,8 +376,7 @@ func TestApplyChangesBatching(t *testing.T) {
 		deletes = append(deletes, r.path)
 	}
 
-	err = applyChanges(t.Context(), db, nil, deletes,
+	err = applyChanges(t.Context(), db, nil, deletes, prog)
-		newProgress("update", int64(n)))
 	if err != nil {
 		t.Fatalf("applyChanges deletes: %v", err)
 	}
@@ -297,3 +385,62 @@ func TestApplyChangesBatching(t *testing.T) {
 		t.Fatalf("records = %d, want 0", len(got))
 	}
 }
+
+// TestCountContentCandidates checks that countContentCandidates counts
+// the records the content phase's search returns: those of each group
+// of two or more records of headTailMin or more with a head, where at
+// least one has no content hash.
+func TestCountContentCandidates(t *testing.T) {
+	t.Parallel()
+
+	db := openTestDB(t)
+
+	// Each group's records: size, head, and content, one per record.
+	groups := []struct {
+		size     int64
+		head     string
+		contents []string
+	}{
+		{headTailMin, "h", []string{"", "c", "c"}}, // returned
+		{headTailMin + 1, "h", []string{"", ""}},   // returned
+		{headTailMin + 2, "h", []string{"c", "c"}}, // all hashed
+		{headTailMin + 3, "h", []string{""}},       // one record
+		{headTailMin - 1, "h", []string{"", ""}},   // too small
+		{headTailMin + 4, "", []string{"", ""}},    // no head
+	}
+
+	var recs []scanRec
+
+	for _, g := range groups {
+		for _, content := range g.contents {
+			recs = append(recs, scanRec{
+				size: g.size, mtime: time.Unix(1, 0), head: g.head,
+				tail: "t", content: content,
+				path: fmt.Sprintf("/r/%d", len(recs)),
+			})
+		}
+	}
+
+	err := applyChanges(t.Context(), db, recs, nil, nil)
+	if err != nil {
+		t.Fatalf("applyChanges: %v", err)
+	}
+
+	got, err := countContentCandidates(t.Context(), db)
+	if err != nil {
+		t.Fatalf("countContentCandidates: %v", err)
+	}
+
+	var returned int64
+
+	err = loadContentCandidates(t.Context(), db,
+		func(scanRec, bool) { returned++ })
+	if err != nil {
+		t.Fatalf("loadContentCandidates: %v", err)
+	}
+
+	if got != 5 || returned != 5 {
+		t.Errorf("count = %d, records returned = %d, want 5 and 5",
+			got, returned)
+	}
+}

main.go

@@ -51,6 +51,10 @@ const (
 // cobra prints for it is the whole message.
 var errNoSubcommand = errors.New("no subcommand")
 
+// errWorkersBelowOne is the usage error for a scan --workers value
+// below 1.
+var errWorkersBelowOne = errors.New("--workers must be at least 1")
+
 // Version is the build version, injected at link time via -ldflags
 // (see the Makefile); "dev" for a plain go build.
 //
@@ -98,8 +102,7 @@ func run(args []string, stdout, stderr io.Writer) int {
 
 		return exitFatal
 	default:
-		// A usage error: cobra has already printed the message and
+		// A usage error, which cobra has already reported on stderr.
-		// the usage text.
 		return exitUsage
 	}
 }
@@ -154,6 +157,9 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 		Use:   cmdScan + " [--workers N] [-x] PATH...",
 		Short: "Walk trees and synchronize the scan database",
 		Args:  cobra.MinimumNArgs(1),
+		PreRunE: func(cmd *cobra.Command, _ []string) error {
+			return checkScanWorkers(cmd, scanWorkers)
+		},
 		RunE: runE(func(ctx context.Context, args []string) error {
 			ctx, stop := interruptContext(ctx)
 			defer stop()
@@ -189,6 +195,19 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 	return root
 }
 
+// checkScanWorkers rejects a scan --workers value below 1. That is a
+// usage error reported in one line: cobra prints the returned message
+// without the usage text, and run exits 2.
+func checkScanWorkers(cmd *cobra.Command, workers int) error {
+	if workers >= 1 {
+		return nil
+	}
+
+	cmd.SilenceUsage = true
+
+	return fmt.Errorf("%w, got %d", errWorkersBelowOne, workers)
+}
+
 // runE adapts a subcommand implementation, or the version print, to
 // cobra's RunE. Cobra prints the error and the command's usage text for
 // every error RunE returns, but a subcommand that ran and failed has no

main_test.go

@@ -8,6 +8,7 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"slices"
 	"strconv"
 	"strings"
 	"testing"
@@ -84,21 +85,41 @@ func makeReadOnly(t *testing.T, path string) {
 
 // captureStderr redirects os.Stderr to a file for the rest of the test
 // and returns a function reading back everything written to it. scan
-// writes its warnings and summary straight to os.Stderr, not to the
+// writes its warnings and summary, and report and trees their
-// stderr writer run is given.
+// summaries, straight to os.Stderr, not to the stderr writer run is
+// given.
 func captureStderr(t *testing.T) func() string {
 	t.Helper()
 
-	f, err := os.Create(filepath.Join(t.TempDir(), "stderr"))
+	return capture(t, &os.Stderr)
+}
+
+// captureStdout does for os.Stdout what captureStderr does for
+// os.Stderr. scan is never given run's stdout writer, so anything it
+// printed would go straight to os.Stdout. The scan tests pass os.Stdout
+// as run's stdout too, so the one capture sees both.
+func captureStdout(t *testing.T) func() string {
+	t.Helper()
+
+	return capture(t, &os.Stdout)
+}
+
+// capture redirects *std, which is os.Stdout or os.Stderr, to a file
+// for the rest of the test and returns a function reading back
+// everything written to it.
+func capture(t *testing.T, std **os.File) func() string {
+	t.Helper()
+
+	f, err := os.Create(filepath.Join(t.TempDir(), "output"))
 	if err != nil {
 		t.Fatal(err)
 	}
 
-	saved := os.Stderr
+	saved := *std
-	os.Stderr = f
+	*std = f
 
 	t.Cleanup(func() {
-		os.Stderr = saved
+		*std = saved
 
 		_ = f.Close()
 	})
@@ -183,30 +204,33 @@ func TestRunFatalAfterOpenClosesDatabase(t *testing.T) {
 	// sidecar check is evidence of the close only for scan: report and
 	// trees only read a database that is out of WAL mode, which leaves
 	// nothing on disk whether they close it or not.
-	cases := map[string][]string{
+	//
-		cmdScan:   {cmdScan},
+	// The subcommands come from the command tree, so a new one is
-		cmdReport: {cmdReport},
+	// checked too: one wired with a bare RunE instead of runE reports
-		cmdTrees:  {cmdTrees},
+	// its failure as a usage error, exit 2 with the usage text.
-	}
+	for _, cmd := range newRootCommand(io.Discard, io.Discard).Commands() {
+		name := cmd.Name()
 
-	for name, args := range cases {
 		t.Run(name, func(t *testing.T) {
 			path := brokenDatabase(t)
 			t.Setenv(databaseEnv, path)
 
+			args := []string{name}
 			if name == cmdScan {
 				args = append(args, t.TempDir())
 			}
 
-			var stdout, stderr bytes.Buffer
+			stdout := captureStdout(t)
 
-			code := run(args, &stdout, &stderr)
+			var stderr bytes.Buffer
+
+			code := run(args, os.Stdout, &stderr)
 			if code != exitFatal {
 				t.Errorf("run(%v) = %d, want %d", args, code, exitFatal)
 			}
 
 			assertNoSidecars(t, path)
-			assertFatalOutput(t, stderr.String(), stdout.String())
+			assertFatalOutput(t, stderr.String(), stdout())
 
 			// Proof that the failure happened after the open: only a
 			// query against the opened database can report this.
@@ -218,22 +242,24 @@ func TestRunFatalAfterOpenClosesDatabase(t *testing.T) {
 	}
 }
 
-func TestRunMissingOperandIsFatalNotUsage(t *testing.T) {
+func TestRunNonexistentPathIsFatalNotUsage(t *testing.T) {
 	// README §Error handling: a PATH operand that does not exist is a
 	// fatal error (1), not a usage error (2) — and a runtime failure
 	// must not dump the usage text.
 	t.Setenv(databaseEnv, testDBPath(t))
 
-	var stdout, stderr bytes.Buffer
+	stdout := captureStdout(t)
+
+	var stderr bytes.Buffer
 
 	missing := filepath.Join(t.TempDir(), "nope")
 
-	code := run([]string{cmdScan, missing}, &stdout, &stderr)
+	code := run([]string{cmdScan, missing}, os.Stdout, &stderr)
 	if code != exitFatal {
 		t.Errorf("run(scan %s) = %d, want %d", missing, code, exitFatal)
 	}
 
-	assertFatalOutput(t, stderr.String(), stdout.String())
+	assertFatalOutput(t, stderr.String(), stdout())
 }
 
 // assertFatalOutput checks that a fatal error was reported the way
@@ -257,6 +283,281 @@ func assertFatalOutput(t *testing.T, stderr, stdout string) {
 	}
 }
 
+func TestRunMissingDatabaseIsFatal(t *testing.T) {
+	// README §Database: report and trees need an existing database; a
+	// missing one exits 1 with a message telling the user to run scan,
+	// after the line naming the database.
+	for _, name := range []string{cmdReport, cmdTrees} {
+		t.Run(name, func(t *testing.T) {
+			path := testDBPath(t)
+			t.Setenv(databaseEnv, path)
+
+			var stdout bytes.Buffer
+
+			// run gets os.Stderr, where the subcommand prints its line,
+			// so the capture shows the two in the order printed.
+			stderr := captureStderr(t)
+
+			code := run([]string{name}, &stdout, os.Stderr)
+			if code != exitFatal {
+				t.Errorf("run(%s) = %d, want %d", name, code, exitFatal)
+			}
+
+			want := name + ": database " + path + " (from " + databaseEnv +
+				")\n" +
+				"sfdupes: " + path + ": no database (run \"sfdupes " +
+				"scan\" first, or set " + databaseEnv + ")\n"
+			if got := stderr(); got != want {
+				t.Errorf("stderr = %q, want %q", got, want)
+			}
+
+			if got := stdout.String(); got != "" {
+				t.Errorf("stdout = %q, want nothing (data only)", got)
+			}
+		})
+	}
+}
+
+func TestRunNamesRelativeDatabase(t *testing.T) {
+	// README §Database: each subcommand's first line on stderr names the
+	// database, a relative SFDUPES_DATABASE made absolute against the
+	// working directory. scan calls it new until a scan has created it.
+	path := testDBPath(t)
+	t.Chdir(filepath.Dir(path))
+	t.Setenv(databaseEnv, filepath.Base(path))
+
+	dir := t.TempDir()
+	from := " (from " + databaseEnv + ")\n"
+
+	want := "scan: new database " + path + from
+	if got := scanOK(t, dir); !strings.HasPrefix(got, want) {
+		t.Errorf("first scan stderr = %q, want it to start %q", got, want)
+	}
+
+	want = "scan: database " + path + from
+	if got := scanOK(t, dir); !strings.HasPrefix(got, want) {
+		t.Errorf("second scan stderr = %q, want it to start %q", got, want)
+	}
+
+	for _, name := range []string{cmdReport, cmdTrees} {
+		stderr := captureStderr(t)
+
+		code := run([]string{name}, io.Discard, os.Stderr)
+
+		want = name + ": database " + path + from
+		if got := stderr(); code != exitOK || !strings.HasPrefix(got, want) {
+			t.Errorf("run(%s) = %d with stderr %q, want %d and it to "+
+				"start %q", name, code, got, exitOK, want)
+		}
+	}
+}
+
+func TestRunUsesDatabaseThroughSymlinkedDirectory(t *testing.T) {
+	// README §Database: the path names the file exactly. With link a
+	// symlink to the directory real/sub, link/../db.sqlite names
+	// real/db.sqlite, not db.sqlite beside link. Every subcommand must
+	// use that file, relative or absolute, and its first line must name
+	// the path as set, with the working directory put in front of a
+	// relative one.
+	dir, err := filepath.EvalSymlinks(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	t.Chdir(dir)
+
+	err = os.MkdirAll(filepath.Join(dir, "real", "sub"), 0o750)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.Symlink(filepath.Join(dir, "real", "sub"),
+		filepath.Join(dir, "link"))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	named := dir + "/link/../db.sqlite"
+	from := " (from " + databaseEnv + ")\n"
+	tree := t.TempDir()
+
+	t.Setenv(databaseEnv, "link/../db.sqlite")
+
+	want := "scan: new database " + named + from
+	if got := scanOK(t, tree); !strings.HasPrefix(got, want) {
+		t.Errorf("relative scan stderr = %q, want it to start %q", got, want)
+	}
+
+	// The absolute path names the database the relative one created.
+	t.Setenv(databaseEnv, named)
+
+	want = "scan: database " + named + from
+	if got := scanOK(t, tree); !strings.HasPrefix(got, want) {
+		t.Errorf("absolute scan stderr = %q, want it to start %q", got, want)
+	}
+
+	for _, name := range []string{cmdReport, cmdTrees} {
+		stderr := captureStderr(t)
+
+		code := run([]string{name}, io.Discard, os.Stderr)
+
+		want = name + ": database " + named + from
+		if got := stderr(); code != exitOK || !strings.HasPrefix(got, want) {
+			t.Errorf("run(%s) = %d with stderr %q, want %d and it to "+
+				"start %q", name, code, got, exitOK, want)
+		}
+	}
+
+	_, err = os.Stat(filepath.Join(dir, "real", "db.sqlite"))
+	if err != nil {
+		t.Errorf("database the path names: %v", err)
+	}
+
+	// With no file at the cleaned path, report and trees succeeded on
+	// the database in real.
+	_, err = os.Stat(filepath.Join(dir, "db.sqlite"))
+	if !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("database at the cleaned path: stat error %v, want it "+
+			"missing", err)
+	}
+}
+
+func TestRunScanFromSymlinkedWorkingDirectory(t *testing.T) {
+	// README §Database: a relative path gets the working directory, its
+	// symlinks resolved, put in front of it. With home/proj a symlink
+	// to data/proj, entered as the working directory through the
+	// symlink, ../new/db.sqlite names data/new/db.sqlite. scan must
+	// create that directory and file, and nothing beside home/proj.
+	dir, err := filepath.EvalSymlinks(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.MkdirAll(filepath.Join(dir, "data", "proj"), 0o750)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.Mkdir(filepath.Join(dir, "home"), 0o750)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.Symlink(filepath.Join(dir, "data", "proj"),
+		filepath.Join(dir, "home", "proj"))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// t.Chdir also sets PWD to the path through the symlink, as a
+	// shell does after cd.
+	t.Chdir(filepath.Join(dir, "home", "proj"))
+	t.Setenv(databaseEnv, "../new/db.sqlite")
+
+	want := "scan: new database " + dir + "/data/proj/../new/db.sqlite" +
+		" (from " + databaseEnv + ")\n"
+	if got := scanOK(t, t.TempDir()); !strings.HasPrefix(got, want) {
+		t.Errorf("scan stderr = %q, want it to start %q", got, want)
+	}
+
+	_, err = os.Stat(filepath.Join(dir, "data", "new", "db.sqlite"))
+	if err != nil {
+		t.Errorf("database the path names: %v", err)
+	}
+
+	_, err = os.Lstat(filepath.Join(dir, "home", "new"))
+	if !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("home/new: stat error %v, want it missing", err)
+	}
+}
+
+func TestRunEscapesDatabasePath(t *testing.T) {
+	// README §Database: each subcommand's first line escapes the
+	// database path like the paths in a report, so a tab, newline or
+	// backslash in it keeps the line one line.
+	dir := t.TempDir()
+	t.Setenv(databaseEnv, dir+"/a\tb\nc\\d.sqlite")
+
+	escaped := dir + `/a\tb\nc\\d.sqlite`
+	from := " (from " + databaseEnv + ")\n"
+
+	want := "scan: new database " + escaped + from
+	if got := scanOK(t, t.TempDir()); !strings.HasPrefix(got, want) {
+		t.Errorf("scan stderr = %q, want it to start %q", got, want)
+	}
+
+	for _, name := range []string{cmdReport, cmdTrees} {
+		stderr := captureStderr(t)
+
+		code := run([]string{name}, io.Discard, os.Stderr)
+
+		want = name + ": database " + escaped + from
+		if got := stderr(); code != exitOK || !strings.HasPrefix(got, want) {
+			t.Errorf("run(%s) = %d with stderr %q, want %d and it to "+
+				"start %q", name, code, got, exitOK, want)
+		}
+	}
+}
+
+func TestRunNamesDefaultDatabase(t *testing.T) {
+	// README §Database: with SFDUPES_DATABASE empty, each subcommand's
+	// first line on stderr names the default database. A database may
+	// exist at the default path on the machine running the test, so
+	// nothing here may create or read one: scan gets an operand that
+	// does not exist, which stops it before it takes the lock, and
+	// report and trees a cancelled context, which stops them before
+	// they read anything.
+	t.Setenv(databaseEnv, "")
+
+	// Whether scan calls the database new depends on that machine too.
+	scanWant := "scan: database " + defaultDatabasePath + " (default)\n"
+
+	_, err := os.Stat(defaultDatabasePath)
+	if errors.Is(err, fs.ErrNotExist) {
+		scanWant = "scan: new database " + defaultDatabasePath +
+			" (default)\n"
+	}
+
+	missing := filepath.Join(t.TempDir(), "nope")
+
+	cases := map[string]struct {
+		run  func() error
+		want string
+	}{
+		cmdScan: {
+			run: func() error {
+				return runScan(t.Context(), []string{missing}, 1, false)
+			},
+			want: scanWant,
+		},
+		cmdReport: {
+			run: func() error {
+				return runReport(cancelledContext(t), io.Discard)
+			},
+			want: "report: database " + defaultDatabasePath + " (default)\n",
+		},
+		cmdTrees: {
+			run: func() error {
+				return runTrees(cancelledContext(t), io.Discard)
+			},
+			want: "trees: database " + defaultDatabasePath + " (default)\n",
+		},
+	}
+
+	for name, tc := range cases {
+		stderr := captureStderr(t)
+
+		err = tc.run()
+		if err == nil {
+			t.Errorf("%s: error = nil, want it stopped", name)
+		}
+
+		if got := stderr(); got != tc.want {
+			t.Errorf("%s stderr = %q, want %q", name, got, tc.want)
+		}
+	}
+}
+
 func TestRunUsageErrors(t *testing.T) {
 	// Usage errors keep exiting 2 with cobra's own report on stderr.
 	cases := map[string]struct {
@@ -295,6 +596,42 @@ func TestRunUsageErrors(t *testing.T) {
 	}
 }
 
+func TestRunScanRejectsWorkersBelowOne(t *testing.T) {
+	// README §scan mode: --workers below 1 is a usage error reported in
+	// one line on stderr, before the scan opens the database.
+	for _, workers := range []string{"0", "-1"} {
+		t.Run(workers, func(t *testing.T) {
+			dbPath := testDBPath(t)
+			t.Setenv(databaseEnv, dbPath)
+
+			var stdout, stderr bytes.Buffer
+
+			args := []string{cmdScan, "--workers", workers, t.TempDir()}
+
+			code := run(args, &stdout, &stderr)
+			if code != exitUsage {
+				t.Errorf("run(%v) = %d, want %d", args, code, exitUsage)
+			}
+
+			want := "Error: --workers must be at least 1, got " + workers +
+				"\n"
+			if got := stderr.String(); got != want {
+				t.Errorf("stderr = %q, want %q", got, want)
+			}
+
+			if got := stdout.String(); got != "" {
+				t.Errorf("stdout = %q, want nothing (data only)", got)
+			}
+
+			_, err := os.Stat(dbPath)
+			if !errors.Is(err, fs.ErrNotExist) {
+				t.Errorf("stat %s: %v, want the database never created",
+					dbPath, err)
+			}
+		})
+	}
+}
+
 func TestRunHelp(t *testing.T) {
 	t.Parallel()
 
@@ -398,17 +735,16 @@ func scanFixture(t *testing.T) []string {
 func scanOK(t *testing.T, operands ...string) string {
 	t.Helper()
 
-	var stdout bytes.Buffer
+	stdout := captureStdout(t)
-
 	stderr := captureStderr(t)
 
-	code := run(append([]string{cmdScan}, operands...), &stdout, os.Stderr)
+	code := run(append([]string{cmdScan}, operands...), os.Stdout, os.Stderr)
 	if code != exitOK {
 		t.Fatalf("run(scan %q) = %d, want %d; stderr: %s",
 			operands, code, exitOK, stderr())
 	}
 
-	if got := stdout.String(); got != "" {
+	if got := stdout(); got != "" {
 		t.Errorf("scan stdout = %q, want nothing (data only)", got)
 	}
 
@@ -416,10 +752,41 @@ func scanOK(t *testing.T, operands ...string) string {
 }
 
 func TestRunScanSucceedsDespiteWarnings(t *testing.T) {
+	// README §Error handling: a scan that skips a file it cannot read
+	// warns, counts the skip in its summary, and still exits 0, which
+	// scanOK checks along with the empty stdout.
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores file permissions")
+	}
+
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
-	scanFixture(t)
+	dir := t.TempDir()
+	writeFile(t, dir, "a.bin", pattern(1, 300))
+
+	// Same size as a.bin, so the scan reads it, and the read fails.
+	unreadable := writeFile(t, dir, "unreadable.bin", pattern(2, 300))
+
+	err := os.Chmod(unreadable, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	stderr := scanOK(t, dir)
+
+	warning := "hash " + unreadable + ": open " + unreadable +
+		": permission denied\n"
+	if !strings.Contains(stderr, warning) {
+		t.Errorf("stderr = %q, want %q", stderr, warning)
+	}
+
+	summary := "scan: 1 files seen (1 added, 0 updated, 0 removed, " +
+		"0 unchanged), 1 skipped\n"
+	if !strings.Contains(stderr, summary) {
+		t.Errorf("stderr = %q, want %q", stderr, summary)
+	}
+
 	assertNoSidecars(t, path)
 }
 
@@ -526,12 +893,14 @@ func TestRunReportSucceeds(t *testing.T) {
 
 	dupes := scanFixture(t)
 
-	var stdout, stderr bytes.Buffer
+	var stdout bytes.Buffer
 
-	code := run([]string{cmdReport}, &stdout, &stderr)
+	stderr := captureStderr(t)
+
+	code := run([]string{cmdReport}, &stdout, os.Stderr)
 	if code != exitOK {
 		t.Fatalf("run(report) = %d, want %d; stderr: %s",
-			code, exitOK, stderr.String())
+			code, exitOK, stderr())
 	}
 
 	want := "first\tdupe\tsize\n" + dupes[0] + "\t" + dupes[1] + "\t300\n"
@@ -539,6 +908,13 @@ func TestRunReportSucceeds(t *testing.T) {
 		t.Errorf("stdout = %q, want %q", got, want)
 	}
 
+	want = "report: database " + path + " (from " + databaseEnv + ")\n" +
+		"report: 2 records read, 1 duplicate groups, 1 dupe files, " +
+		"300 B reclaimable\n"
+	if got := stderr(); got != want {
+		t.Errorf("stderr = %q, want %q", got, want)
+	}
+
 	assertNoSidecars(t, path)
 }
 
@@ -548,12 +924,14 @@ func TestRunTreesSucceeds(t *testing.T) {
 
 	dupes := scanFixture(t)
 
-	var stdout, stderr bytes.Buffer
+	var stdout bytes.Buffer
 
-	code := run([]string{cmdTrees}, &stdout, &stderr)
+	stderr := captureStderr(t)
+
+	code := run([]string{cmdTrees}, &stdout, os.Stderr)
 	if code != exitOK {
 		t.Fatalf("run(trees) = %d, want %d; stderr: %s",
-			code, exitOK, stderr.String())
+			code, exitOK, stderr())
 	}
 
 	// The two directories holding the duplicate pair are duplicate
@@ -564,6 +942,13 @@ func TestRunTreesSucceeds(t *testing.T) {
 		t.Errorf("stdout = %q, want %q", got, want)
 	}
 
+	want = "trees: database " + path + " (from " + databaseEnv + ")\n" +
+		"trees: 2 records read, 1 duplicate tree groups, 1 dupe trees, " +
+		"300 B reclaimable\n"
+	if got := stderr(); got != want {
+		t.Errorf("stderr = %q, want %q", got, want)
+	}
+
 	assertNoSidecars(t, path)
 }
 
@@ -603,6 +988,73 @@ func TestRunReportsNeedOnlyReadAccess(t *testing.T) {
 	}
 }
 
+// assertRunsUseDatabase runs scan, then report and trees, against the
+// database that SFDUPES_DATABASE names, the file name in dir. It fails
+// unless the reports find the duplicate pair the scan recorded and dir
+// then holds only that file and its lock file: nothing was created
+// under a shortened name.
+func assertRunsUseDatabase(t *testing.T, dir, name string) {
+	t.Helper()
+
+	dupes := scanFixture(t)
+
+	want := "first\tdupe\tsize\n" + dupes[0] + "\t" + dupes[1] + "\t300\n"
+	if got := runStdout(t, cmdReport); got != want {
+		t.Errorf("report stdout = %q, want %q", got, want)
+	}
+
+	want = "first\tdupe\tfiles\tsize\n" +
+		filepath.Dir(dupes[0]) + "\t" + filepath.Dir(dupes[1]) + "\t1\t300\n"
+	if got := runStdout(t, cmdTrees); got != want {
+		t.Errorf("trees stdout = %q, want %q", got, want)
+	}
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	got := make([]string, 0, len(entries))
+	for _, e := range entries {
+		got = append(got, e.Name())
+	}
+
+	if wantFiles := []string{name, name + ".lock"}; !slices.Equal(got, wantFiles) {
+		t.Errorf("%s holds %q, want %q", dir, got, wantFiles)
+	}
+}
+
+func TestRunDatabasePathUsedAsGiven(t *testing.T) {
+	// README §Database: the path names the database file exactly. In
+	// SQLite's connection string an unescaped ? or # would end the file
+	// name and % would start an escape, and a path starting with //
+	// could be read as a host name. %25 is a valid escape, so unescaped
+	// this name opens a file named a without any error.
+	const name = "a?b#c%25d e.sqlite"
+
+	t.Run("absolute", func(t *testing.T) {
+		dir := t.TempDir()
+		t.Setenv(databaseEnv, filepath.Join(dir, name))
+
+		assertRunsUseDatabase(t, dir, name)
+	})
+
+	t.Run("leading double slash", func(t *testing.T) {
+		dir := t.TempDir()
+		t.Setenv(databaseEnv, "/"+filepath.Join(dir, name))
+
+		assertRunsUseDatabase(t, dir, name)
+	})
+
+	t.Run("relative", func(t *testing.T) {
+		dir := t.TempDir()
+		t.Chdir(dir)
+		t.Setenv(databaseEnv, name)
+
+		assertRunsUseDatabase(t, dir, name)
+	})
+}
+
 // holdScanLock takes the lock on the database at path, as a running
 // scan does, and holds it until the test ends. It fails the test when
 // the lock is already held.
@@ -619,16 +1071,18 @@ func holdScanLock(t *testing.T, path string) {
 
 func TestRunSecondScanFails(t *testing.T) {
 	// README §Database: while one scan holds the lock, a second scan
-	// fails at once, naming the lock file, without creating the
+	// fails at once, naming the lock file, without opening the
 	// database.
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
 	holdScanLock(t, path)
 
-	var stdout, stderr bytes.Buffer
+	stdout := captureStdout(t)
 
-	code := run([]string{cmdScan, t.TempDir()}, &stdout, &stderr)
+	var stderr bytes.Buffer
+
+	code := run([]string{cmdScan, t.TempDir()}, os.Stdout, &stderr)
 	if code != exitFatal {
 		t.Errorf("run(scan) = %d, want %d", code, exitFatal)
 	}
@@ -639,14 +1093,103 @@ func TestRunSecondScanFails(t *testing.T) {
 		t.Errorf("stderr = %q, want %q", got, want)
 	}
 
-	if got := stdout.String(); got != "" {
+	if got := stdout(); got != "" {
 		t.Errorf("stdout = %q, want nothing (data only)", got)
 	}
 
-	_, err := os.Stat(path)
+	// Taking the lock created the database file, empty; opening it as
-	if !errors.Is(err, fs.ErrNotExist) {
+	// a database would have written to it.
-		t.Errorf("stat %s = %v, want the database not created", path, err)
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
 	}
+
+	if info.Size() != 0 {
+		t.Errorf("database size = %d, want 0 (not opened)", info.Size())
+	}
+}
+
+// assertSecondScanFails runs a scan against the database
+// SFDUPES_DATABASE names while the test holds the lock on it. It fails
+// the test unless that scan fails at once, naming the lock file beside
+// path, the database's real path.
+func assertSecondScanFails(t *testing.T, path string) {
+	t.Helper()
+
+	var stderr bytes.Buffer
+
+	code := run([]string{cmdScan, t.TempDir()}, io.Discard, &stderr)
+	if code != exitFatal {
+		t.Errorf("run(scan) = %d, want %d", code, exitFatal)
+	}
+
+	want := "sfdupes: another scan is running (lock held on " +
+		path + ".lock)\n"
+	if got := stderr.String(); got != want {
+		t.Errorf("stderr = %q, want %q", got, want)
+	}
+}
+
+func TestRunSecondScanThroughSymlinkFails(t *testing.T) {
+	// README §Database: every path to one database names the same lock
+	// file, so while a scan holds it through one path, a scan through
+	// another fails, naming the lock file beside the database's real
+	// path.
+	t.Run("symlink to the database", func(t *testing.T) {
+		path := testDBPath(t)
+		t.Setenv(databaseEnv, path)
+
+		scanFixture(t)
+
+		link := filepath.Join(t.TempDir(), "link.sqlite")
+
+		err := os.Symlink(path, link)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		holdScanLock(t, path)
+		t.Setenv(databaseEnv, link)
+		assertSecondScanFails(t, path)
+	})
+
+	t.Run("symlink to its directory, no database yet", func(t *testing.T) {
+		path := testDBPath(t)
+		link := filepath.Join(t.TempDir(), "link")
+
+		err := os.Symlink(filepath.Dir(path), link)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		holdScanLock(t, path)
+		t.Setenv(databaseEnv, filepath.Join(link, filepath.Base(path)))
+		assertSecondScanFails(t, path)
+	})
+
+	t.Run("symlink whose target does not exist yet", func(t *testing.T) {
+		path := testDBPath(t)
+		link := filepath.Join(t.TempDir(), "link.sqlite")
+
+		err := os.Symlink(path, link)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		// The first scan takes the lock through the link before the
+		// database exists, then creates the database through it.
+		holdScanLock(t, link)
+
+		db, err := openScanDatabase(t.Context(), link)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		closeScanDatabase(t.Context(), db, link)
+
+		t.Setenv(databaseEnv, link)
+		assertSecondScanFails(t, path)
+	})
 }
 
 func TestRunScanReleasesLock(t *testing.T) {

package.json

@@ -0,0 +1,5 @@
+{
+  "devDependencies": {
+    "prettier": "3.8.1"
+  }
+}

progress.go

@@ -2,122 +2,272 @@ package main
 
 import (
 	"fmt"
+	"math"
 	"os"
+	"slices"
+	"strings"
+	"sync"
 	"time"
 
 	"github.com/schollz/progressbar/v3"
 	"golang.org/x/term"
 )
 
-// plainInterval is the minimum time between progress lines when stderr
+// plainInterval is the time between progress lines while a phase runs,
-// is not a TTY.
+// when stderr is not a TTY.
 const plainInterval = 5 * time.Second
 
-// barThrottle caps how often the TTY progress bar redraws.
+// redrawInterval is the time between redraws of the progress display on
-const barThrottle = 100 * time.Millisecond
+// a TTY.
+const redrawInterval = 100 * time.Millisecond
 
-// walkSpinnerType selects the progressbar library's spinner style used
+// spinnerType selects the progressbar library's spinner style.
-// for the walk pass, which has no known total.
+const spinnerType = 14
-const walkSpinnerType = 14
+
+// barWidth is the width of the progressbar library's bar between its
+// two ends, as in the example line in README "Progress".
+const barWidth = 10
 
 // percentScale converts a fraction to a percentage.
 const percentScale = 100
 
+// fallbackWidth is the width taken for a terminal whose width cannot be
+// read, as the progressbar library takes it.
+const fallbackWidth = 80
+
+// spinnerMargin is the columns of a spinner's line besides its text:
+// the spinner and the three spaces the library draws around the text,
+// and the terminal's last column, which every line stays clear of so
+// that no terminal wraps it.
+const spinnerMargin = 5
+
+// barMargin is the columns of a bar's line besides its text: the
+// percent and the bar the library draws after the text, the spaces
+// around them, and the terminal's last column.
+const barMargin = barWidth + 11
+
 // stderrIsTTY reports whether stderr is attached to a terminal.
 func stderrIsTTY() bool {
 	return term.IsTerminal(int(os.Stderr.Fd()))
 }
 
-// progress renders one scan pass's progress on stderr. On a TTY it
+// terminalWidth returns the width of the terminal on stderr, or
-// delegates to the progressbar library (spinner style when the total is
+// fallbackWidth, as the progressbar library does, when it cannot read
-// unknown, full bar with count/percent/rate/elapsed/ETA otherwise). When
+// one.
-// stderr is not a TTY it emits no ANSI redraws: it prints a plain
+func terminalWidth() int {
-// one-line update as the pass starts, then no more often than every
+	width, _, err := term.GetSize(int(os.Stderr.Fd()))
-// plainInterval.
+	if err != nil || width <= 0 {
-//
+		return fallbackWidth
-// All methods must be called from the main goroutine only. On a TTY
-// the library also redraws a spinner from its own goroutine, several
-// times a second, so its count and elapsed time stay current while a
-// pass waits for its next item. A nil *progress is a valid
-// no-display receiver: every method is a no-op, so batched database
-// flushes during the streaming pass can reuse the update-pass helpers
-// without rendering anything.
-type progress struct {
-	label string
-	total int64 // -1 when unknown (walk pass)
-	bar   *progressbar.ProgressBar
-	count int64
-	start time.Time
-	last  time.Time
-}
-
-func newProgress(label string, total int64) *progress {
-	p := &progress{label: label, total: total, start: time.Now()}
-	if stderrIsTTY() {
-		p.bar = newBar(label, total)
-
-		return p
 	}
 
-	// Print the zero state at once: the first item may take minutes,
+	return width
-	// and a pass must never look hung.
+}
-	p.last = p.start
+
-	fmt.Fprintln(os.Stderr, p.plainLine())
+// phaseLabel names phase with its place among phases, as "[2/5] walk".
+func phaseLabel(phases []string, phase string) string {
+	return fmt.Sprintf("[%d/%d] %s",
+		slices.Index(phases, phase)+1, len(phases), phase)
+}
+
+// progressParams describe one phase's progress display as it starts.
+type progressParams struct {
+	label      string // the phase and its place, from phaseLabel
+	total      int64  // the items the phase will complete; -1 when not known
+	estimate   bool   // total is an estimate, which the count may pass
+	waitingFor string // what the phase waits for until setTotal is called
+}
+
+// progress renders one phase's progress on stderr. On a TTY the
+// progressbar library draws line, fitted to the terminal's width: after
+// the library's spinner, or, for a phase with an exact total, before the
+// library's bar when the terminal has room for the bar beside it. It is
+// drawn again every redrawInterval, so its elapsed time keeps moving
+// while the phase waits for its next item. When stderr is not a TTY it
+// emits no ANSI redraws: it prints line as the phase starts, every
+// plainInterval while it runs, and as it ends.
+//
+// The draws come from a goroutine of their own, so mu guards the fields
+// below it. Every method must be called from the main goroutine. A nil
+// *progress is a valid no-display receiver: every method is a no-op, so
+// batched database flushes during the hash phase can reuse the update
+// phase's helpers without rendering anything.
+type progress struct {
+	width func() int    // reads the terminal's width; nil when not a TTY
+	stop  chan struct{} // closed by finish to end the draws
+	done  chan struct{} // closed once the draws have ended
+
+	mu         sync.Mutex
+	bar        *progressbar.ProgressBar // what the library draws; nil until then
+	withBar    bool                     // bar is the library's bar, not its spinner
+	widest     int                      // the widest line bar has drawn, in columns
+	label      string
+	total      int64
+	estimate   bool
+	waitingFor string
+	count      int64
+	start      time.Time // when the phase started, for the elapsed time
+	rateStart  time.Time // when the count started, for the rate
+}
+
+// newProgress starts the display of one phase on stderr.
+func newProgress(params progressParams) *progress {
+	if stderrIsTTY() {
+		return startProgress(params, terminalWidth, redrawInterval)
+	}
+
+	return startProgress(params, nil, plainInterval)
+}
+
+// startProgress shows the phase params describes at once, and again
+// every interval until finish: with the progressbar library on a
+// terminal, whose width each draw reads by calling width, or as a plain
+// line when width is nil.
+func startProgress(params progressParams, width func() int,
+	interval time.Duration,
+) *progress {
+	now := time.Now()
+	p := &progress{
+		width: width, stop: make(chan struct{}), done: make(chan struct{}),
+		label: params.label, total: params.total, estimate: params.estimate,
+		waitingFor: params.waitingFor, start: now, rateStart: now,
+	}
+
+	// Show the zero state at once: the first item may take minutes,
+	// and a phase must never look hung.
+	p.draw()
+
+	go func() {
+		defer close(p.done)
+
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+
+		for {
+			select {
+			case <-p.stop:
+				return
+			case <-ticker.C:
+				p.draw()
+			}
+		}
+	}()
 
 	return p
 }
 
-// newBar builds the TTY display for newProgress.
+// draw shows the phase's progress: on a TTY in place of the line
-func newBar(label string, total int64) *progressbar.ProgressBar {
+// before, and otherwise as a plain line.
-	opts := []progressbar.Option{
+func (p *progress) draw() {
-		progressbar.OptionSetWriter(os.Stderr),
+	p.mu.Lock()
-		progressbar.OptionSetDescription(label),
+	defer p.mu.Unlock()
-		progressbar.OptionShowCount(),
+
-		progressbar.OptionShowIts(),
+	if p.width == nil {
-		progressbar.OptionSetItsString("files"),
+		text, _ := p.line(math.MaxInt, true)
-		progressbar.OptionSetElapsedTime(true),
+		fmt.Fprintln(os.Stderr, text)
-		progressbar.OptionThrottle(barThrottle),
+
-		// Render at zero immediately: a phase must be visible the
+		return
-		// moment it starts, even before its first item completes.
-		progressbar.OptionSetRenderBlankState(true),
-	}
-	if total >= 0 {
-		opts = append(opts,
-			progressbar.OptionSetPredictTime(true),
-			progressbar.OptionShowElapsedTimeOnFinish(),
-		)
-	} else {
-		opts = append(opts,
-			progressbar.OptionSetPredictTime(false),
-			progressbar.OptionSpinnerType(walkSpinnerType),
-		)
 	}
 
-	return progressbar.NewOptions64(total, opts...)
+	width := p.width()
+
+	// A phase with an exact total gets the library's bar when its line,
+	// without the percent the bar shows, fits whole beside the bar. A
+	// total of 0 leaves the bar nothing to fill.
+	text, withBar := "", false
+	if p.total > 0 && !p.estimate {
+		text, withBar = p.line(width-barMargin, false)
+	}
+
+	margin := barMargin
+	if !withBar {
+		margin = spinnerMargin
+		text, _ = p.line(width-margin, true)
+	}
+
+	// The library makes a bar or a spinner, and before each draw erases
+	// its line with as many spaces as the widest line it has drawn. A
+	// display gets a new one when it turns from one to the other, as its
+	// line grows or the terminal is resized, and when the terminal has
+	// been made too narrow for that erase, which would wrap and leave a
+	// line behind at every draw.
+	if p.bar == nil || p.withBar != withBar || p.widest >= width {
+		p.newBar(withBar, width)
+	}
+
+	if withBar {
+		_ = p.bar.Set64(p.count)
+	}
+
+	p.bar.Describe(text)
+
+	// The library drew the text and its margin, less the terminal's last
+	// column, which the margin keeps clear.
+	p.widest = max(p.widest, len(text)+margin-1)
 }
 
-// increment records one completed item and refreshes the display.
+// newBar has the library make what draw draws: a bar for the phase's
+// total when withBar is set, and a spinner when not. Either shows the
+// text draw gives it, and nothing of its own besides the spinner, or
+// the bar and its percent. p.mu must be held.
+func (p *progress) newBar(withBar bool, width int) {
+	if p.bar != nil {
+		// Erase what was drawn before, short of the last column of a
+		// terminal that may have been made narrower since: the library's
+		// own erase is as wide as the widest line it drew.
+		blank := strings.Repeat(" ", min(p.widest, width-1))
+		fmt.Fprint(os.Stderr, "\r"+blank+"\r")
+	}
+
+	total := int64(-1) // the library's spinner
+	if withBar {
+		total = p.total
+	}
+
+	p.bar = progressbar.NewOptions64(total,
+		progressbar.OptionSetWriter(os.Stderr),
+		progressbar.OptionSetWidth(barWidth),
+		progressbar.OptionSpinnerType(spinnerType),
+		// The spinner turns at each draw, not on a timer of the
+		// library's own.
+		progressbar.OptionSetSpinnerChangeInterval(0),
+		// The text carries the elapsed time and the ETA.
+		progressbar.OptionSetElapsedTime(false),
+		progressbar.OptionSetPredictTime(false),
+	)
+	p.withBar, p.widest = withBar, 0
+}
+
+// setTotal gives a phase that started without a total its total, once
+// it is known. The rate, and so the ETA, count from then on: the time
+// spent waiting for the total says nothing about how fast items go.
+func (p *progress) setTotal(total int64) {
+	if p == nil {
+		return
+	}
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	p.total = total
+	p.rateStart = time.Now()
+}
+
+// increment records one completed item, which the display shows at its
+// next draw.
 func (p *progress) increment() {
 	if p == nil {
 		return
 	}
 
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
 	p.count++
-	if p.bar != nil {
-		_ = p.bar.Add(1)
-
-		return
-	}
-
-	if time.Since(p.last) >= plainInterval {
-		p.last = time.Now()
-		fmt.Fprintln(os.Stderr, p.plainLine())
-	}
 }
 
-// warnf prints a one-line warning to stderr without corrupting the bar.
+// warnf prints a one-line warning to stderr without corrupting the
-// The whole message is escaped like a report's path columns, so a path
+// display. The whole message is escaped like a report's path columns,
-// holding a newline cannot split the warning.
+// so a path holding a newline cannot split the warning.
 func (p *progress) warnf(format string, args ...any) {
 	if p == nil {
 		return
@@ -125,51 +275,101 @@ func (p *progress) warnf(format string, args ...any) {
 
 	msg := escapePath(fmt.Sprintf(format, args...))
 
-	if p.bar != nil && p.total < 0 {
+	p.mu.Lock()
-		// The library also redraws a spinner from its own goroutine, so
+	defer p.mu.Unlock()
-		// a direct write could land inside a redraw. The bar prints the
-		// warning itself, just before its next redraw.
-		_, _ = progressbar.Bprintln(p.bar, msg)
-
-		return
-	}
 
 	if p.bar != nil {
+		// The warning takes the display's line; the next draw shows
+		// the display again, on the line below.
 		_ = p.bar.Clear()
 	}
 
 	fmt.Fprintln(os.Stderr, msg)
 }
 
-// finish terminates the pass's display. A bar whose pass stopped short
+// finish ends the phase's display, drawn once more as the phase ends.
-// of its total, as an interrupted one does, is left as last drawn; the
+// A phase stopped short of its total, as an interrupted one is, shows
-// library's Finish would fill it up.
+// the count it stopped at rather than a full bar.
 func (p *progress) finish() {
 	if p == nil {
 		return
 	}
 
-	if p.bar != nil {
+	close(p.stop)
-		if p.total >= 0 && p.count < p.total {
+	<-p.done
-			_ = p.bar.Exit()
-		} else {
-			_ = p.bar.Finish()
-		}
 
+	p.draw()
+
+	if p.width != nil {
+		// The display stays on the TTY as drawn; what follows starts
+		// on a line of its own.
 		fmt.Fprintln(os.Stderr)
-
-		return
 	}
-
-	fmt.Fprintln(os.Stderr, p.plainLine())
 }
 
-// plainLine formats a non-TTY progress line.
+// line formats the phase's progress in at most room columns, as
-func (p *progress) plainLine() string {
+//
-	elapsed := time.Since(p.start)
+//	[3/5] hash: [1234/5000] 25%, 300 files/s, elapsed 4s, eta 13s
+//
+// without the percent when percent is false, as before the library's
+// bar, which shows its own. A phase with no total shows the items done
+// instead, or what it waits for.
+//
+// The phase and its place, the progress, the elapsed time and the ETA
+// are kept whole. A line wider than room leaves out the rate, or what
+// the phase waits for; only if it is still wider is it cut at room, and
+// line reports that it does not fit. Every part is ASCII, so its length
+// is its width in columns. p.mu must be held.
+func (p *progress) line(room int, percent bool) (string, bool) {
+	elapsed := time.Since(p.start).Round(time.Second)
+
+	// head and tail hold the parts kept whole; extra, between them, is
+	// the part left out.
+	var head, extra, tail string
+
+	if p.total < 0 && p.waitingFor != "" {
+		head, extra = p.label+": ", p.waitingFor
+		tail = fmt.Sprintf("elapsed %s, eta unknown", elapsed)
+	} else {
+		rate := 0.0
+		if s := time.Since(p.rateStart).Seconds(); s > 0 {
+			rate = float64(p.count) / s
+		}
+
+		head = p.label + ": " + p.itemsDone(percent) + ", "
+		extra = fmt.Sprintf("%.0f files/s", rate)
+		tail = fmt.Sprintf("elapsed %s, eta %s", elapsed, p.eta(rate))
+	}
+
+	full, kept := head+extra+", "+tail, head+tail
+
+	switch {
+	case len(full) <= room:
+		return full, true
+	case len(kept) <= room:
+		return kept, true
+	}
+
+	return kept[:max(room, 0)], false
+}
+
+// itemsDone formats the items done, as "[1234/5000] 25%", with "~"
+// before a total that is an estimate and without the percent when
+// percent is false, or as "1234 files" when the phase has no total.
+// p.mu must be held.
+func (p *progress) itemsDone(percent bool) string {
 	if p.total < 0 {
-		return fmt.Sprintf("%s: %d files, elapsed %s",
+		return fmt.Sprintf("%d files", p.count)
-			p.label, p.count, elapsed.Round(time.Second))
+	}
+
+	approx := ""
+	if p.estimate {
+		approx = "~"
+	}
+
+	done := fmt.Sprintf("[%d/%s%d]", p.count, approx, p.total)
+	if !percent {
+		return done
 	}
 
 	pct := float64(percentScale)
@@ -177,19 +377,24 @@ func (p *progress) plainLine() string {
 		pct = percentScale * float64(p.count) / float64(p.total)
 	}
 
-	rate := 0.0
+	return fmt.Sprintf("%s %.0f%%", done, pct)
-	if s := elapsed.Seconds(); s > 0 {
+}
-		rate = float64(p.count) / s
+
+// eta returns the time the phase has left at rate items a second, or
+// "unknown": with no total, before the first item, and once the count
+// passes an estimate. p.mu must be held.
+func (p *progress) eta(rate float64) string {
+	switch {
+	case p.total < 0, p.estimate && p.count > p.total:
+		return "unknown"
+	case p.count >= p.total:
+		return "0s"
+	case rate <= 0:
+		return "unknown"
 	}
-
-	eta := "?"
 
-	if rate > 0 && p.count <= p.total {
+	remaining := time.Duration(
-		remaining := time.Duration(float64(p.total-p.count) / rate * float64(time.Second))
+		float64(p.total-p.count) / rate * float64(time.Second))
-		eta = remaining.Round(time.Second).String()
-	}
 
-	return fmt.Sprintf("%s: [%d/%d] %.0f%% %.0f files/s elapsed %s eta %s",
+	return remaining.Round(time.Second).String()
-		p.label, p.count, p.total, pct, rate,
-		elapsed.Round(time.Second), eta)
 }

progress_test.go

@@ -1,16 +1,22 @@
 package main
 
 import (
+	"math"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
 	"time"
+	"unicode/utf8"
 )
 
-// spinnerIdle comfortably outlasts the 100ms interval at which the
+// testRedraw is the redraw interval the tests give a display, so that
-// progressbar library redraws a spinner from its own goroutine.
+// many redraws fit in a few milliseconds.
-const spinnerIdle = 500 * time.Millisecond
+const testRedraw = time.Millisecond
+
+// testDeadline bounds how long a test waits for a display to draw what
+// it expects.
+const testDeadline = 5 * time.Second
 
 //nolint:paralleltest // replaces the process-wide os.Stderr
 func TestStderrIsTTYFalseForNonTerminals(t *testing.T) {
@@ -54,59 +60,437 @@ func TestStderrIsTTYFalseForNonTerminals(t *testing.T) {
 	}
 }
 
-// TestNewProgressPrintsBeforeFirstItem checks that each pass shows its
+func TestPhaseLabel(t *testing.T) {
-// zero state the moment it starts when stderr is not a terminal, and
+	t.Parallel()
-// that the next line still waits for plainInterval.
-//
-//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
-func TestNewProgressPrintsBeforeFirstItem(t *testing.T) {
-	stderr := captureStderr(t)
 
-	newProgress("walk", -1).increment()
+	phases := []string{"load", "walk", "hash"}
-	newProgress("hash", 10).increment()
+	if got := phaseLabel(phases, "walk"); got != "[2/3] walk" {
-
+		t.Errorf("phaseLabel = %q, want %q", got, "[2/3] walk")
-	want := "walk: 0 files, elapsed 0s\n" +
-		"hash: [0/10] 0% 0 files/s elapsed 0s eta ?\n"
-	if got := stderr(); got != want {
-		t.Errorf("stderr = %q, want %q", got, want)
 	}
 }
 
-// newWalkSpinner returns the walk pass's terminal display, writing to
+// TestProgressLine checks the line a display shows in each state, ten
-// os.Stderr whether or not it is a terminal, and stops the library's
+// seconds into the phase.
-// redraws when the test ends.
+func TestProgressLine(t *testing.T) {
-func newWalkSpinner(t *testing.T) *progress {
+	t.Parallel()
+
+	ago := time.Now().Add(-10 * time.Second)
+
+	cases := []struct {
+		p    *progress
+		want string
+	}{{
+		p: &progress{
+			label: scanPhase("load"), total: -1,
+			waitingFor: "counting the records",
+		},
+		want: "[1/5] load: counting the records, elapsed 10s, eta unknown",
+	}, {
+		p:    &progress{label: scanPhase("hash"), total: 100, count: 20},
+		want: "[3/5] hash: [20/100] 20%, 2 files/s, elapsed 10s, eta 40s",
+	}, {
+		p:    &progress{label: scanPhase("hash"), total: 100},
+		want: "[3/5] hash: [0/100] 0%, 0 files/s, elapsed 10s, eta unknown",
+	}, {
+		p:    &progress{label: scanPhase("update"), total: 0},
+		want: "[4/5] update: [0/0] 100%, 0 files/s, elapsed 10s, eta 0s",
+	}, {
+		p: &progress{
+			label: scanPhase("walk"), total: 100, estimate: true, count: 20,
+		},
+		want: "[2/5] walk: [20/~100] 20%, 2 files/s, elapsed 10s, eta 40s",
+	}, {
+		// Past the estimate the walk cannot tell how long it has left.
+		p: &progress{
+			label: scanPhase("walk"), total: 100, estimate: true, count: 120,
+		},
+		want: "[2/5] walk: [120/~100] 120%, 12 files/s, elapsed 10s, " +
+			"eta unknown",
+	}, {
+		// A first scan's walk has no estimate.
+		p:    &progress{label: scanPhase("walk"), total: -1, count: 20},
+		want: "[2/5] walk: 20 files, 2 files/s, elapsed 10s, eta unknown",
+	}}
+
+	for _, tc := range cases {
+		tc.p.start, tc.p.rateStart = ago, ago
+
+		if got, _ := tc.p.line(math.MaxInt, true); got != tc.want {
+			t.Errorf("line = %q, want %q", got, tc.want)
+		}
+	}
+}
+
+// TestLineFitsRoom checks how a line is fitted to the room it has, ten
+// seconds into the phase: it leaves out the rate, or what the phase
+// waits for, and is cut only when what is left is still too wide.
+func TestLineFitsRoom(t *testing.T) {
+	t.Parallel()
+
+	ago := time.Now().Add(-10 * time.Second)
+	hash := &progress{
+		label: scanPhase("hash"), total: 100, count: 20,
+		start: ago, rateStart: ago,
+	}
+	content := &progress{
+		label: scanPhase("content"), total: -1,
+		waitingFor: "searching the database", start: ago, rateStart: ago,
+	}
+
+	cases := []struct {
+		p       *progress
+		room    int
+		percent bool
+		want    string
+		fits    bool
+	}{{
+		p: hash, room: 57, percent: true,
+		want: "[3/5] hash: [20/100] 20%, 2 files/s, elapsed 10s, eta 40s",
+		fits: true,
+	}, {
+		p: hash, room: 56, percent: true,
+		want: "[3/5] hash: [20/100] 20%, elapsed 10s, eta 40s",
+		fits: true,
+	}, {
+		p: hash, room: 45, percent: true,
+		want: "[3/5] hash: [20/100] 20%, elapsed 10s, eta 40",
+		fits: false,
+	}, {
+		// Before the library's bar, which shows the percent.
+		p: hash, room: 57, percent: false,
+		want: "[3/5] hash: [20/100], 2 files/s, elapsed 10s, eta 40s",
+		fits: true,
+	}, {
+		p: content, room: 40, percent: true,
+		want: "[5/5] content: elapsed 10s, eta unknown",
+		fits: true,
+	}}
+
+	for _, tc := range cases {
+		got, fits := tc.p.line(tc.room, tc.percent)
+		if got != tc.want || fits != tc.fits {
+			t.Errorf("line(%d, %t) = %q, %t, want %q, %t",
+				tc.room, tc.percent, got, fits, tc.want, tc.fits)
+		}
+	}
+}
+
+// TestSetTotalStartsRate checks that setTotal starts a phase's rate,
+// and so its ETA, from when the total becomes known, not from when the
+// phase started waiting for it.
+func TestSetTotalStartsRate(t *testing.T) {
+	t.Parallel()
+
+	waited := time.Now().Add(-20 * time.Second)
+	p := &progress{
+		label: scanPhase("load"), total: -1, start: waited, rateStart: waited,
+	}
+
+	p.setTotal(100)
+
+	// Ten seconds after the total came, without waiting ten seconds,
+	// 20 records are read.
+	p.start = p.start.Add(-10 * time.Second)
+	p.rateStart = p.rateStart.Add(-10 * time.Second)
+	p.count = 20
+
+	want := "[1/5] load: [20/100] 20%, 2 files/s, elapsed 30s, eta 40s"
+	if got, _ := p.line(math.MaxInt, true); got != want {
+		t.Errorf("line = %q, want %q", got, want)
+	}
+}
+
+// awaitOutput waits until stderr holds want at least times times, and
+// fails the test if it never does.
+func awaitOutput(t *testing.T, stderr func() string, want string,
+	times int,
+) {
 	t.Helper()
 
-	p := &progress{
+	deadline := time.Now().Add(testDeadline)
-		label: "walk", total: -1, start: time.Now(),
+	for strings.Count(stderr(), want) < times {
-		bar: newBar("walk", -1),
+		if time.Now().After(deadline) {
-	}
+			t.Fatalf("stderr = %q, want %q at least %d times",
-	t.Cleanup(p.finish)
+				stderr(), want, times)
+		}
 
-	return p
+		time.Sleep(testRedraw)
+	}
 }
 
-// TestProgressWarningsOnOwnLines drives the terminal display of the walk
+// TestPlainProgressPrintsAtStartAndEnd checks that when stderr is not a
-// pass through a run of warnings with no items between them, as when the
+// terminal a phase prints its line the moment it starts, before its
-// walk meets many unreadable paths, for several of the spinner's
+// first item, nothing for the items it completes before plainInterval
-// redraws: every warning must land on a line of its own, never inside a
+// has passed, and its line again as it ends.
-// redraw.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestPlainProgressPrintsAtStartAndEnd(t *testing.T) {
+	stderr := captureStderr(t)
+	p := newProgress(progressParams{label: scanPhase("hash"), total: 1000})
+
+	for range 1000 {
+		p.increment()
+	}
+
+	p.finish()
+
+	lines := strings.Split(strings.TrimSuffix(stderr(), "\n"), "\n")
+
+	want := "[3/5] hash: [0/1000] 0%, 0 files/s, elapsed 0s, eta unknown"
+	if len(lines) != 2 || lines[0] != want ||
+		!strings.HasPrefix(lines[1], "[3/5] hash: [1000/1000] 100%, ") {
+		t.Errorf("stderr lines = %q, want %q, then the line at 1000",
+			lines, want)
+	}
+}
+
+// TestPlainProgressPrintsWhileWaiting checks that a phase waiting with
+// no completed items still prints a line every interval.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestPlainProgressPrintsWhileWaiting(t *testing.T) {
+	stderr := captureStderr(t)
+	p := startProgress(progressParams{
+		label: scanPhase("load"), total: -1,
+		waitingFor: "counting the records",
+	}, nil, testRedraw)
+
+	awaitOutput(t, stderr,
+		"[1/5] load: counting the records, elapsed 0s, eta unknown\n", 3)
+	p.finish()
+}
+
+// lastFrame returns what a terminal shows of the frames a display drew:
+// the last one. The library starts each frame with a carriage return
+// and erases the previous one with spaces first.
+func lastFrame(out string) string {
+	var shown string
+
+	for frame := range strings.SplitSeq(out, "\r") {
+		if strings.TrimSpace(frame) != "" {
+			shown = frame
+		}
+	}
+
+	return shown
+}
+
+// TestTerminalRedrawsWhileWaiting checks that the terminal display of a
+// phase, spinner or bar, keeps being drawn while the phase waits for its
+// next item, with the elapsed time as of now, and shows every item
+// completed before the wait. stderr is not a terminal here, so the
+// displays take it to be fallbackWidth wide.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestTerminalRedrawsWhileWaiting(t *testing.T) {
+	stderr := captureStderr(t)
+
+	cases := []struct {
+		params progressParams
+		want   string // how the line shows a count of 50
+	}{
+		{progressParams{label: scanPhase("walk"), total: -1}, "50 files,"},
+		{progressParams{label: scanPhase("hash"), total: 100}, "[50/100],"},
+	}
+
+	for _, tc := range cases {
+		before := len(stderr())
+		since := func() string { return stderr()[before:] }
+		p := startProgress(tc.params, terminalWidth, testRedraw)
+
+		for range 50 {
+			p.increment()
+		}
+
+		// An hour into the phase, without waiting an hour.
+		p.mu.Lock()
+		p.start = p.start.Add(-time.Hour)
+		p.mu.Unlock()
+
+		awaitOutput(t, since, "elapsed 1h0m0s", 1)
+		p.finish()
+
+		if shown := lastFrame(since()); !strings.Contains(shown, tc.want) {
+			t.Errorf("terminal shows %q, want %q", shown, tc.want)
+		}
+	}
+}
+
+// drawLate draws the display params describes on a terminal width
+// columns wide as it starts and once more as it ends, with count items
+// done two and a half hours into the phase, and returns what it wrote
+// to stderr.
+func drawLate(stderr func() string, params progressParams, width int,
+	count int64,
+) string {
+	before := len(stderr())
+
+	// No timed draws come between the two.
+	p := startProgress(params, func() int { return width }, time.Hour)
+
+	// Without counting the items one by one or waiting the hours.
+	p.mu.Lock()
+	p.count = count
+	p.start = p.start.Add(-150 * time.Minute)
+	p.rateStart = p.start
+	p.mu.Unlock()
+
+	p.finish()
+
+	return stderr()[before:]
+}
+
+// TestTerminalLinesKeepETA checks the line each display shows on an
+// 80-column terminal at a large scan's counts and times: the rate is
+// left out, so that the elapsed time and the ETA stay whole.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestTerminalLinesKeepETA(t *testing.T) {
+	stderr := captureStderr(t)
+
+	cases := []struct {
+		params progressParams
+		want   string
+	}{{
+		// Past its estimate, the walk cannot tell how long it has left.
+		params: progressParams{
+			label: scanPhase("walk"), total: 1200000, estimate: true,
+		},
+		want: "[2/5] walk: [1234567/~1200000] 103%, elapsed 2h30m0s, " +
+			"eta unknown",
+	}, {
+		params: progressParams{label: scanPhase("hash"), total: 9876543},
+		want: "[3/5] hash: [1234567/9876543] 12%, elapsed 2h30m0s, " +
+			"eta 17h30m0s",
+	}, {
+		params: progressParams{label: scanPhase("content"), total: 9876543},
+		want: "[5/5] content: [1234567/9876543] 12%, elapsed 2h30m0s, " +
+			"eta 17h30m0s",
+	}}
+
+	for _, tc := range cases {
+		out := drawLate(stderr, tc.params, 80, 1234567)
+		if shown := lastFrame(out); !strings.Contains(shown, tc.want) {
+			t.Errorf("terminal shows %q, want %q", shown, tc.want)
+		}
+	}
+}
+
+// TestTerminalLinesFitWidth draws a large scan's bar display and a small
+// scan's, two and a half hours into the phase, on terminals from 120
+// columns down to 40, and checks that every line stays clear of the
+// terminal's last column. A line that reaches it wraps, and every
+// redraw then leaves a line behind. The bar is drawn where it has room,
+// as at 120 columns, and left out where it has none.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestTerminalLinesFitWidth(t *testing.T) {
+	stderr := captureStderr(t)
+
+	for _, width := range []int{120, 100, 80, 72, 60, 50, 40} {
+		for _, total := range []int64{9876543, 20000} {
+			params := progressParams{label: scanPhase("content"), total: total}
+			out := drawLate(stderr, params, width, total/8)
+
+			if width == 120 && !strings.Contains(out, "% |") {
+				t.Errorf("no bar on a terminal %d wide: %q", width, out)
+			}
+
+			lines := strings.FieldsFuncSeq(out, func(r rune) bool {
+				return r == '\r' || r == '\n'
+			})
+
+			for line := range lines {
+				if n := utf8.RuneCountInString(line); n >= width {
+					t.Errorf("a line of %d columns on a terminal %d wide: %q",
+						n, width, line)
+				}
+			}
+		}
+	}
+}
+
+// TestTerminalNarrowedRedrawsInPlace draws a large scan's display, two
+// and a half hours into the phase, on a terminal 120 columns wide, then
+// makes the terminal narrower than that line and draws it again a few
+// times. Nothing written after that, the erase before each redraw
+// included, may reach the narrower terminal's last column: it would
+// wrap, and every redraw would leave a line behind. At these widths the
+// spinner stays a spinner and the bar stays a bar.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestTerminalNarrowedRedrawsInPlace(t *testing.T) {
+	stderr := captureStderr(t)
+
+	cases := []struct {
+		params progressParams
+		narrow int
+	}{
+		{progressParams{label: scanPhase("walk"), total: -1}, 60},
+		{progressParams{label: scanPhase("hash"), total: 9876543}, 90},
+	}
+
+	for _, tc := range cases {
+		width := 120
+
+		// No timed draws: the test draws.
+		p := startProgress(tc.params, func() int { return width }, time.Hour)
+
+		p.mu.Lock()
+		p.count = 1234567
+		p.start = p.start.Add(-150 * time.Minute)
+		p.rateStart = p.start
+		p.mu.Unlock()
+
+		p.draw()
+
+		width = tc.narrow
+		before := len(stderr())
+
+		p.draw()
+		p.draw()
+		p.finish()
+
+		lines := strings.FieldsFuncSeq(stderr()[before:], func(r rune) bool {
+			return r == '\r' || r == '\n'
+		})
+
+		for line := range lines {
+			if n := utf8.RuneCountInString(line); n >= width {
+				t.Errorf("%d columns written on a terminal made %d wide: %q",
+					n, width, line)
+			}
+		}
+	}
+}
+
+// TestProgressWarningsOnOwnLines drives the terminal displays, spinner
+// and bar, through a run of warnings with no items between them, as when
+// the walk meets many unreadable paths, for many redraws: every warning
+// must land on a line of its own, never inside a redraw.
 //
 //nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
 func TestProgressWarningsOnOwnLines(t *testing.T) {
 	stderr := captureStderr(t)
-	p := newWalkSpinner(t)
 
-	// No pause between warnings: one written straight to stderr is
+	cases := []progressParams{
-	// garbled only if a redraw lands while it is being written.
+		{label: scanPhase("walk"), total: -1},
-	issued := 0
+		{label: scanPhase("hash"), total: 10},
-	for start := time.Now(); time.Since(start) < spinnerIdle; issued++ {
-		p.warnf("warning")
 	}
 
-	// The spinner prints the warnings at its next redraw.
+	issued := 0
-	time.Sleep(spinnerIdle)
+
+	for _, params := range cases {
+		p := startProgress(params, terminalWidth, testRedraw)
+
+		// No pause between warnings: one written straight to stderr is
+		// garbled only if a redraw lands while it is being written.
+		for start := time.Now(); time.Since(start) < 50*testRedraw; issued++ {
+			p.warnf("warning")
+		}
+
+		p.finish()
+	}
 
 	// A terminal shows each line as the text after its last carriage
 	// return.
@@ -129,61 +513,43 @@ func TestProgressWarningsOnOwnLines(t *testing.T) {
 	}
 }
 
-// TestSpinnerShowsCountAfterBurst checks that once a burst of items
+// TestTerminalStoppedShortKeepsCount checks that the terminal display
-// faster than the redraw limit is over, the walk display shows every
+// of a phase that stops before its total, as an interrupted one does,
-// item completed while it waits for the next one.
+// is left showing the count it stopped at rather than a full bar.
 //
 //nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
-func TestSpinnerShowsCountAfterBurst(t *testing.T) {
+func TestTerminalStoppedShortKeepsCount(t *testing.T) {
 	stderr := captureStderr(t)
-	p := newWalkSpinner(t)
+	p := startProgress(progressParams{label: scanPhase("hash"), total: 10},
-
+		terminalWidth, redrawInterval)
-	for range 50 {
-		p.increment()
-	}
-
-	time.Sleep(spinnerIdle)
-
-	if shown := lastFrame(stderr()); !strings.Contains(shown, "(50/-,") {
-		t.Errorf("terminal shows %q, want a count of 50", shown)
-	}
-}
-
-// lastFrame returns what a terminal shows of the frames a bar drew: the
-// last one. The library starts each frame with a carriage return and
-// erases the previous one with spaces first.
-func lastFrame(out string) string {
-	var shown string
-
-	for frame := range strings.SplitSeq(out, "\r") {
-		if strings.TrimSpace(frame) != "" {
-			shown = frame
-		}
-	}
-
-	return shown
-}
-
-// TestBarStoppedShortKeepsCount checks that the terminal display of a
-// pass that stops before its total, as an interrupted one does, is left
-// as last drawn instead of being filled up.
-//
-//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
-func TestBarStoppedShortKeepsCount(t *testing.T) {
-	stderr := captureStderr(t)
-	p := &progress{
-		label: "hash", total: 10, start: time.Now(),
-		bar: newBar("hash", 10),
-	}
 
 	p.increment()
-
-	// Past the redraw limit, so the bar draws the next count.
-	time.Sleep(2 * barThrottle)
 	p.increment()
 	p.finish()
 
-	if shown := lastFrame(stderr()); !strings.Contains(shown, "(2/10,") {
+	if shown := lastFrame(stderr()); !strings.Contains(shown, "[2/10],") {
 		t.Errorf("terminal shows %q, want a count of 2 of 10", shown)
 	}
 }
+
+// TestWarningAfterLastItemKeepsBar checks that a warning printed after
+// a phase's last item, as for a failed read of the last file, leaves the
+// phase's full bar on the terminal below the warning.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestWarningAfterLastItemKeepsBar(t *testing.T) {
+	stderr := captureStderr(t)
+	p := startProgress(progressParams{label: scanPhase("hash"), total: 2},
+		terminalWidth, testRedraw)
+
+	p.increment()
+	p.increment()
+
+	awaitOutput(t, stderr, "[2/2],", 1)
+	p.warnf("warning")
+	p.finish()
+
+	if shown := lastFrame(stderr()); !strings.Contains(shown, "[2/2],") {
+		t.Errorf("terminal shows %q, want a count of 2 of 2", shown)
+	}
+}

report.go

@@ -7,6 +7,7 @@ import (
 	"io"
 	"os"
 	"strings"
+	"time"
 )
 
 // ioBufSize is the buffer size for the buffered stdout writers.
@@ -21,7 +22,7 @@ const minGroupSize = 2
 // only and used by scan for change detection.
 type scanRec struct {
 	size    int64
-	mtime   int64
+	mtime   time.Time
 	head    string
 	tail    string
 	content string
@@ -33,9 +34,16 @@ type scanRec struct {
 // records, and each row is written as it is read, so no group is held
 // in memory. It never touches the scanned filesystem; its only I/O is
 // the database (with SQLite's temporary sort file), stdout, and stderr.
-// Any database problem, including a missing database, is fatal.
+// It names the database on stderr before it opens it. Any database
+// problem, including a missing database, is fatal.
 func runReport(ctx context.Context, stdout io.Writer) error {
-	dbPath := databasePath()
+	dbPath, source, err := databasePath()
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(os.Stderr, "report: database %s (%s)\n",
+		escapePath(dbPath), source)
 
 	db, err := openReportDatabase(ctx, dbPath)
 	if err != nil {

report_test.go

@@ -11,6 +11,7 @@ import (
 	"slices"
 	"strings"
 	"testing"
+	"time"
 )
 
 // awkwardDir is a directory name holding every byte the reports escape.
@@ -313,8 +314,14 @@ func TestDupeGroupsMtimeExcluded(t *testing.T) {
 	// mtime is informational only; records differing only in mtime
 	// still group together.
 	recs := []scanRec{
-		{size: 9, mtime: 100, head: "h", tail: "t", content: "c", path: "/m/1"},
+		{
-		{size: 9, mtime: 200, head: "h", tail: "t", content: "c", path: "/m/2"},
+			size: 9, mtime: time.Unix(100, 0), head: "h", tail: "t",
+			content: "c", path: "/m/1",
+		},
+		{
+			size: 9, mtime: time.Unix(200, 0), head: "h", tail: "t",
+			content: "c", path: "/m/2",
+		},
 	}
 
 	groups := dupeGroupsOf(t, recs)

scan.go

@@ -17,6 +17,7 @@ import (
 	"strings"
 	"sync"
 	"syscall"
+	"time"
 )
 
 // The duplicate ladder (see hashSignature and README "Duplicate
@@ -68,7 +69,7 @@ var errInterrupted = errors.New("scan interrupted")
 type fileRec struct {
 	path  string
 	size  int64
-	mtime int64
+	mtime time.Time
 	dev   uint64
 	ino   uint64
 }
@@ -79,18 +80,28 @@ type fileRec struct {
 // they would dominate the scan's memory.
 type fileMeta struct {
 	size   int64
-	mtime  int64
+	mtime  time.Time
 	hashed bool
 }
 
-// runScan implements the scan subcommand: four sequential phases —
+// scanPhase names one phase of a scan with its place among all of them,
-// walk (which stats each file as it is discovered), hash, update,
+// as "[2/5] walk", for the phase's progress display. The list here is
-// content — that synchronize the persistent database with the
+// the one place the phases are counted.
-// filesystem state under the PATH operands. Only files whose size at
+func scanPhase(name string) string {
-// least one other file shares are ever hashed: a size-unique file
+	return phaseLabel(
-// cannot be a duplicate. A file of headTailMin or more gets its content
+		[]string{"load", "walk", "hash", "update", "content"}, name)
-// hash only when its size, head, and tail match another file's. Flag
+}
-// parsing and the at-least-one-operand check are done by cobra. The
+
+// runScan implements the scan subcommand: five sequential phases —
+// load (which reads the existing records), walk (which stats each file
+// as it is discovered), hash, update, content — that synchronize the
+// persistent database with the filesystem state under the PATH
+// operands. Only files whose size at least one other file shares are
+// ever hashed: a size-unique file cannot be a duplicate. A file of
+// headTailMin or more gets its content hash only when its size, head,
+// and tail match another file's. Flag parsing and the
+// at-least-one-operand check are done by cobra. Before anything else,
+// the scan names the database on stderr, saying whether it is new. The
 // scan holds the lock on the database for its whole run, so a second
 // scan fails before it walks the filesystem or opens the database.
 // Errors are returned rather than exiting, so that the deferred close —
@@ -98,20 +109,31 @@ type fileMeta struct {
 // is released after it. When ctx is cancelled, as by the SIGINT or
 // SIGTERM that interruptContext catches, the scan keeps what it has
 // hashed (see syncScan), prints how many files its walk reached, and
-// returns errInterrupted.
+// returns errInterrupted. workers must be at least 1; the scan command
+// rejects anything less.
 func runScan(ctx context.Context, roots []string, workers int,
 	oneFS bool,
 ) error {
-	if workers < 1 {
+	dbPath, source, err := databasePath()
-		workers = 1
-	}
-
-	roots, err := resolveRoots(roots)
 	if err != nil {
 		return err
 	}
 
-	dbPath := databasePath()
+	// A database file missing now is created by lockScanDatabase below.
+	what := "database"
+
+	_, err = os.Stat(dbPath)
+	if errors.Is(err, fs.ErrNotExist) {
+		what = "new database"
+	}
+
+	fmt.Fprintf(os.Stderr, "scan: %s %s (%s)\n", what, escapePath(dbPath),
+		source)
+
+	roots, err = resolveRoots(roots)
+	if err != nil {
+		return err
+	}
 
 	lock, err := lockScanDatabase(dbPath)
 	if err != nil {
@@ -205,10 +227,16 @@ func resolveRoots(roots []string) ([]string, error) {
 }
 
 // pruneRoots drops operands already covered by another operand:
-// duplicates and any operand lying under another one. Every remaining
+// duplicates and any operand lying under another one. With -x, an
-// file is then reachable through exactly one root, so walked paths are
+// operand under another one is kept when the walk of the deepest kept
-// unique without keeping a scan-wide set of every path seen.
+// operand above it cannot reach it: when device puts any directory from
-func pruneRoots(roots []string) []string {
+// it (from its directory, for a regular file) up to but not including
+// that operand on a different filesystem than that operand. Every
+// remaining file is then reachable through exactly one root, so walked
+// paths are unique without keeping a scan-wide set of every path seen.
+func pruneRoots(roots []string, oneFS bool,
+	device func(path string) (uint64, bool),
+) []string {
 	// Shorter-first ordering guarantees an ancestor is kept before any
 	// operand under it is considered.
 	sorted := slices.Clone(roots)
@@ -223,14 +251,58 @@ func pruneRoots(roots []string) []string {
 	kept := make([]string, 0, len(sorted))
 
 	for _, r := range sorted {
-		if !underAnyRoot(r, kept) {
+		above := deepestRoot(r, kept)
+		if above == "" {
 			kept = append(kept, r)
+
+			continue
+		}
+
+		// Without -x, and always for a duplicate, r is dropped.
+		if !oneFS || above == r {
+			continue
+		}
+
+		aboveDev, aboveOK := device(above)
+		if !aboveOK {
+			continue
+		}
+
+		// The walk of above enters a directory only when it is on
+		// above's filesystem, and then reaches every regular file in it
+		// whatever device the file reports, so for a regular-file
+		// operand the directories checked start at its directory.
+		dir := r
+
+		fi, err := os.Lstat(r)
+		if err == nil && fi.Mode().IsRegular() {
+			dir = filepath.Dir(r)
+		}
+
+		for ; dir != above; dir = filepath.Dir(dir) {
+			dev, ok := device(dir)
+			if ok && dev != aboveDev {
+				kept = append(kept, r)
+
+				break
+			}
 		}
 	}
 
 	return kept
 }
 
+// deviceOfPath returns the filesystem device ID of the file at path,
+// when lstat succeeds and the platform exposes one.
+func deviceOfPath(path string) (uint64, bool) {
+	fi, err := os.Lstat(path)
+	if err != nil {
+		return 0, false
+	}
+
+	return deviceOfInfo(fi)
+}
+
 // scanStats summarizes one scan's database synchronization for the
 // final stderr summary, or for the line an interrupted scan prints.
 type scanStats struct {
@@ -280,31 +352,32 @@ func syncScan(ctx context.Context, db *sql.DB, roots []string,
 }
 
 // runPhases synchronizes the database with the filesystem under roots
-// in four sequential phases: walk (enumerate and stat every file,
+// in five sequential phases: load (read the existing records), walk
-// building a complete size census), hash (read only the new or
+// (enumerate and stat every file, building a complete size census),
-// changed — or previously unhashed — files whose size at least one
+// hash (read only the new or changed — or previously unhashed — files
-// other file shares, committing results in batches as they arrive),
+// whose size at least one other file shares, committing results in
-// update (record the size-unique files without reading them, and
+// batches as they arrive), update (record the size-unique files without
-// delete the records the scan no longer verifies), and content (fill
+// reading them, and delete the records the scan no longer verifies),
-// in the content hash of every record of headTailMin or more whose
+// and content (fill in the content hash of every record of headTailMin
-// size, head, and tail match another record's). Records outside the
+// or more whose size, head, and tail match another record's). Records
-// roots are never touched, except that the content phase fills in
+// outside the roots are never touched, except that the content phase
-// their content hash. Operands the walk cannot start from are dropped
+// fills in their content hash. Operands the walk cannot start from are
-// first, so the records beneath them count as outside the roots unless
+// dropped first, so the records beneath them are treated as if those
-// they lie under another root.
+// operands had not been given.
 func (s *scanState) runPhases(ctx context.Context, roots []string,
 	workers int, oneFS bool,
 ) error {
 	// Types are checked before pruning so that an operand under a
 	// dropped one is still scanned, not dropped as lying under it.
-	roots = pruneRoots(s.walkableRoots(roots))
+	roots = pruneRoots(s.walkableRoots(roots), oneFS, deviceOfPath)
 
 	err := s.loadIndex(ctx, roots)
 	if err != nil {
 		return err
 	}
 
-	changed, unhashed := s.walkPhase(startWalk(ctx, roots, oneFS, workers))
+	changed, unhashed := s.walkPhase(
+		startWalk(ctx, roots, oneFS, workers), roots)
 
 	// A cancelled walk stops early, so its size census covers only part
 	// of the roots, and every file it never reached would look vanished
@@ -332,10 +405,10 @@ func (s *scanState) runPhases(ctx context.Context, roots []string,
 // walkableRoots returns the operands the walk can start from: regular
 // files, and directories not named .zfs. Every other operand is warned
 // about, counted as skipped, and dropped. A dropped operand is no
-// longer a root, so the records stored beneath it count as outside the
+// longer a root, so the records stored beneath it are treated as if it
-// roots and are not deleted as unverified, unless it lies under another
+// had not been given: those under no other root count as outside the
-// root. An operand that fails lstat here is kept, and the walk warns
+// roots and are not deleted as unverified. An operand that fails lstat
-// about it.
+// here is kept, and the walk warns about it.
 func (s *scanState) walkableRoots(roots []string) []string {
 	kept := make([]string, 0, len(roots))
 
@@ -365,14 +438,25 @@ func (s *scanState) walkableRoots(roots []string) []string {
 // separately into the same database.
 func (s *scanState) loadIndex(ctx context.Context, roots []string) error {
 	// Indexing tens of millions of records takes real time; without a
-	// display the scan looks hung before the walk begins.
+	// display the scan looks hung before the walk begins. Counting them
-	prog := newProgress("load", -1)
+	// first gives the display its total.
+	prog := newProgress(progressParams{
+		label: scanPhase("load"), total: -1,
+		waitingFor: "counting the records",
+	})
 	defer prog.finish()
 
+	total, err := countRecords(ctx, s.db)
+	if err != nil {
+		return err
+	}
+
+	prog.setTotal(total)
+
 	s.existing = make(map[string]fileMeta)
 
 	return loadFileMeta(ctx, s.db,
-		func(path string, size, mtime int64, hashed bool) {
+		func(path string, size int64, mtime time.Time, hashed bool) {
 			prog.increment()
 
 			if underAnyRoot(path, roots) {
@@ -393,15 +477,36 @@ func (s *scanState) loadIndex(ctx context.Context, roots []string) error {
 // (the content phase may still fill in its content hash). It returns
 // the new-or-changed files and the unchanged files whose records lack
 // hashes; both remain candidates until the census decides whether
-// their sizes are shared.
+// their sizes are shared. A record below a directory -x did not enter
+// counts as outside the roots: it is not deleted, and its size joins
+// the census. That does not hold below a root at or inside that
+// directory, since that root's own walk verifies the records below it.
 func (s *scanState) walkPhase(
-	events <-chan walkEvent,
+	events <-chan walkEvent, roots []string,
 ) ([]fileRec, []fileRec) {
-	prog := newProgress("walk", -1)
+	// The records the last scan left under the roots estimate how many
+	// files the walk will find. A first scan has none, and no estimate.
+	estimate := int64(len(s.existing))
+	if estimate == 0 {
+		estimate = -1
+	}
 
-	var changed, unhashed []fileRec
+	prog := newProgress(progressParams{
+		label: scanPhase("walk"), total: estimate, estimate: true,
+	})
+
+	var (
+		changed, unhashed []fileRec
+		otherFSDirs       []string
+	)
 
 	for ev := range events {
+		if ev.otherFSDir != "" {
+			otherFSDirs = append(otherFSDirs, ev.otherFSDir)
+
+			continue
+		}
+
 		if ev.fail {
 			s.st.skipped++
 
@@ -418,7 +523,7 @@ func (s *scanState) walkPhase(
 		old, ok := s.existing[ev.rec.path]
 
 		switch {
-		case !ok || old.size != ev.rec.size || old.mtime < ev.rec.mtime:
+		case !ok || old.size != ev.rec.size || mtimeAfter(ev.rec.mtime, old.mtime):
 			changed = append(changed, ev.rec)
 		case old.hashed:
 			delete(s.existing, ev.rec.path)
@@ -431,6 +536,19 @@ func (s *scanState) walkPhase(
 
 	prog.finish()
 
+	for path, old := range s.existing {
+		// Kept only when a directory -x did not enter lies below the
+		// deepest root above the record. A root at or below that
+		// directory was walked on its own and did not find the file.
+		// Both contain the record, so the longer path is the deeper.
+		otherFSDir := deepestRoot(path, otherFSDirs)
+		if len(otherFSDir) > len(deepestRoot(path, roots)) {
+			delete(s.existing, path)
+
+			s.sizes = append(s.sizes, old.size)
+		}
+	}
+
 	return changed, unhashed
 }
 
@@ -546,10 +664,11 @@ func (s *scanState) hashPhase(ctx context.Context, workers int) error {
 }
 
 // readRuns reads runs with the worker pool, one read per inode run, in
-// the order given, under a progress display named label. The workers
+// the order given, under the progress display of the phase named label.
-// compute each run's hashes with hash, and each result goes to record;
+// The workers compute each run's hashes with hash, and each result goes
-// a run that fails to read is warned about and counted as skipped
+// to record; a run that fails to read is warned about and counted as
-// instead. The total counts actual reads, so the bar shows a real ETA.
+// skipped instead. The total counts actual reads, so the display shows
+// a real ETA.
 //
 // Returning early — a failed database write, or a cancelled scan — must
 // not strand the pool: the feeder would park forever on a full jobs
@@ -563,7 +682,9 @@ func (s *scanState) readRuns(ctx context.Context, workers int,
 	pool := startHashPool(ctx, runs, workers, hash)
 	defer pool.stop()
 
-	prog := newProgress(label, int64(len(runs)))
+	prog := newProgress(progressParams{
+		label: scanPhase(label), total: int64(len(runs)),
+	})
 	defer prog.finish()
 
 	for range runs {
@@ -650,7 +771,9 @@ func (s *scanState) updatePhase(ctx context.Context) error {
 	s.st.removed = len(deletes)
 
 	total := len(s.batch) + len(s.sentinels) + len(deletes)
-	prog := newProgress("update", int64(total))
+	prog := newProgress(progressParams{
+		label: scanPhase("update"), total: int64(total),
+	})
 
 	defer prog.finish()
 
@@ -731,16 +854,28 @@ func (s *scanState) contentPhase(ctx context.Context, workers int) error {
 func (s *scanState) contentCandidates(
 	ctx context.Context,
 ) ([]fileRec, map[string]scanRec, error) {
-	// The query and the checks take real time on a large database;
+	// The search and the checks take real time on a large database;
 	// without a display the scan looks hung before the reads begin.
-	prog := newProgress("content", -1)
+	// The display says it is searching until SQLite returns the first
+	// record. The checks start there, against a count of the records
+	// the search returns, and so do their rate and ETA.
+	prog := newProgress(progressParams{
+		label: scanPhase("content"), total: -1,
+		waitingFor: "searching the database",
+	})
 	defer prog.finish()
 
+	total, err := countContentCandidates(ctx, s.db)
+	if err != nil {
+		return nil, nil, err
+	}
+
 	var (
-		toRead []fileRec
+		searching = true // no record has been returned yet
-		first  scanRec   // the current group's first record
+		toRead    []fileRec
-		passed int       // the current group's files that passed the check
+		first     scanRec   // the current group's first record
-		unread []fileRec // those of them without a content hash
+		passed    int       // the current group's files that passed the check
+		unread    []fileRec // those of them without a content hash
 	)
 
 	recs := make(map[string]scanRec)
@@ -759,7 +894,13 @@ func (s *scanState) contentCandidates(
 		passed, unread = 0, nil
 	}
 
-	err := loadContentCandidates(ctx, s.db, func(r scanRec, hashed bool) {
+	err = loadContentCandidates(ctx, s.db, func(r scanRec, hashed bool) {
+		if searching {
+			searching = false
+
+			prog.setTotal(total)
+		}
+
 		prog.increment()
 
 		if r.size != first.size || r.head != first.head || r.tail != first.tail {
@@ -790,6 +931,11 @@ func (s *scanState) contentCandidates(
 		return nil, nil, err
 	}
 
+	// A search that returned no record still ends showing its count.
+	if searching {
+		prog.setTotal(total)
+	}
+
 	endGroup()
 
 	return toRead, recs, nil
@@ -810,7 +956,7 @@ func unchangedFile(r scanRec) (fileRec, bool, error) {
 	}
 
 	if !fi.Mode().IsRegular() || fi.Size() != r.size ||
-		fi.ModTime().Unix() > r.mtime {
+		mtimeAfter(fi.ModTime(), r.mtime) {
 		return fileRec{}, false, nil
 	}
 
@@ -821,6 +967,16 @@ func unchangedFile(r scanRec) (fileRec, bool, error) {
 	}, true, nil
 }
 
+// mtimeAfter reports whether mtime a is later than mtime b.
+// Not a.After(b): time.Time wraps an mtime past year 292 billion; Unix() undoes it.
+func mtimeAfter(a, b time.Time) bool {
+	if a.Unix() != b.Unix() {
+		return a.Unix() > b.Unix()
+	}
+
+	return a.Nanosecond() > b.Nanosecond()
+}
+
 // underAnyRoot reports whether path is any of the roots or lies under
 // one of them.
 func underAnyRoot(path string, roots []string) bool {
@@ -848,6 +1004,20 @@ func underRoot(path, root string) bool {
 	return strings.HasPrefix(path, prefix)
 }
 
+// deepestRoot returns the longest of the roots that path is or lies
+// under, or "" when it lies under none.
+func deepestRoot(path string, roots []string) string {
+	deepest := ""
+
+	for _, root := range roots {
+		if underRoot(path, root) && len(root) > len(deepest) {
+			deepest = root
+		}
+	}
+
+	return deepest
+}
+
 // dirJob is one directory awaiting traversal by the walk workers. It
 // carries its operand's filesystem device so -x can stop at
 // filesystem boundaries.
@@ -858,19 +1028,23 @@ type dirJob struct {
 }
 
 // walkEvent is one walk result delivered to the walk phase: a regular
-// file's statted record, or a warning when fail is set.
+// file's statted record, a warning when fail is set, or, when
+// otherFSDir is set, a directory -x did not enter because it is on
+// another filesystem than its operand.
 type walkEvent struct {
-	rec  fileRec
+	rec        fileRec
-	warn string
+	warn       string
-	fail bool
+	fail       bool
+	otherFSDir string
 }
 
 // startWalk seeds every root into the shared walk worker pool and
 // returns the event stream: one record per regular file, one warning
-// event per per-path error. The channel is closed when the walk
+// event per per-path error, and one event per directory -x did not
-// completes, and also when ctx is cancelled — every goroutine in the
+// enter. The channel is closed when the walk completes, and also when
-// pool abandons its blocking send in that case, so the consumer sees a
+// ctx is cancelled — every goroutine in the pool abandons its blocking
-// truncated but properly terminated stream instead of a stalled one.
+// send in that case, so the consumer sees a truncated but properly
+// terminated stream instead of a stalled one.
 func startWalk(ctx context.Context, roots []string, oneFS bool,
 	workers int,
 ) <-chan walkEvent {
@@ -937,7 +1111,8 @@ func operandWarning(root string, fi fs.FileInfo) string {
 // operand becomes an initial job. walkableRoots has already dropped
 // every other operand. One that has changed into something else since
 // is warned about and skipped here; it is still a root, so the records
-// stored beneath it are deleted as unverified.
+// stored beneath it, other than those under another root, are deleted
+// as unverified.
 func seedRoot(ctx context.Context, root string,
 	events chan<- walkEvent,
 ) []dirJob {
@@ -969,7 +1144,7 @@ func seedRoot(ctx context.Context, root string,
 	sendEvent(ctx, events, walkEvent{rec: fileRec{
 		path:  root,
 		size:  fi.Size(),
-		mtime: fi.ModTime().Unix(),
+		mtime: fi.ModTime(),
 		dev:   dev,
 		ino:   ino,
 	}})
@@ -1127,7 +1302,7 @@ func emitFile(ctx context.Context, p string, e fs.DirEntry,
 	sendEvent(ctx, events, walkEvent{rec: fileRec{
 		path:  p,
 		size:  info.Size(),
-		mtime: info.ModTime().Unix(),
+		mtime: info.ModTime(),
 		dev:   dev,
 		ino:   ino,
 	}})
@@ -1136,7 +1311,9 @@ func emitFile(ctx context.Context, p string, e fs.DirEntry,
 // subdirJob applies the descent rules to directory p: never enter
 // .zfs (ZFS snapshot pseudo-dirs would list every file once per
 // snapshot), and with -x never enter a directory on a different
-// filesystem than its operand.
+// filesystem than its operand, sending an event that names it so the
+// scan keeps the records below it, except those below an operand at or
+// inside it.
 func subdirJob(ctx context.Context, p string, e fs.DirEntry,
 	parent dirJob, oneFS bool, events chan<- walkEvent,
 ) (dirJob, bool) {
@@ -1160,6 +1337,8 @@ func subdirJob(ctx context.Context, p string, e fs.DirEntry,
 	}
 
 	if dev, ok := deviceOfInfo(info); ok && dev != parent.rootDev {
+		sendEvent(ctx, events, walkEvent{otherFSDir: p})
+
 		return dirJob{}, false
 	}
 
@@ -1301,6 +1480,38 @@ func hashWorker(ctx context.Context, jobs <-chan []fileRec,
 	}
 }
 
+// errNotRegular reports a path that is no longer a regular file when it
+// is opened to be read.
+var errNotRegular = errors.New("not a regular file")
+
+// openRegularFile opens path for reading and returns it only if it is
+// still a regular file, since the path may have been replaced after it
+// was statted. O_NONBLOCK keeps the open of a FIFO or a device node
+// from waiting forever, and fstat then rejects it. Reads of a regular
+// file ignore O_NONBLOCK.
+func openRegularFile(path string) (*os.File, error) {
+	//nolint:gosec // hashing operator-supplied paths is the tool's purpose
+	f, err := os.OpenFile(path, os.O_RDONLY|syscall.O_NONBLOCK, 0)
+	if err != nil {
+		return nil, err
+	}
+
+	fi, err := f.Stat()
+	if err != nil {
+		_ = f.Close()
+
+		return nil, err
+	}
+
+	if !fi.Mode().IsRegular() {
+		_ = f.Close()
+
+		return nil, errNotRegular
+	}
+
+	return f, nil
+}
+
 // emptyHash is the lowercase-hex SHA-256 of the empty input: the head,
 // tail, and content hash of every zero-length file.
 const emptyHash = "e3b0c44298fc1c149afbf4c8996fb924" +
@@ -1323,8 +1534,7 @@ func hashSignature(path string, size int64) (string, string, string, error) {
 		return emptyHash, emptyHash, emptyHash, nil
 	}
 
-	//nolint:gosec // hashing operator-supplied paths is the tool's purpose
+	f, err := openRegularFile(path)
-	f, err := os.Open(path)
 	if err != nil {
 		return "", "", "", err
 	}
@@ -1355,8 +1565,7 @@ func hashSignature(path string, size int64) (string, string, string, error) {
 // tail are returned empty, because the content phase keeps the ones its
 // records already hold.
 func hashContentOnly(path string, size int64) (string, string, string, error) {
-	//nolint:gosec // hashing operator-supplied paths is the tool's purpose
+	f, err := openRegularFile(path)
-	f, err := os.Open(path)
 	if err != nil {
 		return "", "", "", err
 	}

scan_test.go

@@ -6,8 +6,10 @@ import (
 	"crypto/sha256"
 	"database/sql"
 	"encoding/hex"
+	"errors"
 	"fmt"
 	"io"
+	"io/fs"
 	"os"
 	"os/signal"
 	"path/filepath"
@@ -18,6 +20,8 @@ import (
 	"syscall"
 	"testing"
 	"time"
+
+	"golang.org/x/sys/unix"
 )
 
 // writeFile creates a file with the given content and returns its path.
@@ -579,6 +583,65 @@ func TestScanContentHashedStalePartners(t *testing.T) {
 	}
 }
 
+// TestScanContentSameSecondRewrite is TestScanContentStalePartners for
+// a stored file rewritten in place at the same size with an mtime later
+// in the same second than recorded: the file counts as changed, so
+// neither it nor its match inside the operand is read.
+func TestScanContentSameSecondRewrite(t *testing.T) {
+	t.Parallel()
+
+	db := openTestDB(t)
+	dirA := t.TempDir()
+	changed := sparseFileWithoutMatch(t, dirA, "changed", headTailMin)
+
+	first := time.Date(2026, 1, 2, 3, 4, 5, 100_000_000, time.UTC)
+
+	err := os.Chtimes(changed, first, first)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	syncTree(t, db, dirA)
+
+	before := dbRecords(t, db)
+
+	// Rewrite one byte in place, keeping the size.
+	pokeAt(t, changed, headTailMin/2, []byte{1})
+
+	later := first.Add(500 * time.Millisecond)
+
+	err = os.Chtimes(changed, later, later)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dirB := t.TempDir()
+	sparseFile(t, dirB, "changed-copy", headTailMin)
+
+	st := syncTree(t, db, dirB)
+	if st != (scanStats{walked: 1, added: 1}) {
+		t.Errorf("stats = %+v, want 1 added and nothing skipped", st)
+	}
+
+	recs := dbRecords(t, db)
+	for _, r := range recs {
+		if r.content != "" {
+			t.Errorf("%s: content = %q, want none: its only match is stale",
+				r.path, r.content)
+		}
+	}
+
+	for _, old := range before {
+		if r := recordByPath(t, recs, old.path); r != old {
+			t.Errorf("record = %+v, want it left as %+v", r, old)
+		}
+	}
+
+	if groups := dupeGroups(t, db); len(groups) != 0 {
+		t.Errorf("groups = %+v, want none", groups)
+	}
+}
+
 // TestScanContentReadFailure checks that a failed content read is
 // counted as skipped and leaves the record without a content hash, and
 // that a later scan tries the read again.
@@ -781,8 +844,8 @@ func TestWalk(t *testing.T) {
 			t.Errorf("%s: size = %d, want 1..3", r.path, r.size)
 		}
 
-		if r.mtime <= 0 {
+		if r.mtime.Unix() <= 0 {
-			t.Errorf("%s: mtime = %d, want positive", r.path, r.mtime)
+			t.Errorf("%s: mtime = %v, want after 1970", r.path, r.mtime)
 		}
 	}
 }
@@ -912,6 +975,456 @@ func TestDeviceOfInfo(t *testing.T) {
 	}
 }
 
+// dirEntryFor returns the fs.DirEntry for name within dir, obtained via
+// the same os.ReadDir the walk uses, so it carries a real Info().
+func dirEntryFor(t *testing.T, dir, name string) fs.DirEntry {
+	t.Helper()
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	for _, e := range entries {
+		if e.Name() == name {
+			return e
+		}
+	}
+
+	t.Fatalf("entry %q not found in %q", name, dir)
+
+	return nil
+}
+
+// callSubdirJob runs subdirJob against e under parent, collecting any
+// events it emits (subdirJob emits at most one).
+func callSubdirJob(t *testing.T, p string, e fs.DirEntry,
+	parent dirJob, oneFS bool,
+) (dirJob, bool, []walkEvent) {
+	t.Helper()
+
+	events := make(chan walkEvent, 1)
+	job, ok := subdirJob(t.Context(), p, e, parent, oneFS, events)
+	close(events)
+
+	var evs []walkEvent
+	for ev := range events {
+		evs = append(evs, ev)
+	}
+
+	return job, ok, evs
+}
+
+// TestSubdirJobOneFilesystem exercises the -x boundary check in
+// subdirJob directly, so no second real filesystem is needed. The
+// subdirectory's real device is compared against a fabricated operand
+// device.
+func TestSubdirJobOneFilesystem(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+
+	sub := filepath.Join(dir, "sub")
+
+	err := os.Mkdir(sub, 0o750)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	info, err := os.Lstat(sub)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dev, ok := deviceOfInfo(info)
+	if !ok {
+		t.Skip("platform exposes no device id")
+	}
+
+	// A device the subdirectory is not on, standing in for an operand
+	// rooted on a different filesystem.
+	otherDev := dev + 1
+	e := dirEntryFor(t, dir, "sub")
+
+	cases := []struct {
+		name   string
+		oneFS  bool
+		parent dirJob
+		wantOK bool
+	}{
+		// -x on, subdirectory on a different device than its operand:
+		// descent is refused.
+		{"reject across boundary", true,
+			dirJob{rootDev: otherDev, rootDevOK: true}, false},
+		// -x on but the operand's own device is unknown: the boundary
+		// check is bypassed and descent proceeds.
+		{"bypass when root device unknown", true,
+			dirJob{rootDev: otherDev, rootDevOK: false}, true},
+		// Default (no -x): boundaries are crossed even onto a different
+		// device.
+		{"cross by default", false,
+			dirJob{rootDev: otherDev, rootDevOK: true}, true},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			job, ok, evs := callSubdirJob(t, sub, e, tc.parent, tc.oneFS)
+			if ok != tc.wantOK {
+				t.Fatalf("accepted = %v, want %v", ok, tc.wantOK)
+			}
+
+			// A refused descent names the directory, so the scan keeps
+			// the records below it.
+			var wantEvs []walkEvent
+			if !ok {
+				wantEvs = []walkEvent{{otherFSDir: sub}}
+			}
+
+			if !slices.Equal(evs, wantEvs) {
+				t.Fatalf("events = %+v, want %+v", evs, wantEvs)
+			}
+
+			// The accepted job must carry the operand's device down, or -x
+			// stops checking below the first level.
+			want := dirJob{
+				path:      sub,
+				rootDev:   tc.parent.rootDev,
+				rootDevOK: tc.parent.rootDevOK,
+			}
+			if ok && job != want {
+				t.Fatalf("job = %+v, want %+v", job, want)
+			}
+		})
+	}
+}
+
+// errInfoUnavailable is returned by errDirEntry.Info().
+var errInfoUnavailable = errors.New("info unavailable")
+
+// errDirEntry is a directory entry whose Info() always fails, driving
+// subdirJob's stat-error branch deterministically.
+type errDirEntry struct{ name string }
+
+func (e errDirEntry) Name() string { return e.name }
+func (errDirEntry) IsDir() bool    { return true }
+func (errDirEntry) Type() fs.FileMode {
+	return fs.ModeDir
+}
+
+func (errDirEntry) Info() (fs.FileInfo, error) {
+	return nil, errInfoUnavailable
+}
+
+// TestSubdirJobStatError asserts that when a subdirectory's Info()
+// fails under -x, subdirJob warns and refuses descent.
+func TestSubdirJobStatError(t *testing.T) {
+	t.Parallel()
+
+	p := "/does/not/matter/sub"
+
+	_, ok, evs := callSubdirJob(t, p, errDirEntry{name: "sub"},
+		dirJob{rootDev: 1, rootDevOK: true}, true)
+	if ok {
+		t.Fatal("descent accepted after stat error, want refused")
+	}
+
+	if len(evs) != 1 || !evs[0].fail || !strings.Contains(evs[0].warn, p) {
+		t.Fatalf("want one warning naming the path, got %+v", evs)
+	}
+}
+
+// syncOneFilesystem scans roots into db with -x and returns the scan
+// stats. Every device pruneRoots looks up, and the device each
+// operand's walk compares its subdirectories with, comes from devices
+// instead of from lstat, so a test can put a path on a filesystem that
+// no directory here is on. Unlike runPhases, it skips walkableRoots,
+// the check for a cancelled walk, and the content phase.
+func syncOneFilesystem(t *testing.T, db *sql.DB, roots []string,
+	devices map[string]uint64,
+) scanStats {
+	t.Helper()
+
+	device := func(path string) (uint64, bool) {
+		dev, ok := devices[path]
+
+		return dev, ok
+	}
+
+	roots = pruneRoots(roots, true, device)
+
+	ctx := t.Context()
+	s := &scanState{db: db}
+
+	err := s.loadIndex(ctx, roots)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	jobs, subdirs, events := startWalkWorkers(ctx, 2, true)
+
+	// seedRoot emits a regular-file operand itself and returns a job
+	// only for a directory operand.
+	var initial []dirJob
+
+	for _, root := range roots {
+		for _, job := range seedRoot(ctx, root, events) {
+			job.rootDev = devices[root]
+			initial = append(initial, job)
+		}
+	}
+
+	dispatchDirs(ctx, initial, jobs, subdirs)
+
+	changed, unhashed := s.walkPhase(events, roots)
+	s.partition(changed, unhashed)
+
+	err = s.hashPhase(ctx, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = s.updatePhase(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return s.st
+}
+
+// TestScanOneFilesystemKeepsOtherFilesystemRecords checks that with -x a
+// record below a directory the walk does not enter, because it is on
+// another filesystem than its operand, counts as outside the operands:
+// it is not deleted, and its size joins the size census. The record of
+// a gone file that is not below that directory is still deleted, even
+// when its path begins with the directory's name. The operand is given
+// a device that no directory here is on, so no second real filesystem
+// is needed.
+func TestScanOneFilesystemKeepsOtherFilesystemRecords(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	db := openTestDB(t)
+
+	// A scan without -x records the file below mnt, and mnt2, which is
+	// beside mnt, not below it.
+	mounted := writeFile(t, dir, "mnt/f", pattern(1, 100))
+	gone := writeFile(t, dir, "mnt2", pattern(3, 50))
+	syncTree(t, db, dir)
+
+	err := os.Remove(gone)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// The same size as mnt/f, so it is hashed only if mnt/f's size is
+	// in the census.
+	added := writeFile(t, dir, "added", pattern(2, 100))
+
+	info, err := os.Lstat(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dev, ok := deviceOfInfo(info)
+	if !ok {
+		t.Skip("platform exposes no device id")
+	}
+
+	syncOneFilesystem(t, db, []string{dir}, map[string]uint64{dir: dev + 1})
+
+	recs := dbRecords(t, db)
+	recordByPath(t, recs, mounted)
+
+	if recordByPath(t, recs, added).head == "" {
+		t.Errorf("%s not hashed: the census lacks the size of %s",
+			added, mounted)
+	}
+
+	if slices.Contains(recordPaths(recs), gone) {
+		t.Errorf("record for %s kept: the file is gone and not below mnt",
+			gone)
+	}
+}
+
+// TestScanOneFilesystemWalksNestedOperand checks that with -x an
+// operand under another one, on a different filesystem than it, is
+// walked on its own: a file added below it is recorded, and the record
+// of a file gone from below it is deleted. A record below a directory
+// that its own walk does not enter is still kept. Each operand is given
+// a device that no directory here is on, so neither walk enters a
+// subdirectory.
+func TestScanOneFilesystemWalksNestedOperand(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	db := openTestDB(t)
+
+	// A scan without -x records both files below mnt.
+	gone := writeFile(t, dir, "mnt/gone", pattern(1, 10))
+	kept := writeFile(t, dir, "mnt/sub/kept", pattern(2, 20))
+	syncTree(t, db, dir)
+
+	err := os.Remove(gone)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	added := writeFile(t, dir, "mnt/added", pattern(3, 30))
+
+	info, err := os.Lstat(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dev, ok := deviceOfInfo(info)
+	if !ok {
+		t.Skip("platform exposes no device id")
+	}
+
+	mnt := filepath.Join(dir, "mnt")
+	syncOneFilesystem(t, db, []string{dir, mnt},
+		map[string]uint64{dir: dev + 1, mnt: dev + 2})
+
+	paths := recordPaths(dbRecords(t, db))
+
+	if !slices.Contains(paths, added) {
+		t.Errorf("no record for %s: the walk did not reach %s", added, mnt)
+	}
+
+	if slices.Contains(paths, gone) {
+		t.Errorf("record for %s kept: the file is gone", gone)
+	}
+
+	if !slices.Contains(paths, kept) {
+		t.Errorf("record for %s deleted: the walk of %s did not enter %s",
+			kept, mnt, filepath.Dir(kept))
+	}
+}
+
+// TestScanOneFilesystemWalksOperandBelowOtherFilesystem checks that
+// with -x an operand on the same filesystem as the operand covering it
+// is walked on its own when a directory between them is on another
+// filesystem, since the walk of the covering operand does not enter
+// that directory: a file added below the nested operand is recorded,
+// and the record of a file gone from below it is deleted. A record
+// below that directory but outside the nested operand is still kept.
+// Both operands are given one device that no directory here is on,
+// while mnt keeps its own.
+func TestScanOneFilesystemWalksOperandBelowOtherFilesystem(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	db := openTestDB(t)
+
+	// A scan without -x records both files below mnt.
+	gone := writeFile(t, dir, "mnt/back/gone", pattern(1, 10))
+	kept := writeFile(t, dir, "mnt/kept", pattern(2, 20))
+	syncTree(t, db, dir)
+
+	err := os.Remove(gone)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	added := writeFile(t, dir, "mnt/back/added", pattern(3, 30))
+
+	info, err := os.Lstat(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dev, ok := deviceOfInfo(info)
+	if !ok {
+		t.Skip("platform exposes no device id")
+	}
+
+	mnt := filepath.Join(dir, "mnt")
+	back := filepath.Join(mnt, "back")
+	syncOneFilesystem(t, db, []string{dir, back},
+		map[string]uint64{dir: dev + 1, mnt: dev, back: dev + 1})
+
+	paths := recordPaths(dbRecords(t, db))
+
+	if !slices.Contains(paths, added) {
+		t.Errorf("no record for %s: the walk did not reach %s", added, back)
+	}
+
+	if slices.Contains(paths, gone) {
+		t.Errorf("record for %s kept: the file is gone", gone)
+	}
+
+	if !slices.Contains(paths, kept) {
+		t.Errorf("record for %s deleted: the walk of %s did not enter %s",
+			kept, dir, mnt)
+	}
+}
+
+// TestScanOneFilesystemRecordsNestedFileOnce checks that with -x a
+// regular-file operand under another operand is dropped when the file
+// reports a different device than that operand but its directory does
+// not, as a file bind-mounted into the tree does: the walk of the other
+// operand enters the directory and reaches the file, so the file is
+// recorded once.
+func TestScanOneFilesystemRecordsNestedFileOnce(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	db := openTestDB(t)
+	file := writeFile(t, dir, "sub/f", pattern(1, 10))
+
+	info, err := os.Lstat(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dev, ok := deviceOfInfo(info)
+	if !ok {
+		t.Skip("platform exposes no device id")
+	}
+
+	st := syncOneFilesystem(t, db, []string{dir, file}, map[string]uint64{
+		dir: dev, filepath.Dir(file): dev, file: dev + 1,
+	})
+
+	if st.added != 1 {
+		t.Errorf("%s recorded %d times, want once", file, st.added)
+	}
+}
+
+// TestScanOneFilesystemWalksNestedFileOperand checks that with -x a
+// regular-file operand under another operand is kept when its directory
+// is on a different filesystem than that operand: the walk of the other
+// operand does not enter the directory, so the file is recorded once,
+// as its own operand. The other operand is given a device that no
+// directory here is on.
+func TestScanOneFilesystemWalksNestedFileOperand(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	db := openTestDB(t)
+	file := writeFile(t, dir, "sub/f", pattern(1, 10))
+
+	info, err := os.Lstat(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dev, ok := deviceOfInfo(info)
+	if !ok {
+		t.Skip("platform exposes no device id")
+	}
+
+	st := syncOneFilesystem(t, db, []string{dir, file}, map[string]uint64{
+		dir: dev + 1, filepath.Dir(file): dev,
+	})
+
+	if st.added != 1 {
+		t.Errorf("%s recorded %d times, want once", file, st.added)
+	}
+}
+
 // buildSmokeTree recreates the README smoke-test filesystem layout
 // with deterministic content and returns the tree root.
 func buildSmokeTree(t *testing.T) string {
@@ -1073,6 +1586,69 @@ func TestScanPipeline(t *testing.T) {
 	assertSmokeTreeGroups(t, dir, db)
 }
 
+// TestScanProgressNamesEachPhase checks the plain progress lines of a
+// first scan, and of a rescan of one operand holding two of the
+// database's records. Each phase's first line names it with its place
+// among the five: load counts the records before reading them, the
+// content phase searches the database, and the walk estimates its total
+// from the records under its operand, or says its ETA is unknown when
+// there are none.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestScanProgressNamesEachPhase(t *testing.T) {
+	stderr := captureStderr(t)
+	dir := buildSmokeTree(t)
+	db := openTestDB(t)
+
+	syncTree(t, db, dir)
+
+	first := stderr()
+
+	syncTree(t, db, filepath.Join(dir, "a"))
+
+	rescan := stderr()[len(first):]
+	load := "[1/5] load: counting the records, elapsed 0s, eta unknown"
+	content := "[5/5] content: searching the database, elapsed 0s, eta unknown"
+	cases := map[string][]string{
+		first: {
+			load, "[2/5] walk: 0 files, 0 files/s, elapsed 0s, eta unknown",
+			"[3/5] hash: [0/", "[4/5] update: [0/", content,
+		},
+		rescan: {
+			load, "[2/5] walk: [0/~2] 0%, 0 files/s, elapsed 0s, eta unknown",
+			"[3/5] hash: [0/", "[4/5] update: [0/", content,
+		},
+	}
+
+	for out, want := range cases {
+		var got []string
+
+		for line := range strings.Lines(out) {
+			label, _, _ := strings.Cut(line, ":")
+			if len(got) == 0 || !strings.HasPrefix(got[len(got)-1], label) {
+				got = append(got, line)
+			}
+		}
+
+		if len(got) != len(want) {
+			t.Fatalf("first lines of the phases = %q, want %q", got, want)
+		}
+
+		for i := range want {
+			if !strings.HasPrefix(got[i], want[i]) {
+				t.Errorf("phase %d starts %q, want %q", i+1, got[i], want[i])
+			}
+		}
+	}
+
+	// The load phase's total is the count of the records.
+	loaded := fmt.Sprintf("\n[1/5] load: [%d/%d] 100%%, ",
+		smokeTreeFiles, smokeTreeFiles)
+	if !strings.Contains(rescan, loaded) {
+		t.Errorf("rescan stderr = %q, want %q", rescan, loaded)
+	}
+}
+
 func TestSyncScanUnchangedReuse(t *testing.T) {
 	t.Parallel()
 
@@ -1130,11 +1706,172 @@ func TestSyncScanMtimeBump(t *testing.T) {
 		t.Fatalf("mtime-bump stats = %+v, want 1 updated", st)
 	}
 
-	if r := recordByPath(t, dbRecords(t, db), a); r.mtime != future.Unix() {
+	if r := recordByPath(t, dbRecords(t, db), a); !r.mtime.Equal(future) {
-		t.Fatalf("mtime = %d, want %d", r.mtime, future.Unix())
+		t.Fatalf("mtime = %v, want %v", r.mtime, future)
 	}
 }
 
+// assertWholeFileHashed fails unless the record for path holds the
+// whole-file hash of data as its head, tail, and content.
+func assertWholeFileHashed(t *testing.T, db *sql.DB, path string,
+	data []byte,
+) {
+	t.Helper()
+
+	r := recordByPath(t, dbRecords(t, db), path)
+	if want := hexSum(data); r.head != want || r.tail != want ||
+		r.content != want {
+		t.Fatalf("head, tail, content = %q, %q, %q, want %q for each",
+			r.head, r.tail, r.content, want)
+	}
+}
+
+// TestSyncScanSameSecondRewrite rewrites a file in place at the same
+// size with an mtime later in the same second as the recorded one: the
+// next scan must notice the change and re-hash the file.
+func TestSyncScanSameSecondRewrite(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	db := openTestDB(t)
+	a := writeFile(t, dir, "a.bin", pattern(1, 500))
+
+	// b.bin shares the size of a.bin, so a.bin is hashed.
+	writeFile(t, dir, "b.bin", pattern(2, 500))
+
+	first := time.Date(2026, 1, 2, 3, 4, 5, 100_000_000, time.UTC)
+
+	err := os.Chtimes(a, first, first)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	syncTree(t, db, dir)
+
+	rewritten := pattern(3, 500)
+	writeFile(t, dir, "a.bin", rewritten)
+
+	later := first.Add(500 * time.Millisecond)
+
+	err = os.Chtimes(a, later, later)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	st := syncTree(t, db, dir)
+	if st != (scanStats{walked: 2, updated: 1, unchanged: 1}) {
+		t.Fatalf("rescan stats = %+v, want 1 updated 1 unchanged", st)
+	}
+
+	assertWholeFileHashed(t, db, a, rewritten)
+}
+
+// TestSyncScanOperandSameSecondRewrite is TestSyncScanSameSecondRewrite
+// for files given to scan as operands, which scan stats without reading
+// their directory.
+func TestSyncScanOperandSameSecondRewrite(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	db := openTestDB(t)
+	a := writeFile(t, dir, "a.bin", pattern(1, 500))
+
+	// b.bin shares the size of a.bin, so a.bin is hashed.
+	b := writeFile(t, dir, "b.bin", pattern(2, 500))
+
+	first := time.Date(2026, 1, 2, 3, 4, 5, 100_000_000, time.UTC)
+
+	err := os.Chtimes(a, first, first)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	syncTree(t, db, a, b)
+
+	rewritten := pattern(3, 500)
+	writeFile(t, dir, "a.bin", rewritten)
+
+	later := first.Add(500 * time.Millisecond)
+
+	err = os.Chtimes(a, later, later)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	st := syncTree(t, db, a, b)
+	if st != (scanStats{walked: 2, updated: 1, unchanged: 1}) {
+		t.Fatalf("rescan stats = %+v, want 1 updated 1 unchanged", st)
+	}
+
+	assertWholeFileHashed(t, db, a, rewritten)
+}
+
+// TestSyncScanRewriteAfter2262 runs assertLateRewriteRehashed with an
+// mtime after 2262, a time too late to count in nanoseconds in an int64.
+func TestSyncScanRewriteAfter2262(t *testing.T) {
+	t.Parallel()
+
+	assertLateRewriteRehashed(t, time.Date(2300, 1, 2, 3, 4, 5, 0, time.UTC))
+}
+
+// TestSyncScanRewritePastTimeLimit runs assertLateRewriteRehashed with an
+// mtime one second past the latest a time.Time holds without wrapping it
+// to a time far in the past.
+func TestSyncScanRewritePastTimeLimit(t *testing.T) {
+	t.Parallel()
+
+	assertLateRewriteRehashed(t, time.Unix(9223371974719179008, 0))
+}
+
+// assertLateRewriteRehashed scans a directory, rewrites a file in it in
+// place at the same size, sets its mtime to late, and fails unless the
+// next scan re-hashes the file. It skips where late does not fit the
+// platform's timespec or the filesystem does not store it.
+func assertLateRewriteRehashed(t *testing.T, late time.Time) {
+	t.Helper()
+
+	dir := t.TempDir()
+	db := openTestDB(t)
+	a := writeFile(t, dir, "a.bin", pattern(1, 500))
+
+	// b.bin shares the size of a.bin, so a.bin is hashed.
+	writeFile(t, dir, "b.bin", pattern(2, 500))
+
+	syncTree(t, db, dir)
+
+	rewritten := pattern(3, 500)
+	writeFile(t, dir, "a.bin", rewritten)
+
+	// os.Chtimes cannot set such a time: it converts through UnixNano.
+	ts, err := unix.TimeToTimespec(late)
+	if err != nil {
+		t.Skipf("an mtime %d seconds after 1970 does not fit this platform's "+
+			"timespec: %v", late.Unix(), err)
+	}
+
+	err = unix.UtimesNano(a, []unix.Timespec{ts, ts})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	fi, err := os.Lstat(a)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if fi.ModTime().Unix() != late.Unix() {
+		t.Skipf("the filesystem stored the mtime as %d seconds after 1970, "+
+			"not %d", fi.ModTime().Unix(), late.Unix())
+	}
+
+	st := syncTree(t, db, dir)
+	if st != (scanStats{walked: 2, updated: 1, unchanged: 1}) {
+		t.Fatalf("rescan stats = %+v, want 1 updated 1 unchanged", st)
+	}
+
+	assertWholeFileHashed(t, db, a, rewritten)
+}
+
 func TestSyncScanAddRemove(t *testing.T) {
 	t.Parallel()
 
@@ -1180,9 +1917,7 @@ func TestSyncScanSizeChange(t *testing.T) {
 
 	writeFile(t, dir, "f", pattern(1, 200))
 
-	mt := time.Unix(old.mtime, 0)
+	err := os.Chtimes(p, old.mtime, old.mtime)
-
-	err := os.Chtimes(p, mt, mt)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -1422,6 +2157,54 @@ func TestScanHardlinkRunFailsTogether(t *testing.T) {
 	}
 }
 
+// TestHashPhaseSkipsFileReplacedByFIFO replaces a walked regular file
+// with a FIFO before the hash phase reads it. Opening a FIFO that has
+// no writer waits for one, so a blocking open would hang the phase. The
+// path must be warned about once and skipped, with no record written.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestHashPhaseSkipsFileReplacedByFIFO(t *testing.T) {
+	stderr := captureStderr(t)
+	dir := t.TempDir()
+	p := writeFile(t, dir, "a.bin", pattern(1, 300))
+
+	walked, _ := collectWalk(t, []string{dir}, false, 1)
+
+	err := os.Remove(p)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = unix.Mkfifo(p, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	s := &scanState{db: openTestDB(t), toHash: walked}
+
+	err = s.hashPhase(t.Context(), 1)
+	if err != nil {
+		t.Fatalf("hashPhase = %v, want nil", err)
+	}
+
+	if s.st.skipped != 1 || len(s.batch) != 0 {
+		t.Errorf("skipped = %d, records = %d, want 1 skipped and none",
+			s.st.skipped, len(s.batch))
+	}
+
+	warning := "hash " + p + ": not a regular file\n"
+	if got := stderr(); strings.Count(got, warning) != 1 {
+		t.Errorf("stderr = %q, want %q once", got, warning)
+	}
+
+	// The content phase opens files the same way.
+	_, _, content, err := hashContentOnly(p, headTailMin)
+	if content != "" || !errors.Is(err, errNotRegular) {
+		t.Errorf("hashContentOnly on a FIFO = %q, %v; want no hash and %v",
+			content, err, errNotRegular)
+	}
+}
+
 // injectedWriteFailure is the message the injected database trigger
 // aborts with, so the test can recognize its own failure in the error
 // the scan reports.
@@ -1615,14 +2398,43 @@ func TestHashRuns(t *testing.T) {
 func TestPruneRoots(t *testing.T) {
 	t.Parallel()
 
+	const pqRoot = "/p/q"
+
+	// /p/q is on another filesystem than /p; /p/q/r is on the same one as
+	// /p/q, /p/s as /p, and /p/t has no known device.
+	devices := map[string]uint64{"/p": 1, pqRoot: 2, "/p/q/r": 2, "/p/s": 1}
+	device := func(path string) (uint64, bool) {
+		dev, ok := devices[path]
+
+		return dev, ok
+	}
+
 	// Duplicates and operands under other operands are dropped; /cc is
 	// not under /c (sibling with a shared prefix).
-	got := pruneRoots([]string{"/a/b", "/a", "/c", "/a", "/a/b/c", "/cc"})
+	got := pruneRoots([]string{"/a/b", "/a", "/c", "/a", "/a/b/c", "/cc"},
+		false, device)
 
 	want := []string{"/a", "/c", "/cc"}
 	if !slices.Equal(got, want) {
 		t.Fatalf("pruneRoots = %q, want %q", got, want)
 	}
+
+	nested := []string{"/p/q/r", pqRoot, "/p", "/p", "/p/s", "/p/t"}
+
+	got = pruneRoots(nested, false, device)
+
+	want = []string{"/p"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("pruneRoots without -x = %q, want %q", got, want)
+	}
+
+	// With -x, /p/q, on another filesystem than /p, is kept as well.
+	got = pruneRoots(nested, true, device)
+
+	want = []string{"/p", pqRoot}
+	if !slices.Equal(got, want) {
+		t.Fatalf("pruneRoots with -x = %q, want %q", got, want)
+	}
 }
 
 func TestReportsNeverTouchFilesystem(t *testing.T) {

script/bootstrap

@@ -2,15 +2,23 @@
 # script/bootstrap: install all dependencies needed to build and develop
 # this repo. Idempotent: every install is guarded by a check so already
 # installed tools are skipped. Base tooling comes from nix, apt, brew,
-# or apk (detected in that order); assumes nothing is present (not git,
+# or apk (detected in that order); assumes nothing is present. The
-# make, or go). The linter is NOT installed: golangci-lint runs via
+# installed node is used only when its major version is the pinned one;
-# docker only (script/lint), pinned by image digest, so the only lint
+# otherwise (node missing, or another major) the pinned version is
-# prerequisite is a working docker — which is warned about, not
+# installed via nvm (installing nvm itself first, from a hash-verified
-# installed, because everything except linting works without it.
+# release archive, never curl | sh), and yarn and the packages are
+# installed under it.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# Pinned versions, 2026-07-06
+NODE_VERSION="22.17.0"
+NVM_VERSION="0.40.3"
+# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
+NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
+YARN_VERSION="1.22.22"
+
 PKGMGR=""
 SUDO=""
 APT_UPDATED=""
@@ -43,6 +51,7 @@ pkg_install() {
     case "$PKGMGR" in
         nix) nix-env -iA "nixpkgs.$1" ;;
         apt)
+            # Package lists may be empty (fresh images); refresh once per run.
             if [ -z "$APT_UPDATED" ]; then
                 $SUDO env DEBIAN_FRONTEND=noninteractive apt-get update
                 APT_UPDATED=1
@@ -58,30 +67,103 @@ missing() {
     ! command -v "$1" >/dev/null 2>&1
 }
 
+# verify_sha256 <file> <expected-hash>
+verify_sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual="$(sha256sum "$1" | cut -d' ' -f1)"
+    else
+        actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
+    fi
+    if [ "$actual" != "$2" ]; then
+        echo "bootstrap: sha256 mismatch for $1" >&2
+        echo "  expected: $2" >&2
+        echo "  actual:   $actual" >&2
+        exit 1
+    fi
+}
+
+# nvm is a bash script; run a command in a bash with nvm loaded
+nvm_sh() {
+    bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
+}
+
+ensure_nvm() {
+    [ -s "$HOME/.nvm/nvm.sh" ] && return 0
+    # nvm prerequisites; nvm itself requires bash
+    if missing bash; then pkg_install bash bash bash bash; fi
+    if missing curl; then pkg_install curl curl curl curl; fi
+    if missing git; then pkg_install git git git git; fi
+    tmp="$(mktemp -d)"
+    curl -fsSL -o "$tmp/nvm.tar.gz" \
+        "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
+    verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
+    mkdir -p "$HOME/.nvm"
+    tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
+    rm -rf "$tmp"
+}
+
+# True when the node on PATH has the pinned major version. Only the
+# major is compared: the Dockerfile stages start from a node 22 alpine
+# image whose exact version is not the pin, and nvm cannot install a
+# prebuilt node on alpine. Another major is not used: the pinned yarn 1
+# prints a deprecation warning under node 24. script/fmt and
+# script/fmt-check carry this function unchanged, to run the yarn
+# installed here.
+node_is_pinned_major() {
+    if ! command -v node >/dev/null 2>&1; then return 1; fi
+    installed="$(node --version)"
+    installed="${installed#v}"
+    [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ]
+}
+
+ensure_node() {
+    if node_is_pinned_major; then
+        echo "bootstrap: using node $(node --version)"
+        return 0
+    fi
+    ensure_nvm
+    nvm_sh "nvm install $NODE_VERSION"
+    nvm_sh "nvm use $NODE_VERSION >/dev/null && \
+        echo \"bootstrap: using node \$(node --version)\""
+}
+
+ensure_yarn() {
+    if ! node_is_pinned_major; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
+            corepack prepare yarn@$YARN_VERSION --activate"
+        return 0
+    fi
+    if ! missing yarn; then return 0; fi
+    if ! missing corepack; then
+        corepack enable
+        corepack prepare "yarn@$YARN_VERSION" --activate
+    else
+        npm install -g "yarn@$YARN_VERSION"
+    fi
+}
+
+install_js_deps() {
+    if node_is_pinned_major; then
+        yarn install --frozen-lockfile
+    else
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
+            yarn install --frozen-lockfile"
+    fi
+}
+
 main() {
     cd "$ROOT"
 
-    # System tooling, deliberately unpinned: these come from the host
-    # package manager and whatever version it ships is what the host
-    # gets, so a presence check is the right check. The repo pins no
-    # system toolchain versions — the Go language version is governed by
-    # go.mod, and builds that must be reproducible run in the Docker
-    # image, whose base images are pinned by digest.
-    if missing git; then pkg_install git git git git; fi
     if missing make; then pkg_install gnumake make make make; fi
+    if missing git; then pkg_install git git git git; fi
+    # Go builds the binary and runs gofmt. Presence is the whole check:
+    # go.mod names the Go version, and the tests and the linter run in
+    # digest-pinned images.
     if missing go; then pkg_install go golang go go; fi
 
-    # Linting runs via docker only (script/lint), so docker is a lint
+    ensure_node
-    # prerequisite rather than something bootstrap installs. Warn, do
+    ensure_yarn
-    # not fail: everything except `make lint` — and, through it,
+    install_js_deps
-    # `make check`, `make docker` and the pre-commit hook — works
-    # without it.
-    if missing docker; then
-        echo "bootstrap: WARNING: docker not found; make lint, make check" >&2
-        echo "bootstrap: and make docker require it. Install docker to" >&2
-        echo "bootstrap: run the linter." >&2
-    fi
-
     go mod download
 
     echo "bootstrap complete"

script/check

@@ -1,6 +1,8 @@
 #!/bin/sh
 # script/check: run all checks (test, lint, fmt-check). Our own
-# extension to scripts-to-rule-them-all. Must not modify any files.
+# extension to scripts-to-rule-them-all. test and lint are Docker
+# phases; fmt-check is native, because a formatter writes the working
+# tree. Must not modify any files.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/cibuild

@@ -1,34 +1,32 @@
 #!/bin/sh
-# script/cibuild: run the CI build. The Gitea workflow runs this on
+# script/cibuild: run the CI build. It bootstraps first: a CI runner
-# push.
+# checks out and runs this and nothing else, and script/fmt-check runs
-#
+# the formatter on the host, which a pristine checkout cannot do.
-# The Dockerfile runs the gates individually as build steps, not the
+# A new CACHEBUST value reruns every RUN step, since a cached gate phase
-# make check aggregate: the lint stage runs make fmt-check,
+# is a check that did not run; unlike --no-cache, it keeps Go's build cache.
-# script/verify-lint-image-pin, golangci-lint config verify and
+# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
-# golangci-lint run; the build stage, dropped to an unprivileged user,
+# first; a stage without that line is served from cache on an unchanged
-# runs make test and make fmt-check. Neither make lint nor make check
+# tree, with no warning.
-# appears, because both reach script/lint, which is itself a docker
-# build, and a docker build cannot run inside one. Lint is not skipped
-# by that — the linter is invoked directly in the lint stage, and the
-# build stage's COPY --from=lint makes that stage a prerequisite, so
-# BuildKit must finish it first. Between the two stages everything
-# make check would run has run, which is why a successful build here
-# implies the repo is green.
-#
-# That implication holds only because of CHECK_EPOCH. A COPY layer is
-# invalidated only by changed content, and a rebuild of an unchanged
-# checkout sends the same content, so without a fresh value here Docker
-# serves the gate layers from cache and the build reports a green it
-# never earned. Passing the current epoch invalidates the gate
-# layers on every run while leaving the pinned base images and
-# go mod download cached; see the Dockerfile for the placement.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --build-arg CHECK_EPOCH="$(date +%s)" .
+    "$SCRIPT_DIR/bootstrap"
+    "$SCRIPT_DIR/check"
+    # The version and the tag each get their own line: a failing
+    # command substitution inside an argument does not trip `set -e`,
+    # so the inline form degrades silently to an empty constant. The
+    # VERSION build argument takes precedence over the version a build
+    # stage derives from the .git in the context.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    tag="$("$SCRIPT_DIR/projectname")"
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
+        --build-arg VERSION="$version" \
+        -t "$tag" .
 }
 
 main "$@"

script/docker

@@ -1,14 +1,11 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
-# The tag comes from script/projectname.
+# Identical in all repos; the tag comes from script/projectname.
-#
+# A new CACHEBUST value reruns every RUN step, since a cached gate phase
-# CHECK_EPOCH is passed for the same reason script/cibuild passes it:
+# is a check that did not run; unlike --no-cache, it keeps Go's build cache.
-# without it Docker serves the Dockerfile's gate layers from cache on an
+# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
-# unchanged tree and this exits 0 having run neither the lint stage's
+# first; a stage without that line is served from cache on an unchanged
-# gates nor the builder stage's test and fmt-check gates. This is the
+# tree, with no warning.
-# set of gates a developer or reviewer runs by hand, so a cached pass
-# here is the most misleading result the repo can produce. Dependency
-# layers sit above the ARG and stay cached.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -16,10 +13,17 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build \
+    # The version and the tag each get their own line: a failing
-        --build-arg CHECK_EPOCH="$(date +%s)" \
+    # command substitution inside an argument does not trip `set -e`,
-        -t "$("$SCRIPT_DIR/projectname")" \
+    # so the inline form degrades silently to an empty constant. The
-        .
+    # VERSION build argument takes precedence over the version a build
+    # stage derives from the .git in the context.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    tag="$("$SCRIPT_DIR/projectname")"
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
+        --build-arg VERSION="$version" \
+        -t "$tag" .
 }
 
 main "$@"

script/fmt

@@ -4,9 +4,39 @@ set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# Must match the pin in script/bootstrap.
+NODE_VERSION="22.17.0"
+
+# True when the node on PATH has the pinned major version: the same
+# function as in script/bootstrap, which uses it to decide where it
+# installs yarn.
+node_is_pinned_major() {
+    if ! command -v node >/dev/null 2>&1; then return 1; fi
+    installed="$(node --version)"
+    installed="${installed#v}"
+    [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ]
+}
+
+# Run the yarn script/bootstrap installed: the yarn on PATH when the
+# node on PATH has the pinned major version, and otherwise yarn under
+# the pinned node in nvm, which bootstrap leaves off the PATH of the
+# shell that called it. nvm is a bash script, hence the subshell.
+run_yarn() {
+    if node_is_pinned_major && command -v yarn >/dev/null 2>&1; then
+        exec yarn "$@"
+    fi
+    if node_is_pinned_major || [ ! -s "$HOME/.nvm/nvm.sh" ]; then
+        echo "fmt: no yarn; run script/bootstrap first" >&2
+        exit 1
+    fi
+    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
+        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
+}
+
 main() {
     cd "$ROOT"
     gofmt -s -w .
+    run_yarn run prettier --write '**/*.md' --tab-width 4 --prose-wrap always
 }
 
 main "$@"

script/fmt-check

@@ -1,18 +1,60 @@
 #!/bin/sh
-# script/fmt-check: check formatting (read-only). Same scope as
+# script/fmt-check: check formatting (read-only).
-# script/fmt, but fails instead of writing.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# Must match the pin in script/bootstrap.
+NODE_VERSION="22.17.0"
+
+# True when the node on PATH has the pinned major version: the same
+# function as in script/bootstrap, which uses it to decide where it
+# installs yarn.
+node_is_pinned_major() {
+    if ! command -v node >/dev/null 2>&1; then return 1; fi
+    installed="$(node --version)"
+    installed="${installed#v}"
+    [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ]
+}
+
+# Run the yarn script/bootstrap installed: the yarn on PATH when the
+# node on PATH has the pinned major version, and otherwise yarn under
+# the pinned node in nvm, which bootstrap leaves off the PATH of the
+# shell that called it. nvm is a bash script, hence the subshell.
+run_yarn() {
+    if node_is_pinned_major && command -v yarn >/dev/null 2>&1; then
+        exec yarn "$@"
+    fi
+    if node_is_pinned_major || [ ! -s "$HOME/.nvm/nvm.sh" ]; then
+        echo "fmt-check: no yarn; run script/bootstrap first" >&2
+        exit 1
+    fi
+    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
+        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
+}
+
 main() {
     cd "$ROOT"
-    files="$(gofmt -s -l .)"
+    status=0
+
+    # gofmt and prettier both run every time, so the output names each
+    # one that fails. Under set -e a bare assignment would end the
+    # script when gofmt fails (a Go file it cannot parse).
+    if ! files="$(gofmt -s -l .)"; then
+        echo "gofmt: failed; see its errors above" >&2
+        status=1
+    fi
     if [ -n "$files" ]; then
         echo "gofmt: files not formatted:" >&2
         echo "$files" >&2
-        exit 1
+        status=1
     fi
+
+    # run_yarn ends in exec; the subshell returns here afterwards.
+    (run_yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always) ||
+        status=1
+
+    exit "$status"
 }
 
 main "$@"

script/install-precommit

@@ -1,19 +1,15 @@
 #!/bin/sh
 # script/install-precommit: install the git pre-commit hook that runs
 # script/precommit. Our own extension to scripts-to-rule-them-all.
-# Hooks are shared between the main checkout and all worktrees, so
-# resolve the common git dir instead of assuming .git is a directory.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    hooks_dir="$(git rev-parse --git-common-dir)/hooks"
+    hook=".git/hooks/pre-commit"
-    mkdir -p "$hooks_dir"
+    printf '#!/bin/sh\nset -e\nscript/precommit\n' > .git/hooks/pre-commit
-    hook="$hooks_dir/pre-commit"
+    chmod +x .git/hooks/pre-commit
-    printf '#!/bin/sh\nset -e\nscript/precommit\n' > "$hook"
-    chmod +x "$hook"
     echo "pre-commit hook installed: runs script/precommit"
 }
 

script/lint

@@ -1,29 +1,26 @@
 #!/bin/sh
-# script/lint: run the linter. golangci-lint is never installed on a
+# script/lint: run the linter. Linting is a phase of the Dockerfile and
-# host: it runs via docker only, one way, everywhere — this builds
+# this builds that phase alone; the linter is never installed or run on
-# Dockerfile.lint, which COPYs the repo into the digest-pinned
+# a developer host, where a shared result cache and a host-global lock
-# golangci-lint image and lints as a build step, so a successful build
+# make its answer untrustworthy.
-# is a clean lint. The only prerequisite is a working docker. The gate
-# steps make no network calls of their own, but Dockerfile.lint runs
-# `go mod download` above them, so a cold cache does reach the network
-# (as does pulling the pinned image); that layer stays cached, and once
-# it is warm this runs offline until go.mod or go.sum changes.
 #
-# CHECK_EPOCH is what makes the result mean anything. Without it docker
+# The phase is not the last stage in the file, so it is built only when
-# serves the gate layers from cache on an unchanged tree and this exits
+# --target names it. A new CACHEBUST value reruns every RUN step, since
-# 0 in well under a second having run no linter. The PID is in the value
+# a cached lint layer is a lint that did not run; unlike --no-cache, it
-# as well as the epoch because two lint runs land inside the same second
+# keeps Go's build cache. This relies on every stage of the Dockerfile
-# easily, and `date +%s` alone would cache the second one.
+# declaring ARG CACHEBUST first; a stage without that line is served
+# from cache on an unchanged tree, with no warning.
+# --output type=cacheonly writes no image, since nothing uses one.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build \
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
-        --build-arg CHECK_EPOCH="$(date +%s)-$$" \
+        --target lint \
-        -f Dockerfile.lint \
+        --output type=cacheonly .
-        .
 }
 
 main "$@"

script/precommit

@@ -1,13 +1,13 @@
 #!/bin/sh
 # script/precommit: run by the git pre-commit hook; fails the commit if
-# checks fail. Our own extension to scripts-to-rule-them-all. Go extra:
+# checks fail. Our own extension to scripts-to-rule-them-all.
-# go mod tidy must be a no-op before the checks run.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
+    # Go extra: go mod tidy must be a no-op before the checks run.
     cd "$ROOT"
     go mod tidy
     if ! git diff --exit-code -- go.mod go.sum; then

script/setup

@@ -1,6 +1,6 @@
 #!/bin/sh
 # script/setup: set up the repo for development after a fresh clone:
-# installs dependencies (script/bootstrap) and the git pre-commit hook.
+# installs dependencies and the git pre-commit hook.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/test

@@ -1,17 +1,23 @@
 #!/bin/sh
-# script/test: run the test suite. Reruns verbosely on failure so CI
+# script/test: run the test suite. Testing is a phase of the Dockerfile
-# logs show which test failed.
+# and this builds that phase alone, on the same terms as script/lint:
+# --target because a phase that is not the last stage is built only when
+# named, and a new CACHEBUST value because a cached test layer is a test
+# that did not run; unlike --no-cache, it keeps Go's build cache. This
+# relies on every stage of the Dockerfile declaring ARG CACHEBUST first;
+# a stage without that line is served from cache on an unchanged tree,
+# with no warning. --output type=cacheonly writes no image, since
+# nothing uses one.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    go test -timeout 30s -cover ./... || {
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
-        echo "--- Rerunning with -v for details ---"
+        --target test \
-        go test -timeout 30s -v ./...
+        --output type=cacheonly .
-        exit 1
-    }
 }
 
 main "$@"

script/verify-lint-image-pin

@@ -1,84 +0,0 @@
-#!/bin/sh
-# script/verify-lint-image-pin: fail unless the golangci-lint image
-# referenced by Dockerfile.lint and the one referenced by the main
-# Dockerfile's lint stage are the same image at the same digest. Our own
-# extension to scripts-to-rule-them-all, not one of its entrypoints.
-#
-# The linter version is pinned in two independent files. That is the
-# shape #42 turned into a build failure rather than tolerate: nothing
-# else keeps the two in sync, and a bump applied to one file alone would
-# leave `make lint` and the fail-fast lint stage of `make docker`
-# linting the same tree against different rulesets, both green. This is
-# the single guard that stops it, run as a gate in both files.
-#
-# It deliberately restates neither pin. A hardcoded expected digest here
-# would be a third copy — one more thing to bump, and the same drift one
-# file further out. It compares the two files to each other and knows
-# nothing about which version is correct.
-#
-# A reference that cannot be read is a hard failure, not a skip: a
-# comparison of two empty strings succeeds, which would turn this guard
-# into exactly the unearned green it exists to prevent.
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-LINT_DOCKERFILE="Dockerfile.lint"
-MAIN_DOCKERFILE="Dockerfile"
-
-# Echo the single golangci-lint image reference in the named Dockerfile.
-# Scans every argument of every FROM instruction rather than assuming a
-# field position, so `FROM --platform=... img AS stage` reads correctly.
-# Exits non-zero, with a diagnosis, unless there is exactly one.
-lint_image_ref() {
-    file="$1"
-
-    if [ ! -f "$file" ]; then
-        echo "verify-lint-image-pin: $file: not found" >&2
-        return 1
-    fi
-
-    refs="$(
-        awk '
-            toupper($1) == "FROM" {
-                for (i = 2; i <= NF; i++) {
-                    if ($i ~ /^golangci\/golangci-lint[:@]/) {
-                        print $i
-                    }
-                }
-            }
-        ' "$file"
-    )"
-
-    count="$(printf '%s' "$refs" | grep -c . || true)"
-    if [ "$count" -ne 1 ]; then
-        echo "verify-lint-image-pin: $file: expected exactly one" \
-            "golangci/golangci-lint FROM reference, found $count" >&2
-        return 1
-    fi
-
-    printf '%s\n' "$refs"
-}
-
-main() {
-    cd "$ROOT"
-
-    lint_ref="$(lint_image_ref "$LINT_DOCKERFILE")"
-    main_ref="$(lint_image_ref "$MAIN_DOCKERFILE")"
-
-    if [ "$lint_ref" != "$main_ref" ]; then
-        echo "verify-lint-image-pin: the linter image is pinned twice and" \
-            "the two pins disagree:" >&2
-        echo "verify-lint-image-pin:   $LINT_DOCKERFILE: $lint_ref" >&2
-        echo "verify-lint-image-pin:   $MAIN_DOCKERFILE: $main_ref" >&2
-        echo "verify-lint-image-pin: bump both FROM lines together so" \
-            "script/lint and the Dockerfile lint stage keep running the" \
-            "same linter" >&2
-        exit 1
-    fi
-
-    echo "verify-lint-image-pin: $LINT_DOCKERFILE and $MAIN_DOCKERFILE" \
-        "agree on $lint_ref"
-}
-
-main "$@"

trees.go

@@ -29,10 +29,16 @@ type treeNode struct {
 // the record paths, computes a Merkle-style digest per directory, and
 // prints maximal duplicate-tree groups as TSV on stdout. It never
 // touches the scanned filesystem; its only I/O is the database, stdout,
-// and stderr. Any database problem, including a missing database, is
+// and stderr. It names the database on stderr before it opens it. Any
-// fatal.
+// database problem, including a missing database, is fatal.
 func runTrees(ctx context.Context, stdout io.Writer) error {
-	dbPath := databasePath()
+	dbPath, source, err := databasePath()
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(os.Stderr, "trees: database %s (%s)\n",
+		escapePath(dbPath), source)
 
 	db, err := openReportDatabase(ctx, dbPath)
 	if err != nil {

yarn.lock

@@ -0,0 +1,8 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+prettier@3.8.1:
+  version "3.8.1"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.1.tgz#edf48977cf991558f4fcbd8a3ba6015ba2a3a173"
+  integrity sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==