Notice when Steam updated a game's install, and protect the version the player switched to #250

Open
opened 2026-10-27 15:46:04 -05:00 by ethan-hann · 1 comment
Owner

Second part of #243 (the first part, in 0.9.20, makes sure Steam is running before a Steam game starts from its program, and never starts a game through Steam's own launch path). Research: .han/out/research-243-drm-launch.md (kept locally), option O5.

Steam can still update an install on its own while it runs, which would overwrite a version the player switched to. Record the Steam manifest's buildid, TargetBuildID, StateFlags and LastUpdated (appmanifest_.acf, read only: D56.5 forbids writing store files) before a launch; warn before starting a Steam game that has an update waiting; and when both the install and the manifest changed during play, withhold the after-play choices that capture the install, offer a saves-only snapshot, and offer to put the player's version back. Gate the approach on the hand test the research names: an older install with an update pending, started from its program and through Steam, plus a cold Steam start, on Windows and on the Linux VM.

Second part of #243 (the first part, in 0.9.20, makes sure Steam is running before a Steam game starts from its program, and never starts a game through Steam's own launch path). Research: .han/out/research-243-drm-launch.md (kept locally), option O5. Steam can still update an install on its own while it runs, which would overwrite a version the player switched to. Record the Steam manifest's buildid, TargetBuildID, StateFlags and LastUpdated (appmanifest_<id>.acf, read only: D56.5 forbids writing store files) before a launch; warn before starting a Steam game that has an update waiting; and when both the install and the manifest changed during play, withhold the after-play choices that capture the install, offer a saves-only snapshot, and offer to put the player's version back. Gate the approach on the hand test the research names: an older install with an update pending, started from its program and through Steam, plus a cold Steam start, on Windows and on the Linux VM.
ethan-hann added this to the 1.0 milestone 2026-10-27 15:46:04 -05:00
Author
Owner

Design proposal (research only, nothing built)

What exists already (0.9.20, D67.4)

SteamInstallState (src/Savepoint.Core/Launch/SteamInstallState.cs) reads buildid, LastUpdated and StateFlags from appmanifest_<id>.acf, read-only. LaunchOrchestrator.Steam.cs reads it before Steam starts, again once Steam is ready (RefuseBeforeSwitchWhenSteamUpdatesAsync) and again just before the program starts (RefuseWhenSteamUpdatesAsync). So the "before play" protection is built. What is missing is everything after the program starts: nothing keeps the ready-time reading, DescribeExitAsync never reads the manifest, and SessionState.Exited only knows ChangedInstallFileCount.

Two gaps in the existing reader: TargetBuildID is not read, and IsUpdating leaves out Validating (131072) and Update Stopping (8388608), although D67.4 says validation refuses.

The flag bits

No Valve document lists them. Three independent readers agree on the bit table: Lutris appmanifest.py, steamlocate app.rs (bits 13 to 15 unused, which matches the code's mask), and LaunchBox's note (4 installed, 6 update required). Bits: 1 Uninstalled, 2 Update Required, 4 Fully Installed, 8 Encrypted, 16 Locked, 32 Files Missing, 64 App Running, 128 Files Corrupt, 256 Update Running, 512 Update Paused, 1024 Update Started, 2048 Uninstalling, 4096 Backup Running, 65536 Reconfiguring, 131072 Validating, 262144 Adding Files, 524288 Preallocating, 1048576 Downloading, 2097152 Staging, 4194304 Committing, 8388608 Update Stopping.

So: update waiting = bit 2 set, or TargetBuildID present and not equal to buildid (LibraryFixtures has real examples: 518 paused update, 22 locked). Update running = the work bits the code already masks, plus 131072 and 8388608. Update happened = buildid or LastUpdated changed since the reading taken at launch.

What to read and when

  1. Add TargetBuildID and UpdateRequired to SteamInstallState. Widen the running mask by the two bits above.
  2. Keep the reading taken once Steam is ready on the session's SessionBook record, next to Starts.
  3. Read again in DescribeExitAsync, and once more in CompleteSessionAsync before a capture starts, since Steam applies a queued update as soon as the game quits.
  4. Read it for every game whose install sits in a Steam library, whatever the launch method. Today ReadSteamInstallAsync goes through SteamGames.NeedsClient, which is false for Through Steam, and that is exactly the path where updates happen. The D67 refusals stay exe-only; only the record-and-compare widens.

Player-facing flow

Before play. LaunchPreview gets a SteamUpdateWaiting note beside SteamNeeded: "Steam has an update waiting for this game. If the game asks Steam to start it, Steam installs the update first and replaces the version you switched to. SavePoint will tell you after you play." For Through Steam: "Steam will install its update before the game starts." A note, not a refusal: the player may want the update.

During play. Nothing new; D67 covers the window up to the program start.

After play. SessionState.Exited gains a SteamUpdated flag, true only when the manifest changed since the ready-time reading and ChangedInstallFileCount is above 0 (the install diff is the ground truth; the manifest says why). Then:

  • The install note becomes: "Steam updated this game while you played, so the game's own files are now Steam's newest version, not the version you switched to."
  • The after-play choices leave out the ones that capture the install (Keep as new, Replace, New profile, Continue) and offer two new choices: Save my saves only (a capture plan that skips the install folder, as a left folder is skipped today) and Put my version back (DiscardChangesAsync(gameId, RepoRole.Install), which already restores the install to the snapshot the launch loaded; no new git work). Not now stays.
  • A third button, "Keep Steam's version anyway", reopens the normal choices behind a confirmation that names the update, so a player who wanted the update is not stuck.
  • Manifest changed but no install file changed: the note only (Steam validated or rewrote the manifest). Install changed but manifest not: today's note, unchanged.

What SavePoint cannot prevent

It never writes store files (D56.5), so it cannot stop Steam. It cannot protect a game that restarts itself through Steam, a Through Steam launch, or a Proton game on Linux; for those the promise is: told before, told after, never snapshotted as yours, and one click back. A background download that Steam applies after the exit reading and before the capture is caught by the re-read before capture. Steam does not update a running game, so the install diff is stable while the game runs.

Options

  • A. Note only. Smallest; the player can still snapshot Steam's build as their version by habit, since Keep is the preselected card today. Not recommended.
  • B. Withhold capture choices, offer saves-only and put-back, confirm to override. Recommended: meets the "a store launch never defeats a switched version" rule without taking the update away from a player who wanted it.
  • C. Put the version back automatically. Simplest for the player, but discards an update silently, and a game that needs the new build then will not start. Not recommended as the default; fine as the preselected card in B.

Hand test before building

On Windows and the Linux VM, with a game Steam has updated: switch to the older snapshot, confirm the manifest still names the newer buildid, then (a) run the exe with Steam open, (b) start Through Steam, (c) close Steam and start it cold before any launch. Repeat with an update genuinely waiting (flags 6 or 518). Record flags, buildid, TargetBuildID, LastUpdated, and whether the files changed. If (b) leaves an older install alone, part of this design shrinks and Through Steam becomes safe; if (c) rewrites files, D67's ordering is confirmed. Also one restart-class game and Balatro.

Open questions before building

  1. Option B, or A or C?
  2. Should "Keep Steam's version anyway" exist, or is the override only reachable through Edit game and a fresh snapshot?
  3. Preselected card after an update: Put my version back, or Save my saves only?
  4. Does the Through Steam pre-play note refuse, or warn only?
  5. Store the manifest's buildid on each snapshot as a second version line ("Steam build 180836") beside the detected version, or keep the Version column as it is? This is the 7.06 versus 180836 question; a separate issue either way.
  6. Does the update check also cover GOG Galaxy (autoUpdate in Galaxy's settings), or Steam only for 1.0?

Rough size

Core: 4 to 6 files (SteamInstallState, SessionBook, the session, complete and preview parts of LaunchOrchestrator, two new completion choices with their plans), 1 to 2 days with tests from LibraryFixtures manifests. App: dialog cards, preview note, catalog keys, half a day. Docs and decision entry, half a day. Hand tests, one evening per OS, and they come first. Total about 3 to 4 days plus the hand tests.

## Design proposal (research only, nothing built) ### What exists already (0.9.20, D67.4) `SteamInstallState` (`src/Savepoint.Core/Launch/SteamInstallState.cs`) reads `buildid`, `LastUpdated` and `StateFlags` from `appmanifest_<id>.acf`, read-only. `LaunchOrchestrator.Steam.cs` reads it before Steam starts, again once Steam is ready (`RefuseBeforeSwitchWhenSteamUpdatesAsync`) and again just before the program starts (`RefuseWhenSteamUpdatesAsync`). So the "before play" protection is built. What is missing is everything after the program starts: nothing keeps the ready-time reading, `DescribeExitAsync` never reads the manifest, and `SessionState.Exited` only knows `ChangedInstallFileCount`. Two gaps in the existing reader: `TargetBuildID` is not read, and `IsUpdating` leaves out Validating (131072) and Update Stopping (8388608), although D67.4 says validation refuses. ### The flag bits No Valve document lists them. Three independent readers agree on the bit table: [Lutris appmanifest.py](https://github.com/lutris/lutris/blob/master/lutris/util/steam/appmanifest.py), [steamlocate app.rs](https://docs.rs/crate/steamlocate/2.0.0-beta.3/source/src/app.rs) (bits 13 to 15 unused, which matches the code's mask), and [LaunchBox's note](https://feedback.launchbox-app.com/help/articles/3293870-steam-game-stuck-as-installing-in-launchbox) (4 installed, 6 update required). Bits: 1 Uninstalled, 2 Update Required, 4 Fully Installed, 8 Encrypted, 16 Locked, 32 Files Missing, 64 App Running, 128 Files Corrupt, 256 Update Running, 512 Update Paused, 1024 Update Started, 2048 Uninstalling, 4096 Backup Running, 65536 Reconfiguring, 131072 Validating, 262144 Adding Files, 524288 Preallocating, 1048576 Downloading, 2097152 Staging, 4194304 Committing, 8388608 Update Stopping. So: **update waiting** = bit 2 set, or `TargetBuildID` present and not equal to `buildid` (`LibraryFixtures` has real examples: 518 paused update, 22 locked). **Update running** = the work bits the code already masks, plus 131072 and 8388608. **Update happened** = `buildid` or `LastUpdated` changed since the reading taken at launch. ### What to read and when 1. Add `TargetBuildID` and `UpdateRequired` to `SteamInstallState`. Widen the running mask by the two bits above. 2. Keep the reading taken once Steam is ready on the session's `SessionBook` record, next to `Starts`. 3. Read again in `DescribeExitAsync`, and once more in `CompleteSessionAsync` before a capture starts, since Steam applies a queued update as soon as the game quits. 4. Read it for every game whose install sits in a Steam library, whatever the launch method. Today `ReadSteamInstallAsync` goes through `SteamGames.NeedsClient`, which is false for Through Steam, and that is exactly the path where updates happen. The D67 refusals stay exe-only; only the record-and-compare widens. ### Player-facing flow **Before play.** `LaunchPreview` gets a `SteamUpdateWaiting` note beside `SteamNeeded`: "Steam has an update waiting for this game. If the game asks Steam to start it, Steam installs the update first and replaces the version you switched to. SavePoint will tell you after you play." For Through Steam: "Steam will install its update before the game starts." A note, not a refusal: the player may want the update. **During play.** Nothing new; D67 covers the window up to the program start. **After play.** `SessionState.Exited` gains a `SteamUpdated` flag, true only when the manifest changed since the ready-time reading and `ChangedInstallFileCount` is above 0 (the install diff is the ground truth; the manifest says why). Then: - The install note becomes: "Steam updated this game while you played, so the game's own files are now Steam's newest version, not the version you switched to." - The after-play choices leave out the ones that capture the install (Keep as new, Replace, New profile, Continue) and offer two new choices: **Save my saves only** (a capture plan that skips the install folder, as a left folder is skipped today) and **Put my version back** (`DiscardChangesAsync(gameId, RepoRole.Install)`, which already restores the install to the snapshot the launch loaded; no new git work). Not now stays. - A third button, "Keep Steam's version anyway", reopens the normal choices behind a confirmation that names the update, so a player who wanted the update is not stuck. - Manifest changed but no install file changed: the note only (Steam validated or rewrote the manifest). Install changed but manifest not: today's note, unchanged. ### What SavePoint cannot prevent It never writes store files (D56.5), so it cannot stop Steam. It cannot protect a game that restarts itself through Steam, a Through Steam launch, or a Proton game on Linux; for those the promise is: told before, told after, never snapshotted as yours, and one click back. A background download that Steam applies after the exit reading and before the capture is caught by the re-read before capture. Steam does not update a running game, so the install diff is stable while the game runs. ### Options - **A. Note only.** Smallest; the player can still snapshot Steam's build as their version by habit, since Keep is the preselected card today. Not recommended. - **B. Withhold capture choices, offer saves-only and put-back, confirm to override.** Recommended: meets the "a store launch never defeats a switched version" rule without taking the update away from a player who wanted it. - **C. Put the version back automatically.** Simplest for the player, but discards an update silently, and a game that needs the new build then will not start. Not recommended as the default; fine as the preselected card in B. ### Hand test before building On Windows and the Linux VM, with a game Steam has updated: switch to the older snapshot, confirm the manifest still names the newer `buildid`, then (a) run the exe with Steam open, (b) start Through Steam, (c) close Steam and start it cold before any launch. Repeat with an update genuinely waiting (flags 6 or 518). Record flags, `buildid`, `TargetBuildID`, `LastUpdated`, and whether the files changed. If (b) leaves an older install alone, part of this design shrinks and Through Steam becomes safe; if (c) rewrites files, D67's ordering is confirmed. Also one restart-class game and Balatro. ### Open questions before building 1. Option B, or A or C? 2. Should "Keep Steam's version anyway" exist, or is the override only reachable through Edit game and a fresh snapshot? 3. Preselected card after an update: Put my version back, or Save my saves only? 4. Does the Through Steam pre-play note refuse, or warn only? 5. Store the manifest's `buildid` on each snapshot as a second version line ("Steam build 180836") beside the detected version, or keep the Version column as it is? This is the 7.06 versus 180836 question; a separate issue either way. 6. Does the update check also cover GOG Galaxy (`autoUpdate` in Galaxy's settings), or Steam only for 1.0? ### Rough size Core: 4 to 6 files (`SteamInstallState`, `SessionBook`, the session, complete and preview parts of `LaunchOrchestrator`, two new completion choices with their plans), 1 to 2 days with tests from `LibraryFixtures` manifests. App: dialog cards, preview note, catalog keys, half a day. Docs and decision entry, half a day. Hand tests, one evening per OS, and they come first. Total about 3 to 4 days plus the hand tests.
Sign in to join this conversation.
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
ethan-hann/SavePoint#250
No description provided.