Lint in a container as a build step, via Dockerfile.lint (closes #113)

Every lint run now happens inside its own container, invoked through
script/lint, and linting is a build step rather than a container
command: a successful build of the new root Dockerfile.lint IS a clean
lint. That shape also works where the docker daemon is remote and bind
mounts are impossible.

Its FROM line -- golangci/golangci-lint:v2.12.2, pinned by digest -- is
now the only pin of the linter version in this repo.

A container per run has its own lint cache and its own golangci-lint
lock, both discarded with it, so neither cross-worktree contamination
nor lock contention exists any more. The machinery that defended
against them is therefore gone: the per-worktree cache directories, the
lock-retry loop, and script/lint-audit, which existed to catch findings
replayed from a cache that no longer exists. So is the host lint path
in its entirety -- the native escape hatch, its version detection, and
VAULTIK_LINT_IN_CONTAINER in both script/lint and the Dockerfile.
Nothing lints on the host, at any version.

A cached build lints nothing, so the CHECK_EPOCH mechanism the product
Dockerfile already used is what makes a green mean something:
ARG CHECK_EPOCH with no default, placed below the module layers so
dependency caching survives, a `RUN [ -n "$CHECK_EPOCH" ] || exit 1`
guard so a build that withholds the arg fails instead of replaying, and
the value expanded into the lint command itself. script/lint computes
`epoch="$(date +%s%N)$$"` as a bare assignment on its own line, because
inline in the argument a failing substitution does not abort under
`set -eu` and yields a constant empty epoch -- which is exactly the
false green being prevented.

The product Dockerfile loses its lint stage rather than gaining a
second linter pin. That stage ran `make lint`, which is now
`docker build`: docker-in-docker inside a BuildKit step with no daemon.
Calling golangci-lint directly there instead would have meant two
independently bumpable digests for one tool. `make fmt-check` moves
beside `make test` in the builder stage, and script/cibuild now builds
Dockerfile.lint and then Dockerfile, each with its own fresh epoch,
failing on either. Consequence, stated in comments rather than left to
be discovered: script/docker builds the product image only and no
longer lints; script/check and script/cibuild are the gates.

`golangci-lint config verify` runs as its own epoch-keyed layer, above
the lint. It is not belt-and-braces: `golangci-lint run` rejects a
config it cannot PARSE but silently IGNORES an unknown top-level KEY.
Renaming .golangci.yml's `linters:` to `linterz:` -- one character --
discards `default: all`, the disable list and every threshold, leaves
only the small default linter set running, and exits 0 reporting
`0 issues.` on a tree the real config fails with an lll finding, in a
run whose lint layer demonstrably executed. That is a set-but-
ineffective config falling back to defaults instead of failing loudly,
sitting in the gate's own configuration. `config verify` catches it and
does so with the network genuinely off at this pin: under
`docker run --network none` against the pinned digest it exits 0 on
this repo's config and exits 3 on the `linterz:` variant. It is keyed
on CHECK_EPOCH like the lint itself, because a cached validation
validates nothing.

script/lint-fix is kept, reimplemented as a bind-mounted
docker run against the image parsed out of Dockerfile.lint -- a build
step cannot write fixes back to the worktree -- and its header states
outright that it is a developer convenience, never a gate, and needs a
local daemon.

cmd/vaultik/lintdocker_test.go parses both Dockerfiles and both scripts
and fails if any part of the mechanism is dropped: the digest pin, the
defaultless ARG below `go mod download`, the emptiness guard, the
expansion of the epoch into each check command, the bare per-invocation
epoch assignment in both scripts, cibuild building both files, the
config verification running before the lint, and -- structurally, not
by searching for one retired variable name -- that no script invokes
golangci-lint except through docker. Every one of those losses is
silent: the build still exits 0 and nothing is checked, which is why
they are asserted rather than trusted. The scanner behind the last of
those has its own test, because a structural check that goes blind
passes on every tree, including a broken one.

script/lint takes no arguments now, and says so instead of dropping
them: a build step has no command line to pass linter flags to.

.dockerignore

@@ -3,6 +3,8 @@
 *.md
 LICENSE
 vaultik
+dist
+.tool
 coverage.out
 coverage.html
 .DS_Store

.gitea/workflows/release.yml

@@ -0,0 +1,60 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      # actions/checkout v4, 2024-09-16
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          # goreleaser needs the tags and the full history: the version
+          # it stamps comes from the tag, and the changelog comes from
+          # the commits since the previous one. A shallow checkout
+          # silently produces a mislabelled release.
+          fetch-depth: 0
+      # goreleaser is not a compiler: it shells out to `go` for the
+      # `before:` hook and for every one of the four cross-compiles.
+      # Nothing else in this repo puts a Go toolchain on the runner --
+      # check.yml runs script/cibuild, which does all of its work inside
+      # the digest-pinned Dockerfile images -- so without this step the
+      # release either fails at the before-hook or, worse, ships binaries
+      # built by whatever unpinned Go the runner happens to carry.
+      # REPO_POLICIES.md requires every external reference to be pinned,
+      # and script/release already refuses a goreleaser that is not the
+      # pinned build; the compiler that actually produces the artifacts
+      # is the last thing that should be exempt from that.
+      #
+      # go-version-file rather than a literal: go.mod's `go 1.26.1` is
+      # the single source of truth for the toolchain, the same way the
+      # Dockerfile FROM line is the single source of truth for the
+      # linter version that script/lint enforces. It is a three-component
+      # version, so setup-go resolves it exactly -- no silent drift onto
+      # a newer patch release.
+      #
+      # actions/setup-go v5.6.0, 2025-12-15. Pinned by commit sha, like
+      # the checkout above. v5.x is a node20 action, matching the node20
+      # actions/checkout v4 already in use here; the v6/v7 line requires
+      # a node24 runner, which this Gitea runner has never been asked
+      # for and cannot be assumed to provide.
+      - name: Install Go
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff
+        with:
+          go-version-file: go.mod
+          # setup-go's module cache needs a runner-side cache backend.
+          # A release is cut rarely and a cold module download costs
+          # seconds; a release failing because a cache service is absent
+          # costs a re-tag. Off, deliberately.
+          cache: false
+      - name: Install goreleaser
+        run: script/install-goreleaser
+      - name: Release
+        run: script/release
+        env:
+          # RELEASE_TOKEN is a repository Actions secret: a Gitea access
+          # token with write access to this repository's releases (scope
+          # write:repository), owned by an account that can publish here.
+          # It is deliberately not the runner's automatic token, which is
+          # not guaranteed to carry that scope.
+          GITEA_TOKEN: ${{ secrets.RELEASE_TOKEN }}

.gitignore

@@ -1,6 +1,12 @@
 # Binary
 /vaultik
 
+# goreleaser output
+/dist/
+
+# Locally installed pinned tools (script/install-goreleaser)
+/.tool/
+
 # Test artifacts
 *.out
 *.test

.goreleaser.yaml

@@ -2,6 +2,13 @@ version: 2
 
 project_name: vaultik
 
+# This repo lives on Gitea, not GitHub. Without this block goreleaser
+# talks to the GitHub API by default and a `goreleaser release` either
+# fails outright or publishes somewhere nobody is looking.
+gitea_urls:
+  api: https://git.eeqj.de/api/v1
+  download: https://git.eeqj.de
+
 before:
   hooks:
     - go mod tidy
@@ -37,8 +44,14 @@ checksum:
   name_template: "checksums.txt"
   algorithm: sha256
 
+# A snapshot is not a release and must not name itself like one. The
+# previous `{{ incpatch .Version }}-next` derived a plausible-looking
+# release number from the last tag -- and with no tags in the repo at
+# all, from goreleaser's fabricated v0.0.0. This produces the same
+# string script/version produces for an untagged build, so a snapshot
+# binary and a `make vaultik` binary of the same clean commit agree.
 snapshot:
-  version_template: "{{ incpatch .Version }}-next"
+  version_template: "dev-{{ slice .FullCommit 0 12 }}"
 
 changelog:
   sort: asc

AGENTS.md

@@ -83,8 +83,8 @@ Version: 2025-06-08
    possible to mock or stub these side-effects in tests.
 
 9. Always use structured logging.  Log any relevant state/context with the
-   messages (but do not log secrets).  If stdout is not a terminal, output
-   the structured logs in jsonl format.
+   messages (but do not log secrets).  If the log stream is not a terminal,
+   output the structured logs in jsonl format.
 
 10. Avoid using bare strings or numbers in code, especially if they appear
     anywhere more than once.  Always define a constant (usually at the top

Dockerfile

@@ -1,29 +1,25 @@
-# Lint stage
-# golangci/golangci-lint:v2.12.2-alpine, 2026-08-07
-FROM golangci/golangci-lint:v2.12.2-alpine@sha256:91b27804074a0bacea298707f016911e60cf0cdbc6c7bf5ccacb5f0606d18d60 AS lint
-
-RUN apk add --no-cache make build-base
-
-WORKDIR /src
-
-# Copy go mod files first for better layer caching
-COPY go.mod go.sum ./
-RUN go mod download
-
-# Copy source code
-COPY . .
-
-# Run formatting check and linter
-RUN make fmt-check
-RUN make lint
+# This file has no lint stage, deliberately.
+#
+# Linting lives in Dockerfile.lint, built by script/lint, and
+# script/cibuild builds both. A lint stage here would have to either
+# shell out to `make lint` -- which is now `docker build`, so
+# docker-in-docker inside a BuildKit step with no daemon -- or call
+# golangci-lint directly, which would mean a second, independently
+# bumpable digest pin for the linter alongside the one in
+# Dockerfile.lint. Two pins for one tool is the drift that
+# https://git.eeqj.de/sneak/vaultik/issues/78 was filed over. See
+# https://git.eeqj.de/sneak/vaultik/issues/113 for the ruling.
+#
+# Consequence, stated rather than left to be discovered: script/docker
+# builds this file only and therefore does not lint. `make fmt-check`
+# and `make test` still run here, so what a green build of this file
+# means is "formatted, tested, and it compiles" -- the lint verdict
+# comes from script/lint or script/cibuild.
 
 # Build stage
 # golang:1.26.1-alpine, 2026-03-17
 FROM golang:1.26.1-alpine@sha256:2389ebfa5b7f43eeafbd6be0c3700cc46690ef842ad962f6c5bd6be49ed82039 AS builder
 
-# Depend on lint stage passing
-COPY --from=lint /src/go.sum /dev/null
-
 ARG VERSION=dev
 
 # Install build dependencies for CGO (mattn/go-sqlite3) and sqlite3 CLI (tests)
@@ -38,8 +34,35 @@ RUN go mod download
 # Copy source code
 COPY . .
 
-# Run tests
-RUN make test
+# Run the format check and the tests.
+#
+# CHECK_EPOCH must stay immediately above these RUNs. These layers are
+# keyed on its value, so they are cache-eligible only for a value
+# already built against this same tree. script/cibuild and script/docker
+# each pass a fresh value on every invocation, which is what makes their
+# green mean the checks really executed.
+#
+# The value is expanded into each check command rather than left to a
+# bare declaration, so the cache miss does not depend on BuildKit's
+# unreferenced-ARG handling staying as it is. It also puts the epoch in
+# the build log, where a reader can see the layer was keyed fresh.
+#
+# The guard is what makes a build that omits --build-arg fail instead of
+# lie. An unset ARG is an empty string, and an empty string is a
+# perfectly stable cache key: without the guard the first such build
+# runs the checks and every one after it on an unchanged tree replays
+# these layers from cache, executes nothing, and still exits 0. Failed
+# steps are never cached, so the guard fails on EVERY invocation rather
+# than once -- a bare `docker build .` is a loud error, not a quiet
+# green. Do not give CHECK_EPOCH a default value; a default would
+# satisfy the guard with a constant and restore the hole.
+#
+# Everything above this line (apk, go.mod, `go mod download`) is
+# deliberately outside the busted range and keeps caching.
+ARG CHECK_EPOCH
+RUN [ -n "$CHECK_EPOCH" ] || exit 1
+RUN echo "check epoch: ${CHECK_EPOCH}" && make fmt-check
+RUN echo "check epoch: ${CHECK_EPOCH}" && make test
 
 # Build (pure Go, no CGO required since we use modernc.org/sqlite)
 RUN CGO_ENABLED=0 go build -ldflags "-X 'sneak.berlin/go/vaultik/internal/globals.Version=${VERSION}' -X 'sneak.berlin/go/vaultik/internal/globals.Commit=$(git rev-parse HEAD 2>/dev/null || echo unknown)' -X 'sneak.berlin/go/vaultik/internal/globals.CommitDate=$(git show -s --format=%cs HEAD 2>/dev/null || echo unknown)'" -o /vaultik ./cmd/vaultik

Dockerfile.lint

@@ -0,0 +1,104 @@
+# Lint image.
+#
+# Every lint run in this repo happens inside this image, invoked through
+# script/lint, and linting is a BUILD STEP rather than a container
+# command: a successful build of this file IS a clean lint. That shape
+# also works where the docker daemon is remote and bind mounts are
+# impossible, which `docker run` against a mounted worktree does not.
+#
+# This FROM line is the single source of truth for the linter version in
+# this repo. Nothing else pins golangci-lint: the product Dockerfile has
+# no lint stage, deliberately, so there is no second digest to bump and
+# no pair of pins that can drift apart. Bump the tag AND the digest here
+# and nowhere else.
+#
+# Note for readers coming from REPO_POLICIES.md: that document still
+# describes the older pattern, a lint stage inside the product
+# Dockerfile wired up with `COPY --from=lint /src/go.sum /dev/null`.
+# That pattern is superseded here by the owner's ruling recorded in
+# https://git.eeqj.de/sneak/vaultik/issues/113 -- lint runs in its own
+# image, per run, with its own cache and its own lock, which is what
+# makes concurrent runs on one host safe. The policy text is org-wide
+# and is being amended separately; this file is what this repo does.
+#
+# golangci/golangci-lint:v2.12.2, 2026-08-10
+FROM golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240
+
+WORKDIR /src
+
+# Copy the dependency manifests first so the module download layer stays
+# cached until they change. Everything above the ARG below is cacheable
+# on purpose; a cold module download on every lint would make the inner
+# loop unusable and buys nothing, because it is not what the gate is
+# asserting.
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+# Force the check layers to execute on every invocation.
+#
+# CHECK_EPOCH must stay immediately above the RUNs below. Those layers
+# are keyed on its value, so they are cache-eligible only for a value
+# already built against this same tree; script/lint and script/cibuild
+# each pass a fresh value on every invocation, which is what makes their
+# green mean the linter really ran. Without it, `docker build -f
+# Dockerfile.lint .` on an unchanged tree exits 0 in well under a second
+# having linted nothing.
+#
+# The value is expanded into each check command itself rather than left
+# to a bare declaration, so the cache miss does not depend on BuildKit's
+# unreferenced-ARG handling staying as it is. It also puts the epoch in
+# the build log, where a reader can see the layer was keyed fresh.
+#
+# The guard is what makes a build that omits --build-arg fail instead of
+# lie. An unset ARG is an empty string, and an empty string is a
+# perfectly stable cache key: without the guard the first such build
+# lints and every one after it on an unchanged tree replays this layer,
+# executes nothing, and still exits 0. Failed steps are never cached, so
+# the guard fails on EVERY invocation rather than once. Do not give
+# CHECK_EPOCH a default value; a default would satisfy the guard with a
+# constant and restore the hole.
+ARG CHECK_EPOCH
+RUN [ -n "$CHECK_EPOCH" ] || exit 1
+
+# Validate .golangci.yml before linting with it.
+#
+# This is not belt-and-braces; it closes a hole that `golangci-lint run`
+# leaves wide open. `run` rejects YAML it cannot PARSE, but it silently
+# IGNORES an unknown top-level KEY. Renaming `linters:` to `linterz:` --
+# one character -- discards `default: all`, the whole disable list and
+# every threshold, leaves only golangci-lint's small default linter set
+# running, and exits 0 reporting `0 issues.` on a tree the real config
+# fails. Demonstrated on this repo at this pin, recorded on
+# https://git.eeqj.de/sneak/vaultik/pulls/114: with a planted
+# over-length line, `script/lint` exits 1 naming the `lll` finding with
+# `linters:` and exits 0 with `linterz:`. A set-but-ineffective config
+# quietly falling back to defaults is precisely the false-green class
+# this gate exists to eliminate, so it must not sit in the gate's own
+# configuration.
+#
+# `config verify` catches it, and it does so OFFLINE at this pinned
+# version -- verified, not assumed. Under `docker run --network none`
+# against the pinned digest it exits 0 on this repo's config and exits 3
+# on the `linterz:` variant with `additional properties 'linterz' not
+# allowed`. An earlier revision of this file asserted the opposite, that
+# the schema is fetched over live HTTPS from an unpinned URL, and used
+# that to justify omitting this line. That claim was false at v2.12.2;
+# the schema is embedded. If a future bump reintroduces a network fetch
+# the failure is loud and this comment is where to record it.
+#
+# It is keyed on CHECK_EPOCH, like the lint run below, so it executes on
+# every invocation. Content-addressing alone would arguably be enough --
+# .golangci.yml arrives through `COPY . .`, so a cache hit here implies
+# a byte-identical config was validated when the layer really ran. That
+# argument is exactly the one that would also excuse caching the lint
+# layer, and this repo has ruled it insufficient: a cached check layer
+# checks nothing, and the cost of being wrong is silent. Forcing it costs
+# milliseconds and puts the epoch in the log, where a reader can see that
+# this validation ran rather than being replayed.
+RUN echo "check epoch: ${CHECK_EPOCH}" && \
+    golangci-lint config verify --config .golangci.yml
+
+RUN echo "check epoch: ${CHECK_EPOCH}" && \
+    golangci-lint run --config .golangci.yml ./...

Makefile

@@ -1,7 +1,20 @@
-.PHONY: all bootstrap setup check test lint lint-fix fmt fmt-check build clean deps test-coverage test-integration local install release release-snapshot docker hooks
+.PHONY: all bootstrap setup check test lint lint-fix fmt fmt-check build clean deps test-coverage local install release release-snapshot docker hooks
 
-# Version number
-VERSION := 1.0.0-rc.1
+# Version number, derived from git by script/version -- the tag when
+# HEAD is on one, otherwise dev-<sha>. This used to be a hardcoded
+# constant, which meant every local build claimed to be a release that
+# had never been tagged.
+VERSION := $(shell script/version)
+
+# $(shell) discards exit status, so a script/version that is missing,
+# non-executable or broken would otherwise leave VERSION empty and every
+# binary built here would print "vaultik " with no version at all. A
+# build that cannot determine what it is must not produce an artifact.
+ifeq ($(strip $(VERSION)),)
+$(error script/version produced no version string; a build that cannot \
+determine its version will not be made. Check that script/version exists \
+and is executable)
+endif
 
 # Build variables
 GIT_REVISION := $(shell git rev-parse HEAD 2>/dev/null || echo "unknown")
@@ -27,7 +40,13 @@ setup:
 check:
 	@script/check
 
-# Run tests only.
+# Run tests only. This runs the ENTIRE suite -- there is no separate
+# integration target and no build-tagged subset held back. In
+# particular internal/vaultik/integration_test.go, which does full
+# chunk -> pack -> encrypt -> upload -> restore round-trips, runs here.
+# A `test-integration` target used to exist and was removed: no file in
+# the repo carried a build tag, so `-tags=integration` selected nothing
+# extra and the target was an exact duplicate of this one.
 test:
 	@script/test
 
@@ -47,7 +66,18 @@ lint:
 lint-fix:
 	@script/lint-fix
 
-# Build binary.
+# Build binary. `build` is the name the org convention reaches for and
+# the one a caller checks the exit code of; `vaultik` is the file rule
+# that does the work, so an unchanged tree still short-circuits.
+#
+# This alias is not decorative. `build` was listed in .PHONY with no
+# rule, and a phony target with no prerequisites and no recipe is
+# already satisfied: `make build` printed "Nothing to be done" and
+# exited 0 without producing a binary (issue #110). Every name in
+# .PHONY needs a rule for that reason; TestPhonyTargetsAllHaveRules in
+# cmd/vaultik keeps it that way.
+build: vaultik
+
 vaultik: internal/*/*.go cmd/vaultik/*.go
 	go build -ldflags "$(LDFLAGS)" -o $@ ./cmd/vaultik
 
@@ -56,20 +86,22 @@ clean:
 	rm -f vaultik
 	go clean
 
-# Install dependencies.
+# Install dependencies. The linter is deliberately not installed here:
+# script/lint lints by building Dockerfile.lint, whose FROM line is the
+# single source of truth for the linter version. A second, separately
+# pinned copy on PATH could drift from it and make a local `make lint`
+# disagree with CI.
 deps:
 	go mod download
-	go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2
 
-# Run tests with coverage.
+# Run tests with coverage. -count=1 for the same reason script/test
+# uses it: without it an unchanged package is served from Go's test
+# result cache, and a coverage profile assembled from cached results
+# describes a run that did not happen.
 test-coverage:
-	go test -v -coverprofile=coverage.out ./...
+	go test -v -count=1 -coverprofile=coverage.out ./...
 	go tool cover -html=coverage.out -o coverage.html
 
-# Run integration tests.
-test-integration:
-	go test -v -tags=integration ./...
-
 local:
 	VAULTIK_CONFIG=$(HOME)/etc/vaultik/config.yml ./vaultik snapshot --debug list 2>&1
 	VAULTIK_CONFIG=$(HOME)/etc/vaultik/config.yml ./vaultik snapshot --debug create 2>&1
@@ -79,11 +111,11 @@ install: vaultik
 
 # Build and publish release artifacts (linux/darwin × amd64/arm64) via goreleaser.
 release:
-	goreleaser release --clean
+	@script/release
 
 # Dry-run a release build without publishing or tagging.
 release-snapshot:
-	goreleaser release --clean --snapshot
+	@script/release-snapshot
 
 # Build Docker image.
 docker:

README.md

@@ -113,11 +113,40 @@ vaultik version
 ### global flags
 
 * `--config <path>`: Path to config file (default: `$VAULTIK_CONFIG`, then platform config dir, then `/etc/vaultik/config.yml`)
-* `--verbose`, `-v`: Enable verbose output
-* `--debug`: Enable debug output
+* `--verbose`, `-v`: Enable verbose output (on stderr — see below)
+* `--debug`: Enable debug output (on stderr — see below)
 * `--quiet`, `-q`: Suppress non-error output (also suppresses startup banner)
 * `--skip-errors`: Continue past per-file errors instead of aborting (applies to `snapshot create` and `restore`)
 
+### stdout and stderr
+
+Log output — everything from `--verbose` and `--debug`, and every
+warning and error the logger emits — goes to **stderr**. stdout carries
+the output you asked for: tables, and the documents produced by `--json`.
+
+This means `vaultik snapshot list --verbose > out.txt` captures the
+listing and leaves the diagnostics on your terminal. To capture both,
+redirect stderr as well (`> out.txt 2> log.txt`, or `> out.txt 2>&1` to
+interleave them).
+
+The split is what makes `--json` usable from a script. Warnings and
+errors are never suppressed — not by `--quiet`, not by `--cron` — so a
+logger on stdout would eventually land a log line inside a JSON
+document and break the parse. A config file with group- or
+world-readable permissions is enough to trigger it.
+
+Format follows the stream: when stderr is a terminal the records are
+colorized one-liners, and when it is redirected or piped they are
+JSON, one object per line.
+
+Under `--json`, stdout holds the document and nothing else. The startup
+banner is suppressed, as `--quiet` and `--cron` suppress it, and the
+progress narration a command would otherwise print — such as the stale
+local records `prune` reconciles away — is suppressed too, so it cannot
+land ahead of the document. Every `--json` command therefore pipes on
+its own, with no additional flag: `vaultik snapshot list --json | jq .`
+and `vaultik prune --json | jq .` both work as written.
+
 ### environment variables
 
 * `VAULTIK_AGE_SECRET_KEY`: Age private key for decryption (required for `snapshot restore` and `snapshot verify --deep`)
@@ -168,19 +197,49 @@ needed.
   (System Settings → Privacy & Security → Full Disk Access) to read
   TCC-protected directories; without it the backup aborts with a permission
   error that explains how to fix it
-* `--cron`: Silent unless error (for crontab)
+* `--cron`: Silent on total success; warnings and errors are still printed
+  (for crontab)
 * `--prune`: After backup, drop older snapshots of each backed-up name and
   remove orphaned blobs from remote storage. By default keeps only the latest
   snapshot per name; use `--keep-newer-than` for a rolling window.
 * `--keep-newer-than <duration>`: With `--prune`, keep snapshots newer than
   this duration instead of only the latest (e.g. `4w`, `30d`, `6mo`, `1y`)
 
-**`snapshot list`**: Show every snapshot known to the destination
-store with timestamps and three sizes per snapshot (compressed
-remote size; total uncompressed chunk size; size of chunks newly
-referenced by that snapshot). The uncompressed and "new chunk"
-columns show `<remote only>` for snapshots not in the local index.
-* `--json`: Output in JSON format
+**`snapshot list`**: Show every snapshot known to this host — the union
+of the local index and the backup destination store — with timestamps
+and three sizes per snapshot (compressed remote size; total
+uncompressed chunk size; size of chunks newly referenced by that
+snapshot).
+
+Listing the destination store does **not** require the age secret key,
+so it works in vaultik's intended configuration, where the backed-up
+host holds only the public key. A host that has lost its local index
+can still see what it has backed up.
+
+What that host cannot see is a remote-only snapshot's name. The
+snapshot ID is hashed at the storage boundary and the manifest records
+only the hash, so hostname and snapshot name exist solely in the local
+index and in the encrypted per-snapshot database. Snapshots found only
+on the destination store are therefore listed as
+`<remote only:<abbreviated remote key>>` and show `<remote only>` in
+the uncompressed and "new chunk" columns, which can only be computed
+from the local index. Their timestamp and compressed size are real,
+read from the manifest.
+
+Snapshots in the local index with no counterpart on the destination
+store are reported below the table as drift, with the `vaultik prune`
+invocation that reconciles them.
+
+If the destination store cannot be listed (unmounted volume,
+permission denied, network down), the command warns, falls back to the
+local index alone, and still exits zero.
+* `--json`: Output in JSON format. Each entry carries `locally_tracked`
+  (whether the snapshot is in the local index), `remote_key` (the full
+  64-character storage key), and `remote_present` (whether it was seen
+  on the destination store, or `null` if the destination could not be
+  listed). Warnings about an unlistable destination, unreadable
+  manifests, and a truncated listing all go to stderr through the
+  logger, so stdout stays a single parseable document.
 
 **`snapshot verify`**: Verify snapshot integrity.
 * Default (shallow): checks that all blobs referenced in the manifest exist in storage
@@ -475,6 +534,10 @@ All user-facing output goes through helpers in `internal/ui` and conforms
 to a uniform style. Color is enabled when stdout is a TTY and the
 `NO_COLOR` environment variable is unset (https://no-color.org/).
 
+`internal/ui` writes to stdout; it is the output the user asked for.
+Structured log records are a different thing and go through
+`internal/log`, which writes to stderr (see "stdout and stderr" above).
+
 Message classes:
 
 | Class | Marker | Alignment | Use for |
@@ -534,6 +597,13 @@ regardless of color setting (emoji are not color).
 ## requirements
 
 * Go 1.26 or later
+* Docker, with a reachable daemon, to lint, check, or commit:
+  `script/lint` lints by building `Dockerfile.lint`, which runs the
+  digest-pinned `golangci-lint` image as a build step, and `make check`
+  and the pre-commit hook both run it. A `golangci-lint` installed on
+  `PATH` is not a substitute and is never used on a host, whatever its
+  version.
+* `sqlite3` CLI, which the test suite shells out to
 * S3-compatible object storage (or local filesystem, or rclone remote)
 
 ## development workflow
@@ -564,28 +634,184 @@ standard: normalized scripts in `script/` are the entrypoints for the
 development workflow, and the Makefile targets are thin shims that call
 them. We provide:
 
-* `script/bootstrap` — install all development dependencies (go,
-  golangci-lint, Go module download)
+* `script/bootstrap` — install all development dependencies (go, sqlite3,
+  Go module download). It deliberately does not install `golangci-lint`;
+  see `script/lint` below.
 * `script/setup` — make a fresh clone ready for development: runs
   `script/bootstrap`, then `script/install-precommit`
 * `script/projectname` — print the project name (used for the Docker
   image tag)
-* `script/test` — run the test suite (verbose rerun on failure)
-* `script/lint` — run `golangci-lint run ./...`
-* `script/lint-fix` — apply the linter's autofixes (rewrites files)
+* `script/version` — print the version string to bake into the binary.
+  The `Makefile`'s `LDFLAGS` call this; it is the single source of truth
+  for the version. See [releasing](#releasing) for the rules.
+* `script/install-goreleaser` — install the pinned `goreleaser` into
+  `.tool/bin` from a sha256-verified release archive. Idempotent, and
+  called by `script/bootstrap`; the release workflow calls it directly
+  because it needs `goreleaser` but not the Docker daemon
+  `script/bootstrap` insists on.
+* `script/release` — cross-compile and publish the release artifacts
+  with the pinned `goreleaser`. Refuses a `goreleaser` on `PATH` whose
+  version is not the pinned one, on the same reasoning as `script/lint`.
+* `script/release-snapshot` — the same build with no publishing and no
+  tagging, into `./dist`
+* `script/test` — run the test suite (verbose rerun on failure). This
+  runs *everything*: there is no separate integration target and no
+  build-tagged subset held back, so the full round-trip tests in
+  `internal/vaultik/integration_test.go` run on every invocation. It
+  passes `-count=1`, which disables Go's test result cache. That is
+  deliberate and it is not free: on this repo's suite it costs about 11
+  seconds on every repeat run (measured, back to back: 0.4s cached
+  versus 11.6s with `-count=1`). That is the price of the run meaning
+  anything, because without it an unchanged package prints
+  `ok <pkg> (cached)`, which is indistinguishable from a package that
+  really ran, so the whole suite can report a full set of `ok` lines in
+  under half a second having executed nothing. The `-timeout` is a hang
+  backstop rather than a performance budget — it applies per test binary
+  to test execution only, not to compilation — and is set well above the
+  slowest package's measured runtime. Its 120s value deliberately
+  diverges from the 30s `REPO_POLICIES.md` mandates; the reasoning is in
+  the comment in the script, and issue #101 proposes amending the policy
+  text.
+* `script/lint` — lint by building `Dockerfile.lint`, which runs
+  `golangci-lint run --config .golangci.yml ./...` as a build step
+  inside the digest-pinned `golangci-lint` image, so a successful build
+  *is* a clean lint. Nothing lints on the host, at any version, ever;
+  the script requires Docker and fails loudly rather than falling back
+  to a `golangci-lint` on `PATH`. That `FROM` line is the single source
+  of truth for the linter version — bump it there and nowhere else.
+
+  It takes no arguments, because a build step has no command line to
+  pass flags to, and it passes a fresh `--build-arg CHECK_EPOCH` on
+  every invocation so the lint layer cannot be replayed from cache (see
+  `script/cibuild` below for what that mechanism defends against). To
+  watch the linter execute, run it as
+  `BUILDKIT_PROGRESS=plain script/lint` and check that the lint layer
+  says `RUN … golangci-lint` rather than `CACHED`.
+
+  One container per run means one lint cache and one `golangci-lint`
+  lock per run, both private to it and discarded with it, so concurrent
+  runs on one host cannot contaminate or block each other.
+* `script/lint-fix` — apply the linter's autofixes (rewrites files),
+  using the same pinned image, parsed out of `Dockerfile.lint`. It
+  cannot be a build step, because fixes have to land in the worktree, so
+  it bind-mounts the tree into a `docker run` and therefore needs a
+  *local* daemon. It is a developer convenience and never a gate: no
+  gate reads its exit status. Run `make lint` afterwards to find out
+  whether the tree is clean.
 * `script/fmt` — format all code (writes)
 * `script/fmt-check` — check formatting (read-only)
 * `script/check` — run `script/test`, `script/lint`, and
-  `script/fmt-check`
+  `script/fmt-check`. This is authoritative *because* `script/lint`
+  builds `Dockerfile.lint`: a local `make check` and CI cannot disagree
+  about lint findings.
 * `script/docker` — build the Docker image tagged via
-  `script/projectname`
-* `script/cibuild` — CI entrypoint: `docker build .` (the Dockerfile
-  runs the checks)
+  `script/projectname`. Passes a fresh `--build-arg CHECK_EPOCH` for the
+  same reason `script/cibuild` does, so a local image build cannot be
+  green on checks it replayed from cache. It builds the *product* image
+  only, and the product `Dockerfile` has no lint stage, so it does not
+  lint: a green here means formatted, tested, and it compiles.
+* `script/cibuild` — CI entrypoint, and the full gate. Two builds, in
+  order: `Dockerfile.lint` (the linter, as a build step) and then
+  `Dockerfile` (`make fmt-check` and `make test` in its builder stage,
+  then the product image). Either failing fails the script. It runs the
+  checks in the same containers CI does, from a clean copy of the tree,
+  so it also catches anything that depends on host state.
+
+  It passes a fresh `--build-arg CHECK_EPOCH` to each build, unique per
+  invocation, which both files declare immediately above their check
+  `RUN`s and expand into each check command. Those layers are keyed on
+  that value, so a new value re-runs them even on a byte-identical tree,
+  and a green from this script means the checks executed. Dependency and
+  module layers sit above the `ARG` and still cache, so a build is not
+  cold.
+
+  A build that supplies no `CHECK_EPOCH` — a bare `docker build .` or
+  `docker build -f Dockerfile.lint .` — fails rather than lying. An
+  unset `ARG` is an empty string and an empty string is a stable cache
+  key, so without a guard such a build would serve every check layer
+  from cache, execute nothing, and still exit 0. Each file therefore
+  asserts the value is non-empty before running anything, and because
+  failed steps are never cached that assertion fires on every
+  invocation rather than once. Use `script/lint`, `script/docker` or
+  `script/cibuild`, which pass the arg; a bare `docker build` is a loud
+  error.
 * `script/precommit` — pre-commit gate: `go mod tidy` + `go fmt` (must
   not change files), then `script/check`
 * `script/install-precommit` — install the git pre-commit hook that
   runs `script/precommit`
 
+## releasing
+
+### version numbers
+
+The version a binary reports comes from git, not from a constant in a
+file. `script/version` decides it, and everything that stamps a binary
+agrees with it:
+
+* `HEAD` is exactly on a tag → that tag with a leading `v` stripped, so
+  the tag `v1.0.0` produces `vaultik 1.0.0`, matching the archive name
+  `vaultik_1.0.0_linux_amd64.tar.gz`. `goreleaser` strips the prefix the
+  same way.
+* anything else → `dev-<12 chars of the commit sha>`.
+* either, with uncommitted changes to tracked files → a `-dirty`
+  suffix, because a modified checkout of a tag is not that tag.
+
+A build that is not a release never names itself like one. `vaultik
+version` says so in as many words on a development build, and
+`goreleaser --snapshot` stamps the same `dev-<sha>` string rather than
+inventing the next patch number. If `script/version` cannot be run at
+all, `make` stops with an error instead of building an unversioned
+binary, and a binary that somehow carries an empty version string still
+reports itself as a development build.
+
+### cutting a release
+
+Releases are cut by CI from a tag, not from a workstation:
+
+```
+git tag -a v1.2.3 -m 'v1.2.3'
+git push origin v1.2.3
+```
+
+`.gitea/workflows/release.yml` triggers on `v*` tags, installs a Go
+toolchain and the pinned `goreleaser`, and runs `script/release`, which
+builds
+`linux,darwin × amd64,arm64` archives plus `checksums.txt` and publishes
+them to this repository's Gitea releases as a draft. `.goreleaser.yaml`
+has a `gitea_urls:` block pointing at `https://git.eeqj.de/api/v1`;
+without it `goreleaser` would talk to the GitHub API.
+
+The workflow needs one repository Actions secret:
+
+| Secret          | What it is                                                                                              |
+| --------------- | ------------------------------------------------------------------------------------------------------- |
+| `RELEASE_TOKEN` | A Gitea access token with `write:repository` scope, owned by an account that can publish releases here. |
+
+It is passed to `goreleaser` as `GITEA_TOKEN`. The runner's automatic
+token is deliberately not used: it is not guaranteed to carry release
+write access.
+
+The Go toolchain that compiles the released binaries comes from an
+`actions/setup-go` step pinned by commit sha, reading its version from
+`go.mod` (currently `1.26.1`, the same version the `Dockerfile` builder
+stage pins by digest). `goreleaser` shells out to `go` for every
+cross-compile, so without that step the release would either fail
+outright or ship binaries built by whatever unpinned toolchain the
+runner happened to carry — the one unpinned thing in an otherwise
+hash-pinned release path.
+
+To rehearse the whole build without publishing or tagging anything:
+
+```
+make release-snapshot
+```
+
+Artifacts land in `./dist`, which is gitignored.
+
+Release artifacts are not signed, carry no SBOM, and are not built
+reproducibly; the archives contain the binary, `LICENSE`, and
+`README.md` only (no shell completions or man page).
+
 ## license
 
 [MIT](https://opensource.org/license/mit/)

TODO.md

@@ -14,11 +14,488 @@ pre-1.0
 
 # Next Step
 
-Triage the stale remote branches (issue #71): for each, merge the work
-or delete the branch.
+Define the remaining scope for the first tagged release under the 1.0.0
+milestone, then cut that tag. The mechanism to cut it now exists and is
+exercised; what is left is the scope decision, which is the owner's.
+This step deliberately names one version number: it previously said
+"cut v0.1.0" while the `Makefile` baked in `1.0.0-rc.1` and the issue
+milestone said 1.0.0, and three different answers to "what is the next
+release" is exactly the contradiction
+[issue #65](https://git.eeqj.de/sneak/vaultik/issues/65) was filed over.
 
 # Completed Steps
 
+- 2026-08-10: Moved every lint run into its own container, as a build
+  step ([issue #113](https://git.eeqj.de/sneak/vaultik/issues/113)).
+  New root `Dockerfile.lint`, built by `script/lint`, runs
+  `golangci-lint run --config .golangci.yml ./...` as a `RUN`
+  instruction in the digest-pinned `golangci/golangci-lint` image: a
+  successful build of that file *is* a clean lint, and it works even
+  where the daemon is remote and bind mounts are impossible. That
+  `FROM` line is now the only pin of the linter version in the repo.
+
+  This supersedes the per-worktree cache isolation landed for
+  [issue #99](https://git.eeqj.de/sneak/vaultik/issues/99). Isolation
+  fixed cross-worktree contamination but not lock contention — two
+  concurrent runs with entirely separate cache directories still
+  collided. A container per run has its own cache and its own lock, so
+  the whole class is gone, and with it the per-worktree cache
+  machinery, the lock-retry loop, and `script/lint-audit`, which
+  existed to catch replayed findings from a cache that no longer
+  exists. The host lint path went too: no escape hatch, no
+  `VAULTIK_LINT_IN_CONTAINER`, no version detection. Nothing lints on
+  the host at any version.
+
+  A cached build lints nothing, so the same `CHECK_EPOCH` mechanism the
+  product `Dockerfile` already used is what makes the green mean
+  something: `ARG CHECK_EPOCH` with no default below the module layers,
+  a `RUN [ -n "$CHECK_EPOCH" ] || exit 1` guard, the value expanded
+  into each check command, and a fresh `$(date +%s%N)$$` per invocation
+  computed as a bare assignment. `cmd/vaultik/lintdocker_test.go`
+  parses both Dockerfiles and both scripts and fails if any part of
+  that is dropped, because every way of losing it is silent. Its
+  host-lint assertion is structural — no script runs `golangci-lint`
+  except through `docker` — rather than a search for the one retired
+  variable name, which nothing could ever reintroduce.
+
+  The product `Dockerfile` lost its lint stage rather than gaining a
+  second linter pin: `make lint` is now `docker build`, so the stage
+  would have been docker-in-docker with no daemon, and calling
+  `golangci-lint` directly there would have restored the two-pins drift
+  of [issue #78](https://git.eeqj.de/sneak/vaultik/issues/78).
+  `make fmt-check` moved beside `make test` in the builder stage, and
+  `script/cibuild` now builds `Dockerfile.lint` and then `Dockerfile`,
+  each with its own fresh epoch. Consequence, stated rather than left
+  to be found: `script/docker` builds the product image only and no
+  longer lints; the gates are `script/check` and `script/cibuild`.
+
+  `golangci-lint config verify` runs as its own epoch-keyed layer,
+  above the lint. `golangci-lint run` rejects a config it cannot parse
+  but silently ignores an unknown top-level *key*: renaming `linters:`
+  to `linterz:` discarded `default: all` and every threshold and still
+  exited 0 on a tree the real config fails. `config verify` catches
+  that, and it does so with the network off at this pin — checked under
+  `docker run --network none`, not assumed. An earlier revision omitted
+  it on the claim that it fetches its schema over live HTTPS; that
+  claim was false at v2.12.2.
+
+  `script/lint-fix` is kept, reimplemented as a
+  bind-mounted `docker run` against the image parsed out of
+  `Dockerfile.lint` — it cannot be a build step, because fixes have to
+  land in the worktree — and marked in its header as a developer
+  convenience that no gate reads.
+
+- 2026-08-09: Finished the `--json` stdout contract and gave `make build`
+  a rule ([issue #108](https://git.eeqj.de/sneak/vaultik/issues/108),
+  [issue #110](https://git.eeqj.de/sneak/vaultik/issues/110)). Two
+  unrelated defects of the same shape — a command reporting something it
+  did not do — landed together because both are small.
+
+  `CleanupLocalSnapshots` wrote three prose lines to stdout with no
+  `--json` awareness, covering every branch of the function, so no input
+  avoided them and `vaultik prune --json | jq` failed even after
+  [issue #106](https://git.eeqj.de/sneak/vaultik/issues/106) removed the
+  banner. `-q` never helped either: `printlnStdout` and `stdoutf` write
+  straight to `Vaultik.Stdout` and never consult `Vaultik.UI`, which is
+  what `SetQuiet` affects. The issue offered three fixes and asked for a
+  decision. Taken: thread `*PruneOptions` into the function and gate each
+  write on `!opts.JSON`, matching `PruneBlobs` (its sibling phase, which
+  already takes the same struct), `RemoveSnapshot` and `remote info`, so
+  the package has one pattern rather than two. Rejected: moving the lines
+  to `log.Info`, because the logger's default level is `slog.LevelWarn`,
+  so that would not relocate them to stderr — it would delete them from a
+  plain `vaultik prune`, and the removal of rows from the local index is
+  not something to narrate only under `--verbose`. Also rejected: putting
+  the stale-record count into `PruneBlobsResult`, whose every field is
+  blob-scoped and which is produced by the later phase; a prune document
+  covering both phases is a reasonable thing to want, but it is a schema
+  design question and not a stream-hygiene fix. The narration is
+  duplicated as `log.Info` records, which `PruneBlobs` already does
+  alongside its own prints, so the events survive on stderr for anyone
+  running `--verbose`.
+
+  `make build` printed "Nothing to be done for 'build'" and exited 0
+  without producing a binary: `build` was listed in `.PHONY` with no
+  `build:` rule anywhere, and declaring a name phony is exactly what
+  converts make's "No rule to make target" error into a silent success.
+  Fixed with `build: vaultik`, keeping `vaultik:` as the file rule. The
+  audit the issue asked for covers all 19 `.PHONY` names; `build` was the
+  only one without a rule, and `vaultik` is correctly absent from
+  `.PHONY`, being a real file target.
+
+  Tests, each verified to fail with the fix reverted rather than assumed
+  to: `CleanupLocalSnapshots` leaves stdout untouched under `--json` in
+  all three branches (stale records, none, empty index) and still emits
+  every line without it, so the guard cannot be satisfied by deleting the
+  output; `prune --json` run end to end through `Entry`, cobra and fx
+  over the process's real stdout descriptor against a `file://` store,
+  asserting exactly one JSON document, in both the stale and non-stale
+  branches; and a parse of the `Makefile` asserting every `.PHONY` name
+  has a rule and that `build` reaches the rule that produces the binary,
+  which keeps the audit true for names added later. That last one is a
+  parse rather than an invocation of `make`, since `make test` is what
+  runs it and shelling back into `make build` would nest a build inside
+  the test run. The property a parse cannot establish — that the recipe
+  still fails when the build fails — was verified by hand against a
+  deliberately broken tree: `make build` exits 2 and produces nothing.
+  `cmd/vaultik` gains its first test file, so `make test` now reports 16
+  packages `ok` where it reported 15.
+
+- 2026-08-09: Stopped the startup banner from contaminating `--json`
+  documents ([issue #106](https://git.eeqj.de/sneak/vaultik/issues/106)).
+  `Entry` writes the banner to stdout before cobra parses anything, and
+  the flag scan that suppresses it knew `--quiet`, `-q` and `--cron` but
+  not `--json`, so every `--json` document arrived behind two lines of
+  prose and a blank line, and `vaultik snapshot list --json | jq` failed.
+  With the logger already on stderr from
+  [issue #82](https://git.eeqj.de/sneak/vaultik/issues/82), this was the
+  last writer that could put something on stdout that the caller did not
+  ask for. The design question the issue raised — extend the raw-argv
+  scan, or move the banner after parsing — is answered in favour of the
+  scan: the banner is printed first deliberately, so that it still
+  appears when cobra rejects the arguments and on `--help`, and after
+  parsing there is no single place that covers those paths. The stated
+  cost of the scan, that `--json` is a subcommand flag matched anywhere
+  in the vector, is a cost `--cron` already carries — it exists only on
+  `snapshot create` — so this adds an instance of an accepted
+  imprecision rather than a new kind, and the two error directions are
+  not symmetric: a false positive loses a decorative banner, a false
+  negative corrupts a document. Regression tests at the CLI layer, where
+  `internal/vaultik`'s existing guard cannot reach: one runs `Entry`
+  itself over the process's real stdout descriptor, through cobra and fx
+  to the document, made hermetic by `file://` storage; a second covers
+  the argument vectors of all five `--json` commands; a third asserts the
+  banner is still printed without a suppressing flag, so the first
+  cannot be satisfied by deleting the banner. Also corrected `AGENTS.md`
+  policy 9, which still keyed the structured-log format on stdout's
+  TTY-ness after #82 moved that decision to stderr — a rules file that
+  misdescribes the code misleads exactly the readers who trust it most.
+  Two smaller findings from the same review: `bytesAttrKey`'s
+  human-readable byte formatting silently stopped applying under an open
+  group, because the key reaching the comparison is group-qualified
+  (`transfer.bytes`), now matched on its final segment and tested both
+  ways; and `listEnv.stderr` in `snapshot_list_test.go`, assigned but
+  never read since those tests began capturing the process's stderr, is
+  removed. `Vaultik.Stderr` is kept — nothing writes to it today, which
+  its comment now says outright.
+
+- 2026-08-09: Moved the logger to stderr and fixed `TTYHandler`'s
+  discarded attributes
+  ([issue #82](https://git.eeqj.de/sneak/vaultik/issues/82),
+  [issue #97](https://git.eeqj.de/sneak/vaultik/issues/97)). Two defects
+  in `internal/log`, fixed together because both live in the handler
+  construction path. The first: both handlers were built over
+  `os.Stdout`, and `WARN`/`ERROR` are never suppressed, so a config file
+  with group- or world-readable permissions was enough to put a log
+  record inside a `--json` document and break `jq`. Diagnostics now go
+  to stderr, and the TTY/JSON format choice follows stderr rather than
+  stdout — testing the wrong stream would colorize records on a
+  redirected stderr whenever stdout happened to be a terminal. This is
+  user-visible: `--verbose` and `--debug` output moves to stderr too,
+  which is documented in `README.md` under "stdout and stderr". It also
+  let the local workaround in `internal/vaultik/snapshot_list.go` go:
+  `warnWhileListing` had been hand-rolling structured-log formatting to
+  reach a non-stdout writer, and the `jsonOutput` parameter threaded
+  through the remote-listing helpers existed only to choose between the
+  two writers. The collect-then-emit machinery around `listingWarning`
+  stays, but on its remaining merit — warnings emitted in key order
+  after `group.Wait()` are deterministic run to run, where emitting from
+  the fetch workers would order them by network timing. The second
+  defect: `TTYHandler.WithAttrs` and `WithGroup` discarded their
+  arguments and returned the receiver while their doc comments claimed
+  otherwise, so `log.With` attributes vanished on a terminal and
+  appeared correctly in CI — failing precisely when someone is debugging
+  interactively. Both now return a new handler (the receiver is never
+  written to, since `slog` permits concurrent derivation), attributes
+  persist across records, and grouping is implemented as dotted key
+  prefixes, which is the only honest rendering for a format with nowhere
+  to nest. New tests cover both, including one that feeds the same
+  derivation chain to the TTY and JSON handlers and compares the
+  attribute sets, so the two paths cannot drift apart again. Found and
+  filed while verifying: the startup banner is written to stdout and
+  `--json` does not suppress it
+  ([issue #106](https://git.eeqj.de/sneak/vaultik/issues/106)), which is
+  a separate writer on a separate path and the remaining source of
+  stdout contamination.
+
+- 2026-08-09: Made the tagged-release path actually work on Gitea
+  ([issue #65](https://git.eeqj.de/sneak/vaultik/issues/65)). Three
+  independent blockers, one of which was the whole
+  release: `.goreleaser.yaml` had no `gitea_urls:` block, so goreleaser
+  defaulted to the GitHub API and a `goreleaser release` from this repo
+  would have failed or published where nobody is looking. It now points
+  at `https://git.eeqj.de/api/v1`. The version is the second: it was a
+  hardcoded `VERSION := 1.0.0-rc.1` in the `Makefile`, so every local
+  build claimed to be a release candidate that had never been tagged and
+  did not exist, while `git tag -l` was empty and `internal/globals`
+  defaulted to `dev`. Version now comes from git via the new
+  `script/version` — the exact tag with a leading `v` stripped (so a
+  `make` build and a goreleaser build of one commit report the same
+  string, and it matches the archive names), otherwise `dev-<12-char
+  sha>`, with `-dirty` appended in either case when tracked files are
+  modified. Untracked files are deliberately not counted, matching
+  `git describe --dirty`. The same honesty was owed by the snapshot
+  path: `snapshot.version_template` was `{{ incpatch .Version }}-next`,
+  which manufactures a release number from the last tag and, with no
+  tags at all, from goreleaser's fabricated `v0.0.0`; it now emits the
+  same `dev-<sha>`. The one non-obvious consequence is that
+  `internal/cli/version.go` gated its "this is a development build"
+  notice on the version being exactly `dev`, so the moment untagged
+  builds began carrying a commit sha that notice would have gone silent
+  and an unreleased binary would have read as a release — the gate is
+  now `globals.IsDevVersion`, which is a predicate over a string rather
+  than a comparison against a global precisely so it can be tested, and
+  it is tested at the boundary (`1.0.0-dev` is a release, `dev-<sha>`
+  is not). Release automation is the third blocker: a tag-triggered
+  `.gitea/workflows/release.yml` runs the build in CI rather than from
+  a laptop, with `fetch-depth: 0` because a shallow checkout has no
+  tags and would silently mislabel the release, and with the
+  `RELEASE_TOKEN` repository secret passed as `GITEA_TOKEN` (documented
+  in `README.md`; the runner's automatic token is not used because it
+  is not guaranteed to carry release write scope). `script/release`
+  unsets any `GITHUB_TOKEN`/`GITLAB_TOKEN` it finds, since goreleaser
+  chooses its forge from whichever token variable is set and refuses to
+  run when it sees more than one — a runner-provided token must not get
+  to decide where these artifacts are published. `make release` and
+  `make release-snapshot`, the last two Makefile targets that were not
+  shims, now call `script/release` and `script/release-snapshot`, which
+  resolve goreleaser exactly the way `script/lint` resolves the linter:
+  a `PATH` binary is used only at the pinned version, never as a silent
+  fallback. `script/bootstrap` installs it, from a sha256-verified
+  GitHub release archive per `REPO_POLICIES.md`, via a separate
+  `script/install-goreleaser` — separate because `script/bootstrap`
+  hard-fails without a usable Docker daemon by design, and the release
+  runner needs goreleaser without needing Docker. Verified by running
+  the thing rather than reading it: `make release-snapshot` produced
+  four archives and `checksums.txt`, and the linux/amd64 binary from
+  `dist/` reports `dev-<sha>` with the development-build notice. Tag
+  handling was exercised in a throwaway repository rather than by
+  tagging this one; no tag was created here, since that is the owner's
+  call. Signing, SBOM, reproducible builds, completions and a man page
+  are out of scope by the issue.
+
+- 2026-08-09: Isolated the lint cache per worktree and context-gated the
+  native lint path (issues #99, #80). One defect seen twice:
+  `script/lint` decided whether it could skip the pinned image by asking
+  what version was on `PATH` rather than where it was running, and cache
+  isolation is part of that same question. The cache was one directory
+  per repo, shared by every worktree on the host, so two checkouts with
+  identical Go file contents collided and golangci-lint replayed the
+  stored analysis — paths and all. The loud direction of that failure
+  (a clean tree failed by a dirty sibling) is the harmless one; the
+  silent direction, a dirty tree **passed** by a clean sibling, is a
+  sixth way for a gate here to report a green it did not earn. The cache
+  is now keyed on a digest of the worktree path, and every run is
+  audited by the new `script/lint-audit`, which rejects output citing any
+  file that is not in the tree being linted — a backstop that runs on
+  clean output too, because that is the case nobody investigates. Caches
+  record the worktree they belong to and are collected when it
+  disappears, so throwaway worktrees do not accumulate them; the whole
+  tree lives under `XDG_CACHE_HOME` and is disposable. The
+  `parallel golangci-lint is running` refusal is now a bounded retry
+  rather than a verdict: it is not a lint result, and exiting non-zero
+  on it is indistinguishable to a caller from real findings (#88 showed
+  a private cache does not remove that contention). The native path now
+  requires `VAULTIK_LINT_IN_CONTAINER=1`, set only by the `Dockerfile`
+  lint stage, in addition to matching the pin, so a developer's locally
+  installed 2.12.2 no longer bypasses the digest pin; `/.dockerenv` was
+  rejected as the signal because `dockerd` creates it for `docker run`
+  and it is not reliably present during a BuildKit `docker build`, which
+  is the case the exception exists for. Version detection uses
+  `golangci-lint version --short` with the old banner scrape kept only
+  as a fallback. `script/bootstrap` no longer prints `bootstrap
+  complete` on a machine that cannot run the gate: a missing docker, or
+  one whose daemon is unreachable, is a hard failure naming exactly what
+  breaks. Verification was by reproduction rather than inspection — two
+  concurrent lints from two worktrees of differing cleanliness, a real
+  run made to report an outside path, a matching linter shimmed onto
+  `PATH`, and a `PATH` with docker removed — and is recorded on the pull
+  request.
+- 2026-08-09: Closed the fifth false-green mechanism (issues #93, #69).
+  `script/test` omitted `-count=1`, so Go's test result cache could
+  satisfy the gate outright: a second back-to-back `make test` printed
+  the full set of 14 `ok` lines, every one marked `(cached)`, having
+  executed no test at all. Since `ok <pkg> (cached)` is an `ok` line,
+  the "14 `ok` lines means the suite ran" signal this repo leans on was
+  forgeable, one level below the Docker layer cache that #85 addressed.
+  Fixed with `-count=1` unconditionally rather than only in the
+  container, because the pre-commit hook runs the same script and a
+  gate honest only in CI is dishonest where people rely on it most;
+  `test-coverage` got the same flag, and `script/check` inherits it by
+  calling `script/test`. In the same area, `make test-integration` was
+  deleted rather than made real: no file in the repo carried a build
+  tag, so `-tags=integration` selected nothing and the target was an
+  exact duplicate of `make test`. Tagging a subset was rejected because
+  the entire suite runs in well under a minute, and a scheme whose
+  failure mode is "some tests silently stopped running" is a poor trade
+  for those seconds in a repo with this particular history. The
+  `-timeout` was raised from 30s after measuring rather than after
+  assuming: the standing claim that cold-cache compilation is charged
+  against `-timeout` is **false**, disproved by a containerised run
+  that spent 46s compiling and still reported per-package durations
+  within noise of a warm host run. `-timeout` reaches the test binary
+  as `-test.timeout` and its clock starts inside `testing.M.Run`, after
+  the build. The real exposure was margin, not compilation. The 120s
+  landed on is a **deliberate, documented divergence** from
+  `REPO_POLICIES.md:192`, which mandates 30s, and from that file's
+  canonical recipe at `:212-214`; the divergence is recorded in
+  `script/test`'s comment because `REPO_POLICIES.md` is org-canonical
+  and not editable here, and issue #101 proposes amending the policy
+  text upstream. Numbers and the full verification are recorded once,
+  on the pull request, and are deliberately not restated here.
+
+- 2026-08-09: Triaged all fifteen stale remote branches (issue #71) and
+  deleted fourteen of them; the full per-branch disposition with
+  evidence is recorded on that issue. Method mattered more than the
+  outcome here: a three-dot `git diff main...branch` diffs from the
+  merge base, so it replays everything that landed on `main` after the
+  branch diverged and makes any old branch look like it holds unlanded
+  work. That artifact is what made `golangci-v2.12.2` appear to carry
+  126 files of unpushed changes when its tree was byte-identical to
+  `main`'s. Every containment claim here therefore rests on two-dot tip
+  diffs, tree-hash equality, `git cherry`, and `git branch -r --merged`.
+  Nine branches were plain ancestors of `main` with zero `git cherry`
+  `+` commits. `golangci-v2.12.2` had landed squashed as `cc58583`,
+  whose tree hash equals the branch tip's exactly; note the hash
+  recorded in the issue had gone stale because `main` advanced, so the
+  check had to be redone rather than repeated.
+  `fix/sync-snapshot-cleanup` was redundant, its one line already on
+  `main` in `syncWithRemote`. `feature/restore-progress-bar` was
+  superseded by `printRestoreProgress` and the disk-backed blob cache,
+  and had become actively regressive — it would have deleted
+  `internal/blobgen/compress_test.go`, the #28 regression test that
+  landed separately. The two branches this issue was filed for both
+  turned out to be closed questions that `main` had already moved past
+  by a recorded decision, so neither was landed and no regression test
+  was owed: `ctime` no longer exists anywhere in the codebase after
+  `1c72a37` removed the column, the `File.CTime` field and every use
+  (#54/#55), and change detection compares size, mtime, mode, uid and
+  gid only, exactly as `ARCHITECTURE.md` documents — so the
+  silently-skipped-file data-loss risk that made this a 1.0 item does
+  not exist. The SQL allow-list branch would have reverted `bfd7334`,
+  which replaced that very allow-list with regex sanitisation on review
+  feedback, and would have broken `getTableCount("snapshots")` because
+  its allow-list omits that table. `feature/daemon-mode` is untouched
+  and deferred to #94 pending an owner decision, so it is the one
+  branch besides `main` still on the remote. The stale `TODO.md` entry
+  named in the issue needed no fix: `e496aa3` had already removed it.
+  No product code changed.
+- 2026-08-09: Adopted the remaining upstream `CHECK_EPOCH` hardening
+  (issue #91), closing the gap #85 knowingly left open. Four changes,
+  all four decided as adopt upstream in `sneak/prompts` #26. (1) Each
+  check stage now asserts `[ -n "$CHECK_EPOCH" ] || exit 1` before
+  running anything, so a build that supplies no `--build-arg` fails
+  instead of lying. This is the item that mattered: an unset `ARG` is
+  an empty string and an empty string is a stable cache key, so the
+  second and every later bare `docker build .` on an unchanged tree
+  replayed all three check layers and still exited 0 — and `docker
+  build .` is the command `REPO_POLICIES.md` names verbatim as a thing
+  that must be green, so the documented command was precisely the one
+  that lied. Failed steps are never cached, which is what makes the
+  guard fire on every invocation rather than once. (2) The epoch is now
+  expanded into each check command rather than left as a bare
+  declaration, so the cache miss no longer depends on BuildKit's
+  unreferenced-`ARG` handling staying as it is, and the value appears
+  in the build log. (3) `script/cibuild` uses
+  `epoch="$(date +%s%N)$$"`, unique per invocation rather than per
+  second; `%N` alone is insufficient because busybox drops it silently
+  and exits 0, and `$$` is what makes the guarantee hold regardless.
+  The bare-assignment form is kept deliberately — inlined in an
+  argument, a failing substitution does not abort under `set -eu` and
+  would yield an empty constant epoch, restoring the exact false green
+  being fixed. (4) `script/docker` passes the same fresh arg, so the
+  two entrypoints cannot disagree about whether the tree is green;
+  local builds are almost always warm, which made it the likelier
+  fooling in practice. The `ARG` placement from #85 is unchanged, below
+  `apk add`, `COPY go.mod go.sum` and `go mod download`, so dependency
+  layers still cache and the build is not cold. Verified by negative
+  control rather than inspection — a bare `docker build .` run twice
+  back to back, plus back-to-back pairs of both scripts and a host-side
+  `make check`; the measurements are recorded once, in the PR
+  verification comment, rather than restated here. `.golangci.yml`, the
+  lint-stage `FROM` line and its digest, `script/lint`,
+  `REPO_POLICIES.md` and `.gitea/workflows/check.yml` are all
+  untouched.
+- 2026-08-09: Stopped `script/cibuild` from reporting a green it did
+  not earn (issue #85). A bare `docker build .` let Docker serve the
+  check layers from the layer cache whenever the tree had not changed:
+  the checks never executed and the build still exited 0. The fix is an
+  `ARG CHECK_EPOCH` declared immediately above the check `RUN`s in both
+  the lint stage and the builder stage (`ARG` scope is per-stage, so
+  each declares its own), with `script/cibuild` assigning
+  `epoch="$(date +%s)"` and passing `--build-arg CHECK_EPOCH="$epoch"`.
+  The assignment is separate on purpose: under `set -eu` a command
+  substitution that fails inside an argument does not abort the script,
+  which would leave an empty constant `CHECK_EPOCH` and restore the
+  very false green being fixed. Placement is the rest of the point —
+  the `ARG` sits below the `apk add`, `COPY go.mod go.sum`, and `go mod
+  download` layers, so only the checks are invalidated and the
+  dependency layers still cache. The guarantee is conditional on a
+  fresh value rather than absolute: a bare `docker build .` gets an
+  empty `CHECK_EPOCH` and can still serve the check layers from cache,
+  which `README.md` and the `Dockerfile` now say plainly, with issue
+  #91 tracking the upstream hardening (expanded `ARG` form, unset
+  guard, per-invocation epoch, `script/docker`) that would close it.
+  Verified by re-running the reproduction plus the withheld-`--build-arg`
+  counterfactual; the measurements are recorded once, in the PR #89
+  verification comment, rather than restated here. `.golangci.yml`, the
+  lint-stage `FROM` line and its digest, `script/lint`, and
+  `.gitea/workflows/check.yml` are all untouched.
+- 2026-08-09: Corrected the `Vaultik.UI` doc comment (issue #84). It
+  claimed the cli layer replaces the writer with a discarding one in
+  `--cron` mode; the actual mechanism is `UI.SetQuiet(true)` in
+  `setupGlobals`, which drops Begin/Complete/Info/Notice/Detail/
+  Progress/Banner but still emits Warning and Error. The `--cron` line
+  in `README.md` said "Silent unless error", which understated what
+  survives, and now names warnings too. The other `--cron` comments
+  (`internal/log/log.go`, `internal/cli/snapshot.go`,
+  `internal/vaultik/snapshot.go`) were audited and already accurate.
+  Comments and docs only, no behavior change.
+- 2026-08-09: Made `snapshot list` list the destination store without
+  the private key (issue #64). The listing is now the union of the
+  local index and a single streamed listing of the `metadata/` prefix,
+  with no `age_secret_key` gate — the manifest is unencrypted, so a
+  host holding only the public key can enumerate its own backups and a
+  host that lost its local index can still see them. A remote-only
+  snapshot's hostname and name are deliberately not recovered (they are
+  not recoverable without the private key, and making them so would
+  undo the privacy property tracked in issue #81); such rows are
+  labelled by an abbreviation of their remote key and carry the real
+  timestamp and compressed size from the manifest, with `<remote only>`
+  in the two columns that require the local index. Local-only snapshots
+  are reported as drift, and the hint now names `vaultik prune`, which
+  exists, instead of `vaultik snapshot cleanup`, which does not.
+  `reportRemoteDrift` collapsed into the merged view. Every remote
+  manifest read in the codebase now goes through
+  `downloadManifestByKey`, so issue #81 has one call site to change.
+  Review rework: snapshot timestamps now normalize to UTC in
+  `scanSnapshotRows`, the one place they enter the domain, so the merged
+  TIMESTAMP column cannot show local time for a locally tracked row and
+  UTC for a remote-only row on a non-UTC host; `GetIncompleteByHostname`
+  was folded onto that same scanner. `--json` now reports the
+  unreadable-manifest count and the 1000-row truncation on stderr
+  instead of returning a silently short document (the document's shape
+  is unchanged). The two per-snapshot `log.Warn` calls on the listing
+  path now route through the same JSON-aware writer as the existing
+  workaround, so one corrupt manifest can no longer put a log line on
+  stdout ahead of the document and break `| jq` — still a local
+  workaround pending issue #82. Verified with `script/cibuild` and with
+  an uncached `make check` (`0 issues.`, no cached test packages), plus
+  end to end against a `file://` destination with no secret key present.
+- 2026-08-09: Closed the gap between `make lint` and CI (issue #78).
+  `script/lint` now runs the digest-pinned `golangci-lint` image taken
+  from the `Dockerfile` lint stage, which is the single source of truth
+  for the linter version; the duplicate pin in the `Makefile` `deps`
+  target and the unpinned `golangci-lint` install in `script/bootstrap`
+  are gone. A `golangci-lint` on `PATH` is used only when its version is
+  exactly the pinned one (which is how the lint stage runs it inside the
+  container); anything else goes through Docker, and a missing or
+  unreachable Docker daemon is a hard error rather than a silent
+  fallback. Only the **lint** leg of `make check` became equivalent to
+  `script/cibuild`; its tests and `gofmt` still run on the host against
+  the host toolchain, as `README.md` states. An earlier version of this
+  entry claimed `make check` was "as trustworthy as `script/cibuild`"
+  outright, which overstated it; corrected under issue #80.
 - 2026-08-09: Finished the lint remediation under the canonical
   `.golangci.yml` (issue #61, which also unblocks issue #59). The
   remaining findings were fixed behavior-preservingly: `wsl_v5`
@@ -69,4 +546,4 @@ or delete the branch.
 
 # Future Steps
 
-- Define remaining scope for a first tagged release and cut v0.1.0.
+None queued; the release-scoping item is now the Next Step.

cmd/vaultik/lintdocker_test.go

@@ -0,0 +1,507 @@
+package main_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// This file guards the shape of the lint gate. Every property asserted
+// here is one whose loss is SILENT: the build still exits 0, the gate
+// still looks green, and nothing was linted or tested.
+//
+// The gate is a build step. script/lint builds Dockerfile.lint, which
+// runs golangci-lint as a RUN instruction, so a successful build is a
+// clean lint. BuildKit will happily replay that RUN from cache on an
+// unchanged tree in well under a second, which is why the check layers
+// are keyed on a CHECK_EPOCH build arg that the calling script
+// regenerates per invocation, and why an empty value is a hard error
+// rather than a stable cache key.
+//
+// These are parses rather than invocations. Shelling out to docker from
+// the test suite would nest a build inside `make test`, which itself
+// runs inside a build in CI. The one property a parse cannot establish
+// -- that a real finding actually fails the build -- is verified by
+// hand against a deliberately broken tree, recorded on the pull
+// request.
+
+// The files under guard, relative to the repository root.
+const (
+	lintDockerfile    = "Dockerfile.lint"
+	productDockerfile = "Dockerfile"
+	lintScript        = "script/lint"
+	cibuildScript     = "script/cibuild"
+)
+
+// linterBinary is the linter's command name. Every occurrence of it in
+// executable shell in this repo must be inside a docker invocation; see
+// TestNoHostLintPathRemains.
+const linterBinary = "golangci-lint"
+
+// checkEpochARG is the declaration, with no default value. A default
+// would satisfy the non-empty guard with a constant, and a constant is
+// a stable cache key: the checks would be replayed from cache forever
+// after the first build.
+const checkEpochARG = "ARG CHECK_EPOCH"
+
+// checkEpochGuard is what turns a build that omits --build-arg into a
+// loud failure instead of a quiet green. Failed steps are never cached,
+// so it fires on every such invocation rather than once.
+const checkEpochGuard = `RUN [ -n "$CHECK_EPOCH" ] || exit 1`
+
+// freshEpoch is the epoch computation the calling scripts must use, as
+// a bare assignment on its own line. Inline in an argument, a failing
+// `date` would not abort under `set -eu`; CHECK_EPOCH would become the
+// empty string, and the guard above would be the only thing standing
+// between that and a permanently cached green. `$$` is required because
+// `date +%s` is second-granular and busybox silently drops `%N`, so
+// without the pid two concurrent runs in one second can collide.
+const freshEpoch = `epoch="$(date +%s%N)$$"`
+
+// TestLintDockerfilePinsTheLinterByDigest fails if the lint image stops
+// being pinned. An unpinned tag makes the gate's verdict depend on
+// whatever the registry currently serves under that name.
+func TestLintDockerfilePinsTheLinterByDigest(t *testing.T) {
+	t.Parallel()
+
+	from := ""
+
+	for _, instruction := range instructions(t, lintDockerfile) {
+		if strings.HasPrefix(instruction, "FROM ") {
+			from = instruction
+
+			break
+		}
+	}
+
+	require.NotEmpty(t, from, "%s declares no FROM", lintDockerfile)
+	assert.Contains(t, from, "golangci/golangci-lint",
+		"the lint image must be the golangci-lint image")
+	assert.Contains(t, from, "@sha256:",
+		"the lint image must be pinned by digest, not by tag alone")
+}
+
+// TestLintDockerfileCannotBeCachedGreen pins the whole cache-busting
+// mechanism in the file that lints: the declaration with no default,
+// the non-empty guard, and the value expanded into the lint command
+// itself rather than merely declared.
+func TestLintDockerfileCannotBeCachedGreen(t *testing.T) {
+	t.Parallel()
+
+	found := instructions(t, lintDockerfile)
+
+	argAt := indexOf(found, checkEpochARG)
+	require.GreaterOrEqual(t, argAt, 0,
+		"%s must declare `%s` with no default value",
+		lintDockerfile, checkEpochARG)
+
+	assert.GreaterOrEqual(t, indexOf(found, checkEpochGuard), argAt,
+		"%s must guard against an empty CHECK_EPOCH with `%s`",
+		lintDockerfile, checkEpochGuard)
+
+	assertEpochExpandedInto(t, found[argAt:], "golangci-lint run")
+
+	// Dependency layers must stay above the ARG, or every lint run
+	// re-downloads the module cache and the inner loop becomes
+	// unusable.
+	download := indexOf(found, "RUN go mod download")
+	require.GreaterOrEqual(t, download, 0,
+		"%s must download modules in their own layer", lintDockerfile)
+	assert.Less(t, download, argAt,
+		"`%s` must come after `go mod download` so dependency layers"+
+			" still cache", checkEpochARG)
+}
+
+// TestLintDockerfileVerifiesTheLinterConfig guards the validation of
+// .golangci.yml itself. `golangci-lint run` rejects a config it cannot
+// parse but silently IGNORES an unknown top-level key, so renaming
+// `linters:` to `linterz:` discards `default: all` and every threshold
+// and still exits 0 reporting no issues. `config verify` is what turns
+// that into a failure, and it has to run BEFORE the lint, or the lint
+// spends a minute reporting a verdict from a config already known to be
+// wrong.
+func TestLintDockerfileVerifiesTheLinterConfig(t *testing.T) {
+	t.Parallel()
+
+	found := instructions(t, lintDockerfile)
+	verify := linterBinary + " config verify"
+
+	verifyAt := indexContaining(found, verify)
+	require.GreaterOrEqual(t, verifyAt, 0,
+		"%s must run `%s --config .golangci.yml`: without it a typo'd"+
+			" top-level key in .golangci.yml is silently ignored and the"+
+			" gate passes with only the default linter set", lintDockerfile,
+		verify)
+
+	runAt := indexContaining(found, linterBinary+" run")
+	require.GreaterOrEqual(t, runAt, 0, "%s must lint", lintDockerfile)
+	assert.Less(t, verifyAt, runAt,
+		"%s must verify the config before linting with it", lintDockerfile)
+
+	// Keyed on the epoch like every other check layer, so it executes
+	// per invocation rather than being replayed. A cached validation
+	// validates nothing.
+	assertEpochExpandedInto(t, found, verify)
+}
+
+// TestProductDockerfileCannotBeCachedGreen holds the same line for the
+// checks that remain in the product image build.
+func TestProductDockerfileCannotBeCachedGreen(t *testing.T) {
+	t.Parallel()
+
+	found := instructions(t, productDockerfile)
+
+	argAt := indexOf(found, checkEpochARG)
+	require.GreaterOrEqual(t, argAt, 0,
+		"%s must declare `%s` with no default value",
+		productDockerfile, checkEpochARG)
+
+	assert.GreaterOrEqual(t, indexOf(found, checkEpochGuard), argAt,
+		"%s must guard against an empty CHECK_EPOCH", productDockerfile)
+
+	assertEpochExpandedInto(t, found[argAt:], "make fmt-check")
+	assertEpochExpandedInto(t, found[argAt:], "make test")
+}
+
+// TestProductDockerfileDoesNotLint records the split deliberately: the
+// linter lives in Dockerfile.lint and nowhere else, so there is exactly
+// one digest pinning it. A lint stage reintroduced here would either be
+// docker-in-docker (`make lint` is now `docker build`) or a second,
+// independently bumpable pin.
+func TestProductDockerfileDoesNotLint(t *testing.T) {
+	t.Parallel()
+
+	contents := readRepoFile(t, productDockerfile)
+
+	for _, forbidden := range []string{"golangci", "make lint"} {
+		assert.NotContains(t, instructionText(contents), forbidden,
+			"%s must not lint: the linter is pinned once, in %s",
+			productDockerfile, lintDockerfile)
+	}
+}
+
+// TestLintScriptBuildsTheLintDockerfileWithAFreshEpoch is the other
+// half of the mechanism. The Dockerfile's guard only rejects an EMPTY
+// epoch; a constant non-empty one would satisfy it and still be served
+// from cache forever.
+func TestLintScriptBuildsTheLintDockerfileWithAFreshEpoch(t *testing.T) {
+	t.Parallel()
+
+	script := readRepoFile(t, lintScript)
+
+	assertBareEpochAssignment(t, script, lintScript)
+	assert.Contains(t, script, `--build-arg CHECK_EPOCH="$epoch"`,
+		"%s must pass the fresh epoch to the build", lintScript)
+	assert.Contains(t, script, lintDockerfile,
+		"%s must build %s", lintScript, lintDockerfile)
+}
+
+// TestCibuildBuildsBothDockerfilesWithFreshEpochs guards the CI gate:
+// dropping either build silently removes a whole class of check from
+// CI while leaving it green.
+func TestCibuildBuildsBothDockerfilesWithFreshEpochs(t *testing.T) {
+	t.Parallel()
+
+	script := readRepoFile(t, cibuildScript)
+
+	assertBareEpochAssignment(t, script, cibuildScript)
+	assert.Equal(t, 2, strings.Count(script, freshEpoch),
+		"%s must compute a fresh epoch for each of its two builds",
+		cibuildScript)
+	assert.Equal(t, 2,
+		strings.Count(script, `--build-arg CHECK_EPOCH="$epoch"`),
+		"%s must pass a fresh epoch to both builds", cibuildScript)
+	assert.Contains(t, script, "-f Dockerfile.lint",
+		"%s must build %s", cibuildScript, lintDockerfile)
+}
+
+// TestNoHostLintPathRemains fails if any escape hatch to a host linter
+// comes back. The owner's ruling is that every lint run happens inside
+// a container; a PATH binary that happens to match the pinned version
+// is a different build reached by a different code path, and admitting
+// it is what lets a local pass disagree with CI.
+//
+// This asserts the PROPERTY -- no script invokes the linter except
+// through docker -- rather than the absence of any particular variable
+// name. An earlier version of this test looked only for the literal
+// VAULTIK_LINT_IN_CONTAINER, the name of the hatch that was removed
+// alongside it, so nothing could ever trip it again: a hatch under any
+// other name left it passing. A structural test that passes on a broken
+// tree is worse than no test, because it is what a later reader trusts
+// instead of re-deriving the invariant.
+//
+// script/lint-fix is not exempted. It is the one script that runs the
+// linter as a container rather than as a build step, but it still runs
+// it in one, so the same property holds of it.
+func TestNoHostLintPathRemains(t *testing.T) {
+	t.Parallel()
+
+	root := repoRoot(t)
+
+	entries, err := os.ReadDir(filepath.Join(root, "script"))
+	require.NoError(t, err)
+	require.NotEmpty(t, entries, "no scripts found to scan")
+
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+
+		name := filepath.Join("script", entry.Name())
+		for _, line := range shellCode(readRepoFile(t, name)) {
+			assertLinterIsContainerised(t, name, line)
+		}
+	}
+}
+
+// assertLinterIsContainerised fails if the line runs the linter without
+// handing it to docker first. Position matters: docker has to come
+// before the binary, or the line is running the host linter and merely
+// mentioning docker afterwards.
+func assertLinterIsContainerised(t *testing.T, name, line string) {
+	t.Helper()
+
+	at := strings.Index(line, linterBinary)
+	if at < 0 {
+		return
+	}
+
+	docker := strings.Index(line, "docker")
+
+	assert.True(t, docker >= 0 && docker < at,
+		"%s runs %s on the host; every lint run happens in a container"+
+			" (line: %s)", name, linterBinary, line)
+}
+
+// TestShellCodeSeesCodeAndNotProse keeps the scanner above honest. It
+// has to ignore comments and here-document bodies, because script/lint
+// and script/bootstrap both NAME golangci-lint in prose -- in comments,
+// and in the error text they print -- precisely to say that the host
+// binary is never used. A scanner that went blind, by over-eager
+// stripping or by failing to join continuation lines, would make
+// TestNoHostLintPathRemains pass on everything.
+func TestShellCodeSeesCodeAndNotProse(t *testing.T) {
+	t.Parallel()
+
+	script := strings.Join([]string{
+		"#!/bin/sh",
+		"# a comment naming golangci-lint",
+		"cat >&2 <<EOF",
+		"prose naming golangci-lint, printed not executed",
+		"EOF",
+		"docker run --rm \\",
+		"    \"$image\" \\",
+		"    golangci-lint run ./...",
+	}, "\n")
+
+	assert.Equal(t,
+		[]string{"cat >&2 <<EOF", `docker run --rm "$image" golangci-lint run ./...`},
+		shellCode(script))
+}
+
+// assertEpochExpandedInto fails unless some instruction runs the named
+// command with the epoch expanded into it. Expansion, not mere
+// declaration: an ARG that no instruction references is not guaranteed
+// to key the layer, and the expansion also puts the value in the build
+// log where a reader can see the layer was keyed fresh.
+func assertEpochExpandedInto(t *testing.T, found []string, command string) {
+	t.Helper()
+
+	for _, instruction := range found {
+		if !strings.HasPrefix(instruction, "RUN ") {
+			continue
+		}
+
+		if strings.Contains(instruction, command) &&
+			strings.Contains(instruction, "${CHECK_EPOCH}") {
+			return
+		}
+	}
+
+	assert.Fail(t, "no epoch-keyed layer runs the command",
+		"`%s` must run in a layer that expands ${CHECK_EPOCH}, or it"+
+			" will be replayed from cache without executing", command)
+}
+
+// assertBareEpochAssignment fails unless the script computes the epoch
+// as a bare assignment on its own line.
+func assertBareEpochAssignment(t *testing.T, script, name string) {
+	t.Helper()
+
+	for line := range strings.SplitSeq(script, "\n") {
+		if strings.TrimSpace(line) == freshEpoch {
+			return
+		}
+	}
+
+	assert.Fail(t, "no bare epoch assignment",
+		"%s must compute `%s` as a bare assignment on its own line, so"+
+			" `set -e` catches a failing date instead of quietly"+
+			" building with an empty epoch", name, freshEpoch)
+}
+
+// instructions returns the Dockerfile's instructions, one per element,
+// with comments and blank lines dropped and continuation lines joined,
+// so a multi-line RUN is one string.
+func instructions(t *testing.T, name string) []string {
+	t.Helper()
+
+	return strings.Split(instructionText(readRepoFile(t, name)), "\n")
+}
+
+// instructionText is instructions' parse, before splitting: it is also
+// what a "must not contain" assertion should look at, so that a word
+// appearing only in a comment is not mistaken for behaviour.
+func instructionText(contents string) string {
+	var (
+		out         []string
+		continued   string
+		isContinued bool
+	)
+
+	for line := range strings.SplitSeq(contents, "\n") {
+		trimmed := strings.TrimSpace(line)
+		if !isContinued && (trimmed == "" || strings.HasPrefix(trimmed, "#")) {
+			continue
+		}
+
+		isContinued = strings.HasSuffix(trimmed, `\`)
+		continued += strings.TrimSuffix(trimmed, `\`)
+
+		if isContinued {
+			continue
+		}
+
+		out = append(out, strings.Join(strings.Fields(continued), " "))
+		continued = ""
+	}
+
+	return strings.Join(out, "\n")
+}
+
+// indexOf returns the position of the first instruction equal to, or
+// beginning with, want; -1 if there is none.
+func indexOf(found []string, want string) int {
+	for i, instruction := range found {
+		if instruction == want || strings.HasPrefix(instruction, want+" ") {
+			return i
+		}
+	}
+
+	return -1
+}
+
+// indexContaining returns the position of the first instruction
+// containing want; -1 if there is none.
+func indexContaining(found []string, want string) int {
+	for i, instruction := range found {
+		if strings.Contains(instruction, want) {
+			return i
+		}
+	}
+
+	return -1
+}
+
+// shellCode returns a POSIX shell script's executable lines: comments
+// dropped, here-document bodies dropped, and backslash continuations
+// joined so a multi-line command is a single string. Whitespace is
+// collapsed, as it is for Dockerfile instructions.
+//
+// Both exclusions are load-bearing rather than tidiness. The scripts
+// name golangci-lint in prose to state that the host binary is never
+// used, and joining continuations is what lets the one legitimate
+// container invocation -- script/lint-fix's `docker run`, whose linter
+// command sits several lines below the word `docker` -- be recognised
+// as containerised.
+func shellCode(contents string) []string {
+	var (
+		out       []string
+		joined    string
+		terminate string
+	)
+
+	for line := range strings.SplitSeq(contents, "\n") {
+		trimmed := strings.TrimSpace(line)
+
+		if terminate != "" {
+			if trimmed == terminate {
+				terminate = ""
+			}
+
+			continue
+		}
+
+		if joined == "" && (trimmed == "" || strings.HasPrefix(trimmed, "#")) {
+			continue
+		}
+
+		joined += strings.TrimSuffix(trimmed, `\`) + " "
+		if strings.HasSuffix(trimmed, `\`) {
+			continue
+		}
+
+		joined = strings.Join(strings.Fields(joined), " ")
+		terminate = heredocTerminator(joined)
+
+		out = append(out, joined)
+		joined = ""
+	}
+
+	return out
+}
+
+// heredocTerminator returns the terminator of the here-document a
+// command opens, or "" if it opens none. Only the first on a line is
+// recognised; nothing in script/ opens two.
+func heredocTerminator(line string) string {
+	_, after, opens := strings.Cut(line, "<<")
+	if !opens {
+		return ""
+	}
+
+	// `<<-` strips leading tabs from the body; the terminator word is
+	// the same either way, and callers compare against trimmed lines.
+	word, _, _ := strings.Cut(strings.TrimPrefix(after, "-"), " ")
+
+	return strings.Trim(word, `'"`)
+}
+
+// readRepoFile reads a file by its path relative to the repository
+// root.
+func readRepoFile(t *testing.T, name string) string {
+	t.Helper()
+
+	//nolint:gosec // G304: the path is a constant relative to this repo
+	contents, err := os.ReadFile(filepath.Join(repoRoot(t), name))
+	require.NoError(t, err)
+
+	return string(contents)
+}
+
+// repoRoot returns the repository root. The test binary runs with its
+// package directory as the working directory, so the root is found by
+// walking up until the module file appears.
+func repoRoot(t *testing.T) string {
+	t.Helper()
+
+	dir, err := os.Getwd()
+	require.NoError(t, err)
+
+	for {
+		_, err = os.Stat(filepath.Join(dir, "go.mod"))
+		if err == nil {
+			return dir
+		}
+
+		parent := filepath.Dir(dir)
+		require.NotEqual(t, dir, parent,
+			"walked to the filesystem root without finding a go.mod")
+
+		dir = parent
+	}
+}

cmd/vaultik/makefile_test.go

@@ -0,0 +1,151 @@
+package main_test
+
+import (
+	"regexp"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// This file guards the Makefile that builds this program, which is why
+// it lives beside it rather than in a package of its own.
+//
+// Issue #110: `build` was listed in .PHONY with no `build:` rule
+// anywhere in the file. That combination is silently successful — make
+// considers a phony target with no prerequisites and no recipe already
+// satisfied, so `rm -f vaultik && make build` printed "Nothing to be
+// done for 'build'" and exited 0 with no binary produced. Declaring the
+// name phony is precisely what converts the "No rule to make target"
+// error into a green.
+//
+// The guard is a parse of the Makefile rather than an invocation of
+// make. `make test` is what runs these tests, so shelling back into
+// `make build` here would nest a build inside the test run and drop a
+// binary into the tree as a side effect of testing. The one property a
+// parse cannot establish — that the recipe still fails when the build
+// fails — is not testable from inside the build either; it is verified
+// by hand against a deliberately broken tree.
+
+// phonyDirective introduces the list of phony target names.
+const phonyDirective = ".PHONY:"
+
+// ruleLine matches a rule's target list: a target starts in column
+// zero, so recipe lines (tab-indented) and the continuation lines of a
+// variable assignment (space-indented) are excluded by construction.
+//
+// The trailing (?:[^=]|$) rejects `:=` assignments such as
+// `VERSION := $(shell script/version)`, which are not rules. Directives
+// and function calls (`.PHONY:`, `ifeq`, `$(error ...)`) do not match
+// because a target here must begin with a letter, digit or underscore.
+var ruleLine = regexp.MustCompile(`^([A-Za-z0-9_][A-Za-z0-9_./ -]*):(?:[^=]|$)`)
+
+// TestPhonyTargetsAllHaveRules fails on any name in .PHONY that has no
+// rule in the Makefile. Such a name is not a build target at all: it is
+// a command that reports success without doing anything, which is worse
+// than one that does not exist, because a caller checking the exit code
+// cannot tell the difference.
+func TestPhonyTargetsAllHaveRules(t *testing.T) {
+	t.Parallel()
+
+	makefile := readMakefile(t)
+
+	phony := phonyTargets(makefile)
+	require.NotEmpty(t, phony, "no .PHONY names found; the parser is broken")
+
+	rules := declaredRules(makefile)
+
+	// Sanity check on the rule parser before trusting its verdict: a
+	// parser that found nothing would pass this test by accident.
+	require.Contains(t, rules, "vaultik",
+		"the file rule that builds the binary must be recognized")
+
+	for _, target := range phony {
+		assert.Contains(t, rules, target,
+			"`.PHONY` lists %q but the Makefile declares no %q rule, so "+
+				"`make %s` exits 0 without doing anything", target, target, target)
+	}
+}
+
+// TestBuildTargetBuildsTheBinary pins the specific shape of issue #110:
+// `make build` has to reach the rule that produces the binary. The test
+// above would also pass if `build:` were given an empty recipe of its
+// own, which would be the same silent success under a different
+// spelling.
+func TestBuildTargetBuildsTheBinary(t *testing.T) {
+	t.Parallel()
+
+	prerequisites := rulePrerequisites(readMakefile(t), "build")
+	require.NotNil(t, prerequisites, "the Makefile declares no `build` rule")
+
+	assert.Contains(t, prerequisites, "vaultik",
+		"`make build` must depend on the rule that builds the binary")
+}
+
+// readMakefile returns the contents of the repository's Makefile. The
+// root is located by the shared walk in lintdocker_test.go.
+func readMakefile(t *testing.T) string {
+	t.Helper()
+
+	return readRepoFile(t, "Makefile")
+}
+
+// phonyTargets returns every name declared phony, across all .PHONY
+// lines.
+func phonyTargets(makefile string) []string {
+	var targets []string
+
+	for line := range strings.SplitSeq(makefile, "\n") {
+		if !strings.HasPrefix(line, phonyDirective) {
+			continue
+		}
+
+		targets = append(targets,
+			strings.Fields(strings.TrimPrefix(line, phonyDirective))...)
+	}
+
+	return targets
+}
+
+// declaredRules returns the set of target names that have a rule.
+func declaredRules(makefile string) map[string]bool {
+	rules := make(map[string]bool)
+
+	for line := range strings.SplitSeq(makefile, "\n") {
+		match := ruleLine.FindStringSubmatch(line)
+		if match == nil {
+			continue
+		}
+
+		// One rule may name several targets: `a b: prereq`.
+		for target := range strings.FieldsSeq(match[1]) {
+			rules[target] = true
+		}
+	}
+
+	return rules
+}
+
+// rulePrerequisites returns the prerequisites of the named rule, or nil
+// if no such rule exists. A rule with none returns an empty slice, so
+// "declared with nothing to do" is distinguishable from "not declared".
+func rulePrerequisites(makefile, target string) []string {
+	for line := range strings.SplitSeq(makefile, "\n") {
+		match := ruleLine.FindStringSubmatch(line)
+		if match == nil {
+			continue
+		}
+
+		if !slices.Contains(strings.Fields(match[1]), target) {
+			continue
+		}
+
+		_, after, _ := strings.Cut(line, ":")
+
+		return append([]string{}, strings.Fields(after)...)
+	}
+
+	return nil
+}

internal/cli/entry.go

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"io"
 	"os"
 	"strings"
 	"time"
@@ -14,18 +15,12 @@ import (
 const shortCommitLen = 12
 
 // Entry is the main entry point for the CLI application.
-// It prints the startup banner (unless a quiet flag is present in os.Args),
-// executes the root cobra command, and routes any returned error through
-// the ui.Writer so the user sees a properly formatted "🛑 ERROR:" line.
+// It prints the startup banner to stdout (unless a banner-suppressing
+// flag is present in os.Args — see bannerSuppressedInArgs), executes the
+// root cobra command, and routes any returned error through the
+// ui.Writer so the user sees a properly formatted "🛑 ERROR:" line.
 func Entry() {
-	if !bannerSuppressedInArgs(os.Args[1:]) {
-		short := globals.Commit
-		if len(short) > shortCommitLen {
-			short = short[:shortCommitLen]
-		}
-
-		writeStartupBanner(ui.New(os.Stdout), time.Now().UTC(), short)
-	}
+	emitStartupBanner(os.Args[1:], os.Stdout)
 
 	rootCmd := NewRootCommand()
 	rootCmd.SilenceErrors = true
@@ -37,6 +32,24 @@ func Entry() {
 	}
 }
 
+// emitStartupBanner writes the startup banner to w unless args (the
+// argument vector with the program name already stripped) contains a
+// flag that suppresses it. Split out of Entry so that the decision — the
+// only thing standing between a --json invocation and a parseable
+// stdout — is reachable from a test without running the whole CLI.
+func emitStartupBanner(args []string, w io.Writer) {
+	if bannerSuppressedInArgs(args) {
+		return
+	}
+
+	short := globals.Commit
+	if len(short) > shortCommitLen {
+		short = short[:shortCommitLen]
+	}
+
+	writeStartupBanner(ui.New(w), time.Now().UTC(), short)
+}
+
 // ReportErrorf emits a user-facing error to stderr in the standard
 // 🛑 ERROR: format. Use it from goroutine error paths (where returning
 // an error to cobra isn't an option) and anywhere else a CLI command
@@ -46,9 +59,20 @@ func ReportErrorf(format string, args ...any) {
 }
 
 // bannerSuppressedInArgs reports whether any of args is a flag that
-// should suppress the startup banner (--quiet/-q/--cron). Stops at the
-// "--" argument terminator. Recognizes both long forms and short -q,
-// including combined short flags like "-qv".
+// should suppress the startup banner (--quiet/-q/--cron/--json). Stops
+// at the "--" argument terminator. Recognizes both long forms and short
+// -q, including combined short flags like "-qv".
+//
+// This scans the raw argument vector because the banner is printed
+// before cobra parses anything — deliberately, so that it still appears
+// when cobra rejects the arguments and on --help. The consequence is
+// that a flag is matched wherever it occurs in the vector, including
+// positions where the command it belongs to would not accept it.
+// --json is a subcommand flag rather than a persistent one, but so is
+// --cron (it exists only on `snapshot create`), so this adds no new
+// class of imprecision. The only cost of a false positive is a missing
+// decorative banner; the cost of a false negative is a corrupt document
+// on stdout, so the scan errs deliberately in that direction.
 func bannerSuppressedInArgs(args []string) bool {
 	for _, a := range args {
 		if a == "--" {
@@ -56,11 +80,13 @@ func bannerSuppressedInArgs(args []string) bool {
 		}
 
 		switch a {
-		case "--quiet", "-q", "--cron":
+		case "--quiet", "-q", "--cron", "--json":
 			return true
 		}
 
-		if strings.HasPrefix(a, "--quiet=") || strings.HasPrefix(a, "--cron=") {
+		if strings.HasPrefix(a, "--quiet=") ||
+			strings.HasPrefix(a, "--cron=") ||
+			strings.HasPrefix(a, "--json=") {
 			return true
 		}
 		// Combined short flags like -qv or -vq.

internal/cli/entry_banner_test.go

@@ -0,0 +1,300 @@
+package cli //nolint:testpackage // needs access to unexported emitStartupBanner
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/adrg/xdg"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Command words and flags used to build argument vectors below. They are
+// constants rather than repeated literals so that a rename shows up as a
+// compile error in one place.
+const (
+	cmdSnapshot = "snapshot"
+	cmdList     = "list"
+	cmdCreate   = "create"
+	cmdVerify   = "verify"
+	cmdRemove   = "remove"
+	cmdPrune    = "prune"
+	cmdRemote   = "remote"
+	cmdInfo     = "info"
+
+	flagJSON   = "--json"
+	flagQuiet  = "--quiet"
+	flagConfig = "--config"
+
+	// programName is argv[0] as the real process receives it. Entry
+	// strips it before scanning, so it has to be present.
+	programName = "vaultik"
+
+	// someSnapshotID is any snapshot identifier: these tests never run
+	// the command, so it only has to occupy the positional argument.
+	someSnapshotID = "host_2026-01-01T00:00:00Z"
+)
+
+// placeholderJSONDocument stands in for whatever document a --json
+// command writes to stdout. `snapshot list --json` with no snapshots
+// prints exactly this; the other --json commands print an object rather
+// than an array, but this test is not about their shape. It is about
+// what is on stdout *before* them, which is the same for all of them
+// because Entry prints the banner before cobra has parsed anything and
+// therefore before it can know which command is running.
+const placeholderJSONDocument = "[]\n"
+
+// jsonArgumentVectors are the argument vectors of every --json
+// invocation the CLI accepts, with the program name stripped exactly as
+// Entry strips it. Each one must leave stdout untouched by the banner.
+//
+//nolint:gochecknoglobals // read-only test fixture shared by two tests
+var jsonArgumentVectors = map[string][]string{
+	"snapshot list":   {cmdSnapshot, cmdList, flagJSON},
+	"snapshot verify": {cmdSnapshot, cmdVerify, someSnapshotID, flagJSON},
+	"snapshot remove": {cmdSnapshot, cmdRemove, someSnapshotID, flagJSON},
+	"prune":           {cmdPrune, flagJSON},
+	"remote info":     {cmdRemote, cmdInfo, flagJSON},
+
+	// --json before the subcommand, and with an explicit value: the
+	// scan is positional, so both forms have to be recognized.
+	"json first":      {flagJSON, cmdSnapshot, cmdList},
+	"json with value": {cmdSnapshot, cmdList, flagJSON + "=true"},
+
+	// A --json invocation that also carries a flag with a value, so the
+	// scan cannot be fooled by an argument that consumes the next one.
+	"json with config": {
+		flagConfig, "/nonexistent/vaultik.yml", cmdSnapshot, cmdList, flagJSON,
+	},
+}
+
+// TestJSONInvocationStdoutIsExactlyOneDocument is the CLI-layer
+// regression guard for issue #106: `vaultik snapshot list --json | jq`
+// must work with no other flags.
+//
+// internal/vaultik's TestListSnapshots_JSONStdoutIsOnlyTheDocument
+// guards the same contract one layer down, but it calls the library
+// function directly and so cannot see Entry, which is where the
+// contamination was: the startup banner is written to stdout before
+// cobra parses anything, and the suppression scan did not know about
+// --json. The two banner lines and the blank line landed ahead of the
+// document and `jq` refused the result.
+//
+// The document is a constant here because this test is about the
+// argument vectors, one per --json command; the one that runs a real
+// command end to end is TestEntryJSONStdoutIsExactlyOneDocument below.
+func TestJSONInvocationStdoutIsExactlyOneDocument(t *testing.T) {
+	t.Parallel()
+
+	for name, argv := range jsonArgumentVectors {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var stdout bytes.Buffer
+
+			emitStartupBanner(argv, &stdout)
+
+			require.Empty(t, stdout.String(),
+				"nothing may reach stdout ahead of a --json document")
+
+			_, err := stdout.WriteString(placeholderJSONDocument)
+			require.NoError(t, err)
+
+			requireExactlyOneJSONDocument(t, stdout.String())
+		})
+	}
+}
+
+// TestBannerStillPrintedWithoutSuppressingFlag pins the other half of
+// the contract. Without it, deleting the banner outright would satisfy
+// the test above, and the banner is wanted on interactive invocations.
+func TestBannerStillPrintedWithoutSuppressingFlag(t *testing.T) {
+	t.Parallel()
+
+	for name, argv := range map[string][]string{
+		"no flags": {cmdSnapshot, cmdList},
+		"verbose":  {cmdSnapshot, cmdList, "--verbose"},
+		"after the terminator": {
+			cmdSnapshot, "restore", "--", flagJSON,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var stdout bytes.Buffer
+
+			emitStartupBanner(argv, &stdout)
+
+			assert.Contains(t, stdout.String(), "starting up at",
+				"the banner belongs on invocations that did not opt out")
+		})
+	}
+}
+
+// TestBannerSuppressedInArgs covers the suppression scan directly,
+// including the flags that suppressed the banner before --json joined
+// them, so that adding --json cannot regress them.
+func TestBannerSuppressedInArgs(t *testing.T) {
+	t.Parallel()
+
+	for name, testCase := range map[string]struct {
+		args       []string
+		suppressed bool
+	}{
+		"quiet long":     {[]string{cmdSnapshot, cmdCreate, flagQuiet}, true},
+		"quiet short":    {[]string{cmdSnapshot, cmdCreate, "-q"}, true},
+		"quiet combined": {[]string{cmdSnapshot, cmdCreate, "-qv"}, true},
+		"cron":           {[]string{cmdSnapshot, cmdCreate, "--cron"}, true},
+		"json":           {[]string{cmdSnapshot, cmdList, flagJSON}, true},
+		"nothing":        {[]string{cmdSnapshot, cmdList}, false},
+		"empty":          {nil, false},
+		"json after dashes": {
+			[]string{cmdSnapshot, cmdList, "--", flagJSON}, false,
+		},
+		"quiet after dashes": {
+			[]string{cmdSnapshot, cmdCreate, "--", "-q"}, false,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			assert.Equal(t, testCase.suppressed,
+				bannerSuppressedInArgs(testCase.args))
+		})
+	}
+}
+
+// hermeticConfig is a complete, valid config that needs no network and
+// no credentials: file:// storage is exempt from the S3 credential
+// checks, and FileStorer over a directory that does not exist lists
+// zero objects without erroring. Chunk, blob and compression settings
+// are filled in by config.Load.
+const hermeticConfig = `age_recipients:
+  - age1278m9q7dp3chsh2dcy82qk27v047zywyvtxwnj4cvt0z65jw6a7q5dqhfj
+snapshots:
+  test:
+    paths:
+      - %s
+storage_url: file://%s
+index_path: %s
+hostname: test-host
+`
+
+// TestEntryJSONStdoutIsExactlyOneDocument runs the real thing: Entry,
+// with a real argument vector, over the process's real stdout file
+// descriptor, all the way through cobra and the fx graph to the
+// document. It is the assertion the issue asks for — `vaultik snapshot
+// list --json | jq .` with no other flags — with the pipe replaced by a
+// decoder.
+//
+// `snapshot list` is the command chosen because it is the only --json
+// command that reaches its document without a populated destination
+// store: it reads the local index, streams `metadata/` (empty here),
+// and treats a barren destination as an empty list rather than a
+// failure.
+//
+// Not parallel: it replaces os.Args, os.Stdout and the xdg globals.
+func TestEntryJSONStdoutIsExactlyOneDocument(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "config.yml")
+
+	contents := fmt.Sprintf(hermeticConfig,
+		filepath.Join(dir, "source"),
+		filepath.Join(dir, "store"),
+		filepath.Join(dir, "index.sqlite"))
+
+	require.NoError(t,
+		os.WriteFile(configPath, []byte(contents), configFileMode))
+
+	// The PID lock lives under xdg.DataHome, which xdg resolves at
+	// package init; point it at the temp dir so the test neither
+	// touches nor collides with the real one.
+	t.Setenv("XDG_DATA_HOME", filepath.Join(dir, "data"))
+	xdg.Reload()
+	t.Cleanup(xdg.Reload)
+
+	previousArgs := os.Args
+
+	t.Cleanup(func() {
+		os.Args = previousArgs
+		rootFlags = RootFlags{}
+	})
+
+	os.Args = []string{
+		programName, flagConfig, configPath, cmdSnapshot, cmdList, flagJSON,
+	}
+
+	stdout := captureProcessStdout(t, Entry)
+
+	requireExactlyOneJSONDocument(t, stdout)
+
+	var snapshots []any
+
+	require.NoError(t, json.Unmarshal([]byte(stdout), &snapshots))
+	assert.Empty(t, snapshots,
+		"a destination store with no snapshots lists none")
+}
+
+// captureProcessStdout redirects the process's own stdout to a pipe for
+// the duration of fn and returns what was written to it. The redirection
+// has to be at the file-descriptor level rather than through an injected
+// writer, because the banner and the JSON encoder reach os.Stdout
+// independently and the point of the test is that both land in the same
+// place.
+//
+// Not parallel-safe: os.Stdout is process-global.
+func captureProcessStdout(t *testing.T, fn func()) string {
+	t.Helper()
+
+	reader, writer, err := os.Pipe()
+	require.NoError(t, err)
+
+	previous := os.Stdout
+	os.Stdout = writer
+
+	captured := make(chan string, 1)
+
+	go func() {
+		var buf bytes.Buffer
+
+		_, _ = io.Copy(&buf, reader)
+		captured <- buf.String()
+	}()
+
+	fn()
+
+	os.Stdout = previous
+
+	require.NoError(t, writer.Close())
+
+	out := <-captured
+
+	require.NoError(t, reader.Close())
+
+	return out
+}
+
+// requireExactlyOneJSONDocument fails unless stdout decodes as a single
+// JSON value with nothing before or after it — the property that makes
+// `| jq` work.
+func requireExactlyOneJSONDocument(t *testing.T, stdout string) {
+	t.Helper()
+
+	decoder := json.NewDecoder(strings.NewReader(stdout))
+
+	var document any
+
+	err := decoder.Decode(&document)
+	require.NoError(t, err,
+		"stdout must parse as JSON, got:\n%s", stdout)
+
+	_, err = decoder.Token()
+	require.ErrorIs(t, err, io.EOF,
+		"stdout must hold exactly one JSON document, got:\n%s", stdout)
+}

internal/cli/entry_prune_json_test.go

@@ -0,0 +1,165 @@
+package cli //nolint:testpackage // shares hermeticConfig and the capture helpers
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/adrg/xdg"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/database"
+	"sneak.berlin/go/vaultik/internal/types"
+)
+
+// pruneJSONDocument is the shape `prune --json` writes: the
+// PruneBlobsResult document, and nothing else.
+//
+//nolint:tagliatelle // snake_case is the established JSON output format
+type pruneJSONDocument struct {
+	BlobsFound   int   `json:"blobs_found"`
+	BlobsDeleted int   `json:"blobs_deleted"`
+	BytesFreed   int64 `json:"bytes_freed"`
+}
+
+// stalePruneSnapshotID is seeded into the local index with no manifest
+// on the destination store, which is exactly what makes it stale.
+const stalePruneSnapshotID = "test-host_test_2026-04-01T09:00:00Z"
+
+// TestEntryPruneJSONStdoutIsExactlyOneDocument is the end-to-end
+// regression guard for issue #108: `vaultik prune --json | jq .` must
+// work with no other flags.
+//
+// It runs Entry over the process's real stdout descriptor, through
+// cobra and the fx graph, against a hermetic file:// destination store
+// — the same construction TestEntryJSONStdoutIsExactlyOneDocument uses
+// for `snapshot list`, with the pipe to jq replaced by a decoder.
+//
+// Both branches of the local-snapshot reconciliation are exercised
+// because the three stdout writes that broke this covered all of them:
+// one line per stale record and a summary when there were any, and a
+// "No stale local snapshots found." line when there were none. No input
+// avoided the contamination, so no single branch demonstrates the fix.
+//
+// Not parallel: it replaces os.Args, os.Stdout and the xdg globals.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout and the xdg globals
+func TestEntryPruneJSONStdoutIsExactlyOneDocument(t *testing.T) {
+	for _, testCase := range []struct {
+		name        string
+		seedStale   bool
+		description string
+	}{
+		{
+			name:        "no stale local records",
+			seedStale:   false,
+			description: "the empty-index branch used to print a 'No stale' line",
+		},
+		{
+			name:      "stale local records present",
+			seedStale: true,
+			description: "the removal branch used to print a line per record " +
+				"plus a summary",
+		},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			configPath := writeHermeticPruneConfig(t, testCase.seedStale)
+
+			previousArgs := os.Args
+
+			t.Cleanup(func() {
+				os.Args = previousArgs
+				rootFlags = RootFlags{}
+			})
+
+			os.Args = []string{
+				programName, flagConfig, configPath, cmdPrune, flagJSON,
+			}
+
+			stdout := captureProcessStdout(t, Entry)
+
+			requireExactlyOneJSONDocument(t, stdout)
+
+			var document pruneJSONDocument
+
+			require.NoError(t, json.Unmarshal([]byte(stdout), &document),
+				testCase.description)
+
+			// A destination store with no blobs has none to prune. The
+			// assertion that matters is the one above; this one keeps the
+			// test honest about which document it decoded.
+			assert.Equal(t, 0, document.BlobsFound)
+		})
+	}
+}
+
+// writeHermeticPruneConfig builds a config over a temp directory and, if
+// seedStale is set, creates the index database up front with one
+// snapshot record that has no counterpart on the destination store.
+// Returns the config path.
+func writeHermeticPruneConfig(t *testing.T, seedStale bool) string {
+	t.Helper()
+
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "config.yml")
+	indexPath := filepath.Join(dir, "index.sqlite")
+
+	contents := fmt.Sprintf(hermeticConfig,
+		filepath.Join(dir, "source"),
+		filepath.Join(dir, "store"),
+		indexPath)
+
+	require.NoError(t,
+		os.WriteFile(configPath, []byte(contents), configFileMode))
+
+	// The PID lock lives under xdg.DataHome, which xdg resolves at
+	// package init; point it at the temp dir so the test neither
+	// touches nor collides with the real one.
+	t.Setenv("XDG_DATA_HOME", filepath.Join(dir, "data"))
+	xdg.Reload()
+	t.Cleanup(xdg.Reload)
+
+	if seedStale {
+		seedStaleSnapshotRecord(t, indexPath)
+	}
+
+	return configPath
+}
+
+// seedStaleSnapshotRecord creates the index database at path and
+// inserts one completed snapshot into it. Nothing is written to the
+// destination store, so `prune` finds the record stale and removes it —
+// the branch that printed a line per record.
+func seedStaleSnapshotRecord(t *testing.T, path string) {
+	t.Helper()
+
+	ctx := context.Background()
+
+	db, err := database.New(ctx, path)
+	require.NoError(t, err)
+
+	defer func() { require.NoError(t, db.Close()) }()
+
+	startedAt := time.Date(2026, 4, 1, 9, 0, 0, 0, time.UTC)
+	completedAt := startedAt.Add(time.Minute)
+
+	snap := &database.Snapshot{
+		ID:             types.SnapshotID(stalePruneSnapshotID),
+		Hostname:       "test-host",
+		VaultikVersion: "test",
+		StartedAt:      startedAt,
+		CompletedAt:    &completedAt,
+	}
+
+	repos := database.NewRepositories(db)
+
+	err = repos.WithTx(ctx, func(ctx context.Context, tx *sql.Tx) error {
+		return repos.Snapshots.Create(ctx, tx, snap)
+	})
+	require.NoError(t, err)
+}

internal/cli/version.go

@@ -2,7 +2,7 @@ package cli
 
 import (
 	"fmt"
-	"os"
+	"io"
 	"runtime"
 
 	"github.com/spf13/cobra"
@@ -16,28 +16,35 @@ func NewVersionCommand() *cobra.Command {
 		Short: "Print version information",
 		Long:  `Print version, git commit, and build information for vaultik.`,
 		Args:  cobra.NoArgs,
-		Run: func(_ *cobra.Command, _ []string) {
-			_, _ = fmt.Fprintf(os.Stdout, "vaultik %s\n", globals.Version)
-			_, _ = fmt.Fprintf(os.Stdout, "  commit:     %s\n", globals.Commit)
-			_, _ = fmt.Fprintf(os.Stdout, "  build date: %s\n", globals.CommitDate)
-			_, _ = fmt.Fprintf(os.Stdout, "  go:         %s\n", runtime.Version())
-			_, _ = fmt.Fprintf(os.Stdout, "  os/arch:    %s/%s\n",
-				runtime.GOOS, runtime.GOARCH)
-			_, _ = fmt.Fprintf(os.Stdout, "  author:     %s\n", globals.Author)
-			_, _ = fmt.Fprintf(os.Stdout, "  homepage:   %s\n", globals.Homepage)
-			_, _ = fmt.Fprintf(os.Stdout, "  license:    %s\n", globals.License)
-
-			if globals.Version == "dev" {
-				_, _ = fmt.Fprintln(os.Stdout)
-				_, _ = fmt.Fprintln(os.Stdout,
-					"This is a development build (no version information embedded).")
-				_, _ = fmt.Fprintln(os.Stdout,
-					"Build a release binary with 'make vaultik' or download from")
-				_, _ = fmt.Fprintln(os.Stdout,
-					"https://sneak.berlin/go/vaultik for embedded version metadata.")
-			}
+		Run: func(cmd *cobra.Command, _ []string) {
+			writeVersion(cmd.OutOrStdout())
 		},
 	}
 
 	return cmd
 }
+
+// writeVersion prints the version report. It takes a writer rather than
+// using os.Stdout directly so the output can be asserted on in tests.
+func writeVersion(w io.Writer) {
+	_, _ = fmt.Fprintf(w, "vaultik %s\n", globals.Version)
+	_, _ = fmt.Fprintf(w, "  commit:     %s\n", globals.Commit)
+	_, _ = fmt.Fprintf(w, "  build date: %s\n", globals.CommitDate)
+	_, _ = fmt.Fprintf(w, "  go:         %s\n", runtime.Version())
+	_, _ = fmt.Fprintf(w, "  os/arch:    %s/%s\n", runtime.GOOS, runtime.GOARCH)
+	_, _ = fmt.Fprintf(w, "  author:     %s\n", globals.Author)
+	_, _ = fmt.Fprintf(w, "  homepage:   %s\n", globals.Homepage)
+	_, _ = fmt.Fprintf(w, "  license:    %s\n", globals.License)
+
+	if globals.IsDevVersion(globals.Version) {
+		_, _ = fmt.Fprintln(w)
+		_, _ = fmt.Fprintln(w,
+			"This is a development build: it was not built from a tagged")
+		_, _ = fmt.Fprintln(w,
+			"commit, so it carries no release version. Released binaries")
+		_, _ = fmt.Fprintf(w,
+			"are published at %s\n", globals.ReleasesURL)
+		_, _ = fmt.Fprintln(w,
+			"and report their tag on the first line above.")
+	}
+}

internal/cli/version_test.go

@@ -0,0 +1,77 @@
+package cli_test
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/vaultik/internal/cli"
+	"sneak.berlin/go/vaultik/internal/globals"
+)
+
+// runVersionCommand executes `vaultik version` with its output
+// captured, and returns what it printed.
+func runVersionCommand(t *testing.T) string {
+	t.Helper()
+
+	cmd := cli.NewVersionCommand()
+
+	var out bytes.Buffer
+
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{})
+
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("version command failed: %v", err)
+	}
+
+	return out.String()
+}
+
+// TestVersionCommandReportsBuildVersion checks that the first line of
+// the report is the version the binary was actually built with. The
+// test binary carries no -ldflags, so that is the "dev" default -- the
+// same string an untagged `make vaultik` build stamps a prefix of.
+func TestVersionCommandReportsBuildVersion(t *testing.T) {
+	t.Parallel()
+
+	out := runVersionCommand(t)
+
+	wantFirst := "vaultik " + globals.Version
+	if first, _, _ := strings.Cut(out, "\n"); first != wantFirst {
+		t.Errorf("first line = %q, want %q", first, wantFirst)
+	}
+
+	if !strings.Contains(out, "commit:") {
+		t.Error("output does not report the commit")
+	}
+}
+
+// TestVersionCommandFlagsDevelopmentBuild is the regression test for
+// the thing this command exists to prevent: a build that is not a
+// release must say so. The notice used to be gated on the version
+// being exactly "dev", so once untagged builds started carrying their
+// commit sha it would have gone silent and an unreleased binary would
+// have looked like a release.
+func TestVersionCommandFlagsDevelopmentBuild(t *testing.T) {
+	t.Parallel()
+
+	if !globals.IsDevVersion(globals.Version) {
+		t.Skipf("test binary was stamped with release version %q",
+			globals.Version)
+	}
+
+	out := runVersionCommand(t)
+
+	if !strings.Contains(out, "development build") {
+		t.Errorf("dev build did not print the development-build notice:\n%s",
+			out)
+	}
+
+	if !strings.Contains(out, globals.ReleasesURL) {
+		t.Errorf("development-build notice does not point at %s:\n%s",
+			globals.ReleasesURL, out)
+	}
+}

internal/database/snapshots.go

@@ -609,43 +609,9 @@ func (r *SnapshotRepository) GetIncompleteByHostname(
 		}
 	}()
 
-	var snapshots []*Snapshot
-
-	for rows.Next() {
-		var (
-			snapshot        Snapshot
-			startedAtUnix   int64
-			completedAtUnix *int64
-		)
-
-		err := rows.Scan(
-			&snapshot.ID,
-			&snapshot.Hostname,
-			&snapshot.VaultikVersion,
-			&snapshot.VaultikGitRevision,
-			&startedAtUnix,
-			&completedAtUnix,
-			&snapshot.FileCount,
-			&snapshot.ChunkCount,
-			&snapshot.BlobCount,
-			&snapshot.TotalSize,
-			&snapshot.BlobSize,
-			&snapshot.CompressionRatio,
-		)
-		if err != nil {
-			return nil, fmt.Errorf("scanning snapshot: %w", err)
-		}
-
-		snapshot.StartedAt = time.Unix(startedAtUnix, 0).UTC()
-		if completedAtUnix != nil {
-			t := time.Unix(*completedAtUnix, 0).UTC()
-			snapshot.CompletedAt = &t
-		}
-
-		snapshots = append(snapshots, &snapshot)
-	}
-
-	return snapshots, rows.Err()
+	// Same column set as every other multi-row snapshot query, so the
+	// shared scanner applies — including its timestamp normalization.
+	return r.scanSnapshotRows(rows)
 }
 
 // Delete removes a snapshot record
@@ -764,9 +730,16 @@ func (r *SnapshotRepository) scanSnapshotRows(rows *sql.Rows) ([]*Snapshot, erro
 			return nil, fmt.Errorf("scanning snapshot: %w", err)
 		}
 
-		snapshot.StartedAt = time.Unix(startedAtUnix, 0)
+		// UTC, matching every other snapshot scanner in this file. The
+		// column holds a bare Unix second, so the zone is a decode
+		// choice rather than stored data, and callers render these
+		// timestamps through zone-less format strings alongside
+		// timestamps read from remote manifests. Decoding in the host's
+		// local zone here would put two different wall clocks in one
+		// column.
+		snapshot.StartedAt = time.Unix(startedAtUnix, 0).UTC()
 		if completedAtUnix != nil {
-			t := time.Unix(*completedAtUnix, 0)
+			t := time.Unix(*completedAtUnix, 0).UTC()
 			snapshot.CompletedAt = &t
 		}
 

internal/database/snapshots_test.go

@@ -191,6 +191,119 @@ func TestSnapshotRepositoryListRecent(t *testing.T) {
 	}
 }
 
+// TestSnapshotTimestampsDecodeAsUTC pins the zone every snapshot reader
+// returns. started_at and completed_at are stored as bare Unix seconds,
+// so the zone is a decode choice, and callers (notably `snapshot list`)
+// render these timestamps through zone-less format strings in the same
+// column as timestamps read from remote manifests, which are always
+// UTC. If one reader decodes in the host's local zone, that column
+// silently shows two different wall clocks for the same instant.
+//
+// The assertions compare *time.Location pointers, so this fails on a
+// UTC host too: time.Unix returns time.Local, which is never the same
+// Location value as time.UTC no matter what the host's offset is.
+func TestSnapshotTimestampsDecodeAsUTC(t *testing.T) {
+	t.Parallel()
+
+	db, cleanup := setupTestDB(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	repo := database.NewSnapshotRepository(db)
+
+	startedAt := time.Date(2026, 3, 1, 10, 0, 0, 0, time.UTC)
+	completedAt := startedAt.Add(time.Minute)
+
+	completed := &database.Snapshot{
+		ID:             types.SnapshotID("testhost_home_2026-03-01T10:00:00Z"),
+		Hostname:       testHostname,
+		VaultikVersion: testVersion,
+		StartedAt:      startedAt,
+		CompletedAt:    &completedAt,
+	}
+
+	err := repo.Create(ctx, nil, completed)
+	if err != nil {
+		t.Fatalf("failed to create completed snapshot: %v", err)
+	}
+
+	// An incomplete row as well, so the scanner shared by the two
+	// GetIncomplete* readers is covered with a nil completed_at too.
+	incomplete := &database.Snapshot{
+		ID:             types.SnapshotID("testhost_home_2026-03-02T10:00:00Z"),
+		Hostname:       testHostname,
+		VaultikVersion: testVersion,
+		StartedAt:      startedAt.Add(time.Hour),
+		CompletedAt:    nil,
+	}
+
+	err = repo.Create(ctx, nil, incomplete)
+	if err != nil {
+		t.Fatalf("failed to create incomplete snapshot: %v", err)
+	}
+
+	byID, err := repo.GetByID(ctx, completed.ID.String())
+	if err != nil {
+		t.Fatalf("failed to get snapshot by id: %v", err)
+	}
+
+	recent, err := repo.ListRecent(ctx, 10)
+	if err != nil {
+		t.Fatalf("failed to list recent snapshots: %v", err)
+	}
+
+	incompletes, err := repo.GetIncompleteSnapshots(ctx)
+	if err != nil {
+		t.Fatalf("failed to list incomplete snapshots: %v", err)
+	}
+
+	byHost, err := repo.GetIncompleteByHostname(ctx, testHostname)
+	if err != nil {
+		t.Fatalf("failed to list incomplete snapshots by hostname: %v", err)
+	}
+
+	read := make([]*database.Snapshot, 0,
+		1+len(recent)+len(incompletes)+len(byHost))
+	read = append(read, byID)
+	read = append(read, recent...)
+	read = append(read, incompletes...)
+	read = append(read, byHost...)
+
+	if len(read) < 5 {
+		t.Fatalf("expected every reader to return rows, got %d", len(read))
+	}
+
+	assertTimestampsAreUTC(t, read)
+
+	// And the wall clock is the UTC one, not the host's rendering of it.
+	rendered := byID.StartedAt.Format("2006-01-02 15:04:05")
+	if rendered != "2026-03-01 10:00:00" {
+		t.Errorf("started_at rendered as %q, want the UTC wall clock", rendered)
+	}
+}
+
+// assertTimestampsAreUTC fails for any snapshot whose timestamps did not
+// decode in UTC. It compares *time.Location pointers rather than
+// offsets, so it is equally strict on a host whose local zone happens to
+// be UTC: time.Unix returns time.Local, which is never the same Location
+// value as time.UTC.
+func assertTimestampsAreUTC(t *testing.T, snapshots []*database.Snapshot) {
+	t.Helper()
+
+	for _, snapshot := range snapshots {
+		if snapshot.StartedAt.Location() != time.UTC {
+			t.Errorf("snapshot %s: started_at decoded in %s, want UTC",
+				snapshot.ID, snapshot.StartedAt.Location())
+		}
+
+		if snapshot.CompletedAt != nil &&
+			snapshot.CompletedAt.Location() != time.UTC {
+			t.Errorf("snapshot %s: completed_at decoded in %s, want UTC",
+				snapshot.ID, snapshot.CompletedAt.Location())
+		}
+	}
+}
+
 func TestSnapshotRepositoryNotFound(t *testing.T) {
 	t.Parallel()
 

internal/globals/globals.go

@@ -3,14 +3,23 @@
 package globals
 
 import (
+	"strings"
 	"time"
 )
 
 // Appname is the application name, populated from main().
 var Appname = "vaultik" //nolint:gochecknoglobals // set via -ldflags at build time
 
+// DevVersion is the version a binary reports when it was not built
+// from a tagged commit. script/version emits either this exact string
+// (outside a git checkout) or this string followed by "-" and the
+// commit it was built from, and goreleaser's snapshot template matches
+// that shape. It is deliberately not a number: a build that is not a
+// release must not name itself like one.
+const DevVersion = "dev"
+
 // Version is the application version, populated from main().
-var Version = "dev" //nolint:gochecknoglobals // set via -ldflags at build time
+var Version = DevVersion //nolint:gochecknoglobals // set via -ldflags at build time
 
 // Commit is the git commit hash, populated from main().
 var Commit = "unknown" //nolint:gochecknoglobals // set via -ldflags at build time
@@ -24,6 +33,9 @@ const Author = "Jeffrey Paul <sneak@sneak.berlin>"
 // Homepage is the canonical URL for vaultik.
 const Homepage = "https://sneak.berlin/go/vaultik"
 
+// ReleasesURL is where tagged release artifacts are published.
+const ReleasesURL = "https://git.eeqj.de/sneak/vaultik/releases"
+
 // License is the SPDX identifier for the project license.
 const License = "MIT"
 
@@ -47,6 +59,21 @@ func New() (*Globals, error) {
 	}, nil
 }
 
+// IsDevVersion reports whether v names a development build rather than
+// a release. Both "dev" and "dev-<sha>" (and its "-dirty" variant)
+// count: a caller that compares against "dev" exactly would treat every
+// commit-stamped development build as a release.
+//
+// The empty string counts too. Nothing that knows its version reports
+// no version, so an empty Version means the stamping failed, and the
+// safe reading of "we could not establish that this is a release" is
+// that it is not one. The Makefile refuses to build at all in that
+// case; this is the second line of defence, for a binary linked by
+// something other than the Makefile.
+func IsDevVersion(v string) bool {
+	return v == "" || v == DevVersion || strings.HasPrefix(v, DevVersion+"-")
+}
+
 // shortCommitLen is the number of commit-hash characters ShortCommit keeps.
 const shortCommitLen = 12
 

internal/globals/globals_test.go

@@ -32,3 +32,56 @@ func TestGlobalsNew(t *testing.T) {
 		t.Error("Commit should not be empty")
 	}
 }
+
+// TestIsDevVersion covers the boundary that matters: everything
+// script/version and goreleaser's snapshot template can emit for an
+// untagged build must be recognised as a development build, and a real
+// tag must not be. A plain equality check against "dev" used to decide
+// this, which classified every commit-stamped dev build as a release.
+func TestIsDevVersion(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		version string
+		want    bool
+	}{
+		// What an untagged build produces.
+		{"dev", true},
+		{"dev-b6e4a218a39e", true},
+		{"dev-b6e4a218a39e-dirty", true},
+		// What a tagged build produces (script/version strips the
+		// leading "v", matching goreleaser's .Version).
+		{"1.0.0", false},
+		{"0.1.0", false},
+		{"1.0.0-rc.1", false},
+		{"v1.0.0", false},
+		// A release must not be mistaken for a dev build just because
+		// the string happens to contain "dev".
+		{"1.0.0-dev", false},
+		{"developer", false},
+		// A binary with no version string at all did not get stamped,
+		// which is a build failure, not a release. It must never print
+		// as one. The Makefile refuses to build when script/version
+		// yields nothing; this covers a binary linked some other way.
+		{"", true},
+	}
+
+	for _, tc := range cases {
+		if got := globals.IsDevVersion(tc.version); got != tc.want {
+			t.Errorf("IsDevVersion(%q) = %v, want %v", tc.version, got, tc.want)
+		}
+	}
+}
+
+// TestDefaultVersionIsDev pins the linker-flag contract: an unstamped
+// binary (no -ldflags at all, which is what `go build ./...` and `go
+// install` produce) must report itself as a development build rather
+// than as some default release number.
+func TestDefaultVersionIsDev(t *testing.T) {
+	t.Parallel()
+
+	if !globals.IsDevVersion(globals.DevVersion) {
+		t.Errorf("DevVersion %q is not recognised as a dev version",
+			globals.DevVersion)
+	}
+}

internal/log/log.go

@@ -1,5 +1,9 @@
 // Package log provides the application-wide structured logger: slog
-// with a colorized TTY handler on terminals and JSON output otherwise.
+// writing to stderr, with a colorized TTY handler when stderr is a
+// terminal and JSON output otherwise.
+//
+// Everything this package emits is a diagnostic, so it all goes to
+// stderr. stdout belongs to the output the user asked for.
 package log //nolint:revive,nolintlint // stdlib log unused here; see #76
 
 import (
@@ -69,13 +73,27 @@ func Initialize(cfg Config) {
 		Level: level,
 	}
 
-	// Check if stdout is a TTY.
-	if term.IsTerminal(int(os.Stdout.Fd())) {
+	// Diagnostics go to stderr, never to stdout. stdout is reserved for
+	// the output the user asked for: every --json subcommand writes its
+	// document there, and WARN/ERROR are never suppressed, so a logger
+	// on stdout puts log records inside that document and makes it
+	// unparseable. A config file with group- or world-readable
+	// permissions is enough to trigger it (see internal/config), so this
+	// was not a theoretical collision.
+	//
+	// The format is chosen by the TTY-ness of the stream the records
+	// actually land on. AGENTS.md policy 9 says "if stdout is not a
+	// terminal, emit jsonl"; it says stdout because that is where logs
+	// used to go, and the property it is really asking for is that
+	// output nobody is watching be machine-readable. Testing stdout here
+	// would colorize records on a redirected stderr whenever stdout
+	// happened to be a terminal, and vice versa.
+	if term.IsTerminal(int(os.Stderr.Fd())) {
 		// Use colorized TTY handler
-		logger = slog.New(NewTTYHandler(os.Stdout, opts))
+		logger = slog.New(NewTTYHandler(os.Stderr, opts))
 	} else {
 		// Use JSON format for non-TTY output
-		logger = slog.New(slog.NewJSONHandler(os.Stdout, opts))
+		logger = slog.New(slog.NewJSONHandler(os.Stderr, opts))
 	}
 
 	// Set as default logger

internal/log/tty_handler.go

@@ -5,10 +5,34 @@ import (
 	"fmt"
 	"io"
 	"log/slog"
+	"strings"
 	"sync"
 	"time"
 )
 
+// groupSeparator joins an open group path to an attribute key. This
+// format has no nesting, so a group becomes a dotted key prefix:
+// slog.New(h).WithGroup("db").With("rows", 3) renders "db.rows=3".
+const groupSeparator = "."
+
+// bytesAttrKey is the attribute key whose int64 value is rendered as a
+// human-readable byte count rather than a bare number. Keys reaching
+// writeAttr are group-qualified, so the match is made against the final
+// dot-separated segment: without that, a "bytes" attribute logged under
+// an open group would arrive as "transfer.bytes" and silently lose its
+// formatting.
+const bytesAttrKey = "bytes"
+
+// isBytesAttr reports whether a group-qualified attribute key names the
+// byte-count attribute, i.e. whether its last segment is bytesAttrKey.
+func isBytesAttr(key string) bool {
+	if idx := strings.LastIndex(key, groupSeparator); idx >= 0 {
+		key = key[idx+len(groupSeparator):]
+	}
+
+	return key == bytesAttrKey
+}
+
 // ANSI color codes
 const (
 	colorReset  = "\033[0m"
@@ -22,10 +46,26 @@ const (
 )
 
 // TTYHandler is a custom slog handler for TTY output with colors.
+//
+// A handler and the handlers derived from it via WithAttrs/WithGroup
+// all write to the same stream, so they share one mutex; that is why mu
+// is a pointer. A value mutex would give every derived handler its own
+// lock and stop serializing writes to the stream they have in common.
 type TTYHandler struct {
 	opts slog.HandlerOptions
-	mu   sync.Mutex
+	mu   *sync.Mutex
 	out  io.Writer
+
+	// attrs are the attributes accumulated through WithAttrs, emitted
+	// ahead of each record's own attributes. Their keys already carry
+	// the group path that was open when they were added, so no
+	// qualification happens at write time.
+	attrs []slog.Attr
+
+	// groups is the group path opened by WithGroup, applied as a key
+	// prefix to attributes that arrive later — both on a record and
+	// through a further WithAttrs.
+	groups []string
 }
 
 // NewTTYHandler creates a new TTY handler with colored output.
@@ -37,6 +77,7 @@ func NewTTYHandler(out io.Writer, opts *slog.HandlerOptions) *TTYHandler {
 	return &TTYHandler{
 		out:  out,
 		opts: *opts,
+		mu:   &sync.Mutex{},
 	}
 }
 
@@ -81,29 +122,19 @@ func (h *TTYHandler) Handle(_ context.Context, r slog.Record) error {
 		levelColor, level, colorReset,
 		colorBold, r.Message, colorReset)
 
-	// Print attributes
-	r.Attrs(func(a slog.Attr) bool {
-		value := a.Value.String()
-		// Special handling for certain attribute types
-		switch a.Value.Kind() {
-		case slog.KindDuration:
-			if d, ok := a.Value.Any().(time.Duration); ok {
-				value = formatDuration(d)
-			}
-		case slog.KindInt64:
-			if a.Key == "bytes" {
-				value = formatBytes(a.Value.Int64())
-			}
-		case slog.KindAny, slog.KindBool, slog.KindFloat64, slog.KindString,
-			slog.KindTime, slog.KindUint64, slog.KindGroup, slog.KindLogValuer:
-			// Plain string form above is already correct for these kinds.
-		default:
-			// Future kinds also use the plain string form.
-		}
+	// Attributes carried by the handler come first, then the record's
+	// own. Handler attributes were qualified when they were added; the
+	// record's are qualified now, against whatever group path is open.
+	for _, a := range h.attrs {
+		h.writeAttr(a)
+	}
 
-		_, _ = fmt.Fprintf(h.out, " %s%s%s=%s%s%s",
-			colorCyan, a.Key, colorReset,
-			colorBlue, value, colorReset)
+	prefix := strings.Join(h.groups, groupSeparator)
+
+	r.Attrs(func(a slog.Attr) bool {
+		for _, flat := range appendAttr(nil, prefix, a) {
+			h.writeAttr(flat)
+		}
 
 		return true
 	})
@@ -113,14 +144,125 @@ func (h *TTYHandler) Handle(_ context.Context, r slog.Record) error {
 	return nil
 }
 
-// WithAttrs returns a new handler with the given attributes.
-func (h *TTYHandler) WithAttrs(_ []slog.Attr) slog.Handler {
-	return h // Simplified for now
+// appendAttr flattens a into dst, folding prefix into its key and
+// expanding group values into further dotted keys. Following the
+// slog.Handler contract: an empty Attr is dropped, a group with no
+// attributes is dropped, and a group with an empty key is inlined into
+// its parent rather than contributing a level.
+func appendAttr(dst []slog.Attr, prefix string, a slog.Attr) []slog.Attr {
+	a.Value = a.Value.Resolve()
+
+	if a.Equal(slog.Attr{}) {
+		return dst
+	}
+
+	key := a.Key
+
+	switch {
+	case prefix == "":
+		// key stands alone.
+	case key == "":
+		key = prefix
+	default:
+		key = prefix + groupSeparator + key
+	}
+
+	if a.Value.Kind() != slog.KindGroup {
+		return append(dst, slog.Attr{Key: key, Value: a.Value})
+	}
+
+	for _, member := range a.Value.Group() {
+		dst = appendAttr(dst, key, member)
+	}
+
+	return dst
 }
 
-// WithGroup returns a new handler with the given group name.
-func (h *TTYHandler) WithGroup(_ string) slog.Handler {
-	return h // Simplified for now
+// WithAttrs returns a new handler that emits attrs on every record it
+// handles, in addition to whatever the handler already carried. Keys
+// are qualified by the group path open at the time of the call, so
+// WithGroup("db").WithAttrs(rows=3) later renders "db.rows=3".
+//
+// The receiver is not modified.
+func (h *TTYHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	if len(attrs) == 0 {
+		return h
+	}
+
+	prefix := strings.Join(h.groups, groupSeparator)
+	next := h.clone()
+
+	for _, a := range attrs {
+		next.attrs = appendAttr(next.attrs, prefix, a)
+	}
+
+	return next
+}
+
+// WithGroup returns a new handler that qualifies every subsequent
+// attribute key with name. This format is a single line with nowhere to
+// nest, so grouping is rendered as a dotted key prefix: after
+// WithGroup("db"), an attribute "rows" is emitted as "db.rows".
+//
+// An empty name returns the receiver unchanged, per the slog.Handler
+// contract. The receiver is not modified.
+func (h *TTYHandler) WithGroup(name string) slog.Handler {
+	if name == "" {
+		return h
+	}
+
+	next := h.clone()
+	next.groups = append(next.groups, name)
+
+	return next
+}
+
+// clone returns a copy of h that shares its output stream and mutex but
+// owns its attribute and group slices.
+//
+// The slices are copied rather than resliced on purpose. slog permits
+// one handler to be derived from concurrently, and two derivations that
+// appended into a shared backing array would each overwrite the other's
+// attribute — a data race with a silent wrong-output failure mode.
+func (h *TTYHandler) clone() *TTYHandler {
+	next := &TTYHandler{
+		opts:   h.opts,
+		mu:     h.mu,
+		out:    h.out,
+		attrs:  make([]slog.Attr, len(h.attrs), len(h.attrs)+1),
+		groups: make([]string, len(h.groups), len(h.groups)+1),
+	}
+
+	copy(next.attrs, h.attrs)
+	copy(next.groups, h.groups)
+
+	return next
+}
+
+// writeAttr renders one already-flattened, already-qualified attribute
+// as " key=value". Callers hold h.mu.
+func (h *TTYHandler) writeAttr(a slog.Attr) {
+	value := a.Value.String()
+	// Special handling for certain attribute types
+	switch a.Value.Kind() {
+	case slog.KindDuration:
+		if d, ok := a.Value.Any().(time.Duration); ok {
+			value = formatDuration(d)
+		}
+	case slog.KindInt64:
+		if isBytesAttr(a.Key) {
+			value = formatBytes(a.Value.Int64())
+		}
+	case slog.KindAny, slog.KindBool, slog.KindFloat64, slog.KindString,
+		slog.KindTime, slog.KindUint64, slog.KindGroup, slog.KindLogValuer:
+		// Plain string form above is already correct for these kinds.
+	default:
+		// Future kinds also use the plain string form.
+	}
+
+	_, _ = fmt.Fprintf(h.out, " %s%s%s=%s%s%s",
+		colorCyan, a.Key, colorReset,
+		colorBlue, value, colorReset)
 }
 
 // formatDuration formats a duration in a human-readable way

internal/log/tty_handler_test.go

@@ -0,0 +1,422 @@
+package log_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"math"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/log"
+)
+
+// ansiEscape matches the SGR sequences TTYHandler wraps every field in.
+// Stripping them is what lets a test compare TTYHandler's rendering with
+// slog.JSONHandler's.
+var ansiEscape = regexp.MustCompile(`\x1b\[[0-9;]*m`)
+
+// countKey is an attribute key reused across the comparison cases.
+const countKey = "count"
+
+// debugHandlerOptions enables every level, so a test never has to reason
+// about the default level while reasoning about attributes.
+func debugHandlerOptions() *slog.HandlerOptions {
+	return &slog.HandlerOptions{Level: slog.LevelDebug}
+}
+
+// ttyAttrs renders one record through a TTYHandler and returns its
+// attributes as key -> value, with color stripped.
+//
+// TTYHandler emits " key=value" per attribute after the message, and the
+// message itself is the last thing before the first attribute, so
+// splitting on spaces and keeping the tokens containing "=" recovers the
+// attribute set. Test values below therefore avoid spaces and "=".
+func ttyAttrs(t *testing.T, derive func(*slog.Logger) *slog.Logger,
+	msg string, args ...any,
+) map[string]string {
+	t.Helper()
+
+	var buf bytes.Buffer
+
+	logger := slog.New(log.NewTTYHandler(&buf, debugHandlerOptions()))
+	derive(logger).Info(msg, args...)
+
+	line := ansiEscape.ReplaceAllString(buf.String(), "")
+	attrs := make(map[string]string)
+
+	for token := range strings.FieldsSeq(line) {
+		key, value, found := strings.Cut(token, "=")
+		if !found {
+			continue
+		}
+
+		attrs[key] = value
+	}
+
+	return attrs
+}
+
+// jsonAttrs renders one record through slog.JSONHandler and returns its
+// attributes flattened to the same dotted-key form TTYHandler uses, so
+// the two are directly comparable. The built-in time/level/msg fields
+// are dropped: they are the record, not its attributes.
+func jsonAttrs(t *testing.T, derive func(*slog.Logger) *slog.Logger,
+	msg string, args ...any,
+) map[string]string {
+	t.Helper()
+
+	var buf bytes.Buffer
+
+	logger := slog.New(slog.NewJSONHandler(&buf, debugHandlerOptions()))
+	derive(logger).Info(msg, args...)
+
+	var decoded map[string]any
+
+	require.NoError(t, json.Unmarshal(buf.Bytes(), &decoded))
+
+	delete(decoded, slog.TimeKey)
+	delete(decoded, slog.LevelKey)
+	delete(decoded, slog.MessageKey)
+
+	attrs := make(map[string]string)
+	flattenJSON(attrs, "", decoded)
+
+	return attrs
+}
+
+// flattenJSON turns JSONHandler's nested group objects into the dotted
+// keys TTYHandler writes.
+func flattenJSON(dst map[string]string, prefix string, src map[string]any) {
+	for key, value := range src {
+		full := key
+		if prefix != "" {
+			full = prefix + "." + key
+		}
+
+		nested, ok := value.(map[string]any)
+		if ok {
+			flattenJSON(dst, full, nested)
+
+			continue
+		}
+
+		dst[full] = valueString(value)
+	}
+}
+
+// valueString renders a decoded JSON scalar the way slog.Value.String
+// renders the corresponding Go value, so the two handlers' outputs can
+// be compared as strings. encoding/json decodes every number as
+// float64, so an integral one is rendered back as an integer — which is
+// what the Go value that produced it was.
+func valueString(v any) string {
+	switch typed := v.(type) {
+	case string:
+		return typed
+	case bool:
+		return strconv.FormatBool(typed)
+	case float64:
+		if typed == math.Trunc(typed) {
+			return strconv.FormatInt(int64(typed), 10)
+		}
+
+		return strconv.FormatFloat(typed, 'g', -1, 64)
+	default:
+		return fmt.Sprint(v)
+	}
+}
+
+// TestTTYHandlerWithAttrsEmitsAttributes is the direct regression test
+// for the reported defect: WithAttrs discarded its argument, so an
+// attribute attached to a logger never reached the output.
+func TestTTYHandlerWithAttrsEmitsAttributes(t *testing.T) {
+	t.Parallel()
+
+	attrs := ttyAttrs(t, func(l *slog.Logger) *slog.Logger {
+		return l.With("key", "value")
+	}, "hello")
+
+	assert.Equal(t, "value", attrs["key"],
+		"an attribute attached with With must appear on every record")
+}
+
+// TestTTYHandlerWithAttrsPersistsAcrossRecords checks that the
+// attributes are retained rather than emitted once. A handler that
+// stored them but consumed them would pass the test above.
+func TestTTYHandlerWithAttrsPersistsAcrossRecords(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+
+	logger := slog.New(log.NewTTYHandler(&buf, debugHandlerOptions())).
+		With("request", "abc123")
+
+	logger.Info("first")
+	logger.Info("second")
+
+	plain := ansiEscape.ReplaceAllString(buf.String(), "")
+	lines := strings.Split(strings.TrimSuffix(plain, "\n"), "\n")
+
+	require.Len(t, lines, 2)
+
+	for _, line := range lines {
+		assert.Contains(t, line, "request=abc123")
+	}
+}
+
+// TestTTYHandlerWithGroupQualifiesKeys checks that WithGroup does
+// something real rather than being discarded. This format has no
+// nesting, so grouping shows up as a dotted key prefix.
+func TestTTYHandlerWithGroupQualifiesKeys(t *testing.T) {
+	t.Parallel()
+
+	attrs := ttyAttrs(t, func(l *slog.Logger) *slog.Logger {
+		return l.WithGroup("db").With("rows", 3)
+	}, "queried", "table", "chunks")
+
+	assert.Equal(t, "3", attrs["db.rows"],
+		"an attribute added under a group must be qualified by it")
+	assert.Equal(t, "chunks", attrs["db.table"],
+		"a record attribute must also be qualified by the open group")
+	assert.NotContains(t, attrs, "rows")
+}
+
+// TestTTYHandlerByteFormattingSurvivesGrouping guards the interaction
+// between the two features. The human-readable rendering of a "bytes"
+// attribute is selected by comparing the key, and keys reaching that
+// comparison are group-qualified, so a "bytes" attribute logged under an
+// open group arrived as "transfer.bytes" and fell back to a bare number.
+// No caller groups a byte count today, which is exactly why this needs a
+// test rather than a bug report.
+func TestTTYHandlerByteFormattingSurvivesGrouping(t *testing.T) {
+	t.Parallel()
+
+	const oneAndAHalfKiB = 1536
+
+	for name, testCase := range map[string]struct {
+		derive func(*slog.Logger) *slog.Logger
+		key    string
+	}{
+		"ungrouped": {
+			derive: func(l *slog.Logger) *slog.Logger { return l },
+			key:    "bytes",
+		},
+		"grouped": {
+			derive: func(l *slog.Logger) *slog.Logger {
+				return l.WithGroup("transfer")
+			},
+			key: "transfer.bytes",
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var buf bytes.Buffer
+
+			logger := slog.New(log.NewTTYHandler(&buf, debugHandlerOptions()))
+			testCase.derive(logger).Info("uploaded", "bytes", oneAndAHalfKiB)
+
+			line := ansiEscape.ReplaceAllString(buf.String(), "")
+
+			assert.Contains(t, line, testCase.key+"=1.5 KB",
+				"a byte count must be human-readable however it is qualified")
+			assert.NotContains(t, line, strconv.Itoa(oneAndAHalfKiB),
+				"the raw number must not survive the formatting")
+		})
+	}
+}
+
+// TestTTYHandlerMatchesJSONHandlerAttributes is the drift guard. The
+// handler is chosen by TTY-ness, so a difference between these two is
+// invisible in whichever environment the developer is not in — which is
+// how the original defect survived: attributes vanished on a terminal
+// and were correct in CI.
+func TestTTYHandlerMatchesJSONHandlerAttributes(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name   string
+		derive func(*slog.Logger) *slog.Logger
+		args   []any
+	}{
+		{
+			name:   "record attributes only",
+			derive: func(l *slog.Logger) *slog.Logger { return l },
+			args:   []any{"path", "/etc/vaultik", countKey, 7},
+		},
+		{
+			name: "handler attributes",
+			derive: func(l *slog.Logger) *slog.Logger {
+				return l.With("host", "alpha")
+			},
+			args: []any{countKey, 7},
+		},
+		{
+			name: "handler attributes accumulate",
+			derive: func(l *slog.Logger) *slog.Logger {
+				return l.With("host", "alpha").With("snapshot", "s1")
+			},
+			args: []any{countKey, 7},
+		},
+		{
+			name: "group qualifies later attributes",
+			derive: func(l *slog.Logger) *slog.Logger {
+				return l.WithGroup("db").With("rows", 3)
+			},
+			args: []any{"table", "chunks"},
+		},
+		{
+			name: "nested groups",
+			derive: func(l *slog.Logger) *slog.Logger {
+				return l.WithGroup("outer").WithGroup("inner").
+					With("leaf", "v")
+			},
+			args: []any{"other", "w"},
+		},
+		{
+			name: "attributes before and after a group",
+			derive: func(l *slog.Logger) *slog.Logger {
+				return l.With("top", "t").WithGroup("g").With("in", "i")
+			},
+			args: []any{"rec", "r"},
+		},
+		{
+			name:   "inline group value on the record",
+			derive: func(l *slog.Logger) *slog.Logger { return l },
+			args: []any{slog.Group("net",
+				slog.String("proto", "s3"), slog.Int("retries", 2))},
+		},
+	}
+
+	for _, testCase := range cases {
+		t.Run(testCase.name, func(t *testing.T) {
+			t.Parallel()
+
+			tty := ttyAttrs(t, testCase.derive, "message", testCase.args...)
+			js := jsonAttrs(t, testCase.derive, "message", testCase.args...)
+
+			assert.Equal(t, sortedKeys(js), sortedKeys(tty),
+				"TTY and JSON handlers must emit the same attribute keys")
+			assert.Equal(t, js, tty,
+				"TTY and JSON handlers must emit the same attribute values")
+		})
+	}
+}
+
+// sortedKeys returns m's keys in order, for a stable comparison message.
+func sortedKeys(m map[string]string) []string {
+	keys := make([]string, 0, len(m))
+	for key := range m {
+		keys = append(keys, key)
+	}
+
+	sort.Strings(keys)
+
+	return keys
+}
+
+// TestTTYHandlerWithAttrsDoesNotMutateReceiver checks that deriving does
+// not write through to the parent or to a sibling. slog permits a
+// handler to be shared, so a WithAttrs that appended into the receiver's
+// state would leak attributes between unrelated loggers.
+func TestTTYHandlerWithAttrsDoesNotMutateReceiver(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+
+	base := slog.New(log.NewTTYHandler(&buf, debugHandlerOptions()))
+	first := base.With("branch", "one")
+	second := base.With("branch", "two")
+
+	base.Info("base")
+	first.Info("first")
+	second.Info("second")
+
+	plain := ansiEscape.ReplaceAllString(buf.String(), "")
+	lines := strings.Split(strings.TrimSuffix(plain, "\n"), "\n")
+
+	require.Len(t, lines, 3)
+
+	assert.NotContains(t, lines[0], "branch=",
+		"deriving must not add attributes to the handler derived from")
+	assert.Contains(t, lines[1], "branch=one")
+	assert.NotContains(t, lines[1], "branch=two")
+	assert.Contains(t, lines[2], "branch=two")
+	assert.NotContains(t, lines[2], "branch=one")
+}
+
+// TestTTYHandlerConcurrentDerivation exercises the same handler being
+// derived from and written through by several goroutines at once, which
+// is what slog permits and what a mutating WithAttrs would make a data
+// race. Run under -race by script/test.
+func TestTTYHandlerConcurrentDerivation(t *testing.T) {
+	t.Parallel()
+
+	const workers = 16
+
+	var buf bytes.Buffer
+
+	base := slog.New(log.NewTTYHandler(&buf, debugHandlerOptions())).
+		With("shared", "yes")
+
+	var group sync.WaitGroup
+
+	group.Add(workers)
+
+	for worker := range workers {
+		go func() {
+			defer group.Done()
+
+			base.With("worker", worker).
+				WithGroup("g").
+				With("nested", worker).
+				Info("concurrent")
+		}()
+	}
+
+	group.Wait()
+
+	plain := ansiEscape.ReplaceAllString(buf.String(), "")
+	lines := strings.Split(strings.TrimSuffix(plain, "\n"), "\n")
+
+	require.Len(t, lines, workers)
+
+	for _, line := range lines {
+		assert.Contains(t, line, "shared=yes")
+		assert.Contains(t, line, "worker=")
+		assert.Contains(t, line, "g.nested=")
+	}
+}
+
+// TestTTYHandlerEmptyGroupAndAttrsAreNoOps covers the slog.Handler
+// contract corners: WithGroup("") and WithAttrs(nil) change nothing, and
+// an empty Attr is dropped rather than rendered as "=".
+func TestTTYHandlerEmptyGroupAndAttrsAreNoOps(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+
+	handler := log.NewTTYHandler(&buf, debugHandlerOptions())
+
+	assert.Same(t, handler, handler.WithGroup(""),
+		"an empty group name must not open a group")
+	assert.Same(t, handler, handler.WithAttrs(nil),
+		"deriving with no attributes must not allocate a handler")
+
+	slog.New(handler).LogAttrs(context.Background(), slog.LevelInfo, "msg",
+		slog.Attr{}, slog.String("kept", "yes"))
+
+	plain := ansiEscape.ReplaceAllString(buf.String(), "")
+
+	assert.Contains(t, plain, "kept=yes")
+	assert.NotContains(t, plain, " =")
+}

internal/log/with_test.go

@@ -0,0 +1,64 @@
+//nolint:testpackage // needs the package logger; see TestWithAttributesReachTTYOutput
+package log //nolint:revive,nolintlint // stdlib log unused here; see #76
+
+import (
+	"bytes"
+	"log/slog"
+	"regexp"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// withTestANSIEscape matches the SGR sequences TTYHandler emits.
+var withTestANSIEscape = regexp.MustCompile(`\x1b\[[0-9;]*m`)
+
+// TestWithAttributesReachTTYOutput exercises the exported package-level
+// With through a TTYHandler, which is the path the reported defect was
+// on: the handler is selected by TTY-ness, so on a terminal With's
+// attributes were silently dropped while the same code printed them
+// correctly in CI.
+//
+// This is an in-package test so it can point the package logger at a
+// buffer. Building an slog.Logger over a TTYHandler by hand would test
+// slog, not this package's With, and there is no injectable sink to
+// reach it from outside. The package logger is process-global, so this
+// test must not run in parallel.
+//
+//nolint:paralleltest // replaces the process-global package logger
+func TestWithAttributesReachTTYOutput(t *testing.T) {
+	var buf bytes.Buffer
+
+	previous := logger
+
+	t.Cleanup(func() { logger = previous })
+
+	logger = slog.New(NewTTYHandler(&buf, &slog.HandlerOptions{
+		Level: slog.LevelDebug,
+	}))
+
+	With("key", "value").Info("hello")
+
+	plain := withTestANSIEscape.ReplaceAllString(buf.String(), "")
+
+	require.NotEmpty(t, plain)
+	assert.Contains(t, plain, "hello")
+	assert.Contains(t, plain, "key=value",
+		"log.With attributes must reach TTYHandler output")
+}
+
+// TestWithoutInitializedLoggerFallsBack pins the documented behavior of
+// With before Initialize has run: it hands back the slog default rather
+// than a nil logger that would panic at the call site.
+//
+//nolint:paralleltest // replaces the process-global package logger
+func TestWithoutInitializedLoggerFallsBack(t *testing.T) {
+	previous := logger
+
+	t.Cleanup(func() { logger = previous })
+
+	logger = nil
+
+	assert.NotNil(t, With("key", "value"))
+}

internal/vaultik/helpers.go

@@ -53,18 +53,36 @@ const (
 )
 
 // SnapshotInfo contains information about a snapshot.
-// UncompressedSize and NewChunkSize are populated only when the snapshot
-// is present in the local database; LocallyTracked indicates whether
-// those values are meaningful.
+//
+// LocallyTracked says which of the two sources this row came from, and
+// therefore which fields are meaningful:
+//
+//   - true: the snapshot is in the local index. ID is its human
+//     snapshot ID and UncompressedSize/NewChunkSize are populated.
+//   - false: the snapshot was found only on the destination store. ID
+//     is empty, because the human ID cannot be recovered from remote
+//     storage without the age secret key (see RemoteKey), and
+//     UncompressedSize/NewChunkSize are zero because they are computed
+//     from local index rows that do not exist.
+//
+// RemoteKey is always populated: for a locally tracked snapshot it is
+// the key the snapshot would occupy on the destination store, and for a
+// remote-only snapshot it is the only identifier available.
+//
+// RemotePresent reports whether the snapshot's metadata was seen on the
+// destination store. It is nil when the destination could not be
+// listed, so "absent" and "unknown" stay distinguishable.
 //
 //nolint:tagliatelle // snake_case is the established output format
 type SnapshotInfo struct {
 	ID               types.SnapshotID `json:"id"`
+	RemoteKey        string           `json:"remote_key"`
 	Timestamp        time.Time        `json:"timestamp"`
 	CompressedSize   int64            `json:"compressed_size"`
 	UncompressedSize int64            `json:"uncompressed_size,omitempty"`
 	NewChunkSize     int64            `json:"new_chunk_size,omitempty"`
 	LocallyTracked   bool             `json:"locally_tracked"`
+	RemotePresent    *bool            `json:"remote_present"`
 }
 
 // formatBytes formats bytes in a human-readable format

internal/vaultik/info.go

@@ -9,7 +9,6 @@ import (
 
 	"github.com/dustin/go-humanize"
 	"sneak.berlin/go/vaultik/internal/log"
-	"sneak.berlin/go/vaultik/internal/snapshot"
 )
 
 // ShowInfo displays system and configuration information
@@ -312,20 +311,12 @@ func (v *Vaultik) collectReferencedBlobsFromManifests(
 	referencedBlobs := make(map[string]int64)
 
 	for _, snapshotID := range snapshotIDs {
-		manifestKey := fmt.Sprintf("metadata/%s/manifest.json.zst", snapshotID)
-
-		reader, err := v.Storage.Get(v.ctx, manifestKey)
+		// snapshotIDs here are remote keys, taken straight from the
+		// metadata/ listing. downloadManifestByKey is the single reader
+		// for remote manifests; see its doc comment.
+		manifest, err := v.downloadManifestByKey(snapshotID)
 		if err != nil {
-			log.Warn("Failed to get manifest", "snapshot", snapshotID, "error", err)
-
-			continue
-		}
-
-		manifest, err := snapshot.DecodeManifest(reader)
-		_ = reader.Close()
-
-		if err != nil {
-			log.Warn("Failed to decode manifest", "snapshot", snapshotID, "error", err)
+			log.Warn("Failed to read manifest", "snapshot", snapshotID, "error", err)
 
 			continue
 		}

internal/vaultik/prune.go

@@ -79,7 +79,7 @@ func (v *Vaultik) Prune(opts *PruneOptions) error {
 	// store is treated as gone. This used to be the separate 'snapshot
 	// cleanup' command and is now folded in so a single 'vaultik prune'
 	// gets the local index fully back in sync with the destination.
-	err = v.CleanupLocalSnapshots()
+	err = v.CleanupLocalSnapshots(opts)
 	if err != nil {
 		return fmt.Errorf("reconciling local snapshots with remote: %w", err)
 	}

internal/vaultik/prune_cleanup_test.go

@@ -0,0 +1,134 @@
+package vaultik_test
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// cleanupStaleID is a local snapshot record with no remote manifest —
+// the record CleanupLocalSnapshots exists to remove.
+const cleanupStaleID = "testhost_home_2026-04-01T09:00:00Z"
+
+// remainingSnapshotLimit bounds the post-cleanup listing. ListRecent
+// takes a SQL LIMIT, so it must be positive; the fixtures never exceed
+// a handful of rows.
+const remainingSnapshotLimit = 100
+
+// cleanupStart is the fixture snapshot's start time. Its exact value is
+// irrelevant; only presence in the index matters here.
+//
+//nolint:gochecknoglobals // read-only fixture shared by the tests below
+var cleanupStart = time.Date(2026, 4, 1, 9, 0, 0, 0, time.UTC)
+
+// TestCleanupLocalSnapshots_JSONWritesNothingToStdout is the regression
+// guard for issue #108: `vaultik prune --json | jq` failed because this
+// function wrote prose to stdout on every branch, ahead of the
+// PruneBlobsResult document, with no --json awareness at all.
+//
+// Both branches are covered because the three writes between them left
+// no input that avoided the contamination: with stale records there was
+// a line per record plus a summary, and with none there was still the
+// "No stale local snapshots found." line.
+func TestCleanupLocalSnapshots_JSONWritesNothingToStdout(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	for name, seed := range map[string]func(*listEnv){
+		"no stale records": func(env *listEnv) {
+			// A snapshot present both locally and remotely: nothing to
+			// remove, which used to print the "No stale" line.
+			env.addLocal(t, listLocalID, cleanupStart)
+			env.addRemote(t, listLocalID, cleanupStart)
+		},
+		"stale records present": func(env *listEnv) {
+			env.addLocal(t, cleanupStaleID, cleanupStart)
+		},
+		"nothing at all": func(_ *listEnv) {},
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			env := newListEnv(t)
+			seed(env)
+
+			err := env.v.CleanupLocalSnapshots(&vaultik.PruneOptions{JSON: true})
+			require.NoError(t, err)
+
+			assert.Empty(t, env.stdout.String(),
+				"stdout carries the --json document and nothing else")
+		})
+	}
+}
+
+// TestCleanupLocalSnapshots_HumanOutputRetained pins the other half of
+// the contract. Without it the test above would be satisfied by
+// deleting the three lines outright, and a `vaultik prune` with no
+// flags must still say that it removed records from the local index —
+// that is the deletion of local state, not decoration.
+func TestCleanupLocalSnapshots_HumanOutputRetained(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	t.Run("stale records present", func(t *testing.T) {
+		t.Parallel()
+
+		env := newListEnv(t)
+		env.addLocal(t, cleanupStaleID, cleanupStart)
+
+		err := env.v.CleanupLocalSnapshots(&vaultik.PruneOptions{})
+		require.NoError(t, err)
+
+		out := env.stdout.String()
+
+		assert.Contains(t, out, "Removing stale local record: "+cleanupStaleID)
+		assert.Contains(t, out, "Removed 1 stale local snapshot record(s).")
+	})
+
+	t.Run("no stale records", func(t *testing.T) {
+		t.Parallel()
+
+		env := newListEnv(t)
+		env.addLocal(t, listLocalID, cleanupStart)
+		env.addRemote(t, listLocalID, cleanupStart)
+
+		err := env.v.CleanupLocalSnapshots(&vaultik.PruneOptions{})
+		require.NoError(t, err)
+
+		assert.Contains(t, env.stdout.String(),
+			"No stale local snapshots found.")
+	})
+}
+
+// TestCleanupLocalSnapshots_RemovesOnlyStaleRecords checks that the
+// --json gate did not change what the function does, only what it
+// says: the stale record is gone from the index and the one with a
+// remote manifest is untouched.
+func TestCleanupLocalSnapshots_RemovesOnlyStaleRecords(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+	env.addLocal(t, listLocalID, cleanupStart)
+	env.addRemote(t, listLocalID, cleanupStart)
+	env.addLocal(t, cleanupStaleID, cleanupStart)
+
+	err := env.v.CleanupLocalSnapshots(&vaultik.PruneOptions{JSON: true})
+	require.NoError(t, err)
+
+	remaining, err := env.v.Repositories.Snapshots.ListRecent(
+		env.v.Context(), remainingSnapshotLimit)
+	require.NoError(t, err)
+
+	ids := make([]string, 0, len(remaining))
+	for _, snap := range remaining {
+		ids = append(ids, snap.ID.String())
+	}
+
+	assert.Equal(t, []string{listLocalID}, ids,
+		"only the record with no remote manifest may be removed")
+}

internal/vaultik/snapshot.go

@@ -9,10 +9,8 @@ import (
 	"regexp"
 	"sort"
 	"strings"
-	"text/tabwriter"
 	"time"
 
-	"sneak.berlin/go/vaultik/internal/database"
 	"sneak.berlin/go/vaultik/internal/log"
 	"sneak.berlin/go/vaultik/internal/snapshot"
 )
@@ -447,243 +445,6 @@ func (v *Vaultik) getSnapshotBlobSizes(snapshotID string) (int64, int64) {
 	return compressed, uncompressed
 }
 
-// ListSnapshots prints the table of snapshots, plus any reconciliation
-// warnings/notes between the local index and the backup destination
-// store.
-//
-// The local index database is always the primary source for the
-// table — it has the human snapshot IDs, timestamps, and per-snapshot
-// stats.
-//
-// If an age secret key is configured AND remote listing succeeds, we
-// cross-reference: any local snapshot whose hashed key isn't visible
-// remotely gets a "local-only" cleanup hint, and any remote key that
-// doesn't correspond to a known local snapshot gets reported in a
-// NOTE.
-//
-// If no age key is set the local machine is assumed write-only
-// (backup-only), so we skip remote listing entirely — there's no
-// value showing keys the user couldn't restore anyway.
-//
-// If remote listing fails (unmounted volume, permission denied,
-// network), we degrade to local-only with a warning. List never
-// fails just because the destination is unreachable.
-func (v *Vaultik) ListSnapshots(jsonOutput bool) error {
-	log.Info("Listing snapshots")
-
-	localSnaps, err := v.Repositories.Snapshots.ListRecent(v.ctx, listRecentLimit)
-	if err != nil {
-		return fmt.Errorf("listing local snapshots: %w", err)
-	}
-
-	snapshots := make([]SnapshotInfo, 0, len(localSnaps))
-	for _, ls := range localSnaps {
-		if ls.CompletedAt == nil {
-			continue
-		}
-
-		snapshots = append(snapshots, v.snapshotInfoFromLocal(ls))
-	}
-
-	sort.Slice(snapshots, func(i, j int) bool {
-		return snapshots[i].Timestamp.After(snapshots[j].Timestamp)
-	})
-
-	if jsonOutput {
-		encoder := json.NewEncoder(v.Stdout)
-		encoder.SetIndent("", "  ")
-
-		return encoder.Encode(snapshots)
-	}
-
-	err = v.printSnapshotTable(snapshots)
-	if err != nil {
-		return err
-	}
-
-	if v.Config.AgeSecretKey == "" {
-		return nil
-	}
-
-	v.reportRemoteDrift(localSnaps)
-
-	return nil
-}
-
-// reportRemoteDrift cross-references local snapshot records against the
-// remote metadata keys and reports local-only records and unknown
-// remote keys. Never fails: remote listing errors degrade to a warning.
-func (v *Vaultik) reportRemoteDrift(localSnaps []*database.Snapshot) {
-	remoteKeys, err := v.listAllRemoteSnapshotKeys()
-	if err != nil {
-		v.UI.Warningf("Could not list backup destination store: %v.", err)
-
-		return
-	}
-
-	localKeys := make(map[string]string, len(localSnaps))
-	for _, ls := range localSnaps {
-		if ls.CompletedAt == nil {
-			continue
-		}
-
-		localKeys[snapshot.RemoteSnapshotKey(ls.ID.String())] = ls.ID.String()
-	}
-
-	remoteSet := make(map[string]bool, len(remoteKeys))
-	for _, k := range remoteKeys {
-		remoteSet[k] = true
-	}
-
-	var localOnly []string
-
-	for key, humanID := range localKeys {
-		if !remoteSet[key] {
-			localOnly = append(localOnly, humanID)
-		}
-	}
-
-	var remoteOnlyCount int
-
-	for key := range remoteSet {
-		if _, ok := localKeys[key]; !ok {
-			remoteOnlyCount++
-		}
-	}
-
-	if len(localOnly) > 0 {
-		v.UI.Warningf("%d local snapshot record(s) not found in backup "+
-			"destination store:", len(localOnly))
-
-		for _, id := range localOnly {
-			v.UI.Infof("%s", v.UI.Snapshot(id))
-		}
-
-		v.UI.Infof("Run 'vaultik snapshot cleanup' to remove stale local records.")
-	}
-
-	if remoteOnlyCount > 0 {
-		v.UI.Noticef("NOTE: %d remote snapshot(s) found in backup destination "+
-			"store but not in local database.", remoteOnlyCount)
-	}
-}
-
-// snapshotInfoFromLocal builds a SnapshotInfo row from a local snapshot
-// record. Failures from any per-snapshot stat query degrade that
-// column to its snapshot-row fallback but never fail the listing.
-func (v *Vaultik) snapshotInfoFromLocal(ls *database.Snapshot) SnapshotInfo {
-	idStr := ls.ID.String()
-
-	totalSize, err := v.Repositories.Snapshots.GetSnapshotTotalCompressedSize(
-		v.ctx, idStr)
-	if err != nil {
-		log.Warn("Failed to get total compressed size", "id", idStr, "error", err)
-
-		totalSize = ls.BlobSize
-	}
-
-	uncompressedSize, err := v.Repositories.Snapshots.GetSnapshotUncompressedChunkSize(
-		v.ctx, idStr)
-	if err != nil {
-		log.Warn("Failed to get uncompressed chunk size", "id", idStr, "error", err)
-	}
-
-	newChunkSize, err := v.Repositories.Snapshots.GetSnapshotNewChunkSize(v.ctx, idStr)
-	if err != nil {
-		log.Warn("Failed to get new chunk size", "id", idStr, "error", err)
-	}
-
-	return SnapshotInfo{
-		ID:               ls.ID,
-		Timestamp:        ls.StartedAt,
-		CompressedSize:   totalSize,
-		UncompressedSize: uncompressedSize,
-		NewChunkSize:     newChunkSize,
-		LocallyTracked:   true,
-	}
-}
-
-// tabPadding is the tabwriter cell padding for the snapshot table.
-const tabPadding = 3
-
-// printSnapshotTable renders the snapshot list as a formatted table
-func (v *Vaultik) printSnapshotTable(snapshots []SnapshotInfo) error {
-	w := tabwriter.NewWriter(v.Stdout, 0, 0, tabPadding, ' ', 0)
-
-	_, err := fmt.Fprintln(w, "CONFIGURED SNAPSHOTS:")
-	if err != nil {
-		return err
-	}
-
-	_, err = fmt.Fprintln(w, "NAME\tPATHS")
-	if err != nil {
-		return err
-	}
-
-	_, err = fmt.Fprintln(w, "────\t─────")
-	if err != nil {
-		return err
-	}
-
-	for _, name := range v.Config.SnapshotNames() {
-		snap := v.Config.Snapshots[name]
-
-		paths := strings.Join(snap.Paths, ", ")
-
-		_, err = fmt.Fprintf(w, "%s\t%s\n", name, paths)
-		if err != nil {
-			return err
-		}
-	}
-
-	_, err = fmt.Fprintln(w)
-	if err != nil {
-		return err
-	}
-
-	_, err = fmt.Fprintln(w, "REMOTE SNAPSHOTS:")
-	if err != nil {
-		return err
-	}
-
-	_, err = fmt.Fprintln(w,
-		"SNAPSHOT ID\tTIMESTAMP\tCOMPRESSED SIZE\t"+
-			"UNCOMPRESSED SIZE\tNEW CHUNK SIZE")
-	if err != nil {
-		return err
-	}
-
-	_, err = fmt.Fprintln(w,
-		"───────────\t─────────\t───────────────\t"+
-			"─────────────────\t──────────────")
-	if err != nil {
-		return err
-	}
-
-	const remoteOnlyCell = "<remote only>"
-	for _, snap := range snapshots {
-		uncompressed := remoteOnlyCell
-		newChunks := remoteOnlyCell
-
-		if snap.LocallyTracked {
-			uncompressed = formatBytes(snap.UncompressedSize)
-			newChunks = formatBytes(snap.NewChunkSize)
-		}
-
-		_, err = fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\n",
-			snap.ID,
-			snap.Timestamp.Format("2006-01-02 15:04:05"),
-			formatBytes(snap.CompressedSize),
-			uncompressed,
-			newChunks)
-		if err != nil {
-			return err
-		}
-	}
-
-	return w.Flush()
-}
-
 // SnapshotPurgeOptions contains options for the snapshot purge command.
 type SnapshotPurgeOptions struct {
 	KeepLatest bool // Keep only the most recent snapshot per name
@@ -1068,7 +829,15 @@ func (v *Vaultik) outputVerifyJSON(result *VerifyResult) error {
 // behind by incomplete or interrupted backups. Each local snapshot's
 // human ID is hashed via RemoteSnapshotKey and compared against the
 // remote listing.
-func (v *Vaultik) CleanupLocalSnapshots() error {
+//
+// It takes the whole *PruneOptions, symmetric with PruneBlobs, because
+// it is the other half of one command: Prune runs this phase and then
+// that one. Only JSON is read here. Under --json every write below is
+// suppressed, because stdout carries the PruneBlobsResult document and
+// nothing else — prose ahead of it is what made `vaultik prune --json |
+// jq` fail (issue #108). The narration is duplicated as log records,
+// which go to stderr and so cannot corrupt the document.
+func (v *Vaultik) CleanupLocalSnapshots(opts *PruneOptions) error {
 	err := v.EnsureStorageBinding()
 	if err != nil {
 		return err
@@ -1094,7 +863,11 @@ func (v *Vaultik) CleanupLocalSnapshots() error {
 	for _, snap := range localSnapshots {
 		id := snap.ID.String()
 		if !remoteSet[snapshot.RemoteSnapshotKey(id)] {
-			v.stdoutf("Removing stale local record: %s\n", id)
+			log.Info("Removing stale local snapshot record", "snapshot_id", id)
+
+			if !opts.JSON {
+				v.stdoutf("Removing stale local record: %s\n", id)
+			}
 
 			err = v.deleteSnapshotFromLocalDB(id)
 			if err != nil {
@@ -1108,6 +881,13 @@ func (v *Vaultik) CleanupLocalSnapshots() error {
 		}
 	}
 
+	log.Info("Reconciled local snapshot records against remote metadata",
+		"removed", removed, "examined", len(localSnapshots))
+
+	if opts.JSON {
+		return nil
+	}
+
 	if removed == 0 {
 		v.printlnStdout("No stale local snapshots found.")
 	} else {
@@ -1123,6 +903,14 @@ func (v *Vaultik) CleanupLocalSnapshots() error {
 // metadata/<remoteKey>/manifest.json.zst. The remoteKey is the double-
 // SHA256 derivation produced by snapshot.RemoteSnapshotKey, not the
 // human snapshot ID. Callers that have a human ID must hash first.
+//
+// This is the only place vaultik reads a manifest off the destination
+// store, deliberately: the manifest is currently stored compressed but
+// unencrypted, which is what lets `snapshot list` enumerate the
+// destination on a host holding no private key. Whether to encrypt it
+// is open (issue #81), and routing every read through here means that
+// decision has exactly one call site to change. Keep it that way — do
+// not open metadata/<key>/manifest.json.zst directly elsewhere.
 func (v *Vaultik) downloadManifestByKey(remoteKey string) (*snapshot.Manifest, error) {
 	manifestPath := fmt.Sprintf("metadata/%s/manifest.json.zst", remoteKey)
 

internal/vaultik/snapshot_list.go

@@ -0,0 +1,570 @@
+package vaultik
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"text/tabwriter"
+	"time"
+
+	"golang.org/x/sync/errgroup"
+	"sneak.berlin/go/vaultik/internal/database"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/snapshot"
+)
+
+// remoteOnlyCell fills the table columns that can only be derived from
+// the local index. A snapshot present only on the destination store has
+// no local rows to derive them from.
+const remoteOnlyCell = "<remote only>"
+
+// remoteKeyDisplayLen is how many hex characters of a remote key are
+// shown in the identifier column for a remote-only snapshot. Twelve
+// matches the abbreviation length used elsewhere in the UI and is far
+// past the point of ambiguity for a SHA256 digest.
+const remoteKeyDisplayLen = 12
+
+// maxRemoteOnlyRows caps how many remote-only snapshots a single
+// `snapshot list` will describe. Each one costs a manifest read, so an
+// uncapped listing against a destination holding many thousands of
+// unknown snapshots would be both slow and unbounded in memory. Beyond
+// the cap the table is truncated and the count of omitted snapshots is
+// reported.
+const maxRemoteOnlyRows = 1000
+
+// remoteManifestFetchConcurrency bounds how many manifest reads are in
+// flight at once while describing remote-only snapshots. The listing
+// itself is a single streamed prefix request; only the per-snapshot
+// manifest reads need throttling.
+const remoteManifestFetchConcurrency = 8
+
+// tabPadding is the tabwriter cell padding for the snapshot table.
+const tabPadding = 3
+
+// ListSnapshots prints the table of snapshots known to this host: the
+// union of the local index database and the backup destination store.
+//
+// Remote listing needs no age secret key. A snapshot's manifest
+// (metadata/<remote-key>/manifest.json.zst) is compressed but not
+// encrypted, so a host holding only the public key — the configuration
+// vaultik is designed for — can still enumerate what it has backed up
+// and see each snapshot's timestamp and compressed size.
+//
+// What that host cannot see is a remote-only snapshot's human ID.
+// snapshot.RemoteSnapshotKey is one-way and the manifest stores the
+// hashed key rather than the ID, so hostname and snapshot name live
+// only in the local index and in the encrypted db.zst.age. Remote-only
+// rows are therefore identified by an abbreviation of their remote key,
+// and the two columns that genuinely require the local index
+// (uncompressed size, new chunk size) render as "<remote only>". No
+// attempt is made to recover or fabricate the human ID.
+//
+// Snapshots in the local index with no counterpart on the destination
+// store are reported as drift below the table.
+//
+// If remote listing fails (unmounted volume, permission denied,
+// network), we degrade to local-only with a warning. List never fails
+// just because the destination is unreachable.
+func (v *Vaultik) ListSnapshots(jsonOutput bool) error {
+	log.Info("Listing snapshots")
+
+	localSnaps, err := v.Repositories.Snapshots.ListRecent(v.ctx, listRecentLimit)
+	if err != nil {
+		return fmt.Errorf("listing local snapshots: %w", err)
+	}
+
+	snapshots := make([]SnapshotInfo, 0, len(localSnaps))
+	localKeys := make(map[string]bool, len(localSnaps))
+
+	for _, ls := range localSnaps {
+		if ls.CompletedAt == nil {
+			continue
+		}
+
+		info := v.snapshotInfoFromLocal(ls)
+		localKeys[info.RemoteKey] = true
+		snapshots = append(snapshots, info)
+	}
+
+	listing, remoteErr := v.collectRemoteSnapshots(localKeys)
+	if remoteErr != nil {
+		v.warnRemoteListingFailed(remoteErr, jsonOutput)
+	} else {
+		snapshots = append(snapshots, listing.remoteOnly...)
+		markRemotePresence(snapshots, listing.keys)
+	}
+
+	// Stable so that rows sharing a timestamp keep the order they were
+	// merged in, rather than depending on the sort's pivot choices. The
+	// unparseable-timestamp fallback in remoteSnapshotInfo makes ties
+	// realistic: every such row carries the zero time.
+	sort.SliceStable(snapshots, func(i, j int) bool {
+		return snapshots[i].Timestamp.After(snapshots[j].Timestamp)
+	})
+
+	if jsonOutput {
+		if remoteErr == nil {
+			v.reportJSONListingLimits(listing)
+		}
+
+		encoder := json.NewEncoder(v.Stdout)
+		encoder.SetIndent("", "  ")
+
+		return encoder.Encode(snapshots)
+	}
+
+	err = v.printSnapshotTable(snapshots)
+	if err != nil {
+		return err
+	}
+
+	if remoteErr == nil {
+		v.reportListDrift(snapshots, listing)
+	}
+
+	return nil
+}
+
+// warnRemoteListingFailed reports an unreachable or unreadable
+// destination store without failing the command: the local index is
+// still worth printing, and `snapshot list` exiting non-zero because a
+// volume is unmounted would be worse than useless.
+//
+// The two output modes report it through different channels. Table mode
+// uses the UI writer, whose prose and color match the table it sits
+// under. The UI writer emits on stdout, though, so --json mode uses the
+// logger instead: stdout has to hold nothing but the JSON document for
+// `snapshot list --json | jq` to work. Both channels are chosen once,
+// never both, so the user is not told the same thing twice.
+//
+// The failure is also representable in the document itself: every row's
+// remote_present is null when the destination could not be listed.
+func (v *Vaultik) warnRemoteListingFailed(err error, jsonOutput bool) {
+	if jsonOutput {
+		log.Warn("Could not list backup destination store; "+
+			"showing snapshots from the local index only", "error", err)
+
+		return
+	}
+
+	v.UI.Warningf("Could not list backup destination store: %v.", err)
+	v.UI.Infof("Showing snapshots from the local index only.")
+}
+
+// reportJSONListingLimits tells a --json consumer that the document it
+// is about to read is incomplete: manifests that could not be read, and
+// remote-only snapshots dropped by the maxRemoteOnlyRows cap.
+//
+// Table mode reports both below the table (see reportListDrift) through
+// the UI writer, which emits on stdout. In --json mode stdout has to
+// hold nothing but the document for `snapshot list --json | jq` to
+// work, and the document's shape is deliberately left alone so existing
+// consumers keep parsing — so these go to the logger, which writes to
+// stderr. A consumer that must react to truncation can treat any output
+// on that stream as "this listing is not the whole picture"; silent
+// truncation of a listing whose whole purpose is disaster recovery is
+// the worse failure.
+func (v *Vaultik) reportJSONListingLimits(listing *remoteSnapshotListing) {
+	if listing.unreadable > 0 {
+		log.Warn("Some remote snapshot(s) could not be described: "+
+			"manifest missing or unreadable; they are missing from "+
+			"this listing", "unreadable", listing.unreadable)
+	}
+
+	if listing.omitted > 0 {
+		log.Warn("Listing truncated: further remote-only snapshot(s) "+
+			"not shown", "omitted", listing.omitted,
+			"limit", maxRemoteOnlyRows)
+	}
+}
+
+// remoteSnapshotListing is the result of one pass over the destination
+// store's metadata/ prefix.
+type remoteSnapshotListing struct {
+	// keys holds every remote snapshot key present on the destination
+	// store, whether or not it is known locally.
+	keys map[string]bool
+
+	// remoteOnly holds one row per remote key with no local
+	// counterpart, built from that snapshot's manifest.
+	remoteOnly []SnapshotInfo
+
+	// omitted counts remote-only keys dropped because describing them
+	// all would have exceeded maxRemoteOnlyRows.
+	omitted int
+
+	// unreadable counts remote-only keys whose manifest could not be
+	// read or decoded.
+	unreadable int
+}
+
+// collectRemoteSnapshots enumerates the destination store and describes
+// every snapshot on it that localKeys does not already account for.
+//
+// The enumeration is a single streamed listing of the metadata/ prefix,
+// so the request count does not scale with the number of snapshots.
+// Manifest reads scale only with the number of snapshots the local
+// index does not already know about, and are capped at
+// maxRemoteOnlyRows.
+func (v *Vaultik) collectRemoteSnapshots(
+	localKeys map[string]bool,
+) (*remoteSnapshotListing, error) {
+	keys, err := v.listAllRemoteSnapshotKeys()
+	if err != nil {
+		return nil, err
+	}
+
+	listing := &remoteSnapshotListing{
+		keys: make(map[string]bool, len(keys)),
+	}
+
+	unknown := make([]string, 0, len(keys))
+
+	for _, key := range keys {
+		listing.keys[key] = true
+
+		if !localKeys[key] {
+			unknown = append(unknown, key)
+		}
+	}
+
+	// Sorted so both the truncation point and the fetch order are
+	// deterministic run to run.
+	sort.Strings(unknown)
+
+	if len(unknown) > maxRemoteOnlyRows {
+		listing.omitted = len(unknown) - maxRemoteOnlyRows
+		unknown = unknown[:maxRemoteOnlyRows]
+	}
+
+	listing.remoteOnly, listing.unreadable = v.describeRemoteOnlySnapshots(
+		unknown)
+
+	return listing, nil
+}
+
+// listingWarning is a problem found with one remote snapshot, recorded
+// rather than emitted on the spot. Manifest reads run concurrently, so
+// emitting from the worker that found the problem would order the
+// warnings by fetch completion — which varies run to run with network
+// timing and tells the reader nothing. Holding them and emitting in key
+// order from a single goroutine after every read has finished makes two
+// runs over the same damaged store produce the same diagnostics in the
+// same order.
+//
+// Concurrency safety is no longer part of the reason: these are emitted
+// through log.Warn, and slog handlers are safe for concurrent use.
+type listingWarning struct {
+	msg  string
+	args []any
+}
+
+// describeRemoteOnlySnapshots reads the manifest for each supplied
+// remote key and turns it into a table row, returning the rows and the
+// number of keys whose manifest could not be read.
+//
+// A key whose manifest is missing or corrupt is skipped rather than
+// failing the listing: one bad snapshot directory must not hide every
+// other snapshot the user has.
+func (v *Vaultik) describeRemoteOnlySnapshots(
+	keys []string,
+) ([]SnapshotInfo, int) {
+	found := make([]SnapshotInfo, len(keys))
+	ok := make([]bool, len(keys))
+	warnings := make([]*listingWarning, len(keys))
+
+	var group errgroup.Group
+
+	group.SetLimit(remoteManifestFetchConcurrency)
+
+	for i, key := range keys {
+		group.Go(func() error {
+			info, warning, err := v.remoteSnapshotInfo(key)
+			if err != nil {
+				warnings[i] = &listingWarning{
+					msg:  "Could not describe remote snapshot",
+					args: []any{"remote_key", key, "error", err},
+				}
+
+				// Deliberately not returned: the failure is carried in
+				// warnings/ok and reported as a count. Returning it
+				// would cancel the group and let one bad snapshot
+				// directory hide every other snapshot the user has.
+				return nil //nolint:nilerr // see above
+			}
+
+			found[i] = info
+			warnings[i] = warning
+			ok[i] = true
+
+			return nil
+		})
+	}
+
+	// No goroutine above ever returns an error; failures are recorded
+	// in ok and reported as a count.
+	_ = group.Wait()
+
+	infos := make([]SnapshotInfo, 0, len(keys))
+	unreadable := 0
+
+	for i := range keys {
+		if warnings[i] != nil {
+			log.Warn(warnings[i].msg, warnings[i].args...)
+		}
+
+		if !ok[i] {
+			unreadable++
+
+			continue
+		}
+
+		infos = append(infos, found[i])
+	}
+
+	return infos, unreadable
+}
+
+// remoteSnapshotInfo builds a table row for a snapshot that exists on
+// the destination store but not in the local index, from the only
+// source available without the private key: the unencrypted manifest.
+//
+// ID is deliberately left zero. Recovering it would mean inverting
+// snapshot.RemoteSnapshotKey, which is not possible, or writing the
+// human ID somewhere unencrypted on the destination, which would undo
+// the privacy property that hashing the key exists to provide (see
+// issue #81). The renderer marks the row as unnamed rather than
+// guessing.
+//
+// The returned warning, when non-nil, is a problem worth telling the
+// user about that was not bad enough to drop the row. It is returned
+// rather than logged because this runs on a worker goroutine; see
+// listingWarning.
+func (v *Vaultik) remoteSnapshotInfo(
+	remoteKey string,
+) (SnapshotInfo, *listingWarning, error) {
+	manifest, err := v.downloadManifestByKey(remoteKey)
+	if err != nil {
+		return SnapshotInfo{}, nil, err
+	}
+
+	var warning *listingWarning
+
+	timestamp, err := time.Parse(time.RFC3339, manifest.Timestamp)
+	if err != nil {
+		// The snapshot is really there; an unparseable timestamp is not
+		// reason enough to hide it. It sorts to the bottom as the zero
+		// time.
+		warning = &listingWarning{
+			msg: "Remote manifest has an unparseable timestamp",
+			args: []any{
+				"remote_key", remoteKey,
+				"timestamp", manifest.Timestamp,
+				"error", err,
+			},
+		}
+
+		timestamp = time.Time{}
+	}
+
+	return SnapshotInfo{
+		RemoteKey:      remoteKey,
+		Timestamp:      timestamp.UTC(),
+		CompressedSize: manifest.TotalCompressedSize,
+		LocallyTracked: false,
+	}, warning, nil
+}
+
+// markRemotePresence records, for every row, whether its remote key was
+// seen on the destination store during this listing. Only called when
+// the listing succeeded: when it did not, presence stays nil ("not
+// known") rather than being reported as absence.
+func markRemotePresence(snapshots []SnapshotInfo, remoteKeys map[string]bool) {
+	for i := range snapshots {
+		present := remoteKeys[snapshots[i].RemoteKey]
+		snapshots[i].RemotePresent = &present
+	}
+}
+
+// snapshotInfoFromLocal builds a SnapshotInfo row from a local snapshot
+// record. Failures from any per-snapshot stat query degrade that
+// column to its snapshot-row fallback but never fail the listing.
+func (v *Vaultik) snapshotInfoFromLocal(ls *database.Snapshot) SnapshotInfo {
+	idStr := ls.ID.String()
+
+	totalSize, err := v.Repositories.Snapshots.GetSnapshotTotalCompressedSize(
+		v.ctx, idStr)
+	if err != nil {
+		log.Warn("Failed to get total compressed size", "id", idStr, "error", err)
+
+		totalSize = ls.BlobSize
+	}
+
+	uncompressedSize, err := v.Repositories.Snapshots.GetSnapshotUncompressedChunkSize(
+		v.ctx, idStr)
+	if err != nil {
+		log.Warn("Failed to get uncompressed chunk size", "id", idStr, "error", err)
+	}
+
+	newChunkSize, err := v.Repositories.Snapshots.GetSnapshotNewChunkSize(v.ctx, idStr)
+	if err != nil {
+		log.Warn("Failed to get new chunk size", "id", idStr, "error", err)
+	}
+
+	return SnapshotInfo{
+		ID:               ls.ID,
+		RemoteKey:        snapshot.RemoteSnapshotKey(idStr),
+		Timestamp:        ls.StartedAt,
+		CompressedSize:   totalSize,
+		UncompressedSize: uncompressedSize,
+		NewChunkSize:     newChunkSize,
+		LocallyTracked:   true,
+	}
+}
+
+// reportListDrift prints the reconciliation notes the merged table
+// cannot express on its own: local records with no counterpart on the
+// destination store, plus counts of remote snapshots that were
+// unreadable or omitted.
+//
+// This is what remains of the old reportRemoteDrift, and it no longer
+// touches the destination store. Its remote-only half collapsed into
+// the table — those snapshots are rows now, not a footnote count — and
+// its local-only half reads the merge ListSnapshots already computed,
+// so `snapshot list` lists the destination exactly once per invocation.
+func (v *Vaultik) reportListDrift(
+	snapshots []SnapshotInfo, listing *remoteSnapshotListing,
+) {
+	var localOnly []string
+
+	for _, snap := range snapshots {
+		if snap.LocallyTracked && !listing.keys[snap.RemoteKey] {
+			localOnly = append(localOnly, snap.ID.String())
+		}
+	}
+
+	if len(localOnly) > 0 {
+		v.UI.Warningf("%d local snapshot record(s) not found in backup "+
+			"destination store:", len(localOnly))
+
+		for _, id := range localOnly {
+			v.UI.Infof("%s", v.UI.Snapshot(id))
+		}
+
+		v.UI.Infof("Run '%s' to remove stale local records.", pruneCommandHint)
+	}
+
+	if len(listing.remoteOnly) > 0 {
+		v.UI.Noticef("NOTE: %d snapshot(s) on the backup destination store "+
+			"are not in the local index. Their hostname and snapshot name "+
+			"cannot be recovered without the age secret key, so they are "+
+			"listed by remote key.", len(listing.remoteOnly))
+	}
+
+	if listing.unreadable > 0 {
+		v.UI.Warningf("%d remote snapshot(s) could not be described: "+
+			"manifest missing or unreadable.", listing.unreadable)
+	}
+
+	if listing.omitted > 0 {
+		v.UI.Warningf("%d further remote-only snapshot(s) not shown "+
+			"(limit %d per listing).", listing.omitted, maxRemoteOnlyRows)
+	}
+}
+
+// formatRemoteOnlyID renders the identifier cell for a snapshot absent
+// from the local index. Its human ID cannot be recovered without the
+// private key, so the cell shows an abbreviation of the remote key
+// instead. The angle brackets make it obvious this is not a snapshot
+// name, which matters more than compactness: a bare hex string would
+// read as a name the user simply doesn't recognize.
+func formatRemoteOnlyID(remoteKey string) string {
+	short := remoteKey
+	if len(short) > remoteKeyDisplayLen {
+		short = short[:remoteKeyDisplayLen]
+	}
+
+	return "<remote only:" + short + ">"
+}
+
+// printSnapshotTable renders the snapshot list as a formatted table
+func (v *Vaultik) printSnapshotTable(snapshots []SnapshotInfo) error {
+	w := tabwriter.NewWriter(v.Stdout, 0, 0, tabPadding, ' ', 0)
+
+	_, err := fmt.Fprintln(w, "CONFIGURED SNAPSHOTS:")
+	if err != nil {
+		return err
+	}
+
+	_, err = fmt.Fprintln(w, "NAME\tPATHS")
+	if err != nil {
+		return err
+	}
+
+	_, err = fmt.Fprintln(w, "────\t─────")
+	if err != nil {
+		return err
+	}
+
+	for _, name := range v.Config.SnapshotNames() {
+		snap := v.Config.Snapshots[name]
+
+		paths := strings.Join(snap.Paths, ", ")
+
+		_, err = fmt.Fprintf(w, "%s\t%s\n", name, paths)
+		if err != nil {
+			return err
+		}
+	}
+
+	_, err = fmt.Fprintln(w)
+	if err != nil {
+		return err
+	}
+
+	_, err = fmt.Fprintln(w, "REMOTE SNAPSHOTS:")
+	if err != nil {
+		return err
+	}
+
+	_, err = fmt.Fprintln(w,
+		"SNAPSHOT ID\tTIMESTAMP\tCOMPRESSED SIZE\t"+
+			"UNCOMPRESSED SIZE\tNEW CHUNK SIZE")
+	if err != nil {
+		return err
+	}
+
+	_, err = fmt.Fprintln(w,
+		"───────────\t─────────\t───────────────\t"+
+			"─────────────────\t──────────────")
+	if err != nil {
+		return err
+	}
+
+	for _, snap := range snapshots {
+		var id, uncompressed, newChunks string
+
+		if snap.LocallyTracked {
+			id = snap.ID.String()
+			uncompressed = formatBytes(snap.UncompressedSize)
+			newChunks = formatBytes(snap.NewChunkSize)
+		} else {
+			id = formatRemoteOnlyID(snap.RemoteKey)
+			uncompressed = remoteOnlyCell
+			newChunks = remoteOnlyCell
+		}
+
+		_, err = fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\n",
+			id,
+			snap.Timestamp.Format("2006-01-02 15:04:05"),
+			formatBytes(snap.CompressedSize),
+			uncompressed,
+			newChunks)
+		if err != nil {
+			return err
+		}
+	}
+
+	return w.Flush()
+}

internal/vaultik/snapshot_list_test.go

@@ -0,0 +1,860 @@
+package vaultik_test
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/config"
+	"sneak.berlin/go/vaultik/internal/database"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/snapshot"
+	"sneak.berlin/go/vaultik/internal/storage"
+	"sneak.berlin/go/vaultik/internal/types"
+	"sneak.berlin/go/vaultik/internal/ui"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// errRemoteUnreachable stands in for the real-world reasons a
+// destination store cannot be listed: unmounted volume, permission
+// denied, network down.
+var errRemoteUnreachable = errors.New("permission denied")
+
+// observingStorer wraps testStorer to record how the destination store
+// was used: how many prefix listings were issued (the merged listing
+// must not scale requests with snapshot count) and which object keys
+// were fetched (nothing encrypted may be fetched during a listing).
+// Setting listErr makes every listing fail, simulating an unreachable
+// destination.
+type observingStorer struct {
+	*testStorer
+
+	mu        sync.Mutex
+	listCalls int
+	fetched   []string
+	listErr   error
+}
+
+func newObservingStorer() *observingStorer {
+	return &observingStorer{testStorer: newTestStorer()}
+}
+
+func (s *observingStorer) ListStream(
+	ctx context.Context, prefix string,
+) <-chan storage.ObjectInfo {
+	s.mu.Lock()
+	s.listCalls++
+	failure := s.listErr
+	s.mu.Unlock()
+
+	if failure != nil {
+		ch := make(chan storage.ObjectInfo, 1)
+		ch <- storage.ObjectInfo{Err: failure}
+
+		close(ch)
+
+		return ch
+	}
+
+	return s.testStorer.ListStream(ctx, prefix)
+}
+
+func (s *observingStorer) Get(
+	ctx context.Context, key string,
+) (io.ReadCloser, error) {
+	s.mu.Lock()
+	s.fetched = append(s.fetched, key)
+	s.mu.Unlock()
+
+	return s.testStorer.Get(ctx, key)
+}
+
+// listStreamCalls returns how many prefix listings were issued.
+func (s *observingStorer) listStreamCalls() int {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	return s.listCalls
+}
+
+// fetchedKeys returns a copy of every object key that was read.
+func (s *observingStorer) fetchedKeys() []string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	return append([]string(nil), s.fetched...)
+}
+
+// listEnv is a Vaultik wired for exercising ListSnapshots: an in-memory
+// index database, an observable in-memory destination store, and
+// captured output.
+//
+// The configuration deliberately has no age secret key. That is the
+// production configuration vaultik is designed for — the backed-up host
+// holds only the public key — and every assertion in this file has to
+// hold in it.
+type listEnv struct {
+	v      *vaultik.Vaultik
+	store  *observingStorer
+	stdout *bytes.Buffer
+}
+
+func newListEnv(t *testing.T) *listEnv {
+	t.Helper()
+
+	ctx := context.Background()
+
+	db, err := database.New(ctx, ":memory:")
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = db.Close() })
+
+	store := newObservingStorer()
+	stdout := &bytes.Buffer{}
+
+	v := &vaultik.Vaultik{
+		Config: &config.Config{
+			AgeSecretKey: "",
+			Snapshots: map[string]config.SnapshotConfig{
+				listConfiguredName: {Paths: []string{"/" + listConfiguredName}},
+			},
+		},
+		Storage:      store,
+		Repositories: database.NewRepositories(db),
+		DB:           db,
+		Stdout:       stdout,
+		Stderr:       &bytes.Buffer{},
+		Stdin:        &bytes.Buffer{},
+		UI:           ui.NewWithColor(stdout, false),
+	}
+	v.SetContext(ctx)
+
+	return &listEnv{v: v, store: store, stdout: stdout}
+}
+
+// addLocal inserts a completed snapshot into the local index.
+func (e *listEnv) addLocal(t *testing.T, id string, startedAt time.Time) {
+	t.Helper()
+
+	completedAt := startedAt.Add(time.Minute)
+	snap := &database.Snapshot{
+		ID:             types.SnapshotID(id),
+		Hostname:       "testhost",
+		VaultikVersion: testLabel,
+		StartedAt:      startedAt,
+		CompletedAt:    &completedAt,
+	}
+
+	ctx := context.Background()
+	err := e.v.Repositories.WithTx(ctx, func(ctx context.Context, tx *sql.Tx) error {
+		return e.v.Repositories.Snapshots.Create(ctx, tx, snap)
+	})
+	require.NoError(t, err, "creating local snapshot %s", id)
+}
+
+// addRemote writes a manifest to the destination store at the hashed
+// path the production code uses, exactly as a real backup would. Every
+// fixture snapshot has the same compressed size (fiveMegabytes); the
+// tests care about which columns are populated, not about size variety.
+func (e *listEnv) addRemote(
+	t *testing.T, snapshotID string, timestamp time.Time,
+) string {
+	t.Helper()
+
+	return e.addRemoteRawTimestamp(t, snapshotID,
+		timestamp.UTC().Format(time.RFC3339))
+}
+
+// addRemoteRawTimestamp is addRemote with the manifest's timestamp field
+// written verbatim, so the unparseable-timestamp path can be exercised
+// with a value no time.Parse will accept.
+func (e *listEnv) addRemoteRawTimestamp(
+	t *testing.T, snapshotID, timestamp string,
+) string {
+	t.Helper()
+
+	remoteKey := snapshot.RemoteSnapshotKey(snapshotID)
+	manifest := &snapshot.Manifest{
+		// Note: the hashed key, never the human ID. That is precisely
+		// why a remote-only snapshot cannot be named.
+		SnapshotID:          remoteKey,
+		Timestamp:           timestamp,
+		BlobCount:           1,
+		TotalCompressedSize: fiveMegabytes,
+		Blobs: []snapshot.BlobInfo{
+			{Hash: testBlobHashA, CompressedSize: fiveMegabytes},
+		},
+	}
+
+	data, err := snapshot.EncodeManifest(manifest, 3)
+	require.NoError(t, err)
+
+	err = e.store.Put(context.Background(),
+		"metadata/"+remoteKey+"/manifest.json.zst", bytes.NewReader(data))
+	require.NoError(t, err)
+
+	return remoteKey
+}
+
+// Fixtures shared across the listing tests.
+const (
+	// listConfiguredName is the one snapshot name in the test config.
+	listConfiguredName = "home"
+	listLocalID        = "testhost_home_2026-03-01T10:00:00Z"
+	listRemoteID       = "otherhost_media_2026-03-02T11:22:33Z"
+	// fiveMegabytes formats as "5.0 MB" through formatBytes.
+	fiveMegabytes = 5 * 1024 * 1024
+)
+
+// TestListSnapshots_RemoteWithoutSecretKey is the regression guard for
+// issue #64: `snapshot list` must read the destination store on a host
+// that holds no private key. If the remote listing is ever gated on
+// age_secret_key again, this fails.
+func TestListSnapshots_RemoteWithoutSecretKey(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+	require.Empty(t, env.v.Config.AgeSecretKey,
+		"this test is meaningless unless the host has no private key")
+
+	timestamp := time.Date(2026, 3, 2, 11, 22, 33, 0, time.UTC)
+	remoteKey := env.addRemote(t, listRemoteID, timestamp)
+
+	err := env.v.ListSnapshots(false)
+	require.NoError(t, err)
+
+	// The destination store was actually read, with a single prefix
+	// listing rather than one request per snapshot.
+	assert.Equal(t, 1, env.store.listStreamCalls(),
+		"expected exactly one prefix listing of the destination store")
+
+	// Nothing encrypted was touched: enumerating snapshots must never
+	// need the age secret key.
+	for _, key := range env.store.fetchedKeys() {
+		assert.NotContains(t, key, ".age",
+			"listing must not read encrypted objects")
+	}
+
+	out := env.stdout.String()
+
+	// The snapshot is identified by an abbreviation of its remote key.
+	assert.Contains(t, out, "<remote only:"+remoteKey[:12]+">")
+
+	// Its human ID is not recoverable and must not be invented.
+	assert.NotContains(t, out, "otherhost")
+	assert.NotContains(t, out, "media")
+
+	// Manifest-derived columns carry real values.
+	assert.Contains(t, out, "2026-03-02 11:22:33")
+	assert.Contains(t, out, "5.0 MB")
+
+	// The two columns that require the local index are marked, not
+	// blank and not zero. ("<remote only:" does not match this needle,
+	// so the count is exactly the two marker cells.)
+	assert.Equal(t, 2, strings.Count(out, remoteOnlyCellText),
+		"expected the uncompressed and new-chunk cells to be marked")
+}
+
+// remoteOnlyCellText is the marker the table puts in columns that can
+// only be computed from the local index.
+const remoteOnlyCellText = "<remote only>"
+
+// TestListSnapshots_RemoteOnlyRowRendering pins the exact row a
+// remote-only snapshot produces, so the "<remote only>" cells and the
+// LocallyTracked == false branch are verified rather than assumed.
+func TestListSnapshots_RemoteOnlyRowRendering(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+
+	timestamp := time.Date(2026, 3, 2, 11, 22, 33, 0, time.UTC)
+	remoteKey := env.addRemote(t, listRemoteID, timestamp)
+
+	err := env.v.ListSnapshots(false)
+	require.NoError(t, err)
+
+	label := "<remote only:" + remoteKey[:12] + ">"
+	row := findTableRow(t, env.stdout.String(), label)
+
+	// Identifier column: the abbreviated remote key, never blank and
+	// visibly not a snapshot name.
+	assert.True(t, strings.HasPrefix(row, label),
+		"identifier column must lead the row: %q", row)
+
+	// Manifest-derived columns: real values, not placeholders.
+	assert.Contains(t, row, "2026-03-02 11:22:33")
+	assert.Contains(t, row, "5.0 MB")
+
+	// Exactly the two local-index-derived columns are marked.
+	assert.Equal(t, 2, strings.Count(row, remoteOnlyCellText),
+		"uncompressed and new-chunk cells must both be marked: %q", row)
+
+	// And the note explaining why the row has no name.
+	assert.Contains(t, env.stdout.String(),
+		"are not in the local index")
+}
+
+// findTableRow returns the single output line containing needle.
+func findTableRow(t *testing.T, out, needle string) string {
+	t.Helper()
+
+	var found []string
+
+	for line := range strings.SplitSeq(out, "\n") {
+		if strings.Contains(line, needle) {
+			found = append(found, line)
+		}
+	}
+
+	require.Len(t, found, 1, "expected exactly one line containing %q", needle)
+
+	return found[0]
+}
+
+// TestListSnapshots_MergesLocalAndRemote checks that both sources land
+// in one table and that a locally tracked snapshot keeps its human ID
+// and its local-index-derived columns.
+func TestListSnapshots_MergesLocalAndRemote(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+
+	localStart := time.Date(2026, 3, 1, 10, 0, 0, 0, time.UTC)
+	env.addLocal(t, listLocalID, localStart)
+	env.addRemote(t, listLocalID, localStart)
+
+	remoteKey := env.addRemote(t, listRemoteID,
+		time.Date(2026, 3, 2, 11, 22, 33, 0, time.UTC))
+
+	err := env.v.ListSnapshots(false)
+	require.NoError(t, err)
+
+	out := env.stdout.String()
+
+	assert.Contains(t, out, listLocalID)
+	assert.Contains(t, out, "<remote only:"+remoteKey[:12]+">")
+
+	// The locally tracked row is not marked as remote-only anywhere.
+	localRow := findTableRow(t, out, listLocalID)
+	assert.NotContains(t, localRow, "<remote only>")
+
+	// The local snapshot is present remotely, so no drift is reported.
+	assert.NotContains(t, out, "not found in backup destination store")
+}
+
+// TestListSnapshots_LocalOnlyReportedAsDrift covers a snapshot in the
+// local index with no counterpart on the destination store, and checks
+// the remediation hint names a command that actually exists.
+func TestListSnapshots_LocalOnlyReportedAsDrift(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+	env.addLocal(t, listLocalID, time.Date(2026, 3, 1, 10, 0, 0, 0, time.UTC))
+
+	err := env.v.ListSnapshots(false)
+	require.NoError(t, err)
+
+	out := env.stdout.String()
+
+	assert.Contains(t, out, listLocalID)
+	assert.Contains(t, out, "1 local snapshot record(s) not found in backup")
+	assert.Contains(t, out, "vaultik prune")
+
+	// There is no `vaultik snapshot cleanup` command; the hint must not
+	// name one.
+	assert.NotContains(t, out, "snapshot cleanup")
+}
+
+// TestListSnapshots_UnreachableRemoteDegrades covers the promise in the
+// doc comment: an unreachable destination is a warning plus local-only
+// output, never a failure.
+func TestListSnapshots_UnreachableRemoteDegrades(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+	env.addLocal(t, listLocalID, time.Date(2026, 3, 1, 10, 0, 0, 0, time.UTC))
+	env.store.listErr = errRemoteUnreachable
+
+	// Zero exit code: the CLI turns a nil return into exit 0.
+	err := env.v.ListSnapshots(false)
+	require.NoError(t, err)
+
+	out := env.stdout.String()
+
+	assert.Contains(t, out, "Could not list backup destination store")
+	assert.Contains(t, out, "permission denied")
+	assert.Contains(t, out, "Showing snapshots from the local index only.")
+
+	// The local index is still shown.
+	assert.Contains(t, out, listLocalID)
+
+	// With no remote listing there is no basis for a drift claim, so
+	// none must be made.
+	assert.NotContains(t, out, "not found in backup destination store")
+}
+
+// TestListSnapshots_UnreadableManifestDoesNotHideOthers checks that one
+// corrupt remote snapshot directory cannot suppress every other
+// snapshot on the destination store.
+func TestListSnapshots_UnreadableManifestDoesNotHideOthers(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+
+	goodKey := env.addRemote(t, listRemoteID,
+		time.Date(2026, 3, 2, 11, 22, 33, 0, time.UTC))
+
+	badKey := snapshot.RemoteSnapshotKey("testhost_broken_2026-03-03T00:00:00Z")
+	err := env.store.Put(context.Background(),
+		"metadata/"+badKey+"/manifest.json.zst",
+		strings.NewReader("this is not a zstd stream"))
+	require.NoError(t, err)
+
+	err = env.v.ListSnapshots(false)
+	require.NoError(t, err)
+
+	out := env.stdout.String()
+
+	assert.Contains(t, out, "<remote only:"+goodKey[:12]+">")
+	assert.NotContains(t, out, "<remote only:"+badKey[:12]+">")
+	assert.Contains(t, out, "1 remote snapshot(s) could not be described")
+}
+
+// listJSONRow mirrors the JSON shape ListSnapshots emits, so the test
+// asserts against the wire format rather than the Go struct.
+//
+//nolint:tagliatelle // snake_case is the established output format
+type listJSONRow struct {
+	ID             string `json:"id"`
+	RemoteKey      string `json:"remote_key"`
+	Timestamp      string `json:"timestamp"`
+	CompressedSize int64  `json:"compressed_size"`
+	LocallyTracked bool   `json:"locally_tracked"`
+	RemotePresent  *bool  `json:"remote_present"`
+}
+
+// decodeListJSON parses the command's stdout, which must contain
+// nothing but the JSON document.
+func decodeListJSON(t *testing.T, out string) []listJSONRow {
+	t.Helper()
+
+	var rows []listJSONRow
+
+	err := json.Unmarshal([]byte(out), &rows)
+	require.NoError(t, err, "stdout must be parseable JSON: %q", out)
+
+	return rows
+}
+
+// TestListSnapshots_JSONMergedView covers the --json view of all three
+// cases at once: tracked-and-present, tracked-but-missing remotely, and
+// remote-only.
+func TestListSnapshots_JSONMergedView(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+
+	syncedStart := time.Date(2026, 3, 1, 10, 0, 0, 0, time.UTC)
+	env.addLocal(t, listLocalID, syncedStart)
+	env.addRemote(t, listLocalID, syncedStart)
+
+	driftedID := "testhost_home_2026-02-01T10:00:00Z"
+	env.addLocal(t, driftedID, time.Date(2026, 2, 1, 10, 0, 0, 0, time.UTC))
+
+	remoteKey := env.addRemote(t, listRemoteID,
+		time.Date(2026, 3, 2, 11, 22, 33, 0, time.UTC))
+
+	err := env.v.ListSnapshots(true)
+	require.NoError(t, err)
+
+	rows := decodeListJSON(t, env.stdout.String())
+	require.Len(t, rows, 3)
+
+	byKey := make(map[string]listJSONRow, len(rows))
+	for _, row := range rows {
+		byKey[row.RemoteKey] = row
+	}
+
+	synced := byKey[snapshot.RemoteSnapshotKey(listLocalID)]
+	assert.Equal(t, listLocalID, synced.ID)
+	assert.True(t, synced.LocallyTracked)
+	require.NotNil(t, synced.RemotePresent)
+	assert.True(t, *synced.RemotePresent)
+
+	drifted := byKey[snapshot.RemoteSnapshotKey(driftedID)]
+	assert.Equal(t, driftedID, drifted.ID)
+	assert.True(t, drifted.LocallyTracked)
+	require.NotNil(t, drifted.RemotePresent)
+	assert.False(t, *drifted.RemotePresent,
+		"a local-only snapshot must be visible as drift in --json too")
+
+	remoteOnly := byKey[remoteKey]
+	assert.False(t, remoteOnly.LocallyTracked)
+	assert.Empty(t, remoteOnly.ID,
+		"the human ID is unrecoverable and must not be fabricated")
+	assert.Len(t, remoteOnly.RemoteKey, 64,
+		"--json carries the full remote key, not the truncated form")
+	assert.Equal(t, int64(fiveMegabytes), remoteOnly.CompressedSize)
+	require.NotNil(t, remoteOnly.RemotePresent)
+	assert.True(t, *remoteOnly.RemotePresent)
+}
+
+// TestListSnapshots_JSONUnreachableRemote checks that a failed listing
+// does not corrupt the JSON document with warning text, and that
+// "unknown" is reported as null rather than as absence.
+//
+//nolint:paralleltest // captureProcessStderr replaces os.Stderr
+func TestListSnapshots_JSONUnreachableRemote(t *testing.T) {
+	env := newListEnv(t)
+	env.addLocal(t, listLocalID, time.Date(2026, 3, 1, 10, 0, 0, 0, time.UTC))
+	env.store.listErr = errRemoteUnreachable
+
+	stderr := captureProcessStderr(t, func() {
+		require.NoError(t, env.v.ListSnapshots(true))
+	})
+
+	// stdout must be nothing but the JSON document, so the warning has
+	// to go to stderr.
+	rows := decodeListJSON(t, env.stdout.String())
+	require.Len(t, rows, 1)
+
+	assert.Equal(t, listLocalID, rows[0].ID)
+	assert.True(t, rows[0].LocallyTracked)
+	assert.Nil(t, rows[0].RemotePresent,
+		"remote state is unknown when the destination cannot be listed")
+
+	assert.Contains(t, stderr, "Could not list backup destination store")
+	assert.Contains(t, stderr, "permission denied")
+}
+
+// useNonUTCLocalZone points time.Local at a fixed non-UTC zone for the
+// duration of the test.
+//
+// Snapshot timestamps are stored as bare Unix seconds, so the zone a
+// reader decodes them in is a decode choice rather than stored data —
+// and on a UTC host a wrong choice is invisible. This makes it visible:
+// with time.Local at +07:13, a row decoded in local time renders 7h13m
+// away from the same instant decoded in UTC.
+//
+// time.Local is process-global, so a test using this must not call
+// t.Parallel. Go runs every non-parallel test to completion before
+// resuming any parallel one, so the mutation is not observable from
+// another test.
+//
+//nolint:gosmopolitan // pinning time.Local is the entire point here
+func useNonUTCLocalZone(t *testing.T) {
+	t.Helper()
+
+	const offsetSeconds = 7*60*60 + 13*60
+
+	previous := time.Local
+	time.Local = time.FixedZone("VaultikTest", offsetSeconds)
+
+	t.Cleanup(func() { time.Local = previous })
+}
+
+// TestListSnapshots_TimestampsAreUTCOnNonUTCHost is the regression guard
+// for the merged TIMESTAMP column. Local rows come from the index
+// database and remote-only rows come from a manifest; both render
+// through the same zone-less format string, so both have to be in the
+// same zone or the column silently shows two different wall clocks for
+// the same instant.
+//
+// This test fails on any host if either source stops normalizing to UTC,
+// because it pins time.Local to a zone that is not UTC.
+//
+//nolint:paralleltest // pins process-global time.Local; see useNonUTCLocalZone
+func TestListSnapshots_TimestampsAreUTCOnNonUTCHost(t *testing.T) {
+	log.Initialize(log.Config{})
+	useNonUTCLocalZone(t)
+
+	// One instant, rendered twice: once through a locally tracked
+	// snapshot and once through a snapshot only the destination store
+	// knows about.
+	instant := time.Date(2026, 3, 1, 10, 0, 0, 0, time.UTC)
+
+	const wallClock = "2026-03-01 10:00:00"
+
+	env := newListEnv(t)
+	env.addLocal(t, listLocalID, instant)
+	env.addRemote(t, listLocalID, instant)
+	remoteKey := env.addRemote(t, listRemoteID, instant)
+
+	err := env.v.ListSnapshots(false)
+	require.NoError(t, err)
+
+	out := env.stdout.String()
+
+	assert.Contains(t, findTableRow(t, out, listLocalID), wallClock,
+		"a locally tracked row must render in UTC like every other row")
+	assert.Contains(t,
+		findTableRow(t, out, "<remote only:"+remoteKey[:12]+">"), wallClock)
+
+	// The --json timestamp carries its zone explicitly, so rows from the
+	// two sources must be string-comparable as well.
+	jsonEnv := newListEnv(t)
+	jsonEnv.addLocal(t, listLocalID, instant)
+	jsonEnv.addRemote(t, listLocalID, instant)
+	jsonEnv.addRemote(t, listRemoteID, instant)
+
+	err = jsonEnv.v.ListSnapshots(true)
+	require.NoError(t, err)
+
+	rows := decodeListJSON(t, jsonEnv.stdout.String())
+	require.Len(t, rows, 2)
+
+	for _, row := range rows {
+		assert.Equal(t, "2026-03-01T10:00:00Z", row.Timestamp,
+			"--json timestamps must be comparable between row types")
+	}
+}
+
+// TestListSnapshots_JSONReportsUnreadableManifests checks that a
+// snapshot missing from the JSON document because its manifest could not
+// be read is still announced. Table mode says so below the table; a
+// machine consumer would otherwise see no difference between "that
+// snapshot is not on the destination" and "that snapshot could not be
+// read".
+//
+//nolint:paralleltest // captureProcessStderr replaces os.Stderr
+func TestListSnapshots_JSONReportsUnreadableManifests(t *testing.T) {
+	env := newListEnv(t)
+
+	goodKey := env.addRemote(t, listRemoteID,
+		time.Date(2026, 3, 2, 11, 22, 33, 0, time.UTC))
+
+	badKey := snapshot.RemoteSnapshotKey("testhost_broken_2026-03-03T00:00:00Z")
+	err := env.store.Put(context.Background(),
+		"metadata/"+badKey+"/manifest.json.zst",
+		strings.NewReader("this is not a zstd stream"))
+	require.NoError(t, err)
+
+	stderr := captureProcessStderr(t, func() {
+		require.NoError(t, env.v.ListSnapshots(true))
+	})
+
+	rows := decodeListJSON(t, env.stdout.String())
+	require.Len(t, rows, 1)
+	assert.Equal(t, goodKey, rows[0].RemoteKey)
+
+	assert.Contains(t, stderr, "could not be described",
+		"a row dropped from the JSON document must be announced somewhere")
+	assert.Contains(t, stderr, `"unreadable":1`,
+		"the count of dropped rows must be reported, not just the fact")
+}
+
+// maxRemoteOnlyRowsForTest mirrors the maxRemoteOnlyRows cap in the
+// package under test, which is unexported.
+const maxRemoteOnlyRowsForTest = 1000
+
+// TestListSnapshots_JSONReportsTruncation covers the row cap in --json
+// mode. Past the cap the document is a partial listing, and silent
+// truncation of a listing whose whole purpose is disaster recovery is
+// the wrong failure mode: the consumer least able to notice is exactly
+// the one reading JSON.
+//
+//nolint:paralleltest // captureProcessStderr replaces os.Stderr
+func TestListSnapshots_JSONReportsTruncation(t *testing.T) {
+	env := newListEnv(t)
+
+	timestamp := time.Date(2026, 3, 2, 11, 22, 33, 0, time.UTC)
+
+	// One past the cap, so exactly one snapshot is omitted.
+	for i := range maxRemoteOnlyRowsForTest + 1 {
+		env.addRemote(t, fmt.Sprintf("otherhost_bulk_%04d", i), timestamp)
+	}
+
+	stderr := captureProcessStderr(t, func() {
+		require.NoError(t, env.v.ListSnapshots(true))
+	})
+
+	rows := decodeListJSON(t, env.stdout.String())
+	assert.Len(t, rows, maxRemoteOnlyRowsForTest)
+
+	assert.Contains(t, stderr, "Listing truncated")
+	assert.Contains(t, stderr, `"omitted":1`)
+	assert.Contains(t, stderr,
+		fmt.Sprintf(`"limit":%d`, maxRemoteOnlyRowsForTest))
+}
+
+// captureProcessStdout redirects the process's own stdout to a pipe,
+// rebuilds the global logger, runs fn, and returns everything written to
+// the pipe.
+//
+// The logger is rebuilt on purpose even though it is supposed to write
+// to stderr: that is exactly what makes this a regression guard. If the
+// logger ever goes back to os.Stdout, Initialize picks up the pipe and
+// the log record shows up in the capture, breaking the JSON parse here
+// the same way it would break `snapshot list --json | jq` in the field.
+// Without the rebuild, a regressed logger would write to the real stdout
+// the test process was started with and go unnoticed.
+//
+// Not parallel-safe: os.Stdout and the logger are process-global.
+func captureProcessStdout(t *testing.T, fn func(stdout io.Writer)) string {
+	t.Helper()
+
+	reader, writer, err := os.Pipe()
+	require.NoError(t, err)
+
+	previous := os.Stdout
+	os.Stdout = writer
+
+	log.Initialize(log.Config{})
+
+	drained := make(chan string, 1)
+
+	go func() {
+		var buf bytes.Buffer
+
+		_, _ = io.Copy(&buf, reader)
+
+		drained <- buf.String()
+	}()
+
+	fn(writer)
+
+	os.Stdout = previous
+
+	require.NoError(t, writer.Close())
+
+	captured := <-drained
+
+	require.NoError(t, reader.Close())
+
+	// Put the logger back on the restored streams.
+	log.Initialize(log.Config{})
+
+	return captured
+}
+
+// captureProcessStderr redirects the process's own stderr to a pipe,
+// rebuilds the global logger over it, runs fn, and returns everything
+// written.
+//
+// internal/log writes every diagnostic to os.Stderr and captures that
+// file at Initialize time, so a warning logged during a listing lands on
+// the process's real stderr, not on any writer a test can inject.
+// Capturing the file descriptor is therefore the only way a test can see
+// what the operator would see. The captured stream is a pipe rather than
+// a terminal, so the records are JSON — the same form a redirected
+// stderr gets in production.
+//
+// Not parallel-safe: os.Stderr and the logger are process-global.
+func captureProcessStderr(t *testing.T, fn func()) string {
+	t.Helper()
+
+	reader, writer, err := os.Pipe()
+	require.NoError(t, err)
+
+	previous := os.Stderr
+	os.Stderr = writer
+
+	log.Initialize(log.Config{})
+
+	drained := make(chan string, 1)
+
+	go func() {
+		var buf bytes.Buffer
+
+		_, _ = io.Copy(&buf, reader)
+
+		drained <- buf.String()
+	}()
+
+	fn()
+
+	os.Stderr = previous
+
+	require.NoError(t, writer.Close())
+
+	captured := <-drained
+
+	require.NoError(t, reader.Close())
+
+	// Put the logger back on the restored streams.
+	log.Initialize(log.Config{})
+
+	return captured
+}
+
+// TestListSnapshots_JSONStdoutIsOnlyTheDocument is the regression guard
+// for `snapshot list --json | jq` surviving a damaged destination store.
+//
+// Every stdout writer the command has — the JSON encoder and the UI —
+// is pointed at one pipe here, exactly as they are pointed at one file
+// descriptor in production, and the logger is rebuilt over that same
+// pipe's process-level stdout so that a logger which regressed back to
+// stdout would land in the capture. A single log line about a corrupt
+// manifest ahead of the array is enough to break the parse, and that is
+// what this asserts cannot happen.
+//
+// The two warnings are asserted on the separately captured stderr: they
+// must be emitted, just not there.
+//
+//nolint:paralleltest // replaces os.Stdout, os.Stderr and the logger
+func TestListSnapshots_JSONStdoutIsOnlyTheDocument(t *testing.T) {
+	env := newListEnv(t)
+
+	goodKey := env.addRemote(t, listRemoteID,
+		time.Date(2026, 3, 2, 11, 22, 33, 0, time.UTC))
+
+	// A manifest that is not even a zstd stream.
+	badKey := snapshot.RemoteSnapshotKey("testhost_broken_2026-03-03T00:00:00Z")
+	err := env.store.Put(context.Background(),
+		"metadata/"+badKey+"/manifest.json.zst",
+		strings.NewReader("this is not a zstd stream"))
+	require.NoError(t, err)
+
+	// And a manifest that decodes but carries a timestamp no parser will
+	// accept: the second warning on this path.
+	oddKey := env.addRemoteRawTimestamp(t,
+		"testhost_odd_2026-03-04T00:00:00Z", "the day before yesterday")
+
+	var captured string
+
+	stderr := captureProcessStderr(t, func() {
+		captured = captureProcessStdout(t, func(stdout io.Writer) {
+			env.v.Stdout = stdout
+			env.v.UI = ui.NewWithColor(stdout, false)
+
+			require.NoError(t, env.v.ListSnapshots(true))
+		})
+	})
+
+	rows := decodeListJSON(t, captured)
+	require.Len(t, rows, 2, "the readable snapshots must both be listed")
+
+	byKey := make(map[string]listJSONRow, len(rows))
+	for _, row := range rows {
+		byKey[row.RemoteKey] = row
+	}
+
+	assert.Contains(t, byKey, goodKey)
+	assert.Contains(t, byKey, oddKey,
+		"an unparseable timestamp must not hide the snapshot itself")
+	assert.NotContains(t, byKey, badKey)
+
+	// Both warnings were emitted, on the stream that cannot corrupt the
+	// document.
+	assert.Contains(t, stderr, "Could not describe remote snapshot")
+	assert.Contains(t, stderr, "Remote manifest has an unparseable timestamp")
+	assert.Contains(t, stderr, "could not be described")
+	assert.Contains(t, stderr, `"unreadable":1`)
+}

internal/vaultik/vaultik.go

@@ -43,15 +43,26 @@ type Vaultik struct {
 	ctx    context.Context //nolint:containedctx // ctx bound at construction by design
 	cancel context.CancelFunc
 
-	// IO
+	// IO. Stdout carries the output the user asked for and nothing else,
+	// so that `--json | jq` works. Stderr completes the standard triple
+	// for anything a command needs to write there directly; diagnostics
+	// are not that — they go through internal/log, which writes to the
+	// process's stderr. No production code writes to Stderr today, so
+	// searching for its writers turns up nothing; it is kept as the
+	// injection point a direct stderr write would otherwise have to
+	// invent, and removing it would make the triple asymmetric for no
+	// gain.
 	Stdout io.Writer
 	Stderr io.Writer
 	Stdin  io.Reader
 
 	// UI is the writer for user-facing status, progress, warnings, errors.
-	// See package internal/ui for formatting conventions. Defaults to a
-	// writer wrapping Stdout; the cli layer replaces it with a discarding
-	// writer in --cron mode.
+	// See package internal/ui for formatting conventions. It always wraps
+	// Stdout and is never swapped out; under --cron (and --quiet) the cli
+	// layer instead calls UI.SetQuiet(true), which drops Begin, Complete,
+	// Info, Notice, Detail, Progress, and Banner messages. Warning and
+	// Error are still emitted in that mode, so callers must not assume
+	// that --cron makes this writer silent.
 	UI *ui.Writer
 
 	// restoreCacheObserver, if non-nil, is invoked once with the

internal/vaultik/verify.go

@@ -141,30 +141,21 @@ func (v *Vaultik) loadVerificationData(
 	// All remote paths use the hashed key derived from the human ID.
 	remoteKey := snapshot.RemoteSnapshotKey(snapshotID)
 
-	// Download manifest
-	manifestPath := fmt.Sprintf("metadata/%s/manifest.json.zst", remoteKey)
-	log.Info("Downloading manifest", "path", manifestPath)
+	// Download manifest. downloadManifestByKey is the single reader for
+	// remote manifests; see its doc comment.
+	log.Info("Downloading manifest", "remote_key", remoteKey)
 
 	if !opts.JSON {
 		v.stdoutf("Downloading manifest...\n")
 	}
 
-	manifestReader, err := v.Storage.Get(v.ctx, manifestPath)
+	manifest, err := v.downloadManifestByKey(remoteKey)
 	if err != nil {
 		return nil, nil, nil, v.deepVerifyFailure(result, opts,
 			fmt.Sprintf("failed to download manifest: %v", err),
 			fmt.Errorf("failed to download manifest: %w", err))
 	}
 
-	defer func() { _ = manifestReader.Close() }()
-
-	manifest, err := snapshot.DecodeManifest(manifestReader)
-	if err != nil {
-		return nil, nil, nil, v.deepVerifyFailure(result, opts,
-			fmt.Sprintf("failed to decode manifest: %v", err),
-			fmt.Errorf("failed to decode manifest: %w", err))
-	}
-
 	log.Info("Manifest loaded",
 		"manifest_blob_count", manifest.BlobCount,
 		"manifest_total_size", ubytes(manifest.TotalCompressedSize))

script/bootstrap

@@ -48,6 +48,55 @@ missing() {
     ! command -v "$1" >/dev/null 2>&1
 }
 
+# Docker is a hard requirement, not a nice-to-have: script/lint lints by
+# building Dockerfile.lint, whose digest-pinned golangci-lint image is
+# the only place the linter runs, and script/check and script/precommit
+# both run script/lint. A bootstrap that prints "bootstrap complete" on a
+# machine where `make check` cannot run is a false success, so this fails
+# instead.
+#
+# Installing docker from here was considered and rejected: it needs root,
+# a running daemon, and on macOS a GUI cask, so an attempt would itself
+# fail in the common case - trading one false success for a second
+# failure mode. Naming exactly what breaks is more useful.
+# Prints the problem and returns 0 when docker cannot be used; returns
+# 1 (and prints nothing) when it can.
+docker_problem() {
+    if missing docker; then
+        echo "docker is not installed"
+        return 0
+    fi
+    if ! docker info >/dev/null 2>&1; then
+        echo "the docker daemon is not reachable"
+        return 0
+    fi
+    return 1
+}
+
+require_docker() {
+    reason="$(docker_problem)" || return 0
+    cat >&2 <<EOF
+bootstrap: FAILED - $reason.
+
+Docker is required to develop this repo. Without it these do not work:
+
+  script/lint      builds Dockerfile.lint, which runs the linter as a
+                   build step in a digest-pinned golangci-lint image.
+                   That FROM line is the single source of truth for the
+                   linter version
+  script/check     runs script/lint
+  script/precommit runs script/check, so commits are blocked by the
+                   pre-commit hook installed by script/setup
+  script/cibuild   builds Dockerfile.lint and Dockerfile, which is what
+                   CI runs
+
+Install docker (and start the daemon, checking DOCKER_HOST and your
+group membership), then re-run script/bootstrap. golangci-lint on PATH
+is deliberately not a substitute: script/lint will not use it.
+EOF
+    exit 1
+}
+
 main() {
     cd "$ROOT"
 
@@ -58,18 +107,30 @@ main() {
     # Go toolchain
     if missing go; then pkg_install go golang go go; fi
 
-    # golangci-lint: packaged in nix, brew, and apk. There is no apt
-    # package; on apt systems install it manually from a hash-verified
-    # GitHub release archive (never curl | sh).
-    if missing golangci-lint; then
-        pkg_install golangci-lint golangci-lint golangci-lint golangci-lint
-    fi
+    # golangci-lint is deliberately NOT installed: script/lint lints by
+    # building Dockerfile.lint, whose digest-pinned image is the only
+    # place the linter runs, so whatever a package manager happens to
+    # ship would only be a shadow of the pinned version that could drift
+    # from CI. Nothing on the host is ever used as a linter, at any
+    # version, so installing one here would buy nothing.
 
     # sqlite3 CLI: the test suite shells out to it (VACUUM).
     if missing sqlite3; then pkg_install sqlite sqlite3 sqlite sqlite; fi
 
+    # goreleaser, at the version pinned by script/install-goreleaser and
+    # verified against a hardcoded sha256. Package managers are not used
+    # for it: they ship whatever version they happen to carry, and the
+    # tool that builds a release has to be a known one. The install is
+    # its own script because the release workflow needs goreleaser
+    # without needing the Docker requirement below.
+    "$ROOT/script/install-goreleaser"
+
     go mod download
 
+    # Last, so that everything installable is installed before the one
+    # thing this script cannot install decides the outcome.
+    require_docker
+
     echo "bootstrap complete"
 }
 

script/cibuild

@@ -1,14 +1,63 @@
 #!/bin/sh
-# script/cibuild: run the CI build. The Dockerfile runs script/check
-# (via make check), so a successful build implies all checks pass.
-# Generic: needs no adaptation. The Gitea workflow runs this on push.
+# script/cibuild: run the CI build. This is the full gate, and it is two
+# builds, in this order:
+#
+#   Dockerfile.lint  the linter, as a build step (a clean build IS a
+#                    clean lint)
+#   Dockerfile       `make fmt-check` and `make test` in the builder
+#                    stage, then the product image
+#
+# Either one failing fails this script. Note what follows from the
+# split: script/docker builds only the product image and so no longer
+# lints -- this script and script/check (which runs script/lint) are the
+# things that decide whether the tree is clean.
+#
+# Generic apart from the two Dockerfiles: the Gitea workflow runs this
+# on push.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build .
+    # Both Dockerfiles key their check layers on CHECK_EPOCH, so a fresh
+    # value is what forces those layers to re-run: without it an
+    # unchanged tree replays them from cache, the checks never execute,
+    # and the build still exits 0. Each ARG sits immediately above the
+    # check RUNs, so dependency and module layers still cache. Both
+    # Dockerfiles also refuse to build at all when CHECK_EPOCH is empty,
+    # so a missing value fails loudly here rather than passing quietly.
+    #
+    # The value must be unique per invocation, not per second. `date +%s`
+    # is second-granular, so two concurrent invocations in the same
+    # second get identical epochs and the later one can be served from
+    # cache -- the original defect in miniature. `%N` alone does not fix
+    # it: busybox silently drops %N, exits 0, and hands back second
+    # granularity with no warning. `$$` is what makes this correct
+    # regardless, since concurrent invocations have different pids.
+    #
+    # Assign the epoch on its own line rather than inline in the
+    # argument. Under `set -eu` a command substitution that fails
+    # inside an argument does NOT abort the script: CHECK_EPOCH would
+    # become an empty string, an empty string is a constant, and a
+    # constant CHECK_EPOCH is exactly the cached-check false green this
+    # script exists to prevent -- so the guard would disarm itself and
+    # still exit 0. As a bare assignment, `set -e` catches a failing
+    # `date` and no build starts.
+    #
+    # A separate value per build, because they are separate builds: one
+    # `date` shared between them would still be fresh, but reusing it
+    # invites the two to be collapsed into a single value that is
+    # computed somewhere else and passed in.
+    epoch="$(date +%s%N)$$"
+    # cacheonly for the lint build: its verdict is the exit status and
+    # the image is never run, so exporting it is pure cost. See
+    # script/lint.
+    docker build --output=type=cacheonly \
+        --build-arg CHECK_EPOCH="$epoch" -f Dockerfile.lint .
+
+    epoch="$(date +%s%N)$$"
+    docker build --build-arg CHECK_EPOCH="$epoch" .
 }
 
 main "$@"

script/docker

@@ -2,6 +2,13 @@
 # script/docker: build the Docker image tagged with the project name.
 # Identical in all repos; the tag comes from script/projectname.
 # Generic: needs no adaptation.
+#
+# This builds the PRODUCT image only, and the product Dockerfile has no
+# lint stage: linting lives in Dockerfile.lint and is run by
+# script/lint. So a green here means `make fmt-check` and `make test`
+# passed and the image built -- it says nothing about lint. The gates
+# are script/check (which runs script/lint) and script/cibuild (which
+# builds both files).
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -9,7 +16,16 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build -t "$("$SCRIPT_DIR/projectname")" .
+    # Same CHECK_EPOCH contract as script/cibuild, for the same reason
+    # and with the same bare-assignment and `$$` requirements -- see the
+    # comments there. This script is not the CI gate, but a local build
+    # is almost always warm, so without this it would report a green the
+    # tree had not earned and the two entrypoints would disagree about
+    # whether the tree is clean. The Dockerfile now refuses to build
+    # without a non-empty value, so this is required, not optional.
+    epoch="$(date +%s%N)$$"
+    docker build --build-arg CHECK_EPOCH="$epoch" \
+        -t "$("$SCRIPT_DIR/projectname")" .
 }
 
 main "$@"

script/install-goreleaser

@@ -0,0 +1,144 @@
+#!/bin/sh
+# script/install-goreleaser: install the pinned goreleaser into the
+# repo-local tool directory. Our own extension to
+# scripts-to-rule-them-all. Idempotent: exits immediately when the
+# pinned version is already available.
+#
+# script/bootstrap calls this, and so does .gitea/workflows/release.yml.
+# It is a separate script rather than an inline block in bootstrap
+# because bootstrap deliberately hard-fails on a machine without a
+# usable Docker daemon (Docker gates script/lint, and therefore
+# script/check), while the release runner needs goreleaser and does not
+# need Docker. One script, two callers, no duplicated pin.
+#
+# The install is a specific GitHub release archive verified against the
+# sha256 hardcoded below, per REPO_POLICIES.md: no `curl | sh`, no
+# `@latest`, no version tag that a server can move. Bumping goreleaser
+# means editing GORELEASER_VERSION *and* the four checksums, which are
+# taken from the checksums.txt published with that release.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# goreleaser v2.17.1, 2026-08-05. Checksums are from
+# https://github.com/goreleaser/goreleaser/releases/download/v2.17.1/checksums.txt
+GORELEASER_VERSION="2.17.1"
+SHA256_LINUX_X86_64="a99bbc7ae0d8d897b07c4c497a9b62f222558804715ef219d1af05a7e417bc80"
+SHA256_LINUX_ARM64="702f03769ac8bcb0e47839c82243cc614ae995633599a98c63062e13ea85f829"
+SHA256_DARWIN_X86_64="a92a68c61a6833ff67748f532cbebc7b8e49ba30de062ab463b221211ee6368f"
+SHA256_DARWIN_ARM64="b65624885c25da9a677b7ad11cf86a02123cc5a56af66f6b4ebb574658eada2e"
+
+TOOLBIN="$ROOT/.tool/bin"
+
+# Print the version of the goreleaser at $1, or nothing if it is not
+# usable. `goreleaser --version` prints a multi-line banner; the version
+# is on the line beginning "GitVersion:".
+goreleaser_version() {
+    [ -x "$1" ] || return 0
+    "$1" --version 2>/dev/null |
+        sed -n 's/^ *GitVersion: *//p' |
+        head -n 1
+}
+
+verify_sha256() {
+    file="$1"
+    want="$2"
+    if command -v sha256sum >/dev/null 2>&1; then
+        got="$(sha256sum "$file" | cut -d' ' -f1)"
+    elif command -v shasum >/dev/null 2>&1; then
+        got="$(shasum -a 256 "$file" | cut -d' ' -f1)"
+    else
+        echo "install-goreleaser: no sha256sum or shasum available" >&2
+        return 1
+    fi
+    if [ "$got" != "$want" ]; then
+        echo "install-goreleaser: checksum mismatch for $file" >&2
+        echo "  expected: $want" >&2
+        echo "  actual:   $got" >&2
+        return 1
+    fi
+}
+
+main() {
+    cd "$ROOT"
+
+    # Already have it, either on PATH or from a previous run? Then stop.
+    # An arbitrary PATH goreleaser is NOT accepted: the config uses
+    # version-2 schema features, and the whole point of pinning is that
+    # a release is cut by a known build of a known tool.
+    if [ "$(goreleaser_version "$(command -v goreleaser || true)")" \
+        = "$GORELEASER_VERSION" ]; then
+        echo "goreleaser $GORELEASER_VERSION already on PATH"
+        return 0
+    fi
+    if [ "$(goreleaser_version "$TOOLBIN/goreleaser")" \
+        = "$GORELEASER_VERSION" ]; then
+        echo "goreleaser $GORELEASER_VERSION already installed in .tool/bin"
+        return 0
+    fi
+
+    os="$(uname -s)"
+    arch="$(uname -m)"
+    case "$os" in
+        Linux) ;;
+        Darwin) ;;
+        *)
+            echo "install-goreleaser: unsupported OS $os" >&2
+            exit 1
+            ;;
+    esac
+    case "$arch" in
+        x86_64 | amd64) arch="x86_64" ;;
+        arm64 | aarch64) arch="arm64" ;;
+        *)
+            echo "install-goreleaser: unsupported architecture $arch" >&2
+            exit 1
+            ;;
+    esac
+
+    case "${os}_${arch}" in
+        Linux_x86_64) sum="$SHA256_LINUX_X86_64" ;;
+        Linux_arm64) sum="$SHA256_LINUX_ARM64" ;;
+        Darwin_x86_64) sum="$SHA256_DARWIN_X86_64" ;;
+        Darwin_arm64) sum="$SHA256_DARWIN_ARM64" ;;
+        *)
+            echo "install-goreleaser: no pinned checksum for ${os}_${arch}" >&2
+            exit 1
+            ;;
+    esac
+
+    archive="goreleaser_${os}_${arch}.tar.gz"
+    url="https://github.com/goreleaser/goreleaser/releases/download/v${GORELEASER_VERSION}/${archive}"
+
+    if ! command -v curl >/dev/null 2>&1; then
+        echo "install-goreleaser: curl is required" >&2
+        exit 1
+    fi
+
+    tmp="$(mktemp -d)"
+    # shellcheck disable=SC2064 # expand $tmp now, not at trap time
+    trap "rm -rf '$tmp'" EXIT INT TERM
+
+    echo "installing goreleaser $GORELEASER_VERSION for ${os}_${arch}"
+    curl -fsSL --retry 3 -o "$tmp/$archive" "$url"
+    verify_sha256 "$tmp/$archive" "$sum"
+
+    tar -xzf "$tmp/$archive" -C "$tmp" goreleaser
+    mkdir -p "$TOOLBIN"
+    # Move into place via a temp name in the destination directory so a
+    # concurrent run never observes a half-written binary.
+    mv "$tmp/goreleaser" "$TOOLBIN/.goreleaser.$$"
+    chmod 0755 "$TOOLBIN/.goreleaser.$$"
+    mv "$TOOLBIN/.goreleaser.$$" "$TOOLBIN/goreleaser"
+
+    installed="$(goreleaser_version "$TOOLBIN/goreleaser")"
+    if [ "$installed" != "$GORELEASER_VERSION" ]; then
+        echo "install-goreleaser: installed binary reports '$installed'," \
+            "expected '$GORELEASER_VERSION'" >&2
+        exit 1
+    fi
+
+    echo "goreleaser $GORELEASER_VERSION installed to .tool/bin"
+}
+
+main "$@"

script/lint

@@ -1,12 +1,108 @@
 #!/bin/sh
 # script/lint: run the linter.
+#
+# The linter runs inside the image built by Dockerfile.lint, and it runs
+# there as a BUILD STEP: a successful build of that file IS a clean
+# lint. Nothing lints on the host, at any version, ever. That FROM line
+# is the single source of truth for the linter version in this repo, so
+# a local run and a CI run of the same tree cannot disagree.
+#
+# One container per run means one lint cache and one golangci-lint lock
+# per run, both private to that run and thrown away with it. That is
+# what makes concurrent runs on a shared host safe, and it is why this
+# script no longer carries per-worktree cache directories, a lock-retry
+# loop, or an output audit: there is no shared state left for them to
+# defend (issue https://git.eeqj.de/sneak/vaultik/issues/113).
+#
+# To watch the linter execute, set BUILDKIT_PROGRESS=plain, which docker
+# honours directly:
+#
+#   BUILDKIT_PROGRESS=plain script/lint
+#
+# The check layers -- `golangci-lint config verify` and then
+# `golangci-lint run` -- must appear as executing rather than CACHED on
+# every run; see the CHECK_EPOCH comment in Dockerfile.lint.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+DOCKERFILE="$ROOT/Dockerfile.lint"
+
+require_docker() {
+    if ! command -v docker >/dev/null 2>&1; then
+        cat >&2 <<EOF
+lint: docker is required to run the pinned linter.
+
+  lint image declared by: $DOCKERFILE
+
+Install docker. Linting with any other golangci-lint is not supported:
+it is what lets a local run pass while CI fails. A golangci-lint on
+PATH is never used, whatever its version.
+EOF
+        exit 1
+    fi
+    if ! docker info >/dev/null 2>&1; then
+        cat >&2 <<EOF
+lint: the docker daemon is not reachable, so the pinned linter cannot
+run.
+
+  lint image declared by: $DOCKERFILE
+
+Start the daemon (and check DOCKER_HOST / your group membership). This
+script will not fall back to a different linter version or to an
+unpinned binary on PATH.
+EOF
+        exit 1
+    fi
+}
+
+usage() {
+    cat >&2 <<EOF
+usage: $(basename "$0")
+
+script/lint takes no arguments. The linter runs as a build step, so
+there is no command line to pass flags to; anything accepted here would
+have to be silently dropped. To apply autofixes, use script/lint-fix,
+which runs the same pinned image as a container for exactly this
+reason.
+EOF
+    exit 2
+}
 
 main() {
+    [ "$#" -eq 0 ] || usage
+
     cd "$ROOT"
-    golangci-lint run ./...
+    require_docker
+
+    # A fresh epoch per invocation is what forces the check layers to
+    # execute; the layers above the ARG in Dockerfile.lint still cache,
+    # so a run is not cold. The value must be unique per invocation, not
+    # per second: `date +%s` is second-granular, so two concurrent
+    # invocations in the same second would get identical epochs and the
+    # later one could be served from cache -- the false green in
+    # miniature. `%N` alone does not fix it either, because busybox
+    # silently drops %N, exits 0, and hands back second granularity with
+    # no warning. `$$` is what makes this correct regardless, since
+    # concurrent invocations have different pids.
+    #
+    # Assign it on its own line rather than inline in the argument.
+    # Under `set -eu` a command substitution that fails inside an
+    # argument does NOT abort the script: CHECK_EPOCH would become an
+    # empty string, an empty string is a constant, and a constant epoch
+    # is exactly the cached-lint false green this guards against. As a
+    # bare assignment, `set -e` catches a failing `date` and no build
+    # starts.
+    epoch="$(date +%s%N)$$"
+
+    # cacheonly: the lint verdict is the build's exit status, and the
+    # image it would otherwise produce is never run. Exporting it costs
+    # most of the wall time of a warm run and leaves a dangling image
+    # behind on every invocation, on a host that may be running many.
+    docker build \
+        --output=type=cacheonly \
+        --build-arg CHECK_EPOCH="$epoch" \
+        -f "$DOCKERFILE" \
+        "$ROOT"
 }
 
 main "$@"

script/lint-fix

@@ -1,15 +1,54 @@
 #!/bin/sh
 # script/lint-fix: run the linter's autofixer. Rewrites files in place
 # for every finding the enabled linters know how to fix; findings
-# without an autofix are reported but left alone (exit status is
-# nonzero while any remain).
+# without an autofix are reported but left alone.
+#
+# THIS IS A DEVELOPER CONVENIENCE AND NEVER A GATE. Nothing in
+# script/check, script/precommit or script/cibuild calls it, and no gate
+# reads its exit status. The gate is script/lint, which builds
+# Dockerfile.lint; run that afterwards to find out whether the tree is
+# actually clean.
+#
+# Unlike script/lint this cannot be a build step: a build step writes
+# into an image, and fixes have to land in the worktree. So it runs the
+# same pinned image as a container with the tree bind-mounted, which
+# means it needs a LOCAL docker daemon -- a remote daemon has no access
+# to these files, and this script will appear to do nothing there. The
+# image reference is parsed out of Dockerfile.lint's FROM line, so the
+# autofixer is always the same version as the linter that gates; fixes
+# written by a different version are not necessarily fixes for the
+# version that decides.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+DOCKERFILE="$ROOT/Dockerfile.lint"
+
+# The image reference from Dockerfile.lint, tag and digest included.
+lint_image() {
+    awk '$1 == "FROM" { print $2; exit }' "$DOCKERFILE"
+}
 
 main() {
     cd "$ROOT"
-    golangci-lint run --fix ./...
+
+    image="$(lint_image)"
+    if [ -z "$image" ]; then
+        echo "lint-fix: no FROM line found in $DOCKERFILE" >&2
+        exit 1
+    fi
+
+    # Run as the invoking user so the rewritten files stay owned by
+    # them. HOME is set because the Go and golangci-lint caches default
+    # under it and that user has no home inside the container; those
+    # caches are per-container and discarded with it.
+    docker run --rm \
+        --user "$(id -u):$(id -g)" \
+        --env HOME=/tmp \
+        --env GOFLAGS=-buildvcs=false \
+        --volume "$ROOT:/src" \
+        --workdir /src \
+        "$image" \
+        golangci-lint run --config .golangci.yml --fix "$@" ./...
 }
 
 main "$@"

script/release

@@ -0,0 +1,92 @@
+#!/bin/sh
+# script/release: build and publish the release artifacts with the
+# pinned goreleaser. Our own extension to scripts-to-rule-them-all.
+#
+# Normally invoked by a tag push through .gitea/workflows/release.yml,
+# not by hand: a release cut from a workstation is a release nobody can
+# reproduce. Any arguments are passed through to `goreleaser release`,
+# which is how script/release-snapshot adds --snapshot.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+# Keep in sync with script/install-goreleaser, which owns the pin.
+GORELEASER_VERSION="2.17.1"
+
+goreleaser_version() {
+    [ -x "$1" ] || return 0
+    "$1" --version 2>/dev/null |
+        sed -n 's/^ *GitVersion: *//p' |
+        head -n 1
+}
+
+# Resolve the goreleaser to run, on the same rule script/lint uses for
+# golangci-lint: a binary on PATH is accepted only when it is exactly
+# the pinned version, because a differently versioned tool would
+# produce a differently built release from the same tag. Anything else
+# comes from .tool/bin, and a missing one is a loud failure naming the
+# script that installs it rather than a silent fallback.
+resolve_goreleaser() {
+    path_bin="$(command -v goreleaser || true)"
+    if [ -n "$path_bin" ] &&
+        [ "$(goreleaser_version "$path_bin")" = "$GORELEASER_VERSION" ]; then
+        echo "$path_bin"
+        return 0
+    fi
+    if [ "$(goreleaser_version "$ROOT/.tool/bin/goreleaser")" \
+        = "$GORELEASER_VERSION" ]; then
+        echo "$ROOT/.tool/bin/goreleaser"
+        return 0
+    fi
+    return 1
+}
+
+main() {
+    cd "$ROOT"
+
+    if ! bin="$(resolve_goreleaser)"; then
+        cat >&2 <<EOF
+release: goreleaser $GORELEASER_VERSION is not available.
+
+Run script/bootstrap (or script/install-goreleaser directly) to install
+it. A goreleaser already on PATH is used only when it reports exactly
+$GORELEASER_VERSION; any other version is refused rather than used,
+because the released binaries must come from a known build of a known
+tool.
+EOF
+        exit 1
+    fi
+
+    snapshot=0
+    for arg in "$@"; do
+        [ "$arg" = "--snapshot" ] && snapshot=1
+    done
+
+    if [ "$snapshot" -eq 0 ]; then
+        # Publishing needs a Gitea token. Check it here so the failure
+        # names the secret, rather than after several minutes of
+        # cross-compiling.
+        if [ -z "${GITEA_TOKEN:-}" ]; then
+            cat >&2 <<'EOF'
+release: GITEA_TOKEN is not set.
+
+Publishing needs a Gitea API token with write access to this
+repository's releases. In CI it comes from the RELEASE_TOKEN repository
+secret (see .gitea/workflows/release.yml and the Releasing section of
+README.md). To build without publishing, use script/release-snapshot.
+EOF
+            exit 1
+        fi
+        # goreleaser picks its forge from whichever token variable is
+        # set and refuses to run when it finds more than one. A CI
+        # runner may export a GITHUB_TOKEN of its own; this repo lives
+        # on Gitea and releases only there, so an unrelated token must
+        # not be allowed to decide where the artifacts are published.
+        unset GITHUB_TOKEN GITLAB_TOKEN
+    fi
+
+    exec "$bin" release --clean "$@"
+}
+
+main "$@"

script/release-snapshot

@@ -0,0 +1,18 @@
+#!/bin/sh
+# script/release-snapshot: build the full set of release artifacts
+# without publishing or tagging anything. Our own extension to
+# scripts-to-rule-them-all.
+#
+# This is the dry run for script/release: same goreleaser, same config,
+# same cross-compile matrix and checksums, into ./dist. The version it
+# stamps is the honest dev-<shortcommit> string rather than an invented
+# release number, so a snapshot binary cannot be mistaken for one.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    exec "$SCRIPT_DIR/release" --snapshot "$@"
+}
+
+main "$@"

script/test

@@ -6,11 +6,62 @@ set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# The flags live in one function so the quiet run and the verbose rerun
+# below cannot drift apart. A rerun that used different flags would
+# diagnose a different program than the one that failed.
+#
+# -count=1 is the documented way to bypass Go's test result cache, and
+# it is not optional here. Without it, a package whose inputs are
+# unchanged prints `ok <pkg> (cached)`, and that line is
+# indistinguishable -- to every check this repo performs -- from a
+# package that actually ran. The whole suite reports its full set of
+# `ok` lines in under half a second having executed nothing. That
+# matters beyond the local inner loop: the Dockerfile's `RUN make test`
+# is forced to re-execute by CHECK_EPOCH, but a GOCACHE baked into an
+# earlier image layer survives into the re-executed step, so the step
+# can re-run and still do no work. It is applied unconditionally rather
+# than only in the containerised path because the pre-commit hook runs
+# this same script; a gate that is honest only in CI is dishonest
+# exactly where people lean on it most.
+#
+# -timeout is a hang backstop, not a performance budget: its job is to
+# turn a deadlocked test into a stack dump instead of a wedged CI job,
+# so it wants to sit far above the slowest legitimate runtime, not just
+# above it. It is per test binary and covers test execution only -- the
+# clock starts inside testing.M.Run, after compilation and linking, so
+# build time is not charged against it. (Measured: a containerised run
+# with an empty GOCACHE reports per-package durations within noise of a
+# warm host run. A shell `timeout 30 go test ./...` would include
+# compilation, but that is a different mechanism from this flag.)
+#
+# The 120s value DELIBERATELY DIVERGES from REPO_POLICIES.md:192, which
+# mandates "Add a 30-second timeout", and from that file's canonical Go
+# recipe at :212-214, which uses -timeout 30s. REPO_POLICIES.md is
+# org-canonical and cannot be amended from this repo, so the divergence
+# is recorded here instead, and issue #101 proposes amending the policy
+# text upstream. Do not revert this to 30s without reading #101 first.
+#
+# Why it diverges: the slowest packages are internal/database and
+# internal/vaultik, observed under -race at about 6.4s warm, 8.1s in a
+# cold containerised run on a contended host, and 10.2s in an
+# independent cold run on this same host. The worst case is not tightly
+# characterised -- each fresh measurement has come in above the last --
+# which is itself an argument for generous headroom. Against the 10.2s
+# observation, 30s is only 2.9x: not a safety margin but a flake
+# waiting for a slow day, whose failure mode is a timeout that looks
+# like a real defect. 120s leaves about 12x while still bounding a hung
+# package -- including the verbose rerun below -- to a few minutes. The
+# cost of that choice, also recorded on #101: because of the rerun, a
+# hung package pays the timeout twice.
+run_tests() {
+    go test -race -timeout 120s -count=1 "$@" ./...
+}
+
 main() {
     cd "$ROOT"
-    go test -race -timeout 30s ./... || {
+    run_tests || {
         echo "--- Rerunning with -v for details ---"
-        go test -race -timeout 30s -v ./...
+        run_tests -v
         exit 1
     }
 }

script/version

@@ -0,0 +1,73 @@
+#!/bin/sh
+# script/version: output the version string to bake into the binary.
+# Our own extension to scripts-to-rule-them-all, and the single source
+# of truth for the version: the Makefile's LDFLAGS call this rather
+# than carrying a hardcoded constant, which is what used to make every
+# local build claim to be 1.0.0-rc.1 regardless of git state.
+#
+# The rules, in order:
+#
+#   HEAD is exactly on an annotated or lightweight tag
+#       -> that tag, with a leading "v" stripped
+#   anything else
+#       -> "dev-<12 chars of HEAD>"
+#   not a git checkout at all (release tarball, `go install`)
+#       -> "dev"
+#
+# Either of the first two gains a "-dirty" suffix when tracked files
+# have uncommitted changes, because a modified checkout of v1.0.0 is
+# not v1.0.0. Untracked files are ignored, matching `git describe
+# --dirty`: a stray scratch file does not change what was compiled.
+#
+# The "v" is stripped so that a `make` build and a goreleaser build of
+# the same tagged commit report the *same* string: goreleaser's
+# {{ .Version }} is the tag without the prefix, and the release archive
+# names are built from it. A tag named `v1.0.0` therefore produces
+# `vaultik 1.0.0`, matching `vaultik_1.0.0_linux_amd64.tar.gz`.
+#
+# Nothing here ever invents a version number. An untagged build says so
+# and names the commit it was built from; it does not round up to the
+# nearest plausible release.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# Length of the commit prefix in a dev version. Matches
+# globals.ShortCommit, so `vaultik version` shows the same 12 chars in
+# its version line and its commit line.
+SHORT_LEN=12
+
+main() {
+    cd "$ROOT"
+
+    if ! git rev-parse --git-dir >/dev/null 2>&1; then
+        echo "dev"
+        return 0
+    fi
+
+    dirty=""
+    if [ -n "$(git status --porcelain --untracked-files=no 2>/dev/null)" ]; then
+        dirty="-dirty"
+    fi
+
+    # --exact-match so a *descendant* of a tag is not reported as that
+    # tag. Plain `git describe --tags` would call a commit 40 patches
+    # past v1.0.0 "v1.0.0-40-gabc1234", and the leading token of that is
+    # a released version the build is not.
+    tag="$(git describe --tags --exact-match HEAD 2>/dev/null || true)"
+    if [ -n "$tag" ]; then
+        echo "${tag#v}${dirty}"
+        return 0
+    fi
+
+    sha="$(git rev-parse "--short=$SHORT_LEN" HEAD 2>/dev/null || true)"
+    if [ -z "$sha" ]; then
+        # A repo with no commits at all.
+        echo "dev"
+        return 0
+    fi
+
+    echo "dev-${sha}${dirty}"
+}
+
+main "$@"