fix(ghidra): explain server restart for timeout recovery (#5356)

Explain process-scoped startup settings in shared CLI/MCP timeout guidance and the bundled skill. Preserve Evidence and cleanup before restarting REA, reconnect MCP, and allow enough client request time.

Validated with focused tests, static/docs/package checks, real Ghidra CLI/MCP recovery, and a completed 591-second EXE analysis under CPU and memory limits.

.agents/skills/reverse-engineer-anything/SKILL.md

@@ -2,7 +2,7 @@
 name: reverse-engineer-anything
 description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
 metadata:
-  version: "42"
+  version: "43"
 ---
 
 # REA
@@ -256,6 +256,12 @@ Provider candidate facts describe possible providers, while top-level session
 capabilities describe the current route and `analysis_provider_binding` names the
 selected provider. Do not treat those scopes as interchangeable.
 
+For a Ghidra startup timeout on a large native target, follow
+[deadline recovery](references/native-and-artifacts.md#ghidra-startup-deadline-recovery)
+before abandoning deep analysis or repeating the same cold import. The default
+330 seconds is configurable; changing the server's environment requires a new
+REA process.
+
 ## Work summary-first
 
 Start with the default result and use its inline Evidence and graph context.

.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md

@@ -155,6 +155,36 @@ operation's full ordered list. Candidate capabilities describe possible
 providers. Top-level session capabilities describe the current route, and
 `analysis_provider_binding` identifies the selected provider.
 
+## Ghidra startup deadline recovery
+
+`provider_timeout` during the first Ghidra query can cover import, auto-analysis,
+bridge startup, and readiness. The default 330,000 ms is configurable through
+`REA_GHIDRA_STARTUP_TIMEOUT_MS`; a smaller query still needs the same cold import.
+
+Preserve useful Evidence before closing the session or restarting REA. Check
+`close_binary` and resolve reported cleanup failures. Set a larger startup budget
+in the environment that launches REA, then restart REA and reconnect the MCP
+client before reopening the same target. Closing and reopening a binary in the
+existing server keeps its original configuration and starts import again.
+Environment changes in an agent's shell do not update an already running MCP
+server. If its launch configuration cannot be changed, report that constraint
+and the exact retry setting instead of claiming a fixed technical limit.
+
+The client's tool-call deadline must allow startup plus the requested query;
+server settings and progress notifications cannot override it. CLI analysis
+avoids the MCP client deadline, but retains the provider deadline. For example:
+
+```sh
+REA_GHIDRA_STARTUP_TIMEOUT_MS=1800000 rea analyze /absolute/path/to/app.exe --provider ghidra --json
+```
+
+Thirty minutes is an example budget, not a completion guarantee. Keep host CPU
+and memory controls in place. Disable specific expensive analyzers only when
+their missing coverage is acceptable and retain the resulting limitations.
+Exported C and embedded resources remain useful independent evidence, but a
+timeout does not establish complete analysis or absence of code. See the
+[deadline and client guide](https://github.com/morluto/rea/blob/main/docs/mcp-contracts.md#ghidra-first-query-deadlines-and-recovery).
+
 ## Static memory and original file bytes
 
 For Ghidra, `read_bytes` reads initialized analysis memory, including loader

docs/installation.md

@@ -987,6 +987,24 @@ can time out earlier even when Ghidra would complete within its startup deadline
 See [Ghidra first-query deadlines and recovery](mcp-contracts.md#ghidra-first-query-deadlines-and-recovery)
 for client options and the close/reopen recovery flow.
 
+The 330-second default is configurable. Configuration is read when REA starts:
+changing an environment variable in another shell, or closing and reopening a
+binary in the same MCP server, does not change that server's startup allowance.
+For a CLI retry with an example 30-minute allowance:
+
+```sh
+REA_GHIDRA_STARTUP_TIMEOUT_MS=1800000 rea analyze /absolute/path/to/app.exe --provider ghidra --json
+```
+
+For MCP, export useful Evidence before restarting, close the binary and resolve
+any cleanup failure, update the environment in the client's REA server launch
+configuration, then restart REA and reconnect before reopening the target. Allow
+startup plus the query in the client's own tool-call deadline. Every retry 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
+guarantee completion. Keep [heap and host CPU controls](#ghidra-heap-and-cpu-controls)
+appropriate for the machine.
+
 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

docs/mcp-contracts.md

@@ -783,6 +783,13 @@ the current client, so it is not a fresh-start recovery. On the same connection:
    `provider_id: "ghidra"`, then retry the first query with an appropriate client
    deadline. The connection and selected provider do not need to change.
 
+If REA's provider startup allowance also needs raising, preserve Evidence and
+close as above, then update `REA_GHIDRA_STARTUP_TIMEOUT_MS` in REA's launch
+environment and restart the server. Reconnect the MCP client before reopening
+the target. Configuration is read at process startup; close/reopen on the same
+connection cannot apply a changed environment. See the
+[CLI retry example](installation.md#ghidra).
+
 This close/reopen flow was exercised on one real Linux stdio connection after a
 controlled startup timeout, followed by a successful overview and function
 analysis. A separate Windows x64 stdio run with Ghidra 12.1.4, JDK 21 and Node

src/generatedPackageMetadata.ts

@@ -5,5 +5,5 @@ export const PACKAGE_METADATA = {
   serverSdkVersion: "2.3.1",
   clientSdkVersion: "2.3.1",
   coreSdkVersion: "2.3.1",
-  skillVersion: "42",
+  skillVersion: "43",
 } as const;

src/ghidra/GhidraProvider.behavior.test.ts

@@ -2931,6 +2931,12 @@ describe("Ghidra deadline guidance", () => {
     expect(projected.remediation.action).toContain(
       "REA_GHIDRA_DISABLED_ANALYZERS",
     );
+    expect(projected.remediation.action).toContain("restart REA");
+    expect(projected.remediation.action).toContain("reconnect the MCP client");
+    expect(projected.remediation.action).toContain("export useful Evidence");
+    expect(projected.remediation.action).toContain(
+      "Reopening alone keeps the current server settings",
+    );
     expect(projected.remediation.action).not.toContain("rea doctor");
   });
 

src/ghidra/GhidraProviderClient.ts

@@ -1096,8 +1096,8 @@ const projectObservedJvmMemoryFailure = (
 
 /** Name the settings that change Ghidra's import-and-analysis startup deadline. */
 const ghidraStartupTimeoutGuidance = (timeoutMs: number) => ({
-  userMessage: `Ghidra did not finish importing and analyzing the target within its ${String(timeoutMs)} ms startup deadline (REA_GHIDRA_STARTUP_TIMEOUT_MS).`,
-  remediationAction: `Large binaries can need longer: set REA_GHIDRA_STARTUP_TIMEOUT_MS above ${String(timeoutMs)} in the environment that starts REA, or skip expensive analyzers with REA_GHIDRA_DISABLED_ANALYZERS, then open the target again. An MCP client's own tool-call timeout is separate and may also need raising.`,
+  userMessage: `Ghidra did not finish importing and analyzing the target within its configured ${String(timeoutMs)} ms startup deadline (REA_GHIDRA_STARTUP_TIMEOUT_MS).`,
+  remediationAction: `Large binaries can need longer: set REA_GHIDRA_STARTUP_TIMEOUT_MS above ${String(timeoutMs)} in REA's launch environment; REA_GHIDRA_DISABLED_ANALYZERS can skip selected expensive analyzers with reduced coverage. Before restarting, export useful Evidence and close the binary; resolve any cleanup failure. Then restart REA, reconnect the MCP client if used, and reopen the target. Reopening alone keeps the current server settings and repeats import from scratch. The MCP client's tool-call deadline must also allow startup and the query.`,
 });
 
 /** A provider already observed as running can be restarted by reopening. */