Cache Plutonium runtime files on hosts

docs/guides/native-hosts.md

@@ -55,8 +55,10 @@ enrollment; inspect `systemctl status docker` and `journalctl -u docker`.
 The controller reconciles automatic setup on agent heartbeats. Command polls only
 deliver work already queued. Setup first pulls `PLUTAINER_IMAGE` (default
 `ghcr.io/ayymoss/plutainer:latest`), then prepares the latest verified upload for
-T5 and for T6 when available, one setup operation at a time. Uploading new files
-or enrolling another host needs no manual propagation. Setup waits for an active, connected,
+T5 and for T6 when available, one setup operation at a time. After those prerequisites,
+capable agents also prepare the optional Plutonium runtime cache described below.
+Uploading new files or enrolling another host needs no manual propagation.
+Setup waits for an active, connected,
 healthy host with sufficient storage. Failed operations retry automatically with
 backoff from one minute to fifteen minutes; their errors remain visible in the
 host's setup panel and **Hosts → Operation history**. This shared history lists
@@ -90,6 +92,50 @@ cached mutable image tag. Advanced controls on the
 host and game-file pages can explicitly pull a custom runtime, prepare an older
 upload or retry preparation immediately.
 
+### Plutonium runtime cache
+
+Agent 1.8.0 adds a host cache for the files Plutainer normally downloads from
+Plutonium on a new container's first start. This is separate from the cached
+Docker image and uploaded base game libraries. Automatic preparation warms it
+after the image and libraries are ready and refreshes it for new production
+revisions. The controller only queues this work for agents that advertise support.
+Cache preparation is optional: a missing or corrupt cache does not prevent a
+launch from using Plutainer's normal download path.
+
+Cache preparation has lower priority than deployments and other host changes.
+If work arrives during a download, the next heartbeat tells the agent to yield
+between transfer steps. Preparation resumes under the same operation ID after
+that work finishes, reusing files that have already passed verification.
+
+The agent downloads the official production manifest and its listed vendor files,
+verifies the SHA-1 hashes published in that manifest, and makes a snapshot
+available only after the complete set passes verification. It keeps the cache
+under `agent/plutonium-cache` within the host data directory. It does not populate
+the cache from existing lobbies, so lobby configuration, keys, custom scripts,
+plugins and runtime state are not collected into it. Preparation retains the
+current snapshot and the resumable download, removes older snapshots, and clears
+abandoned temporary files before checking available storage or publishing the
+new snapshot. A failed refresh preserves the previous complete cache.
+
+For new instances and rebuilds using `ghcr.io/ayymoss/plutainer` image references,
+the agent seeds `app/runtime/plutonium` from a valid snapshot, including its
+matching `cdn_info.json`, before applying the instance's launch files. Each
+instance receives its own writable copy; changes made by a lobby or its updater
+cannot change the host cache or another lobby. Custom runtime images keep their
+existing startup behavior.
+
+Plutainer's updater remains enabled. When a cached revision is current, it can
+skip the initial vendor-file download; when production is newer, it can download
+the update normally. Launch readiness still verifies the running Plutonium
+revision against production. Refreshing the cache does not restart or update
+running lobbies. Ordinary restarts retain the instance's existing files and do
+not need to seed from the cache again.
+
+Deleting a lobby preserves the host cache for subsequent launches. Deleting the
+host removes it with the rest of the managed data directory. This is intended to
+reduce repeated first-start downloads; deployment-time improvements still need
+measurement on a real Debian/Docker/Plutonium host.
+
 ### Storage layout
 
 The default host root is `/var/lib/electric-cherry`; installer `--data-dir` changes
@@ -698,6 +744,15 @@ game hosts. Run:
   loss and host reboot during update. Verify updater protocol mismatch requests
   an installer rerun.
 - T5 and T6 deployments and a mixed collection from a fresh destination host.
+- Warm the Plutonium runtime cache, then create and rebuild T5 and T6 lobbies;
+  verify the running revision and compare first-start downloads and launch times
+  with an empty cache. Test missing, corrupt and interrupted cache preparation,
+  a newer production revision, and a custom runtime image. Confirm launch-file
+  overrides survive seeding, lobby writes cannot alter the cache or another lobby,
+  and cache refresh leaves running lobbies unchanged. Queue a deployment during
+  preparation and verify that downloading yields and later resumes. Interrupt
+  preparation by stopping the agent and verify that retry removes abandoned
+  temporary files while retaining completed downloads.
 - Start, stop, restart, rebuild, destroy; verify RCON, map and runtime revision.
 - Read console and game logs, including Plutainer's relative game-log links.
 - File campaign and rollback, with a player joining between controller check and