rea-agents 6.2.0 → 6.4.0

package/dist/server/registerWebRuntimeTools.js

@@ -2,11 +2,12 @@ import { toolContract } from "../contracts/toolContracts.js";
 import { mcpProgressReporter } from "./mcpProgress.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { runAdmittedToolOperation } from "./admittedToolOperation.js";
 /** Bind distinct runtime operations to named contracts and the session's Evidence owner. */
-export const registerWebRuntimeTools = (server, service, logger, recordEvidence) => {
+export const registerWebRuntimeTools = (server, service, logger, recordEvidence, withAdmittedAnalysis) => {
     const execution = toolContract("observe_web_execution");
     const listeners = toolContract("inspect_web_event_listeners");
-    server.registerTool(execution.name, toolRegistrationOptions(execution), async (input, context) => {
+    server.registerTool(execution.name, toolRegistrationOptions(execution), async (input, context) => runAdmittedToolOperation(server, withAdmittedAnalysis, execution.name, context.mcpReq.signal, async () => {
         const result = await logToolExecution(logger, execution.name, () => service.observe(input, {
             signal: context.mcpReq.signal,
             progress: mcpProgressReporter(context),
@@ -15,12 +16,12 @@ export const registerWebRuntimeTools = (server, service, logger, recordEvidence)
             return server.delivery.toCallToolResult(result, execution);
         const recorded = recordEvidence?.(result.value);
         return server.delivery.toEvidenceToolResult(result.value, execution, recorded);
-    });
-    server.registerTool(listeners.name, toolRegistrationOptions(listeners), async (input, context) => {
+    }));
+    server.registerTool(listeners.name, toolRegistrationOptions(listeners), async (input, context) => runAdmittedToolOperation(server, withAdmittedAnalysis, listeners.name, context.mcpReq.signal, async () => {
         const result = await logToolExecution(logger, listeners.name, () => service.inspect(input, { signal: context.mcpReq.signal }));
         if (!result.ok)
             return server.delivery.toCallToolResult(result, listeners);
         const recorded = recordEvidence?.(result.value);
         return server.delivery.toEvidenceToolResult(result.value, listeners, recorded);
-    });
+    }));
 };

package/dist/server/registerWebScriptTool.js

@@ -2,14 +2,17 @@ import { exportWebScriptsValidated } from "../application/WebScriptExportService
 import { toolContract } from "../contracts/toolContracts.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { runAdmittedToolOperation } from "./admittedToolOperation.js";
 /** Register local script export without requiring a live browser provider. */
 export const registerWebScriptTool = (server, options) => {
     const contract = toolContract("export_web_scripts");
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
-        const result = await logToolExecution(options.logger, contract.name, () => exportWebScriptsValidated(input, { signal: context.mcpReq.signal }));
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => runAdmittedToolOperation(server, options.withAdmittedAnalysis, contract.name, context.mcpReq.signal, async () => {
+        const result = await logToolExecution(options.logger, contract.name, () => exportWebScriptsValidated(input, options.artifactResources, {
+            signal: context.mcpReq.signal,
+        }));
         if (!result.ok)
             return server.delivery.toCallToolResult(result, contract);
         const recorded = options.recordEvidence?.(result.value);
         return server.delivery.toEvidenceToolResult(result.value, contract, recorded);
-    });
+    }));
 };

package/dist/server/registerWebSourceLocationTool.js

@@ -1,14 +1,9 @@
 import { toolContract } from "../contracts/toolContracts.js";
-import { logToolExecution } from "./toolLogging.js";
+import { createEvidenceToolHandler } from "./contractToolHandler.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
 /** Bind source point tracing to its exact named contract and session Evidence owner. */
-export const registerWebSourceLocationTool = (server, service, logger, recordEvidence) => {
+export const registerWebSourceLocationTool = (server, service, logger, recordEvidence, withAdmittedAnalysis) => {
     const contract = toolContract("trace_web_source_location");
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
-        const result = await logToolExecution(logger, contract.name, () => service.trace(input, { signal: context.mcpReq.signal }));
-        if (!result.ok)
-            return server.delivery.toCallToolResult(result, contract);
-        const recorded = recordEvidence?.(result.value);
-        return server.delivery.toEvidenceToolResult(result.value, contract, recorded);
-    });
+    const handler = createEvidenceToolHandler(server, (input, options) => service.trace(input, options), logger, recordEvidence, withAdmittedAnalysis);
+    server.registerTool(contract.name, toolRegistrationOptions(contract), handler(contract));
 };

package/dist/server/toolResult.js

@@ -1,5 +1,5 @@
 import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";
-import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { projectAnalysisError, } from "../domain/analysisErrorProjection.js";
 import {} from "../domain/analysisErrorBase.js";
 import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
 import { encodeToolResult, MCP_RESULT_STRING_LIMIT, } from "./toolResultEncoding.js";
@@ -36,7 +36,26 @@ export class ToolResultDelivery {
     }
     /** Project an error without allocating oversized repeated MCP text. */
     toErrorToolResult(error) {
-        const structuredContent = { error: projectAnalysisError(error) };
+        return this.projectedErrorResult(projectAnalysisError(error));
+    }
+    /** Deliver the original failure with the producer-acknowledged partial Evidence reference. */
+    toRecordedPartialErrorToolResult(error, evidenceId, recorded) {
+        if (!recorded.ok)
+            return this.toErrorToolResult(error);
+        const projected = projectAnalysisError(error);
+        return this.projectedErrorResult({
+            ...projected,
+            details: {
+                ...projected.details,
+                partial_observation: {
+                    kind: "retained-evidence",
+                    evidence_id: evidenceId,
+                },
+            },
+        });
+    }
+    projectedErrorResult(projected) {
+        const structuredContent = { error: projected };
         // Errors reach the wire as text only; the structured copy is a private
         // carrier the transport removes after its own budget check.
         const encoded = encodeToolResult(structuredContent, this.resultBudgetBytes, "text");

package/dist/windows/WindowsPrivateRuntime.js

@@ -34,7 +34,7 @@ export class WindowsPrivateRuntime {
         const authority = requireWindowsNativeAuthority();
         const observation = runtimeSchema.parse(authority.call("runtime_create", [parent, prefix]));
         const runtime = new WindowsPrivateRuntime(observation, authority);
-        runtimes.set(observation.path.toLowerCase(), runtime);
+        runtimes.set(windowsRuntimeIdentityKey(observation), runtime);
         return runtime;
     }
     /** Open a private child directory through retained, verified parent handles. */
@@ -119,13 +119,20 @@ export class WindowsPrivateRuntime {
         await this.#pending?.catch(() => undefined);
         this.authority.call("runtime_close", [this.observation.handle]);
         this.#closed = true;
-        runtimes.delete(this.observation.path.toLowerCase());
+        runtimes.delete(windowsRuntimeIdentityKey(this.observation));
     }
 }
-/** Select an already-owned runtime; an arbitrary pathname cannot grant authority. */
+/** File id returned by the OS. Path spelling is not part of the lease key. */
+const windowsRuntimeIdentityKey = (identity) => `${identity.volumeSerial}:${identity.fileId}`;
+/**
+ * Select an already-owned runtime. Only the observed `path` or `finalPath`
+ * matches, character for character. A case variant fails closed.
+ */
 export const windowsPrivateRuntime = (rootPath) => {
-    const runtime = runtimes.get(rootPath.toLowerCase());
-    if (runtime === undefined)
+    const matches = [...runtimes.values()].filter((runtime) => runtime.observation.finalPath === rootPath ||
+        runtime.observation.path === rootPath);
+    const runtime = matches[0];
+    if (matches.length !== 1 || runtime === undefined)
         throw new Error(`No native private runtime owns ${rootPath}`);
     return runtime;
 };

package/install.sh

@@ -85,19 +85,22 @@ if [[ "$version" =~ \+ ]]; then
   fail "npm cannot install an exact version with build metadata. Pass a version without build metadata, then retry."
 fi
 
-prefix_args=()
+install_args=(install --global)
 if [[ "$platform" == "Linux" ]]; then
-  prefix_args=(--prefix "$HOME/.local")
+  install_args+=(--prefix "$HOME/.local")
   install_bin="$HOME/.local/bin/rea"
 else
   npm_prefix="$(npm prefix --global)" || fail "the npm global prefix could not be read. Repair the npm configuration, then retry."
   install_bin="$npm_prefix/bin/rea"
 fi
+install_args+=("$PACKAGE@$version")
 
 printf 'REA install plan\n'
 printf '  Version: %s\n' "$version"
 printf '  Runtime: Node.js %s\n' "$node_version"
-printf '  Command: npm install --global %s@%s\n' "$PACKAGE" "$version"
+printf '  Command:'
+printf ' %q' npm "${install_args[@]}"
+printf '\n'
 printf '  Binary:  %s\n' "$install_bin"
 printf '  Setup:   %s\n' "$([[ "$start_setup" == true ]] && printf 'start when a terminal is available' || printf 'skipped')"
 
@@ -107,7 +110,7 @@ if [[ "$dry_run" == true ]]; then
 fi
 
 printf 'Installing %s@%s...\n' "$PACKAGE" "$version"
-npm install --global ${prefix_args[@]+"${prefix_args[@]}"} "$PACKAGE@$version" || fail "npm could not install REA. Check registry access and npm permissions, then retry."
+npm "${install_args[@]}" || fail "npm could not install REA. Check registry access and npm permissions, then retry."
 [[ -x "$install_bin" ]] || fail "npm completed without installing the rea command. Check the npm global bin directory and PATH, then retry."
 installed_version="$("$install_bin" --version 2>/dev/null | tr -d '[:space:]')" || fail "the installed REA version could not be read. Reinstall the requested version, then retry."
 [[ "$installed_version" == "$version" ]] || fail "installed version $installed_version does not match $version. Reinstall the requested version, then retry."

package/licenses/nativeaot-parser-MIT.txt

@@ -0,0 +1,28 @@
+The MIT License (MIT)
+=====================
+
+Copyright © 2023-2025 Washi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The read-only NativeAOT parser adapts format and hydration semantics from
+Washi1337/ghidra-nativeaot commit
+effeb734fc570c32650f88b159608979dc7b423e (MIT). MethodTable field layout was
+cross-checked against .NET runtime src/coreclr/nativeaot/Runtime/inc/MethodTable.h
+at dotnet/runtime commit a3b2d40328be0be3f8dd43f0e5cc925b8827b044 (MIT).

package/native/windows/build/manifest.json

@@ -1,9 +1,9 @@
 {
-  "packageVersion": "6.2.0",
+  "packageVersion": "6.4.0",
   "platform": "win32",
   "architecture": "x64",
   "abiVersion": 1,
   "nodeApiVersion": 8,
   "artifact": "rea-windows-x64.node",
-  "artifactSha256": "fedfd4ce8b3e15784d1a6ef7e9ba7eb9052e8335a1c75b6d69cd7e94f29ab1f8"
+  "artifactSha256": "c4fd9f377e567bcf15ba3fec3e0b0ed965d82b765a2adcdac49e46f14524b6d5"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rea-agents",
   "mcpName": "io.github.morluto/rea",
-  "version": "6.2.0",
+  "version": "6.4.0",
   "description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,9 @@
     "access": "public"
   },
   "type": "module",
+  "imports": {
+    "#javascript-analysis-worker": "./dist/composition/javascriptAnalysisWorkerProcess.js"
+  },
   "bin": {
     "rea": "scripts/rea.mjs",
     "rea-agents": "scripts/rea.mjs"
@@ -50,6 +53,8 @@
     "bridge/ghidra/ReaGhidraBridge.java",
     "bridge/ghidra/ReaGhidraExtensions.java",
     "bridge/ghidra/ReaGhidraPrepareCom.java",
+    "bridge/ghidra/ReaGhidraApplySeeds.java",
+    "bridge/ghidra/ReaGhidraNoReturnFix.java",
     "bridge/android/ReaJadxBridge.java",
     "bridge/mitmproxy/capture.py",
     "scripts/rea.mjs",
@@ -76,9 +81,11 @@
     "bridge/pwndbg/launch_impl.py",
     "bridge/pwndbg/core_context.py",
     "third_party/pwndbg/README.md",
-    "third_party/pwndbg/LICENSE.md"
+    "third_party/pwndbg/LICENSE.md",
+    "licenses/nativeaot-parser-MIT.txt"
   ],
   "scripts": {
+    "release:notes": "node scripts/release-notes.mjs",
     "deps:check": "node scripts/check-dependency-install.mjs",
     "metadata:generate": "node scripts/run-exclusive.mjs artifacts node scripts/generate-package-metadata.mjs",
     "metadata:check": "node scripts/generate-package-metadata.mjs --check",
@@ -88,7 +95,7 @@
     "prebuild": "npm run deps:check",
     "build": "node scripts/run-exclusive.mjs artifacts turbo run artifacts:skills --force",
     "precheck": "npm run deps:check",
-    "check": "node scripts/run-exclusive.mjs artifacts turbo run typecheck lint format:check knip metadata:check",
+    "check": "node scripts/run-exclusive.mjs artifacts turbo run typecheck lint format:check knip metadata:check && npm run verify:architecture-guards",
     "precheck:fast": "npm run deps:check",
     "check:fast": "turbo run typecheck lint --output-logs=errors-only",
     "precheck:changed": "npm run deps:check",
@@ -98,8 +105,10 @@
     "precheck:pr": "npm run deps:check",
     "check:pr": "node scripts/run-exclusive.mjs artifacts turbo run typecheck lint format:check knip metadata:check test:run && npm run docs:check && npm run jscpd && npm run scan:todos",
     "precheck:ci": "npm run deps:check",
-    "check:ci": "node scripts/run-exclusive.mjs artifacts turbo run typecheck lint format:check knip metadata:check jscpd scan:todos",
+    "check:ci": "node scripts/run-exclusive.mjs artifacts turbo run typecheck lint format:check knip metadata:check jscpd scan:todos && npm run verify:architecture-guards",
     "build:cached": "node scripts/check-dependency-install.mjs && node scripts/run-exclusive.mjs artifacts turbo run artifacts:skills",
+    "build:termux": "node scripts/run-exclusive.mjs artifacts npm run build:termux:run",
+    "build:termux:run": "npm run compile:termux && npm run artifacts:skills",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "lint": "oxlint && npm run verify:module-boundaries",
@@ -144,7 +153,13 @@
     "verify:native-ui": "npm run build:cached && node scripts/verify-native-ui.mjs",
     "verify:keyed-archive": "npm run build:cached && node scripts/verify/apple/keyed-archive.mjs",
     "verify:macos-bundle": "npm run build:cached && node scripts/verify/apple/macos-bundle.mjs",
+    "verify:legacy-simulator": "npm run build:cached && node scripts/verify/apple/legacy-simulator.mjs",
+    "verify:architecture-guards": "node scripts/verify/architecture-guards.mjs",
+    "verify:apktool": "npm run build:cached && node scripts/verify-apktool.mjs",
+    "verify:adb": "npm run build:cached && node scripts/verify-adb.mjs",
     "verify:ghidra": "npm run build:cached && node scripts/verify-real-ghidra.mjs",
+    "verify:ghidra:seeds": "npm run build:cached && node scripts/verify/ghidra/seeds.mjs",
+    "verify:ghidra:mips": "npm run build:cached && node scripts/verify-real-ghidra-mips.mjs",
     "verify:ghidra:swift": "npm run build:cached && node scripts/verify-real-ghidra-swift.mjs",
     "verify:ida": "npm run build:cached && node scripts/verify-real-ida.mjs",
     "verify:ghidra:switch": "npm run build:cached && node scripts/verify-real-ghidra-switch.mjs",
@@ -167,6 +182,7 @@
     "verify:firmware": "npm run build:cached && node scripts/verify/firmware/analysis.mjs",
     "fixtures:firmware": "node scripts/fixtures/firmware/generate.mjs",
     "verify:android": "npm run build:cached && node scripts/verify/android/analysis.mjs",
+    "verify:jeb": "npm run build:cached && node scripts/verify-jeb.mjs",
     "fixtures:android": "node scripts/fixtures/android/fetch.mjs",
     "verify:agent": "npm run build:cached && node scripts/verify-agent-experience.mjs",
     "verify:hopper:linux": "npm run verify:fixtures && npm run build:cached && node scripts/verify-real-hopper-linux.mjs",
@@ -177,6 +193,17 @@
     "verify:readiness": "npm run build:cached && npm run verify:fixtures && node scripts/verify-reconstruction-readiness.mjs",
     "verify:package": "npm run build:cached && node scripts/verify-package.mjs",
     "verify:package:windows": "npm run build:cached && node scripts/verify-windows-package.mjs",
+    "verify:qwen-client": "npm run build:cached && node scripts/verify-qwen-client.mjs",
+    "verify:gemini-client": "npm run build:cached && node scripts/verify-gemini-client.mjs",
+    "verify:opencode-client": "npm run build:cached && node scripts/verify-opencode-client.mjs",
+    "verify:grok-client": "npm run build:cached && node scripts/verify-grok-client.mjs",
+    "verify:commandcode-client": "npm run build:cached && node scripts/verify-commandcode-client.mjs",
+    "verify:omp-client": "npm run build:cached && node scripts/verify-omp-client.mjs",
+    "verify:copilot-client": "npm run build:cached && node scripts/verify-copilot-client.mjs",
+    "verify:claude-client": "npm run build:cached && node scripts/verify-claude-client.mjs",
+    "verify:pi-client": "npm run build:cached && node scripts/verify-native-agent-client.mjs pi",
+    "verify:hermes-client": "npm run build:cached && node scripts/verify-native-agent-client.mjs hermes",
+    "verify:deepseek-client": "npm run build:cached && node scripts/verify-deepseek-client.mjs",
     "probe:windows-capabilities": "npm run build:cached && node scripts/windows-capabilities.mjs",
     "verify:published": "node scripts/verify-published-package.mjs",
     "config:print": "node scripts/print-mcp-config.mjs",
@@ -218,6 +245,7 @@
     "verify:recorded:crash": "npm run build:cached && node scripts/verify-recorded-crash.mjs",
     "mcp-catalog:check:built": "node scripts/generate-mcp-tool-catalog.mjs --check",
     "compile": "node scripts/clean-build-output.mjs && tsc -p tsconfig.build.json",
+    "compile:termux": "node scripts/clean-build-output.mjs && node --max-old-space-size=3072 node_modules/typescript-termux/lib/tsc.js -p tsconfig.build.json",
     "artifacts:mcp-catalog": "node scripts/generate-mcp-tool-catalog.mjs",
     "artifacts:skills": "node scripts/generate-skill-metadata.mjs",
     "artifacts:product-catalog": "node scripts/generate-product-catalog.mjs",
@@ -243,6 +271,7 @@
     "@lydell/node-pty": "1.1.0",
     "@modelcontextprotocol/client": "2.3.1",
     "@modelcontextprotocol/server": "2.3.1",
+    "@xmldom/xmldom": "0.9.12",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
     "@zip.js/zip.js": "2.15.0",
@@ -263,10 +292,12 @@
     "plist": "5.0.0",
     "semver": "7.8.5",
     "smol-toml": "1.9.0",
+    "stream-json": "3.7.0",
     "write-file-atomic": "7.0.0",
     "ws": "8.21.0",
     "zod": "4.4.3",
-    "evmole": "0.9.3"
+    "evmole": "0.9.3",
+    "yaml": "2.9.0"
   },
   "overrides": {
     "vitepress": {
@@ -289,8 +320,8 @@
     "oxlint": "1.87.0",
     "turbo": "2.11.7",
     "typescript": "7.0.2",
+    "typescript-termux": "npm:typescript@5.9.3",
     "vitepress": "1.6.4",
-    "vitest": "5.0.3",
-    "yaml": "2.9.0"
+    "vitest": "5.0.3"
   }
 }

package/scripts/rea.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { access } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // Route production MCP before importing Incur. Incur owns registration helpers
@@ -15,6 +15,21 @@ const isMcpMode =
   args.length === 1 && (args[0] === "--mcp" || args[0] === "mcp");
 const isMcpDoctorMode = args[0] === "mcp" && args[1] === "doctor";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// Playwright's registry assumes one of its three desktop host platforms when
+// it chooses the browser cache directory. Termux reports `android`, although
+// its Node runtime and filesystem are POSIX-compatible. Keep the cache path
+// explicit so REA can start on Termux. Browser launch still requires a
+// caller-supplied Android-compatible Chromium executable.
+if (
+  process.platform === "android" &&
+  process.env.PLAYWRIGHT_BROWSERS_PATH === undefined
+) {
+  const cacheRoot =
+    process.env.XDG_CACHE_HOME ?? join(process.env.HOME ?? ".", ".cache");
+  process.env.PLAYWRIGHT_BROWSERS_PATH = join(cacheRoot, "ms-playwright");
+}
+
 const runtimeFiles = isMcpMode
   ? ["dist/main.js"]
   : isMcpDoctorMode

package/skills/reverse-engineer-anything/SKILL.md

@@ -2,8 +2,8 @@
 name: reverse-engineer-anything
 description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
 metadata:
-  version: "34"
-  tool_count: 139
+  version: "37"
+  tool_count: 170
 ---
 
 # REA
@@ -26,50 +26,18 @@ a skill installed from repository main may describe capabilities absent from
 an older npm release. Keep complete inline Evidence when that server does not
 advertise retained references.
 
-When tools are absent or registration is stale:
-
-1. Diagnose without changing files. For Codex, run
-   `npx -y rea-agents@latest doctor --client codex --json`. Substitute the current
-   supported client: `claude_code`, `claude_desktop`, `codex`, `cursor`,
-   `gemini_cli`, `windsurf`, `devin`, `opencode`, `antigravity`, `copilot_cli`,
-   `commandcode`, `vscode`, `grok_build`, or `grok_bot`. `grok_bot` has no local
-   file registration: doctor reports the Grok Bot chat step, and setup does not
-   write `mcp.json`. If the client is unknown, use `doctor --json` and
-   inspect its registration results before choosing a setup scope.
-2. Distinguish the reason. Missing, malformed, or stale registration needs a
-   scoped configuration repair. An aligned registration with no tools in the
-   active session needs a restart/reconnection; doctor cannot prove that the
-   current agent has connected. A missing provider affects only tasks requiring
-   that provider: static JavaScript inspection needs neither Hopper nor Ghidra,
-   and Android inspection has separate bring-your-own JADX/Java prerequisites.
-3. For a configuration repair, prepare the read-only plan:
-   `npx -y rea-agents@latest setup --client codex --dry-run --json`.
-   Use the current client's ID, show its exact proposed paths, backups, and
-   changes, and obtain approval before setup writes configuration or installs
-   Hopper. Setup normally installs the matching bundled skill too; include that
-   replacement in the reviewed plan. After approval, apply the same scope with
-   `npx -y rea-agents@latest setup --client codex --yes`. Add `--install-hopper`
-   only if that separate installation was needed and explicitly approved.
-4. Restart/reconnect the affected agent. Verify that REA tools actually appear
-   in the session, then resume the original investigation. If they remain
-   absent, inspect the client's MCP launch error rather than repeating setup.
-
-REA setup never installs or upgrades Node.js, npm, Homebrew, Java, Ghidra, IDA,
-JADX, Binwalk, or Unblob. Use existing prerequisites; do not install unrelated
-software to repair
-MCP registration. For an unsupported client, use manual stdio registration
-with a version-pinned `rea-agents` package or continue through the CLI.
-
-A concrete CLI fallback for an operator-supplied JavaScript tree or ASAR is:
-
-```bash
-npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
-```
-
-No MCP registration or native engine is required. Read the returned Evidence,
-graph, limitations, and unknowns with the same care as an MCP result; the CLI
-returns the Evidence record directly. This fallback does not establish that
-MCP is configured. Native CLI tasks still require their selected engine.
+If tools are absent, a call is blocked by the client, or a required provider is
+unavailable, read [connection and recovery](references/connection-and-recovery.md).
+Diagnose the observed blocker, continue useful supported work, and resume the
+original task after repair. Client approval, shell PATH, registration and engine
+availability have different remedies; avoid repeating setup for all of them.
+
+Prefer an existing `rea` CLI. When none is installed and REA package acquisition
+is within the authorized scope, use `npx -y rea-agents@6.4.0` in its place.
+Configuration repair starts with a read-only setup plan; show paths, backups and
+skill replacement before applying authorized changes. Preserve existing approval
+and target-execution boundaries. REA setup never installs or upgrades unrelated
+software, including Node.js, npm, Homebrew, Java, Ghidra, IDA, JADX, Binwalk or Unblob.
 
 ## Route the target first
 
@@ -115,6 +83,9 @@ explicit path or endpoint and do not need it.
   Historical PIDs do not select live processes. Request `include_debugger_context`
   only when core-only mapping candidates help; see the
   [recorded crash guide](https://github.com/morluto/rea/blob/main/docs/recorded-crashes.md).
+- PE resource type/name/language trees and static icon group references:
+  `inspect_pe_resources` with an explicit path. This portable operation requires
+  no active target or engine; opaque payloads retain file ranges and SHA-256.
 - Native executable, library, or analysis database: `open_binary`, then
   use focused analysis tools directly; call `binary_overview` when metadata or
   inventory context is useful and available from the selected provider.
@@ -131,9 +102,11 @@ after opening; IDA does not supply `binary_overview`. Consult session availabili
 when composing broader workflows. Modern direct callers and unsupported dossier
 facets remain unknown; live IDA results are not replayed from snapshots.
 
-If the app is missing, ask which app to inspect. Resolve a human-readable app
-name to one clear installed artifact when possible; ask only when matches are
-ambiguous. Never choose an example app on the user's behalf.
+If the user says only "my app" without a name, path, or target already selected
+for this task, ask which app before searching for artifacts. Paths in unrelated
+saved reports and nearby test fixtures do not select the user's target. Resolve
+an actual human-readable app name to one clear installed artifact when possible;
+ask when matches are ambiguous. Never choose an example app on the user's behalf.
 
 In a target-free session, use `open_binary` to bind any archive/package or
 native target whose analysis tool operates on the active target. Do not call an
@@ -144,7 +117,15 @@ list stays complete; availability depends on the operation, target, and host.
 ## Work summary-first
 
 Start with the default result and use its inline Evidence and graph context.
-Do not repeat an identical tool call. Make a focused follow-up only when the
+For a JavaScript application or ELF layout whose size is unknown or large,
+call `analyze_javascript_application` or `inspect_binary_layout` with
+`"detail": "summary"`, then inspect the retained `parent_evidence_id` with
+`inspect_analysis_view`.
+Page module identities and select the returned `node_id` before requesting an
+item; a single file path can represent several graph roles. Do not repeat an
+identical analysis or rejected call without a changed input or resolved blocker.
+Recheck session state when a lifecycle change makes that status useful.
+Make a focused follow-up only when the
 returned result leaves a specific question unanswered.
 
 If MCP reports `resource_constraint` with `details.resource: "transport"`, call
@@ -155,6 +136,24 @@ session to a selected path. The analysis remains complete in the ledger; avoid
 repeating it merely to request the same oversized response. Complete CLI JSON
 output also streams without a single MCP frame.
 
+When the retained parent ID is unknown, use `get_evidence_bundle` with
+`detail: "summary"` and exact filters for operation, target SHA-256,
+analysis-profile digest or canonical procedure address. Select its returned
+Evidence ID for the next view instead of requesting the complete bundle.
+`retention: "complete-record"` means the whole record is stored; native
+value-flow truncation and unknown metadata remain separate. For an exported
+portable bundle, use `rea inspect-evidence-bundle` with JSON containing `path`,
+`detail: "summary"` and the same `filters`. Reading that file still requires
+validating its full contents within the local memory budget.
+
+A client can also truncate a successful tool result without a REA transport
+error. Treat that preview as incomplete; use the retained parent ID for smaller
+views or export when the full record is needed. Do not parse the preview as
+canonical JSON or repeat the producer. For JavaScript, read the
+[module-view and trace recipes](references/javascript-applications.md) before
+drilling into a large graph; a broad bidirectional trace can expand unrelated
+containment relationships even after summary analysis.
+
 Every conclusion must distinguish observations, inferences, and unknowns. Cite
 Evidence IDs, preserve limitations and incomplete coverage, and never imply
 that static analysis observed execution. Runtime requests execute the declared
@@ -162,7 +161,9 @@ target and lifecycle; do not broaden the target or action beyond those fields.
 
 Within the user's requested investigation, call available analysis tools
 directly. REA does not require permission grants or per-call approval flags.
-Follow the declared request scope and the host's actual access requirements.
+The agent client can independently require approval. Follow the declared request
+scope and the host's actual access requirements; use the recovery guide for an
+observed client-policy rejection.
 
 ## Plan broader investigations