Add the Bloom Freeze Doctor (BL-16719)

Bloom.sln

@@ -1,3 +1,4 @@
+
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 17
 VisualStudioVersion = 17.7.34003.232
@@ -29,6 +30,16 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "WebView2PdfMaker", "src\WebView2PdfMaker\WebView2PdfMaker.csproj", "{F697DD7A-2D74-4850-8381-7E4ADB1E4431}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{827E0CD3-B72D-47B6-A68D-7590B98EB39B}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BloomFreezeDoctor.Protocol", "src\BloomFreezeDoctor.Protocol\BloomFreezeDoctor.Protocol.csproj", "{BC16B558-A063-411A-8BF0-C259CBD62E48}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BloomFreezeDoctor.Core", "src\BloomFreezeDoctor.Core\BloomFreezeDoctor.Core.csproj", "{DFDB8F7F-62BA-4019-891F-378897E56A6E}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BloomFreezeDoctor", "src\BloomFreezeDoctor\BloomFreezeDoctor.csproj", "{DB569C6F-CD1A-4F6C-AD1D-5768749F2B68}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BloomFreezeDoctor.Tests", "src\BloomFreezeDoctor.Tests\BloomFreezeDoctor.Tests.csproj", "{993C2D6D-07BC-4929-90F9-67F64753AC71}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|x64 = Debug|x64
@@ -61,12 +72,48 @@ Global
 		{F697DD7A-2D74-4850-8381-7E4ADB1E4431}.Release|x64.Build.0 = Release|x64
 		{F697DD7A-2D74-4850-8381-7E4ADB1E4431}.Release|ARM64.ActiveCfg = Release|ARM64
 		{F697DD7A-2D74-4850-8381-7E4ADB1E4431}.Release|ARM64.Build.0 = Release|ARM64
+		{BC16B558-A063-411A-8BF0-C259CBD62E48}.Debug|x64.ActiveCfg = Debug|x64
+		{BC16B558-A063-411A-8BF0-C259CBD62E48}.Debug|x64.Build.0 = Debug|x64
+		{BC16B558-A063-411A-8BF0-C259CBD62E48}.Debug|ARM64.ActiveCfg = Debug|ARM64
+		{BC16B558-A063-411A-8BF0-C259CBD62E48}.Debug|ARM64.Build.0 = Debug|ARM64
+		{BC16B558-A063-411A-8BF0-C259CBD62E48}.Release|x64.ActiveCfg = Release|x64
+		{BC16B558-A063-411A-8BF0-C259CBD62E48}.Release|x64.Build.0 = Release|x64
+		{BC16B558-A063-411A-8BF0-C259CBD62E48}.Release|ARM64.ActiveCfg = Release|ARM64
+		{BC16B558-A063-411A-8BF0-C259CBD62E48}.Release|ARM64.Build.0 = Release|ARM64
+		{DFDB8F7F-62BA-4019-891F-378897E56A6E}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{DFDB8F7F-62BA-4019-891F-378897E56A6E}.Debug|x64.Build.0 = Debug|Any CPU
+		{DFDB8F7F-62BA-4019-891F-378897E56A6E}.Debug|ARM64.ActiveCfg = Debug|Any CPU
+		{DFDB8F7F-62BA-4019-891F-378897E56A6E}.Debug|ARM64.Build.0 = Debug|Any CPU
+		{DFDB8F7F-62BA-4019-891F-378897E56A6E}.Release|x64.ActiveCfg = Release|Any CPU
+		{DFDB8F7F-62BA-4019-891F-378897E56A6E}.Release|x64.Build.0 = Release|Any CPU
+		{DFDB8F7F-62BA-4019-891F-378897E56A6E}.Release|ARM64.ActiveCfg = Release|Any CPU
+		{DFDB8F7F-62BA-4019-891F-378897E56A6E}.Release|ARM64.Build.0 = Release|Any CPU
+		{DB569C6F-CD1A-4F6C-AD1D-5768749F2B68}.Debug|x64.ActiveCfg = Debug|x64
+		{DB569C6F-CD1A-4F6C-AD1D-5768749F2B68}.Debug|x64.Build.0 = Debug|x64
+		{DB569C6F-CD1A-4F6C-AD1D-5768749F2B68}.Debug|ARM64.ActiveCfg = Debug|ARM64
+		{DB569C6F-CD1A-4F6C-AD1D-5768749F2B68}.Debug|ARM64.Build.0 = Debug|ARM64
+		{DB569C6F-CD1A-4F6C-AD1D-5768749F2B68}.Release|x64.ActiveCfg = Release|x64
+		{DB569C6F-CD1A-4F6C-AD1D-5768749F2B68}.Release|x64.Build.0 = Release|x64
+		{DB569C6F-CD1A-4F6C-AD1D-5768749F2B68}.Release|ARM64.ActiveCfg = Release|ARM64
+		{DB569C6F-CD1A-4F6C-AD1D-5768749F2B68}.Release|ARM64.Build.0 = Release|ARM64
+		{993C2D6D-07BC-4929-90F9-67F64753AC71}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{993C2D6D-07BC-4929-90F9-67F64753AC71}.Debug|x64.Build.0 = Debug|Any CPU
+		{993C2D6D-07BC-4929-90F9-67F64753AC71}.Debug|ARM64.ActiveCfg = Debug|Any CPU
+		{993C2D6D-07BC-4929-90F9-67F64753AC71}.Debug|ARM64.Build.0 = Debug|Any CPU
+		{993C2D6D-07BC-4929-90F9-67F64753AC71}.Release|x64.ActiveCfg = Release|Any CPU
+		{993C2D6D-07BC-4929-90F9-67F64753AC71}.Release|x64.Build.0 = Release|Any CPU
+		{993C2D6D-07BC-4929-90F9-67F64753AC71}.Release|ARM64.ActiveCfg = Release|Any CPU
+		{993C2D6D-07BC-4929-90F9-67F64753AC71}.Release|ARM64.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{D38FC737-8C27-46CB-B490-3CB2E7AB3C99} = {04AF3A87-C943-4731-BE3D-659EA705171D}
+		{BC16B558-A063-411A-8BF0-C259CBD62E48} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{DFDB8F7F-62BA-4019-891F-378897E56A6E} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{DB569C6F-CD1A-4F6C-AD1D-5768749F2B68} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{993C2D6D-07BC-4929-90F9-67F64753AC71} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {AFDCD471-511E-432D-B6B3-2F9D5AD1ACED}

Directory.Build.props

@@ -53,7 +53,13 @@
             This lives here rather than as a -p: on the wrapper's command line because a
             global property cannot be varied per project.
         -->
-        <UseAppHost Condition="'$(MSBuildProjectName)' != 'WebView2PdfMaker'">false</UseAppHost>
+        <!--
+            BloomFreezeDoctor joins WebView2PdfMaker for the same reason: Bloom launches it by FILE NAME
+            (BloomFreezeDoctor.exe, see FreezeDoctor/DoctorLauncher.cs), so without its apphost the
+            "Run Freeze Doctor" menu item silently does nothing in an agent-built tree - which is an
+            expensive thing to debug, because nothing reports an error.
+        -->
+        <UseAppHost Condition="'$(MSBuildProjectName)' != 'WebView2PdfMaker' AND '$(MSBuildProjectName)' != 'BloomFreezeDoctor'">false</UseAppHost>
         <!--
             Once obj moves out of the project directory, the SDK no longer treats the
             conventional in-tree obj\ and bin\ as intermediate output, so their stale

PAPERCUTS.md

@@ -19,6 +19,22 @@ House rules:
 
 ---
 
+## 2026-08-26 — A Bloom launched by ./go.sh cannot be watched by the Freeze Doctor
+
+- **Cut:** `go.sh` runs Bloom with `--automation`, and the Doctor deliberately refuses to watch any
+  run whose command line carries that flag (such runs legitimately have no window, so watching them
+  would manufacture zombie reports). So the repo’s sanctioned dev launcher produces the one kind of
+  Bloom the Doctor ignores, and an agent following AGENTS.md cannot test the Doctor at all. Launching
+  the built exe directly instead dies at Velopack init when given no arguments ("Bloom Problem"
+  immediately), though the same binary starts fine with go.sh’s own arguments. F5 works, which is why
+  every successful manual test of this feature so far has been F5.
+- **Idea:** either have go.sh omit `--automation` (or offer a flag to), or say in AGENTS.md that testing
+  the Freeze Doctor needs F5 rather than go.sh, and why. Also worth noting that go.sh builds to
+  `output/Debug/AnyCPU` while launch.json runs `output/Debug/x64`.
+- **Context:** BL-16719, trying to run a crash test unattended. A related false start: 
+  `build/agent-dotnet.sh` builds into `output/agent/<key>/`, so `output/Debug/x64` was eleven commits
+  stale and the first attempt silently exercised old code.
+
 ## 2026-07-30 — Visual regression suite reports only the first stale image per case
 - **Cut:** Each case in `src/BloomVisualRegressionTests/index.spec.ts` compares the book preview
   and then every bloom-player page in sequence, and every comparison throws on failure — so the

build/Bloom.proj

@@ -170,6 +170,12 @@
     build here does NOT go to the same directory as the VS build. -->
     <Exec Command='dotnet build "$(RootDir)\src\BloomExe\BloomExe.csproj" --configuration $(Configuration) --runtime win-x64 --output "$(RootDir)\output\$(Configuration)\x64" "/p:OutDir=$(RootDir)\output\$(Configuration)\x64\\" "/p:SolutionDir=$(RootDir)\"' />
     <Exec Command='dotnet build "$(RootDir)\src\WebView2PdfMaker\WebView2PdfMaker.csproj" --configuration $(Configuration) --runtime win-x64 --output "$(RootDir)\output\$(Configuration)\x64" "/p:OutDir=$(RootDir)\output\$(Configuration)\x64\\" "/p:SolutionDir=$(RootDir)\"' />
+    <!-- The Freeze Doctor, which ships inside Bloom's installer rather than having one of its own. It
+    has to be named here, exactly like WebView2PdfMaker above, BECAUSE this target builds project by
+    project rather than building the solution: being in Bloom.sln is not enough. Leaving it out would
+    have failed silently and expensively - the signing step below has ContinueOnError, so an unbuilt
+    Doctor would simply have been missing from the installer with nothing going red anywhere. -->
+    <Exec Command='dotnet build "$(RootDir)\src\BloomFreezeDoctor\BloomFreezeDoctor.csproj" --configuration $(Configuration) --runtime win-x64 --output "$(RootDir)\output\$(Configuration)\x64" "/p:OutDir=$(RootDir)\output\$(Configuration)\x64\\" "/p:SolutionDir=$(RootDir)\"' />
   <!--If the number of directories between output and OutDir changes, we need a corresponding
     change in BloomFileLocatorTests.kRelativePathToBrowserFolder and XMatterHelperTests.OneTimeSetup-->
     <Exec Command='dotnet build "$(RootDir)\src\BloomTests\BloomTests.csproj" --configuration $(Configuration) --runtime win-x64 --output "$(RootDir)\output\Tests\$(Configuration)\x64" "/p:OutDir=$(RootDir)\output\Tests\$(Configuration)\x64\\" "/p:SolutionDir=$(RootDir)\"' />
@@ -507,6 +513,11 @@
     <!-- Sign x64 executables -->
     <Exec Command='sign "$(RootDir)\output\$(Configuration)\x64\Bloom.exe"' ContinueOnError="$(ContinueOnExeSignError)"></Exec>
     <Exec Command='sign "$(RootDir)\output\$(Configuration)\x64\BloomPdfMaker.exe"' ContinueOnError="$(ContinueOnExeSignError)"></Exec>
+    <!-- The Freeze Doctor. Signed here rather than by an installer of its own, because it no longer has
+         one: it ships inside Bloom's installer and is switched on from the debug menu. An unsigned exe
+         inside a signed installer is what behavioural antivirus objects to, and it matters more than
+         usual for this one, which opens handles to other processes and writes memory dumps. -->
+    <Exec Command='sign "$(RootDir)\output\$(Configuration)\x64\BloomFreezeDoctor.exe"' ContinueOnError="$(ContinueOnExeSignError)"></Exec>
     <!-- restore to Sign ARM64 executables
     <Exec Command='sign "$(RootDir)\output\$(Configuration)\arm64\Bloom.exe"' ContinueOnError="$(ContinueOnExeSignError)"></Exec>
     <Exec Command='sign "$(RootDir)\output\$(Configuration)\arm64\BloomPdfMaker.exe"' ContinueOnError="$(ContinueOnExeSignError)"></Exec>

build/check-csharp-ApplicationExit.sh

@@ -22,6 +22,14 @@ if [ -s $filesToCheck ]; then
       # exemption the check fires on any commit that merely stages the file -- a merge
       # of master, say -- for code the committer never touched.
       src/WebView2PdfMaker/*) continue;;
+      # BloomFreezeDoctor is the same case as WebView2PdfMaker above, for the same reason: a separate
+      # executable, its own static Program, no Program.Exit to call instead. Application.Exit is simply
+      # how its WinForms message loop ends.
+      #
+      # Worth noting that this rule, and the RobustFile one next door, both assume every .cs file in the
+      # repo is Bloom. A second application needs them to know WHICH application a file belongs to, and
+      # the WebView2PdfMaker line above shows that was already true before the Doctor arrived.
+      src/BloomFreezeDoctor/*|src/BloomFreezeDoctor.Core/*|src/BloomFreezeDoctor.Tests/*) continue;;
     esac
     # Strip // line comments and /* ... */ single-line block comments before
     # searching, so a mention of Application.Exit in a comment doesn't trip this check.

build/check-csharp-robustfile.sh

@@ -35,6 +35,12 @@ if [ -s $filesToCheck ]; then
     case "$file" in
       src/BloomExe/RobustFileIO.cs) continue;;
       src/BloomTests/*) continue;;
+      # The Freeze Doctor's TEST project only, matching the src/BloomTests carve-out above for the same
+      # reason. Its production code is NOT exempt: it was converted to RobustFile/RobustIO rather than
+      # excused, because a diagnostic tool writing to a user's disk has no more business losing a file to
+      # a passing virus scanner than Bloom does - and the first thing the conversion found was a real
+      # one, an outbox rename that failed about one run in three and threw away a gathered report.
+      src/BloomFreezeDoctor.Tests/*) continue;;
     esac
     if awk '
       # Flag ordinary banned file APIs directly.

scripts/watchBloomExe.mjs

@@ -30,11 +30,18 @@ const parseArgs = () => {
             "..",
         ),
         vitePort: undefined,
+        // Build and run once instead of running under "dotnet watch". See go.mjs --nowatch.
+        noWatch: false,
     };
 
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
 
+        if (arg === "--nowatch" || arg === "--no-watch") {
+            options.noWatch = true;
+            continue;
+        }
+
         if (arg === "--repo-root") {
             options.repoRoot = requireOptionValue(args, i, "--repo-root");
             i++;
@@ -131,14 +138,20 @@ const tryInferVitePortFromRunningBloom = async () => {
 const effectiveVitePort =
     options.vitePort ?? (await tryInferVitePortFromRunningBloom());
 
-const dotnetArgs = [
-    "watch",
-    "run",
-    "--project",
-    projectPath,
-    "--",
-    "--automation",
-];
+// With --nowatch we run Bloom directly rather than under "dotnet watch". The watcher costs real time
+// before Bloom appears - it builds, then starts its own file watching over the whole project - and buys
+// nothing at all unless you are editing C#. Everything below still works: the file-change handling simply
+// never fires, because nothing reports a change.
+const dotnetArgs = options.noWatch
+    ? ["run", "--project", projectPath, "--", "--automation"]
+    : ["watch", "run", "--project", projectPath, "--", "--automation"];
+
+if (options.noWatch) {
+    console.log(
+        "Running without dotnet watch: C# edits will NOT rebuild by themselves. " +
+            "The front end is unaffected - TypeScript and LESS still update live through Vite.",
+    );
+}
 
 const startupLabel = getHelpfulStartupLabel(options.repoRoot);
 

src/BloomBrowserUI/bookEdit/aiImageEditor/aiImageEditorOverlay.test.ts

@@ -280,7 +280,9 @@ describe("aiImageEditorOverlay: the live page is NOT saved after a commit", () =
         commitAndReplyFromHost(postFromEditor, false);
 
         // The overlay stays up so the user can read the error about the slot that failed.
-        expect(document.getElementById("ai-image-editor-overlay")).not.toBeNull();
+        expect(
+            document.getElementById("ai-image-editor-overlay"),
+        ).not.toBeNull();
         expect(postThatMightNavigate).not.toHaveBeenCalled();
 
         closeButton.click();

src/BloomBrowserUI/react_components/TopBar/TopBarContextMenu.tsx

@@ -30,6 +30,7 @@ export const TopBarContextMenu: React.FunctionComponent<{
         React.useState(false);
     const [isMeddlingWithNewFiles, setIsMeddlingWithNewFiles] =
         React.useState(false);
+    const [runFreezeDoctor, setRunFreezeDoctor] = React.useState(false);
     const [canChooseDevBloomLibrary, setCanChooseDevBloomLibrary] =
         React.useState(false);
     const [useDevBloomLibrary, setUseDevBloomLibrary] = React.useState(false);
@@ -53,6 +54,11 @@ export const TopBarContextMenu: React.FunctionComponent<{
         getBoolean("app/isMeddlingWithNewFiles", (value) => {
             setIsMeddlingWithNewFiles(value);
         });
+        // Persisted across runs, so the check mark has to come from the back end rather than
+        // from local state: it may well have been turned on during a previous session.
+        getBoolean("app/runFreezeDoctor", (value) => {
+            setRunFreezeDoctor(value);
+        });
         // Only some builds offer the choice of web site, and only the back end knows
         // which web site this run of Bloom uses.
         getBoolean("app/canChooseDevBloomLibrary", (value) => {
@@ -163,6 +169,18 @@ export const TopBarContextMenu: React.FunctionComponent<{
                     setIsMeddlingWithNewFiles(newValue);
                 },
             },
+            {
+                // The Freeze Doctor ships inside Bloom but does nothing unless switched on here.
+                // Turning it on starts it immediately, so you can switch it on while chasing a freeze
+                // rather than having to restart Bloom first.
+                label: "Run Freeze Doctor",
+                selected: runFreezeDoctor,
+                onClick: () => {
+                    const newValue = !runFreezeDoctor;
+                    postBoolean("app/runFreezeDoctor", newValue);
+                    setRunFreezeDoctor(newValue);
+                },
+            },
         ];
         if (canChooseDevBloomLibrary) {
             items.push({ label: "-" });
@@ -183,6 +201,7 @@ export const TopBarContextMenu: React.FunctionComponent<{
         alwaysMeasurePerformance,
         currentlyMeasuring,
         isMeddlingWithNewFiles,
+        runFreezeDoctor,
         canChooseDevBloomLibrary,
         useDevBloomLibrary,
     ]);