rea-argonaut · git:20261017.454d344 · 2026-10-17 · sha256 b3b08c4c9030baf2

rea-argonaut git:20261017.454d344A

Immutable. This exact content never changes and is served at /api/v1/blob/b3b08c4c9030baf2.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_qfq4sy3jounqhmzk/b3b08c4c9030baf298751db75c7eb90355ac45c4f857a3b25c510b7f7d7b444d.json

Then /plugin install rea-argonaut@markdownregistry-qfq4sy3jounqhmzk in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: rea-argonaut
description: "Zero-G Reverse Engineering Anything & Verified Rust Reconstruction for Gemini 4 Argon and Google Antigravity 2.0. Use whenever reverse-engineering native binaries (ELF/Mach-O/PE), stripped Rust/C++, frozen Python/PyInstaller, AI models (GGUF/SafeTensors/ONNX/TFLite), game engines (Unity IL2CPP/Godot .pck/Electron .asar), .NET, Go, Flutter, WebAssembly, EVM contracts, Electron/JS, Android APKs, firmware, network captures, or porting C/C++ subsystems to verified safe Rust."
---

# REA-Argonaut (`ArgonZeroG` Engine)

`REA-Argonaut` is the Zero-G reverse-engineering and verified reconstruction engine built for **Gemini 4 Argon** and **Google Antigravity 2.0**. It exposes **194 MCP tools** across **39 forensic domains** (`187` original REA tools + `7` `ArgonZeroG` engines) with unthrottled whole-subgraph extraction (`detail: "full"` by default), 2-tier cross-platform native resilience (Linux, macOS, Windows), a 4-subagent Hub-and-Spoke Super-Swarm, and closed-loop property-based C-to-Rust parity verification.

## The 5 Core `ArgonZeroG` Operational Laws

### Law 1 — Whole-Subsystem Subgraph Caching Over Micro-Paging (`decompile_subgraph`)
- **Never page 50 lines at a time.** Legacy 4K-context truncation (`detail: "summary"`, `max_lines: 50`) destroys cross-procedural type and invariant recovery and causes 18+ sequential MCP round-trips.
- Always open the target and ingest the connected call subgraph in one turn so the entire subsystem resides in the Gemini 4 Argon prompt context cache:
  1. `open_binary({ path: "/abs/path/to/binary", provider_id: "auto" })` *(note: `provider: "auto"` is also accepted as an alias for `provider_id`)*
  2. `binary_overview({})` and `list_procedures({})` *(automatically seeds recovered C++ Itanium/MSVC RTTI virtual methods as `ClassName__vslot_N_<addr>` across stripped binaries)*
  3. `decompile_subgraph({ procedure: "<symbol_or_hex>", max_depth: 3, max_nodes: 50, traversal: "bfs", include_assembly: true })` *(note: `entry` is also accepted as an alias for `procedure`, and seeded `ClassName__vslot_N_<addr>` symbols can be targeted directly)*
- `decompile_subgraph` returns full decompiled pseudocode, disassembled instruction lines, callers, callees, cycle edges (`cycle_edges`), aggregated strings (`aggregated_strings`), recovered struct field displacements (`inferred_struct_offsets`), and pre-extracted C/C++-to-Safe-Rust porting invariants (`latent_hazards`, `total_latent_hazards`) for every procedure in the subgraph in a single round-trip.

### Law 2 — 2-Tier Native Resilience (`provider_id: "auto"`)
- `REA-Argonaut` operates across **Linux (`ELF`)**, **macOS (`Mach-O` thin & Universal)**, and **Windows (`PE/COFF` PE32/PE32+)** without brittle single-tool dependencies:
  - **Tier 1 (`ghidra` / `hopper` / `ida`)**: Full symbolic decompilation, P-Code value-flow graphs (`trace_native_values`), and HighFunction `PTRSUB`/`PTRADD` struct offset recovery when a Tier-1 provider is configured via `GHIDRA_INSTALL_DIR` (or alias `REA_GHIDRA_HOME`) and `JAVA_HOME` (supports Ghidra `11.x` and `12.x`, verified on `12.1.4`).
  - **Tier 2 (`zero-install` / `ZeroInstallNativeProvider`)**: Automatic fallback when Ghidra/Hopper/IDA are absent. Combines pure-TypeScript ELF/Mach-O/PE container parsers with host OS binutils (`objdump`, `llvm-objdump`, `aarch64-linux-gnu-objdump`, `readelf`, `nm`, `otool -tV`, `dumpbin`), a built-in `x86`/`x86_64`/`ARM64` (`AArch64`) instruction decoder, `.plt` $\to$ `.rela.plt` $\to$ `.dynsym` call-graph resolution, and an Android Bionic `APS2` (`SHT_ANDROID_RELA`) SLEB128 relocation unpacker for `.got` global symbol tracking. Automatically recovers stripped-binary procedure boundaries (`sub_<hex>`) from entrypoints, `CALL`/`BL` targets, `endbr64`/`push rbp`/`stp x29, x30` prologues, and cross-vertical C++ RTTI/VTable virtual method slots (`ClassName__vslot_N_<addr>`).
  - **Format-Specific Layout, Resource & Crash Routing**:
    - **ELF Binaries & SONAME Symlinks**: Use `inspect_binary_layout({ path })` (resolves symlinks such as `/lib/x86_64-linux-gnu/liblz4.so.1` via `os.path.realpath`) and `inspect_recorded_crash({ path })` (`ET_CORE`).
    - **Windows PE Binaries (`.exe`, `.dll`, `.sys`)**: Use `inspect_rust_cpp_binary({ path })`, `inspect_pe_resources({ path })`, and `open_binary` + `binary_overview` (do not pass PE binaries to the ELF-specific `inspect_binary_layout` tool).
    - **macOS Mach-O Binaries**: Use `inspect_binary_layout({ path })`, `inspect_rust_cpp_binary({ path })`, and `open_binary` + `binary_overview`.

### Law 3 — Specialized Forensic Verticals First
- Before brute-force disassembling a stripped binary, container, or runtime bundle, run `export_recon_kit` or the dedicated `ArgonZeroG` forensic vertical to recover high-level structure:
  - **Universal 4-Mount Recon Kit (`export_recon_kit`)**: Materializes `RECON_BLUEPRINT.md` and the 4-Mount `recon-kit/` workspace directory across native binaries, packaged UI/game archives, hardware/firmware/protocol captures, and AI model/data artifacts (`mock_ui_concepts: false` by default).
  - **Stripped Rust & C++ (`inspect_rust_cpp_binary`)**: Extracts Rust compiler version, cargo registry crate versions (`rust.crates`), `.rela.dyn` `core::panicking::Location` source file/line trees (`rust.panic_locations`), demangled v0 (`_RNv`) / legacy (`_ZN`) symbols, and C++ Itanium (`_ZTV`, `_ZTI`, `_ZTS`) & MSVC (`RTTICompleteObjectLocator`, `RTTIClassHierarchyDescriptor`, `vftable`) class hierarchies (`cpp.classes`).
  - **Frozen Python (`inspect_python_frozen_binary`)**: Unpacks PyInstaller `MEI\x0c\x0b\x0a\x0b\x0e` CArchive cookies, TOC entries (`toc_entries`, capped via `max_toc_entries` or alias `max_entries`), `PYZ-00.pyz` headers (`pyz_header`), entrypoint scripts (`entry_scripts`), and Python `3.8`–`3.14` `.pyc` marshaled code objects (`code_objects`).
  - **AI Model & Prompt Forensics (`inspect_ai_model_artifact`)**: Streams `.gguf` (v1–v3), `.safetensors`, `.onnx`, and `.tflite` headers in `< 50 ms` without loading multi-GB weights into RAM (`header_bytes_read` << `size_bytes`), extracting hyperparameters, tensor layouts, embedded Jinja `tokenizer.chat_template` / system prompts (`extracted_prompts`), and pickle-free `security_audit` checks.
  - **Game Engine & Application Archives (`inspect_engine_archive`)**: Parses **all 3** archive formats in pure TypeScript (with `max_files` or alias `max_entries`):
    1. **Unity `IL2CPP` `global-metadata.dat` (`0xFAB11BAF` v24–v31)**: Recovers C# namespaces, types, methods (`il2cpp.types`, `il2cpp.methods`), and string literals (`il2cpp.string_literals`).
    2. **Godot Engine `.pck` (`GDPC` `0x43504447` v1–v3)**: Enumerates bundled `res://` scenes, `.gd`/`.gdc` scripts, offsets, and MD5 hashes (`godot_pck.files`).
    3. **Electron `.asar` Chromium Pickle Archives**: Streams the Pickle JSON header tree (`asar.files`), extracts `main_entry_script` from embedded `package.json`, and flags native `.node` addons (`asar.native_addons`).
  - **All 35 Classic REA Verticals**: `.NET` CIL (`inspect_managed_artifact`), Go `gopclntab` (`inspect_go_binary`), Dart/Flutter AOT, WebAssembly (`inspect_wasm_artifact`), EVM bytecode (`inspect_evm_interface`), Hermes/QuickJS/V8 bytecode (`analyze_javascript_application`), Android APK/DEX (`inspect_android_package`), Java/Kotlin `.class`/`.jar`, iOS `.ipa`, macOS `.app`, Windows MSI/Registry/Minidump, Firmware/UF2/DeviceTree (`inspect_firmware_regions`, `extract_firmware`), PCAP (`inspect_packet_capture`, `inspect_web_network_capture`), Sigrok logic captures (`decode_signal_recording`), SQLite (`inspect_sqlite_database`), and generic containers (`inspect_artifact`).

### Law 4 — Hub-and-Spoke Super-Swarm Orchestration Playbook
When analyzing multi-subsystem binaries, multi-artifact bundles, or porting C/C++ subsystems to verified Safe Rust, orchestrate the **4 Bundled Antigravity 2.0 Swarm Subagents** (`plugins/rea-argonaut/agents/*.md`) in a **Hub-and-Spoke** topology:

1. **The 4 Domain-Locked Specialist Subagents**:
   - **`subgraph-architect`**: Stage 1 Native Subgraph, Algorithm, Struct Layout & Safe Rust Porting Invariant Mapper (`open_binary`, `binary_overview`, `list_procedures`, `inspect_rust_cpp_binary`, `decompile_subgraph`).
   - **`forensic-vertical-specialist`**: Multi-Vertical Binary, Game Engine Archive, Frozen Python & AI Model Forensic Specialist (`export_recon_kit`, `inspect_rust_cpp_binary`, `inspect_python_frozen_binary`, `inspect_ai_model_artifact`, `inspect_engine_archive`, `inspect_binary_layout`, `inspect_pe_resources`).
   - **`safe-rust-reconstructor`**: Stage 2 `#![forbid(unsafe_code)]` Safe Rust Reconstruction Engineer (synthesizes idiomatic, zero-unsafe Rust that satisfies every Stage 1 porting invariant while preserving bit-exact C ABI/arithmetic semantics).
   - **`adversarial-parity-auditor`**: Stage 3 & 4 Closed-Loop Differential Fuzzer & Executive Scorecard Auditor (`verify_rust_parity` with `10,000+` SplitMix64 + boundary cases, coordinate-wise binary-search counterexample shrinking, C-vs-Rust micro-benchmarking, and opt-in `html_report_path` / Markdown scorecard generation).
2. **Parallel Discovery vs. Serialized Build/Fuzz Coordination**:
   - **Phase A — Parallel Read-Only Discovery**: Dispatch `subgraph-architect` and `forensic-vertical-specialist` in parallel across disjoint subsystems or binary artifacts. Because `decompile_subgraph` and vertical inspectors are read-only, multiple subagents can map separate call subgraphs simultaneously without lock contention.
   - **Phase B — Parallel File-Fenced Reconstruction**: Assign each subsystem module to a `safe-rust-reconstructor` subagent with a strict directory/file fence. Subagents perform file reads and file edits only inside their assigned module fence.
   - **Phase C — Serialized `verify_rust_parity` & Self-Healing Loop**: Dispatch `adversarial-parity-auditor` to run `verify_rust_parity` one subsystem at a time so CPU-bound `rustc -C opt-level=3` compilation and 100,000-iteration micro-benchmarks never contend for CPU cores. If `status === "diverged"`, route `counterexample.shrunk_inputs` and `bit_diff_summary` back to `safe-rust-reconstructor` until `status === "verified_bit_exact"`.
3. **Hardware-Adaptive Resource Scaling (Zero Hardware Assumptions)**:
   - Never hardcode core counts, thread pool sizes, or machine-specific paths. All parallel workers scale dynamically at runtime via `os.availableParallelism()` and `os.totalmem()` in Node.js (`AdaptiveResourceProfile.ts`) and `std::thread::available_parallelism()` in Rust.

### Law 5 — Closed-Loop Mathematical Verification (`verify_rust_parity`)
- **Never claim a C/C++-to-Rust reconstruction is equivalent by visual inspection alone.**
- After synthesizing safe Rust from a decompiled native procedure or subgraph, invoke `verify_rust_parity`:
  - **Input Contract**: `symbol_name`, `rust_fn_name` (optional, defaults to `symbol_name`), `rust_source_code`, `target_binary_path` (or `c_source_code`), `arg_types` (`1..8` parameters of `"i8" | "u8" | "i16" | "u16" | "i32" | "u32" | "i64" | "u64" | "f32" | "f64" | "f32_finite" | "f64_finite" | "bool" | "bytes"`, where `"bytes"` bridges `(*const u8, usize)` in C ABI $\leftrightarrow$ `&[u8]` in Safe Rust, and `"f32_finite"` / `"f64_finite"` generate 100% finite IEEE-754 floats for DSP/sensor filters), `return_type`, `iterations` (default `10000`), `seed` (default `1337420`), `float_ulp_tolerance` (default `0`, with built-in canonical IEEE-754 `NaN` and `±0.0` equivalence), `forbid_unsafe` (default `true`), optional `scaffold_output_dir` (automatically scaffolds a **100% pure `#![forbid(unsafe_code)]` Rust Cargo crate** — `Cargo.toml`, `src/lib.rs`, `tests/parity_regression.rs` — with zero HTML clutter by default), and optional `html_report_path` (`--html-report <path>`, an explicit opt-in flag that writes an Antigravity `generative_ui`-compliant HTML parity report when `status === "verified_bit_exact"`).
  - **Sandboxed Execution & PIE Patching**: Automatically strips ELF `DF_1_PIE` (`0x08000000` in `DT_FLAGS_1`), patches Mach-O `MH_EXECUTE -> MH_DYLIB`, or sets PE `IMAGE_FILE_DLL` on a temporary workspace copy so `dlopen()` / `LoadLibrary` can load both shared libraries and PIE executables inside an OS sandbox (`linux-bwrap+prlimit`, `linux-prlimit`, `darwin-sandbox-exec`, `win32-job-object`).
  - **Output Telemetry**:
    - `status`: `"verified_bit_exact" | "diverged" | "sandbox_fault" | "compile_error"`
    - `memory_safety`: `{ forbid_unsafe_enforced: true, candidate_unsafe_blocks: 0 }`
    - `benchmark_telemetry`: `{ benchmark_iterations: 100000, c_oracle_total_ns, safe_rust_total_ns, c_oracle_ns_per_call, safe_rust_ns_per_call, speedup_vs_c_oracle }`
    - `counterexample`: `{ failing_iteration, original_inputs, shrunk_inputs, shrink_steps, c_output, rust_output, c_output_hex, rust_output_hex, bit_diff_summary, ulp_distance }`
    - `scaffolded_crate`: `{ output_dir, cargo_toml_path, lib_rs_path, regression_test_path, dashboard_html_path }` (when `scaffold_output_dir` is supplied; `dashboard_html_path` is populated only when opt-in `html_report_path` is provided)
  - If `status === "diverged"`, inspect `counterexample.shrunk_inputs`, `counterexample.c_output_hex`, `counterexample.rust_output_hex`, and `counterexample.bit_diff_summary`, patch the Rust code, and re-run `verify_rust_parity` until `status === "verified_bit_exact"`.

---

## The 4-Phase Recon-to-Argon Handoff Workflow (`export_recon_kit`)

When reverse-engineering complex native binaries, packaged UI archives, firmware images, or AI model bundles for architectural exploration, clean-room reconstruction, or security auditing, execute the **4-Phase Recon-to-Argon Handoff Workflow**:

- **Phase 1 — Materialize the 4-Mount Recon Kit (`export_recon_kit`):**
  Call `export_recon_kit({ path: "/abs/path/to/target" })` to automatically detect all applicable domain mounts (`Mount 1: native-binary`, `Mount 2: packaged-ui-archive`, `Mount 3: hardware-firmware-protocol`, `Mount 4: ai-model-data`) and materialize `RECON_BLUEPRINT.md` and the structured 4-Mount `recon-kit/` workspace directory (`0` unsolicited `.html` files by default; `mock_ui_concepts: false`).
- **Phase 2 — Native `ask_question` Harness Selection (& Opt-In UI Concept Mock):**
  Always use Antigravity's native `ask_question` tool (never generate HTML with clickable `<button>` / `onclick=` controls) so the user selects which subsystem and which of the **4 Harnesses** (`verified-safe-rust-port`, `clean-room-app-ui-rebuild`, `hardware-hal-protocol-replay`, `security-hazard-audit`) to execute. If Mount 2 UI assets were discovered, include an option in `ask_question` asking if the user wants to generate a visual `generative_ui` UI concept mock (`mock_ui_concepts: true`).
- **Phase 3 — Antigravity + Gemini 4 Argon Reconstruction:**
  Hand off to **Antigravity + Gemini 4 Argon** to build/recreate the selected library, application, UI, or hardware driver directly from `RECON_BLUEPRINT.md` and `recon-kit/` without re-running decompilers.
- **Phase 4 — Mathematical Referee Verification:**
  Run `verify_rust_parity` (scaffolds a clean `#![forbid(unsafe_code)]` Cargo crate by default via `scaffold_output_dir`, with `html_report_path` strictly opt-in) or CLI `argonaut verify-reconstruction` as the mathematical referee.

### Living Workspace Docs vs. Brain Artifacts & Native Decision Controls
- **Native Decision Controls (`ask_question`):** All subsystem and harness choices use Antigravity's native `ask_question` tool; never generate HTML with clickable `<button>` or `onclick=` controls.
- **Living Workspace Docs vs. Brain Artifacts:** `export_recon_kit` writes `RECON_BLUEPRINT.md` and `recon-kit/*.md` directly into the workspace `output_dir` as standard Markdown files (without `ArtifactMetadata`), whereas brain artifacts (`<appDataDir>/brain/<conversation-id>`) with `RequestFeedback: true` are reserved strictly for actionable step-by-step implementation plans, and opt-in `generative_ui` HTML mocks (`mock_ui_concepts: true` or `html_report_path`) set `UserFacing: true` and `RequestFeedback: false`.

---

## The 4-Stage Continuous Modernization Pipeline (C/C++ Binary to Verified Safe Rust)

### Stage 1 — Subgraph Architecture, Domain Model & Porting Invariants (`subgraph-architect`)
1. Open the binary session (`open_binary({ path, provider_id: "auto" })`) and extract the target subsystem in a single call with `decompile_subgraph`.
2. Catalog all pre-extracted **C/C++-to-Safe-Rust Porting Invariants** (`latent_hazards` / `total_latent_hazards`) across every procedure in the subgraph:
   - `potential_integer_overflow_to_pointer` — 32-bit index/stride arithmetic (`imul`/`mul`/`madd`/`shl`) widened into a 64-bit pointer offset (`movsxd`/`sxtw`); translate to `usize`/`i64` with `checked_mul` or wrapping semantics in Safe Rust.
   - `unchecked_division` — hardware `div`/`idiv`/`udiv`/`sdiv`/`fdiv` without an adjacent zero-divisor guard; translate to `checked_div` or explicit domain guard in Safe Rust.
   - `thread_hostile_mutable_global` — reads/writes to `.bss`/`.data`/`.got` static state; encapsulate into an explicit owned Rust context struct or `Mutex`/`Atomic` for thread-safe reentrancy.
   - `unsafe_memory_sink` — calls to legacy C buffer routines (`strcpy`, `strcat`, `sprintf`, `gets`, `scanf`, `system`); replace with bounds-checked Rust slices and `String` formatting.
   - `uninitialized_or_stack_hazard` — large stack frame allocations (`>= 4096` bytes); replace with heap-allocated `Vec` or bounded buffers.
3. Combine `inferred_struct_offsets`, `aggregated_strings`, and control-flow topology to synthesize the clean mathematical or physical **Domain Model** before writing Rust code.

### Stage 2 — `#![forbid(unsafe_code)]` Safe Rust Port (`safe-rust-reconstructor`)
1. Implement the reconstructed subsystem in modular Safe Rust (`#![forbid(unsafe_code)]`, `candidate_unsafe_blocks === 0`, `<= 400 LOC` per file, `0` warnings under `cargo clippy --all-targets -- -D warnings`).
2. Replace every cataloged `latent_hazard` with compile-time or checked Rust guarantees (checked/wrapping integer math, slice bounds, thread-safe value state instead of mutable globals, `Result`/`Option` error propagation).
3. Inline hot helper functions (`#[inline(always)]`) and structure hot loops for LLVM autovectorization (`-C opt-level=3 -C codegen-units=1`).

### Stage 3 — Closed-Loop `verify_rust_parity` Crucible (`adversarial-parity-auditor`)
1. Run `verify_rust_parity` with `forbid_unsafe: true` and `iterations: 10000` (or higher).
2. If any SplitMix64 or boundary seed diverges, use the shrunk counterexample (`counterexample.shrunk_inputs` and `bit_diff_summary`) to self-heal the Rust implementation in a closed loop until `status === "verified_bit_exact"`.
3. Record both **`memory_safety`** (`forbid_unsafe_enforced: true`, `candidate_unsafe_blocks: 0`) and **`benchmark_telemetry`** (`c_oracle_ns_per_call`, `safe_rust_ns_per_call`, `speedup_vs_c_oracle`).

### Stage 4 — Verification Scorecard & Opt-In Interactive HTML Dashboard
1. Present the completed modernization summary in Markdown (and, when explicitly opted-in via `html_report_path` / `--html-report`, generate an interactive `generative_ui` HTML scorecard with `UserFacing: true`, `RequestFeedback: false`) that reports:
   - **Headline KPIs:** Native Speedup (`speedup_vs_c_oracle`), `0 Unsafe` (`#![forbid(unsafe_code)]`), `100.0%` Bit-Exact Output Parity across `10,064` FFI test vectors, and MCP Round-Trip Collapse (`18 -> 1`, `-94.4%`).
   - **Eliminated Hazard Matrix:** Side-by-side mapping of each Stage 1 `latent_hazard` address/procedure to the Stage 2 Safe Rust remediation and Stage 3 verification proof.

---

## Reference Guides
- [Whole-Subgraph Extraction & Context Caching Guide](references/subgraph-caching.md) — `decompile_subgraph` parameters, `inferred_struct_offsets`, `latent_hazards`, and single-turn KV-cache optimization.
- [Specialized Forensic Verticals Guide](references/niche-verticals-guide.md) — Deep-dive schemas and workflows for `inspect_rust_cpp_binary`, `inspect_python_frozen_binary`, `inspect_ai_model_artifact`, and `inspect_engine_archive`.
- [Hub-and-Spoke Super-Swarm Orchestration Guide](references/swarm-orchestration.md) — Coordinating `subgraph-architect`, `safe-rust-reconstructor`, `forensic-vertical-specialist`, and `adversarial-parity-auditor`.
- [Closed-Loop Rust Parity Verification Guide](references/rust-parity-verification.md) — `verify_rust_parity` FFI harness, ELF `DF_1_PIE` / Mach-O / PE patching, counterexample shrinker, and OS sandboxing.
- [ArgonZeroG Step-by-Step Playbooks](references/argon-zerog-workflow.md) — Copy-pasteable JSON tool call sequences across all 4 flagship workflows.
- [39-Domain Vertical Routing Matrix](references/vertical-routing-matrix.md) — Complete lookup table mapping file extensions and magic bytes to primary and secondary MCP tools and CLI commands.