Fail a bare docker build instead of serving cached gates (closes #39)

Each Dockerfile stage that runs gates now checks, right after its
ARG CHECK_EPOCH, that the value is not empty, and stops with a message
naming script/cibuild and script/docker. A plain `docker build .` can
no longer report a green from cached gate layers.

script/cibuild and script/docker now append the process id to the
epoch, the form script/lint already uses, so two runs started in the
same second still get different values.

README says both. TODO.md corrects the steady-state CACHED count
recorded for issue 32 from twelve to thirteen.

Model: opus-5-5

.golangci.yml

@@ -10,14 +10,20 @@ 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
     - 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
   settings:
     lll:
       line-length: 88
@@ -28,6 +34,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

@@ -10,11 +10,13 @@ COPY . .
 # invalidates COPY only when the copied content changes, so on an
 # unchanged tree the gates below would be served from cache and the
 # build would exit 0 having run nothing. script/cibuild and
-# script/docker pass a fresh CHECK_EPOCH on every invocation.
+# script/docker pass a fresh CHECK_EPOCH on every invocation. A build
+# that passes none, such as a bare `docker build .`, fails at the check
+# right after the ARG instead of quietly serving the gates from cache.
 #
-# Two properties this depends on. ARG is per-stage, so the build stage
+# Two properties this depends on. ARG is per-stage, so the markdown and
-# below declares it again; one declaration here would leave that
+# build stages below declare it again; one declaration here would leave
-# stage's gate cacheable. And each gate RUN must reference the value,
+# their gates cacheable. And each gate RUN must reference the value,
 # because BuildKit hashes the expanded command: a declared but
 # unreferenced ARG invalidates nothing.
 #
@@ -22,14 +24,25 @@ COPY . .
 # (the pinned base image, go mod download) keeps its cache; only the
 # gates go cold.
 ARG CHECK_EPOCH
+RUN if [ -z "${CHECK_EPOCH}" ]; then \
+        echo "CHECK_EPOCH is unset; build via script/cibuild or script/docker" >&2; \
+        exit 1; \
+    fi
 
 # The linter is invoked directly here, not through `make lint`. That
 # target now runs `docker build -f Dockerfile.lint`, and a docker build
 # cannot run a docker build: routing the gate through make would mean
 # 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
+# from the build stage below, and `make fmt-check` from both stages: it
-# gate, not the aggregate, and it shells out to nothing.
+# runs prettier through docker too. Its gofmt half is the step below,
-RUN echo "gate fmt-check, epoch ${CHECK_EPOCH}" && make fmt-check
+# its Markdown half the markdown stage further down. gofmt's output is
+# assigned to a variable first so that its own exit status, as when it
+# cannot parse a file, still fails the step.
+RUN echo "gate gofmt, epoch ${CHECK_EPOCH}" && \
+    files="$(gofmt -s -l .)" && \
+    if [ -n "$files" ]; then \
+        echo "gofmt: files not formatted:" >&2; echo "$files" >&2; exit 1; \
+    fi
 
 # 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
@@ -46,32 +59,69 @@ RUN echo "gate config verify, epoch ${CHECK_EPOCH}" && \
 RUN echo "gate lint, epoch ${CHECK_EPOCH}" && \
     golangci-lint run --config .golangci.yml ./...
 
+# Prettier stage: the prettier that formats this repository's Markdown,
+# never installed on a host. script/fmt and script/fmt-check build this
+# stage alone and run it with the repository mounted on /src. prettier
+# is installed in /tools so that the repository, mounted or copied onto
+# /src, cannot hide it.
+# node:22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS prettier
+WORKDIR /tools
+# yarn.lock pins prettier by hash, and --frozen-lockfile fails rather
+# than install anything yarn.lock does not name.
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+ENV PATH=/tools/node_modules/.bin:$PATH
+WORKDIR /src
+
+# Markdown stage: the Markdown half of `make fmt-check`, as a gate.
+FROM prettier AS markdown
+COPY . .
+# Second per-stage declaration of the gate cache-buster and its check;
+# see the lint stage above.
+ARG CHECK_EPOCH
+RUN if [ -z "${CHECK_EPOCH}" ]; then \
+        echo "CHECK_EPOCH is unset; build via script/cibuild or script/docker" >&2; \
+        exit 1; \
+    fi
+RUN echo "gate prettier, epoch ${CHECK_EPOCH}" && \
+    prettier --check '**/*.md' --tab-width 4 --prose-wrap always
+
 # Build stage
 # golang:1.25-alpine, 2026-07-23
 FROM golang@sha256:56961d79ea8129efddcc0b8643fd8a5416b4e6228cfd477e3fd61deb2672c587 AS builder
 
 # We never build or run as root. Create an unprivileged user and point
-# HOME and the Go caches at its home so go build and go test can write
+# HOME and the build cache at its home so go build and go test can write
-# their caches when we drop to it below. $GOPATH/bin is deliberately not
+# it when we drop to it below. $GOPATH/bin is deliberately not on PATH:
-# on PATH: script/bootstrap no longer `go install`s anything (the linter
+# script/bootstrap no longer `go install`s anything (the linter runs
-# runs from a pinned image, never from a host install), so nothing lands
+# 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
+# No-op file copies whose only purpose is the build-graph edge: they are
-# makes this stage depend on the lint stage, and so what forces BuildKit
+# what make this stage depend on the lint and markdown stages, and so
-# to finish fmt-check, the pin guard and lint before compilation and
+# what forces BuildKit to finish gofmt, the pin guard, lint and prettier
-# tests start. Remove it and the fail-fast design dies silently — the
+# before compilation and tests start. Remove one and the fail-fast
-# build stops gating on lint and still exits 0. It replaces a copy of
+# design dies silently — the build stops gating on that stage and still
-# the linter binary itself, which is no longer wanted here: nothing in
+# exits 0. The first replaces a copy of the linter binary itself, which
-# this stage runs the linter, because `make lint` is now a docker build
+# is no longer wanted here: nothing in this stage runs the linter,
-# and a docker build cannot run inside one.
+# 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=markdown /src/go.sum /dev/null
 
 # Install development prerequisites the same way a developer does,
 # rather than duplicating the installs inline. Only script/ and the
@@ -83,30 +133,46 @@ COPY script/ script/
 COPY go.mod go.sum ./
 RUN script/bootstrap
 
-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
 
-# Hand the sources and caches to the unprivileged user, then drop root
+# The sources are handed to builder as they are copied, so no layer has
-# before running any checks or builds.
+# to walk them. Then drop root before running any checks or builds.
-RUN chown -R builder:builder /src /home/builder
+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
+# The gate is `make test`, not `make check`: that aggregate runs
-# runs `script/lint`, which is now a docker build, and nothing inside an
+# `script/lint` and `script/fmt-check`, which both run docker, and
-# image build may shell out to docker. Lint is not skipped by this — it
+# nothing inside an image build may shell out to docker. Lint and the
-# ran in the lint stage above, which this stage's COPY --from makes a
+# format checks are not skipped by this — they ran in the lint and
-# prerequisite. `make`, not the scripts directly, because the Makefile's
+# markdown stages above, which this stage's COPY --from lines make
+# prerequisites. `make`, not the script 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
+# Third per-stage declaration of the gate cache-buster and its check;
-# stage above for why one is not enough. It is placed after USER so the
+# see the lint stage above for why one is not enough. It is placed after
-# drop to the unprivileged user still happens before the checks run.
+# USER so the drop to the unprivileged user still happens before the
+# checks run.
 ARG CHECK_EPOCH
+RUN if [ -z "${CHECK_EPOCH}" ]; then \
+        echo "CHECK_EPOCH is unset; build via script/cibuild or script/docker" >&2; \
+        exit 1; \
+    fi
 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

TODO.md

@@ -1,488 +1,501 @@
 # 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`)
 - 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 whose title ends with ` (closes #N)`
-  ` (closes #N)`
+- an independent review gates the merge; every finding is addressed or
-- an independent review gates the merge; every finding is addressed
+  explicitly rebutted on the PR
-  or explicitly rebutted on the PR
 - merge to `main` once the review passes
 
 # 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
 
-- `report` and `trees` stream the records instead of holding them all in
+- a bare `docker build .` fails with a message naming `script/cibuild` and
-  memory; the schema gains the `files_signature` index (2026-10-04,
+  `script/docker` instead of serving the gates from cache (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/39)
+
+- `make fmt` and `make fmt-check` run prettier over all Markdown, in Docker, 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)
+
+- README documents install, Docker, a daily cron scan and how to read and check
+  the reports (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/54)
+
+- the `Dockerfile` build stage keeps the Go module cache out of `builder`'s home
+  and copies the sources with `--chown`, so no `chown -R` walks them
+  (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/43)
+
+- `--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 hashed,
+  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 memory;
+  the schema gains the `files_signature` index (2026-10-04,
   https://git.eeqj.de/sneak/sfdupes/issues/14)
 
-- warn about and skip symlink, socket, FIFO, device and `.zfs`
+- progress prints at once on a non-terminal, uses a real terminal test, and
-  operands, keeping the records beneath them (2026-10-03,
+  prints warnings through a spinner instead of racing its redraw (2026-10-03,
+  https://git.eeqj.de/sneak/sfdupes/issues/13)
+
+- warn about and skip symlink, socket, FIFO, device and `.zfs` operands, keeping
+  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` now sends
-  sends `.git`, without `.git/config`, and the `Dockerfile` build
+  `.git`, without `.git/config`, and the `Dockerfile` build stage takes the
-  stage takes the `VERSION` build argument when one is given,
+  `VERSION` build argument when one is given, otherwise
-  otherwise `git describe --tags --always` of that `.git`. The build
+  `git describe --tags --always` of that `.git`. The build fails if the context
-  fails if the context carries `.git` and the version still comes out
+  carries `.git` and the version still comes out empty, `dev` or `unknown`. The
-  empty, `dev` or `unknown`. The CI checkout step fetches the full
+  CI checkout step fetches the full history (`fetch-depth: 0`) so CI sees the
-  history (`fetch-depth: 0`) so CI sees the tag and stamps the same
+  tag and stamps the same value as `make build`.
-  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): a file under 10 MiB is hashed in
-  hashed in full and compared directly, with no end-window step — its
+  full and compared directly, with no end-window step — its `head`, `tail`, and
-  `head`, `tail`, and `content` all hold the whole-file hash. A file at
+  `content` all hold the whole-file hash. A file at 10 MiB or above gets only
-  10 MiB or above gets only the 64 KiB `head` and `tail` in the hash
+  the 64 KiB `head` and `tail` in the hash phase; a new content phase, after the
-  phase; a new content phase, after the update phase, reads it for its
+  update phase, reads it for its `content` hash — the whole file below 50 MiB,
-  `content` hash — the whole file below 50 MiB, gigabyte-spaced 1 MiB
+  gigabyte-spaced 1 MiB samples at or above — only when its size, `head`, and
-  samples at or above — only when its size, `head`, and `tail` match
+  `tail` match another record's, from the same scan or stored by an earlier one,
-  another record's, from the same scan or stored by an earlier one, so
+  so a stored file gains its content hash when it gains a match. A file that is
-  a stored file gains its content hash when it gains a match. A file
+  gone or has changed since its record was written is not read. The `content`
-  that is gone or has changed since its record was written is not
+  column is part of the version 1 schema. `report` and `trees` group by the
-  read. The `content` column is part of the version 1 schema. `report`
+  extended signature and leave out any record without a `content` hash, so the
-  and `trees` group by the extended signature and leave out any record
+  ladder is applied across the whole database. README "Duplicate detection"
-  without a `content` hash, so the ladder is applied across the whole
+  documents every rung including the probabilistic large-file path.
-  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
-  `(Debian-based)` parenthetical (v2.12.1 was Debian too) and the
+  `(Debian-based)` parenthetical (v2.12.1 was Debian too) and the redundant tag,
-  redundant tag, so both pins are the policy `# image:vX.Y.Z,
+  so both pins are the policy `# image:vX.Y.Z, YYYY-MM-DD` comment over a bare
-  YYYY-MM-DD` comment over a bare `FROM image@sha256:...`. Digest
+  `FROM image@sha256:...`. Digest unchanged. `script/verify-lint-image-pin`
-  unchanged. `script/verify-lint-image-pin` parses those `FROM` lines
+  parses those `FROM` lines and still matches the tagless form; its advice line
-  and still matches the tagless form; its advice line lost the now
+  lost the now meaningless "tag and digest". With no tag in either reference, a
-  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
-  tag-only disagreement no longer exists — a one-sided tag is caught as
+  mismatch.
-  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 runs inside a container invoked through the `script/`
-  linter runs inside a container invoked through the `script/`
+  entrypoint and is never installed on a host. New root `Dockerfile.lint` COPYs
-  entrypoint and is never installed on a host. New root
+  the repo into the digest-pinned `golangci/golangci-lint:v2.12.2` image and
-  `Dockerfile.lint` COPYs the repo into the digest-pinned
+  runs `golangci-lint config verify` and `golangci-lint run` as build steps, so
-  `golangci/golangci-lint:v2.12.2` image and runs
+  a successful build IS a clean lint; `script/lint` is reduced to building it.
-  `golangci-lint config verify` and `golangci-lint run` as build
+  `script/bootstrap` loses the `go install`, the pin constants, the version
-  steps, so a successful build IS a clean lint; `script/lint` is
+  parser and `verify_golangci_lint` outright rather than hardening them — with
-  reduced to building it. `script/bootstrap` loses the `go install`,
+  nothing linting on the host, the `$GOPATH/bin` versus `PATH` problem that
-  the pin constants, the version parser and `verify_golangci_lint`
+  motivated them has no subject — and now warns rather than fails when `docker`
-  outright rather than hardening them — with nothing linting on the
+  is absent. Two traps handled. A lint build on an unchanged tree returns
-  host, the `$GOPATH/bin` versus `PATH` problem that motivated them has
+  success in well under a second having run no linter, which is
-  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
+  https://git.eeqj.de/sneak/sfdupes/issues/39 again, so `Dockerfile.lint`
-  `Dockerfile.lint` carries `ARG CHECK_EPOCH` referenced
+  carries `ARG CHECK_EPOCH` referenced inside every gate `RUN` (BuildKit hashes
-  inside every gate `RUN` (BuildKit hashes the expanded command, not
+  the expanded command, not the declaration) and `script/lint` passes
-  the declaration) and `script/lint` passes `"$(date +%s)-$$"` — the
+  `"$(date +%s)-$$"` — the PID matters because two lint runs land inside the
-  PID matters because two lint runs land inside the same second easily.
+  same second easily. And nothing inside an image build may shell out to docker,
-  And nothing inside an image build may shell out to docker, so the
+  so the main `Dockerfile`'s lint stage now invokes `golangci-lint` directly
-  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
+  `make fmt-check` instead of the `make check` aggregate (`make`, not the
-  the scripts bare, because the Makefile's `export CGO_ENABLED = 0`
+  scripts bare, because the Makefile's `export CGO_ENABLED = 0` only reaches
-  only reaches what it invokes). `COPY --from=lint`
+  what it invokes). `COPY --from=lint` `/usr/bin/golangci-lint` is replaced by
-  `/usr/bin/golangci-lint` is replaced by
+  `COPY --from=lint /src/go.sum /dev/null`: the copied binary was the only edge
-  `COPY --from=lint /src/go.sum /dev/null`: the copied binary was the
+  forcing BuildKit to finish linting before the build stage starts, and dropping
-  only edge forcing BuildKit to finish linting before the build stage
+  it without replacing the edge would have ended fail-fast linting silently
-  starts, and dropping it without replacing the edge would have ended
+  under a still-green build. That is canonical `REPO_POLICIES.md:107`'s ordering
-  fail-fast linting silently under a still-green build. That is
+  edge, restored. `ENV PATH=/home/builder/go/bin:$PATH` is gone with the
-  canonical `REPO_POLICIES.md:107`'s ordering edge, restored.
+  `go install` that justified it. `script/verify-linter-pin` is retired, deleted
-  `ENV PATH=/home/builder/go/bin:$PATH` is gone with the `go install`
+  along with its README entry, because both of its subjects ceased to exist in
-  that justified it. `script/verify-linter-pin` is retired, deleted
+  the same change: it compared a linter binary against `GOLANGCI_LINT_VERSION`
-  along with its README entry, because both of its subjects ceased to
+  in `script/bootstrap`, and there is now neither a binary crossing between
-  exist in the same change: it compared a linter binary against
+  stages nor a version pin in bootstrap. The drift it guarded has not gone away,
-  `GOLANGCI_LINT_VERSION` in `script/bootstrap`, and there is now
+  it has moved — the linter is still pinned twice, now as the `FROM` line of
-  neither a binary crossing between stages nor a version pin in
+  `Dockerfile.lint` and the `FROM` line of the `Dockerfile` lint stage, with
-  bootstrap. The drift it guarded has not gone away, it has moved — the
+  nothing syncing them, which is exactly what
-  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`,
+  replacement is one new `script/verify-lint-image-pin`, run as a gate in both
-  run as a gate in both files, which compares the two references to
+  files, which compares the two references to each other and deliberately
-  each other and deliberately restates neither: a hardcoded expected
+  restates neither: a hardcoded expected digest would be a third copy and the
-  digest would be a third copy and the same drift one file further out.
+  same drift one file further out. `golangci-lint config verify` is included per
-  `golangci-lint config verify` is included per the ruling, and the
+  the ruling, and the concern about its unpinned live HTTPS schema fetch was
-  concern about its unpinned live HTTPS schema fetch was measured
+  measured rather than assumed — under `--network none` the pinned binary both
-  rather than assumed — under `--network none` the pinned binary both
+  passes a valid config and rejects an invalid one with the jsonschema error, so
-  passes a valid config and rejects an invalid one with the jsonschema
+  it validates from an embedded schema and makes no network call of its own. The
-  error, so it validates from an embedded schema and makes no network
+  README scopes that to the gate steps rather than to linting as a whole:
-  call of its own. The README scopes that to the gate steps rather
+  `Dockerfile.lint` runs `go mod download` above them, so a cold cache still
-  than to linting as a whole: `Dockerfile.lint` runs `go mod download`
+  needs the network and only a warm one lints offline. Verified: `make lint`
-  above them, so a cold cache still needs the network and only a warm
+  green with every `PATH` directory containing a `golangci-lint` removed
-  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
+  `command -v golangci-lint` empty); two consecutive `script/lint` runs on an
-  on an untouched tree both executed the linter, 27.7s and 28.7s in the
+  untouched tree both executed the linter, 27.7s and 28.7s in the lint step
-  lint step under distinct epochs with the `COPY . .` layer `CACHED`
+  under distinct epochs with the `COPY . .` layer `CACHED` above them, at 42.2s
-  above them, at 42.2s and 41.8s wall clock — the no-cache rule was not
+  and 41.8s wall clock — the no-cache rule was not weakened to shorten that.
-  weakened to shorten that. Negative control: a planted
+  Negative control: a planted `var unusedIssue46Sentinel = 1` failed
-  `var unusedIssue46Sentinel = 1` failed `script/lint` with
+  `script/lint` with
-  `report.go:173:5: var unusedIssue46Sentinel is unused (unused)`, and
+  `report.go:173:5: var unusedIssue46Sentinel is unused (unused)`, and failed
-  failed `make docker` at `[lint 9/9]` with the build stage stopped at
+  `make docker` at `[lint 9/9]` with the build stage stopped at `[builder 3/12]`
-  `[builder 3/12]` — `COPY --from=lint`, `script/bootstrap`, the test
+  — `COPY --from=lint`, `script/bootstrap`, the test gate and `make build` all
-  gate and `make build` all zero occurrences — then reverted clean. The
+  zero occurrences — then reverted clean. The drift guard fails on a tag-only
-  drift guard fails on a tag-only disagreement, on a digest-only
+  disagreement, on a digest-only disagreement, and on an unreadable reference,
-  disagreement, and on an unreadable reference, naming both sides.
+  naming both sides. `make docker` green in 5m35s with all six gates executing
-  `make docker` green in 5m35s with all six gates executing under one
+  under one epoch (lint 37.6s, test 25.2s reporting
-  epoch (lint 37.6s, test 25.2s reporting
+  `ok sneak.berlin/go/sfdupes 1.938s coverage: 88.5%`, not `(cached)`). The
-  `ok sneak.berlin/go/sfdupes 1.938s coverage: 88.5%`, not `(cached)`).
+  non-root quirk still holds: in the builder image with the Go test cache off,
-  The non-root quirk still holds: in the builder image with the Go test
+  `--user 0:0` fails `TestScanHardlinkRunFailsTogether` (exit 1) where the
-  cache off, `--user 0:0` fails `TestScanHardlinkRunFailsTogether`
+  unprivileged user passes (exit 0). Noted for follow-up, not fixed here:
-  (exit 1) where the unprivileged user passes (exit 0). Noted for
+  `golangci-lint` warns that the `gomodguard` linter is deprecated since v2.12.0
-  follow-up, not fixed here: `golangci-lint` warns that the
+  in favour of `gomodguard_v2`.
-  `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 #42): canonical `REPO_POLICIES.md:97` requires
-  `REPO_POLICIES.md:97` requires it, and the inline install left the
+  it, and the inline install left the build stage maintaining its own notion of
-  build stage maintaining its own notion of the toolchain — exactly
+  the toolchain — exactly the divergence #24 exists to close, one layer down.
-  the divergence #24 exists to close, one layer down. The stage now
+  The stage now copies `script/` plus `go.mod`/`go.sum` and runs
-  copies `script/` plus `go.mod`/`go.sum` and runs `script/bootstrap`,
+  `script/bootstrap`, which ends in `go mod download`, so the separate
-  which ends in `go mod download`, so the separate invocation of that
+  invocation of that is gone. `COPY --from=lint /usr/bin/golangci-lint` stays,
-  is gone. `COPY --from=lint /usr/bin/golangci-lint` stays, and moves
+  and moves above the bootstrap layer. It is the only edge making this stage
-  above the bootstrap layer. It is the only edge making this stage
+  depend on the lint stage, so deleting it as redundant would end fail-fast
-  depend on the lint stage, so deleting it as redundant would end
+  linting silently. Letting bootstrap install its own linter here would have
-  fail-fast linting silently. Letting bootstrap install its own linter
+  reintroduced the second toolchain and paid for a from-source build of it. What
-  here would have reintroduced the second toolchain and paid for a
+  makes the two stages provably one toolchain rather than two that happen to
-  from-source build of it. What makes the two stages provably one
+  agree is a new `script/verify-linter-pin`, run in the build stage on the
-  toolchain rather than two that happen to agree is a new
+  binary that arrives from the lint stage, before bootstrap: it fails the build
-  `script/verify-linter-pin`, run in the build stage on the binary
+  naming both versions unless that binary is the version `script/bootstrap`
-  that arrives from the lint stage, before bootstrap: it fails the
+  pins. Bootstrap's own check could not serve that purpose — it reinstalls its
-  build naming both versions unless that binary is the version
+  pin from source and then verifies whatever `PATH` resolves, so drift
-  `script/bootstrap` pins. Bootstrap's own check could not serve that
+  self-heals silently and a lint stage image bumped on its own would lint at the
-  purpose — it reinstalls its pin from source and then verifies
+  new version while `make check` ran at the old one, green. The linter version
-  whatever `PATH` resolves, so drift self-heals silently and a lint
+  is pinned in two independent places (the lint stage image digest and
-  stage image bumped on its own would lint at the new version while
-  `make check` ran at the old one, green. The linter version is pinned
-  in two independent places (the lint stage image digest and
   `GOLANGCI_LINT_VERSION`) and nothing else keeps them in sync, so a
   half-applied bump is now a build failure. The pin is read out of
-  `script/bootstrap`, which stays the single source of truth; a pin
+  `script/bootstrap`, which stays the single source of truth; a pin that cannot
-  that cannot be read is a hard failure, not a skip. The check needs
+  be read is a hard failure, not a skip. The check needs no `CHECK_EPOCH`: its
-  no `CHECK_EPOCH`: its only inputs are the copied binary and
+  only inputs are the copied binary and `script/`, so Docker invalidates the
-  `script/`, so Docker invalidates the layer exactly when a cached
+  layer exactly when a cached result would stop being true, and it is documented
-  result would stop being true, and it is documented with the other
+  with the other entrypoints in the README. `$GOPATH/bin` joins `PATH` because
-  entrypoints in the README. `$GOPATH/bin` joins `PATH` because
+  that is where bootstrap's `go install` lands and bootstrap verifies its
-  that is where bootstrap's `go install` lands and bootstrap verifies
+  installs against what `PATH` resolves — nothing in the image is shadowed by
-  its installs against what `PATH` resolves — nothing in the image is
+  it, the directory does not exist until bootstrap runs. Everything added sits
-  shadowed by it, the directory does not exist until bootstrap runs.
+  above `ARG CHECK_EPOCH`, and the `chown` and `USER builder` still precede
-  Everything added sits above `ARG CHECK_EPOCH`, and the `chown` and
+  `make check`. Verified: the guard fails the build with both versions named
-  `USER builder` still precede `make check`. Verified: the guard fails
+  when the lint stage's linter is faked to a different version, and an
-  the build with both versions named when the lint stage's linter is
+  unmodified build still passes it; bootstrap runs clean under Alpine's `sh` and
-  faked to a different version, and an unmodified build still passes
+  its `apk` branch, installing `git` and `make` and finding the copied linter
-  it; bootstrap runs clean under Alpine's `sh` and its `apk` branch,
+  already at the pin; a second build served the bootstrap and dependency layers
-  installing `git` and `make` and finding the copied
+  `CACHED` while both gates ran with a fresh epoch; a planted `unused` finding
-  linter already at the pin; a second build served the bootstrap and
+  failed the build at the lint gate in 48.9s with the build stage's `make check`
-  dependency layers `CACHED` while both gates ran with a fresh epoch;
+  never starting; and the suite run in the image as `--user 0:0` fails
-  a planted `unused` finding failed the build at the lint gate in
+  `TestScanHardlinkRunFailsTogether`, so the drop to the unprivileged user is
-  48.9s with the build stage's `make check` never starting; and the
+  still load-bearing. That last check needs the Go test cache disabled — the
-  suite run in the image as `--user 0:0` fails
+  first attempt reported `ok ... (cached)` as root, reusing the result the
-  `TestScanHardlinkRunFailsTogether`, so the drop to the unprivileged
+  build-time run had left in the shared cache, which would have read as a pass.
-  user is still load-bearing. That last check needs the Go test cache
+  Build wall time, on a shared host running many concurrent builds and so noisy:
-  disabled — the first attempt reported `ok ... (cached)` as root,
+  2m13s on an unchanged tree, 2m17s and 4m29s for two builds after a source
-  reusing the result the build-time run had left in the shared cache,
+  change, 5m14s cold. Only the cold one breaches the policy ceiling, and not
-  which would have read as a pass. Build wall time, on a shared host
+  because of this change — `chown -R builder:builder /src /home/builder` walks
-  running many concurrent builds and so noisy: 2m13s on an unchanged
+  the module cache and re-runs on every source change, and it alone varied
-  tree, 2m17s and 4m29s for two builds after a source change, 5m14s
+  between 77s and 210s across those four builds, which is also the whole spread
-  cold. Only the cold one breaches the policy ceiling, and not because
+  in the totals. The same cold measurement against `main` is 5m03s with a 209s
-  of this change — `chown -R builder:builder /src /home/builder` walks
+  `chown`. Filed as #43
-  the module cache and re-runs on every source change, and it alone
+- bust the Docker layer cache for the gate steps, so `script/cibuild` and
-  varied between 77s and 210s across those four builds, which is also
+  `script/docker` cannot report a green they did not earn (2026-08-09, branch
-  the whole spread in the totals. The same cold measurement against
+  `cibuild-cache-bust`, closes #32): both scripts were bare `docker build`
-  `main` is 5m03s with a 209s `chown`. Filed as #43
+  invocations with no cache control, and the `Dockerfile` copies the tree before
-- bust the Docker layer cache for the gate steps, so `script/cibuild`
+  running its gates, so on an unchanged tree Docker served those layers from
-  and `script/docker` cannot report a green they did not earn
+  cache and the build exited 0 having executed nothing. That is not hypothetical
-  (2026-08-09, branch `cibuild-cache-bust`, closes #32): both scripts
+  here — every merge this repo has done is a non-fast-forward merge of an
-  were bare `docker build` invocations with no cache control, and the
+  undiverged branch, so each merge commit's tree is byte-identical to the branch
-  `Dockerfile` copies the tree before running its gates, so on an
+  head's and each merge CI run was almost certainly a full cache hit; and PR
-  unchanged tree Docker served those layers from cache and the build
+  #31's reviewer found `make docker` returning success as a 17-layer cache hit,
-  exited 0 having executed nothing. That is not hypothetical here —
+  catching it only by being suspicious. The fix is `ARG CHECK_EPOCH` with the
-  every merge this repo has done is a non-fast-forward merge of an
+  scripts passing `--build-arg CHECK_EPOCH="$(date +%s)"`. Two details make or
-  undiverged branch, so each merge commit's tree is byte-identical to
+  break it. `ARG` is scoped per stage and this `Dockerfile` has three gates
-  the branch head's and each merge CI run was almost certainly a full
+  across two — `make fmt-check` and `make lint` in the lint stage, `make check`
-  cache hit; and PR #31's reviewer found `make docker` returning
+  in the build stage — so a single declaration would have left one stage
-  success as a 17-layer cache hit, catching it only by being
+  silently cacheable; it is declared in both. And BuildKit hashes the expanded
-  suspicious. The fix is `ARG CHECK_EPOCH` with the scripts passing
+  command, not the declaration, so a declared-but-unreferenced `ARG` invalidates
-  `--build-arg CHECK_EPOCH="$(date +%s)"`. Two details make or break
+  nothing: each gate `RUN` echoes the epoch, which also puts the value in the
-  it. `ARG` is scoped per stage and this `Dockerfile` has three gates
+  build log as evidence the layer really ran. Placement is below the dependency
-  across two — `make fmt-check` and `make lint` in the lint stage,
+  layers on purpose — a build that goes cold every time would be a different
-  `make check` in the build stage — so a single declaration would have
+  bug, not a fix. Verified by running each script twice back to back on an
-  left one stage silently cacheable; it is declared in both. And
+  unchanged tree under `BUILDKIT_PROGRESS=plain`: all three gates executed on
-  BuildKit hashes the expanded command, not the declaration, so a
+  all four runs, each with a fresh epoch in the log (`script/cibuild` 78.8s then
-  declared-but-unreferenced `ARG` invalidates nothing: each gate `RUN`
+  61.1s; `script/docker` 61.1s then 53.4s), and thirteen steps were still served
-  echoes the epoch, which also puts the value in the build log as
+  `CACHED` in the steady state — the lint stage's `WORKDIR /src`, both
-  evidence the layer really ran. Placement is below the dependency
+  `go mod download`s, `apk add`, `adduser`, the `chown`, every `go.mod`/`go.sum`
-  layers on purpose — a build that goes cold every time would be a
+  and source copy, the linter copy out of the lint stage, and the binary copy
-  different bug, not a fix. Verified by running each script twice back
+  into the runtime stage. The lint stage still gates the build stage: with a
-  to back on an unchanged tree under `BUILDKIT_PROGRESS=plain`: all
+  deliberate `unused` finding planted in the tree, the build failed at
-  three gates executed on all four runs, each with a fresh epoch in
+  `make lint` in 36.1s and the build-stage `make check` never started. The build
-  the log (`script/cibuild` 78.8s then 61.1s; `script/docker` 61.1s
+  stage also still drops to the unprivileged `builder` user before `make check`,
-  then 53.4s), and twelve steps were still served `CACHED` in the
+  which the suite depends on rather than merely prefers: forcing the same image
-  steady state — both `go mod download`s, `apk add`, `adduser`, the
+  to run the tests as root fails `TestScanHardlinkRunFailsTogether`, because
-  `chown`, every `go.mod`/`go.sum` and source copy, the linter copy
+  root reads straight through the `chmod(0)` the test uses to prove hard links
-  out of the lint stage, and the binary copy into the runtime stage.
+  are read once. This is the local fix only; propagating it to the canonical
-  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`
+- check the installed golangci-lint version in `script/bootstrap` instead of
-  instead of only its presence (2026-08-09, branch
+  only its presence (2026-08-09, branch `bootstrap-version-check`, closes #24):
-  `bootstrap-version-check`, closes #24): `missing golangci-lint` meant
+  `missing golangci-lint` meant any linter already on `PATH` satisfied the
-  any linter already on `PATH` satisfied the check, so the pin was never
+  check, so the pin was never consulted and the v2.12.2 bump from #3 was inert
-  consulted and the v2.12.2 bump from #3 was inert on every host that
+  on every host that already had one — this host ran v2.10.1 against a v2.12.2
-  already had one — this host ran v2.10.1 against a v2.12.2 pin,
+  pin, `make check` went green, and `make docker` then rejected the same commit
-  `make check` went green, and `make docker` then rejected the same
+  with findings the local gate never saw. The version now lives in one place,
-  commit with findings the local gate never saw. The version now lives
+  `GOLANGCI_LINT_VERSION`, with the `go install` module ref derived from it so a
-  in one place, `GOLANGCI_LINT_VERSION`, with the `go install` module
+  bump cannot half-apply; a `golangci_lint_version` helper parses
-  ref derived from it so a bump cannot half-apply; a
+  `golangci-lint --version` (taking the field after the word `version` and
-  `golangci_lint_version` helper parses `golangci-lint --version`
+  tolerating an optional leading `v`, which the module ref carries and the
-  (taking the field after the word `version` and tolerating an optional
+  binary's output does not), and any version that is not the pin — older, newer,
-  leading `v`, which the module ref carries and the binary's output does
+  absent or unparseable — is reinstalled. The install is then verified against
-  not), and any version that is not the pin — older, newer, absent or
+  the binary `PATH` actually resolves: `go install` writes into `GOBIN` (or
-  unparseable — is reinstalled. The install is then verified against the
+  `GOPATH/bin`) while `make lint` runs whichever `golangci-lint` comes first on
-  binary `PATH` actually resolves: `go install` writes into `GOBIN` (or
+  `PATH`, so a wrong-version one sitting ahead of it — nix, apt, brew, apk, or
-  `GOPATH/bin`) while `make lint` runs whichever `golangci-lint` comes
+  the `/usr/local/bin` copy the `Dockerfile` builder stage makes — would swallow
-  first on `PATH`, so a wrong-version one sitting ahead of it — nix,
+  the install and leave the local gate disagreeing with CI under an affirmative
-  apt, brew, apk, or the `/usr/local/bin` copy the `Dockerfile` builder
+  `bootstrap complete`. Bootstrap now re-reads the effective version after
-  stage makes — would swallow the install and leave the local gate
+  installing and, on a mismatch, prints both paths and both versions to stderr
-  disagreeing with CI under an affirmative `bootstrap complete`.
+  and exits non-zero instead of claiming success; it does not reorder anyone's
-  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
+  connected, so a present-but-broken binary says why rather than reinstalling
-  reinstalling forever in silence, and is bounded by `timeout(1)` where
+  forever in silence, and is bounded by `timeout(1)` where that exists, so a
-  that exists, so a wedged binary cannot hang bootstrap. `git`, `make`
+  wedged binary cannot hang bootstrap. `git`, `make` and `go` keep their
-  and `go` keep their presence-only checks and now say why in a
+  presence-only checks and now say why in a comment: they are host
-  comment: they are host package-manager tools the repo deliberately
+  package-manager tools the repo deliberately does not pin, with `go.mod`
-  does not pin, with `go.mod` governing the language version and the
+  governing the language version and the digest-pinned images covering
-  digest-pinned images covering reproducible builds. Verified on this
+  reproducible builds. Verified on this host by bootstrapping from v2.10.1 to
-  host by bootstrapping from v2.10.1 to v2.12.2 and running it again to
+  v2.12.2 and running it again to a no-op, plus stub runs of the real script
-  a no-op, plus stub runs of the real script under `dash` covering a
+  under `dash` covering a thirteen-input parse matrix (absent, older, newer,
-  thirteen-input parse matrix (absent, older, newer, host-style,
+  host-style, image-style, leading-`v`, stderr-only, empty, non-zero exit,
-  image-style, leading-`v`, stderr-only, empty, non-zero exit, impostor
+  impostor binary, `(devel)`, trailing `version`), a shadowed install that must
-  binary, `(devel)`, trailing `version`), a shadowed install that must
+  exit non-zero, an install destination not on `PATH` at all, `GOBIN` set, and a
-  exit non-zero, an install destination not on `PATH` at all, `GOBIN`
+  wedged binary that must hit the timeout; `make check` and `make lint` are
-  set, and a wedged binary that must hit the timeout; `make check` and
+  clean at v2.12.2, so v2.10.1 was not hiding any findings on `main`
-  `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 #6): `hashPhase` used to return the moment
-  moment `recordRun` failed and abandon the pool — the feeder parked
+  `recordRun` failed and abandon the pool — the feeder parked forever on a full
-  forever on a full `jobs` channel and every worker on a full
+  `jobs` channel and every worker on a full `results` channel. That only stopped
-  `results` channel. That only stopped being invisible when #4 landed
+  being invisible when #4 landed and `runScan` began unwinding instead of
-  and `runScan` began unwinding instead of calling `os.Exit`. The
+  calling `os.Exit`. The pool is now an owned, context-aware `hashPool`: every
-  pool is now an owned, context-aware `hashPool`: every blocking send
+  blocking send in the feeder and the workers selects on `ctx.Done()`, `jobs` is
-  in the feeder and the workers selects on `ctx.Done()`, `jobs` is
+  closed on every path out, and `hashPhase` defers `pool.stop()`, which cancels
-  closed on every path out, and `hashPhase` defers `pool.stop()`,
+  and then drains `results` until the last goroutine has exited — draining is
-  which cancels and then drains `results` until the last goroutine
+  what frees a worker already parked on a send. `ctx` is threaded from
-  has exited — draining is what frees a worker already parked on a
+  `cmd.Context()` through `runScan`, `syncScan`, both worker pools and the whole
-  send. `ctx` is threaded from `cmd.Context()` through `runScan`,
+  database layer (it is the first parameter everywhere), so #5 can hand this
-  `syncScan`, both worker pools and the whole database layer (it is
+  path a signal and needs to add nothing else. The walk pool never leaked,
-  the first parameter everywhere), so #5 can hand this path a signal
+  because `walkPhase` always drains its events to close, but it has the same
-  and needs to add nothing else. The walk pool never leaked, because
+  unbounded-send shape and #5 will give it an early return, so it gets the same
-  `walkPhase` always drains its events to close, but it has the same
+  treatment plus a `ctx.Err()` guard after the walk: a cancelled walk yields a
-  unbounded-send shape and #5 will give it an early return, so it
+  partial size census, and every file it never reached looks vanished to the
-  gets the same treatment plus a `ctx.Err()` guard after the walk: a
+  update phase. That phase's own `BeginTx` fails on the same cancelled context
-  cancelled walk yields a partial size census, and every file it never
+  before deleting anything, so the guard is defence in depth rather than the
-  reached looks vanished to the update phase. That phase's own
+  only barrier — but it is the one that survives #5 deciding an interrupted scan
-  `BeginTx` fails on the same cancelled context before deleting
+  may commit what it has. Tests drive `run(scan)` against a database whose
-  anything, so the guard is defence in depth rather than the only
+  insert trigger aborts, and assert both that the scan fails instead of hanging
-  barrier — but it is the one that survives #5 deciding an interrupted
+  and that `runtime.NumGoroutine()` polls back to its pre-scan baseline; a
-  scan may commit what it has. Tests drive `run(scan)` against a
+  second set cancels a scan part-way through the walk — deterministically, by
-  database whose insert trigger aborts, and assert both that the scan
+  counting the scan's own consultations of `ctx.Done()` rather than racing a
-  fails instead of hanging and that `runtime.NumGoroutine()` polls
+  timer — and asserts that it stops at the guard holding a partial census and a
-  back to its pre-scan baseline; a second set cancels a scan part-way
+  still-populated record index, with every record intact. The remaining
-  through the walk — deterministically, by counting the scan's own
+  cancellation branches of both pools are covered by direct tests of
-  consultations of `ctx.Done()` rather than racing a timer — and
+  `sendEvent`, the walk workers, `dispatchDirs`, `feedHashJobs`, `hashWorker`
-  asserts that it stops at the guard holding a partial census and a
+  and `hashPhase`
-  still-populated record index, with every record intact. The
+- guarantee the database is closed on every fatal exit path (2026-08-09, branch
-  remaining cancellation branches of both pools are covered by direct
+  `db-close-on-fatal`, closes #4): `fatalf` and its `os.Exit(1)` are gone, so
-  tests of `sendEvent`, the walk workers, `dispatchDirs`,
+  the deferred `db.Close()` — and with it the SQLite WAL checkpoint — now
-  `feedHashJobs`, `hashWorker` and `hashPhase`
+  actually runs when a subcommand fails; `runScan`, `runReport`, `runTrees`,
-- guarantee the database is closed on every fatal exit path
+  `loadRecords` and `resolveRoots` return errors instead. The single exit point
-  (2026-08-09, branch `db-close-on-fatal`, closes #4): `fatalf` and
+  is `run` in `main.go`: it maps a `fatalError` (anything a subcommand returned)
-  its `os.Exit(1)` are gone, so the deferred `db.Close()` — and with
+  to exit 1 and cobra's own argument and flag errors to exit 2, which keeps a
-  it the SQLite WAL checkpoint — now actually runs when a subcommand
+  runtime failure from being reported as a usage error or printing the usage
-  fails; `runScan`, `runReport`, `runTrees`, `loadRecords` and
+  text. New `main_test.go` drives the CLI in-process and asserts the exit codes
-  `resolveRoots` return errors instead. The single exit point is `run`
+  from README §Error handling plus the stdout/stderr split, including that a
-  in `main.go`: it maps a `fatalError` (anything a subcommand
+  fatal error raised after the database is open leaves no `-wal`/`-shm` sidecar
-  returned) to exit 1 and cobra's own argument and flag errors to exit
+  behind for `scan`, `report` or `trees`
-  2, which keeps a runtime failure from being reported as a usage
+- update golangci-lint to v2.12.2 with the canonical config (2026-08-09, branch
-  error or printing the usage text. New `main_test.go` drives the CLI
+  `golangci-v2.12.2`, merged as `38a01bd`, closes #3): bumped the pinned linter
-  in-process and asserts the exit codes from README §Error handling
+  in the `Dockerfile` lint stage and `script/bootstrap` from v2.12.1 to v2.12.2,
-  plus the stdout/stderr split, including that a fatal error raised
+  and replaced `.golangci.yml` with the canonical file — the linter settings
-  after the database is open leaves no `-wal`/`-shm` sidecar behind
-  for `scan`, `report` or `trees`
-- 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
+  `linters.settings` per the v2 schema, so they are actually applied; no new
-  applied; no new lint findings surfaced
+  lint findings surfaced
-- convert Makefile targets to scripts-to-rule-them-all `script/`
+- convert Makefile targets to scripts-to-rule-them-all `script/` entrypoints
-  entrypoints like the other managed repos (2026-07-26, commit
+  like the other managed repos (2026-07-26, commit `3abeacf`, closes #1): all 12
-  `3abeacf`, closes #1): all 12 `script/` entrypoints exist
+  `script/` entrypoints exist (`bootstrap`, `setup`, `projectname`, `test`,
-  (`bootstrap`, `setup`, `projectname`, `test`, `lint`, `fmt`,
+  `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
-  `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
+  `install-precommit`) and every Makefile target is now a thin shim over them,
-  `install-precommit`) and every Makefile target is now a thin shim
+  matching the other managed repos
-  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 — an operator watching operand 3 of 14 hash 300k files concluded
-  that looked like the whole run's — an operator watching operand 3 of
+  20M files were being skipped
-  14 hash 300k files concluded 20M files were being skipped
+- parallel walk (2026-07-24, branch `parallel-walk`): the walk pass was a single
-- parallel walk (2026-07-24, branch `parallel-walk`): the walk pass
+  goroutine and took hours at ~20M files on a busy pool (observed: 22M files in
-  was a single goroutine and took hours at ~20M files on a busy pool
+  4h on a ZFS server); it is now a per-directory worker-pool traversal that
-  (observed: 22M files in 4h on a ZFS server); it is now a
+  records size/mtime during the walk (folding away the separate stat pass,
-  per-directory worker-pool traversal that records size/mtime during
+  halving metadata I/O), and each `PATH` operand commits in its own transaction
-  the walk (folding away the separate stat pass, halving metadata
+  so an interrupted scan keeps completed operands
-  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
-- `go test` runs without `-race` — the repo mandates `CGO_ENABLED=0`
+  builds) and the race detector requires cgo
-  (pure-Go builds) and the race detector requires cgo

cancel_test.go

@@ -4,20 +4,35 @@ import (
 	"context"
 	"database/sql"
 	"errors"
+	"fmt"
 	"os"
+	"os/signal"
 	"path/filepath"
+	"slices"
 	"strconv"
+	"strings"
 	"sync"
 	"sync/atomic"
+	"syscall"
 	"testing"
 	"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
@@ -28,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
@@ -86,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
@@ -150,9 +173,13 @@ func assertRecordsIntact(t *testing.T, db *sql.DB, before []string) {
 // Every one of those records would look vanished to the update phase.
 // The guard is what stops the scan there, and this test is what
 // notices if it stops doing so: deleting the guard, or making it
-// unreachable, makes the scan carry its truncated view into a later
+// unreachable, makes the scan carry its truncated view into the update
-// phase and fail there instead, with a wrapped error rather than the
+// phase, which counts every record the walk never reached for removal.
-// bare cancellation.
+//
+// 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) {
@@ -182,10 +209,10 @@ func TestSyncScanCancelledMidWalkKeepsRecords(t *testing.T) {
 
 // assertWalkGuardAborted checks that the scan stopped at the post-walk
 // guard: with a census that is neither empty (the walk really ran)
-// nor complete (it really was cut short), and with the guard's own
+// nor complete (it really was cut short), and with no record counted
-// bare cancellation as the error. A wrapped error means the partial
+// for removal. A removal count means the partial census was carried
-// census was carried past the guard into the hash or update phase,
+// past the guard into the update phase, which is the failure this test
-// which is the failure this test exists to catch.
+// exists to catch.
 func assertWalkGuardAborted(t *testing.T, st scanStats, err error) {
 	t.Helper()
 
@@ -194,12 +221,6 @@ func assertWalkGuardAborted(t *testing.T, st scanStats, err error) {
 			err, context.Canceled)
 	}
 
-	if errors.Unwrap(err) != nil {
-		t.Errorf("syncScan reported %q, want the guard's bare "+
-			"cancellation: a wrapped error means the truncated census "+
-			"reached a later phase", err)
-	}
-
 	if st.unchanged == 0 {
 		t.Fatalf("stats = %+v: the census is empty, so the walk never "+
 			"ran and the guard was reached for the wrong reason", st)
@@ -211,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",
@@ -260,6 +282,252 @@ func TestSyncScanCancelledBeforeLoadIndex(t *testing.T) {
 	assertRecordsIntact(t, db, before)
 }
 
+// hashCancelAtDone is the consultation on which the mid-hash test's
+// context cancels itself. The walk of buildWalkCancelTree spends about
+// one per file and three per directory, and the hash phase then one per
+// file hashed, so this lands about half way through the hash phase.
+const hashCancelAtDone = walkCancelFiles + 3*walkCancelDirs +
+	walkCancelFiles/2
+
+// TestSyncScanCancelledMidHashKeepsHashedRecords cancels a first scan
+// part-way through its hash phase. The fixture holds fewer files than a
+// batch, so every file hashed is still waiting to be committed: the scan
+// must commit them all before it returns, and the next scan must hash
+// only the rest.
+func TestSyncScanCancelledMidHashKeepsHashedRecords(t *testing.T) {
+	t.Parallel()
+
+	dir := buildWalkCancelTree(t)
+	db := openTestDB(t)
+
+	st, err := syncScan(newWalkClock(hashCancelAtDone), db,
+		[]string{dir}, walkCancelWorkers, false)
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("syncScan cancelled mid-hash = %v, want %v",
+			err, context.Canceled)
+	}
+
+	if st.walked != walkCancelFiles || st.added == 0 ||
+		st.added >= walkCancelFiles {
+		t.Fatalf("stats = %+v: want the walk complete and the hash phase "+
+			"cut short", st)
+	}
+
+	if got := len(dbRecords(t, db)); got != st.added {
+		t.Errorf("%d records after the cancelled scan, want the %d it hashed",
+			got, st.added)
+	}
+
+	hashed := st.added
+
+	st = syncTree(t, db, dir)
+	if st.added != walkCancelFiles-hashed || st.unchanged != hashed {
+		t.Errorf("next scan stats = %+v, want %d added %d unchanged",
+			st, walkCancelFiles-hashed, hashed)
+	}
+}
+
+// storedPaths opens the database at path as report does, which fails
+// unless it is a valid database, and returns its records' paths.
+func storedPaths(t *testing.T, path string) []string {
+	t.Helper()
+
+	db, err := openReportDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	return recordPaths(dbRecords(t, db))
+}
+
+// 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 and nothing on
+// stdout, leave the database valid and as 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)
+
+	err := runScan(t.Context(), []string{dir}, walkCancelWorkers, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	before := storedPaths(t, path)
+
+	// A vanished file and a new one: the interrupted scan records
+	// neither.
+	gone := filepath.Join(dir, "a", "unique.bin")
+
+	err = os.Remove(gone)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	added := writeFile(t, dir, "a/new.bin", pattern(50, 10))
+	shown := len(stderr())
+	done := make(chan struct{})
+
+	go func() {
+		defer close(done)
+
+		err = runScan(cancelledContext(t), []string{dir}, walkCancelWorkers,
+			false)
+	}()
+
+	awaitReturn(t, done, "runScan")
+
+	if !errors.Is(err, errInterrupted) {
+		t.Fatalf("runScan on a cancelled context = %v, want %v",
+			err, errInterrupted)
+	}
+
+	want := "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) {
+		t.Errorf("records = %q after the interrupted scan, want %q",
+			got, before)
+	}
+
+	err = runScan(t.Context(), []string{dir}, walkCancelWorkers, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	got := storedPaths(t, path)
+	if slices.Contains(got, gone) || !slices.Contains(got, added) {
+		t.Errorf("records = %q after the next scan, want %q gone and %q "+
+			"added", got, gone, added)
+	}
+}
+
+// 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, write nothing to stdout, close the
+// 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)
+
+	err := runScan(newWalkClock(hashCancelAtDone), []string{dir},
+		walkCancelWorkers, false)
+	if !errors.Is(err, errInterrupted) {
+		t.Fatalf("runScan interrupted mid-hash = %v, want %v",
+			err, errInterrupted)
+	}
+
+	holdScanLock(t, path)
+
+	want := fmt.Sprintf("scan: interrupted after %d files\n", walkCancelFiles)
+	if got := stderr(); !strings.HasSuffix(got, want) {
+		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)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	// A plain close also removes the sidecars, but leaves WAL mode on.
+	var mode string
+
+	err = db.QueryRowContext(t.Context(), "PRAGMA journal_mode").Scan(&mode)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if mode != "delete" {
+		t.Errorf("journal mode = %q after the interrupted scan, want %q",
+			mode, "delete")
+	}
+
+	kept := len(dbRecords(t, db))
+	if kept == 0 || kept >= walkCancelFiles {
+		t.Errorf("%d records after the interrupted scan, want those it "+
+			"hashed: some but not all of the %d files", kept, walkCancelFiles)
+	}
+}
+
+// TestInterruptContextCatchesSIGTERM sends SIGTERM to the test process
+// while the scan's handler is installed, and checks that it cancels the
+// scan's context.
+//
+//nolint:paralleltest // signals the whole process: must not run beside a scan
+func TestInterruptContextCatchesSIGTERM(t *testing.T) {
+	// Caught here as well, so that a handler that misses SIGTERM fails
+	// this test instead of ending the test process.
+	caught := make(chan os.Signal, 1)
+	signal.Notify(caught, syscall.SIGTERM)
+
+	defer signal.Stop(caught)
+
+	ctx, stop := interruptContext(t.Context())
+	defer stop()
+
+	err := syscall.Kill(os.Getpid(), syscall.SIGTERM)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	select {
+	case <-ctx.Done():
+	case <-time.After(poolUnwind):
+		t.Fatal("SIGTERM did not cancel the scan's context")
+	}
+}
+
+// TestCommitFullBatchKeepsFailedBatch checks that a full batch whose
+// commit fails, as it does once the scan is interrupted, stays in the
+// batch, so that syncScan's final commit saves it.
+func TestCommitFullBatchKeepsFailedBatch(t *testing.T) {
+	t.Parallel()
+
+	s := &scanState{db: openTestDB(t)}
+	for i := range updateBatchSize {
+		s.batch = append(s.batch, scanRec{path: "/f" + strconv.Itoa(i)})
+	}
+
+	err := s.commitFullBatch(cancelledContext(t))
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("commitFullBatch on a cancelled context = %v, want %v",
+			err, context.Canceled)
+	}
+
+	if len(s.batch) != updateBatchSize {
+		t.Errorf("batch holds %d records after the failed commit, want %d",
+			len(s.batch), updateBatchSize)
+	}
+}
+
 // drainClosed counts the values received from ch until it closes,
 // failing the test if it does not close within poolUnwind. A pool that
 // ignored its cancellation leaves its channel open with its goroutines
@@ -328,20 +596,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)
@@ -412,7 +709,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()
 
@@ -438,41 +739,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,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
+	"net/url"
 	"os"
 	"path/filepath"
 	"slices"
@@ -107,7 +108,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)
 	}
@@ -219,6 +232,12 @@ func openReportDatabase(ctx context.Context,
 	}
 
 	v, err := userVersion(ctx, db)
+	if err == nil && v == 0 {
+		// An empty database passes this check and fails the version
+		// check below.
+		err = checkUnversioned(ctx, db)
+	}
+
 	if err != nil {
 		_ = db.Close()
 
@@ -245,6 +264,11 @@ func initSchema(ctx context.Context, db *sql.DB) error {
 
 	switch v {
 	case 0:
+		err = checkUnversioned(ctx, db)
+		if err != nil {
+			return err
+		}
+
 		return createSchema(ctx, db)
 	case schemaVersion:
 		return nil
@@ -254,25 +278,65 @@ 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. createSchema creates the files table and
+// sets the version together, so a files table at version 0 was made by
+// something else. Adopting it could corrupt unrelated data, so that is
+// 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
+
+	err := db.QueryRowContext(ctx,
+		"SELECT name FROM sqlite_master "+
+			"WHERE type = 'table' AND name = 'files'").Scan(&name)
+
+	switch {
+	case err == nil:
+		return fmt.Errorf(
+			"has a files table but no schema version; "+
+				"remove the file and rescan: %w", errSchemaVersion)
+	case errors.Is(err, sql.ErrNoRows):
+		return nil
+	default:
+		return fmt.Errorf("check for files table: %w", err)
+	}
+}
+
 // 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
 }
 

db_test.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"path/filepath"
 	"slices"
+	"strings"
 	"testing"
 )
 
@@ -77,6 +78,76 @@ func TestOpenScanDatabaseCreates(t *testing.T) {
 	}
 }
 
+func TestOpenDatabaseUnversionedForeign(t *testing.T) {
+	t.Parallel()
+
+	// A database that has a files table but user_version 0, written by
+	// some other tool. report, trees and scan must refuse it with the
+	// schema-version error, not adopt it and not emit a raw SQLite
+	// "table files already exists".
+	path := testDBPath(t)
+
+	db, err := sql.Open("sqlite", path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = db.ExecContext(t.Context(), "CREATE TABLE files (x INTEGER)")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_ = db.Close()
+
+	_, err = openReportDatabase(t.Context(), path)
+	if !errors.Is(err, errSchemaVersion) ||
+		!strings.Contains(err.Error(), "remove the file and rescan") {
+		t.Fatalf("report: err = %v, want errSchemaVersion telling the "+
+			"operator to remove the file and rescan", err)
+	}
+
+	_, err = openScanDatabase(t.Context(), path)
+	if !errors.Is(err, errSchemaVersion) ||
+		!strings.Contains(err.Error(), "remove the file and rescan") {
+		t.Fatalf("scan: err = %v, want errSchemaVersion telling the "+
+			"operator to remove the file and rescan", err)
+	}
+}
+
+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()
 
@@ -86,9 +157,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)
@@ -105,7 +178,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)
 	}
 }
 

go.mod

@@ -6,6 +6,7 @@ require (
 	github.com/schollz/progressbar/v3 v3.19.1
 	github.com/spf13/cobra v1.10.2
 	golang.org/x/sys v0.46.0
+	golang.org/x/term v0.44.0
 	modernc.org/sqlite v1.54.0
 )
 
@@ -19,7 +20,6 @@ require (
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
-	golang.org/x/term v0.44.0 // indirect
 	modernc.org/libc v1.74.1 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect

main.go

@@ -15,6 +15,7 @@
 //	sfdupes scan [--workers N] [-x] PATH...
 //	sfdupes report > dupes.tsv
 //	sfdupes trees > dupetrees.tsv
+//	sfdupes --version
 //
 // See README.md for the complete specification.
 package main
@@ -50,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.
 //
@@ -87,6 +92,9 @@ func run(args []string, stdout, stderr io.Writer) int {
 	switch {
 	case err == nil:
 		return exitOK
+	case errors.Is(err, errInterrupted):
+		// The interrupted scan has printed its own line.
+		return exitFatal
 	case errors.As(err, &fatal):
 		// The command ran and failed: a runtime error, reported
 		// without the usage text that a usage error gets.
@@ -94,22 +102,35 @@ 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
 	}
 }
 
 // newRootCommand builds the command tree. Everything on stdout is
-// machine-readable data; all human-facing output (help, usage, errors)
+// machine-readable data, the version line included; all human-facing
-// goes to stderr.
+// output (help, usage, errors) goes to stderr.
 func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
+	var showVersion bool
+
+	printVersion := runE(func(context.Context, []string) error {
+		_, err := fmt.Fprintf(stdout, "sfdupes %s\n", Version)
+		if err != nil {
+			return fmt.Errorf("write stdout: %w", err)
+		}
+
+		return nil
+	})
+
 	root := &cobra.Command{
-		Use:     "sfdupes",
+		Use:   "sfdupes",
-		Short:   "Find candidate duplicate files by size and head/tail/content SHA-256",
+		Short: "Find candidate duplicate files by size and head/tail/content SHA-256",
-		Version: Version,
+		Args:  cobra.NoArgs,
-		Args:    cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
-		RunE: func(cmd *cobra.Command, _ []string) error {
+			if showVersion {
+				return printVersion(cmd, args)
+			}
+
 			// A missing subcommand prints usage and exits 2: cobra
 			// prints the usage text for the returned error, and run
 			// maps everything that is not a fatal error to exit 2.
@@ -122,6 +143,11 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 	root.SetErr(stderr)
 	root.CompletionOptions.DisableDefaultCmd = true
 
+	// Cobra's built-in version flag prints through the help writer,
+	// stderr; this one prints to stdout.
+	root.Flags().BoolVarP(&showVersion, "version", "v", false,
+		"print the version to stdout")
+
 	var (
 		scanWorkers int
 		scanOneFS   bool
@@ -131,7 +157,13 @@ 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()
+
 			return runScan(ctx, args, scanWorkers, scanOneFS)
 		}),
 	}
@@ -163,13 +195,26 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 	return root
 }
 
-// runE adapts a subcommand implementation to cobra's RunE. Cobra
+// checkScanWorkers rejects a scan --workers value below 1. That is a
-// prints the error and the command's usage text for every error RunE
+// usage error reported in one line: cobra prints the returned message
-// returns, but a subcommand that ran and failed has no usage problem
+// without the usage text, and run exits 2.
-// to report: both are silenced here, and the error is marked fatal so
+func checkScanWorkers(cmd *cobra.Command, workers int) error {
-// that run reports it on stderr and exits 1 rather than 2. The command's
+	if workers >= 1 {
-// context is handed to the implementation: cancelling it unwinds the
+		return nil
-// scan's worker pools.
+	}
+
+	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
+// usage problem to report: both are silenced here, and the error is
+// marked fatal so that run reports it on stderr and exits 1 rather than
+// 2. The command's context is handed to the implementation: cancelling
+// it unwinds the scan's worker pools.
 func runE(
 	fn func(ctx context.Context, args []string) error,
 ) func(*cobra.Command, []string) error {

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,34 @@ 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.
+	for _, name := range []string{cmdReport, cmdTrees} {
+		t.Run(name, func(t *testing.T) {
+			path := testDBPath(t)
+			t.Setenv(databaseEnv, path)
+
+			var stdout, stderr bytes.Buffer
+
+			code := run([]string{name}, &stdout, &stderr)
+			if code != exitFatal {
+				t.Errorf("run(%s) = %d, want %d", name, code, exitFatal)
+			}
+
+			want := "sfdupes: " + path + ": no database (run \"sfdupes " +
+				"scan\" first, or set " + databaseEnv + ")\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)
+			}
+		})
+	}
+}
+
 func TestRunUsageErrors(t *testing.T) {
 	// Usage errors keep exiting 2 with cobra's own report on stderr.
 	cases := map[string]struct {
@@ -295,34 +349,108 @@ func TestRunUsageErrors(t *testing.T) {
 	}
 }
 
-// TestRunHelpAndVersionSucceed checks that the two informational flags
+func TestRunScanRejectsWorkersBelowOne(t *testing.T) {
-// exit 0 and keep their human-facing output on stderr.
+	// README §scan mode: --workers below 1 is a usage error reported in
-func TestRunHelpAndVersionSucceed(t *testing.T) {
+	// one line on stderr, before the scan opens the database.
-	t.Parallel()
+	for _, workers := range []string{"0", "-1"} {
+		t.Run(workers, func(t *testing.T) {
+			dbPath := testDBPath(t)
+			t.Setenv(databaseEnv, dbPath)
 
-	assertHumanOutput(t, "--help")
+			var stdout, stderr bytes.Buffer
-	assertHumanOutput(t, "--version")
+
+			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)
+			}
+		})
+	}
 }
 
-// assertHumanOutput runs sfdupes with one informational flag and checks
+func TestRunHelp(t *testing.T) {
-// that it succeeds with its output on stderr and stdout untouched
+	t.Parallel()
-// (README design goal 4).
-func assertHumanOutput(t *testing.T, arg string) {
-	t.Helper()
 
-	var stdout, stderr bytes.Buffer
+	// README §Subcommands: help goes to stderr, exits 0, and leaves
+	// stdout empty.
+	cases := [][]string{{"--help"}, {"-h"}, {cmdScan, "--help"}}
 
-	code := run([]string{arg}, &stdout, &stderr)
+	for _, args := range cases {
-	if code != exitOK {
+		var stdout, stderr bytes.Buffer
-		t.Errorf("run(%s) = %d, want %d", arg, code, exitOK)
+
+		code := run(args, &stdout, &stderr)
+		if code != exitOK {
+			t.Errorf("run(%v) = %d, want %d", args, code, exitOK)
+		}
+
+		if !strings.Contains(stderr.String(), usageMarker) {
+			t.Errorf("run(%v) stderr = %q, want the help text",
+				args, stderr.String())
+		}
+
+		if got := stdout.String(); got != "" {
+			t.Errorf("run(%v) stdout = %q, want nothing (data only)",
+				args, got)
+		}
+	}
+}
+
+func TestRunVersion(t *testing.T) {
+	t.Parallel()
+
+	// README §Subcommands: the version is one line on stdout, with
+	// nothing on stderr, and exits 0.
+	for _, arg := range []string{"--version", "-v"} {
+		var stdout, stderr bytes.Buffer
+
+		code := run([]string{arg}, &stdout, &stderr)
+		if code != exitOK {
+			t.Errorf("run(%s) = %d, want %d", arg, code, exitOK)
+		}
+
+		want := "sfdupes " + Version + "\n"
+		if got := stdout.String(); got != want {
+			t.Errorf("run(%s) stdout = %q, want %q", arg, got, want)
+		}
+
+		if got := stderr.String(); got != "" {
+			t.Errorf("run(%s) stderr = %q, want nothing", arg, got)
+		}
+	}
+}
+
+func TestRunVersionWriteFailureIsFatal(t *testing.T) {
+	t.Parallel()
+
+	// README §Error handling: a stdout write failure exits 1, reported
+	// in one line on stderr.
+	var stderr bytes.Buffer
+
+	code := run([]string{"--version"}, failingWriter{}, &stderr)
+	if code != exitFatal {
+		t.Errorf("run(--version) = %d, want %d", code, exitFatal)
 	}
 
-	if stderr.Len() == 0 {
+	want := "sfdupes: write stdout: " + errWriteFailed.Error() + "\n"
-		t.Errorf("run(%s) wrote nothing to stderr", arg)
+	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)
 	}
 }
 
@@ -360,17 +488,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)
 	}
 
@@ -378,10 +505,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)
 }
 
@@ -488,12 +646,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"
@@ -501,6 +661,12 @@ func TestRunReportSucceeds(t *testing.T) {
 		t.Errorf("stdout = %q, want %q", got, want)
 	}
 
+	want = "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)
 }
 
@@ -510,12 +676,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
@@ -526,6 +694,12 @@ func TestRunTreesSucceeds(t *testing.T) {
 		t.Errorf("stdout = %q, want %q", got, want)
 	}
 
+	want = "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)
 }
 
@@ -565,6 +739,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.
@@ -588,9 +829,11 @@ func TestRunSecondScanFails(t *testing.T) {
 
 	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)
 	}
@@ -601,7 +844,7 @@ 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)
 	}
 

package.json

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

progress.go

@@ -6,6 +6,7 @@ import (
 	"time"
 
 	"github.com/schollz/progressbar/v3"
+	"golang.org/x/term"
 )
 
 // plainInterval is the minimum time between progress lines when stderr
@@ -24,24 +25,23 @@ const percentScale = 100
 
 // stderrIsTTY reports whether stderr is attached to a terminal.
 func stderrIsTTY() bool {
-	fi, err := os.Stderr.Stat()
+	return term.IsTerminal(int(os.Stderr.Fd()))
-	if err != nil {
-		return false
-	}
-
-	return fi.Mode()&os.ModeCharDevice != 0
 }
 
 // progress renders one scan pass's progress on stderr. On a TTY it
 // delegates to the progressbar library (spinner style when the total is
 // unknown, full bar with count/percent/rate/elapsed/ETA otherwise). When
 // stderr is not a TTY it emits no ANSI redraws: it prints a plain
-// one-line update no more often than every plainInterval.
+// one-line update as the pass starts, then no more often than every
+// plainInterval.
 //
-// All methods must be called from the main goroutine only. A nil
+// All methods must be called from the main goroutine only. On a TTY
-// *progress is a valid no-display receiver: every method is a no-op,
+// the library also redraws a spinner from its own goroutine, several
-// so batched database flushes during the streaming pass can reuse the
+// times a second, so its count and elapsed time stay current while a
-// update-pass helpers without rendering anything.
+// 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)
@@ -53,10 +53,22 @@ type progress struct {
 
 func newProgress(label string, total int64) *progress {
 	p := &progress{label: label, total: total, start: time.Now()}
-	if !stderrIsTTY() {
+	if stderrIsTTY() {
+		p.bar = newBar(label, total)
+
 		return p
 	}
 
+	// Print the zero state at once: the first item may take minutes,
+	// and a pass must never look hung.
+	p.last = p.start
+	fmt.Fprintln(os.Stderr, p.plainLine())
+
+	return p
+}
+
+// newBar builds the TTY display for newProgress.
+func newBar(label string, total int64) *progressbar.ProgressBar {
 	opts := []progressbar.Option{
 		progressbar.OptionSetWriter(os.Stderr),
 		progressbar.OptionSetDescription(label),
@@ -81,9 +93,7 @@ func newProgress(label string, total int64) *progress {
 		)
 	}
 
-	p.bar = progressbar.NewOptions64(total, opts...)
+	return progressbar.NewOptions64(total, opts...)
-
-	return p
 }
 
 // increment records one completed item and refreshes the display.
@@ -113,21 +123,38 @@ func (p *progress) warnf(format string, args ...any) {
 		return
 	}
 
+	msg := escapePath(fmt.Sprintf(format, args...))
+
+	if p.bar != nil && p.total < 0 {
+		// The library also redraws a spinner from its own goroutine, so
+		// 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 {
 		_ = p.bar.Clear()
 	}
 
-	fmt.Fprintln(os.Stderr, escapePath(fmt.Sprintf(format, args...)))
+	fmt.Fprintln(os.Stderr, msg)
 }
 
-// finish terminates the pass's display.
+// finish terminates the pass's display. A bar whose pass stopped short
+// of its total, as an interrupted one does, is left as last drawn; the
+// library's Finish would fill it up.
 func (p *progress) finish() {
 	if p == nil {
 		return
 	}
 
 	if p.bar != nil {
-		_ = p.bar.Finish()
+		if p.total >= 0 && p.count < p.total {
+			_ = p.bar.Exit()
+		} else {
+			_ = p.bar.Finish()
+		}
 
 		fmt.Fprintln(os.Stderr)
 

progress_test.go

@@ -0,0 +1,189 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// spinnerIdle comfortably outlasts the 100ms interval at which the
+// progressbar library redraws a spinner from its own goroutine.
+const spinnerIdle = 500 * time.Millisecond
+
+//nolint:paralleltest // replaces the process-wide os.Stderr
+func TestStderrIsTTYFalseForNonTerminals(t *testing.T) {
+	r, pipe, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	regular, err := os.Create(filepath.Join(t.TempDir(), "stderr"))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	devNull, err := os.OpenFile(os.DevNull, os.O_WRONLY, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	saved := os.Stderr
+
+	t.Cleanup(func() {
+		os.Stderr = saved
+
+		for _, f := range []*os.File{r, pipe, regular, devNull} {
+			_ = f.Close()
+		}
+	})
+
+	cases := map[string]*os.File{
+		"a pipe":         pipe,
+		"a regular file": regular,
+		os.DevNull:       devNull,
+	}
+
+	for name, f := range cases {
+		os.Stderr = f
+
+		if stderrIsTTY() {
+			t.Errorf("stderrIsTTY() = true with stderr on %s", name)
+		}
+	}
+}
+
+// TestNewProgressPrintsBeforeFirstItem checks that each pass shows its
+// zero state the moment it starts when stderr is not a terminal, and
+// 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()
+	newProgress("hash", 10).increment()
+
+	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
+// os.Stderr whether or not it is a terminal, and stops the library's
+// redraws when the test ends.
+func newWalkSpinner(t *testing.T) *progress {
+	t.Helper()
+
+	p := &progress{
+		label: "walk", total: -1, start: time.Now(),
+		bar: newBar("walk", -1),
+	}
+	t.Cleanup(p.finish)
+
+	return p
+}
+
+// TestProgressWarningsOnOwnLines drives the terminal display of the walk
+// pass through a run of warnings with no items between them, as when the
+// walk meets many unreadable paths, for several of the spinner's
+// 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
+	// garbled only if a redraw lands while it is being written.
+	issued := 0
+	for start := time.Now(); time.Since(start) < spinnerIdle; issued++ {
+		p.warnf("warning")
+	}
+
+	// The spinner prints the warnings at its next redraw.
+	time.Sleep(spinnerIdle)
+
+	// A terminal shows each line as the text after its last carriage
+	// return.
+	shown := 0
+
+	for line := range strings.SplitSeq(stderr(), "\n") {
+		if !strings.Contains(line, "warning") {
+			continue
+		}
+
+		shown++
+
+		if text := line[strings.LastIndex(line, "\r")+1:]; text != "warning" {
+			t.Errorf("terminal shows %q, want %q", text, "warning")
+		}
+	}
+
+	if shown != issued {
+		t.Errorf("%d warning lines, want %d", shown, issued)
+	}
+}
+
+// TestSpinnerShowsCountAfterBurst checks that once a burst of items
+// faster than the redraw limit is over, the walk display shows every
+// item completed while it waits for the next one.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestSpinnerShowsCountAfterBurst(t *testing.T) {
+	stderr := captureStderr(t)
+	p := newWalkSpinner(t)
+
+	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,") {
+		t.Errorf("terminal shows %q, want a count of 2 of 10", shown)
+	}
+}

report_test.go

@@ -3,6 +3,8 @@ package main
 import (
 	"bytes"
 	"database/sql"
+	"errors"
+	"fmt"
 	"io"
 	"os"
 	"path/filepath"
@@ -114,6 +116,29 @@ func TestRunReportEscapesPaths(t *testing.T) {
 	}
 }
 
+func TestReportStdoutFailsWhileReading(t *testing.T) {
+	// Each row holds two paths longer than dir, so the report is more
+	// than twice the stdout buffer and stdout fails while rows are
+	// still being read, not at the final flush.
+	dir := "/" + strings.Repeat("d", 4096)
+
+	recs := make([]scanRec, ioBufSize/len(dir))
+	for i := range recs {
+		recs[i] = scanRec{
+			size: 1, head: "h", tail: "t", content: "c",
+			path: fmt.Sprintf("%s/%d", dir, i),
+		}
+	}
+
+	t.Setenv(databaseEnv, seedDatabase(t, recs))
+
+	err := runReport(t.Context(), failingWriter{})
+	if !errors.Is(err, errWriteFailed) ||
+		!strings.HasPrefix(err.Error(), "write stdout: ") {
+		t.Errorf("error = %v, want write stdout: %v", err, errWriteFailed)
+	}
+}
+
 func TestRunReportsIgnoreInsertionOrder(t *testing.T) {
 	// README §Constraints: identical database contents give identical
 	// output, whatever order the records were inserted in.
@@ -301,11 +326,13 @@ func TestDupeGroupsMtimeExcluded(t *testing.T) {
 func TestDupeGroupsTieBreak(t *testing.T) {
 	t.Parallel()
 
+	// The hashes sort opposite to the first paths, so ordering the
+	// groups by hash instead of by first path fails this test.
 	recs := []scanRec{
-		{size: 50, head: "b", tail: "b", content: "b", path: "/beta/2"},
+		{size: 50, head: "a", tail: "a", content: "a", path: "/beta/2"},
-		{size: 50, head: "b", tail: "b", content: "b", path: "/beta/1"},
+		{size: 50, head: "a", tail: "a", content: "a", path: "/beta/1"},
-		{size: 50, head: "a", tail: "a", content: "a", path: "/alpha/2"},
+		{size: 50, head: "b", tail: "b", content: "b", path: "/alpha/2"},
-		{size: 50, head: "a", tail: "a", content: "a", path: "/alpha/1"},
+		{size: 50, head: "b", tail: "b", content: "b", path: "/alpha/1"},
 	}
 
 	groups := dupeGroupsOf(t, recs)

scan.go

@@ -11,6 +11,7 @@ import (
 	"io"
 	"io/fs"
 	"os"
+	"os/signal"
 	"path/filepath"
 	"slices"
 	"strings"
@@ -57,6 +58,10 @@ const sampleWindow = 1024 * 1024
 // and hash worker pools.
 const workQueueDepth = 1024
 
+// errInterrupted reports a scan stopped by SIGINT or SIGTERM. runScan
+// has already printed its line, so run prints nothing more.
+var errInterrupted = errors.New("scan interrupted")
+
 // fileRec carries one statted file between the scan phases. dev and
 // ino identify the underlying inode so hard-linked paths can share
 // one read; both are zero when the platform exposes no inode.
@@ -90,15 +95,14 @@ type fileMeta struct {
 // scan fails before it walks the filesystem or opens the database.
 // Errors are returned rather than exiting, so that the deferred close —
 // which takes the database out of WAL mode — always runs, and the lock
-// is released after it. Cancelling ctx unwinds the worker pools and
+// is released after it. When ctx is cancelled, as by the SIGINT or
-// aborts the scan with the context's error.
+// SIGTERM that interruptContext catches, the scan keeps what it has
+// hashed (see syncScan), prints how many files its walk reached, and
+// 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 {
-		workers = 1
-	}
-
 	roots, err := resolveRoots(roots)
 	if err != nil {
 		return err
@@ -114,6 +118,12 @@ func runScan(ctx context.Context, roots []string, workers int,
 	defer func() { _ = lock.Close() }()
 
 	db, err := openScanDatabase(ctx, dbPath)
+	if err != nil && ctx.Err() != nil {
+		// Interrupted while opening; SQLite may report that with an
+		// error of its own rather than the context's.
+		return interrupted(0)
+	}
+
 	if err != nil {
 		return err
 	}
@@ -121,6 +131,10 @@ func runScan(ctx context.Context, roots []string, workers int,
 	defer closeScanDatabase(ctx, db, dbPath)
 
 	st, err := syncScan(ctx, db, roots, workers, oneFS)
+	if errors.Is(err, context.Canceled) {
+		return interrupted(st.walked)
+	}
+
 	if err != nil {
 		return fmt.Errorf("update database %s: %w", dbPath, err)
 	}
@@ -134,6 +148,34 @@ func runScan(ctx context.Context, roots []string, workers int,
 	return nil
 }
 
+// interruptContext returns a copy of ctx that the first SIGINT or
+// SIGTERM cancels; the scan command runs the scan under it. stop
+// releases the signals.
+func interruptContext(ctx context.Context) (context.Context, func()) {
+	// A SIGINT ignored from the start, as by a script's background job,
+	// stays ignored.
+	signals := []os.Signal{syscall.SIGTERM}
+	if !signal.Ignored(syscall.SIGINT) {
+		signals = append(signals, syscall.SIGINT)
+	}
+
+	ctx, stop := signal.NotifyContext(ctx, signals...)
+
+	// Stopping restores the default handling, so a second signal ends
+	// the process at once.
+	context.AfterFunc(ctx, stop)
+
+	return ctx, stop
+}
+
+// interrupted prints the line for a scan stopped by a signal after its
+// walk reached walked files, and returns errInterrupted.
+func interrupted(walked int) error {
+	fmt.Fprintf(os.Stderr, "scan: interrupted after %d files\n", walked)
+
+	return errInterrupted
+}
+
 // resolveRoots converts each PATH operand to an absolute, lexically
 // cleaned path (symlinks are not resolved) and verifies that it
 // exists. Database records are keyed by absolute path, so scan results
@@ -187,8 +229,9 @@ func pruneRoots(roots []string) []string {
 }
 
 // scanStats summarizes one scan's database synchronization for the
-// final stderr summary.
+// final stderr summary, or for the line an interrupted scan prints.
 type scanStats struct {
+	walked    int // files the walk reached
 	added     int
 	updated   int
 	removed   int
@@ -210,7 +253,30 @@ type scanState struct {
 	st        scanStats
 }
 
-// syncScan synchronizes the database with the filesystem under roots
+// syncScan synchronizes the database with the filesystem under roots;
+// see runPhases. When ctx is cancelled, as by an interrupt, it commits
+// the hashed records still waiting in the batch, starts no other write
+// or deletion, and returns the cancellation.
+func syncScan(ctx context.Context, db *sql.DB, roots []string,
+	workers int, oneFS bool,
+) (scanStats, error) {
+	s := &scanState{db: db}
+
+	err := s.runPhases(ctx, roots, workers, oneFS)
+	if err == nil || ctx.Err() == nil {
+		return s.st, err
+	}
+
+	// The one write made after the cancellation, so it cannot use ctx.
+	err = applyChanges(context.WithoutCancel(ctx), db, s.batch, nil, nil)
+	if err != nil {
+		return s.st, err
+	}
+
+	return s.st, ctx.Err()
+}
+
+// runPhases synchronizes the database with the filesystem under roots
 // in four sequential phases: walk (enumerate and stat every file,
 // building a complete size census), hash (read only the new or
 // changed — or previously unhashed — files whose size at least one
@@ -223,48 +289,41 @@ type scanState struct {
 // their content hash. Operands the walk cannot start from are dropped
 // first, so the records beneath them count as outside the roots unless
 // they lie under another root.
-func syncScan(ctx context.Context, db *sql.DB, roots []string,
+func (s *scanState) runPhases(ctx context.Context, roots []string,
 	workers int, oneFS bool,
-) (scanStats, error) {
+) error {
-	s := &scanState{db: db}
-
 	// 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))
 
 	err := s.loadIndex(ctx, roots)
 	if err != nil {
-		return s.st, err
+		return err
 	}
 
 	changed, unhashed := s.walkPhase(startWalk(ctx, roots, oneFS, workers))
 
 	// A cancelled walk stops early, so its size census covers only part
-	// of the roots, and every file it never reached looks vanished to
+	// of the roots, and every file it never reached would look vanished
-	// the update phase. Defence in depth rather than the only barrier:
+	// to the update phase. Stop before anything is written or deleted.
-	// that phase would today fail on its first BeginTx with the same
-	// cancelled context before deleting anything. But it is the barrier
-	// that survives a later decision to let an interrupted scan commit
-	// what it has, and it turns a confusing failure deep in the update
-	// phase into a clean abort at the phase boundary.
 	err = ctx.Err()
 	if err != nil {
-		return s.st, err
+		return err
 	}
 
 	s.partition(changed, unhashed)
 
 	err = s.hashPhase(ctx, workers)
 	if err != nil {
-		return s.st, err
+		return err
 	}
 
 	err = s.updatePhase(ctx)
 	if err != nil {
-		return s.st, err
+		return err
 	}
 
-	return s.st, s.contentPhase(ctx, workers)
+	return s.contentPhase(ctx, workers)
 }
 
 // walkableRoots returns the operands the walk can start from: regular
@@ -349,6 +408,7 @@ func (s *scanState) walkPhase(
 		}
 
 		s.sizes = append(s.sizes, ev.rec.size)
+		s.st.walked++
 
 		prog.increment()
 
@@ -552,16 +612,22 @@ func (s *scanState) recordRun(ctx context.Context, r hashResult) error {
 }
 
 // commitFullBatch commits the running batch once it holds
-// updateBatchSize records.
+// updateBatchSize records. A batch that fails to commit is kept: the
+// commit fails when the scan is interrupted, and syncScan then commits
+// the batch itself.
 func (s *scanState) commitFullBatch(ctx context.Context) error {
 	if len(s.batch) < updateBatchSize {
 		return nil
 	}
 
 	err := applyBatch(ctx, s.db, s.batch, nil, nil)
+	if err != nil {
+		return err
+	}
+
 	s.batch = s.batch[:0]
 
-	return err
+	return nil
 }
 
 // updatePhase writes the scan's tail under one progress display: the
@@ -1004,6 +1070,12 @@ func walkOneDir(ctx context.Context, job dirJob, oneFS bool,
 	var subs []dirJob
 
 	for _, e := range entries {
+		// A cancelled scan wants nothing more from this directory: stop
+		// rather than lstat the rest of a large one.
+		if ctx.Err() != nil {
+			return nil
+		}
+
 		p := filepath.Join(job.path, e.Name())
 
 		if e.IsDir() {

scan_test.go

@@ -6,14 +6,18 @@ import (
 	"crypto/sha256"
 	"database/sql"
 	"encoding/hex"
+	"errors"
 	"fmt"
 	"io"
+	"io/fs"
 	"os"
+	"os/signal"
 	"path/filepath"
 	"runtime"
 	"slices"
 	"strconv"
 	"strings"
+	"syscall"
 	"testing"
 	"time"
 )
@@ -456,7 +460,7 @@ func TestScanContentWithinOperand(t *testing.T) {
 	added := sparseFile(t, dir, "d2", headTailMin)
 
 	st := syncTree(t, db, dir)
-	if st != (scanStats{added: 1, unchanged: 2}) {
+	if st != (scanStats{walked: 3, added: 1, unchanged: 2}) {
 		t.Fatalf("rescan stats = %+v, want 1 added 2 unchanged", st)
 	}
 
@@ -502,7 +506,7 @@ func TestScanContentStalePartners(t *testing.T) {
 	sparseFile(t, dirB, "changed-copy", headTailMin+1)
 
 	st := syncTree(t, db, dirB)
-	if st != (scanStats{added: 2}) {
+	if st != (scanStats{walked: 2, added: 2}) {
 		t.Errorf("stats = %+v, want 2 added and nothing skipped", st)
 	}
 
@@ -559,7 +563,7 @@ func TestScanContentHashedStalePartners(t *testing.T) {
 	b := sparseFile(t, t.TempDir(), "copy", headTailMin)
 
 	st := syncTree(t, db, filepath.Dir(b))
-	if st != (scanStats{added: 1}) {
+	if st != (scanStats{walked: 1, added: 1}) {
 		t.Errorf("stats = %+v, want 1 added and nothing skipped", st)
 	}
 
@@ -599,7 +603,7 @@ func TestScanContentReadFailure(t *testing.T) {
 	b := sparseFile(t, dirB, "b", headTailMin)
 
 	st := syncTree(t, db, dirB)
-	if st != (scanStats{added: 1, skipped: 1}) {
+	if st != (scanStats{walked: 1, added: 1, skipped: 1}) {
 		t.Fatalf("stats = %+v, want 1 added 1 skipped", st)
 	}
 
@@ -613,7 +617,7 @@ func TestScanContentReadFailure(t *testing.T) {
 	}
 
 	st = syncTree(t, db, dirB)
-	if st != (scanStats{unchanged: 1}) {
+	if st != (scanStats{walked: 1, unchanged: 1}) {
 		t.Fatalf("rescan stats = %+v, want 1 unchanged", st)
 	}
 
@@ -659,7 +663,7 @@ func TestScanContentCheckError(t *testing.T) {
 	b := sparseFile(t, t.TempDir(), "b", headTailMin)
 
 	st := syncTree(t, db, filepath.Dir(b))
-	if st != (scanStats{added: 1, skipped: 1}) {
+	if st != (scanStats{walked: 1, added: 1, skipped: 1}) {
 		t.Fatalf("stats = %+v, want 1 added 1 skipped", st)
 	}
 
@@ -687,7 +691,7 @@ func TestScanContentHardlinks(t *testing.T) {
 	c := sparseFile(t, dir, "copy", headTailMin)
 
 	st := syncTree(t, db, dir)
-	if st != (scanStats{added: 3}) {
+	if st != (scanStats{walked: 3, added: 3}) {
 		t.Fatalf("stats = %+v, want 3 added", st)
 	}
 
@@ -910,6 +914,159 @@ 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
+// warning 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)
+			}
+
+			if len(evs) != 0 {
+				t.Fatalf("unexpected events: %+v", evs)
+			}
+
+			// 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)
+	}
+}
+
 // buildSmokeTree recreates the README smoke-test filesystem layout
 // with deterministic content and returns the tree root.
 func buildSmokeTree(t *testing.T) string {
@@ -1058,7 +1215,7 @@ func TestScanPipeline(t *testing.T) {
 	db := openTestDB(t)
 
 	st := syncTree(t, db, dir)
-	if st != (scanStats{added: smokeTreeFiles}) {
+	if st != (scanStats{walked: smokeTreeFiles, added: smokeTreeFiles}) {
 		t.Fatalf("stats = %+v, want %d added only", st, smokeTreeFiles)
 	}
 
@@ -1081,7 +1238,7 @@ func TestSyncScanUnchangedReuse(t *testing.T) {
 	writeFile(t, dir, "b.bin", pattern(2, 600))
 
 	st := syncTree(t, db, dir)
-	if st != (scanStats{added: 2}) {
+	if st != (scanStats{walked: 2, added: 2}) {
 		t.Fatalf("first scan stats = %+v, want 2 added", st)
 	}
 
@@ -1095,7 +1252,7 @@ func TestSyncScanUnchangedReuse(t *testing.T) {
 	}
 
 	st = syncTree(t, db, dir)
-	if st != (scanStats{unchanged: 2}) {
+	if st != (scanStats{walked: 2, unchanged: 2}) {
 		t.Fatalf("rescan stats = %+v, want 2 unchanged", st)
 	}
 
@@ -1124,7 +1281,7 @@ func TestSyncScanMtimeBump(t *testing.T) {
 	}
 
 	st := syncTree(t, db, dir)
-	if st != (scanStats{updated: 1}) {
+	if st != (scanStats{walked: 1, updated: 1}) {
 		t.Fatalf("mtime-bump stats = %+v, want 1 updated", st)
 	}
 
@@ -1152,7 +1309,7 @@ func TestSyncScanAddRemove(t *testing.T) {
 	}
 
 	st := syncTree(t, db, dir)
-	if st != (scanStats{added: 1, removed: 1, unchanged: 1}) {
+	if st != (scanStats{walked: 2, added: 1, removed: 1, unchanged: 1}) {
 		t.Fatalf("add/remove stats = %+v, want 1 added 1 removed 1 unchanged",
 			st)
 	}
@@ -1269,7 +1426,7 @@ func TestSyncScanOverlappingRoots(t *testing.T) {
 	// A file reachable via two overlapping operands is deduplicated
 	// by path in the shared walk and processed once.
 	st := syncTree(t, db, dir, filepath.Join(dir, "sub"))
-	if st != (scanStats{added: 1}) {
+	if st != (scanStats{walked: 1, added: 1}) {
 		t.Fatalf("stats = %+v, want 1 added", st)
 	}
 
@@ -1290,7 +1447,7 @@ func TestScanSkipsUniqueSizes(t *testing.T) {
 	// Neither size is shared, so neither file is read: both records
 	// are written without hashes and no duplicates are reported.
 	st := syncTree(t, db, dir)
-	if st != (scanStats{added: 2}) {
+	if st != (scanStats{walked: 2, added: 2}) {
 		t.Fatalf("stats = %+v, want 2 added", st)
 	}
 
@@ -1312,7 +1469,7 @@ func TestScanSkipsUniqueSizes(t *testing.T) {
 	c := writeFile(t, dir, "c.bin", pattern(1, 500))
 
 	st = syncTree(t, db, dir)
-	if st != (scanStats{added: 1, updated: 1, unchanged: 1}) {
+	if st != (scanStats{walked: 3, added: 1, updated: 1, unchanged: 1}) {
 		t.Fatalf("rescan stats = %+v, want 1 added 1 updated 1 unchanged",
 			st)
 	}
@@ -1376,7 +1533,7 @@ func TestScanHardlinksReadOnce(t *testing.T) {
 	}
 
 	st := syncTree(t, db, dir)
-	if st != (scanStats{added: 2}) {
+	if st != (scanStats{walked: 2, added: 2}) {
 		t.Fatalf("stats = %+v, want 2 added", st)
 	}
 
@@ -1498,6 +1655,13 @@ func injectWriteFailure(t *testing.T, path string) {
 func baselineGoroutines(t *testing.T) int {
 	t.Helper()
 
+	// The first scan command in a process starts os/signal's goroutine,
+	// which never exits. Start it now, so the baseline counts it
+	// instead of the scan seeming to leave it behind.
+	ch := make(chan os.Signal, 1)
+	signal.Notify(ch, syscall.SIGINT)
+	signal.Stop(ch)
+
 	deadline := time.Now().Add(goroutineSettle)
 	last := runtime.NumGoroutine()
 

script/bootstrap

@@ -3,10 +3,12 @@
 # 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,
-# make, or go). The linter is NOT installed: golangci-lint runs via
+# make, or go). Neither the linter nor the Markdown formatter is
-# docker only (script/lint), pinned by image digest, so the only lint
+# installed: golangci-lint (script/lint) and prettier (script/fmt,
+# script/fmt-check) run via docker only, pinned by hash, so their only
 # prerequisite is a working docker — which is warned about, not
-# installed, because everything except linting works without it.
+# installed, because everything except linting and formatting works
+# without it.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -71,15 +73,15 @@ main() {
     if missing make; then pkg_install gnumake make make make; fi
     if missing go; then pkg_install go golang go go; fi
 
-    # Linting runs via docker only (script/lint), so docker is a lint
+    # Linting and Markdown formatting run via docker only, so docker is
-    # prerequisite rather than something bootstrap installs. Warn, do
+    # their prerequisite rather than something bootstrap installs. Warn,
-    # not fail: everything except `make lint` — and, through it,
+    # do not fail: everything except `make lint`, `make fmt` and
-    # `make check`, `make docker` and the pre-commit hook — works
+    # `make fmt-check` — and, through them, `make check`, `make docker`
-    # without it.
+    # 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: WARNING: docker not found; make lint, make fmt," >&2
-        echo "bootstrap: and make docker require it. Install docker to" >&2
+        echo "bootstrap: make fmt-check, make check and make docker" >&2
-        echo "bootstrap: run the linter." >&2
+        echo "bootstrap: require it." >&2
     fi
 
     go mod download

script/cibuild

@@ -3,17 +3,17 @@
 # push.
 #
 # The Dockerfile runs the gates individually as build steps, not the
-# make check aggregate: the lint stage runs make fmt-check,
+# make check aggregate: the lint stage runs the gofmt check,
 # script/verify-lint-image-pin, golangci-lint config verify and
-# golangci-lint run; the build stage, dropped to an unprivileged user,
+# golangci-lint run; the markdown stage runs the prettier check; the
-# runs make test and make fmt-check. Neither make lint nor make check
+# build stage, dropped to an unprivileged user, runs make test. None of
-# appears, because both reach script/lint, which is itself a docker
+# make lint, make fmt-check or make check appears, because each runs
-# build, and a docker build cannot run inside one. Lint is not skipped
+# docker, and docker cannot run inside a docker build. Nothing is
-# by that — the linter is invoked directly in the lint stage, and the
+# skipped by that — the linter, gofmt and prettier are invoked directly
-# build stage's COPY --from=lint makes that stage a prerequisite, so
+# in their stages, and the build stage's COPY --from lines make those
-# BuildKit must finish it first. Between the two stages everything
+# stages prerequisites, so BuildKit must finish them first. Between the
-# make check would run has run, which is why a successful build here
+# three stages everything make check would run has run, which is why a
-# implies the repo is green.
+# 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
@@ -21,14 +21,17 @@
 # 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.
+# go mod download cached; see the Dockerfile for the placement. The
+# process id goes in with the epoch so that two runs started in the
+# same second still get different values, the same form script/lint
+# uses.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --build-arg CHECK_EPOCH="$(date +%s)" .
+    docker build --build-arg CHECK_EPOCH="$(date +%s)-$$" .
 }
 
 main "$@"

script/docker

@@ -3,12 +3,12 @@
 # The tag comes from script/projectname.
 #
 # CHECK_EPOCH is passed for the same reason script/cibuild passes it:
-# without it Docker serves the Dockerfile's gate layers from cache on an
+# without a fresh value Docker serves the gate layers from cache on an
-# unchanged tree and this exits 0 having run neither the lint stage's
+# unchanged tree and this exits 0 having run none of the lint stage's
-# gates nor the builder stage's test and fmt-check gates. This is the
+# gates, the markdown stage's prettier gate or the builder stage's test
-# set of gates a developer or reviewer runs by hand, so a cached pass
+# gate. This is the set of gates a developer or reviewer runs by hand,
-# here is the most misleading result the repo can produce. Dependency
+# so a cached pass here is the most misleading result the repo can
-# layers sit above the ARG and stay cached.
+# produce. Dependency layers sit above the ARG and stay cached.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -17,7 +17,7 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 main() {
     cd "$ROOT"
     docker build \
-        --build-arg CHECK_EPOCH="$(date +%s)" \
+        --build-arg CHECK_EPOCH="$(date +%s)-$$" \
         -t "$("$SCRIPT_DIR/projectname")" \
         .
 }

script/fmt

@@ -1,12 +1,22 @@
 #!/bin/sh
-# script/fmt: format all files (writes).
+# script/fmt: format all files (writes): the Go sources with gofmt, the
+# Markdown with prettier. prettier is never installed on the host: it
+# runs from the Dockerfile's prettier stage with the repository mounted,
+# as the calling user so the files it rewrites keep their owner. The tag
+# makes each build replace the previous image instead of leaving another
+# one behind.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
     gofmt -s -w .
+    image="$("$SCRIPT_DIR/projectname")-prettier"
+    docker build -q --target prettier -t "$image" . >/dev/null
+    docker run --rm --user "$(id -u):$(id -g)" -v "$ROOT:/src" "$image" \
+        prettier --write '**/*.md' --tab-width 4 --prose-wrap always
 }
 
 main "$@"

script/fmt-check

@@ -1,18 +1,39 @@
 #!/bin/sh
 # script/fmt-check: check formatting (read-only). Same scope as
-# script/fmt, but fails instead of writing.
+# script/fmt, but fails instead of writing. gofmt and prettier both run
+# every time and each reports its own failure, so the output says which
+# one failed.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    files="$(gofmt -s -l .)"
+    status=0
+
+    # Under set -e a bare assignment would end the script when gofmt
+    # fails (a Go file it cannot parse), and prettier would never run.
+    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
+
+    # Same image as script/fmt; see there.
+    image="$("$SCRIPT_DIR/projectname")-prettier"
+    docker build -q --target prettier -t "$image" . >/dev/null
+    if ! docker run --rm -v "$ROOT:/src:ro" "$image" \
+        prettier --check '**/*.md' --tab-width 4 --prose-wrap always; then
+        echo "prettier: Markdown not formatted; run make fmt" >&2
+        status=1
+    fi
+
+    exit "$status"
 }
 
 main "$@"

script/lint

@@ -14,6 +14,10 @@
 # 0 in well under a second having run no linter. The PID is in the value
 # as well as the epoch because two lint runs land inside the same second
 # easily, and `date +%s` alone would cache the second one.
+#
+# The result is the build's exit status and the image is never used, so
+# --output=type=cacheonly writes none. Without it every run spends
+# seconds exporting an image and leaves it behind untagged.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -22,6 +26,7 @@ main() {
     cd "$ROOT"
     docker build \
         --build-arg CHECK_EPOCH="$(date +%s)-$$" \
+        --output=type=cacheonly \
         -f Dockerfile.lint \
         .
 }

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==