fix(recovery): harden backup walker + master backup (audit follow-up)

Adversarial audit of the Phase 2 recovery subsystem surfaced three genuine
hardening gaps; fixed here.

BackupChainWalker:
- Stable selection on mtime ties — added an ordinal path tiebreaker so the chosen
  (and the prospect "second-newest") backup is deterministic across runs instead of
  relying on LINQ's unspecified ordering for equal timestamps.
- Empty/whitespace-only backups are never treated as a clean restore source (a
  zero-byte sibling could otherwise be considered before the parse check).

RecoveryService.CreateMasterBackup:
- Rejects a master-backup directory that lives inside the profile folder (would zip
  itself) — fails fast with ArgumentException.
- Builds the snapshot with a filtered ZipArchive that excludes IUUT's own .iuut-tmp-*
  and .iuut-recovery-* artifacts (only the save data is captured), and skips a file
  locked mid-recovery rather than aborting the whole snapshot.
- A zip failure now degrades to MasterBackupZipPath=null and recovery still proceeds
  (per-file SafeSaveWriter backups remain the safety net) instead of crashing.

Audit findings deliberately NOT actioned (with reasons): recomputing a prospect blob
SHA-1 over corrupt bytes is not recovery (it would let the game load a logically-broken
world) — refusing → restore-from-backup is correct; the walker is already blob-aware
(the planner passes a prospect predicate that includes the SHA-1 check); the
plan→execute TOCTOU is bounded by SafeSaveWriter's post-write re-parse, which rejects
any backup that changed to invalid content.

Tests (4 new, 173 total, all green): empty backup never chosen; equal-mtime selection
is deterministic; master-backup dir inside the profile folder throws; the snapshot zip
excludes .iuut-tmp-* but contains the corrupt save.

Verified: dotnet build -c Release 0/0, dotnet test 173/173, dotnet format clean,
governance-lint clean.

Agent: claude-code/2.1.149
Consulted: AGENTS.md, .agent/CONSTITUTION.md#III, .agent/CODE_STYLE.md#3, .agent/TESTING_CONTRACT.md#2,#5, docs/IUUT-PROJECT-DOCUMENTATION.md#12.1,#7.6
Co-Authored-By: Claude <noreply@anthropic.com>

Author: 2 people

src/IUUT.Core/Recovery/BackupChainWalker.cs

@@ -31,7 +31,10 @@ public BackupScanResult Scan(string filePath, Func<string, bool> isClean, bool i
             foreach (var path in EnumerateBackups(directory, fileName))
             {
                 var isIuut = Path.GetFileName(path).Contains(BackupManager.BackupInfix, StringComparison.Ordinal);
-                var clean = TryRead(path, out var content) && IsCleanSafe(isClean, content);
+                // An empty or whitespace-only backup is never a valid restore source.
+                var clean = TryRead(path, out var content)
+                    && !string.IsNullOrWhiteSpace(content)
+                    && IsCleanSafe(isClean, content);
                 candidates.Add(new BackupCandidate
                 {
                     Path = path,
@@ -58,6 +61,7 @@ private static (BackupCandidate? Chosen, BackupRestoreKind Kind) Choose(
         var gameClean = all
             .Where(c => !c.IsIuutBackup && c.IsClean)
             .OrderByDescending(c => c.LastModifiedUtc)
+            .ThenBy(c => c.Path, StringComparer.Ordinal) // stable tiebreak when mtimes are equal
             .ToList();
 
         if (gameClean.Count > 0)
@@ -70,6 +74,7 @@ private static (BackupCandidate? Chosen, BackupRestoreKind Kind) Choose(
         var iuutClean = all
             .Where(c => c.IsIuutBackup && c.IsClean)
             .OrderByDescending(c => c.LastModifiedUtc)
+            .ThenBy(c => c.Path, StringComparer.Ordinal) // stable tiebreak when mtimes are equal
             .ToList();
 
         return iuutClean.Count > 0

src/IUUT.Core/Recovery/RecoveryService.cs

@@ -58,22 +58,64 @@ public async Task<RecoveryReport> ExecuteAsync(
         };
     }
 
-    private string CreateMasterBackup(string profileFolder, string destinationDirectory)
+    private string? CreateMasterBackup(string profileFolder, string destinationDirectory)
     {
-        Directory.CreateDirectory(destinationDirectory);
-        var folderName = Path.GetFileName(Path.TrimEndingDirectorySeparator(profileFolder));
-        var stamp = _clock.UtcNow.ToString("yyyyMMdd-HHmmss", CultureInfo.InvariantCulture);
-
-        var zipPath = Path.Combine(destinationDirectory, $"{folderName}.iuut-recovery-{stamp}.zip");
-        var n = 2;
-        while (File.Exists(zipPath))
+        // The zip must live OUTSIDE the folder it snapshots, or it would try to include itself.
+        var folderFull = Path.GetFullPath(profileFolder);
+        var destFull = Path.GetFullPath(destinationDirectory);
+        if (destFull == folderFull ||
+            destFull.StartsWith(folderFull + Path.DirectorySeparatorChar, StringComparison.Ordinal))
         {
-            zipPath = Path.Combine(destinationDirectory, $"{folderName}.iuut-recovery-{stamp}-{n}.zip");
-            n++;
+            throw new ArgumentException(
+                "The master-backup directory must be outside the profile folder.", nameof(destinationDirectory));
         }
 
-        ZipFile.CreateFromDirectory(profileFolder, zipPath, CompressionLevel.Optimal, includeBaseDirectory: false);
-        return zipPath;
+        try
+        {
+            Directory.CreateDirectory(destinationDirectory);
+            var folderName = Path.GetFileName(Path.TrimEndingDirectorySeparator(profileFolder));
+            var stamp = _clock.UtcNow.ToString("yyyyMMdd-HHmmss", CultureInfo.InvariantCulture);
+
+            var zipPath = Path.Combine(destinationDirectory, $"{folderName}.iuut-recovery-{stamp}.zip");
+            var n = 2;
+            while (File.Exists(zipPath))
+            {
+                zipPath = Path.Combine(destinationDirectory, $"{folderName}.iuut-recovery-{stamp}-{n}.zip");
+                n++;
+            }
+
+            using var archive = ZipFile.Open(zipPath, ZipArchiveMode.Create);
+            foreach (var file in Directory.EnumerateFiles(profileFolder, "*", SearchOption.AllDirectories))
+            {
+                var name = Path.GetFileName(file);
+                // Never snapshot IUUT's own transient temp files or recovery zips — only the save data.
+                if (name.Contains(".iuut-tmp-", StringComparison.Ordinal) ||
+                    name.Contains(".iuut-recovery-", StringComparison.Ordinal))
+                {
+                    continue;
+                }
+
+                var entryName = Path.GetRelativePath(profileFolder, file).Replace('\\', '/');
+                try
+                {
+                    archive.CreateEntryFromFile(file, entryName, CompressionLevel.Optimal);
+                }
+                catch (IOException)
+                {
+                    // A file locked mid-recovery is skipped rather than aborting the whole snapshot.
+                }
+            }
+
+            return zipPath;
+        }
+        catch (IOException)
+        {
+            return null; // recovery still proceeds; per-file SafeSaveWriter backups remain the safety net
+        }
+        catch (UnauthorizedAccessException)
+        {
+            return null;
+        }
     }
 
     private async Task<RecoveryFileResult> ApplyAsync(RecoveryFileAction action, CancellationToken cancellationToken)

tests/IUUT.Core.Tests/Integration/BackupChainWalkerTests.cs

@@ -120,5 +120,31 @@ public void Scan_NoCleanCandidate_ReturnsNone()
         result.Candidates.Should().ContainSingle();
     }
 
+    [Fact]
+    public void Scan_EmptyOrWhitespaceBackup_IsNeverChosen()
+    {
+        var file = Write("Profile.json", "{ corrupt", 0);
+        Write("Profile.json.backup", "", 5);                          // empty, newest
+        var valid = Write("Profile.json.backup_1", "{\"a\":1}", 1);   // valid, older
+
+        var result = _walker.Scan(file, ParsesJson);
+
+        result.Chosen!.Path.Should().Be(valid, "a zero-byte backup is not a valid restore source");
+    }
+
+    [Fact]
+    public void Scan_EqualMtimes_PicksDeterministically()
+    {
+        var file = Write("Mounts.json", "{ corrupt", 0);
+        var a = Write("Mounts.json.backup", "{\"x\":1}", 3);
+        Write("Mounts.json.backup_1", "{\"x\":2}", 3);                // identical mtime
+
+        var first = _walker.Scan(file, ParsesJson).Chosen!.Path;
+        var second = _walker.Scan(file, ParsesJson).Chosen!.Path;
+
+        first.Should().Be(second, "selection must be stable across runs");
+        first.Should().Be(a, "ties break by ordinal path; 'Mounts.json.backup' sorts before '.backup_1'");
+    }
+
     public void Dispose() => _temp.Dispose();
 }

tests/IUUT.Core.Tests/Integration/RecoveryServiceTests.cs

@@ -104,5 +104,31 @@ public async Task ExecuteAsync_AllClean_TakesBackup_ButChangesNothing()
         report.PartialRecovery.Should().BeFalse();
     }
 
+    [Fact]
+    public async Task ExecuteAsync_DestinationInsideProfileFolder_Throws()
+    {
+        Write("Profile.json", ProfileSerializer.Serialize(new ProfileModel { UserId = SteamId }));
+        var plan = _planner.Plan(_profileDir);
+
+        var act = async () => await _service.ExecuteAsync(plan, Path.Combine(_profileDir, "backups"));
+
+        await act.Should().ThrowAsync<ArgumentException>("the master backup must not live inside the folder it snapshots");
+    }
+
+    [Fact]
+    public async Task ExecuteAsync_MasterBackup_ExcludesIuutTempArtifacts()
+    {
+        Write("Profile.json", "{ broken");
+        Write("Profile.json.backup", ProfileSerializer.Serialize(new ProfileModel { UserId = SteamId }));
+        Write("Profile.json.iuut-tmp-deadbeef", "leftover temp content");
+
+        var plan = _planner.Plan(_profileDir);
+        var report = await _service.ExecuteAsync(plan, _backupDir);
+
+        using var zip = ZipFile.OpenRead(report.MasterBackupZipPath!);
+        zip.Entries.Should().NotContain(e => e.FullName.Contains(".iuut-tmp-"), "transient temp files are not part of the snapshot");
+        zip.Entries.Should().Contain(e => e.FullName == "Profile.json", "the corrupt save itself is captured");
+    }
+
     public void Dispose() => _temp.Dispose();
 }