[codex] Add run save snapshots

[CompleteDotTech]

Summary

Ports the implementation from CompleteDotTech#3 onto Gennadiyev/STS2MCP.

This adds opt-in run save snapshots: automatic snapshot capture on game saves, manual snapshot creation, snapshot listing, and guarded restoration back to the active profile's current-run save slot.

Dependency Note

The source PR was stacked on top of the endpoint-audit work from CompleteDotTech#2.

This upstream PR is therefore stacked on the branch opened as:

• [codex] Add endpoint audit fixes #85

Until PR #85 is merged, this PR's diff against main includes the endpoint-audit foundation plus the snapshot implementation. The snapshot-specific commit is Add run save snapshots, followed by this documentation pass.

What Changed

Snapshot endpoint

Adds:

• GET /api/v1/snapshots
• POST /api/v1/snapshots

GET /api/v1/snapshots lists snapshot feature status and known snapshots:

• status
• kind: snapshots
• enabled
• enable_env_var
• snapshot_root_env_var
• snapshot_root
• count
• snapshots

POST /api/v1/snapshots supports:

• {"action": "create"}
• {"action": "resume", "snapshot_id": "..."}

MCP tools

Adds MCP wrappers:

• list_snapshots()
• create_snapshot()
• resume_snapshot(snapshot_id)

These wrappers preserve structured HTTP endpoint errors through the MCP bridge, including http_status.

Opt-in behavior

Snapshots are disabled by default.

Enable automatic snapshot capture by launching the game with:

STS2_MCP_SNAPSHOTS=1

Override the snapshot root with:

STS2_MCP_SNAPSHOT_DIR=/path/to/snapshot/root

Without an override, snapshots are stored under the detected active account save root in sts2_mcp_snapshots.

Automatic and manual snapshots

When enabled, automatic snapshots subscribe to the game save event and copy the active run save whenever STS2 writes it.

Manual snapshot creation copies the active profile's latest:

• current_run.save
• current_run_mp.save

into a snapshot directory and writes metadata with profile, save scope, run identity, save time, mode, source file name, and creation time.

Manual creation is rejected on map and shop-like screens because those STS2 save states do not restore exactly:

• map
• shop
• fake_merchant

The docs call out the recommended workflow: snapshot after choosing a map node, before entering a shop, or after leaving it.

Restore behavior

resume restores a selected snapshot to the active profile's current-run save slot.

Restore is rejected while a run is in progress. After a successful restore, use the in-game Continue flow to load the restored run.

If a current-run save already exists at the restore destination, the endpoint first writes a:

.pre_snapshot_resume_*.backup

copy before overwriting it.

Restore safety

The restore path is deliberately not trusted from serialized snapshot metadata.

The implementation:

• reconstructs snapshot file paths from the snapshot root, snapshot ID, and supported save filename
• accepts only current_run.save and current_run_mp.save
• derives restore destinations from the active profile/save root
• rejects snapshot metadata with unsupported save filenames
• enumerates only immediate snapshot directories instead of recursively scanning arbitrary trees
• sanitizes snapshot IDs as path components
• logs snapshot exceptions and metadata parse failures

Structured errors

Snapshot actions return stable structured error codes such as:

• snapshots_disabled
• missing_snapshot_id
• unknown_snapshot_action
• snapshot_not_found
• current_run_save_not_found
• run_in_progress
• snapshot_state_not_supported
• save_manager_unavailable
• snapshot_restore_path_unavailable
• snapshots_read_failed
• snapshot_create_failed
• snapshot_resume_failed

Snapshot request validation reports malformed requests before feature-disabled state, so clients get stable validation errors for missing actions or missing snapshot IDs.

Documentation

Updates:

• README.md
• docs/raw-full.md
• docs/raw-simplified.md
• mcp/README.md
• docs/endpoint-contracts.md

The dedicated endpoint-contract doc now covers snapshot enablement, API actions, restore safety rules, blocked UI states, structured error codes, MCP wrappers, and audit coverage.

Validation

Completed locally on this branch:

• python3 -m py_compile scripts/audit_endpoints.py scripts/test_mcp_server.py mcp/server.py
• python3 scripts/audit_endpoints.py --skip-live
• uv run --project mcp python scripts/test_mcp_server.py
• "/mnt/c/Program Files/dotnet/dotnet.exe" build STS2_MCP.csproj -c Release -o out/STS2_MCP -p:STS2GameDir="C:\Program Files (x86)\Steam\steamapps\common\Slay the Spire 2"

The .NET build completed successfully with 0 warnings and 0 errors.

Live snapshot validation was not rerun during this upstream port because it requires launching the game with STS2_MCP_SNAPSHOTS=1. The source PR includes live verification notes for snapshot listing, manual creation, and in-progress restore rejection.