fix: resolve github.com reliably via explicit DNS upstreams

[ChrisSc]

Problem

Inside claude-code, github.com failed to resolve (Could not resolve host) while every other GitHub host (api., codeload., objects.githubusercontent.com, …) worked. The firewall log showed the same thing at boot: could not resolve github.com.

Root cause

On Docker Desktop, the embedded resolver forwards to host(192.168.65.7), which goes through the macOS system resolver (mDNSResponder). On a lossy link, that layer caches dropped upstream queries as negative answers:

Path	NXDOMAIN	Timeouts
Mac → 8.8.8.8 / 8.8.4.4 (UDP + TCP)	0 / 120	~10–15%
Container → 8.8.8.8 directly	0 / 40	9 / 40
Container → 127.0.0.11 (Docker → host resolver)	38 / 40	2 / 40

dns-sd -G v4 github.com on the host flipped between real A records and No Such Record. The bad answer comes from the resolver layer, not from the network. github.com has a 60s TTL and is re-queried constantly, so it hits this far more than long-TTL hosts. A timeout gets retried; a cached NXDOMAIN fails immediately.

Fix

• compose.yaml: dns: [8.8.8.8, 8.8.4.4] on claude-code, so the embedded resolver queries Google directly instead of the host resolver cache. 127.0.0.11 stays the container's nameserver.
• init-firewall.sh: explicit upstreams are dialed from inside the container netns (unlike host(x) upstreams). Without an allow, strict mode's OUTPUT DROP turned every lookup into SERVFAIL (reproduced). The script now allows udp+tcp/53 to the plain # ExtServers: entries Docker writes into resolv.conf. DNS to any other destination stays dropped, and these are the same recursive resolvers 127.0.0.11 already forwards to, so there's no new tunnel surface. It also adds a post-clamp DNS check, so a resolver failure isn't misreported as "GitHub ranges may have failed to load".
• Docs: the DNS invariant in .devcontainer/CLAUDE.md; the symptom in README troubleshooting.

Testing

• Throwaway container from the built image, strict mode, patched script:
  • --dns 8.8.8.8 --dns 8.8.4.4: getent github.com 60/60 (was 0/10); git ls-remote https://github.com/... OK; example.com and direct DNS to 1.1.1.1 still blocked; re-run is idempotent.
  • Default (host() upstream): no extra rules added, behavior unchanged.
• Live container, rebuilt and recreated: make boot-check OK, healthy, ExtServers: [8.8.8.8 8.8.4.4], getent github.com 40/40, git over HTTPS and SSH to GitHub OK.
• make lint gates: shellcheck, hadolint, yamllint (via uvx), docker compose config — all pass. The one yamllint warning (mem_limit comment) predates this change.

Notes

• 8.8.8.8 / 8.8.4.4 are now hardcoded; a network that blocks Google DNS would need these edited.
• The host itself still has the flaky resolver (it bit git push while opening this PR). This fixes the container only.

🤖 Generated with Claude Code