claim(2): HQ1 image pre-pull — warm local store before deploy (4 unit tests + warm-cache-skip + bad-tag-clear-error + abra-unchanged)

lifecycle.prepull_images (commit 2bf40d6): docker compose config --images → docker pull skip-if-present,
before deploy_app's abra.deploy + perform_upgrade's chaos redeploy. Adversary criteria all met:
warm-cache 2nd run 'present' (no redownload, n8n-prepull2), bad-tag → clear RuntimeError pre-deploy,
abra deploy path unchanged (no service update/scale), real-run green. 4 unit tests pass. Gate evidence
in STATUS-2.

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

machine-docs/BACKLOG-2.md

@@ -184,7 +184,14 @@ Phase plan: `/srv/cc-ci/cc-ci-plan/plan-phase2-recipe-tests.md`
       with the F2-7 keycloak-specificity caveat; worked lasuite-docs example end-to-end. **Will
       re-pass when Q3.2/Q3.5 enroll new recipes** (immich/lasuite-drive) to confirm a new
       engineer can follow the doc cold.
-- [ ] **HQ1 — Harness image pre-pull (near-term unit, orchestrator 2026-05-29).** PLAN:
+- [x] **HQ1 — Harness image pre-pull — DONE @2026-05-29 (commit `2bf40d6`), CLAIMED (STATUS-2 gate),
+      awaiting Adversary.** `lifecycle.prepull_images` resolves images via `docker compose config
+      --images` (COMPOSE_FILE from app .env; $VERSION interpolation + multi-compose) → `docker pull`
+      skip-if-present; called in deploy_app before the (unchanged real) abra.deploy AND in
+      perform_upgrade before the chaos redeploy. Validated: 4 unit tests (tests/unit/test_prepull.py)
+      + warm-cache 2nd run "present" (no re-download) + bad-tag → clear RuntimeError pre-deploy +
+      abra deploy unchanged (no service update/scale). Original spec below.
+- [ ] **HQ1 (orig)** — Harness image pre-pull (near-term unit, orchestrator 2026-05-29). PLAN:
       `cc-ci-plan/plan-prepull-images.md`. At the START of a recipe test sequence (before the first
       `abra app deploy`) AND before the upgrade tier's new-version deploy: resolve recipe images via
       `docker compose --env-file <app.env> -f <COMPOSE_FILE> config --images` and `docker pull` each

machine-docs/JOURNAL-2.md

@@ -969,3 +969,19 @@ recipe to gain a `pg_dump` backup hook — a recipe-create-pr unit (mirror immic
 the 4 backupbot labels [adapt POSTGRES_USER=postgres, DB=immich] → cc-ci full-suite green on the PR →
 operator merge), exactly like Q3.2b for drive. Filed DEFERRED + BACKLOG. NOT claiming Q3.5 full (restore
 RED); Adversary to weigh whether the recipe PR is required before Phase-2 DONE or §7.1 sign-off applies.
+
+---
+
+## 2026-05-29 — HQ1 image pre-pull DONE (commit 2bf40d6), claimed
+
+Implemented per plan-prepull-images.md: lifecycle.prepull_images resolves a recipe's images via
+`docker compose config --images` (COMPOSE_FILE from the app .env — handles $VERSION interpolation +
+multi-compose; verified the invocation on custom-html-tiny [1 img] + lasuite-meet [compose.yml:
+compose.turn.yml]) and docker-pulls them skip-if-present. Wired into deploy_app (before the unchanged
+abra.deploy) + perform_upgrade (before the chaos redeploy). Validation: 4 unit tests (mocked docker)
+prove present→skip / missing→pull / pull-fail→RAISE / no-images→skip; n8n run #1 prepulled a cold
+image + green; n8n run #2 (warm) showed `prepull: present` (no re-download); a bogus tag raised a
+clear "clear pull error BEFORE deploy: manifest unknown" pre-deploy. abra deploy unchanged (no service
+update/scale). This eliminates the first-deploy "No such image" race I hit on immich + lasuite-meet
+and gives clear pull errors instead of murky converge timeouts. Honest scope: removes pull-time not
+app-init-time.

machine-docs/STATUS-2.md

@@ -141,6 +141,34 @@ SKIP no longer yields a GREEN `!testme`.
 
 ## Gate
 
+**Gate: HQ1 image pre-pull — CLAIMED @2026-05-29, awaiting Adversary.**
+
+**WHAT.** `runner/harness/lifecycle.prepull_images(recipe, domain)` warms the local image store BEFORE
+the deploy: resolves the recipe's images via `docker compose --env-file <app.env> -f <COMPOSE_FILE…>
+config --images` (handles `$VERSION` interpolation + multi-compose, reading abra's COMPOSE_FILE from
+the app .env), then `docker pull` each with **skip-if-present** (`docker image inspect` → zero network
+for already-cached pinned tags). Called in `deploy_app` BEFORE the (UNCHANGED, real) `abra.deploy`, and
+in `generic.perform_upgrade` BEFORE the chaos redeploy (warms the new-version images). A pull failure
+RAISES a clear pull error pre-deploy (not a murky converge timeout). The deploy path is unchanged —
+prepull only warms the store (no `docker service update/scale`). Honest scope: removes PULL time, NOT
+app-INIT time (slow-init apps still need their healthcheck/READY_PROBE).
+
+**HOW / EXPECTED (Adversary, on cc-ci):**
+- `cc-ci-run -m pytest tests/unit/test_prepull.py -q` → **4 passed** (present→skip, missing→pull,
+  pull-fail→RAISE, no-images→skip).
+- Warm-cache no-redownload: run a cached recipe (e.g. n8n) → log shows `prepull: present <img>` (skip,
+  no pull). Proven: `/root/ccci-n8n-prepull2.log` (`prepull: present n8nio/n8n:2.20.6`), install+custom pass.
+- Bad-tag clear error: pointing a recipe at a bogus image tag → prepull RAISES
+  `RuntimeError: … clear pull error BEFORE deploy: manifest unknown` (proven, deploy-free).
+- Real-run-green + abra unchanged: `/root/ccci-n8n-prepull.log` (cold image pulled by prepull, then
+  install+custom GREEN); `grep` of `prepull_images` shows only compose-config / image-inspect / pull.
+
+**WHERE.** Commit `2bf40d6`. Files: `runner/harness/lifecycle.py` (`prepull_images` + deploy_app call),
+`runner/harness/generic.py` (perform_upgrade call), `tests/unit/test_prepull.py`. Plan:
+`cc-ci-plan/plan-prepull-images.md`.
+
+---
+
 **Gate: Q3.3 lasuite-meet — ✅ Adversary PASS @2026-05-29 (REVIEW-2 `a46f7d4`).**
 
 **WHAT.** lasuite-meet (La Suite real-time meetings via LiveKit; OIDC-required; sibling of