OpenMaidEngine/docs/superpowers/specs/2026-07-07-ghidra-mcp-native-re-design.md

Ghidra + MCP native-RE workflow (proven on u00428010) — design

Date: 2026-07-07 Status: approved (brainstorming) → ready for implementation plan Slice: native-engine RE enablement; first target = SCJUMP's decision→scene resolver.

---

1. Problem & goal

We keep hitting the same wall: logic compiled into AGE.EXE that scripts call as native ops — decision→scene (u00428010), call-script dispatch, op 0x60 (the rand-like SCJUMP gate), the gfx command-buffer. Frida (dynamic observation) has taken us far but stalls where the native logic is a complex state machine that must be read, not just watched. The blocker that previously ruled out static analysis (packed exe) is gone — we have the in-place-unpacked engine dumped (build/engine-dump/, module @0x400000, validated at the AGF landmark 0x474f1f).

Goal: stand up a repeatable "Claude drives Ghidra over MCP" loop and prove it end-to-end on one native function — u00428010, the SCJUMP decision→scene resolver — to a concrete result: either recover the 0x62ccf → SCxxxx.BIN mapping (finishing the SCJUMP slice), or establish precisely what makes it runtime-only. Success de-risks the whole approach and leaves a documented, reusable process for the other native walls.

2. Non-goals (this slice)

• Not reversing call-script dispatch, op 0x60, or the gfx command-buffer — those are follow-on slices that reuse the proven loop. One target only.
• Not building custom RE tooling — we use an off-the-shelf Ghidra MCP server; we don't write our own bridge.
• No redistribution of engine binaries — the dump/PE stay local, for analysis only.
• Not committing to reimplementing u00428010 in the VM this slice; the deliverable is the understanding (the mapping/table or a clear runtime verdict). Reimplementation is a later step.

3. Environment (confirmed 2026-07-07)

• Have: Ghidra 12.1.2 installed; the game runs locally (JP locale); Frida 17.15.3; build/engine-dump/ (raw runtime dump: manifest.json + range_<base>.bin, module base 0x400000).
• Need (this slice sets up): the bethington/ghidra-mcp server (plugin + bridge) registered in Claude Code; possibly pe-sieve.exe (only if raw-dump analysis is inadequate).
• Target facts: consumers do lookup-array(ptr, 0x5f0ed, 0x62ccf) then u00428010(ptr). Kelebek names the op by its handler VA 0x428010 (may drift in our build → resolve via the dispatch table [esi+idx*120+0x53d88] / proximity). The interpreter executes from the module @0x400000 (stable base) — not the per-run heap (an earlier worry, since corrected).

4. The MCP server — bethington/ghidra-mcp

Chosen over LaurieWired/GhidraMCP because it explicitly exposes the primitives this analysis needs: decompile_function, get_xrefs_to/get_xrefs_from, get_function_by_address, read_memory, list_data_items, search_byte_patterns, struct/enum tools. Actively maintained (v5.14.2, Jun 2026), stdio-MCP transport designed for Claude Code. Requires Ghidra 12.1.2 (matches ours); prereqs Java 21, Maven 3.9+, Python 3.10+. The 256-tool surface is a non-issue for Claude Code — tools are deferred/ searchable, so only the handful used are loaded via ToolSearch.

Setup (user, one-time): build + deploy the Ghidra extension (python -m tools.setup ...), start the HTTP-serving plugin inside Ghidra (127.0.0.1:8089), run the MCP bridge, and register the server in Claude Code's MCP config. A connectivity check (I call list_functions and get a non-empty result) gates progress to analysis.

Fallback: if the bridge proves painful, I can still work from decompiler output the user pastes, or a Ghidra headless export — degraded (no automated xrefs) but not blocked.

5. Analyzable image — raw-dump-first, pe-sieve as escalation

For reading one function's logic, a perfect IAT is often unnecessary (unnamed API calls are fine when the function is a table lookup). So:

1. Stage A — try the existing raw dump (build/engine-dump/range_<0x400000>.bin), imported into Ghidra as a raw 32-bit x86 binary at base 0x400000, auto-analyzed. Zero new setup. If the decompiler renders u00428010's region legibly, prep is done.
2. Stage B — escalate to pe-sieve only if Stage A is inadequate: with the game running, pe-sieve.exe /pid <PID> /imp 3 rebuilds the IAT into a clean PE (recorded in vm-mapping-plan.md appendix; pe-sieve is a single portable exe, Bash-drivable while the user has the game up). Validate the dump by confirming plaintext SYS4422/.BIN/DATA1 strings appear.

The escalation is triggered by observation (illegible/incomplete decompilation), not assumed up front.

6. Ghidra load parameters

32-bit x86 (x86:LE:32:default), image base 0x400000. For the raw dump: import as "Raw Binary", set the language + base, run auto-analysis (decompiler, function ID, data references). For a pe-sieve PE: standard PE import. Confirm the AGF landmark (VA 0x474f1f contains the BM/0x4D42 check) reads as real code — the recorded dump-sanity anchor.

7. Analysis plan for u00428010

Driven by me over MCP:

1. Locate the real handler. Try get_function_by_address(0x428010); if it lands mid-function or on non-handler code (Kelebek build drift), find it via the interpreter's op dispatch table ([esi+idx*120+0x53d88]) or by xrefs from the operand-fetch path (call 0x41b940).
2. Decompile it and read how it consumes its pointer argument (the &0x5f0ed[decision] reference) — what fields it reads, what it returns, what it calls.
3. Chase the data. Follow xrefs/reads to any static table in .data: does the decision index map, directly or via 0x5f0ed, to a scene id / filename / SYS4INI section? list_data_items + read_memory on the referenced table; cross-check candidate scene ids against the real corpus (SC#### filenames) and build/asset-sections.json.
4. Verdict. Either (a) recover the decision → scene mapping (ideally a static table we can export → a static win finishing SCJUMP), or (b) determine it's computed at runtime (e.g. from live state the table doesn't encode) and document exactly what's needed to resolve it (a Frida hook point).

Success criterion: a concrete, evidence-backed answer to "what scene does decision N load?", or a precise statement of why it can't be answered statically + the identified runtime hook.

8. Findings capture

• New canonical doc docs/engine-re.md — "native-engine reverse engineering": the home for decompiled native-op findings. This slice writes the u00428010 section (handler address, decompiled behavior, the 0x5f0ed/table structure, the decision→scene verdict). Future native walls (call-script, op 0x60, gfx buffer) get sections here. Includes a short "how to run the Ghidra+MCP loop" runbook (setup + connect) so it's repeatable.
• vm-map/opcodes.toml — if u00428010 (and any native op identified along the way) gets real semantics, record them there (its existing home); rebuild via opcodes_build.py --build.
• docs/scjump-progression.md — update the "native decision→scene boundary" section with the result (mapping recovered, or the precise runtime dependency).
• CLAUDE.md canonical-documents map — add a row: Native-engine RE (decompiled AGE.EXE) → docs/engine-re.md.
• If pe-sieve is used, note the dump-prep recipe in docs/engine-re.md (and reference the existing vm-mapping-plan.md appendix rather than duplicating).

9. Risks & fallbacks

• MCP setup friction / version mismatch → fallback to pasted decompiler output or headless export (degraded, not blocked). A connectivity gate (§4) catches this before analysis.
• Anti-debug / protector → attach post-title (already works for our Frida dump); pe-sieve is a read-only scan (low risk). Not expected to affect Ghidra static analysis of an already-captured image.
• VA drift (Kelebek build ≠ ours) → resolve the handler via the dispatch table, not the raw VA.
• The answer is genuinely runtime → that is still a successful outcome for this slice: it validates the workflow and pinpoints the exact Frida hook, converting an open wall into a defined task.

10. Definition of done

1. bethington/ghidra-mcp connected in Claude Code; I can list_functions / decompile_function on the loaded engine image.
2. u00428010 located and decompiled; its use of 0x5f0ed and any static table understood.
3. A verdict on decision→scene: recovered mapping (with evidence) or a precise runtime-hook statement.
4. docs/engine-re.md written (findings + repeatable runbook); scjump-progression.md and (if applicable) opcodes.toml + CLAUDE.md updated; status memory updated.

11. Implementation order (for the plan)

1. Set up bethington/ghidra-mcp (user) + register in Claude Code; connectivity gate.
2. Load the raw engine dump in Ghidra (32-bit, base 0x400000); confirm the AGF landmark; assess decomp quality. Escalate to pe-sieve /imp 3 only if inadequate.
3. Locate + decompile u00428010; chase 0x5f0ed + referenced tables; reach the decision→scene verdict.
4. Write docs/engine-re.md (findings + runbook); update scjump-progression.md, opcodes.toml (if applicable), CLAUDE.md map, status memory.