fix(ghidra): explain Program reuse after startup timeouts

Explain Program reuse in cold-start timeout recovery and distinguish query
snapshots from saved Ghidra analysis. Preserve explicit startup-mode selection,
first-analysis requirements, and custom-analyzer choices.

Refs #10365

Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>

docs/getting-started/installation.md

@@ -1434,8 +1434,8 @@ empty, invalid or out-of-range supplied values fail configuration validation.
 When the deadline elapses, the `provider_timeout` error names
 `REA_GHIDRA_STARTUP_TIMEOUT_MS` with the deadline that was applied. In
 fresh-import mode it also suggests `REA_GHIDRA_DISABLED_ANALYZERS` for analyzers
-that dominate the time and `REA_GHIDRA_PROJECT_PATH` for reusing a completed
-analysis; in existing-project mode it omits that import and analyzer advice.
+that dominate the time and the Program reuse choices below; in existing-project
+mode it omits that import and analyzer advice.
 REA parses the supplied configuration environment and
 passes the deadline to each provider client; a startup failure is returned by the query that triggered it,
 without exposing partial analysis. This deadline is separate from MCP transport
@@ -1462,12 +1462,34 @@ the settings update does not clear cleanup blockers. To change the launch
 environment instead, export useful Evidence, close the binary and resolve any
 cleanup failure, update the client's REA server launch configuration, then
 restart REA and reconnect. Allow startup plus the query in the client's own
-tool-call deadline; runtime updates do not change that deadline. Each new startup attempt uses
-a fresh ephemeral import; smaller result requests do not reduce the prerequisite
-auto-analysis. A larger time allowance does not raise the JVM heap limit or
+tool-call deadline; runtime updates do not change that deadline. In the default
+fresh-import mode, each new startup attempt repeats import and analysis; smaller
+result requests do not reduce that prerequisite. A larger time allowance does not raise the JVM heap limit or
 guarantee completion. Keep [heap and host CPU controls](#ghidra-heap-and-cpu-controls)
 appropriate for the machine.
 
+For repeated CLI commands on a large binary, explicitly choose where the analyzed
+Program is retained:
+
+- [Owned Program checkpoints](#automatically-checkpoint-an-owned-ghidra-program)
+  (`REA_GHIDRA_CHECKPOINT_DIR`) save completed analysis automatically for supported
+  stock native ELF, PE and Mach-O imports on Linux/macOS. Initial analysis must
+  finish once; later invocations restore the saved Program without auto-analysis.
+  This mode excludes analysis overrides. For customized analysis, reuse a project
+  already analyzed with the desired settings rather than discarding those choices
+  to enable checkpoints.
+- [An existing Ghidra project](#reuse-an-existing-ghidra-project)
+  (`REA_GHIDRA_PROJECT_PATH`, with `REA_GHIDRA_PROGRAM_NAME` when needed) reuses a
+  Program already analyzed and saved in Ghidra. REA opens a private copy without
+  auto-analysis and leaves the caller's project unchanged.
+
+Configure the selection in each CLI invocation's environment or in the MCP server
+registration, then restart that server. A running MCP session already reuses its
+Program across queries. `--snapshot` caches REA query results, not the analyzed
+Ghidra Program: a query absent from that snapshot still needs provider startup.
+Neither reuse mode resumes unfinished initial auto-analysis or removes its
+first-run time and memory requirements.
+
 One session contains exactly one imported Program; use `provider_id: "ghidra"`, `--provider ghidra`, or
 `REA_ANALYSIS_PROVIDER=ghidra` when both Hopper and Ghidra support the target.
 One persistent decompiler is owned by the Program, and a serial queue keeps

src/ghidra/GhidraProvider.behavior.test.ts

@@ -4795,6 +4795,22 @@ describe("Ghidra startup deadline for a finished invocation", () => {
       expect(
         invocation.remediation.action.includes("REA_GHIDRA_DISABLED_ANALYZERS"),
       ).toBe(!existingProject);
+      for (const { remediation } of [invocation, continuing]) {
+        if (existingProject) {
+          expect(remediation.action).not.toContain("REA_GHIDRA_CHECKPOINT_DIR");
+        } else {
+          expect(remediation.action).toContain("REA_GHIDRA_CHECKPOINT_DIR");
+          expect(remediation.action).toContain(
+            "--snapshot reuses cached query results, not the analyzed Ghidra Program",
+          );
+          expect(remediation.action).toContain(
+            "Initial analysis must still complete once",
+          );
+          expect(remediation.action).toContain(
+            "Changing startup mode requires a new REA invocation or an MCP server restart",
+          );
+        }
+      }
     },
   );
 

src/ghidra/GhidraProviderClient.ts

@@ -2043,7 +2043,7 @@ export const ghidraStartupTimeoutGuidance = (
       ? `Large projects can need longer: ${raise}. Existing-project mode does not run auto-analysis, so analyzer settings do not shorten this startup. ${retry}${client}`
       : source === "owned-checkpoint"
         ? `Checkpoint startup can need longer: ${raise}. Restoring a saved Program skips auto-analysis; initial analysis and its first checkpoint must complete once. ${retry} Keep REA_GHIDRA_CHECKPOINT_DIR to recover the last successful save. Analyzer overrides require explicitly disabling checkpoint mode.${client}`
-        : `Large binaries can need longer: ${raise}; REA_GHIDRA_DISABLED_ANALYZERS can skip selected expensive analyzers with reduced coverage. ${retry} ${reopen} repeats import from scratch; for repeated work on the same native ELF, PE or Mach-O binary on a POSIX host, analyze it once into a Ghidra project and set REA_GHIDRA_PROJECT_PATH to reuse that analysis.${client}`;
+        : `Large binaries can need longer: ${raise}; REA_GHIDRA_DISABLED_ANALYZERS can skip selected expensive analyzers with reduced coverage. ${retry} ${reopen} repeats import from scratch; --snapshot reuses cached query results, not the analyzed Ghidra Program. For repeated work on supported native ELF, PE or Mach-O binaries on Linux/macOS, opt into REA_GHIDRA_CHECKPOINT_DIR to save completed analysis automatically, or select an analyzed project with REA_GHIDRA_PROJECT_PATH. Checkpoint mode excludes analysis overrides; use a project already analyzed with the desired settings for customized analysis. Changing startup mode requires a new REA invocation or an MCP server restart. Initial analysis must still complete once.${client}`;
   };
   return {
     limit: analysisSettingLimit(