feat(infra): turn a bridge-subnet collision into actionable guidance (#180)

The configurable subnet (network.subnet) gives an affected host the knob, but a
non-expert who hits Docker's cryptic "Pool overlaps with other one on this
address space" won't know to use it. `pithead up`/`apply`/`upgrade` now capture
the compose-up failure and, when it's a subnet overlap, print the exact fix —
set network.subnet to a free /24 (with an example) — instead of a raw Docker
stack trace. Pure, unit-tested explain_subnet_collision helper.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: VijitSingh97

CHANGELOG.md

@@ -161,7 +161,9 @@ per the process in [`docs/releasing.md`](docs/releasing.md).
   The structured fixed-IP layout is preserved (services keep their `.25`–`.31` octets), so the
   host-networked dashboard's bridge addressing and the #122 worker-SSRF CIDR guard still hold — only
   the `/24` base moves. A single `NETWORK_PREFIX` flows through every config path: compose
-  interpolation, monerod/Tor container `envsubst`/`sed` at start, and the Tari config render.
+  interpolation, monerod/Tor container `envsubst`/`sed` at start, and the Tari config render. And if
+  a host *does* collide, `pithead up`/`apply` now catch Docker's overlap error and print the exact
+  `network.subnet` fix (with an example) instead of a raw Docker stack trace.
 - Dashboard now records **every** P2Pool share instead of at most one per 30 s poll: it tracks the
   cumulative `shares_found` counter and records the per-poll delta as N distinct shares. A
   higher-hashrate or nano-sidechain node finding 2+ shares within one poll window no longer

docs/test-inventory.md

@@ -5,7 +5,7 @@ edit by hand** — re-run the target to refresh. See [Testing Strategy](testing-
 how the tiers fit together._
 
 **Totals:** 432 dashboard unit tests · 12 contract tests · 25 frontend
-tests · 28 `pithead` shell sections · 15 harness self-test sections ·
+tests · 29 `pithead` shell sections · 15 harness self-test sections ·
 8 live config scenarios (15 axis values) · 6 mini-stack scenarios.
 
 > Counts are **test functions / named cases** (parametrized pytest cases expand to more at
@@ -16,7 +16,7 @@ tests · 28 `pithead` shell sections · 15 harness self-test sections ·
 |---|---|---|
 | 1 — Unit | dashboard pytest | 432 |
 | 1 — Unit | frontend (node --test) | 25 |
-| 1 — Unit | `pithead` shell suite | 28 sections |
+| 1 — Unit | `pithead` shell suite | 29 sections |
 | 1 — Unit | compose interpolation + hardening (#90) | 1 |
 | 2 — Contract | fake-daemon clients | 12 |
 | 3 — Mini-stack | docker control-plane scenarios | 6 |
@@ -532,7 +532,7 @@ tests · 28 `pithead` shell sections · 15 harness self-test sections ·
 - heroKpis: mode colour follows the server mode_variant token
 - heroKpis: total is accent-coloured; blocks and tier carry no colour class
 
-### `pithead` shell suite (tests/stack/run.sh) — 28 sections
+### `pithead` shell suite (tests/stack/run.sh) — 29 sections
 - unit: resolve_default
 - unit: assert_safe_dir
 - unit: is_public_ip classifier (#113)
@@ -541,6 +541,7 @@ tests · 28 `pithead` shell sections · 15 harness self-test sections ·
 - unit: docker_boot_enabled (#137)
 - unit: is_valid_host (#130)
 - unit: describe_change
+- unit: explain_subnet_collision (#180)
 - unit: env helpers
 - unit: export_build_provenance (Issue #58)
 - unit: node credential helpers
@@ -688,5 +689,5 @@ tests · 28 `pithead` shell sections · 15 harness self-test sections ·
 
 ---
 
-_Grand total: **526** enumerated cases/sections across the four tiers (plus the live
+_Grand total: **527** enumerated cases/sections across the four tiers (plus the live
 lifecycle and fault-injection phases, which are exercised on a real server)._

pithead

@@ -100,12 +100,38 @@ migrate_compose_project() {
     docker rm -f "${stale[@]}" >/dev/null 2>&1 || true
 }
 
+# Turn Docker's cryptic bridge-subnet overlap error into an actionable fix (#180). $1 = compose
+# output. A no-op unless Docker rejected the subnet ("Pool overlaps with other one on this address
+# space"), which happens when the host already uses the stack's /24.
+explain_subnet_collision() {
+    case "$1" in
+        *"overlaps with other one"*|*"Pool overlaps"*)
+            local sub; sub="$(env_get NETWORK_SUBNET 2>/dev/null || true)"; [ -n "$sub" ] || sub="172.28.0.0/24"
+            warn "Docker refused the stack's bridge subnet ($sub): it overlaps a network already on this host."
+            warn "Pick a free /24 and set it in ${CONFIG_FILE:-config.json} — e.g.  \"network\": { \"subnet\": \"172.30.0.0/24\" }  — then re-run '$0 apply' && '$0 up' (see docs/configuration.md, network.subnet)." ;;
+    esac
+}
+
+# Run `docker compose up` with live output; on failure, explain a bridge-subnet collision (#180) if
+# that's what Docker rejected. Returns compose's own exit code.
+compose_up_checked() {
+    local tmp out rc
+    tmp="$(mktemp)"
+    docker compose up "$@" 2>&1 | tee "$tmp"
+    rc=${PIPESTATUS[0]}
+    out="$(cat "$tmp")"; rm -f "$tmp"
+    [ "$rc" -ne 0 ] && explain_subnet_collision "$out"
+    return "$rc"
+}
+
 stack_up() {
     log "Starting stack..."
     warn_missing_data_dirs
     migrate_compose_project
     # Docker Compose automatically picks up COMPOSE_PROFILES from .env
-    docker compose up -d
+    if ! compose_up_checked -d; then
+        error "Stack failed to start — see the error above."
+    fi
     log "Stack started successfully!"
     announce_dashboard_url
 }
@@ -140,7 +166,9 @@ stack_upgrade() {
     generate_caddyfile
     log "Re-rendered generated config for the current release."
     migrate_compose_project
-    docker compose up -d --build
+    if ! compose_up_checked -d --build; then
+        error "Upgrade failed during 'docker compose up' — see the error above."
+    fi
     log "Stack upgraded."
 }
 
@@ -2035,7 +2063,7 @@ apply() {
     : > "$apply_marker"
     # Compose recreates only the services whose resolved config changed; --remove-orphans
     # drops monerod when a local→remote switch deactivates the local_node profile.
-    if ! docker compose up -d --remove-orphans; then
+    if ! compose_up_checked -d --remove-orphans; then
         warn "Config files were updated but containers were NOT recreated ('docker compose up' failed)."
         warn "Fix the cause shown above, then re-run '$0 apply' (it will retry the recreate) — or '$0 up'."
         exit 1   # leave $apply_marker in place so the retry re-attempts the recreate

tests/stack/run.sh

@@ -132,6 +132,12 @@ assert_contains "tari mem is INFO"   "$(run_sourced "$SANDBOX" describe_change T
 assert_contains "monero mem is INFO" "$(run_sourced "$SANDBOX" describe_change MONERO_MEM_LIMIT 4g 6g)"  "INFO"
 assert_contains "monero mem recreate note" "$(run_sourced "$SANDBOX" describe_change MONERO_MEM_LIMIT 4g 6g)" "monerod container is recreated"
 
+echo "== unit: explain_subnet_collision (#180) =="
+ov="$(run_sourced "$SANDBOX" explain_subnet_collision "invalid pool request: Pool overlaps with other one on this address space" 2>&1)"
+assert_contains "subnet overlap -> network.subnet hint"  "$ov" "network"
+assert_contains "subnet overlap -> suggests a free /24"  "$ov" "/24"
+assert_eq "non-overlap failure stays silent" "$(run_sourced "$SANDBOX" explain_subnet_collision "some other failure" 2>&1)" ""
+
 echo "== unit: env helpers =="
 printf 'A=1\nB=two\nPROXY_AUTH_TOKEN=keep=me\n' > "$SANDBOX/old.env"
 printf 'A=1\nB=three\nC=4\nPROXY_AUTH_TOKEN=keep=me\n' > "$SANDBOX/new.env"