[PR #736] [MERGED] docs(ghidra): explain first-query deadlines and recovery #2202

New issue

Closed

opened 2026-10-16 21:15:37 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:15:37 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/736
Author: @N0zoM1z0
Created: 10/6/2026
Status: ✅ Merged
Merged: 10/6/2026
Merged by: @N0zoM1z0

Base: main ← Head: docs/727-ghidra-query-deadlines

📝 Commits (1)

0b315f2 docs(ghidra): explain first-query deadlines and recovery

📊 Changes

3 files changed (+82 additions, -3 deletions)

View changed files

📝 README.md (+2 -0)
📝 docs/installation.md (+12 -3)
📝 docs/mcp-contracts.md (+68 -0)

📄 Description

Summary

Fixes #727. Explain why a Ghidra target can open quickly while its first analysis query exceeds an MCP client's default deadline, and document a verified same-connection cancellation recovery.

Problem and expected behavior

The installation guide said the provider startup deadline fails the open. Public target selection is lazy: the first Ghidra-backed query starts import/auto-analysis. Clients must distinguish transport initialize, REA's 330-second engine startup allowance, and their individual tool-call deadline.

Change and scope

Correct the installation guide, link the recovery guide from README, and document the pinned SDK's second-argument request options, progress-token handling, and close/reopen behavior. The 240-second example is explicitly environment-qualified and does not silently change client/server defaults.

Contract and boundary impact

Semantic owner and earliest changed stage: documentation of the existing target-selection/startup/client boundary.
CLI and MCP/tool-catalog contract: no schema, inventory, or runtime changes; CLI has no MCP client deadline and retains provider startup/SIGINT behavior.
Provider, bridge, target-format, or platform compatibility: no expanded support; local verification is Linux x64/WSL2 with existing Ghidra 12.1.4 and JDK 21.
Evidence, artifact, provenance, or reconstruction contract: unchanged; recovery warns that close clears retained records and explains preserving inline Evidence/exporting first.
Process execution, authorization, cleanup, or containment impact: documents existing owned-work drain/cleanup and requires reading actual cleanup outcomes; no new permission flags or fallback.
Generated metadata (docs/product-catalog.json), package, or installation impact: none.

Evidence and regression coverage

Tests added or updated: no new deterministic tests for a documentation-only change; verified the concrete public workflow with real Ghidra.
Base reproduction or other evidence: #727 measured a first overview exceeding the 60-second client default, while a correctly configured longer request succeeded. The inaccurate installation statement is replaced.
User-visible example: client.callTool({name: "binary_overview", arguments: {}}, {timeout: 240000, onprogress: handler}); options are the second argument, not tool input or a third argument.
Remaining proof gaps: this targeted real workflow covers startup cancellation, overview, procedure inventory, function analysis, progress and cleanup. It does not rerun the entire Ghidra operation-conformance lane or establish Windows/macOS recovery coverage.

Validation performed

npm run build:cached — passed.
npm run docs:check — passed.
npm run check:fast — passed.
Real pinned-SDK 2.3.1 stdio/Ghidra workflow — a controlled 5-second cold-start request timed out; close/reopen on the same connection succeeded, followed by overview in 64.201 seconds, procedure inventory in 12 ms and function analysis in 148 ms. Two progress updates were received. The successful request used the documented second-argument options.
Resource/cleanup observation — two-CPU affinity and observed 512 MiB Java heap; sampled Java RSS peak 487.3 MiB; both observed owned Java PIDs exited and no newly created Ghidra temporary roots remained.
Local SDK default export — confirmed DEFAULT_REQUEST_TIMEOUT_MSEC === 60000.
git diff --check — passed.

Additional local composition review: all four issue branches were merged on a
private temporary branch. The expected #720/#722 overlaps in error remediation
were combined, and shared product/skill/conformance metadata was regenerated
from the combined source contracts. Eight focused test files (54 tests),
npm run check:fast, npm run docs:check, and the real stdio regression
workflows for #719/#720/#722 passed. Public PRs remain independently based on
main; when merging them together, regenerate metadata instead of choosing one
branch's generated digests.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: real Ghidra/Linux recovery verified; no Hopper/browser, local Windows-native, or macOS claim.
Package or release metadata impact: documentation only, no installations or dependencies.
Security, privacy, process, or containment review: reused existing toolchains; no distribution copy or host configuration writes. Public examples contain no private paths or credentials. Owned runtime processes and temporary roots were cleaned.

Review checklist

The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/736 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/6/2026 **Status:** ✅ Merged **Merged:** 10/6/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `docs/727-ghidra-query-deadlines` --- ### 📝 Commits (1) - [`0b315f2`](https://github.com/morluto/rea/commit/0b315f229ff2a60e01946084489e357b20700899) docs(ghidra): explain first-query deadlines and recovery ### 📊 Changes **3 files changed** (+82 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+2 -0) 📝 `docs/installation.md` (+12 -3) 📝 `docs/mcp-contracts.md` (+68 -0) </details> ### 📄 Description ## Summary Fixes #727. Explain why a Ghidra target can open quickly while its first analysis query exceeds an MCP client's default deadline, and document a verified same-connection cancellation recovery. ## Problem and expected behavior The installation guide said the provider startup deadline fails the open. Public target selection is lazy: the first Ghidra-backed query starts import/auto-analysis. Clients must distinguish transport initialize, REA's 330-second engine startup allowance, and their individual tool-call deadline. ## Change and scope Correct the installation guide, link the recovery guide from README, and document the pinned SDK's second-argument request options, progress-token handling, and close/reopen behavior. The 240-second example is explicitly environment-qualified and does not silently change client/server defaults. ## Contract and boundary impact - Semantic owner and earliest changed stage: documentation of the existing target-selection/startup/client boundary. - CLI and MCP/tool-catalog contract: no schema, inventory, or runtime changes; CLI has no MCP client deadline and retains provider startup/SIGINT behavior. - Provider, bridge, target-format, or platform compatibility: no expanded support; local verification is Linux x64/WSL2 with existing Ghidra 12.1.4 and JDK 21. - Evidence, artifact, provenance, or reconstruction contract: unchanged; recovery warns that close clears retained records and explains preserving inline Evidence/exporting first. - Process execution, authorization, cleanup, or containment impact: documents existing owned-work drain/cleanup and requires reading actual cleanup outcomes; no new permission flags or fallback. - Generated metadata (`docs/product-catalog.json`), package, or installation impact: none. ## Evidence and regression coverage - Tests added or updated: no new deterministic tests for a documentation-only change; verified the concrete public workflow with real Ghidra. - Base reproduction or other evidence: #727 measured a first overview exceeding the 60-second client default, while a correctly configured longer request succeeded. The inaccurate installation statement is replaced. - User-visible example: `client.callTool({name: "binary_overview", arguments: {}}, {timeout: 240000, onprogress: handler})`; options are the second argument, not tool input or a third argument. - Remaining proof gaps: this targeted real workflow covers startup cancellation, overview, procedure inventory, function analysis, progress and cleanup. It does not rerun the entire Ghidra operation-conformance lane or establish Windows/macOS recovery coverage. ## Validation performed - `npm run build:cached` — passed. - `npm run docs:check` — passed. - `npm run check:fast` — passed. - Real pinned-SDK 2.3.1 stdio/Ghidra workflow — a controlled 5-second cold-start request timed out; close/reopen on the same connection succeeded, followed by overview in 64.201 seconds, procedure inventory in 12 ms and function analysis in 148 ms. Two progress updates were received. The successful request used the documented second-argument options. - Resource/cleanup observation — two-CPU affinity and observed 512 MiB Java heap; sampled Java RSS peak 487.3 MiB; both observed owned Java PIDs exited and no newly created Ghidra temporary roots remained. - Local SDK default export — confirmed `DEFAULT_REQUEST_TIMEOUT_MSEC === 60000`. - `git diff --check` — passed. Additional local composition review: all four issue branches were merged on a private temporary branch. The expected #720/#722 overlaps in error remediation were combined, and shared product/skill/conformance metadata was regenerated from the combined source contracts. Eight focused test files (54 tests), `npm run check:fast`, `npm run docs:check`, and the real stdio regression workflows for #719/#720/#722 passed. Public PRs remain independently based on main; when merging them together, regenerate metadata instead of choosing one branch's generated digests. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: real Ghidra/Linux recovery verified; no Hopper/browser, local Windows-native, or macOS claim. - Package or release metadata impact: documentation only, no installations or dependencies. - Security, privacy, process, or containment review: reused existing toolchains; no distribution copy or host configuration writes. Public examples contain no private paths or credentials. Owned runtime processes and temporary roots were cleaned. ## Review checklist - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:15:37 +00:00