reverse-engineering-assistant 7.2.1__tar.gz → 7.3.0__tar.gz

{reverse_engineering_assistant-7.2.1 → reverse_engineering_assistant-7.3.0}/.gitattributes

@@ -2,4 +2,7 @@ tests/fixtures/test_fat_binary filter=lfs diff=lfs merge=lfs -text
 tests/fixtures/test_archive.zip filter=lfs diff=lfs merge=lfs -text
 tests/fixtures/test_arm64 filter=lfs diff=lfs merge=lfs -text
 tests/fixtures/test_x86_64 filter=lfs diff=lfs merge=lfs -text
+tests/fixtures/test_cpp_arm64 filter=lfs diff=lfs merge=lfs -text
+tests/fixtures/test_cpp_x86_64 filter=lfs diff=lfs merge=lfs -text
 tests/fixtures/*.zip filter=lfs diff=lfs merge=lfs -text
+tests/fixtures/test_dataflow_x86_64 filter=lfs diff=lfs merge=lfs -text

reverse_engineering_assistant-7.3.0/.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,91 @@
+name: Copilot Setup Steps
+
+# Provisions the environment for the GitHub Copilot coding agent.
+# Mirrors the toolchain used by test-ghidra.yml and test-headless.yml so the
+# agent can build the extension, run Java unit + integration tests, and
+# exercise the Python CLI / PyGhidra paths without further setup.
+#
+# Schema constraints (see GitHub Copilot docs):
+#   - Job MUST be named `copilot-setup-steps`.
+#   - Only `steps`, `permissions`, `runs-on`, `services`, `snapshot`,
+#     and `timeout-minutes` (max 59) may be set on the job.
+#   - actions/checkout fetch-depth is overridden by the system.
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          lfs: true
+
+      - name: Install C/C++ toolchain and Xvfb
+        # build-essential covers gcc/g++/make for rebuilding tests/fixtures
+        # sources. clang is handy for cross-checks. xvfb lets the agent run
+        # Ghidra integration tests (which require a display) on demand.
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            build-essential \
+            clang \
+            xvfb \
+            unzip
+          gcc --version
+          clang --version
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v5
+        with:
+          java-version: "21"
+          distribution: "microsoft"
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Install Ghidra
+        # Sets GHIDRA_INSTALL_DIR for subsequent steps and the agent session.
+        uses: antoniovazquezblanco/setup-ghidra@v2.1.2
+        with:
+          version: "latest"
+          auth_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v6
+        with:
+          gradle-version: "8.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Sync Python dependencies
+        run: uv sync --prerelease=allow
+
+      - name: Install PyGhidra from local Ghidra
+        run: uv pip install "${GHIDRA_INSTALL_DIR}/Ghidra/Features/PyGhidra/pypkg"
+
+      - name: Verify PyGhidra installation
+        run: |
+          uv run python -c "import pyghidra; print(f'PyGhidra version: {pyghidra.__version__}')"
+
+      - name: Pre-warm Gradle dependency cache
+        # Resolve Java deps and compile sources so the agent's first build
+        # is fast. Skipping `buildExtension` keeps setup under the timeout
+        # while still pulling every dependency the build graph needs.
+        run: gradle --no-daemon compileJava compileTestJava compileIntegrationTestJava

{reverse_engineering_assistant-7.2.1 → reverse_engineering_assistant-7.3.0}/.github/workflows/publish-ghidra.yml

@@ -22,6 +22,7 @@ jobs:
             "12.0.2",
             "12.0.3",
             "12.0.4",
+            "12.1",
         ]
     name: Build distribution 📦
     runs-on: ubuntu-latest
@@ -33,7 +34,7 @@ jobs:
         java-version: "21"
         distribution: "microsoft"
     - name: Install Ghidra 🐉
-      uses: antoniovazquezblanco/setup-ghidra@v2.1.0
+      uses: antoniovazquezblanco/setup-ghidra@v2.1.2
       with:
         version: ${{ matrix.ghidra-version }}
         auth_token: ${{ secrets.GITHUB_TOKEN }}

{reverse_engineering_assistant-7.2.1 → reverse_engineering_assistant-7.3.0}/.github/workflows/test-ghidra.yml

@@ -23,6 +23,7 @@ jobs:
             "12.0.2",
             "12.0.3",
             "12.0.4",
+            "12.1",
             "latest",
         ]
     name: Test on Ghidra ${{ matrix.ghidra-version }}
@@ -39,7 +40,7 @@ jobs:
         distribution: "microsoft"
 
     - name: Install Ghidra 🐉
-      uses: antoniovazquezblanco/setup-ghidra@v2.1.0
+      uses: antoniovazquezblanco/setup-ghidra@v2.1.2
       with:
         version: ${{ matrix.ghidra-version }}
         auth_token: ${{ secrets.GITHUB_TOKEN }}
@@ -104,7 +105,7 @@ jobs:
         distribution: "microsoft"
 
     - name: Install Ghidra 🐉
-      uses: antoniovazquezblanco/setup-ghidra@v2.1.0
+      uses: antoniovazquezblanco/setup-ghidra@v2.1.2
       with:
         version: "latest"
         auth_token: ${{ secrets.GITHUB_TOKEN }}
@@ -155,7 +156,7 @@ jobs:
         queries: security-extended,security-and-quality
 
     - name: Install Ghidra 🐉
-      uses: antoniovazquezblanco/setup-ghidra@v2.1.0
+      uses: antoniovazquezblanco/setup-ghidra@v2.1.2
       with:
         version: "latest"
         auth_token: ${{ secrets.GITHUB_TOKEN }}

{reverse_engineering_assistant-7.2.1 → reverse_engineering_assistant-7.3.0}/.github/workflows/test-headless.yml

@@ -23,7 +23,23 @@ jobs:
           - "12.0.2"
           - "12.0.3"
           - "12.0.4"
+          - "12.1"
           - "latest"
+        # macOS hosted runners are ~4x slower per e2e test and far scarcer
+        # (7 concurrent macOS jobs queued for hours). Linux carries full
+        # version coverage; macOS validates the platform itself (native
+        # decompiler build, arm64) on the oldest and newest Ghidra only.
+        exclude:
+          - os: macos-latest
+            ghidra-version: "12.0.1"
+          - os: macos-latest
+            ghidra-version: "12.0.2"
+          - os: macos-latest
+            ghidra-version: "12.0.3"
+          - os: macos-latest
+            ghidra-version: "12.0.4"
+          - os: macos-latest
+            ghidra-version: "12.1"
       fail-fast: false  # Continue other tests if one fails
 
     name: Test on ${{ matrix.os }} / Ghidra ${{ matrix.ghidra-version }}
@@ -47,7 +63,7 @@ jobs:
         python-version: "3.10"
 
     - name: Install Ghidra ${{ matrix.ghidra-version }}
-      uses: antoniovazquezblanco/setup-ghidra@v2.1.0
+      uses: antoniovazquezblanco/setup-ghidra@v2.1.2
       with:
         version: ${{ matrix.ghidra-version }}
         auth_token: ${{ secrets.GITHUB_TOKEN }}
@@ -57,6 +73,16 @@ jobs:
       with:
         gradle-version: "8.14"
 
+    # Ghidra releases ship prebuilt decompiler natives for Linux and Windows but
+    # NOT macOS. Without this, decompilation silently returns nothing on macOS
+    # runners and any decompiler-dependent headless test fails. Ghidra searches
+    # build/os/<platform> (where this task writes) before os/<platform>, so the
+    # installed PyGhidra runtime picks these up. Linux runners already have
+    # prebuilt natives, so the step is macOS-only.
+    - name: Build Ghidra natives (macOS only)
+      if: runner.os == 'macOS'
+      run: gradle -p "$GHIDRA_INSTALL_DIR/support/gradle" buildNatives
+
     - name: Build ReVa Extension
       run: gradle clean buildExtension --no-build-cache
 
@@ -89,11 +115,18 @@ jobs:
       id: headless_test
       run: |
         echo "::group::Running headless integration tests"
-        uv run pytest tests/ -v --timeout=180 --tb=short --junitxml=test-results.xml
+        uv run pytest tests/ -v --timeout=180 --tb=short --junitxml=test-results.xml ${PYTEST_EXTRA_ARGS}
         echo "::endgroup::"
+      # The e2e suite shares one mcp-reva server per pytest session (per
+      # xdist worker), so the dominant historical cost — a full JVM/PyGhidra
+      # boot per test (~40s on macOS, ~10s on Linux) — is paid once per
+      # worker instead of ~110 times. macOS additionally runs 2 xdist
+      # workers. If this times out again, suspect a server hang or a new
+      # per-test boot, not a slow suite.
       timeout-minutes: 30
       env:
         GHIDRA_INSTALL_DIR: ${{ env.GHIDRA_INSTALL_DIR }}
+        PYTEST_EXTRA_ARGS: ${{ runner.os == 'macOS' && '-n 2' || '' }}
 
     - name: Upload test artifacts
       uses: actions/upload-artifact@v7

{reverse_engineering_assistant-7.2.1 → reverse_engineering_assistant-7.3.0}/.gitignore

@@ -17,3 +17,6 @@ __pycache__
 # ReVa local project directories
 .reva/
 .claude/worktrees
+
+# Local superpowers spec workspace
+docs/superpowers/

{reverse_engineering_assistant-7.2.1 → reverse_engineering_assistant-7.3.0}/CLAUDE.md

@@ -138,7 +138,7 @@ mcp-reva CLI → PyGhidra → ReVaLauncher → Jetty (HTTP)
 - **Foundation Layer** (`util/`) - AddressUtil, ProgramLookupUtil, DataTypeParserUtil, etc.
 - **Plugin Layer** (`plugin/`) - ConfigManager, RevaProgramManager, Ghidra lifecycle
 - **Server Layer** (`server/`) - McpServerManager, Jetty server, streamable transport
-- **Tool Layer** (`tools/`) - 17 specialized tool packages (decompiler, functions, strings, callgraph, dataflow, etc.)
+- **Tool Layer** (`tools/`) - 19 specialized tool packages (decompiler, functions, strings, callgraph, dataflow, etc.)
 - **Resource Layer** (`resources/`) - Read-only MCP resource providers
 - **Headless Layer** (`headless/`) - RevaHeadlessLauncher for PyGhidra integration
 
@@ -154,7 +154,7 @@ src/main/java/reva/          # Java extension code
   ├── util/                  # Foundational utilities (ALWAYS use these!)
   ├── plugin/                # ConfigManager, plugin lifecycle
   ├── server/                # McpServerManager, Jetty
-  ├── tools/                 # 17 tool provider packages
+  ├── tools/                 # 19 tool provider packages
   ├── resources/             # MCP resource providers
   ├── headless/              # RevaHeadlessLauncher
   └── ui/                    # Optional GUI components
@@ -168,15 +168,17 @@ scripts/                     # Helper scripts (reva_headless_server.py)
 ### Package-Level Documentation
 Each major package contains its own CLAUDE.md file with detailed implementation guidance:
 - **Essential Infrastructure**: `util/`, `plugin/`, `server/` - Core systems documentation
-- **Tool Providers**: Each of the 17 tool packages has comprehensive implementation guides
+- **Tool Providers**: Each of the 19 tool packages has comprehensive implementation guides
 - **Supporting Systems**: `resources/`, `services/`, `ui/` - Specialized component documentation
 
 ### Tool Provider Categories
 - **Core Analysis**: decompiler, functions, strings, symbols, xrefs, memory
 - **Data & Types**: data, datatypes, structures
 - **Advanced Analysis**: callgraph, dataflow, constants, vtable, imports
+- **diff**: binary diffing via Version Tracking (match functions, explain changes, transfer analysis between variants)
 - **Annotations**: comments, bookmarks
 - **Project Management**: project
+- **Scripting**: scripts (Python script run/list/read/write/edit; requires PyGhidra)
 
 ## Development Guidelines
 
@@ -224,6 +226,7 @@ When adding new tools to DecompilerToolProvider:
 - Return structured JSON with success flags and program metadata
 - Exception handling is automatic: `registerTool()` wraps all handlers to catch `IllegalArgumentException` and `ProgramValidationException` and convert them to error responses. Manual try-catch is only needed for custom error handling or resource cleanup (e.g., DecompInterface disposal).
 - Use pagination for large datasets (functions, symbols, strings, etc.)
+- Progress notifications: only emit when client opted in (`request.progressToken() != null` → `exchange.progressNotification(new ProgressNotification(token, progress, total, message))`). Examples: `ProjectToolProvider` import-file, `DecompilerToolProvider` search-decompilation.
 
 ## MCP Server Configuration
 
@@ -262,13 +265,13 @@ Install via: `claude plugin marketplace add cyberkaida/reverse-engineering-assis
 ### Java
 - Ghidra: 12.0+ (source at `../ghidra`)
 - Java: 21+
-- MCP SDK: io.modelcontextprotocol.sdk v0.17.0 (BOM-managed)
-- Jackson: 2.20.x (force-resolved for MCP SDK compatibility)
+- MCP SDK: io.modelcontextprotocol.sdk v1.1.1 (BOM-managed)
+- Jackson: 2.21.x (force-resolved for MCP SDK compatibility)
 - Jetty: 11.0.26 (embedded servlet server)
 
 ### Python
 - Python: 3.10+ (managed via uv)
-- PyGhidra: 3.0.0+ (Ghidra initialization)
+- PyGhidra: 3.1.0+ (Ghidra initialization)
 - MCP: Latest (stdio transport implementation)
 - httpx + httpx-sse: MCP HTTP client (for StdioBridge)
 
@@ -301,7 +304,7 @@ Install via: `claude plugin marketplace add cyberkaida/reverse-engineering-assis
 - **Testing (Java)**: Integration tests require `java.awt.headless=false`, fork=1
 - **Testing (Python)**: pytest with markers (unit/integration/e2e/cli)
 - **Build**: Use `gradle` directly, NOT `./gradlew`
-- **MCP SDK**: v0.17.0 with forced Jackson 2.20.x for compatibility
+- **MCP SDK**: v1.1.1 with forced Jackson 2.21.x for compatibility
 
 ## Important Notes
 
@@ -313,9 +316,11 @@ Install via: `claude plugin marketplace add cyberkaida/reverse-engineering-assis
 
 ### Common Issues
 - **Jackson conflicts**: `rm lib/*.jar` and rebuild to fix MCP SDK compatibility
-- **Test reports**: Use Read tool or Grep, NOT `open` command
+- **Test reports**: Parse `build/test-results/integrationTest/TEST-*.xml` with Read/Grep — don't trust `BUILD SUCCESSFUL` alone (compileIntegrationTestJava can fail silently in mixed output)
 - **CI logs**: Use Task agent to read (very long logs, context-intensive)
 - **Stdio mode**: Requires clean stdin/stdout - no debug prints to stdout
+- **Help build (`gradle install`)**: JavaHelp validation fails the whole module on any cross-file anchor collision in `src/main/help/help/topics/` or any broken `help/shared/*` reference (note/tip/warning images live in `src/main/resources/help/shared/`, not under `src/main/help/`). See [help/CLAUDE.md](src/main/help/CLAUDE.md).
+- **Test fixtures (binaries)**: All binary fixtures under `tests/fixtures/` MUST be tracked via git-lfs. Before `git add`-ing a new binary, register it in `.gitattributes` with `filter=lfs diff=lfs merge=lfs -text` (per-file or via glob like `tests/fixtures/test_cpp_*`). Verify the staged form is a 3-line LFS pointer (`version https://git-lfs.github.com/...`), not raw bytes — `git diff --cached <path>` should show ~3 insertions, not thousands. If a binary slipped into a commit as raw bytes, fix with `git reset --soft HEAD~1`, update `.gitattributes`, `git rm --cached <binary>`, then re-add (the LFS clean filter runs on add). CI's `actions/checkout@v6` is configured with `lfs: true` so pointers resolve to real binaries on remote runners.
 
 ### Testing Strategy
 - **Java unit tests**: Fast, no Ghidra environment, test utilities/logic

{reverse_engineering_assistant-7.2.1 → reverse_engineering_assistant-7.3.0}/DEVELOPER.md

@@ -150,7 +150,7 @@ ReVa is designed to handle the Ghidra lifecycle correctly:
 | MCP SDK | v0.17.0 |
 | Jackson | 2.20.x |
 | Jetty | 11.0.26 |
-| PyGhidra | 3.0.0+ |
+| PyGhidra | 3.1.0+ |
 | JUnit | 4 (NOT 5) |
 
 ### Build Commands

reverse_engineering_assistant-7.3.0/Module.manifest

@@ -0,0 +1 @@
+MODULE DEPENDENCY: Ghidra/Features/VersionTracking

{reverse_engineering_assistant-7.2.1 → reverse_engineering_assistant-7.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reverse-engineering-assistant
-Version: 7.2.1
+Version: 7.3.0
 Summary: ReVa - AI-powered Reverse Engineering Assistant for Ghidra with MCP server and Claude CLI integration
 Author-email: cyberkaida <cyberkaida@users.noreply.github.com>
 Maintainer: cyberkaida
@@ -28,7 +28,7 @@ Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pyghidra>=3.0.0
+Requires-Dist: pyghidra>=3.1.0
 Requires-Dist: mcp
 Requires-Dist: httpx<1.0,>=0.27.0
 Requires-Dist: httpx-sse>=0.4.0
@@ -37,6 +37,7 @@ Requires-Dist: pytest>=7.0.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
 Requires-Dist: pytest-timeout>=2.0.0; extra == "test"
 Requires-Dist: pytest-sugar>=0.9.0; extra == "test"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
 Requires-Dist: mcp; extra == "test"
 Requires-Dist: httpx<1.0,>=0.27.0; extra == "test"
 Requires-Dist: httpx-sse>=0.4.0; extra == "test"
@@ -90,6 +91,7 @@ You can ask questions like:
 - What does `mmap` return?
 - What does the function at address 0x80000 do?
 - This is a CTF problem. Write a pwntools script to get the flag.
+- Import these two binaries and diff them, explain the changes.
 
 # Installation
 
@@ -110,6 +112,12 @@ After installing the extension you need to activate it in two places:
 1. In the Project view, open the File menu and select "Configure". Click the "Configure all plugins" button on the top right of the menu (it looks like a plug). Check the "ReVa Application Plugin"
 2. In the Code Browser tool (Click the Dragon icon or open a File), open the File menu and select "Configure". Click the "Configure all plugins" button on the top right of the menu (it looks like a plug). Check the "ReVa Plugin". Then Press File and select "Save Tool". This will enable ReVa by default.
 
+> NOTE: ReVa provides access to the PyGhidra scripting environment. If
+> you allow ReVa to listen on a public interface, either enable the API
+> key authentication or disable the scripting tools in the settings.
+> The default configuration is to listen on localhost and allow the
+> scripting tools.
+
 # Usage
 
 There are two ways to use ReVa, with the Ghidra UI in assistant mode or in headless mode. Headless mode is ideal for automation and CI/CD pipelines, while the assistant mode is great for interactive analysis.

{reverse_engineering_assistant-7.2.1 → reverse_engineering_assistant-7.3.0}/README.md

@@ -46,6 +46,7 @@ You can ask questions like:
 - What does `mmap` return?
 - What does the function at address 0x80000 do?
 - This is a CTF problem. Write a pwntools script to get the flag.
+- Import these two binaries and diff them, explain the changes.
 
 # Installation
 
@@ -66,6 +67,12 @@ After installing the extension you need to activate it in two places:
 1. In the Project view, open the File menu and select "Configure". Click the "Configure all plugins" button on the top right of the menu (it looks like a plug). Check the "ReVa Application Plugin"
 2. In the Code Browser tool (Click the Dragon icon or open a File), open the File menu and select "Configure". Click the "Configure all plugins" button on the top right of the menu (it looks like a plug). Check the "ReVa Plugin". Then Press File and select "Save Tool". This will enable ReVa by default.
 
+> NOTE: ReVa provides access to the PyGhidra scripting environment. If
+> you allow ReVa to listen on a public interface, either enable the API
+> key authentication or disable the scripting tools in the settings.
+> The default configuration is to listen on localhost and allow the
+> scripting tools.
+
 # Usage
 
 There are two ways to use ReVa, with the Ghidra UI in assistant mode or in headless mode. Headless mode is ideal for automation and CI/CD pipelines, while the assistant mode is great for interactive analysis.

reverse_engineering_assistant-7.3.0/ReVa/skills/pyghidra-scripting/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: pyghidra-scripting
+description: Write and run Python (PyGhidra) code inside the Ghidra session that ReVa's MCP server is already attached to, using the five ReVa scripting tools — `run-script`, `list-scripts`, `read-script`, `write-script`, `edit-script`. Use this whenever the user asks to execute Python against the current program, reach for the Ghidra Flat API directly, write a custom analysis pass, automate something the other ReVa tools don't expose, or persist a `.py` script in Ghidra's scripts directory. Also use when an existing ReVa MCP tool can't do what's needed and the right answer is "drop into PyGhidra for one call." Do NOT use this skill for plain ReVa tool calls that already have a dedicated MCP tool (use that tool instead); do NOT use it to build standalone Python programs that run pyghidra in their own process (the run-script tool runs *inside* the ReVa-hosted Ghidra).
+---
+
+# PyGhidra scripting via ReVa
+
+ReVa exposes five MCP tools under the `scripts` provider that let an assistant write, edit, run, and inspect Python scripts inside the same Ghidra session ReVa is serving. The Python code runs under PyGhidra (CPython 3 + JPype), so it has the full Ghidra Java API available — the `FlatProgramAPI`, `DecompInterface`, `FunctionManager`, everything.
+
+This skill teaches when to reach for these tools, how to structure the Python you send to `run-script`, and the pitfalls that bite in practice.
+
+## The five tools at a glance
+
+| Tool | Purpose | Use when |
+|---|---|---|
+| `run-script` | Execute Python against a program. Inline `code`, or by `scriptPath` / `scriptName`. | The dedicated ReVa MCP tools don't cover what you need, or you want one tight pass over the program. |
+| `list-scripts` | Enumerate scripts across registered directories. Filterable by name/path; paginated. | Discovering what's already saved before writing a new one. |
+| `read-script` | `cat -n` view of a script with `offset` / `limit` and a `truncated` flag. | Reading an existing script before editing it. The numbered output is what `edit-script` lines up against. |
+| `write-script` | Create a new `.py` file (or full overwrite with `overwrite: true`). User-writeable dirs only. | Saving a reusable script. Never reach for this just to bundle inline code — use `run-script` with `code` for one-shot use. |
+| `edit-script` | `old_string` → `new_string` replacement. Errors if `old_string` matches multiple places unless `replace_all: true`. | Iterating on an existing script. Pair with `read-script` to see line context first. |
+
+## Reach-for-it triggers
+
+`run-script` is the escape hatch. Use it when:
+
+- You need to run a custom predicate over every function/symbol/instruction and the existing list/find tools don't filter the right way.
+- You need to combine multiple Ghidra API calls into one operation that would otherwise take many MCP round-trips.
+- You want to use a Ghidra API ReVa doesn't expose — e.g. `DecompInterface` low-level features, `PCode` analysis, custom `AddressSet` arithmetic, the data flow API directly, `BinaryReader`, etc.
+- You're prototyping; once it works and is reusable, save it with `write-script`.
+
+Don't use `run-script` when a dedicated ReVa MCP tool already does the job — those tools have stable schemas and structured output that's easier to reason about than free-form `stdout`. The decompiler / functions / strings / symbols / xrefs tools cover the common path.
+
+## Runtime gate: PyGhidra-only
+
+`run-script` only works when Ghidra was launched **under PyGhidra**:
+
+- ✅ `mcp-reva` (Claude CLI / stdio mode)
+- ✅ `pyghidra-gui` (GUI mode launched with PyGhidra)
+- ✅ `reva_headless_server.py` (headless mode via PyGhidra)
+- ❌ Plain `ghidraRun` — PyGhidra is not wired in; you'll get a `PyGhidraNotAvailableException` error response with launch guidance.
+
+If a `run-script` call comes back with that error, the right move is to tell the user how to relaunch (don't keep retrying). The other four tools (`list-scripts`, `read-script`, `write-script`, `edit-script`) work in every mode because they're plain file operations.
+
+## The execution contract for `run-script`
+
+This is the contract your inline `code` (or saved script) runs under. Internalise it — most failures come from getting one of these wrong.
+
+**Pre-bound globals.** The script runs as a Ghidra PyGhidra script, so the standard `GhidraScript` globals are already defined: `currentProgram`, `currentAddress`, `currentSelection`, `currentHighlight`, `monitor`, `state`, plus `FlatProgramAPI` helpers like `toAddr`, `getFunctionAt`, `getFunctionContaining`, `getSymbolAt`, `getInstructionAt`, `getDataAt`, `getReferencesTo`, `getReferencesFrom`, `createLabel`, `setEOLComment`, `find`, `findBytes`, `clearListing`. You do **not** need to import or set these up. `currentProgram` is the program identified by the `programPath` argument.
+
+**No automatic transaction.** Unlike GhidraScripts run from inside Ghidra's GUI, ReVa's `run-script` deliberately does **not** open a transaction around your code. Any mutation (rename, retype, comment, label, create function, etc.) must be wrapped manually:
+
+```python
+tx = currentProgram.startTransaction("Describe the edit")
+try:
+    # ... do stuff that mutates state ...
+    currentProgram.endTransaction(tx, True)   # commit
+except Exception:
+    currentProgram.endTransaction(tx, False)  # roll back
+    raise
+```
+
+This is intentional — auto-wrapping at the tool layer would create nested-transaction footguns when scripts already handle their own. Read-only scripts (printing, counting, dumping) need no transaction at all.
+
+**Inline header.** When you pass `code`, the tool prepends `# @runtime PyGhidra\n` automatically. Don't add it yourself.
+
+**Cancellation is cooperative.** The configured timeout (default 60s, overridable per-call via `timeoutSeconds`) only fires if your code yields to the monitor. In long loops, call `monitor.isCancelled()` regularly and break:
+
+```python
+fm = currentProgram.getFunctionManager()
+for func in fm.getFunctions(True):
+    if monitor.isCancelled():
+        break
+    # ... work ...
+```
+
+A tight Python loop without a monitor check will run past the timeout. The result will then come back with `timedOut: true` and partial output but the Ghidra session may still be busy for a moment.
+
+**Output is captured and capped.** `stdout` and `stderr` are each capped at 64K chars by default (configurable via `SCRIPT_OUTPUT_CHAR_LIMIT`). If you blow the cap, the result has `stdoutTruncated: true` or `stderrTruncated: true`. Design output for an LLM consumer — terse, structured, line-per-record. Reach for JSON if downstream parsing matters:
+
+```python
+import json
+results = []
+for func in currentProgram.getFunctionManager().getFunctions(True):
+    if monitor.isCancelled(): break
+    if some_predicate(func):
+        results.append({"addr": str(func.getEntryPoint()), "name": func.getName()})
+print(json.dumps(results))
+```
+
+**Result schema.** `run-script` returns:
+
+```json
+{
+  "success": true|false,
+  "programPath": "/binary.exe",
+  "stdout": "...",
+  "stderr": "...",
+  "stdoutTruncated": false,
+  "stderrTruncated": false,
+  "durationMs": 1234,
+  "timedOut": false,
+  "scriptSource": {"type": "inline|path|name", "value": "..."},
+  "error": "ClassName: message"   // only when the executor itself threw
+}
+```
+
+`success` is `false` if the script raised a Python exception (detected via the `Traceback (most recent call last)` marker in stderr), if it hit the timeout, or if the executor threw. Read `stderr` to see the actual traceback — Python exceptions don't surface as MCP errors, they come back in `stderr` with `success: false`.
+
+## What you can call from inside
+
+The script has the full Ghidra/PyGhidra surface. The most commonly useful entry points:
+
+```python
+# Program structure
+prog     = currentProgram                             # the Program object
+listing  = prog.getListing()                          # CodeUnits, data, comments
+memory   = prog.getMemory()                           # blocks, bytes
+fm       = prog.getFunctionManager()                  # functions
+st       = prog.getSymbolTable()                      # symbols/labels
+rm       = prog.getReferenceManager()                 # xrefs
+dtm      = prog.getDataTypeManager()                  # data types
+
+# Flat-API one-liners (already global)
+addr     = toAddr(0x401000)
+func     = getFunctionAt(addr) or getFunctionContaining(addr)
+sym      = getSymbolAt(addr)
+instr    = getInstructionAt(addr)
+xrefs_to = getReferencesTo(addr)
+
+# Java classes — import as normal Python after PyGhidra is up (it is, when run-script runs)
+from ghidra.program.model.symbol import SourceType
+from ghidra.app.decompiler import DecompInterface, DecompileOptions
+```
+
+For everything else: see [references/flat-api.md](references/flat-api.md) for the categorised Flat-API cheat-sheet, and [references/jpype-interop.md](references/jpype-interop.md) for the Java-via-Python idioms (arrays, iterators, sign extension, type stubs).
+
+## Workflow patterns
+
+### Inline one-shot (most common)
+
+```
+run-script(programPath="/bin", code="""
+fm = currentProgram.getFunctionManager()
+total = 0
+huge = []
+for f in fm.getFunctions(True):
+    if monitor.isCancelled(): break
+    size = f.getBody().getNumAddresses()
+    total += size
+    if size > 4096:
+        huge.append((str(f.getEntryPoint()), f.getName(), size))
+print(f'total bytes: {total}')
+for addr, name, size in huge:
+    print(f'{addr} {size:6d} {name}')
+""")
+```
+
+Read the stdout, draw conclusions, move on. Nothing persisted.
+
+### Iterate then save
+
+1. Send a draft via `run-script` with inline `code`.
+2. When it works, call `write-script` with `scriptName="MyAnalysis.py"` and the final `code`. (Pick a descriptive name — `list-scripts` will return it.)
+3. Next time, `run-script` with `scriptName="MyAnalysis.py"`.
+
+### Edit-in-place on a saved script
+
+1. `list-scripts` (or remember the name).
+2. `read-script` — note the line numbers around what you want to change.
+3. `edit-script` with `old_string` set to a *uniquely identifying* slice (include enough surrounding context that there's exactly one match). The tool errors out on ambiguity unless you pass `replace_all: true`.
+4. Re-run via `run-script(scriptName=...)`.
+
+`edit-script` is preferred over re-writing the whole file — it preserves the rest of the script unchanged and is what the user can review as a diff.
+
+## Pitfalls
+
+These are the ones that account for most "why did my script misbehave."
+
+### Forgot the transaction
+Mutations without `startTransaction` throw `IllegalStateException: not in transaction`. If a `run-script` call mutates and you see this in `stderr`, that's the cause. Wrap the mutating block — see the contract section above.
+
+### `monitor.isCancelled()` check missing
+Tight loops that never check the monitor blow past the timeout silently — the `timedOut` flag still flips, but your script may have already done damage. Always check the monitor inside any loop touching every function / instruction / address.
+
+### Java `Iterator` vs Python iterable
+Most Ghidra iterators are Python-iterable thanks to JPype, but a few (notably `SymbolIterator` from some accessors and the older `ReferenceIterator`) only expose `hasNext()` / `next()`. If a `for x in it:` loop silently yields nothing, fall back to `while it.hasNext(): x = it.next()`. `FunctionManager.getFunctions(True)` is iterable directly.
+
+### Java `byte` is signed
+`MemoryBlock.getBytes(addr, byte[] buf)` fills you a Java `byte[]`. Values come back as `-128..127`. Mask with `b & 0xff` if you want `0..255`. Allocating the buffer: `import jpype; buf = jpype.JByte[16]`.
+
+### `print()` is what shows up in stdout
+The script's `print()` is rerouted to the captured stdout writer — that's how you get output back. Don't use logging frameworks expecting them to flush somewhere visible; `print(...)` is the contract.
+
+### Decompiler is expensive to construct
+If you decompile more than a handful of functions in one script, build the `DecompInterface` once and reuse it. Always `dispose()` it. With a per-function timeout of 30s, a 100-function pass that re-builds the decompiler each call can easily blow `run-script`'s overall timeout.
+
+```python
+from ghidra.app.decompiler import DecompInterface
+decomp = DecompInterface()
+decomp.openProgram(currentProgram)
+try:
+    for f in currentProgram.getFunctionManager().getFunctions(True):
+        if monitor.isCancelled(): break
+        res = decomp.decompileFunction(f, 30, monitor)
+        if res.decompileCompleted():
+            # process res.getDecompiledFunction().getC()
+            pass
+finally:
+    decomp.dispose()
+```
+
+### `script` paths must live inside a registered scripts dir
+`run-script(scriptPath=...)` refuses paths outside Ghidra's registered script directories (user dir, system dirs, bundle dirs). Same for `read-script`. For writes, you're additionally limited to the *writeable* set (user dir, typically `~/ghidra_scripts/`). System dirs are read-only.
+
+### Inline `code` and saved scripts both bypass Ghidra's `# @category` UI metadata
+`run-script(code=...)` writes a temp file with only the `# @runtime PyGhidra` header. `# @category`, `# @menupath`, `# @keybinding` headers in a *saved* script matter for the Ghidra GUI but are ignored by `run-script` — keep them if you want the script to appear in the Script Manager, drop them otherwise.
+
+## Where to go next
+
+These reference files are bundled with the skill. Load only the one(s) relevant.
+
+- **[references/flat-api.md](references/flat-api.md)** — Categorised cheat-sheet for the program-inspection surface: `FlatProgramAPI` one-liners (`toAddr`, `getFunctionAt`, `createLabel`, `setEOLComment`, references, comments, bookmarks, search), `AddressSet` arithmetic for restricting iteration, imports/externals/thunks (`isThunk`, `getCallingFunctions`, `ExternalManager`), data types & structs (`StructureDataType`, `DataTypeManager`, `createData`), and `FlatDecompilerAPI` basics. Load when writing inline `code` that inspects or mutates program structure.
+
+- **[references/decompiler-pcode.md](references/decompiler-pcode.md)** — The decompiler's internal representation: `HighFunction`, `LocalSymbolMap`, `HighSymbol`/`HighVariable`/`HighParam`, `Varnode` def-use chains, `PcodeOp` opcodes (COPY/LOAD/CALL/MULTIEQUAL/PTRSUB/…), `ParallelDecompiler` for batch passes, `HighFunctionDBUtil` for persisting decompiler-derived renames. Load when the question is "trace this value back to its source", "where does this argument come from", "which functions look like the decompiler got confused", "rename this `iVar3` to something useful", or any task that needs more than the C source string.
+
+- **[references/jpype-interop.md](references/jpype-interop.md)** — Python ↔ Java boundary notes: arrays (`jpype.JByte[16]`), sign extension, varargs, overload resolution, exception types, getter/setter ↔ property, package collisions, type stubs (`from ghidra.ghidra_builtins import *` under `TYPE_CHECKING`). Load when JPype errors show up or you're doing anything beyond simple `for x in it:` iteration.
+
+- **[references/recipes.md](references/recipes.md)** — Copy-pasteable inline `code` snippets covering the well-trodden paths: function iteration with predicates, xrefs to a symbol with caller context, batch rename by regex, thunks-aware callers of an import, decompile-and-grep, string dump with referencers, call-graph walk, plate/EOL annotations, raw byte reads — plus the heavier patterns: define a struct and apply it to memory, set a function signature with proper storage, trace argN back through Varnode def-use chains, register touches per function, `ParallelDecompiler` batch decompilation, `EmulatorHelper` for string deobfuscation, recursive xref-walking, and persisting a decompiler-derived rename via `HighFunctionDBUtil`. Load when the user asks "how do I do X" and X is a well-trodden path.
+
+- **[references/persistent-scripts.md](references/persistent-scripts.md)** — Conventions for saved scripts: naming, where files land, GhidraScript headers (`# @category`, `# @runtime`), how to discover existing scripts before duplicating, the typical edit cycle. Load when the user wants to save / reuse / iterate on a script rather than one-shot it.
+
+## Working style
+
+A few things that keep PyGhidra-via-ReVa pleasant:
+
+- **Prefer dedicated ReVa tools first.** `run-script` is powerful but free-form; the structured tools (decompiler, functions, strings, xrefs, …) have schemas the assistant can reason about more reliably. Reach for `run-script` only when the structured tools don't cover the question.
+- **Print structured output.** When a `run-script` result is going to be re-consumed by an LLM, prefer JSON or fixed columns over prose. The 64K cap is per-stream — design for it.
+- **Keep transactions narrow.** Open one per logical edit, not one wrapping the whole script. Smaller transactions undo cleanly in Ghidra's history and survive errors better.
+- **Iterate with `edit-script`, not `write-script`.** Once a saved script exists, targeted edits produce reviewable diffs; full overwrites don't.
+- **Read before you edit.** `read-script` first to see the current state and pick `old_string` slices that are unique. Editing blind almost always picks too-short a slice and either misses or hits multiple lines.