Merge pull request 'Fix flaky ScorekeeperSessionTest' (#11) from fix/scorekeeper-test-flake into dev

A guest counts as connected before the host's sheet has arrived over the socket, so
tests that read the guest's players straight away could see an empty list. The helper
now waits for the guest to hold the host's sheet. 0 failures in 12 runs (was ~1 in 3).

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016eTor2tpxKb4dXbd8RqnvZ

CLAUDE.md

@@ -1,78 +1,61 @@
-> **Moved to Gitea.** CI now runs on Gitea Actions at
-> `git.wallacenet.ca/devadmin/ProLibertateGames`, publishing to Cloudflare Pages
-> (`plg.wallacenet.ca`) only. The sandbox notes below describe the earlier GitHub
-> setup (no CI run from session pushes, `workflow_dispatch` as the workaround);
-> re-verify them against Gitea before relying on them.
-
 # Working on this repo with Claude
 
-## Nothing a session does triggers CI. Dispatch it explicitly.
+CI runs on **Gitea Actions** at `git.wallacenet.ca/devadmin/ProLibertateGames`
+(workflows in `.github/workflows/`), publishing to Cloudflare Pages
+(`plg.wallacenet.ca`). The workflow below was measured on the dev machine
+(`~/ProLibertateGames`); it replaces the earlier GitHub-sandbox notes, which no
+longer apply.
 
-GitHub creates **no workflow run** for anything this sandbox does — pushing a
+## Build, test and lint locally
-branch, opening a pull request, or merging one. All of it goes through the same
-integration, and GitHub suppresses event-triggered runs from it. The pull
-request will say it was opened by the repo owner; that is only how the UI
-attributes it, and it does not change the suppression.
 
-This was measured, not assumed:
+Gradle works on the dev machine. Two environment variables are required: the
+default JDK is 25, which Gradle 8.14 cannot use, and the Android SDK lives in the
+home directory.
 
-| Action | Result |
+```
-| --- | --- |
+export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
-| Human pushes a Claude-authored commit (`d165e5ef`, `469c900e`) | CI runs |
+export ANDROID_HOME=$HOME/android-sdk      # platform 34, build-tools 34.0.0
-| Session pushes `dev` / `main` (`43394b8`, `742add4`) | no run |
+./gradlew testDebugUnitTest lintDebug assembleDebug
-| Session opens a PR against `dev` (#1) | no run |
+```
-| Session calls `workflow_dispatch` | **runs** |
 
-`workflow_dispatch` works because it creates a run directly instead of relying
+The Katan tests run in seconds; a clean build takes a few minutes. Run the full
-on an event. It is the only mechanism available from a session, so every build
+suite, lint and `assembleDebug` before pushing: they are what CI runs. There is
-has to be asked for by hand.
+no KVM, so no emulator; the engine and the UI logic are covered by unit tests
+(see `docs/UI-catan.md`).
 
-## Verify before merging, without publishing
+## Shipping: branch, PR, CI, merge
 
-`ci.yml` builds, tests and lints on any ref, but its staging and publishing
+1. Branch from `dev`; before pushing, merge `origin/dev` in (it moves between
-steps are gated on `github.ref == 'refs/heads/dev'`. Dispatching it on a
+   sessions).
-**feature branch** therefore gives the full check — build, unit tests, Android
+2. Plain `git push` has no credentials. Use the Gitea token as a one-off header:
-lint — and publishes nothing.
+   `git -c "http.extraheader=Authorization: token $(cat ~/.config/gitea/token)" push -u origin <branch>`.
-
+3. Open the PR with `POST /api/v1/repos/devadmin/ProLibertateGames/pulls`
-So the working loop is:
+   (same token, `Authorization: token ...`). CI (`ci.yml`) runs on the PR: build,
-
+   unit tests and Android lint; it publishes nothing. Poll
-1. Commit and push the feature branch.
+   `/actions/runs` until it completes (about 7 minutes).
-2. Dispatch `ci.yml` on that branch. Wait for green. This is the real review
+4. Merge with `POST .../pulls/N/merge {"Do":"merge"}`. The push to `dev` runs
-   gate, and it is the only verification that exists (see below).
+   `ci.yml` again and publishes the build (about 9 minutes).
-3. Open the PR through the API and merge it there, so the change is reviewable
-   and the merge commit is honest about what happened. Neither step builds
-   anything.
-4. Dispatch the target branch's workflow to actually build and publish:
-   `ci.yml` on `dev`, `release.yml` on `main`.
-
-Skipping step 4 leaves a branch whose head was never built and no release.
 
 ## Merging is a shipping action
 
 Both long-lived branches publish, so a merge is a release, not just an
 integration:
 
-- **`dev`** → `ci.yml` publishes a `v<series>.N-dev` **prerelease**, offered by the
+- **`dev`** publishes a `v<series>.N-dev` build to
-  in-app updater to anyone on the Dev channel.
+  `https://plg.wallacenet.ca/dev/latest.json`, offered by the in-app updater to
-- **`main`** → `release.yml` publishes a **production** release, which the
+  anyone on the Dev channel.
-  updater installs for everyone on the Production channel.
+- **`main`** runs `release.yml` and publishes a **production** release for
+  everyone on the Production channel. Confirm before merging to `main`.
+  `release.yml` runs `assembleDebug` only (no tests, no lint), so a `main`
+  release is only as verified as the `dev` build it replays.
 
-Confirm before shipping to `main`. Note that `release.yml` runs `assembleDebug`
+## Katan
-only — no tests, no lint — so a `main` release is only as verified as the `dev`
-build it replays.
 
-## Gradle does not run in the sandbox
+The island game is catalogue id `catan`, shown as **Katan**. It has two rule
-
+sets chosen at setup: the base game (`docs/RULES-catan.md`) and Cities & Knights
-`./gradlew` cannot resolve the Android plugin here: the proxy blocks
+(`docs/RULES-catan-ck.md`, code in `game/catan/CatanCk*.kt`, state behind
-`dl.google.com` with a 403. No local build, no local test run, no local lint. A
+`CatanState.ck`, which is null in the base game). The screen is layered; see
-dispatched CI run is the only way to find out whether a change compiles.
+`docs/UI-catan.md` before changing it.
-
-## A permanent fix, if you want one
-
-The suppression is a property of the sandbox's credential, so it cannot be
-fixed from inside a session. Giving the environment a personal access token to
-push with would make pushes and PRs behave normally for everyone. Until then,
-the dispatch step above is the workaround.
 
 ## Bash output is filtered before it reaches the model
 

app/src/main/java/org/prolibertate/games/MainActivity.kt

@@ -14,7 +14,9 @@ import org.prolibertate.games.ui.AppEnv
 import org.prolibertate.games.ui.AppRoot
 import org.prolibertate.games.ui.theme.ProLibertateTheme
 import org.prolibertate.games.update.Updater
+import java.io.File
 import java.util.UUID
+import org.prolibertate.games.game.engine.SavedGameStore
 
 class MainActivity : ComponentActivity() {
 
@@ -40,6 +42,7 @@ class MainActivity : ComponentActivity() {
                 deviceId = peerId,
             ),
             peerId = peerId,
+            saves = SavedGameStore(File(filesDir, "saved-games")),
         )
 
         setContent {

app/src/main/java/org/prolibertate/games/game/engine/SavedGame.kt

@@ -0,0 +1,101 @@
+package org.prolibertate.games.game.engine
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import java.io.File
+
+/**
+ * A game in progress, kept so it can be picked up again after the app has been
+ * closed.
+ *
+ * The match is stored the way the host holds it: the [config] it was dealt from
+ * (seed, seats, options) and the whole authoritative [stateJson], hidden cards
+ * included, as the game's own rules encode it. Nothing here knows what game it
+ * is; [gameId] is only the name of the slot.
+ */
+@Serializable
+data class SavedMatch(
+    val gameId: String,
+    val config: TableConfig,
+    /** The seat the person at this device plays. */
+    val localSeat: Int,
+    val stateJson: String,
+    /** Wall-clock milliseconds when the position was written. */
+    val savedAtMillis: Long,
+    /** A line saying how the game stands, from the rules' own summary. */
+    val summary: String = "",
+)
+
+/**
+ * One saved game per game, kept as a file each under [directory].
+ *
+ * One slot per game rather than a list: the player is mid-way through a game of
+ * Chess or they are not. Starting a new one replaces it, which is what the
+ * resume prompt on the setup screen says.
+ *
+ * Writes are atomic — the position goes to a temporary file that is then moved
+ * over the real one — so being killed half way through a save leaves the
+ * previous position, not half of the new one. Reads never throw: a file that
+ * will not parse is a game that cannot be resumed, so it is removed and reported
+ * as absent.
+ */
+class SavedGameStore(private val directory: File) {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        encodeDefaults = true
+    }
+
+    private fun fileFor(gameId: String): File {
+        // The ids are catalogue constants, but they become file names, so
+        // nothing that could climb out of the directory is let through.
+        require(gameId.isNotBlank() && gameId.all { it.isLetterOrDigit() || it == '_' || it == '-' }) {
+            "Not a game id: $gameId"
+        }
+        return File(directory, "$gameId.json")
+    }
+
+    /** Writes [match] over whatever was saved for its game. */
+    @Synchronized
+    fun save(match: SavedMatch) {
+        directory.mkdirs()
+        val target = fileFor(match.gameId)
+        val temp = File(directory, "${match.gameId}.json.tmp")
+        temp.writeText(json.encodeToString(SavedMatch.serializer(), match))
+        if (!temp.renameTo(target)) {
+            // Some file systems will not rename over an existing file.
+            target.delete()
+            check(temp.renameTo(target)) { "Could not write the saved game" }
+        }
+    }
+
+    /** The saved game for [gameId], or null if there is none or it cannot be read. */
+    @Synchronized
+    fun load(gameId: String): SavedMatch? {
+        val file = fileFor(gameId)
+        if (!file.isFile) return null
+        val match = runCatching {
+            json.decodeFromString(SavedMatch.serializer(), file.readText())
+        }.getOrNull()
+        if (match == null || match.gameId != gameId) {
+            file.delete()
+            return null
+        }
+        return match
+    }
+
+    /** Forgets the saved game for [gameId]. A no-op if there is none. */
+    @Synchronized
+    fun clear(gameId: String) {
+        fileFor(gameId).delete()
+    }
+
+    /** Every readable saved game, the most recently played first. */
+    @Synchronized
+    fun all(): List<SavedMatch> {
+        val files = directory.listFiles { f -> f.isFile && f.name.endsWith(".json") } ?: return emptyList()
+        return files
+            .mapNotNull { file -> runCatching { load(file.name.removeSuffix(".json")) }.getOrNull() }
+            .sortedByDescending { it.savedAtMillis }
+    }
+}

app/src/main/java/org/prolibertate/games/net/MatchController.kt

@@ -96,6 +96,27 @@ class MatchController<S : Any, M : Any>(
 
     /** Host only: the true state. Clients never see this. */
     private var authoritative: S? = null
+
+    /** A position to carry on from instead of dealing, set by [restore] before [startAsHost]. */
+    private var restored: S? = null
+
+    /**
+     * Host only: told about every position the table reaches, so it can be kept
+     * for later. Called under the table's lock, so it must return quickly — the
+     * snapshot encodes its state only when asked, and the work of writing it
+     * belongs to whoever is listening.
+     */
+    var onHostState: ((HostSnapshot) -> Unit)? = null
+
+    /** One position of the table, as handed to [onHostState]. */
+    class HostSnapshot(
+        val finished: Boolean,
+        val summary: String,
+        private val encode: () -> String,
+    ) {
+        /** The whole true state, encoded by the game's own rules. */
+        fun stateJson(): String = encode()
+    }
     private val lock = Mutex()
     private var sequence = 0
 
@@ -160,7 +181,7 @@ class MatchController<S : Any, M : Any>(
         check(role == Role.HOST) { "Not hosting" }
         clients.forEach { connection -> listenToPeer(connection) }
         scope.launch {
-            val initial = runCatching { rules.initialState(config) }.getOrElse { error ->
+            val initial = restored ?: runCatching { rules.initialState(config) }.getOrElse { error ->
                 // A table the rules will not accept is a dead end, not a reason
                 // to take the app down with it: this runs in the screen's own
                 // scope, where nothing would catch it.
@@ -175,6 +196,20 @@ class MatchController<S : Any, M : Any>(
         }
     }
 
+    /**
+     * Host: carry on from a saved position instead of dealing a new game.
+     *
+     * Call before [startAsHost]. Returns false, and changes nothing, if
+     * [stateJson] cannot be read by this version of the game — a save made by an
+     * older build, say — and the caller should deal a fresh table instead.
+     */
+    fun restore(stateJson: String): Boolean {
+        check(role == Role.HOST) { "Only a host can restore a game" }
+        val state = runCatching { rules.decodeState(stateJson) }.getOrNull() ?: return false
+        restored = state
+        return true
+    }
+
     private fun listenToPeer(connection: Connection) {
         peers[connection.peerId] = connection
         peerJobs[connection.peerId] = scope.launch {
@@ -449,6 +484,16 @@ class MatchController<S : Any, M : Any>(
         }
         _finished.value = rules.isFinished(current)
 
+        if (role == Role.HOST) {
+            onHostState?.invoke(
+                HostSnapshot(
+                    finished = rules.isFinished(current),
+                    summary = rules.summary(current),
+                    encode = { rules.encodeState(current) },
+                ),
+            )
+        }
+
         for (slot in config.seats) {
             val peerId = slot.peerId ?: continue
             val connection = peers[peerId] ?: continue

app/src/main/java/org/prolibertate/games/net/MatchSaver.kt

@@ -0,0 +1,95 @@
+package org.prolibertate.games.net
+
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.collectLatest
+import kotlinx.coroutines.flow.filterNotNull
+import kotlinx.coroutines.launch
+import org.prolibertate.games.game.engine.SavedGameStore
+import org.prolibertate.games.game.engine.SavedMatch
+import org.prolibertate.games.game.engine.TableConfig
+
+/**
+ * Keeps the position of one table on disk as it is played.
+ *
+ * It is fed every position the host reaches ([offer]) and writes the newest one
+ * off the main thread. Positions that arrive while a write is under way are
+ * dropped in favour of the latest — a computer's turn can be several moves in a
+ * second, and only where the game stands matters. A finished game is not kept:
+ * its slot is cleared, so a won game is not offered back as one to resume.
+ *
+ * [flush] writes whatever has not been written yet, on the caller's thread. It
+ * is what makes leaving the table, or the app going to the background, safe: the
+ * background writer may not have caught up, and the process may not be given the
+ * chance to let it.
+ */
+class MatchSaver(
+    private val store: SavedGameStore,
+    private val gameId: String,
+    private val config: TableConfig,
+    private val localSeat: Int,
+    private val scope: CoroutineScope,
+    private val clock: () -> Long = System::currentTimeMillis,
+) {
+    private val latest = MutableStateFlow<MatchController.HostSnapshot?>(null)
+    private var worker: Job? = null
+    private var written: MatchController.HostSnapshot? = null
+    private var discarded = false
+
+    /** Starts the background writer. */
+    fun start() {
+        worker = scope.launch(Dispatchers.IO) {
+            latest.filterNotNull().collectLatest { write(it) }
+        }
+    }
+
+    /** Hands over the newest position. Cheap: the encoding happens on the writer. */
+    fun offer(snapshot: MatchController.HostSnapshot) {
+        latest.value = snapshot
+    }
+
+    /** Writes the newest position now if the writer has not already. */
+    fun flush() {
+        latest.value?.let { write(it) }
+    }
+
+    /** The game was ended on purpose: forget the saved position and write no more. */
+    @Synchronized
+    fun discard() {
+        discarded = true
+        worker?.cancel()
+        worker = null
+        runCatching { store.clear(gameId) }
+    }
+
+    fun stop() {
+        worker?.cancel()
+        worker = null
+    }
+
+    @Synchronized
+    private fun write(snapshot: MatchController.HostSnapshot) {
+        if (discarded || snapshot === written) return
+        written = snapshot
+        // Saving is a courtesy to the player: a full disk must not take the game
+        // down with it.
+        runCatching {
+            if (snapshot.finished) {
+                store.clear(gameId)
+            } else {
+                store.save(
+                    SavedMatch(
+                        gameId = gameId,
+                        config = config,
+                        localSeat = localSeat,
+                        stateJson = snapshot.stateJson(),
+                        savedAtMillis = clock(),
+                        summary = snapshot.summary,
+                    ),
+                )
+            }
+        }
+    }
+}

app/src/main/java/org/prolibertate/games/ui/AppRoot.kt

@@ -29,6 +29,8 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.CompositionLocalProvider
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.produceState
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
@@ -50,6 +52,10 @@ import org.prolibertate.games.settings.SettingsRepository
 import org.prolibertate.games.ui.game.LocalCardSpeed
 import org.prolibertate.games.update.UpdateChannel
 import org.prolibertate.games.update.Updater
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import org.prolibertate.games.game.engine.SavedGameStore
+import org.prolibertate.games.game.engine.SavedMatch
 
 /** Everything the screens need, assembled once by the activity. */
 class AppEnv(
@@ -60,6 +66,8 @@ class AppEnv(
     /** The shared score sheet, for the Scorekeeper to host or join. */
     val scoreSession: ScorekeeperSession,
     val peerId: String,
+    /** Games in progress, kept between sessions. */
+    val saves: SavedGameStore,
 )
 
 /**
@@ -83,6 +91,8 @@ sealed interface Route {
         val config: TableConfig,
         val hosting: Boolean,
         val localSeat: Int,
+        /** A saved position to carry on from, as the game's rules encoded it; null deals a new game. */
+        val resumeState: String? = null,
     ) : Route
 }
 
@@ -167,6 +177,10 @@ private fun AppContent(
             // Dev builds show the games that are not finished yet; production
             // releases list only what can actually be played.
             showComingSoon = showComingSoon,
+            saved = savedGames(env, stack),
+            onResume = { saved ->
+                push(Route.Play(saved.gameId, saved.config, true, saved.localSeat, saved.stateJson))
+            },
             onPickSection = { push(Route.Section(it)) },
             onJoinGame = { push(Route.Lobby(gameId = "", optionsJson = "{}", hosting = false)) },
             onScorekeeper = { push(Route.Scorekeeper) },
@@ -194,7 +208,13 @@ private fun AppContent(
             onBack = { pop() },
         )
 
-        is Route.Setup -> GameSetupScreen(
+        is Route.Setup -> {
+            // Bumped when the saved game is thrown away, so the banner goes with it.
+            var discards by remember(route) { mutableIntStateOf(0) }
+            val saved by produceState<SavedMatch?>(null, route, discards) {
+                value = withContext(Dispatchers.IO) { env.saves.load(route.gameId) }
+            }
+            GameSetupScreen(
                 descriptor = GameCatalog.byId(route.gameId)!!,
                 playerName = settings.displayName,
                 onBack = { pop() },
@@ -202,7 +222,16 @@ private fun AppContent(
                 onHostOnline = { optionsJson ->
                     push(Route.Lobby(route.gameId, optionsJson, hosting = true))
                 },
+                saved = saved,
+                onResume = { match ->
+                    push(Route.Play(match.gameId, match.config, true, match.localSeat, match.stateJson))
+                },
+                onDiscardSaved = {
+                    env.saves.clear(route.gameId)
+                    discards++
+                },
             )
+        }
 
         is Route.Lobby -> LobbyScreen(
             env = env,
@@ -231,6 +260,8 @@ private fun AppContent(
 @Composable
 fun MainMenuScreen(
     showComingSoon: Boolean,
+    saved: List<SavedMatch>,
+    onResume: (SavedMatch) -> Unit,
     onPickSection: (GameMenu) -> Unit,
     onJoinGame: () -> Unit,
     onScorekeeper: () -> Unit,
@@ -280,6 +311,23 @@ fun MainMenuScreen(
                     )
                 }
 
+                // Games left half-played, most recent first, above everything
+                // else: coming back to the app is mostly coming back to one.
+                if (saved.isNotEmpty()) {
+                    Text(
+                        "Continue",
+                        style = MaterialTheme.typography.labelLarge,
+                        modifier = Modifier.fillMaxWidth(),
+                    )
+                    val now = System.currentTimeMillis()
+                    saved.forEach { match ->
+                        val title = GameCatalog.byId(match.gameId)?.title ?: match.gameId
+                        Button(onClick = { onResume(match) }, modifier = Modifier.fillMaxWidth()) {
+                            Text(savedLine(title, match, now))
+                        }
+                    }
+                }
+
                 // Below the games, and full width like them, so the column
                 // stays one column all the way down.
                 OutlinedButton(
@@ -490,3 +538,17 @@ fun PrimaryAction(text: String, enabled: Boolean = true, onClick: () -> Unit) {
         Text(text)
     }
 }
+
+/**
+ * The saved games, read off the main thread each time the menu is the screen
+ * showing — which is when a game has just been left and its last position
+ * written, so the list is not read until that has happened.
+ */
+@Composable
+private fun savedGames(env: AppEnv, stack: List<Route>): List<SavedMatch> {
+    val onMenu = stack.last() is Route.Menu
+    val saved by produceState(emptyList<SavedMatch>(), onMenu, stack.size) {
+        value = if (onMenu) withContext(Dispatchers.IO) { env.saves.all() } else emptyList()
+    }
+    return saved
+}

app/src/main/java/org/prolibertate/games/ui/EndGameHandle.kt

@@ -0,0 +1,21 @@
+package org.prolibertate.games.ui
+
+import androidx.compose.runtime.staticCompositionLocalOf
+
+/**
+ * How a screen's "End game" button tells the table to forget the saved game.
+ *
+ * Leaving a table keeps its position so it can be resumed; ending one on purpose
+ * does not. The two arrive at the screen as the same "go back", so the
+ * difference is carried here instead: [PlayScreen] provides one handle, the match
+ * it builds says what ending means for it by setting [onEnd], and each End-game
+ * dialog calls [end] before it leaves.
+ */
+class EndGameHandle {
+    /** Set by the table once it knows how to forget its own saved position. */
+    var onEnd: () -> Unit = {}
+
+    fun end() = onEnd()
+}
+
+val LocalEndGameHandle = staticCompositionLocalOf { EndGameHandle() }

app/src/main/java/org/prolibertate/games/ui/GameSetupScreen.kt

@@ -9,11 +9,14 @@ import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Button
+import androidx.compose.material3.Card
 import androidx.compose.material3.Divider
 import androidx.compose.material3.FilterChip
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Switch
 import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
@@ -29,6 +32,7 @@ import org.prolibertate.games.game.GameCatalog
 import org.prolibertate.games.game.GameDescriptor
 import org.prolibertate.games.game.engine.PlayerKind
 import org.prolibertate.games.game.engine.PlayerSlot
+import org.prolibertate.games.game.engine.SavedMatch
 import org.prolibertate.games.game.engine.TableConfig
 import org.prolibertate.games.game.backgammon.BackgammonLevel
 import org.prolibertate.games.game.backgammon.BackgammonOptions
@@ -83,6 +87,10 @@ fun GameSetupScreen(
     onBack: () -> Unit,
     onPlayOffline: (TableConfig, Int) -> Unit,
     onHostOnline: (String) -> Unit,
+    /** A game of this kind left half-played, if there is one. */
+    saved: SavedMatch? = null,
+    onResume: (SavedMatch) -> Unit = {},
+    onDiscardSaved: () -> Unit = {},
 ) {
     var euchre by remember { mutableStateOf(EuchreOptions()) }
     var sequence by remember { mutableStateOf(SequenceOptions()) }
@@ -149,6 +157,10 @@ fun GameSetupScreen(
         ) {
             Text(descriptor.blurb, style = MaterialTheme.typography.bodyMedium)
 
+            if (saved != null) {
+                SavedGameBanner(saved, onResume = { onResume(saved) }, onDiscard = onDiscardSaved)
+            }
+
             Divider()
             Text("House rules", fontWeight = FontWeight.Bold)
 
@@ -233,6 +245,12 @@ fun GameSetupScreen(
                 descriptor.id == GameCatalog.PIRATES && playPirates -> 1
                 else -> 0
             }
+            if (saved != null) {
+                Text(
+                    "Starting a new game replaces the one in progress.",
+                    style = MaterialTheme.typography.bodySmall,
+                )
+            }
             PrimaryAction(text = if (solo) "Play" else "Play against the computer") {
                 onPlayOffline(
                     offlineConfig(descriptor.id, optionsJson, seatCount, playerName, localSeat),
@@ -1216,3 +1234,30 @@ private fun PyramidOptionsEditor(options: PyramidOptions, onChange: (PyramidOpti
         onSelect = { onChange(options.copy(redeals = it)) },
     )
 }
+
+/**
+ * The game that was left unfinished, with the two things to do about it. Shown
+ * above the options so it is the first thing seen on coming back to a game.
+ */
+@Composable
+private fun SavedGameBanner(saved: SavedMatch, onResume: () -> Unit, onDiscard: () -> Unit) {
+    Card(modifier = Modifier.fillMaxWidth()) {
+        Column(
+            modifier = Modifier.padding(12.dp),
+            verticalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            Text("Game in progress", fontWeight = FontWeight.Bold)
+            Text(
+                buildString {
+                    append("Saved ${agoText(System.currentTimeMillis(), saved.savedAtMillis)}")
+                    if (saved.summary.isNotBlank()) append(" · ${saved.summary}")
+                },
+                style = MaterialTheme.typography.bodySmall,
+            )
+            Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+                Button(onClick = onResume) { Text("Resume") }
+                TextButton(onClick = onDiscard) { Text("Discard") }
+            }
+        }
+    }
+}

app/src/main/java/org/prolibertate/games/ui/PlayScreen.kt

@@ -2,10 +2,12 @@ package org.prolibertate.games.ui
 
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
 import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.runtime.rememberCoroutineScope
@@ -112,6 +114,8 @@ import org.prolibertate.games.game.wizard.WizardPhase
 import org.prolibertate.games.game.wizard.WizardRules
 import org.prolibertate.games.game.wizard.WizardState
 import org.prolibertate.games.net.MatchController
+import org.prolibertate.games.net.MatchSaver
+import org.prolibertate.games.game.engine.PlayerKind
 import org.prolibertate.games.settings.Settings
 import org.prolibertate.games.ui.game.BackgammonScreen
 import org.prolibertate.games.ui.game.catan.CatanScreen
@@ -155,6 +159,10 @@ fun PlayScreen(
     val scope = rememberCoroutineScope()
     val role = if (route.hosting) MatchController.Role.HOST else MatchController.Role.CLIENT
 
+    // The same handle for every table this screen builds, so an End-game dialog
+    // anywhere below can reach the table that is showing.
+    val endHandle = remember(route) { EndGameHandle() }
+    CompositionLocalProvider(LocalEndGameHandle provides endHandle) {
         when (route.gameId) {
             GameCatalog.EUCHRE -> {
                 val controller = remember(route) {
@@ -699,6 +707,7 @@ fun PlayScreen(
 
             else -> Text("That game isn't playable yet.")
         }
+    }
 }
 
 @Composable
@@ -707,8 +716,38 @@ private fun <S : Any, M : Any> StartMatch(
     controller: MatchController<S, M>,
     route: Route.Play,
 ) {
+    val scope = rememberCoroutineScope()
+    val endHandle = LocalEndGameHandle.current
+
+    // A game against the computer (or on one device) is kept as it is played, so
+    // it can be picked up after the app has been closed. A table with another
+    // device at it is not: the other player's seat cannot be held for them.
+    val saveable = route.hosting && route.config.seats.none { it.kind == PlayerKind.HUMAN_REMOTE }
+    val saver = remember(controller) {
+        if (saveable) {
+            MatchSaver(env.saves, route.gameId, route.config, route.localSeat, scope)
+        } else {
+            null
+        }
+    }
+    // The position to carry on from belongs to the first table only. Dealing
+    // again (solitaire's "new deal") builds a fresh controller under the same
+    // route, and that one must not be put back to where the last one stood.
+    val resume = remember(route) { mutableStateOf(route.resumeState) }
+
     LaunchedEffect(controller) {
         if (route.hosting) {
+            resume.value?.let { saved ->
+                resume.value = null
+                // A save this version cannot read — one from an older build — is
+                // not worth keeping; the table is dealt afresh instead.
+                if (!controller.restore(saved)) env.saves.clear(route.gameId)
+            }
+            if (saver != null) {
+                saver.start()
+                controller.onHostState = saver::offer
+                endHandle.onEnd = saver::discard
+            }
             controller.startAsHost(env.lobby.hostConnections)
         } else {
             env.lobby.clientConnection?.let { controller.startAsClient(it) }
@@ -721,6 +760,10 @@ private fun <S : Any, M : Any> StartMatch(
         env.lobby.rebinder = controller
         onDispose {
             env.lobby.rebinder = null
+            // Whatever the writer has not caught up with is written before the
+            // table goes, so leaving mid-move does not lose the last move.
+            saver?.flush()
+            saver?.stop()
             controller.close()
         }
     }
@@ -734,11 +777,14 @@ private fun <S : Any, M : Any> StartMatch(
     // sent. So the table is asked for again on the way back in, over a fresh
     // link if the old one did not survive.
     val lifecycleOwner = LocalLifecycleOwner.current
-    DisposableEffect(lifecycleOwner, route.hosting) {
+    DisposableEffect(lifecycleOwner, route.hosting, saver) {
         val observer = LifecycleEventObserver { _, event ->
             if (event == Lifecycle.Event.ON_START && !route.hosting) {
                 env.lobby.restoreLink()
             }
+            // The app going to the background may be the last the process hears:
+            // Android can end it without a word, so the position is written now.
+            if (event == Lifecycle.Event.ON_STOP) saver?.flush()
         }
         lifecycleOwner.lifecycle.addObserver(observer)
         onDispose { lifecycleOwner.lifecycle.removeObserver(observer) }

app/src/main/java/org/prolibertate/games/ui/SavedGameText.kt

@@ -0,0 +1,24 @@
+package org.prolibertate.games.ui
+
+import org.prolibertate.games.game.engine.SavedMatch
+
+/** How long ago something happened, in the words a person would use. */
+fun agoText(nowMillis: Long, thenMillis: Long): String {
+    val seconds = ((nowMillis - thenMillis) / 1000).coerceAtLeast(0)
+    val minutes = seconds / 60
+    val hours = minutes / 60
+    val days = hours / 24
+    return when {
+        seconds < 45 -> "just now"
+        minutes < 2 -> "a minute ago"
+        minutes < 60 -> "$minutes minutes ago"
+        hours < 2 -> "an hour ago"
+        hours < 24 -> "$hours hours ago"
+        days < 2 -> "yesterday"
+        else -> "$days days ago"
+    }
+}
+
+/** "Chess · saved 5 minutes ago" for a menu line. */
+fun savedLine(title: String, match: SavedMatch, nowMillis: Long): String =
+    "$title · saved ${agoText(nowMillis, match.savedAtMillis)}"

app/src/main/java/org/prolibertate/games/ui/game/BackgammonScreen.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.clickable
@@ -378,7 +379,12 @@ private fun LeaveDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
                     "at the table is told you have left."
             )
         },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/CardTable.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.BorderStroke
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
@@ -79,7 +80,12 @@ fun PatienceEndDialog(what: String, onEnd: () -> Unit, onKeepPlaying: () -> Unit
         onDismissRequest = onKeepPlaying,
         title = { Text("End this game?") },
         text = { Text(what) },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/CheckersScreen.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.clickable
@@ -314,7 +315,12 @@ private fun EndGameDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
                     "at the table is told you have left."
             )
         },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/ChessScreen.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.clickable
@@ -215,7 +216,12 @@ private fun ConfirmEndDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
                     "at the table is told you have left."
             )
         },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/HeartsScreen.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
@@ -268,7 +269,12 @@ private fun EndHeartsDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
         onDismissRequest = onKeepPlaying,
         title = { Text("End this game?") },
         text = { Text("The game ends here. Anyone else at the table is told you have left.") },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/KlondikeScreen.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.BorderStroke
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
@@ -342,7 +343,12 @@ private fun EndTableDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
         onDismissRequest = onKeepPlaying,
         title = { Text("End this game?") },
         text = { Text("The deal is left as it stands.") },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/MastermindScreen.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.clickable
@@ -356,7 +357,12 @@ private fun EndDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
         onDismissRequest = onKeepPlaying,
         title = { Text("End this game?") },
         text = { Text("The game ends here. Anyone else at the table is told you have left.") },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/MorrisScreen.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.Canvas
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
@@ -483,7 +484,12 @@ private fun LeaveBoardDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
                     "at the table is told you have left."
             )
         },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/PegSolitaireScreen.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.BorderStroke
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
@@ -242,7 +243,12 @@ private fun EndBoardDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
         onDismissRequest = onKeepPlaying,
         title = { Text("End this game?") },
         text = { Text("The board is left as it stands.") },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/PiratesScreen.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.Canvas
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
@@ -371,7 +372,12 @@ private fun LeaveFieldDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
                     "at the table is told you have left."
             )
         },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/TayuScreen.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.Canvas
 import androidx.compose.foundation.gestures.detectTapGestures
 import androidx.compose.foundation.layout.Arrangement
@@ -668,7 +669,12 @@ private fun TayuConfirmEndDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
                     "table is told you have left."
             )
         },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/YahtzeeScreen.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.clickable
@@ -295,7 +296,12 @@ private fun EndCardDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
         onDismissRequest = onKeepPlaying,
         title = { Text("End this game?") },
         text = { Text("The game ends here. Anyone else at the table is told you have left.") },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/main/java/org/prolibertate/games/ui/game/catan/CatanDialogs.kt

@@ -1,5 +1,6 @@
 package org.prolibertate.games.ui.game.catan
 
+import org.prolibertate.games.ui.LocalEndGameHandle
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.ExperimentalLayoutApi
@@ -603,7 +604,12 @@ fun CatanEndGameDialog(onEnd: () -> Unit, onKeepPlaying: () -> Unit) {
                     "at the table is told you have left.",
             )
         },
-        confirmButton = { TextButton(onClick = onEnd) { Text("End the game") } },
+        confirmButton = {
+            // Ending a game on purpose also forgets the saved position: only
+            // leaving the table keeps it to be picked up again.
+            val handle = LocalEndGameHandle.current
+            TextButton(onClick = { handle.end(); onEnd() }) { Text("End the game") }
+        },
         dismissButton = { TextButton(onClick = onKeepPlaying) { Text("Keep playing") } },
     )
 }

app/src/test/java/org/prolibertate/games/game/engine/SavedGameStoreTest.kt

@@ -0,0 +1,119 @@
+package org.prolibertate.games.game.engine
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+import org.junit.rules.TemporaryFolder
+import java.io.File
+
+class SavedGameStoreTest {
+
+    @get:Rule
+    val folder = TemporaryFolder()
+
+    private fun store() = SavedGameStore(File(folder.root, "saves"))
+
+    private fun match(gameId: String = "chess", state: String = "{\"turn\":1}", at: Long = 1_000L) = SavedMatch(
+        gameId = gameId,
+        config = TableConfig(
+            gameId = gameId,
+            seats = listOf(
+                PlayerSlot(0, "You", PlayerKind.HUMAN_LOCAL, 0),
+                PlayerSlot(1, "Computer", PlayerKind.AI, 1),
+            ),
+            optionsJson = "{}",
+            seed = 42L,
+        ),
+        localSeat = 0,
+        stateJson = state,
+        savedAtMillis = at,
+        summary = "White to move",
+    )
+
+    @Test
+    fun `a saved game comes back exactly as it went in`() {
+        val s = store()
+        s.save(match())
+        assertEquals(match(), s.load("chess"))
+    }
+
+    @Test
+    fun `there is nothing to load before anything is saved`() {
+        assertNull(store().load("chess"))
+        assertTrue(store().all().isEmpty())
+    }
+
+    @Test
+    fun `a game keeps one slot, and saving again replaces it`() {
+        val s = store()
+        s.save(match(state = "one", at = 1))
+        s.save(match(state = "two", at = 2))
+        assertEquals("two", s.load("chess")!!.stateJson)
+        assertEquals(1, s.all().size)
+    }
+
+    @Test
+    fun `clearing forgets the game and leaves the others`() {
+        val s = store()
+        s.save(match("chess"))
+        s.save(match("golf"))
+        s.clear("chess")
+        assertNull(s.load("chess"))
+        assertEquals("golf", s.load("golf")!!.gameId)
+        s.clear("chess") // clearing nothing is fine
+    }
+
+    @Test
+    fun `the most recently played game is listed first`() {
+        val s = store()
+        s.save(match("chess", at = 10))
+        s.save(match("golf", at = 30))
+        s.save(match("catan", at = 20))
+        assertEquals(listOf("golf", "catan", "chess"), s.all().map { it.gameId })
+    }
+
+    @Test
+    fun `a file that cannot be read is dropped rather than thrown`() {
+        val s = store()
+        s.save(match())
+        File(folder.root, "saves/chess.json").writeText("{ this is not json")
+        assertNull(s.load("chess"))
+        assertFalse(File(folder.root, "saves/chess.json").exists())
+    }
+
+    @Test
+    fun `a file holding another game is not served as this one`() {
+        val s = store()
+        s.save(match("golf"))
+        File(folder.root, "saves/golf.json").copyTo(File(folder.root, "saves/chess.json"))
+        assertNull(s.load("chess"))
+    }
+
+    @Test
+    fun `a save that was cut off half way leaves the previous position`() {
+        val s = store()
+        s.save(match(state = "good"))
+        // What a kill mid-write leaves behind: a stray temporary file.
+        File(folder.root, "saves/chess.json.tmp").writeText("{ half a wri")
+        assertEquals("good", s.load("chess")!!.stateJson)
+        assertEquals(1, s.all().size)
+    }
+
+    @Test
+    fun `a game id cannot climb out of the folder`() {
+        val bad = runCatching { store().load("../secret") }
+        assertTrue(bad.isFailure)
+    }
+
+    @Test
+    fun `an unknown field from a newer build does not stop a save loading`() {
+        val s = store()
+        s.save(match())
+        val file = File(folder.root, "saves/chess.json")
+        file.writeText(file.readText().replaceFirst("{", "{\"addedLater\":true,"))
+        assertEquals("chess", s.load("chess")!!.gameId)
+    }
+}

app/src/test/java/org/prolibertate/games/net/MatchSaverTest.kt

@@ -0,0 +1,191 @@
+package org.prolibertate.games.net
+
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.runBlocking
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+import org.junit.rules.TemporaryFolder
+import org.prolibertate.games.game.engine.GameAi
+import org.prolibertate.games.game.engine.GameRules
+import org.prolibertate.games.game.engine.PlayerKind
+import org.prolibertate.games.game.engine.PlayerSlot
+import org.prolibertate.games.game.engine.SavedGameStore
+import org.prolibertate.games.game.engine.TableConfig
+import java.io.File
+
+/**
+ * Saving a table as it is played, and starting a table from a save.
+ *
+ * The game here is a counter: one seat, a move adds one, and it is finished at
+ * [GOAL]. It has hidden state — [Counter.secret] — so the tests can check that
+ * what is saved is the true state, not the view a player is shown.
+ */
+class MatchSaverTest {
+
+    @get:Rule
+    val folder = TemporaryFolder()
+
+    private val scopes = mutableListOf<CoroutineScope>()
+
+    @After
+    fun tearDown() {
+        scopes.forEach { it.cancel() }
+    }
+
+    private data class Counter(val n: Int, val secret: String)
+
+    private object Rules : GameRules<Counter, String> {
+        override val gameId = "counter"
+        override fun initialState(config: TableConfig) = Counter(0, "hidden-${config.seed}")
+        override fun currentSeat(state: Counter): Int? = if (state.n >= GOAL) null else 0
+        override fun legalMoves(state: Counter, seat: Int) = if (state.n >= GOAL) emptyList() else listOf("add")
+        override fun applyMove(state: Counter, seat: Int, move: String) = state.copy(n = state.n + 1)
+        override fun isFinished(state: Counter) = state.n >= GOAL
+        override fun summary(state: Counter) = "at ${state.n}"
+        override fun viewFor(state: Counter, seat: Int) = state.copy(secret = "")
+        override fun encodeState(state: Counter) = "${state.n}|${state.secret}"
+        override fun decodeState(json: String): Counter {
+            val (n, secret) = json.split("|", limit = 2)
+            return Counter(n.toInt(), secret)
+        }
+
+        override fun encodeMove(move: String) = move
+        override fun decodeMove(json: String) = json
+    }
+
+    private val config = TableConfig(
+        gameId = "counter",
+        seats = listOf(PlayerSlot(0, "You", PlayerKind.HUMAN_LOCAL, 0)),
+        optionsJson = "{}",
+        seed = 7L,
+    )
+
+    private fun scope() = CoroutineScope(Job() + Dispatchers.Default).also { scopes += it }
+
+    private fun controller(): MatchController<Counter, String> = MatchController(
+        rules = Rules,
+        ai = object : GameAi<Counter, String> {
+            override fun chooseMove(state: Counter, seat: Int, legal: List<String>) = legal.first()
+        },
+        config = config,
+        scope = scope(),
+        role = MatchController.Role.HOST,
+        localSeats = setOf(0),
+        primarySeat = 0,
+    )
+
+    private fun store() = SavedGameStore(File(folder.root, "saves"))
+
+    private fun waitFor(what: String, check: () -> Boolean) = runBlocking {
+        repeat(200) {
+            if (check()) return@runBlocking
+            delay(10)
+        }
+        error("Timed out waiting for $what")
+    }
+
+    private fun saver(s: SavedGameStore, c: MatchController<Counter, String>) =
+        MatchSaver(s, "counter", config, localSeat = 0, scope = scope(), clock = { 123L }).also {
+            it.start()
+            c.onHostState = it::offer
+        }
+
+    @Test
+    fun `every position the table reaches is kept, with the true state`() {
+        val s = store()
+        val c = controller()
+        saver(s, c)
+        c.startAsHost(emptyList())
+        waitFor("the deal") { c.state.value != null }
+        c.submit("add")
+        c.submit("add")
+        waitFor("two moves") { s.load("counter")?.stateJson?.startsWith("2|") == true }
+
+        val saved = s.load("counter")!!
+        assertEquals("2|hidden-7", saved.stateJson) // the hidden part is saved; the view blanks it
+        assertEquals("at 2", saved.summary)
+        assertEquals(123L, saved.savedAtMillis)
+        assertEquals(config, saved.config)
+    }
+
+    @Test
+    fun `a table started from a save carries on from where it stood`() {
+        val s = store()
+        val first = controller()
+        saver(s, first)
+        first.startAsHost(emptyList())
+        waitFor("the deal") { first.state.value != null }
+        repeat(3) { first.submit("add") }
+        waitFor("three moves") { s.load("counter")?.stateJson?.startsWith("3|") == true }
+        first.close()
+
+        val second = controller()
+        assertTrue(second.restore(s.load("counter")!!.stateJson))
+        second.startAsHost(emptyList())
+        waitFor("the restored table") { second.state.value != null }
+        assertEquals(3, second.state.value!!.n)
+        second.submit("add")
+        waitFor("a move after resuming") { second.state.value!!.n == 4 }
+    }
+
+    @Test
+    fun `a save the game cannot read is refused and the table is dealt afresh`() {
+        val c = controller()
+        assertFalse(c.restore("not a counter"))
+        c.startAsHost(emptyList())
+        waitFor("a fresh deal") { c.state.value != null }
+        assertEquals(0, c.state.value!!.n)
+    }
+
+    @Test
+    fun `a finished game is not kept`() {
+        val s = store()
+        val c = controller()
+        saver(s, c)
+        c.startAsHost(emptyList())
+        waitFor("the deal") { s.load("counter") != null }
+        repeat(GOAL) { c.submit("add") }
+        waitFor("the finish") { c.finished.value }
+        waitFor("the slot to clear") { s.load("counter") == null }
+    }
+
+    @Test
+    fun `flush writes the position the background writer has not reached`() {
+        val s = store()
+        val saver = MatchSaver(s, "counter", config, 0, scope(), clock = { 1L })
+        // Not started: nothing is written in the background at all.
+        saver.offer(MatchController.HostSnapshot(false, "at 5") { "5|x" })
+        assertNull(s.load("counter"))
+        saver.flush()
+        assertEquals("5|x", s.load("counter")!!.stateJson)
+    }
+
+    @Test
+    fun `ending a game on purpose forgets it and writes no more`() {
+        val s = store()
+        val saver = MatchSaver(s, "counter", config, 0, scope(), clock = { 1L })
+        saver.offer(MatchController.HostSnapshot(false, "at 1") { "1|x" })
+        saver.flush()
+        assertNotNull(s.load("counter"))
+        saver.discard()
+        assertNull(s.load("counter"))
+        // Leaving after ending must not put it back.
+        saver.offer(MatchController.HostSnapshot(false, "at 2") { "2|x" })
+        saver.flush()
+        assertNull(s.load("counter"))
+    }
+
+    private companion object {
+        const val GOAL = 5
+    }
+}

app/src/test/java/org/prolibertate/games/net/SaveRoundTripAllGamesTest.kt

@@ -0,0 +1,177 @@
+package org.prolibertate.games.net
+
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.prolibertate.games.game.GameCatalog
+import org.prolibertate.games.game.engine.GameAi
+import org.prolibertate.games.game.engine.GameRules
+import org.prolibertate.games.game.engine.PlayerKind
+import org.prolibertate.games.game.engine.PlayerSlot
+import org.prolibertate.games.game.engine.TableConfig
+import org.prolibertate.games.ui.seatCountFor
+import org.prolibertate.games.game.backgammon.BackgammonAi
+import org.prolibertate.games.game.backgammon.BackgammonOptions
+import org.prolibertate.games.game.backgammon.BackgammonRules
+import org.prolibertate.games.game.catan.CatanAi
+import org.prolibertate.games.game.catan.CatanOptions
+import org.prolibertate.games.game.catan.CatanRules
+import org.prolibertate.games.game.checkers.CheckersAi
+import org.prolibertate.games.game.checkers.CheckersOptions
+import org.prolibertate.games.game.checkers.CheckersRules
+import org.prolibertate.games.game.chess.ChessAi
+import org.prolibertate.games.game.chess.ChessOptions
+import org.prolibertate.games.game.chess.ChessRules
+import org.prolibertate.games.game.crazyeights.CrazyEightsAi
+import org.prolibertate.games.game.crazyeights.CrazyEightsOptions
+import org.prolibertate.games.game.crazyeights.CrazyEightsRules
+import org.prolibertate.games.game.cribbage.CribbageAi
+import org.prolibertate.games.game.cribbage.CribbageOptions
+import org.prolibertate.games.game.cribbage.CribbageRules
+import org.prolibertate.games.game.euchre.EuchreAi
+import org.prolibertate.games.game.euchre.EuchreOptions
+import org.prolibertate.games.game.euchre.EuchreRules
+import org.prolibertate.games.game.freecell.FreeCellOptions
+import org.prolibertate.games.game.freecell.FreeCellRules
+import org.prolibertate.games.game.golf.GolfAi
+import org.prolibertate.games.game.golf.GolfOptions
+import org.prolibertate.games.game.golf.GolfRules
+import org.prolibertate.games.game.hearts.HeartsAi
+import org.prolibertate.games.game.hearts.HeartsOptions
+import org.prolibertate.games.game.hearts.HeartsRules
+import org.prolibertate.games.game.kaiser.KaiserAi
+import org.prolibertate.games.game.kaiser.KaiserOptions
+import org.prolibertate.games.game.kaiser.KaiserRules
+import org.prolibertate.games.game.klondike.KlondikeAi
+import org.prolibertate.games.game.klondike.KlondikeOptions
+import org.prolibertate.games.game.klondike.KlondikeRules
+import org.prolibertate.games.game.mastermind.MastermindAi
+import org.prolibertate.games.game.mastermind.MastermindOptions
+import org.prolibertate.games.game.mastermind.MastermindRules
+import org.prolibertate.games.game.morris.MorrisAi
+import org.prolibertate.games.game.morris.MorrisOptions
+import org.prolibertate.games.game.morris.MorrisRules
+import org.prolibertate.games.game.pegsolitaire.PegSolitaireAi
+import org.prolibertate.games.game.pegsolitaire.PegSolitaireOptions
+import org.prolibertate.games.game.pegsolitaire.PegSolitaireRules
+import org.prolibertate.games.game.pirates.PiratesAi
+import org.prolibertate.games.game.pirates.PiratesOptions
+import org.prolibertate.games.game.pirates.PiratesRules
+import org.prolibertate.games.game.president.PresidentAi
+import org.prolibertate.games.game.president.PresidentOptions
+import org.prolibertate.games.game.president.PresidentRules
+import org.prolibertate.games.game.pyramid.PyramidOptions
+import org.prolibertate.games.game.pyramid.PyramidRules
+import org.prolibertate.games.game.sequence.SequenceAi
+import org.prolibertate.games.game.sequence.SequenceOptions
+import org.prolibertate.games.game.sequence.SequenceRules
+import org.prolibertate.games.game.solitaire.FirstLegalAi
+import org.prolibertate.games.game.spider.SpiderOptions
+import org.prolibertate.games.game.spider.SpiderRules
+import org.prolibertate.games.game.tayu.TayuAi
+import org.prolibertate.games.game.tayu.TayuOptions
+import org.prolibertate.games.game.tayu.TayuRules
+import org.prolibertate.games.game.wizard.WizardAi
+import org.prolibertate.games.game.wizard.WizardOptions
+import org.prolibertate.games.game.wizard.WizardRules
+import org.prolibertate.games.game.yahtzee.YahtzeeAi
+import org.prolibertate.games.game.yahtzee.YahtzeeOptions
+import org.prolibertate.games.game.yahtzee.YahtzeeRules
+
+/**
+ * Every game can be saved and picked up again.
+ *
+ * For each game in the catalogue a table is dealt and played by the computer, and
+ * at every single move the whole true state is encoded and decoded again — which
+ * is exactly what saving it to disk and resuming does — and play carries on from
+ * the decoded copy. A game whose state does not survive that, or that cannot make
+ * a legal move from a state it has been through it, fails here.
+ */
+class SaveRoundTripAllGamesTest {
+
+    private val json = Json { encodeDefaults = true }
+
+    private fun <S : Any, M : Any> exercise(
+        gameId: String,
+        rules: GameRules<S, M>,
+        ai: GameAi<S, M>,
+        optionsJson: String,
+        steps: Int = 120,
+    ) {
+        val seats = seatCountFor(gameId, optionsJson)
+        val config = TableConfig(
+            gameId = gameId,
+            seats = (0 until seats).map {
+                PlayerSlot(it, "P$it", if (it == 0) PlayerKind.HUMAN_LOCAL else PlayerKind.AI, it)
+            },
+            optionsJson = optionsJson,
+            seed = 20240607L,
+        )
+        var state = rules.initialState(config)
+        var moves = 0
+        repeat(steps) {
+            if (rules.isFinished(state)) return
+            // The save and the resume: what goes to disk, and what comes back.
+            val saved = rules.encodeState(state)
+            val back = rules.decodeState(saved)
+            assertEquals("$gameId: a saved state encodes differently after a resume", saved, rules.encodeState(back))
+            assertEquals(
+                "$gameId: a resumed state is not on the same seat's turn",
+                rules.currentSeat(state),
+                rules.currentSeat(back),
+            )
+            assertEquals(
+                "$gameId: a resumed state has different legal moves",
+                rules.currentSeat(state)?.let { rules.legalMoves(state, it) },
+                rules.currentSeat(back)?.let { rules.legalMoves(back, it) },
+            )
+            state = back
+
+            val seat = rules.currentSeat(state) ?: return // waiting on a scoreboard, which is not a move
+            val legal = rules.legalMoves(state, seat)
+            if (legal.isEmpty()) return
+            val move = ai.chooseMove(state, seat, legal)
+            assertTrue("$gameId: move $move is not legal after a resume", rules.isLegalMove(state, seat, move))
+            state = rules.applyMove(state, seat, move)
+            moves++
+        }
+        assertTrue("$gameId: made no moves", moves > 0)
+    }
+
+    private inline fun <reified O> opts(o: O) = json.encodeToString(o)
+
+    @Test fun euchre() = exercise(GameCatalog.EUCHRE, EuchreRules, EuchreAi(), opts(EuchreOptions()))
+    @Test fun sequence() = exercise(GameCatalog.SEQUENCE, SequenceRules, SequenceAi(), opts(SequenceOptions()))
+    @Test fun president() = exercise(GameCatalog.PRESIDENT, PresidentRules, PresidentAi(), opts(PresidentOptions()))
+    @Test fun golf() = exercise(GameCatalog.GOLF, GolfRules, GolfAi(), opts(GolfOptions()))
+    @Test fun kaiser() = exercise(GameCatalog.KAISER, KaiserRules, KaiserAi(), opts(KaiserOptions()))
+    @Test fun wizard() = exercise(GameCatalog.WIZARD, WizardRules, WizardAi(), opts(WizardOptions()))
+    @Test fun crazyEights() = exercise(GameCatalog.CRAZY_EIGHTS, CrazyEightsRules, CrazyEightsAi(), opts(CrazyEightsOptions()))
+    @Test fun cribbage() = exercise(GameCatalog.CRIBBAGE, CribbageRules, CribbageAi(), opts(CribbageOptions()))
+    @Test fun tayu() = exercise(GameCatalog.TAYU, TayuRules, TayuAi(), opts(TayuOptions()))
+    @Test fun checkers() = exercise(GameCatalog.CHECKERS, CheckersRules, CheckersAi(), opts(CheckersOptions()))
+    @Test fun backgammon() = exercise(GameCatalog.BACKGAMMON, BackgammonRules, BackgammonAi(), opts(BackgammonOptions()))
+    @Test fun mastermind() = exercise(GameCatalog.MASTERMIND, MastermindRules, MastermindAi(), opts(MastermindOptions()))
+    @Test fun pirates() = exercise(GameCatalog.PIRATES, PiratesRules, PiratesAi(), opts(PiratesOptions()))
+    @Test fun hearts() = exercise(GameCatalog.HEARTS, HeartsRules, HeartsAi, opts(HeartsOptions()))
+    @Test fun pegSolitaire() = exercise(GameCatalog.PEG_SOLITAIRE, PegSolitaireRules, PegSolitaireAi, opts(PegSolitaireOptions()))
+    @Test fun yahtzee() = exercise(GameCatalog.YAHTZEE, YahtzeeRules, YahtzeeAi, opts(YahtzeeOptions()))
+    @Test fun klondike() = exercise(GameCatalog.KLONDIKE, KlondikeRules, KlondikeAi, opts(KlondikeOptions()))
+    @Test fun freecell() = exercise(GameCatalog.FREECELL, FreeCellRules, FirstLegalAi(), opts(FreeCellOptions()))
+    @Test fun spider() = exercise(GameCatalog.SPIDER, SpiderRules, FirstLegalAi(), opts(SpiderOptions()))
+    @Test fun pyramid() = exercise(GameCatalog.PYRAMID, PyramidRules, FirstLegalAi(), opts(PyramidOptions()))
+    @Test fun morris() = exercise(GameCatalog.MORRIS, MorrisRules, MorrisAi(), opts(MorrisOptions()))
+    @Test fun chess() = exercise(GameCatalog.CHESS, ChessRules, ChessAi(), opts(ChessOptions()), steps = 24)
+    @Test fun catan() = exercise(GameCatalog.CATAN, CatanRules, CatanAi(), opts(CatanOptions()), steps = 400)
+
+    @Test
+    fun catanCitiesAndKnights() = exercise(
+        GameCatalog.CATAN,
+        CatanRules,
+        CatanAi(),
+        opts(CatanOptions(3, 13, org.prolibertate.games.game.catan.CatanRuleSet.CITIES_AND_KNIGHTS)),
+        steps = 600,
+    )
+}

app/src/test/java/org/prolibertate/games/net/ScorekeeperSessionTest.kt

@@ -145,6 +145,11 @@ class ScorekeeperSessionTest {
         await("$name to be asking") { host.state.requests.any { it.id == deviceId } }
         host.session.allow(deviceId)
         await("$name to be let in") { guest.state.value.connected }
+        // The sheet follows the connection over the socket, so `connected` can
+        // flip while it is still in flight. Callers read the guest's sheet at
+        // once (its players, its rounds), and on a slow runner that was an empty
+        // one: wait until the guest is looking at the host's.
+        await("$name to receive the sheet") { guest.state.value.sheet == host.state.sheet }
         return guest
     }
 

app/src/test/java/org/prolibertate/games/ui/SavedGameTextTest.kt

@@ -0,0 +1,27 @@
+package org.prolibertate.games.ui
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class SavedGameTextTest {
+    private val minute = 60_000L
+    private val hour = 60 * minute
+    private val day = 24 * hour
+
+    @Test
+    fun `how long ago reads like a person would say it`() {
+        assertEquals("just now", agoText(1_000, 1_000))
+        assertEquals("just now", agoText(30_000, 0))
+        assertEquals("a minute ago", agoText(minute + 20_000, 0))
+        assertEquals("5 minutes ago", agoText(5 * minute, 0))
+        assertEquals("an hour ago", agoText(90 * minute, 0))
+        assertEquals("3 hours ago", agoText(3 * hour, 0))
+        assertEquals("yesterday", agoText(30 * hour, 0))
+        assertEquals("4 days ago", agoText(4 * day, 0))
+    }
+
+    @Test
+    fun `a clock that ran backwards does not say nonsense`() {
+        assertEquals("just now", agoText(0, 10 * minute))
+    }
+}

docs/README.md

@@ -42,6 +42,8 @@ Naming: the catalogue id, lowercase, e.g. `crazy8s` → `RULES-crazy8s.md`.
 
 - Build, CI, releases and OTA are described in the CI section of the root
   [README](../README.md).
+- [SAVED-GAMES.md](SAVED-GAMES.md) — how a game in progress is kept between sessions, and what is
+  not kept.
 - [UI-catan.md](UI-catan.md) — how the Katan screen is layered, and how to restyle,
   re-copy or re-lay-out it without touching the rules.
 - `licenses/` — third-party licences that must travel with the app

docs/SAVED-GAMES.md

@@ -0,0 +1,43 @@
+# Saved games
+
+A game played against the computer (or on one device) is kept as it is played, and can be
+picked up again after the app has been closed.
+
+## What the player sees
+
+- **Main menu → Continue.** Each game left half-played is listed, most recent first
+  ("Chess · saved 5 minutes ago"); tapping it resumes.
+- **A game's setup screen** shows a *Game in progress* card with **Resume** and **Discard**.
+  Starting a new game from that screen replaces the saved one.
+- **Leaving the table** (the back arrow, or the app being closed or sent to the background)
+  keeps the position. **End game → End the game** is the deliberate way to throw it away.
+- A game that is **finished** is not kept.
+- A **networked** table is not kept: the other player's seat cannot be held for them. Only a
+  table with no remote human at it (`PlayerKind.HUMAN_REMOTE`) is saved.
+
+One slot per game: there is one saved Chess game, one saved Katan game, and so on.
+
+## How it works
+
+| Piece | Where | Does |
+| --- | --- | --- |
+| `SavedMatch`, `SavedGameStore` | `game/engine/SavedGame.kt` | one JSON file per game under `filesDir/saved-games/`, written atomically (temp file, then renamed); an unreadable file is deleted and read as absent |
+| `MatchController.onHostState`, `restore` | `net/MatchController.kt` | the host reports every position it reaches; `restore(json)` starts the table from a saved position instead of dealing |
+| `MatchSaver` | `net/MatchSaver.kt` | takes the newest position and writes it off the main thread; `flush()` writes synchronously on leaving or on `ON_STOP`; `discard()` forgets the game |
+| `StartMatch` | `ui/PlayScreen.kt` | wires the two together for every game; consumes the resume state once, so a solitaire "new deal" is not put back |
+| `LocalEndGameHandle` | `ui/EndGameHandle.kt` | how each *End game* dialog tells the table to forget its save |
+
+What is saved is `rules.encodeState` of the **host's true state** (hidden cards included),
+plus the `TableConfig` (seed, seats, options) and the local seat. Nothing in the store knows
+which game it is holding, so a new game is saved with no work, provided its state encodes.
+
+A save this build cannot decode (one written by an older version whose state has since
+changed shape) is thrown away and a fresh game is dealt.
+
+## Tests
+
+- `SavedGameStoreTest` — the files: round trip, one slot, ordering, corruption, a cut-off write.
+- `MatchSaverTest` — saving as a table is played, resuming from a save, finished games, flush, discard.
+- `SaveRoundTripAllGamesTest` — **every game in the catalogue**: the whole state is encoded and
+  decoded at every move of a computer-played game, and play carries on from the decoded copy.
+  A new game should be added to it.