feat: SHA-stamped surrogate filename and configurable pool size (#1339)

- Use SHA-256 content hash in surrogate binary filename
  (hyperlight_surrogate_{sha8}.exe) to eliminate cross-version
  ACCESS_DENIED race when multiple hyperlight versions coexist.

- Add HYPERLIGHT_INITIAL_SURROGATES env var (1-512, default 512)
  to control how many surrogate processes are pre-created at startup.

- Add HYPERLIGHT_MAX_SURROGATES env var (>=initial, <=512, default 512)
  as hard cap with on-demand CAS growth when pool is exhausted.

- Rollback created_count on process creation failure to prevent
  permanent capacity loss from transient errors.

- Increment created_count per-process (not store-after-loop) to
  prevent count drift on partial init failure.

- Warn when env var values are clamped to valid range.

- Add tests for env var parsing (with #[serial] for thread safety)
  and locked-file extraction resilience.

- Update surrogate development notes documentation.

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Author: simongdavies

Cargo.lock

@@ -4,6 +4,8 @@
 
 > Note: The use of surrogates is a temporary workaround on Windows until WHP allows us to create more than one partition per running process.
 
-These surrogate processes are managed by the host via the [surrogate_process_manager](./src/hyperlight_host/src/hypervisor/surrogate_process_manager.rs) which will launch several of these surrogates (up to the 512), assign memory to them, then launch partitions from there, and reuse them as necessary.
+These surrogate processes are managed by the host via the [surrogate_process_manager](./src/hyperlight_host/src/hypervisor/surrogate_process_manager.rs) which pre-creates an initial pool of surrogates at startup (512 by default, configurable via the `HYPERLIGHT_INITIAL_SURROGATES` environment variable). If the pool is exhausted, additional processes are created on demand up to a configurable maximum (`HYPERLIGHT_MAX_SURROGATES`, also defaulting to 512). Once the maximum is reached, callers block until a process is returned to the pool.
 
-`hyperlight_surrogate.exe` gets built during `hyperlight-host`'s build script, gets embedded into the `hyperlight-host` Rust library via [rust-embed](https://crates.io/crates/rust-embed), and is extracted at runtime next to the executable when the surrogate process manager is initialized.
+> **Note:** `HYPERLIGHT_MAX_SURROGATES` is authoritative — if `HYPERLIGHT_INITIAL_SURROGATES` exceeds it, the initial count is silently clamped down to the maximum. For example, setting only `HYPERLIGHT_MAX_SURROGATES=256` limits both the initial pool and the ceiling to 256.
+
+`hyperlight_surrogate.exe` gets built during `hyperlight-host`'s build script, gets embedded into the `hyperlight-host` Rust library via [rust-embed](https://crates.io/crates/rust-embed), and is extracted at runtime next to the executable when the surrogate process manager is initialized. The extracted filename includes a short BLAKE3 hash of the binary content (e.g., `hyperlight_surrogate_a1b2c3d4.exe`) so that multiple hyperlight versions can coexist without file-deletion races.

docs/hyperlight-surrogate-development-notes.md

@@ -70,7 +70,6 @@ windows = { version = "0.62", features = [
 windows-sys = { version = "0.61", features = ["Win32"] }
 windows-result = "0.4"
 rust-embed = { version = "8.11.0", features = ["debug-embed", "include-exclude", "interpolate-folder-path"] }
-sha256 = "1.6.0"
 windows-version = "0.1"
 lazy_static = "1.4.0"