rea-agents 1.7.0 → 2.1.0

package/README.md

@@ -10,11 +10,11 @@
 
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
-[![78 MCP tools](https://img.shields.io/badge/MCP_tools-78-5c4ee5?style=flat-square)](#78-tools-for-investigation)
+[![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](#tool-catalog-for-investigation)
 [![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 
-[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [78 tools](#78-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
+[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [Tool catalog](#tool-catalog-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
 
 <br />
 
@@ -30,7 +30,7 @@
 
 See a feature in an app that you want in your own product? Give the app to your agent—even without its source code. With REA, the agent can investigate the feature, explain how it works, show its evidence, and build a version adapted to your stack and requirements.
 
-REA gives agents one consistent way to investigate software. Today that includes deep native analysis and function dossiers through Hopper or bring-your-own Ghidra on Linux, reproducible Evidence v2 records, controlled process capture, passive website and Electron observation, bounded JavaScript/source-map reconstruction, and a versioned domain graph for connecting JavaScript application layers without confusing static inference with runtime observation. The longer-term toolkit extends the same agent workflow to APIs, protocols, mobile artifacts, firmware, richer runtime behavior, and differences between versions.
+REA gives agents one consistent way to investigate software. Today that includes deep native analysis and function dossiers through Hopper or bring-your-own Ghidra on Linux, plus an experimental Windows x64 Ghidra P0 for approved native PE applications; execution-free managed PE/CLI triage; reproducible Evidence v2 records; controlled process capture; passive website and Electron observation; bounded JavaScript/source-map reconstruction; and a versioned domain graph for connecting JavaScript application layers without confusing static inference with runtime observation. The longer-term toolkit extends the same agent workflow to APIs, protocols, mobile artifacts, firmware, richer runtime behavior, and differences between versions.
 
 Reverse engineering normally makes the operator choose a tool, learn its API, move evidence between programs, and decide what to inspect next. REA gives that work to the agent through commands, skills, structured results, and repeatable investigation workflows.
 
@@ -85,17 +85,41 @@ REA shows how it reached its conclusions. It does not claim to recover original
 
 ## Quick start
 
-### Install the CLI — recommended
+### Run setup — recommended
 
 ```bash
-npm install --global rea-agents
-rea setup
+npx rea-agents setup
 ```
 
-Installing the CLI does not update Homebrew, Node.js, npm, Hopper, or agent configuration. `rea setup` detects what is already present, prints every proposed change, and asks before applying it.
+The npm package-runner prompt, when shown, approves downloading REA for this
+invocation; it does not approve any setup changes. The REA wizard separately
+shows its complete plan and asks before applying it. Setup does not update
+Homebrew, Node.js, or npm. `npx rea-agents setup` opens with the work it
+enables: investigate local apps from an agent, recover evidence through a
+deep-analysis provider, and reuse REA's guided workflow. It summarizes the
+detected agents, then asks which independent capabilities to set up: coding-agent
+access through MCP, the shared investigation skill, and—when needed—the Hopper
+provider. Nothing is preselected. Choosing MCP access opens a second empty
+checklist for the specific detected agents that should receive a registration.
+
+REA keeps the journey inline so its history remains in the terminal. Selecting
+a capability does not select every detected target or authorize a change.
+Before anything changes, REA validates existing configuration, prints exact
+paths and external effects, and asks for final approval with **No** as the
+default. The screen keeps the available keys visible while you choose; Ctrl-C
+and declining leave the system unchanged.
 
 REA detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, and Devin. It configures the first six when detected; Devin is reported but left unchanged because it has no documented local MCP configuration boundary. Registrations are additive, backup-first, and read back after writing. You can safely rerun setup.
 
+Use `rea setup --dry-run` to inspect the plan, repeat `--client` to select exact
+agents, and `--accessible` for sequential vertical prompts. Machine output
+remains available through `--json`; prompt UI and progress go to stderr.
+
+After a successful setup, REA reports the capabilities now ready to use and a
+concrete next step, such as restarting a configured agent before asking it to
+investigate an application. It does not claim an integration or provider is
+ready unless setup and its final diagnostic check verified it.
+
 An optional curl wrapper installs the same CLI package and starts setup only when a terminal is available:
 
 ```bash
@@ -117,9 +141,9 @@ Review the setup plan, approve it if appropriate, then describe the app or featu
 ### From Terminal — no installation
 
 ```bash
-npx -y rea-agents setup
-npx -y rea-agents doctor
-npx -y rea-agents analyze /Applications/Notes.app
+npx rea-agents setup
+npx -y rea-agents@latest doctor
+npx -y rea-agents@latest analyze /Applications/Notes.app
 ```
 
 Review the setup plan before confirming it. Restart a configured agent so it loads REA.
@@ -146,10 +170,16 @@ an unrelated global package.
 
 Choose either the no-install commands or the global installation. You do not need both.
 
+`npm install rea-agents` without `--global` installs `rea` only into the
+current project's `node_modules/.bin`; it does not add `rea` to your shell
+`PATH`. Use the `npx` commands above for one-off runs or `--global` when you
+want a shell-visible `rea` command.
+
 ### Requirements
 
 - macOS 12 or newer
 - Ubuntu 24.04+, Fedora 41+, or 64-bit Arch Linux
+- Windows x64 for the experimental, Ghidra-only native PE P0 boundary
 - Node.js 22.19+ or 24.11+ (including newer releases)
 - npm; REA does not require or install a particular npm version
 
@@ -158,7 +188,7 @@ Deep binary operations use [Hopper](https://www.hopperapp.com/), a separate desk
 If something is not working, run:
 
 ```bash
-npx -y rea-agents doctor
+npx -y rea-agents@latest doctor
 ```
 
 `rea doctor --json` is read-only and distinguishes unsupported hosts, missing dependencies, a missing local analysis engine, configuration drift, and healthy checks. Paid-license activation is optional: on Linux, REA runs the supported Hopper demo build on a private Xvfb display and selects Hopper's offered demo mode for each analysis session.
@@ -188,7 +218,7 @@ REA defaults `HOPPER_LAUNCHER_PATH` to `/Applications/Hopper Disassembler.app/Co
 
 ### Ghidra read-only analysis provider
 
-The current Ghidra adapter supports the exact official Ghidra 12.1.2 release on Linux x64 with a 64-bit full JDK 21. Download and extract those projects yourself, then configure absolute paths:
+The Ghidra adapter supports the exact official Ghidra 12.1.2 release with a 64-bit full JDK 21 on Linux x64. It also provides an experimental Windows x64 P0 limited to approved native x86-64 PE applications. Download and extract those projects yourself, then configure absolute paths:
 
 ```bash
 export GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.1.2_PUBLIC
@@ -200,7 +230,9 @@ rea providers --json
 
 Doctor distinguishes missing configuration, a bad installation root, the wrong Ghidra or Java version, a JRE without `javac`, a missing `support/analyzeHeadless`, and an unsupported platform or architecture. Approved setup only copies the verified non-secret paths into detected MCP registrations; it does not modify the Ghidra installation or install/download Ghidra or Java.
 
-REA loads its packaged Java `HeadlessScript` with `-scriptPath`, imports the target into a mode-0700 temporary project, enables `-readOnly` and `-deleteProject`, caps auto-analysis at 300 seconds with two CPUs and a 2 GiB Java heap, and authenticates every request over a mode-0600 Unix socket. It isolates Ghidra home/cache/config/temp paths and removes the owned project, socket, process group, and runtime root on close, cancellation, timeout, or process exit.
+On Windows, set the same variables in PowerShell and run `rea doctor --json`; automated `rea setup` and Hopper installation remain unavailable. The P0 target boundary rejects DLLs, managed PE files, non-x86-64 images, mutable/hostile inputs, and non-PE formats. See the [Windows Ghidra P0 operations guide](docs/windows-ghidra-p0.md) for registration, exact limitations, CI evidence, and acceptance gates.
+
+REA loads its packaged Java `HeadlessScript` with `-scriptPath`, copies and digest-verifies the target in an ephemeral runtime, enables `-readOnly` and `-deleteProject`, caps auto-analysis at 300 seconds with two CPUs and a 2 GiB Java heap, and authenticates every request. Linux uses a mode-0600 Unix socket. Windows P0 uses token-authenticated IPv4 loopback and a token-free endpoint record because Node path-based IPC does not connect to Java AF_UNIX sockets on Windows. The bridge verifies Ghidra's imported-byte SHA-256 before serving any operation.
 
 The Ghidra adapter declares 18 direct and enhanced operations. Its ten inventory operations are `list_documents`, `list_procedures`, `list_strings`, `list_names`, `list_segments`, `address_name`, `procedure_address`, `resolve_containing_procedure`, `search_procedures`, and `search_strings`. It also admits `procedure_info`, `procedure_pseudo_code`, `procedure_assembly`, `procedure_callers`, `procedure_callees`, `procedure_references`, `xrefs`, and `analyze_function`. These capabilities enable the shared Swift/Objective-C inventory workflows, `binary_overview`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, `trace_feature`, and complete function dossiers. Default-space addresses are lowercase `0x` hexadecimal. Other spaces, including `EXTERNAL`, use `<percent-encoded-space>:0x<hex>`. Symbol results identify primary, dynamic, external, type, and source facts; procedures distinguish external functions and thunks; strings identify charset, missing-terminator state, byte length, and value truncation; memory-block ends are exclusive and permissions come directly from Ghidra.
 
@@ -208,6 +240,8 @@ The bridge serves operations only after auto-analysis completes. Each Program ow
 
 `npm run verify:ghidra` compiles source-owned x86-64 debug and stripped ELF, AArch64 ELF, x86-64 PE, and x86-64 Mach-O fixtures. Against real Ghidra 12.1.2 it validates every admitted operation, direct and indirect calls, imports/exports/thunks, typed references, strings/xrefs, multi-block CFG, cancellation, deadlines, concurrency, malformed inputs, and complete process/project cleanup. Set `REA_CC`, `REA_CLANG`, or `REA_LLD_LINK` only when the corresponding compiler command is not on `PATH`.
 
+`npm run verify:ghidra:windows` uses a deterministic source-owned native x86-64 PE application and requires all 18 operations, target/snapshot/import digest linkage, authenticated loopback transport, and cleanup on a controlled Windows x64 Ghidra 12.1.2 runner. This proof does not establish Job Object ownership, private DACLs, or reparse-point-safe authority.
+
 To remove only REA-owned MCP registrations and the managed skill:
 
 ```bash
@@ -219,15 +253,16 @@ Uninstall preserves Hopper, Node.js, evidence, captures, external evidence roots
 
 ### CLI or agent?
 
-| If you want to…                                                 | Use                                                                       |
-| --------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| Ask an agent to investigate an app and build a feature          | Install the skill, then talk to your agent                                |
-| Inspect or decompile one part of an app from the Terminal       | `rea analyze` or `rea decompile`                                          |
-| Validate, canonicalize, or compare Evidence v2 bundles          | `rea evidence-import`, `rea evidence-export`, or `rea compare`            |
-| Run or resume a persistent two-version artifact analysis        | `rea investigate-versions`                                                |
-| Reuse immutable analysis results without relaunching a provider | Pass `--snapshot /approved/path/analysis.json` to a deep-analysis command |
-| Import source as historical reference                           | `rea import-reference-source`                                             |
-| Capture or compare controlled process behavior                  | `rea capture-process` or `rea compare-process-captures`                   |
+| If you want to…                                                  | Use                                                                       |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Ask an agent to investigate an app and build a feature           | Install the skill, then talk to your agent                                |
+| Inspect or decompile one part of an app from the Terminal        | `rea analyze` or `rea decompile`                                          |
+| Validate, canonicalize, or compare Evidence v2 bundles           | `rea evidence-import`, `rea evidence-export`, or `rea compare`            |
+| Run or resume a persistent two-version artifact analysis         | `rea investigate-versions`                                                |
+| Map a local JavaScript/Electron application without executing it | `rea analyze-javascript-application`                                      |
+| Reuse immutable analysis results without relaunching a provider  | Pass `--snapshot /approved/path/analysis.json` to a deep-analysis command |
+| Import source as historical reference                            | `rea import-reference-source`                                             |
+| Capture or compare controlled process behavior                   | `rea capture-process` or `rea compare-process-captures`                   |
 
 Filesystem evidence commands and MCP file tools are disabled until the operator approves absolute roots:
 
@@ -238,6 +273,7 @@ rea evidence-import /absolute/path/to/evidence/bundle.json
 rea evidence-export /absolute/path/to/evidence/bundle.json /absolute/path/to/evidence/canonical.json
 rea compare /absolute/path/to/evidence/left.json /absolute/path/to/evidence/right.json
 rea investigate-versions /absolute/path/to/releases/v1 /absolute/path/to/releases/v2 /absolute/path/to/evidence/releases.json --yes --workspace-name releases
+rea analyze-javascript-application /absolute/path/to/releases/app.asar --approved --json
 ```
 
 `investigate-versions` inventories both versions, checkpoints their observed
@@ -318,30 +354,39 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its
 - Analyze Swift and Objective-C metadata without manually untangling every mangled symbol.
 - Leave names, comments, and bookmarks in Hopper so human and agent analysis reinforce each other.
 
-## 78 tools for investigation
+## Tool catalog for investigation
 
-| Tool family               | Count | Examples                                                                                                                         |
-| ------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------- |
-| Native inspection         |    33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations                                 |
-| Investigation workflows   |    10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery          |
-| Native macOS utilities    |     5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing                    |
-| Artifact graph            |     2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree               |
-| Browser observation       |     8 | exact-origin CDP capture, bundle and source-map analysis, WebMCP discovery, session timelines, capture diff, and visual evidence |
-| Electron observation      |     2 | canonical-root-confined file-page discovery and passive DOM, resource, and optionally approved script-source inspection          |
-| Workspace and observation |    18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle          |
+| Tool family               | Count | Examples                                                                                                                                                                                                                                  |
+| ------------------------- | ----: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Native inspection         |    33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations                                                                                                                                          |
+| Investigation workflows   |    10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery                                                                                                                   |
+| Native macOS utilities    |     5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing                                                                                                                             |
+| Artifact graph            |     2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree                                                                                                                        |
+| Managed PE/CLI            |     8 | PE/CLI identity, metadata members, CIL hashes, P/Invoke/native-boundary declarations and verification, application-graph projection, decompiler reconstruction import, token remapping, runtime-correlation plans, and version comparison |
+| Browser observation       |     8 | exact-origin CDP capture, bundle and source-map analysis, WebMCP discovery, session timelines, capture diff, and visual evidence                                                                                                          |
+| Electron analysis         |     4 | passive root-confined observation, bounded static application mapping, and evidence-backed static/runtime reconciliation                                                                                                                  |
+| Application workflows     |     7 | bounded cross-layer traces, unique-only version matching, approved Linux-isolated extracted-module replay, managed-runtime characterization, and reconstruction coverage closure                                                          |
+| Workspace and observation |    18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle                                                                                                                   |
 
 The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness implements controlled behavioral capture.
 
 ## Current status
 
-REA is already useful for native application, browser, and Electron investigation on supported macOS and Linux hosts:
+REA is already useful for native application, browser, and Electron investigation on supported macOS and Linux hosts, plus the bounded Windows Ghidra P0 described above:
 
 - Open Mach-O, ELF, PE, `.app`, ZIP, APK, IPA, ASAR, plist, JavaScript, source-map, and generic analysis-database targets; Hopper remains the only adapter that accepts legacy `.hop` databases.
 - Discover deep-analysis candidates without starting them, choose deterministically, and retain one immutable provider/profile binding until an explicit switch or close; provider failures never trigger transparent fallback.
 - Attach to a user-owned Chrome-family browser over a configured loopback CDP endpoint; capture exact-origin web structure, safe metadata, approved value-free payload shapes, bundle/source-map evidence, WebMCP declarations, user-action timelines, capture diffs, and explicitly approved screenshots without navigation or JavaScript evaluation.
 - Inspect Electron `file://` renderer pages through a separate canonical-root permission boundary without invoking Electron APIs; script contents remain separately approved and byte bounded.
 - Validate and canonically serialize a provider-neutral [JavaScript Application Graph v1](docs/javascript-application-graph.md) spanning packages, ASAR entries, Electron roles, JavaScript/source-map entities, browser/runtime instances, IPC, endpoints, storage, and native add-ons. This shipped domain contract performs no extraction or I/O by itself.
-- Reconstruct bounded static package, entrypoint, Webpack/Rspack module, import, worker, endpoint, storage, source-map, and native-add-on structure from a local directory or ASAR through an AST-only [application service](docs/javascript-artifact-reconstruction.md). The service does not execute bootstrap code and does not add a standalone CLI/MCP tool yet.
+- Reconstruct bounded static package, entrypoint, Webpack/Rspack module, import, worker, endpoint, storage, source-map, BrowserWindow, preload, contextBridge, IPC, utility-process, and native-add-on structure from an approved local directory or ASAR through `analyze_javascript_application` or `rea analyze-javascript-application`. The AST-only [application service](docs/javascript-artifact-reconstruction.md) never executes bootstrap code, pairs only unique exact literal IPC channels, and reports dynamic or ambiguous channels as unresolved.
+- Reconcile that static graph with existing passive web or Electron Evidence through `reconcile_javascript_runtime` or `rea reconcile-javascript-runtime`. Exact captured bytes outrank caller-declared file/URL mappings; target, frame, script, worker, cache, and asset ambiguity stays explicit, source-map authority stays separate, and a module resident in an observed bundle is never reported as executed. See [JavaScript static/runtime reconciliation](docs/javascript-runtime-reconciliation.md).
+- Trace a literal route, string, API, IPC channel, module, or native export through authenticated application Evidence with explicit traversal bounds, then hand exact native artifact digests and requested exports to retained Ghidra or Hopper Evidence without automatic provider switching. Compare application versions using unique-only digest, source-map, structural, and semantic tiers; duplicate, incomplete, and truncated matches stay unknown. See [cross-layer JavaScript application workflows](docs/javascript-application-workflows.md).
+- Classify PE/CLI managed artifacts with `inspect_managed_artifact` / `rea inspect-managed-artifact`, inspect bounded metadata members, signatures, raw CIL hashes, limited decoded-instruction-tuple v1 hashes, separately reported exception regions, call edges, and field-access anchors with `inspect_managed_members` / `rea inspect-managed-members`, inventory declared ModuleRef/ImplMap/PInvoke and non-IL method boundary indicators with `inspect_managed_native_boundaries` / `rea inspect-managed-native-boundaries`, then compare two authenticated member observations with `compare_managed_members` / `rea compare-managed-members`. `verify_managed_native_boundaries` / `rea verify-managed-native-boundaries` checks managed P/Invoke declarations against authenticated native export or function Evidence while keeping verified, inferred, contradicted, and unresolved states distinct. The comparison treats build-local tokens as build-local and uses unique decoded-CIL/signature and structural method-shape tiers, never names alone; the v1 tuple hash does not itself resolve tokens or fully commit control flow. `project_managed_application_graph` / `rea project-managed-application-graph` projects authenticated managed artifact/member/native-boundary Evidence into the existing application graph for cross-layer feature tracing. `import_managed_reconstruction` / `rea import-managed-reconstruction` admits user-supplied decompiler C#/IL/pseudocode as analyst inference only after exact artifact SHA-256, MVID, signature, and the shipped v1 decoded-IL commitment match. Separately, `plan_managed_runtime_correlation` / `rea plan-managed-runtime-correlation` can admit a default-disabled, permission-gated runtime-correlation plan locked to the same build evidence. These paths never load the assembly, resolve CLR dependencies, execute target code, run a decompiler, or translate managed tokens into native addresses; full normalized-CIL v2 semantics, native-body bridge mapping, and an actual runtime executor remain future managed-code contracts.
+- Configure `REA_ILSPY_CMD_PATH=/absolute/path/to/ilspycmd` only when you want
+  doctor and `verify:managed` to inspect a bring-your-own ILSpy command as a
+  real reconstruction oracle. REA does not install ILSpy and does not treat
+  decompiler text as canonical metadata or CIL observation.
 - Traverse content-addressed artifact graphs without extraction; on macOS, read-only DMG traversal additionally requires `native_mount_approved: true` and `REA_ARTIFACT_NATIVE_MOUNT_ENABLED=true`. Materialize only approved occurrences into absent output roots.
 - Build bounded function dossiers with pseudocode, assembly, CFG edges, comments, calls, references, strings, and names.
 - Search and trace features across symbols, strings, metadata, references, and call paths.
@@ -386,24 +431,24 @@ REA is growing into a toolkit for understanding software across static artifacts
 ### Now
 
 1. **Maintain truthful product metadata** — extend the shipped canonical catalog and drift checks whenever versions, tools, providers, schemas, setup clients, or CLI capabilities change.
-2. **Electron boundary extraction and high-level surface** — extend the shipped static artifact projector with contextBridge, IPC, utility-process, and native-export boundaries, then expose one provider-neutral CLI/MCP workflow without widening authority.
-3. **Cross-provider conformance growth** — add source-owned architectures and difficult indirect/thunk cases while preserving semantic comparison and provider-specific text boundaries.
+2. **Cross-provider conformance growth** — add source-owned architectures and difficult indirect/thunk cases while preserving semantic comparison and provider-specific text boundaries.
 
 ### Next
 
-1. **Cross-layer tracing and version comparison** — trace renderer behavior through preload, IPC, main-process, storage, network, and native boundaries, then compare those paths across application versions.
-2. **Deeper JavaScript and source recovery** — add historical-source matching, rechunked/minified cross-version matching, and stronger static/runtime reconciliation on top of the shipped AST-only Webpack/Rspack reconstruction.
-3. **Deterministic behavior harnesses** — extend process ownership, protocol fixtures, filesystem observation, reconnects, and cross-version behavioral comparison.
+1. **Controlled replay conformance growth** — extend the shipped Linux extracted-module sandbox with more source-owned hostile fixtures and cross-kernel conformance; browser or Electron interaction remains a different future authority.
+2. **Broader application graph evidence** — extend authenticated cross-layer traces with additional static extractors and separately approved runtime authorities.
+3. **Professional managed-code analysis** — extend shipped PE/CLI triage, CIL evidence, managed/native declaration inventory, source-owned conformance, and obfuscation-resistant comparisons toward verified native-provider composition under the accepted [managed-code boundary](docs/managed-code-analysis.md).
+4. **Deterministic behavior harnesses** — extend process ownership, protocol fixtures, filesystem observation, reconnects, and cross-version behavioral comparison.
 
 ### Later
 
-1. **Controlled interaction and replay** — keep approved JavaScript execution, browser interaction, Electron instrumentation, and fuzzing behind a separate authority from passive observation.
+1. **Controlled application interaction** — evaluate separately authorized full-application driving without widening passive browser, Electron, or extracted-module replay authority.
 2. **Native runtime observation** — approval-gated LLDB, Frida, system logs, process/filesystem observers, and native API tracing.
 3. **Additional providers and targets** — evaluate IDA/Hex-Rays, Binary Ninja, Rizin, LIEF, Windows-native providers, mobile artifacts, firmware, document formats, and other software-defined systems.
 
 New providers must produce the same evidence and safety metadata as existing capabilities before they become part of the public workflow. Once REA has multiple optional toolchains, setup can become capability-selective; the consent rules for that future work are recorded in the [installation roadmap](docs/roadmap.md).
 
-See the [static-analysis provider evaluation](docs/provider-evaluation.md) for the shipped Ghidra function-analysis boundary, remaining admission gates, and provider comparison matrix, and [ADR-0001](docs/adr/0001-provider-selection-and-analysis-profiles.md) for the binding, selection, profile, snapshot, and compatibility decisions.
+See the [static-analysis provider evaluation](docs/provider-evaluation.md) for the shipped Ghidra function-analysis boundary, remaining admission gates, and provider comparison matrix; [ADR-0001](docs/adr/0001-provider-selection-and-analysis-profiles.md) for binding, selection, profile, snapshot, and compatibility decisions; the [controlled replay guide](docs/controlled-javascript-replay.md) plus [ADR-0002](docs/adr/0002-controlled-replay-authority-and-sandbox.md) for the shipped JavaScript replay boundary; and [ADR-0003](docs/adr/0003-managed-code-evidence-and-provider-boundary.md) for the managed-code evidence and provider design.
 
 ## Using REA with other agents
 
@@ -416,7 +461,7 @@ Setup detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf,
   "mcpServers": {
     "rea": {
       "command": "npx",
-      "args": ["-y", "rea-agents", "mcp"]
+      "args": ["-y", "rea-agents@latest", "mcp"]
     }
   }
 }
@@ -457,20 +502,20 @@ The CLI and MCP server use the same application workflows and evidence contracts
 The agent workflow above is the easiest way to use REA. For a one-off overview from the Terminal:
 
 ```bash
-npx -y rea-agents analyze /Applications/Notes.app
-npx -y rea-agents inspect /Applications/Notes.app
-npx -y rea-agents inspect /Applications/Notes.app --detail detailed --limit 20
-npx -y rea-agents search /Applications/Notes.app "offline"
-npx -y rea-agents function /Applications/Notes.app 0x1000
-npx -y rea-agents xrefs /Applications/Notes.app 0x1000
-npx -y rea-agents trace /Applications/Notes.app "offline"
-npx -y rea-agents compare /absolute/path/to/left-evidence.json /absolute/path/to/right-evidence.json
-npx -y rea-agents investigate-versions /path/to/v1 /path/to/v2 /absolute/path/to/evidence/releases.json --yes
-npx -y rea-agents capabilities
-npx -y rea-agents providers
+npx -y rea-agents@latest analyze /Applications/Notes.app
+npx -y rea-agents@latest inspect /Applications/Notes.app
+npx -y rea-agents@latest inspect /Applications/Notes.app --detail detailed --limit 20
+npx -y rea-agents@latest search /Applications/Notes.app "offline"
+npx -y rea-agents@latest function /Applications/Notes.app 0x1000
+npx -y rea-agents@latest xrefs /Applications/Notes.app 0x1000
+npx -y rea-agents@latest trace /Applications/Notes.app "offline"
+npx -y rea-agents@latest compare /absolute/path/to/left-evidence.json /absolute/path/to/right-evidence.json
+npx -y rea-agents@latest investigate-versions /path/to/v1 /path/to/v2 /absolute/path/to/evidence/releases.json --yes
+npx -y rea-agents@latest capabilities
+npx -y rea-agents@latest providers
 ```
 
-Run `npx -y rea-agents --help` for direct decompilation, bounded search and
+Run `npx -y rea-agents@latest --help` for direct decompilation, bounded search and
 other options. `analyze` and `inspect` share the same overview workflow;
 `function`, `xrefs`, and `trace` return the same Evidence v2 envelopes as MCP.
 
@@ -559,6 +604,10 @@ environment allowlist in `REA_PROCESS_ALLOWED_ENV_JSON`. Because the current PTY
 adapter uses host networking, it also requires
 `REA_PROCESS_ALLOW_EXTERNAL_NETWORK=true`.
 
+Set `REA_PROCESS_CAPTURE_AUTO_GRANT=false` to configure those process-capture
+limits as a ceiling without implicitly granting them. This mode remains
+fail-closed until a narrower grant is established.
+
 Capture a scenario or compare two saved Process Capture v4 Evidence records:
 
 ```bash
@@ -572,18 +621,22 @@ first terminal, interaction, exit, filesystem, protocol, process, or shim
 divergence. See [Process Capture v4](docs/process-capture.md) for scenario
 fields, command-shim replay, checkpoint triggers, limits, and safety behavior.
 
-If the native PTY backend is unavailable, install Xcode command-line tools and
-run `npm run rebuild:native`. Linux source builds require Python, `make`, and a
-C++ toolchain. Compatible packaged binaries do not require this rebuild.
+REA installs a prebuilt PTY backend for supported macOS, Linux, and Windows
+architectures. If the capability check reports that the backend is unavailable,
+reinstall REA for the current platform and architecture.
 
 ASAR inventory verifies Electron integrity metadata for both archive entries
 and `.asar.unpacked` companion files. Integrity failures identify the logical
 path, declared and calculated SHA-256 values, and whether the entry was
-unpacked; REA does not silently accept the mismatched artifact.
+unpacked; REA does not silently accept the mismatched artifact. If a supplied
+ASAR declares unpacked companion bytes that are absent from the local artifact
+set, REA keeps that occurrence as `unavailable` and continues analyzing the
+embedded JavaScript instead of treating the missing native/resource bytes as
+verified or absent.
 
 ## Security model
 
-REA does not provide a hosted analysis service. Hopper and Ghidra bridge communication uses authenticated private local sockets. Dynamic capabilities are disabled by default and require both operator policy and explicit per-call approval. REA is not a security sandbox: providers and launched targets run with the current user's permissions, and each capability reports its side effects and limitations. Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md).
+REA does not provide a hosted analysis service. Hopper and Linux Ghidra bridge communication uses authenticated private local sockets. Windows Ghidra P0 uses authenticated IPv4 loopback but does not claim named-pipe DACL or hostile-local-user isolation. Dynamic capabilities are disabled by default and require both operator policy and explicit per-call approval. Shipped providers, passive observers, and Process Capture are not security sandboxes: providers and launched targets run with the current user's permissions. Extracted JavaScript replay is a distinct Linux-only capability that fails closed unless Bubblewrap namespaces, architecture-checked seccomp, private runtime mounts, and delegated cgroup limits are available; it never inherits browser, Electron, or Process Capture authority. See [ADR-0002](docs/adr/0002-controlled-replay-authority-and-sandbox.md). Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md).
 
 ## FAQ
 

package/bridge/ghidra/ReaGhidraBridge.java

@@ -7,15 +7,20 @@ import java.io.ByteArrayOutputStream;
 import java.io.IOException;
 import java.io.Reader;
 import java.math.BigInteger;
+import java.net.InetAddress;
+import java.net.InetSocketAddress;
 import java.net.StandardProtocolFamily;
 import java.net.UnixDomainSocketAddress;
 import java.nio.channels.Channels;
 import java.nio.channels.ServerSocketChannel;
 import java.nio.channels.SocketChannel;
 import java.nio.charset.StandardCharsets;
+import java.nio.file.AtomicMoveNotSupportedException;
 import java.nio.file.Files;
 import java.nio.file.LinkOption;
 import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.nio.file.StandardOpenOption;
 import java.nio.file.attribute.PosixFilePermissions;
 import java.security.MessageDigest;
 import java.util.ArrayList;
@@ -67,7 +72,7 @@ import ghidra.program.model.symbol.Symbol;
 import ghidra.program.model.symbol.SymbolIterator;
 
 public final class ReaGhidraBridge extends HeadlessScript {
-    private static final int BRIDGE_VERSION = 3;
+    private static final int BRIDGE_VERSION = 4;
     private static final int MAX_DESCRIPTOR_BYTES = 16 * 1024;
     private static final int MAX_REQUEST_CHARACTERS = 256 * 1024;
     private static final int MAX_RESPONSE_BYTES = 1024 * 1024;
@@ -85,9 +90,11 @@ public final class ReaGhidraBridge extends HeadlessScript {
     private static final Gson GSON = new GsonBuilder().serializeNulls().create();
     private static final Set<String> DESCRIPTOR_KEYS = Set.of(
         "schema_version",
-        "socket_path",
+        "transport",
+        "endpoint_path",
         "token",
         "run_id",
+        "target_sha256",
         "provider_version",
         "profile_digest"
     );
@@ -143,6 +150,16 @@ public final class ReaGhidraBridge extends HeadlessScript {
         if (!Application.getApplicationVersion().equals(descriptor.providerVersion)) {
             throw new IllegalStateException("Ghidra provider version does not match the session");
         }
+        String importedSha256 = currentProgram.getExecutableSHA256();
+        if (importedSha256 == null ||
+            !constantTimeEquals(
+                importedSha256.toLowerCase(Locale.ROOT),
+                descriptor.targetSha256
+            )) {
+            throw new IllegalStateException(
+                "Ghidra imported-byte digest does not match the admitted target"
+            );
+        }
         try {
             initializeDecompiler();
             serve(descriptor);
@@ -156,22 +173,77 @@ public final class ReaGhidraBridge extends HeadlessScript {
     }
 
     private void serve(SessionDescriptor descriptor) throws Exception {
-        Path socketPath = Path.of(descriptor.socketPath);
+        if (descriptor.transport.equals("unix-socket")) {
+            serveUnixSocket(descriptor);
+            return;
+        }
+        if (descriptor.transport.equals("authenticated-loopback-tcp")) {
+            serveLoopbackTcp(descriptor);
+            return;
+        }
+        throw new IllegalArgumentException("REA bridge transport is invalid");
+    }
+
+    private void serveUnixSocket(SessionDescriptor descriptor) throws Exception {
+        Path socketPath = Path.of(descriptor.endpointPath);
         Files.deleteIfExists(socketPath);
         try (ServerSocketChannel server = ServerSocketChannel.open(StandardProtocolFamily.UNIX)) {
             server.bind(UnixDomainSocketAddress.of(socketPath));
             Files.setPosixFilePermissions(socketPath, PosixFilePermissions.fromString("rw-------"));
-            try (SocketChannel client = server.accept();
-                 BufferedReader reader = new BufferedReader(Channels.newReader(client, StandardCharsets.UTF_8));
-                 BufferedWriter writer = new BufferedWriter(Channels.newWriter(client, StandardCharsets.UTF_8))) {
-                serveClient(descriptor, reader, writer);
-            }
+            acceptClient(server, descriptor);
         }
         finally {
             Files.deleteIfExists(socketPath);
         }
     }
 
+    private void serveLoopbackTcp(SessionDescriptor descriptor) throws Exception {
+        Path endpointPath = Path.of(descriptor.endpointPath);
+        Path pendingPath = endpointPath.resolveSibling(endpointPath.getFileName() + ".pending");
+        Files.deleteIfExists(endpointPath);
+        Files.deleteIfExists(pendingPath);
+        try (ServerSocketChannel server = ServerSocketChannel.open()) {
+            server.bind(new InetSocketAddress(InetAddress.getByName("127.0.0.1"), 0));
+            InetSocketAddress address = (InetSocketAddress) server.getLocalAddress();
+            JsonObject endpoint = new JsonObject();
+            endpoint.addProperty("schema_version", 1);
+            endpoint.addProperty("host", "127.0.0.1");
+            endpoint.addProperty("port", address.getPort());
+            Files.writeString(
+                pendingPath,
+                GSON.toJson(endpoint) + "\n",
+                StandardCharsets.UTF_8,
+                StandardOpenOption.CREATE_NEW,
+                StandardOpenOption.WRITE
+            );
+            try {
+                Files.move(pendingPath, endpointPath, StandardCopyOption.ATOMIC_MOVE);
+            }
+            catch (AtomicMoveNotSupportedException exception) {
+                Files.move(pendingPath, endpointPath);
+            }
+            acceptClient(server, descriptor);
+        }
+        finally {
+            Files.deleteIfExists(pendingPath);
+            Files.deleteIfExists(endpointPath);
+        }
+    }
+
+    private void acceptClient(
+            ServerSocketChannel server,
+            SessionDescriptor descriptor) throws Exception {
+        try (SocketChannel client = server.accept();
+             BufferedReader reader = new BufferedReader(
+                 Channels.newReader(client, StandardCharsets.UTF_8)
+             );
+             BufferedWriter writer = new BufferedWriter(
+                 Channels.newWriter(client, StandardCharsets.UTF_8)
+             )) {
+            serveClient(descriptor, reader, writer);
+        }
+    }
+
     private void serveClient(
             SessionDescriptor descriptor,
             BufferedReader reader,
@@ -270,6 +342,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
             "default_address_space",
             currentProgram.getAddressFactory().getDefaultAddressSpace().getName()
         );
+        target.addProperty("sha256", descriptor.targetSha256);
 
         JsonObject result = new JsonObject();
         result.addProperty("name", "REA Ghidra bridge");
@@ -1586,13 +1659,15 @@ public final class ReaGhidraBridge extends HeadlessScript {
             JsonParser.parseString(Files.readString(path, StandardCharsets.UTF_8)),
             DESCRIPTOR_KEYS
         );
-        if (requireInteger(object, "schema_version") != 1) {
+        if (requireInteger(object, "schema_version") != 2) {
             throw new IllegalArgumentException("REA session descriptor version is invalid");
         }
         return new SessionDescriptor(
-            requireString(object, "socket_path"),
+            requireString(object, "transport"),
+            requireString(object, "endpoint_path"),
             requireString(object, "token"),
             requireString(object, "run_id"),
+            requireSha256(object, "target_sha256"),
             requireString(object, "provider_version"),
             requireString(object, "profile_digest")
         );
@@ -1662,6 +1737,14 @@ public final class ReaGhidraBridge extends HeadlessScript {
         return result;
     }
 
+    private static String requireSha256(JsonObject object, String name) {
+        String value = requireString(object, name);
+        if (!value.matches("[a-f0-9]{64}")) {
+            throw new IllegalArgumentException(name + " must be lowercase SHA-256");
+        }
+        return value;
+    }
+
     private static int requireInteger(JsonObject object, String name) {
         JsonElement value = object.get(name);
         if (value == null || !value.isJsonPrimitive() || !value.getAsJsonPrimitive().isNumber()) {
@@ -1795,9 +1878,11 @@ public final class ReaGhidraBridge extends HeadlessScript {
     private record InstructionScan(List<Instruction> instructions, boolean truncated) {}
     private record TruncatedValue(String value, boolean truncated) {}
     private record SessionDescriptor(
-        String socketPath,
+        String transport,
+        String endpointPath,
         String token,
         String runId,
+        String targetSha256,
         String providerVersion,
         String profileDigest
     ) {}

package/dist/application/ArtifactExtraction.js

@@ -113,7 +113,7 @@ const createExtractionResult = (input, inventory, selected, extracted) => {
     });
 };
 const loadInventory = async (path, limits, selectedIds, signal) => {
-    const snapshot = await scanArtifactInventory(path, limits, signal);
+    const snapshot = await scanArtifactInventory(path, limits, { signal });
     const occurrences = new Map();
     const neededNodes = new Set();
     collectOccurrences(snapshot.occurrences, selectedIds, occurrences, neededNodes);

package/dist/application/ArtifactInventory/classify.js

@@ -0,0 +1,42 @@
+import { open } from "node:fs/promises";
+import { classifyArtifactPath } from "../ArtifactGraphConstruction.js";
+const classifyContainerExtension = (path) => {
+    const lower = path.toLowerCase();
+    for (const format of ["asar", "ipa", "apk", "zip", "dmg", "pkg"])
+        if (lower.endsWith(`.${format}`))
+            return format;
+    return undefined;
+};
+export const classifyRoot = async (path, directory) => {
+    if (directory)
+        return "directory";
+    const extensionFormat = classifyContainerExtension(path);
+    if (extensionFormat !== undefined)
+        return extensionFormat;
+    const handle = await open(path, "r");
+    try {
+        const magic = Buffer.alloc(4);
+        const observed = await handle.read(magic, 0, magic.length, 0);
+        if (observed.bytesRead === 4 &&
+            magic[0] === 0x50 &&
+            magic[1] === 0x4b &&
+            [0x03, 0x05, 0x07].includes(magic[2] ?? -1) &&
+            [0x04, 0x06, 0x08].includes(magic[3] ?? -1))
+            return "zip";
+        if (observed.bytesRead === 4) {
+            const header = magic.readUInt32BE(0);
+            if ([0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(header))
+                return "mach-o-universal";
+            if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(header))
+                return "mach-o";
+            if (magic.equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
+                return "elf";
+        }
+        if (observed.bytesRead >= 2 && magic[0] === 0x4d && magic[1] === 0x5a)
+            return "pe";
+    }
+    finally {
+        await handle.close();
+    }
+    return classifyArtifactPath(path).format;
+};