feat: install and record registry snapshot

README.md

@@ -464,13 +464,20 @@ actually contains. `staging-box` is the one in-tree tenant — mechanism-adjacen
 (sshd hardening through the shared `lib/sshd.sh`, docker, no agent), user
 `ops`, box#69's server posture with `root-door=open` acceptance.
 
-**Where the registry comes from — three knobs, precedence high to low:**
+**Where the registry comes from — precedence high to low:**
 
 | knob | meaning |
 |------|---------|
 | `RIG_TEMPLATES_DIR` | a local folder — no fetch: the offline-test path, and "try a template before it exists anywhere" |
 | `RIG_TEMPLATES_REF` | any ref of `RIG_TEMPLATES_REPO` (default `heavy-duty/rig-templates`), fetched as an unauthenticated tarball at bootstrap time |
-| *(neither set)* | **the in-tree pin** — `RIG_TEMPLATES_PIN` in `commands/lib/templates.sh`, the `BOX_RELEASE` discipline: bumped by ordinary reviewed rig PR, so a rig release freezes the mechanism+registry pair, and a newer rig matches newer templates by default (the #110 ruling) |
+| *(neither set; matching snapshot installed)* | **the installed pin snapshot** — `install.sh` best-effort fetches `RIG_TEMPLATES_PIN` once into `templates@<pin-sha>/` inside the versioned rig tree; default converges read it with zero registry network I/O |
+| *(snapshot absent, empty, or stale)* | **live fetch of the in-tree pin** — the pre-snapshot fallback: `RIG_TEMPLATES_PIN` in `commands/lib/templates.sh` is fetched at converge time. A failed snapshot download only warns during install, so rig remains usable and retries here |
+
+The pin remains the only source of truth. An older `templates@<sha>/`
+directory cannot answer after a pin bump, and an explicit
+`RIG_TEMPLATES_REF` always fetches that ref rather than consulting the
+snapshot. Logs mark the installed path as `(snapshot)` so drill evidence
+records which source actually served the converge.
 
 **The security trade — in bold, not a footnote.** **A main-tracked
 rig-templates repo means every merged PR there executes as root inside every

drill/drill.sh

@@ -59,6 +59,7 @@ BOXREF="${BOX_REF:-}"
 TPLREPO="${RIG_TEMPLATES_REPO:-heavy-duty/rig-templates}"
 TPLREF="${RIG_TEMPLATES_REF:-}"
 TPL_SHA=""
+TPL_SOURCE="fetched"
 ROLE=staging-server
 USERS_FILE="${DRILL_USERS_FILE:-}"
 RUN_ID="${DRILL_RUN_ID:-drill-$(date -u +%F)}"
@@ -274,8 +275,9 @@ emit_record() {
     printf 'Run ID: %s. Host: %s, %s vCPU / %s GB RAM (%s).\n' "$RUN_ID" "${os:-unknown}" "$cpus" "$ram" "$virt"
     printf 'Candidate refs: rig@%s (RIG_REF=%s), box@%s (BOX_REF=%s).\n' \
       "${RIG_SHA:-unresolved}" "$REF" "${BOX_SHA:-unresolved}" "$BOXREF"
-    printf 'Template registry: %s@%s (ref %s) — the rig-templates the converge read (#110).\n' \
+    printf 'Template registry: %s@%s (ref %s, %s) — the rig-templates source the converge read (#110/#153).\n' \
-      "${TPLREPO:-heavy-duty/rig-templates}" "${TPL_SHA:-unresolved}" "${TPLREF:-unresolved}"
+      "${TPLREPO:-heavy-duty/rig-templates}" "${TPL_SHA:-unresolved}" \
+      "${TPLREF:-unresolved}" "$TPL_SOURCE"
     printf 'Instrument: drill/drill.sh, legs in execution order.\n\n'
     printf '| Leg | Result |\n'
     printf '| --- | --- |\n'
@@ -396,13 +398,17 @@ ok "installed tree confirms: $REPO@$REF (version $DRILL_VERSION)"
 # through ref_sha like the two candidates above.
 if [ -z "$TPLREF" ]; then
   TPLREF="$(sed -n 's/^RIG_TEMPLATES_PIN=//p' "$RIG_TREE/commands/lib/templates.sh" 2>/dev/null | head -n1)"
+  if [ -n "$TPLREF" ] &&
+     [ -n "$(find "$RIG_TREE/templates@$TPLREF" -mindepth 2 -maxdepth 2 -type f -name template.env -print -quit 2>/dev/null)" ]; then
+    TPL_SOURCE="snapshot"
+  fi
 fi
 if [[ "$TPLREF" =~ ^[0-9a-f]{40}$ ]]; then
   TPL_SHA="${TPLREF:0:7}"
 elif [ -n "$TPLREF" ]; then
   TPL_SHA="$(ref_sha "$TPLREPO" "$TPLREF")"
 fi
-inf "templates: $TPLREPO@${TPLREF:-unresolved} (${TPL_SHA:-unresolved})"
+inf "templates: $TPLREPO@${TPLREF:-unresolved} (${TPL_SHA:-unresolved}, $TPL_SOURCE)"
 [ -n "$RECORD" ] || RECORD="$ROOT/drills/$DRILL_VERSION.md"
 
 # =============================================================================

install.sh

@@ -249,6 +249,57 @@ set_exec() {   # $1 = a rig tree: the executable bits install.sh owns
   fi
 }
 
+# snapshot_templates <rig-tree> — best-effort install-time cache of the exact
+# registry pin carried by that tree. The pin remains the sole source of truth;
+# the directory name makes a stale snapshot invisible after an upgrade.
+# Failure is deliberately a warning: rig itself is still a complete install,
+# and templates_resolve preserves the live-fetch fallback.
+snapshot_templates() {
+  local tree="$1" pin repo url got="" unpack top snapshot
+  pin="$(sed -n 's/^RIG_TEMPLATES_PIN=//p' "$tree/commands/lib/templates.sh" 2>/dev/null | head -n1 || true)"
+  if [ -z "$pin" ]; then
+    warn "installed tree carries no RIG_TEMPLATES_PIN; template registry snapshot skipped."
+    return 0
+  fi
+  repo="${RIG_TEMPLATES_REPO:-heavy-duty/rig-templates}"
+  snapshot="$tree/templates@$pin"
+  if ! command -v curl >/dev/null 2>&1; then
+    warn "curl is unavailable; template registry snapshot $repo@$pin was not installed (converge will retry the live fetch)."
+    return 0
+  fi
+  unpack="$TMPDIR/templates-unpack"
+  rm -rf "$unpack"
+  mkdir -p "$unpack"
+  log "downloading template registry snapshot $repo@$pin"
+  for url in \
+    "https://github.com/$repo/archive/refs/tags/$pin.tar.gz" \
+    "https://github.com/$repo/archive/refs/heads/$pin.tar.gz" \
+    "https://github.com/$repo/archive/$pin.tar.gz"; do
+    if curl -fsSL "$url" -o "$TMPDIR/templates.tar.gz" 2>/dev/null; then got="$url"; break; fi
+  done
+  if [ -z "$got" ]; then
+    warn "could not fetch template registry snapshot $repo@$pin; rig installed without it (converge will retry the live fetch)."
+    return 0
+  fi
+  if ! tar -xzf "$TMPDIR/templates.tar.gz" -C "$unpack"; then
+    warn "could not extract template registry snapshot from $got; rig installed without it (converge will retry the live fetch)."
+    return 0
+  fi
+  set -- "$unpack"/*/
+  if ! { [ $# -eq 1 ] && [ -d "$1" ]; }; then
+    warn "template registry snapshot from $got has an unexpected archive shape; rig installed without it (converge will retry the live fetch)."
+    return 0
+  fi
+  top="${1%/}"
+  if [ -z "$(find "$top" -mindepth 2 -maxdepth 2 -type f -name template.env -print -quit 2>/dev/null)" ]; then
+    warn "template registry snapshot from $got has no definitions; rig installed without it (converge will retry the live fetch)."
+    return 0
+  fi
+  rm -rf "$snapshot"
+  mv "$top" "$snapshot"
+  log "template registry snapshot installed: $repo@$pin"
+}
+
 # --- install into $DEST/versions/<version> -----------------------------------
 VDIR="$DEST/versions/$new_ver"
 newly_installed=0
@@ -259,6 +310,7 @@ if [ -d "$VDIR" ]; then
     log "RIG_REINSTALL=1 — replacing the installed $new_ver tree"
     stage="$VDIR.new.$$"; old="$VDIR.old.$$"
     rm -rf "$stage" "$old"
+    snapshot_templates "$EXTRACTED"
     set_exec "$EXTRACTED"
     mv "$EXTRACTED" "$stage"
     # Swap by renames, delete LAST: rm-then-move leaves a hole the whole
@@ -276,6 +328,7 @@ if [ -d "$VDIR" ]; then
 else
   log "installing $new_ver into $VDIR"
   mkdir -p "$DEST/versions"
+  snapshot_templates "$EXTRACTED"
   set_exec "$EXTRACTED"
   mv "$EXTRACTED" "$VDIR"
   newly_installed=1

test/cli.sh

@@ -2654,6 +2654,19 @@ check "help lists the versioned verbs" 0 "uninstall" "$ROOT/bin/rig" --help
 WORK="$(mktemp -d)"
 FAKEHOME="$WORK/home"; mkdir -p "$FAKEHOME"
 
+# Every real installer run gets a deterministic registry archive. The curl
+# shim can also be poisoned per call to prove warn-and-continue behavior.
+SNAPBIN="$WORK/snapshot-bin"
+mkdir -p "$SNAPBIN" "$WORK/snapshot-stage/rig-templates-pin/scratch-box"
+printf 'USER="scratch"\n' > "$WORK/snapshot-stage/rig-templates-pin/scratch-box/template.env"
+tar -czf "$WORK/snapshot.tar.gz" -C "$WORK/snapshot-stage" rig-templates-pin
+cat > "$SNAPBIN/curl" <<'CURLEOF'
+#!/usr/bin/env bash
+[ -z "${SNAPSHOT_FETCH_FAIL:-}" ] || exit 22
+cp "${SNAPSHOT_TARBALL:?}" "$4"
+CURLEOF
+chmod +x "$SNAPBIN/curl"
+
 # A fabricated "newer release": the same CLI, a different VERSION — what an
 # upgrade actually is, from the installer's point of view.
 SRC9="$WORK/src-9.9.9"; mkdir -p "$SRC9/bin"
@@ -2665,7 +2678,8 @@ echo "8.8.8-drill" > "$SRC8/VERSION"
 
 inst() {  # inst <rig_home> <rig_bin> [VAR=val ...] — run install.sh for real
   local h="$1" b="$2"; shift 2
-  env HOME="$FAKEHOME" RIG_ROLE_MARKER="$WORK/no-marker" \
+  env HOME="$FAKEHOME" PATH="$SNAPBIN:$PATH" \
+      SNAPSHOT_TARBALL="$WORK/snapshot.tar.gz" RIG_ROLE_MARKER="$WORK/no-marker" \
       RIG_HOME="$h" RIG_BIN="$b" \
       RIG_INSTALL_SOURCE="$ROOT" "$@" bash "$ROOT/install.sh"
 }
@@ -2681,6 +2695,16 @@ check "install: 'current' points at versions/<v>" 0 "versions/$VER" readlink "$H
 check "install: the PATH symlink rides the chain" 0 "$H1/current/bin/rig" readlink "$B1/rig"
 check "install: rig --version answers through the whole chain" 0 "rig $VER" irig "$B1/rig" --version
 check "install: INSTALLED_FROM records the local source" 0 "local:" cat "$H1/versions/$VER/INSTALLED_FROM"
+check "install: the pinned registry snapshot lands inside the version tree" 0 "" \
+  test -f "$H1/versions/$VER/templates@$TPL_PIN/scratch-box/template.env"
+
+HFAIL="$WORK/h-failed-snapshot"; BFAIL="$WORK/b-failed-snapshot"
+check "install: unreachable registry warns and still installs rig" 0 "WARNING: could not fetch template registry snapshot" \
+  inst "$HFAIL" "$BFAIL" SNAPSHOT_FETCH_FAIL=1
+check "install: failed snapshot fetch leaves a working tree" 0 "rig $VER" \
+  "$BFAIL/rig" --version
+check "install: failed snapshot fetch leaves no hollow snapshot" 1 "" \
+  test -e "$HFAIL/versions/$VER/templates@$TPL_PIN"
 
 # --- rig#39: no $HOME in the environment (cloud-init's runcmd) ---------------
 # The box#88 seed runs install.sh from runcmd, which carries NO $HOME; under
@@ -2703,10 +2727,13 @@ check "install: no \$HOME and no getent answer refuses by name" 1 "set HOME and
 
 # --- converge, don't clobber ------------------------------------------------
 touch "$H1/versions/$VER/CANARY"
+touch "$H1/versions/$VER/templates@$TPL_PIN/STALE"
 check "install: a same-version re-run is a no-op that says so" 0 "already installed" inst "$H1" "$B1"
 check "install: the no-op left the tree untouched" 0 "" test -e "$H1/versions/$VER/CANARY"
 check "install: RIG_REINSTALL=1 replaces that version's tree" 0 "reinstalled" inst "$H1" "$B1" RIG_REINSTALL=1
 check "install: the reinstall really replaced it (canary gone)" 1 "" test -e "$H1/versions/$VER/CANARY"
+check "install: reinstall replaces the registry snapshot" 1 "" \
+  test -e "$H1/versions/$VER/templates@$TPL_PIN/STALE"
 
 # --- a second version: side-by-side, and the flip ---------------------------
 check "install: a second version installs side-by-side" 0 "" inst "$H1" "$B1" RIG_INSTALL_SOURCE="$SRC9"

test/install-lifecycle.sh

@@ -65,6 +65,18 @@ VER="$(cat "$ROOT/VERSION")"
 WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
 
+# install.sh snapshots the pinned registry even for the local source channel.
+# Serve a deterministic archive so this lifecycle remains fully offline.
+SNAPBIN="$WORK/snapshot-bin"
+mkdir -p "$SNAPBIN" "$WORK/snapshot-stage/rig-templates-pin/test-box"
+printf 'USER="test"\n' > "$WORK/snapshot-stage/rig-templates-pin/test-box/template.env"
+tar -czf "$WORK/snapshot.tar.gz" -C "$WORK/snapshot-stage" rig-templates-pin
+cat > "$SNAPBIN/curl" <<'CURLEOF'
+#!/usr/bin/env bash
+cp "${SNAPSHOT_TARBALL:?}" "$4"
+CURLEOF
+chmod +x "$SNAPBIN/curl"
+
 # tree_state <root> — what "changed nothing" must mean: every file's bytes,
 # every path's type and mode, every symlink's target. Beat 3 captures this
 # before and after the re-run and diffs the two.
@@ -124,7 +136,10 @@ check "honesty: a really-gone path passes the absence assert" 0 "" \
 # RIG_INSTALL_SOURCE is the supported local channel (its contract — dir,
 # tarball, loud refusal, no silent download fallback — is test/release.sh's);
 # in CI $ROOT is $GITHUB_WORKSPACE, so what lands is the code under review.
-b1() { RIG_INSTALL_SOURCE="$ROOT" bash "$ROOT/install.sh"; }
+b1() {
+  PATH="$SNAPBIN:$PATH" SNAPSHOT_TARBALL="$WORK/snapshot.tar.gz" \
+    RIG_INSTALL_SOURCE="$ROOT" bash "$ROOT/install.sh"
+}
 check "beat 1: install.sh installs this checkout" 0 "done" b1
 
 # --- beat 2: assert what landed ----------------------------------------------
@@ -140,6 +155,9 @@ check "beat 2: rig --version answers through the whole chain" 0 "rig $VER" \
   "$BINDIR/rig" --version
 check "beat 2: INSTALLED_FROM names the local source" 0 "local:$ROOT" \
   cat "$DEST/versions/$VER/INSTALLED_FROM"
+TPL_PIN="$(sed -n 's/^RIG_TEMPLATES_PIN=//p' "$ROOT/commands/lib/templates.sh")"
+check "beat 2: pinned registry snapshot landed in the version tree" 0 "" \
+  test -f "$DEST/versions/$VER/templates@$TPL_PIN/test-box/template.env"
 
 # --- beat 3: the converging re-run -------------------------------------------
 # "Ran twice without crashing" is the self-deception this beat exists to