[PR #429] [MERGED] fix(hopper): add bounded analysis recovery #1978

New issue

Closed

opened 2026-10-16 21:13:02 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:13:02 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/429
Author: @N0zoM1z0
Created: 7/23/2026
Status: ✅ Merged
Merged: 7/23/2026
Merged by: @N0zoM1z0

Base: main ← Head: codex/fix-hopper-p0-analysis

📝 Commits (2)

e9e862f fix(hopper): add bounded analysis recovery
59feb47 test(package): stabilize fake Hopper ownership

📊 Changes

69 files changed (+1770 additions, -372 deletions)

View changed files

📝 AGENTS.md (+1 -1)
📝 README.md (+16 -5)
📝 README_ar.md (+1 -1)
📝 README_ja.md (+1 -1)
📝 README_ko.md (+1 -1)
📝 README_zh.md (+1 -1)
📝 bridge/ghidra/ReaGhidraBridge.java (+48 -1)
📝 bridge/hopper_bridge.py (+117 -20)
📝 docs/adr/0001-provider-selection-and-analysis-profiles.md (+1 -1)
📝 docs/installation.md (+1 -1)
📝 docs/product-catalog.json (+11 -7)
📝 docs/provider-evaluation.md (+7 -6)
📝 docs/roadmap.md (+2 -2)
📝 docs/verification/managed-conformance-manifest.json (+2 -2)
📝 docs/windows-ghidra-p0.md (+2 -2)
➕ scripts/lib/real-hopper-function-basics.mjs (+71 -0)
📝 scripts/verify-package-environment.mjs (+20 -4)
📝 scripts/verify-real-ghidra-function.mjs (+29 -2)
📝 scripts/verify-real-ghidra-windows.mjs (+1 -0)
📝 scripts/verify-real-hopper.mjs (+7 -36)

...and 49 more files

📄 Description

Summary

add read_function_instructions as a provider-neutral MCP operation and rea instructions CLI command for bounded raw instruction windows without decompilation or whole-program inventory scans
serialize Hopper bridge requests through a bounded FIFO, expose detached request activity and elapsed time in binary_session, and forward MCP progress through enhanced workflows
cache Hopper inventories and successful pseudocode safely, reduce binary_overview work, and invalidate derived caches after mutations
make close_binary return typed cleanup_incomplete results when shutdown cannot be proven, report cleanup phases, and prevent opening a replacement provider after unconfirmed cleanup
admit the new operation through Ghidra bridge protocol v5, update real-provider verifiers, contracts, generated metadata, localized documentation, and the bundled skill

Root cause

Hopper executes its public Python API on one dedicated thread. Concurrent callers could overlap the wire, a timed-out caller hid work that still occupied Hopper, and small dossier requests could trigger decompilation plus repeated whole-program inventories. Lifecycle cleanup also discarded whether document shutdown had actually been acknowledged.

Impact

Agents can choose a fast instruction-only path, distinguish queued or detached provider work from a dead bridge, and receive actionable cleanup failures instead of false success. CLI and MCP remain equivalent. The official native-analysis catalog grows to 34 operations; Ghidra now admits 19 operations.

Verification

npm test — 196 files, 1,388 tests passed
npm run check under Node 24.18 — typecheck, lint, format, knip, and metadata passed with zero lint warnings
npm run docs:check
npm run evidence:check
npm run verify:package — isolated package/setup/CLI/MCP verification, 99 tools
npm run verify:hopper — real Hopper across three ELF targets, large pagination, new instruction fast path, target switching, unrelated-Hopper preservation, and clean shutdown
python3 -m py_compile bridge/hopper_bridge.py

Real Ghidra verification was not performed because this host has JDK 21 but no bring-your-own Ghidra installation. Ghidra bridge, protocol, MCP, provider, and source-truthfulness tests pass.

_{🔄 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/429 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 7/23/2026 **Status:** ✅ Merged **Merged:** 7/23/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `codex/fix-hopper-p0-analysis` --- ### 📝 Commits (2) - [`e9e862f`](https://github.com/morluto/rea/commit/e9e862fc6b9890b4bd30b1cb3c9457087c21d04a) fix(hopper): add bounded analysis recovery - [`59feb47`](https://github.com/morluto/rea/commit/59feb471c895d7b1db3a9221dad83733e0951491) test(package): stabilize fake Hopper ownership ### 📊 Changes **69 files changed** (+1770 additions, -372 deletions) <details> <summary>View changed files</summary> 📝 `AGENTS.md` (+1 -1) 📝 `README.md` (+16 -5) 📝 `README_ar.md` (+1 -1) 📝 `README_ja.md` (+1 -1) 📝 `README_ko.md` (+1 -1) 📝 `README_zh.md` (+1 -1) 📝 `bridge/ghidra/ReaGhidraBridge.java` (+48 -1) 📝 `bridge/hopper_bridge.py` (+117 -20) 📝 `docs/adr/0001-provider-selection-and-analysis-profiles.md` (+1 -1) 📝 `docs/installation.md` (+1 -1) 📝 `docs/product-catalog.json` (+11 -7) 📝 `docs/provider-evaluation.md` (+7 -6) 📝 `docs/roadmap.md` (+2 -2) 📝 `docs/verification/managed-conformance-manifest.json` (+2 -2) 📝 `docs/windows-ghidra-p0.md` (+2 -2) ➕ `scripts/lib/real-hopper-function-basics.mjs` (+71 -0) 📝 `scripts/verify-package-environment.mjs` (+20 -4) 📝 `scripts/verify-real-ghidra-function.mjs` (+29 -2) 📝 `scripts/verify-real-ghidra-windows.mjs` (+1 -0) 📝 `scripts/verify-real-hopper.mjs` (+7 -36) _...and 49 more files_ </details> ### 📄 Description ## Summary - add `read_function_instructions` as a provider-neutral MCP operation and `rea instructions` CLI command for bounded raw instruction windows without decompilation or whole-program inventory scans - serialize Hopper bridge requests through a bounded FIFO, expose detached request activity and elapsed time in `binary_session`, and forward MCP progress through enhanced workflows - cache Hopper inventories and successful pseudocode safely, reduce `binary_overview` work, and invalidate derived caches after mutations - make `close_binary` return typed `cleanup_incomplete` results when shutdown cannot be proven, report cleanup phases, and prevent opening a replacement provider after unconfirmed cleanup - admit the new operation through Ghidra bridge protocol v5, update real-provider verifiers, contracts, generated metadata, localized documentation, and the bundled skill ## Root cause Hopper executes its public Python API on one dedicated thread. Concurrent callers could overlap the wire, a timed-out caller hid work that still occupied Hopper, and small dossier requests could trigger decompilation plus repeated whole-program inventories. Lifecycle cleanup also discarded whether document shutdown had actually been acknowledged. ## Impact Agents can choose a fast instruction-only path, distinguish queued or detached provider work from a dead bridge, and receive actionable cleanup failures instead of false success. CLI and MCP remain equivalent. The official native-analysis catalog grows to 34 operations; Ghidra now admits 19 operations. ## Verification - `npm test` — 196 files, 1,388 tests passed - `npm run check` under Node 24.18 — typecheck, lint, format, knip, and metadata passed with zero lint warnings - `npm run docs:check` - `npm run evidence:check` - `npm run verify:package` — isolated package/setup/CLI/MCP verification, 99 tools - `npm run verify:hopper` — real Hopper across three ELF targets, large pagination, new instruction fast path, target switching, unrelated-Hopper preservation, and clean shutdown - `python3 -m py_compile bridge/hopper_bridge.py` Real Ghidra verification was not performed because this host has JDK 21 but no bring-your-own Ghidra installation. Ghidra bridge, protocol, MCP, provider, and source-truthfulness tests pass. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:13:02 +00:00