dind passthrough: warn when DIND_HOST_PASSTHROUGH_IMAGES is set but no host socket is mounted (issue #102)

[konard]

Summary

Fixes #102.

When box-dind runs with host-image passthrough enabled (the default
DIND_HOST_PASSTHROUGH=public) and an explicit allowlist set
(DIND_HOST_PASSTHROUGH_IMAGES=...) but the host Docker socket is not
bind-mounted, passthrough was a silent no-op: nothing was copied, nothing
printed, and the first nested docker run re-pulled the full image from the
registry with no hint why. A non-empty allowlist is an unambiguous opt-in
signal, so a missing socket is almost certainly a misconfiguration worth
surfacing.

Downstream this silently re-pulled a 30+ GB image because of a forgotten
-v flag (link-assistant/hive-mind#1914).

Change

passthrough_host_images in ubuntu/24.04/dind/dind-entrypoint.sh now emits a
single actionable warning in exactly the opt-in case — enabled passthrough +
allowlist set + no socket mounted — naming the missing mount:

host-image passthrough is enabled and DIND_HOST_PASSTHROUGH_IMAGES is set, but
no host docker socket is mounted at <sock>; the nested daemon will NOT be
seeded from the host (first 'docker run' will pull from the registry).
Mount it with: -v /var/run/docker.sock:<sock>:ro

Behavior preserved:

• The present-but-unreachable socket path already warned and still wins (its
  more specific "not accessible" message fires first).
• Plain box-dind containers that never set an allowlist stay silent when
  no socket is mounted, so the default mode is not spammed.

Reproduce

docker pull hello-world
docker run --rm -it --privileged \
  -e DIND_HOST_PASSTHROUGH=public \
  -e DIND_HOST_PASSTHROUGH_IMAGES="hello-world" \
  konard/box-dind:latest \
  bash -lc 'docker run --rm hello-world'
# Before: nested daemon pulls hello-world, no warning.
# After:  startup logs warn that no host socket is mounted + the -v remediation.

Tests

• Unit (experiments/preload-unit-test.sh): new Case 8b (allowlist +
  absent socket → warning naming the var and the -v remediation) and
  Case 8c (present-but-unreachable socket still wins; the missing-mount hint
  is suppressed). Existing Case 8 still asserts plain mode stays silent.
  RESULT: 46 passed, 0 failed.
• Integration (tests/dind/example-preload-images.sh): new case starts a
  consumer with DIND_HOST_PASSTHROUGH_IMAGES set but no -v socket mount
  and asserts the warning appears in the container logs.

Docs / release

• docs/dind/USAGE.md: documents the opt-in warning under the
  DIND_HOST_PASSTHROUGH_IMAGES scoping section.
• Adds a patch changeset (.changeset/issue-102-passthrough-missing-socket-warning.md).
• Removed the auto-generated .gitkeep placeholder.

[konard]

Working session summary

Done. Here's a summary of what I did for issue #102.

Root cause

In ubuntu/24.04/dind/dind-entrypoint.sh, passthrough_host_images() returned silently whenever the host Docker socket wasn't reachable — but it only emitted a warning for the present-but-unreachable socket case. The common absent socket case stayed silent, even when the operator had set DIND_HOST_PASSTHROUGH_IMAGES (an unambiguous opt-in). The result: passthrough did nothing, and the first nested docker run re-pulled from the registry with no hint why (downstream, a 30+ GB re-pull in link-assistant/hive-mind#1914).

Fix

Added one elif branch: when there's no socket file but DIND_HOST_PASSTHROUGH_IMAGES is set, emit a single actionable warning naming the missing -v /var/run/docker.sock:${DIND_HOST_DOCKER_SOCK}:ro mount. Preserved both existing behaviors:

• present-but-unreachable socket → its more specific "not accessible" warning still fires first;
• plain box-dind with no allowlist → stays silent (no new noise).

Tests (reproduce → fix)

• Unit (experiments/preload-unit-test.sh): Case 8b (allowlist + absent socket → warning + -v remediation) and Case 8c (unreachable socket still wins, hint suppressed). Existing Case 8 (silent default) still passes — 46 passed, 0 failed.
• Integration (tests/dind/example-preload-images.sh): new case runs a container with the allowlist set but no socket mount and asserts the warning in the logs.

Docs / release

• Documented the opt-in warning in docs/dind/USAGE.md.
• Added a patch changeset (the repo's release trigger).
• Removed the auto-generated .gitkeep placeholder.

PR #103 is updated, marked ready, and pushed: #103

The integration test will exercise the change in CI (pr-test-dind); the local unit test and shell syntax checks pass.

---

This summary was automatically extracted from the AI working session output.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $1.531006
• Calculated by Anthropic: $1.733450
• Difference: $0.202444 (+13.22%)

📊 Context and tokens usage:

• 66.9K / 1M (7%) input tokens, 13.8K / 128K (11%) output tokens

Total: (2.9K new + 54.0K cache writes + 1.7M cache reads) input tokens, 13.8K output tokens, $1.531006 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus
• Model: Claude Opus 4.8 (claude-opus-4-8)

📎 Log file uploaded as Gist (1067KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

✅ Ready to merge

This pull request is now ready to be merged:

• All CI checks have passed
• No merge conflicts
• No pending changes

---

Monitored by hive-mind with --auto-restart-until-mergeable flag