Skip to content

fix(ghidra): recover stale clients on same-target reopen - #2014

Merged
morluto merged 5 commits into
morluto:mainfrom
lyly-bonbon:fix/ghidra-reopen-health
Oct 12, 2026
Merged

morluto merged 5 commits into
morluto:mainfrom
lyly-bonbon:fix/ghidra-reopen-health

Conversation

@lyly-bonbon

@lyly-bonbon lyly-bonbon commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Recover a retained Ghidra session when its process has exited or its bridge connection has closed. Same-target open_binary now retires the stale client; the next query starts a replacement after cleanup succeeds.

Refs #1719.

Problem and expected behavior

After a successful query, killing the Ghidra child or disconnecting its socket left the successful startup promise cached. Ghidra exposed no operational health snapshot, so the composite provider's health response let same-target reopen reuse that client. The next query still failed against the old bridge.

Reopen should release the stale session and permit a fresh lazy start. If cleanup cannot be confirmed, it must return cleanup_incomplete, retain ownership, and retry cleanup on the next open without starting another child.

Change and scope

  • Report observed process exit, socket disconnection, and resources retained after failed cleanup from GhidraClient.
  • Forward that snapshot through the Ghidra provider's existing optional health hook, using the shared session recovery path.
  • Preserve lazy startup and reuse of a live client. Historical exit diagnostics after successful cleanup do not mark a new session unhealthy.

This addresses stale-client recovery. It does not change startup deadlines, snapshot semantics, or detection of a connected but unresponsive bridge.

Contract and boundary impact

  • Semantic owner and earliest changed stage: Ghidra client lifecycle observation, before retained-client reuse.
  • CLI and MCP/tool-catalog contract: existing shapes and tools; same-target reopen now recovers from observed exit/disconnection.
  • Provider, bridge, target-format, or platform compatibility: no bridge protocol or target-format changes.
  • Evidence, artifact, provenance, or reconstruction contract: unchanged; tests verify the input bytes remain intact.
  • Process execution, authorization, cleanup, or containment impact: existing ownership and cleanup gates remain authoritative; replacement stays blocked while cleanup is incomplete.
  • Generated metadata, package, or installation impact: none.

Evidence and regression coverage

  • Added three public MCP scenarios covering lazy start/live reuse, signal exit, socket loss with a live child, and two failed cleanup attempts followed by recovery. They use the production client/provider/session, real Node children and Unix sockets, with installation discovery and the Java bridge simulated.
  • All three fail on base b8fab742 and pass with this change: old resources survive reopen, a disconnected child remains alive, and unconfirmed cleanup is incorrectly bypassed on the base.
  • Extended client boundary tests for retained file descriptors and runtime directories after cleanup failure, successful retries, and historical exit diagnostics.
  • Representative MCP behavior: open_binary returns success after stale resources are released; list_strings succeeds through the replacement. Unconfirmed cleanup returns error code cleanup_incomplete and launches no replacement.
  • Remaining proof gaps: no real Ghidra/JDK installation on this host; the new Unix-socket MCP scenarios explicitly skip Windows.

Validation performed

On macOS arm64 with Node 24.18.0 and npm 11.16.0:

  • npm run test:focused -- tests/boundary/mcp/ghidraReopen.test.ts tests/boundary/providers/ghidra/ghidraClient.test.ts src/ghidra/GhidraProvider.behavior.test.ts src/application/binary/BinarySessionLiveness.test.ts tests/composition/analysis-sessions/binarySession.test.ts tests/composition/analysis-sessions/providerBinding.test.ts — 124 tests passed across six files.
  • npm run check — passed; lint reported warnings and no errors.
  • Re-ran the 33 client boundary tests and npm run check after making the shutdown diagnostic assertion compare against the child's observed exit code; both passed.
  • npm run verify:test-discovery — all 895 test files discovered exactly once.
  • npm run jscpd — passed.
  • git diff --check — passed.
  • npm run verify:ghidra — build passed; real-provider verification could not start because GHIDRA_INSTALL_DIR is unavailable. No real-engine result is claimed.

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: controlled macOS process/socket coverage only; real Ghidra and Windows execution remain unverified.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: no new launch authority or transport data; recovery uses existing owned-resource cleanup and preserves failed cleanup for retry.

Review checklist

  • This PR addresses a concrete problem and links the related issue.
  • The change has one focused outcome and a Conventional Commit title.
  • Tests cover the changed behavior and cleanup failure paths.
  • Public schemas and generated metadata require no changes.
  • Representative MCP behavior and verification limits are recorded above.
  • The final diff contains no unrelated changes or unsupported claims.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 007a34940f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ghidra/GhidraClient.ts Resolved
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-12T06:11:39.692914Z 2f325ae New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@CassieFox23

Copy link
Copy Markdown
Contributor

TL;DR: The fix works with real Ghidra. I killed the Ghidra process, then reopened the same file. On head the next query started a fresh Ghidra and worked. On base the queries after that reopen failed.

Results

Base is 42b0ed1 and head is ad717f5. Each row ran in one MCP session over stdio. Times are from my client. Row labels match the step names in my logs.

Case Base Head
a. Open, then query Works. Query took about 6 s. Works. Query took about 6 s.
b. Kill Java, open same file, query, then list_documents (3 runs each) Open ok in 2 ms. Both queries fail in 2 to 3 ms with execution_failure. No new Java. 3 of 3. Open ok in 28 ms. Query works in 5.6 to 5.9 s. New Java started. list_documents works in 3 ms. 3 of 3.
d. Close, open same file, query Works. New Java started. Works. New Java started.
e. Kill Java, open a different file, query Works. New Java started. Works. New Java started.
f. Open, query, open same file with Java alive, query Same Java process. Second query took 2 ms. Same Java process. Second query took 2 ms.
g. Kill Java, then query with no reopen Fails with execution_failure. Fails the same way. The PR does not change this.
Leftover processes after each run None. None.
Unit test check Base Head
npm run typecheck pass pass
The PR's two test files (36 tests), Node 24.18.0 6 failed, 30 passed 36 passed
ghidraReopen.test.ts alone (3 tests), Node 24.18.0 3 failed 3 passed
Same two files, Node 22.23.1 and 26.11.1 not run 36 passed each
ghidraReopen.test.ts alone, Node 22.23.1 and 26.11.1 not run 3 passed each

On base I copied in the PR's two test files and its fake Ghidra fixture. The original ghidraClient.test.ts on base passes 33 of 33.

Not run

  • Case c, a closed bridge socket with a live process. The socket belongs to the Ghidra process. Closing it from outside means attaching to that process, which I did not do.
  • The cleanup_incomplete error with real Ghidra. I cannot make real cleanup fail. The PR's fake-Ghidra test covers it, and it passes on head.
  • Windows.
  • The reporter's 25 MB PE file. I used a 12 KB ELF, so each start took about 6 s.
  • A bridge that is connected but not answering. The PR says it does not cover this.
  • The full test suite and npm run check.

Thanks, lyly-bonbon, for the fix.

Commands
git -C ~/code/rea-mirror/rea.git fetch origin
git -C ~/code/rea-mirror/rea.git archive 42b0ed126 | tar -x -C $J/base
git -C ~/code/rea-mirror/rea.git archive ad717f566 | tar -x -C $J/head
# in each tree, Node 24.18.0
npm ci && npm run build && npm run test:prepare
npm run typecheck
npm run test:focused -- tests/boundary/mcp/ghidraReopen.test.ts tests/boundary/providers/ghidra/ghidraClient.test.ts
npm run test:focused -- tests/boundary/mcp/ghidraReopen.test.ts
# real Ghidra, one MCP server per session, driven over stdio
export GHIDRA_INSTALL_DIR=~/.local/opt/ghidra_12.1.4_PUBLIC JAVA_HOME=~/.local/opt/jdk-21.0.12.1+1
export REA_ANALYSIS_PROVIDER=ghidra REA_GHIDRA_STARTUP_TIMEOUT_MS=600000
node scripts/rea.mjs mcp

Each real-Ghidra session sent these calls.

  • Case b: open_binary hello, search_procedures main, SIGKILL the Java child of the server, wait 1 s, open_binary hello, search_procedures main, list_documents.
  • Case d: open_binary, search_procedures, close_binary, open_binary, search_procedures.
  • Case e: open_binary hello, search_procedures, SIGKILL, open_binary other, search_procedures mul.
  • Case f: open_binary, search_procedures, open_binary, search_procedures.
  • Case g: open_binary, search_procedures, SIGKILL, search_procedures twice.

The client script finds the Java child by walking /proc from its own server PID. REA starts Java directly, so Java is the server's own child. Two helper processes sit under Java (the decompiler and a demangler). The script kills only that Java PID. After each session it checks that every PID it saw is gone.

The PR branch forked from b8fab74, one commit before 42b0ed1. Both commits hold the same Ghidra source and fake fixture. The PR's own test file was copied into the base tree for the base unit-test runs.

Test setup
  • Box: Nobara 44 (Fedora 44 base), Linux 7.2.9
  • CPU: AMD Ryzen 9 5900X, 12 cores / 24 threads
  • RAM: 32 GB DDR4-3600
  • Node: 22.23.1, 24.18.0, 26.11.1
  • Head: ad717f5. Base: 42b0ed1.
  • Other: Ghidra 12.1.4 (Apache-2.0), Temurin JDK 21.0.12.1. Test files were a 12 KB ELF and a second small ELF I built with gcc from a short C file.
  • The load average (busy tasks, out of 24 threads) was about 1.3 to 2.0. I did not check whether other agents were running.

🤖 Generated with Claude Code (Sonnet 5.5, verified by Opus 5.5) 🦊

cursoragent and others added 3 commits October 12, 2026 04:52
Health and startup exit checks called the supervisor snapshot, which
concatenates retained launcher output only to read the exit code.
@morluto
morluto merged commit 4573e8c into morluto:main Oct 12, 2026
29 checks passed
@github-actions github-actions Bot mentioned this pull request Oct 12, 2026
3 tasks done
@CassieFox23

Copy link
Copy Markdown
Contributor

TL;DR: This PR merged as 4573e8c. Before that, I retested its last code change. Every test and every real Ghidra case gave the same result as before.

I retested head 2ecd9df. Results match my earlier comment on ad717f5, so nothing new broke. The final head, 2f325ae, only brought in main. The PR's own files there match what I tested.

Check On ad717f5 On 2ecd9df
Real Ghidra, cases a, b, d, e, f work work, same outcome
Real Ghidra, case g (query after a kill, no reopen) fails fails the same way, the PR does not change this
typecheck pass pass
Reopen test file pass pass
Client test file pass pass
Process output test file not run pass

All tests passed on Node 22, 24 and 26.

Still not run

  • Case c, a closed bridge socket with a live process.
  • The cleanup_incomplete error with real Ghidra.
  • Windows.
  • The reporter's 25 MB PE file.
  • A bridge that is connected but not answering.
  • The full test suite and npm run check.

Thanks, lyly-bonbon, for the fix.

Commands
git -C ~/code/rea-mirror/rea.git archive 2ecd9df83 | tar -x -C $J/head
npm ci && npm run build && npm run test:prepare
npm run typecheck
npm run test:focused -- tests/boundary/mcp/ghidraReopen.test.ts
npm run test:focused -- tests/boundary/providers/ghidra/ghidraClient.test.ts
npm run test:focused -- src/process/ProviderProcessOutput.test.ts
# real Ghidra, same stdio script as my earlier comment
node scripts/rea.mjs mcp

I ran each test file alone on each Node version. Each real-Ghidra case ran in its own MCP session, and case b ran 3 times. After each session, none of my processes were still running. The target was a 12 KB ELF built with gcc from a short C file. It is not the same file as in my first run. Queries ran about half a second slower, and the box was busier. I did not pin the cause.

Test setup
  • Box: Nobara 44 (Fedora 44 base), Linux 7.2.9
  • CPU: AMD Ryzen 9 5900X, 12 cores / 24 threads
  • RAM: 32 GB DDR4-3600
  • Node: 22.23.1, 24.18.0, 26.11.1
  • Head: 2ecd9df. Base: 42b0ed1.
  • Other: Ghidra 12.1.4 (Apache-2.0), Temurin JDK 21.0.12.1
  • Other agents shared the box. The load average (busy tasks, out of 24 threads) was about 4 at the end.

🤖 Generated with Claude Code (Sonnet 5.5, verified by Opus 5.5) 🦊

@morluto

morluto commented Oct 12, 2026

Copy link
Copy Markdown
Owner

@lyly-bonbon, thank you for making same-target Ghidra reopen respond to observed process exits and disconnected sockets. The recovery path keeps lazy reuse for a live client, while holding onto ownership when cleanup is still uncertain—a useful lifecycle distinction. Welcome to REA!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: native Native analysis and decompilation, including Ghidra, IDA, and Hopper analysis behavior bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants