test-build: add --pull to refresh a stale local image

require_image pulled only when the image was missing, so once the
image-builder rebuilt a registry tag the local copy went stale with no
warning. --pull runs `docker pull` first, which compares digests itself
and costs one manifest request when nothing changed. If the registry is
unreachable it falls back to the local copy with a warning, and still
fails when there is none.

The README documents a daily cron pull for machines that run test-build,
and the skill notes that local images are not refreshed automatically.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 21 insertions, 6 deletions

diff --git a/test-build b/test-build
index 6899c05..56cc291 100755
--- a/test-build
+++ b/test-build
@@ -54,6 +54,7 @@ ASSUME_YES=0       # --yes: skip the confirm prompt (still prints the order)
 USE_CACHE=1        # --no-cache disables the dep cache for one run
 KEEP_TARGET=0      # --keep: copy the built target package out to KEEP_DIR
 LOCAL_DEPS=0       # --local-deps: also resolve deps from the target's own repo
+PULL_IMAGE=0       # --pull: refresh the image from the registry before building
 VERSION_ID="current"   # "current" | "15.0"; set by --stable
 TARGET_ARG=""
 
@@ -89,6 +90,10 @@ OPTIONS:
   --local-deps  Also resolve deps from the target's own repo (its grandparent
                 dir), for packages whose deps are siblings in the same repo and
                 not on SBo. The configured SBo tree is still searched after.
+  --pull        Pull the image from the registry before building, so a local
+                copy older than the registry's tag is refreshed. A no-op when
+                it is already current. Falls back to the local copy if the
+                registry is unreachable.
   --no-color    Disable ANSI color (auto-disabled when stdout is not a TTY).
 EOF
 }
@@ -104,6 +109,7 @@ parse_args() {
       --no-cache) USE_CACHE=0; shift ;;
       --keep) KEEP_TARGET=1; shift ;;
       --local-deps) LOCAL_DEPS=1; shift ;;
+      --pull) PULL_IMAGE=1; shift ;;
       --no-color) USE_COLOR=0; shift ;;
       -*) echo "Unknown option: $1" >&2; usage >&2; exit 2 ;;
       *)
@@ -850,13 +856,22 @@ print_summary() {
 # Ensure the selected image is available locally. It is built by a separate job
 # (the image-builder) and pushed to the LAN registry; this script only consumes
 # it. If it is not already local, pull it once (ACTIVE_IMAGE is a fully-qualified
-# registry ref). A stale local tag is not refreshed here.
-# ponytail: pull-if-missing only. If the registry's :current is rebuilt, the
-#   local copy goes stale silently. Add a --pull force-flag if that bites.
+# registry ref). A stale local tag is refreshed only with --pull (or by the
+# daily cron pull in the README); `docker pull` itself does the digest check,
+# so an up-to-date image costs one manifest request.
 require_image() {
-  docker image inspect "$ACTIVE_IMAGE" >/dev/null 2>&1 && return 0
-  echo "Image not present locally, pulling: $ACTIVE_IMAGE" >&2
-  docker pull "$ACTIVE_IMAGE" >&2 && return 0
+  if [[ $PULL_IMAGE -eq 1 ]]; then
+    echo "Pulling: $ACTIVE_IMAGE" >&2
+    docker pull "$ACTIVE_IMAGE" >&2 && return 0
+    if docker image inspect "$ACTIVE_IMAGE" >/dev/null 2>&1; then
+      echo "WARN: pull failed; using the local copy, which may be stale." >&2
+      return 0
+    fi
+  else
+    docker image inspect "$ACTIVE_IMAGE" >/dev/null 2>&1 && return 0
+    echo "Image not present locally, pulling: $ACTIVE_IMAGE" >&2
+    docker pull "$ACTIVE_IMAGE" >&2 && return 0
+  fi
   cat >&2 <<EOF
 Image not found and pull failed: $ACTIVE_IMAGE
 It is produced by the image-builder job (full Slackware $VERSION_ID +