feat(boot-test): CI boot tests use the Steam download cache, updated once a day

CI deployed every Steam game from scratch on each run, downloading the whole
game from Steam each time. scripts/boot-test.sh now runs the new
`gbrgames boot-test ID`, the builder's own deploy path: the same payload and
node-agent BootTest, but Steam games start from the cache volume
(gbr-steamcache-<app>, kept by RUNNER.md's prune).

The cache is updated at most once a day (a timestamp in the cache volume, not
copied into servers), so a repeat run within a day doesn't ask Steam for an
update at all; the node-agent's own install still checks the files and fetches
anything newer.

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

cmd/gbrgames/agentboot.go

@@ -4,10 +4,14 @@ import (
 	"bytes"
 	"encoding/json"
 	"errors"
+	"flag"
 	"fmt"
 	"os"
 	"os/exec"
 	"regexp"
+	"strconv"
+	"strings"
+	"time"
 )
 
 // Every server the builder starts, first boots included, is deployed by the node-agent's own code
@@ -73,14 +77,25 @@ var steamCacheFresh = map[string]bool{}
 
 var numericAppID = regexp.MustCompile(`^\d+$`)
 
+// When the cache was last updated, in the cache volume (not copied into servers)
+const steamCacheStamp = ".gbr-cache-updated"
+
+// steamCacheMaxAge: a cache updated more recently isn't updated again, which saves Steam a login and an
+// update check per boot; the node-agent's own install still fetches anything newer
+const steamCacheMaxAge = 24 * time.Hour
+
 // seedSteamApp fills a server volume from a cached SteamCMD install of the app, so a boot doesn't
 // download the whole game again: the node-agent's own install then only checks the files. The cache is
-// updated once per run. Without it (STEAM_CACHE=off, or the update failing) the agent downloads as usual.
+// updated at most once a day. Without it (STEAM_CACHE=off, or the update failing) the agent downloads as usual.
 func seedSteamApp(appID, volume string) {
 	if os.Getenv("STEAM_CACHE") == "off" || !numericAppID.MatchString(appID) {
 		return
 	}
 	cache := "gbr-steamcache-" + appID
+	if !steamCacheFresh[appID] && steamCacheUpdatedWithin(cache, steamCacheMaxAge) {
+		fmt.Printf("[steam-cache] the cached install of Steam app %s was updated in the last %s\n", appID, steamCacheMaxAge)
+		steamCacheFresh[appID] = true
+	}
 	if !steamCacheFresh[appID] {
 		fmt.Printf("[steam-cache] updating the cached install of Steam app %s\n", appID)
 		if out, err := runCmd("docker", "volume", "create", "--label", "gbr.cache=steam", cache); err != nil {
@@ -98,12 +113,56 @@ func seedSteamApp(appID, volume string) {
 			fmt.Printf("[steam-cache] update failed (%v); the boot downloads the app itself\n", err)
 			return
 		}
+		runCmd("docker", "run", "--rm", "-v", cache+":/server", "alpine", "sh", "-c",
+			fmt.Sprintf("date +%%s > /server/%s", steamCacheStamp))
 		steamCacheFresh[appID] = true
 	}
 	runCmd("docker", "volume", "create", volume)
-	if out, err := runCmd("docker", "run", "--rm", "-v", cache+":/from:ro", "-v", volume+":/to", "alpine", "cp", "-a", "/from/.", "/to/"); err != nil {
+	if out, err := runCmd("docker", "run", "--rm", "-v", cache+":/from:ro", "-v", volume+":/to", "alpine", "sh", "-c",
+		"cp -a /from/. /to/ && rm -f /to/"+steamCacheStamp); err != nil {
 		fmt.Printf("[steam-cache] copying into %s failed (%v: %s); the boot downloads the app itself\n", volume, err, out)
 		return
 	}
 	fmt.Printf("[steam-cache] %s seeded from the cached install of app %s\n", volume, appID)
 }
+
+func steamCacheUpdatedWithin(cache string, age time.Duration) bool {
+	out, err := runCmd("docker", "run", "--rm", "-v", cache+":/c:ro", "alpine", "cat", "/c/"+steamCacheStamp)
+	if err != nil {
+		return false
+	}
+	return stampWithin(out, time.Now(), age)
+}
+
+func stampWithin(stamp string, now time.Time, age time.Duration) bool {
+	secs, err := strconv.ParseInt(strings.TrimSpace(stamp), 10, 64)
+	return err == nil && now.Sub(time.Unix(secs, 0)) < age
+}
+
+// runBootTest boot-tests one game the way CI does: its real payload, deployed by the node-agent, with
+// the Steam download cache. Exits 3 when a secret it needs isn't set, 1 when it fails.
+func runBootTest(args []string) error {
+	fs := flag.NewFlagSet("boot-test", flag.ExitOnError)
+	gamesDir := fs.String("games", "games", "directory holding one folder per game")
+	fs.Parse(args)
+	if fs.NArg() != 1 {
+		return errors.New("boot-test needs a game id")
+	}
+	payload, err := bootTestPayload(*gamesDir, fs.Arg(0), false)
+	var missing *missingSecretError
+	if errors.As(err, &missing) {
+		fmt.Fprintln(os.Stderr, "skip: "+missing.Error())
+		os.Exit(exitMissingSecret)
+	}
+	if err != nil {
+		return err
+	}
+	_, passed, err := runAgentBootTest(payload, agentImageFromEnv())
+	if err != nil {
+		return err
+	}
+	if !passed {
+		os.Exit(1)
+	}
+	return nil
+}