rea-agents 6.3.0 → 6.5.0

package/scripts/hopper-demo-x11.py

@@ -10,6 +10,7 @@ import json
 import os
 from pathlib import Path
 import secrets
+import select
 import stat
 import subprocess
 import tempfile
@@ -118,6 +119,7 @@ class XWindowAttributes(ctypes.Structure):
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser()
     parser.add_argument("--probe", action="store_true")
+    parser.add_argument("--owner-stdin", action="store_true")
     parser.add_argument("--hopper")
     parser.add_argument("--socket")
     parser.add_argument(
@@ -133,6 +135,43 @@ def parse_args() -> argparse.Namespace:
     return parser.parse_args()
 
 
+class OwnerLifetime:
+    """The launcher's private pipe is a lifetime capability, independent of PIDs."""
+
+    def __init__(self, enabled: bool) -> None:
+        self._poll = select.poll() if enabled else None
+        if self._poll is not None:
+            # Node/libuv can implement piped stdio with a Unix socket pair.
+            mode = os.fstat(0).st_mode
+            if not (stat.S_ISFIFO(mode) or stat.S_ISSOCK(mode)):
+                raise AdapterFailure(
+                    INVALID_LAUNCH_COMMAND,
+                    "invalid_launch_command",
+                    "owner lifetime requires a private stdin pipe",
+                )
+            self._poll.register(0, select.POLLIN | select.POLLHUP | select.POLLERR)
+
+    def alive(self) -> bool:
+        if self._poll is None:
+            return True
+        for _, events in self._poll.poll(0):
+            if events & (select.POLLHUP | select.POLLERR | select.POLLNVAL):
+                return False
+            if events & select.POLLIN and not os.read(0, 4096):
+                return False
+        return True
+
+
+def wait_for_hopper(child: subprocess.Popen[bytes], owner: OwnerLifetime) -> int:
+    while owner.alive():
+        try:
+            return child.wait(timeout=0.1)
+        except subprocess.TimeoutExpired:
+            continue
+    # run_launch's finally owns cleanup of both direct, unreaped children.
+    return 0
+
+
 def digest(path: Path) -> str:
     value = hashlib.sha256()
     with path.open("rb") as file:
@@ -572,6 +611,7 @@ def start_xvfb(
                     "-auth",
                     str(authority),
                 ],
+                stdin=subprocess.DEVNULL,
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.PIPE,
             )
@@ -627,6 +667,9 @@ def run_launch(args: argparse.Namespace) -> int:
             "invalid_launch_command",
             "missing Hopper launch coordinates",
         )
+    owner = OwnerLifetime(args.owner_stdin)
+    if not owner.alive():
+        return 0
     hopper = Path(args.hopper)
     socket = Path(args.socket)
     try:
@@ -654,6 +697,8 @@ def run_launch(args: argparse.Namespace) -> int:
     child: subprocess.Popen[bytes] | None = None
     display: int | None = None
     try:
+        if not owner.alive():
+            return 0
         hopper_environment = dict(os.environ)
         for name in ("WAYLAND_DISPLAY", "WAYLAND_SOCKET"):
             hopper_environment.pop(name, None)
@@ -666,7 +711,10 @@ def run_launch(args: argparse.Namespace) -> int:
                 "XDG_SESSION_TYPE": "x11",
             }
         )
-        child = subprocess.Popen(command, env=hopper_environment)
+        # Children must not consume or retain REA's lifetime pipe.
+        child = subprocess.Popen(
+            command, env=hopper_environment, stdin=subprocess.DEVNULL
+        )
         leader = os.getpid()
         os.environ["XAUTHORITY"] = str(authority)
 
@@ -702,10 +750,12 @@ def run_launch(args: argparse.Namespace) -> int:
         observed: list[tuple[int, int, int, int, int]] = []
         dialog: tuple[int, int, int, int, int] | None = None
         while time.monotonic() < deadline:
+            if not owner.alive():
+                return 0
             if socket.exists():
                 x11.XCloseDisplay(display)
                 display = None
-                return child.wait()
+                return wait_for_hopper(child, owner)
             if not hopper_is_owned(leader, hopper):
                 if child.poll() is None:
                     time.sleep(0.1)
@@ -749,7 +799,7 @@ def run_launch(args: argparse.Namespace) -> int:
         x11.XFlush(display)
         x11.XCloseDisplay(display)
         display = None
-        return child.wait()
+        return wait_for_hopper(child, owner)
     except AdapterFailure as error:
         raise error.with_stderr(capture)
     finally:

package/scripts/prepack.mjs

@@ -46,6 +46,11 @@ if (await pathExists(join(root, "src"))) {
 } else {
   for (const path of [
     "dist/main.js",
+    "dist/mcp/main.js",
+    "dist/cli-runtime/cli.js",
+    "dist/cli-runtime/cliOutput.js",
+    "dist/cli-runtime/cliResultOutput.js",
+    "dist/cli-runtime/mcpDoctor.js",
     "dist/mcpDoctor.js",
     "dist/cli.js",
     "dist/cliOutput.js",

package/scripts/rea-android-workspace-guardian.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { setTimeout as delay } from "node:timers/promises";
+import { WindowsPrivateRuntime } from "../dist/windows/WindowsPrivateRuntime.js";
+
+if (process.platform !== "win32" || process.argv.length !== 3)
+  throw new Error(
+    "Android workspace guardian requires Windows and one parent directory",
+  );
+
+// This process owns the native directory handle. Detached process creation
+// keeps it alive when the REA owner is terminated without running JS cleanup.
+const runtime = WindowsPrivateRuntime.create(process.argv[2], "rea-android-");
+const ready = await new Promise((resolve) => {
+  process.stdout.once("error", () => resolve(false));
+  process.stdout.write(
+    JSON.stringify({
+      path: runtime.observation.path,
+      volumeSerial: runtime.observation.volumeSerial,
+      fileId: runtime.observation.fileId,
+      privateDacl: runtime.observation.privateDacl,
+    }) + "\n",
+    (error) => resolve(error == null),
+  );
+});
+
+// The owner holds the write end until close/death. A failed readiness pipe
+// also grants cleanup authority, including owner death during startup.
+if (ready) {
+  for await (const _ of process.stdin) {
+    // No commands are accepted; only EOF grants cleanup authority.
+  }
+} else {
+  process.stdin.destroy();
+}
+
+// A failed native walk retains the directory identity lease for a later retry.
+// Keep this process alive so a transient sharing violation cannot orphan it.
+for (;;) {
+  try {
+    await runtime.close();
+    process.exit(0);
+  } catch {
+    await delay(1000);
+  }
+}

package/scripts/rea.mjs

@@ -1,11 +1,11 @@
 #!/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
-// such as `mcp add`, while only dist/main.js may serve the stdio tool catalog.
+// such as `mcp add`, while the MCP runtime serves the stdio tool catalog.
 const args = process.argv.slice(2);
 const { default: packageJson } = await import("../package.json", {
   with: { type: "json" },
@@ -15,11 +15,36 @@ 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)), "..");
+
+// Windows home lookup throws for an empty USERPROFILE. Dependencies resolve
+// home during import, before REA's own resolver can apply its account fallback.
+if (process.platform === "win32" && process.env.USERPROFILE === "") {
+  delete process.env.USERPROFILE;
+}
+
+// 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"]
+  ? ["dist/mcp/main.js"]
   : isMcpDoctorMode
-    ? ["dist/main.js", "dist/mcpDoctor.js"]
-    : ["dist/cli.js", "dist/cliOutput.js", "dist/cli/streamedJsonOutput.js"];
+    ? ["dist/mcp/main.js", "dist/cli-runtime/mcpDoctor.js"]
+    : [
+        "dist/cli-runtime/cli.js",
+        "dist/cli-runtime/cliOutput.js",
+        "dist/cli-runtime/cliResultOutput.js",
+      ];
 
 if (!(await compiledRuntimeExists(runtimeFiles))) {
   process.stderr.write(
@@ -27,10 +52,11 @@ if (!(await compiledRuntimeExists(runtimeFiles))) {
   );
   process.exitCode = 1;
 } else if (isMcpMode) {
-  const { runEntrypoint } = await import("../dist/main.js");
+  const { runEntrypoint } = await import("../dist/mcp/main.js");
   await runEntrypoint();
 } else if (isMcpDoctorMode) {
-  const { runProductionMcpDoctorCli } = await import("../dist/mcpDoctor.js");
+  const { runProductionMcpDoctorCli } =
+    await import("../dist/cli-runtime/mcpDoctor.js");
   const result = await runProductionMcpDoctorCli(args.slice(2), {
     dispatcherPath: fileURLToPath(import.meta.url),
     packageRoot,
@@ -38,21 +64,26 @@ if (!(await compiledRuntimeExists(runtimeFiles))) {
   process.stdout.write(result.output);
   process.exitCode = result.exitCode;
 } else {
-  const { createCli } = await import("../dist/cli.js");
-  const { createStreamedCliJsonOutput } =
-    await import("../dist/cli/streamedJsonOutput.js");
+  const { cliConfigurationError, createCli } =
+    await import("../dist/cli-runtime/cli.js");
+  const { createCliResultOutput } =
+    await import("../dist/cli-runtime/cliResultOutput.js");
   const {
     renderCliOutputArgumentError,
     renderEmptyFilteredCliOutput,
     validateCliOutputArguments,
-  } = await import("../dist/cliOutput.js");
+  } = await import("../dist/cli-runtime/cliOutput.js");
   const outputArguments = validateCliOutputArguments(args);
-  if (!outputArguments.ok) {
+  const configurationError = cliConfigurationError(process.env);
+  if (configurationError !== undefined) {
+    process.stderr.write(`${configurationError}\n`);
+    process.exitCode = 1;
+  } else if (!outputArguments.ok) {
     process.stdout.write(renderCliOutputArgumentError(outputArguments));
     process.exitCode = 1;
   } else {
     let wroteOutput = false;
-    const resultOutput = createStreamedCliJsonOutput(args, process.stdout);
+    const resultOutput = createCliResultOutput(args, process.stdout);
     await createCli(process.env, resultOutput).serve(args, {
       stdout: (output) => {
         if (resultOutput?.handled) {

package/scripts/verify-windows-native-artifact.mjs

@@ -27,9 +27,9 @@ if (
   );
 const offset = bytes.length >= 64 ? bytes.readUInt32LE(0x3c) : bytes.length;
 if (
-  bytes.toString("ascii", 0, 2) !== "MZ" ||
+  bytes.toString("latin1", 0, 2) !== "MZ" ||
   offset > bytes.length - 26 ||
-  bytes.toString("ascii", offset, offset + 4) !== "PE\0\0" ||
+  bytes.toString("latin1", offset, offset + 4) !== "PE\0\0" ||
   bytes.readUInt16LE(offset + 4) !== 0x8664 ||
   bytes.readUInt16LE(offset + 24) !== 0x20b
 )

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: "42"
+  tool_count: 207
 ---
 
 # REA
@@ -26,10 +26,15 @@ 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:
+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.
 
-1. Diagnose without changing files. For Codex, run
-   `npx -y rea-agents@6.3.0 doctor --client codex --json`. Substitute the current
+1. Diagnose without changing REA or client configuration. `npx` may download
+   the package and write to npm's cache. For Codex, run
+   `npx -y rea-agents@6.5.0 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`, `omp`, or `grok_bot`. `grok_bot` has no local
@@ -43,12 +48,12 @@ When tools are absent or registration is stale:
    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@6.3.0 setup --client codex --dry-run --json`.
+   `npx -y rea-agents@6.5.0 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@6.3.0 setup --client codex --yes`. Add `--install-hopper`
+   `npx -y rea-agents@6.5.0 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
@@ -63,13 +68,19 @@ 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@6.3.0 analyze-javascript-application /absolute/path/to/app --json
+npx -y rea-agents@6.5.0 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.
+Prefer an existing `rea` CLI. When none is installed and REA package acquisition
+is within the authorized scope, use `npx -y rea-agents@6.5.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
 
@@ -94,17 +105,88 @@ explicit path or endpoint and do not need it.
   consult the NativeAOT workflow in `references/native-and-artifacts.md` for
   optional metadata recovery and its supported host/layout boundary.
 - User-owned browser page already open: `list_browser_targets`.
-- Retained HAR/native mitmproxy capture: `inspect_web_network_capture`. Select
+- Browser action the agent must perform (click, type, navigate):
+  `capture_browser_scenario` with declared actions. See
+  [runtime observation](references/runtime-observation.md) for connect/launch
+  and the focused follow-up browser tools.
+- Fiddler Everywhere traffic or a native `.saz` capture: read the
+  [Fiddler workflow](references/runtime-observation.md#fiddler-everywhere-traffic-debugging).
+  Inspect saved SAZ with `inspect_web_network_capture` and `format: "saz"`;
+  connect Everywhere's separate MCP server for live traffic.
+- Retained HAR/SAZ/native mitmproxy/aioquic qlog capture: `inspect_web_network_capture`. Select
   original record ordinals when useful; inspect producer fields and byte/number
   sidecars without fetching recorded URLs or claiming live attribution. See
   [historical captures](https://github.com/morluto/rea/blob/main/docs/web-network-captures.md) for the exact upstream
-  profile and credential exclusions.
-- User-owned Electron runtime already open: `list_electron_targets`.
+  profile and credential exclusions. Qlog support starts with aioquic 1.5.0
+  JSON 0.3; stream coverage and endpoint loss declarations do not recover bodies
+  or establish network loss. Prefer detail summary, then kind qlog trace/stream
+  pages; select one trace, stream ID and direction for contribution/range pages.
+  Facts retain all-recorded-events-before-selection scope. Other qlog layouts
+  and PCAP correlation are unsupported.
+- User-owned Electron runtime already open: `list_electron_targets`. Before an electron-main Inspector attempt, check packaged fuses with `inspect_electron_fuses`; disabled `EnableNodeCliInspectArguments` means the app ignores `--inspect`.
+- Packet-field discovery: `inspect_packet_fields` searches installed protocols
+  and field names/types before choosing fields for `inspect_packet_capture`.
+  Query/page the relevant records; registrations do not establish observed traffic.
+- Recorded packet captures: `inspect_packet_capture` with selected TShark fields,
+  display filters and decode-as rules. Requires Linux, util-linux prlimit and `REA_TSHARK_COMMAND`; see
+  [capture guide](https://github.com/morluto/rea/blob/main/docs/packet-captures.md).
+  Packet limits count input packets before filtering. Output defaults to 50 matching
+  frames; use `match_offset` / `match_limit` for later pages, or explicit null
+  limit for complete matching output. Preserve the source digest across pages.
+  This does not perform live capture.
+  For address/DNS/SNI/protocol summaries use `inspect_pcap_capture` with MCP
+  detail summary, then retained kind pcap pages. Requires Wireshark 4.x tshark
+  and capinfos, with Linux prlimit or Windows Job Objects; see
+  [packet summaries](https://github.com/morluto/rea/blob/main/docs/pcap-analysis.md).
+  Select an exact DNS question for address pages; page exhaustion does not prove
+  network completeness. This reads recordings and does not acquire traffic.
+- Decoder discovery: `inspect_signal_decoders` searches installed decoder IDs
+  or selected decoder help, including channels and options. Query and page the
+  relevant details before choosing settings; this does not scan hardware.
+- Recorded logic/signal traces: `decode_signal_recording` with explicit decoder,
+  channel and protocol settings. On Linux with util-linux prlimit, supply sigrok-cli 0.7.2 through
+  `REA_SIGROK_COMMAND`; see [recording guide](https://github.com/morluto/rea/blob/main/docs/signal-recordings.md).
+  Output defaults to 50 literal lines; select annotation classes and page with
+  `line_offset` / `line_limit`, or explicit null for all remaining output.
+  Window counts are display lines, not annotations or samples. Preserve source digests across pages.
+  This reads existing files; it does not acquire hardware signals.
+- Explicit local WebAssembly artifact: `inspect_wasm_artifact`. Supply WABT 1.0.42
+  through `REA_WABT_BIN_DIRECTORY`; retain exact byte/tool identity and decoded WAT.
+  Select JavaScript glue and candidate paths explicitly and preserve URL/path
+  ambiguity. No implicit fetch or target execution; WAT is not original source.
+  See the [WASM guide](https://github.com/morluto/rea/blob/main/docs/wasm-artifacts.md).
 - Explicit local EVM bytecode carrier: `inspect_evm_interface` with caller-selected
   `raw` or `hex` encoding. Preserve carrier/decoded digests and treat selectors,
   argument strings and mutability as inferred candidates; this performs no chain
-  lookup or target execution. See the
+  lookup or target execution. For the complete inferred interface without hex or
+  duplicate stdout, discover support and select `detail: "summary"`; complete
+  Evidence stays retained under its original identity. Use the returned
+  `parent_evidence_id` for exact function or `bytecode_hex`/stdout/stderr pages.
+  Candidate coverage does not establish interface completeness. See the
   [EVM bytecode guide](https://github.com/morluto/rea/blob/main/docs/evm-bytecode.md).
+- Embedded Go compiler, module or build-setting metadata: `inspect_go_binary`
+  with the explicit local file. This built-in target-free inspection requires no
+  Go installation or disassembler. Preserve raw module bytes and source ranges;
+  absent metadata does not prove a binary is not Go, and unparsed text records
+  remain explicit. See the
+  [Go binary guide](https://github.com/morluto/rea/blob/main/docs/go-binaries.md).
+- Embedded cargo-auditable Rust dependency metadata: `inspect_rust_binary`
+  with the explicit local ELF, PE, or thin Mach-O file. This built-in
+  target-free inspection requires no Rust installation or disassembler. Preserve
+  package order, dependency indices, and the section file range. A missing
+  `.dep-v0` section is null metadata, not proof the binary has no dependencies.
+  A rustc commit hash is an inference from a read-only `/rustc/<40-hex>/` path.
+  See the
+  [Rust binary guide](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md).
+
+- Explicit local SQLite database snapshot: `inspect_sqlite_database`. Inspect
+  with Node.js 24.x >=24.15 or 26+ providing native SQLite limits. Read schema
+  first (compact inventory by default), or select an exact ordinary table
+  and `columns` when rows are needed. Defaults are selected-table schema and
+  20 rows; request `schema_scope: "database"` for the complete stored schema. Preserve both database and existing sibling WAL identity; row samples
+  report truncation and have unspecified order. Use a quiescent snapshot rather
+  than assuming a live database/WAL pair was copied atomically. See the
+  [SQLite guide](https://github.com/morluto/rea/blob/main/docs/sqlite-databases.md).
 - Explicit Linux ELF file for offline layout, symbols, relocations or static
   mitigation evidence: `inspect_binary_layout`. This target-free operation uses
   caller-supplied pwntools without opening a disassembler database. Preserve its
@@ -115,6 +197,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,20 +216,36 @@ 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
 unadvertised tool; inspect `binary_session` with `{}` and its
-`result.tool_availability` for availability reasons and remediation. The tool
-list stays complete; availability depends on the operation, target, and host.
+`result.tool_availability` for availability reasons and remediation. Expand each
+group's `names` into entries, inheriting the inventory-level client requirements
+unless the group overrides them. In its closed effect and annotation vocabularies,
+listed flags are true and omitted known flags are false. The grouped name union
+is the complete tool inventory; use `tools/list` for canonical tool schemas.
+Provider candidate facts describe possible providers, while top-level session
+capabilities describe the current route and `analysis_provider_binding` names the
+selected provider. Do not treat those scopes as interchangeable.
 
 ## 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 +256,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 +281,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
 
@@ -207,7 +328,8 @@ as complete while required questions remain open.
   [references/javascript-applications.md](references/javascript-applications.md)
 - Android APK declarations, classes, methods, and static references:
   [references/android-applications.md](references/android-applications.md)
-- Passive browser/Electron observation and static/runtime reconciliation:
+- Browser/Electron observation (passive and scenario) and static/runtime
+  reconciliation:
   [references/runtime-observation.md](references/runtime-observation.md)
 - Evidence paging, comparisons, residual unknowns, and verification:
   [references/evidence-workflows.md](references/evidence-workflows.md)