fix(devcontainer): mount the cache volumes at the roots the tools use

[Syndic]

The gap

Both named volumes missed most of what they were supposed to persist. Measured in a container built from current main (3b10601), with findmnt naming which paths were actually volumes:

Cache	Real path	Persisted before?	Size
Bazel output base	~/.cache/bazel	yes	23G
GOCACHE	~/.cache/go-build	no	1.9G
bazelisk downloads	~/.cache/bazelisk	no	61M
pre-commit hook envs	~/.cache/pre-commit	no	13M
uv	~/.cache/uv	no	—
$GOPATH/pkg (module + checksum-db caches)	/go/pkg	no	544M
—	~/go	yes	written by nothing

Two separate bugs:

• ud-bazel-cache targeted ~/.cache/bazel, one directory inside the cache root, so its four siblings were container-local.
• ud-go-cache targeted ~/go, but features/go bakes GOPATH=/go into the image ENV. Running the image with no volumes at all is the check that settles it:

$ docker run --rm --entrypoint /bin/bash vsc-busy-nash-… -lc 'go env GOPATH GOMODCACHE; ls /go; ls /home/vscode/go; ls /home/vscode/.cache'
/go
/go/pkg/mod
bin                                                   # /go holds only bin/
ls: cannot access '/home/vscode/go': No such file or directory
ls: cannot access '/home/vscode/.cache': No such file or directory

So ~/go is a path nothing in the container writes, while the real Go state at /go/pkg was discarded on every rebuild.

Neither fails loudly. The container just rebuilds those caches every time, which reads as "devcontainers are slow".

The fix

Two volumes, each at the root of what it persists:

• ud-cache → ~/.cache
• ud-go-pkg-cache → /go/pkg

Why the whole of ~/.cache, not per-tool volumes. Per-tool only persists what someone remembered to enumerate, which is precisely the failure being fixed — bazelisk was silently missing and nobody noticed. Mounting the root means a tool that starts caching under XDG is covered with no edit. Nothing under it wants to stay ephemeral either: every entry is content-addressed or key-validated by its own tool, and CI builds cold, so a stale local cache can't reach main.

Why $GOPATH/pkg and not $GOPATH. /go/bin is image content — features/go builds ten tools there at image-build time — and Docker only seeds a volume from the image while the volume is empty. A volume over all of /go would freeze bin/ at whatever the image held on first mount, so a later feature bump would install tools nobody ever sees. Persisting it buys nothing anyway: post-create.sh reinstalls its six pinned tools over the image's copies on every create. pkg/ is the derived half of GOPATH, bin/ the artifact half.

Why not $GOMODCACHE alone. The checksum-db cache is a sibling of the module cache at /go/pkg/sumdb, and Docker creates the /go/pkg mountpoint parent root-owned, so the first go install dies on open /go/pkg/sumdb/sum.golang.org/latest: no such file or directory.

Nesting a ~/.cache volume under the existing ~/.cache/bazel one would have worked mechanically, but leaves two volumes with overlapping meaning and no axis separating them — bazel clean --expunge already gives per-tool discard from inside the container. So ud-bazel-cache is retired rather than kept.

post-create.sh's chown follows the new targets and is now guarded on current ownership. Unconditional chown -R over a warm ~/.cache is minutes spent re-asserting ownership that is already correct, and it would flatten the go feature's vscode:golang group.

Validation

All run in the devcontainer.

Persistence. Sentinels written in one container, then devcontainer up --remove-existing-container, then read back in the next:

--- container id (previous was fe3c0a7f11b8) ---
d6d13ad9db25
--- sentinels written by the PREVIOUS container ---
/home/vscode/.cache/SENTINEL-busy-nash   busy-nash-fd3c66 2026-08-19T18:46:31Z
/go/pkg/SENTINEL-busy-nash               busy-nash-fd3c66 2026-08-19T18:46:31Z
--- what survived, by size ---
1.9G  ~/.cache/go-build     61M  ~/.cache/bazelisk    13M  ~/.cache/pre-commit
544M  /go/pkg/mod           12K  /go/pkg/sumdb

/go/bin is not shadowed — the four tools post-create.sh does not install keep the image's date next to the six it does:

-rwxrwxr-x golint         2026-08-18 15:48    # image layer
-rwxrwxr-x goplay         2026-08-18 15:48    # image layer
-rwxrwxr-x revive         2026-08-18 15:48    # image layer
-rwxrwxr-x staticcheck    2026-08-18 15:48    # image layer
-rwxr-xr-x golangci-lint  2026-08-19 11:46    # post-create, pinned
-rwxr-xr-x gopls          2026-08-19 11:46    # post-create, pinned
… (ten total)

Ownership — the go feature's group survives on /go, and only the mount targets are re-owned:

/go vscode:golang 2775    /go/bin vscode:golang 2775
/go/pkg vscode:vscode 755    /home/vscode/.cache vscode:vscode 755

The chown is load-bearing for both targets, probed with fresh volumes against the bare image so no hook had run:

/go/pkg root:root 755
/home/vscode/.cache root:root 755
touch: cannot touch '/go/pkg/probe': Permission denied
touch: cannot touch '/home/vscode/.cache/probe': Permission denied

That corrected a claim carried over from the earlier attempt at this change, which said /go/pkg was the target that "actually arrives root-owned". The image has a directory at neither, so both do; the comment and the CLAUDE.md bullet say that now.

Warm effect. In the freshly recreated container: go build ./... 0.70s, pre-commit install-hooks 0.35s. The recreate's postCreateCommand did not re-download bazel 9.2.0 and uv sync reported Checked 6 packages rather than installing them — both were a download and an install on the pre-change container in the same session.

Suite. bazel test //... — 22/22 pass. pre-commit run --all-files — all seven hooks pass.

New tests are mutation-checked — each of these makes //.devcontainer:test_devcontainer_config fail, and reverting makes it pass:

1. widening the go mount to /go (with the chown loop widened to match, so it is the root assertion catching it, not the agreement one)
2. narrowing the cache mount back to ~/.cache/bazel
3. dropping /go/pkg from the chown loop
4. replacing the loop with a plain chown line

Notes for the reviewer

• After merging, docker volume rm ud-bazel-cache ud-go-cache reclaims the two now-unreferenced volumes (~23G for ud-bazel-cache on this host). Don't run it while other worktrees' containers are still up — they hold the old mounts until they are recreated.
• Related, and a thing that misled an earlier pass at this: a volume's content is shared across every checkout of this repo on the host, but its mount point is per-container. A container on the old config shows ud-go-cache at ~/go full of files that a container on this branch wrote at /go, which reads as "~/go was live" and isn't. findmnt, or docker run against the bare image, is what settles it.
• .claude/CLAUDE.md gains a "Devcontainer cache volumes" section — expect a possible trivial conflict with ci(bazel): namespace the repository cache per workflow #229 and ci: cache Go modules at every setup-go call site #230, which also append sections to that file.
• This supersedes fix(devcontainer): mount the cache volumes at the roots the tools use #231, which implemented the same design but went CONFLICTING after fix(shellcheck): follow source= directives, and move the check into the editor #232 touched four of its five files. Re-applied cleanly on 3b10601 rather than rebased.
• govulncheck is red on pristine main right now (four Go 1.26.5 stdlib advisories, fixed in 1.26.6). Pre-existing and unrelated to this branch.

🤖 Generated with Claude Code