rea-agents 1.7.0 → 2.0.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, 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.
 
@@ -219,15 +219,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 +239,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,17 +320,19 @@ 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     |     3 | bounded cross-layer traces, unique-only version matching, and approved Linux-isolated extracted-module replay                                                                                                                             |
+| 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.
 
@@ -341,7 +345,10 @@ REA is already useful for native application, browser, and Electron investigatio
 - 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, method-body CIL hashes, 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 remaps build-local tokens using unique CIL/signature and structural method-shape tiers, never names alone. `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 normalized IL commitments 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; native-body bridge mapping and an actual runtime executor remain future managed-code contracts.
 - 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 +393,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
 
@@ -583,7 +590,7 @@ unpacked; REA does not silently accept the mismatched artifact.
 
 ## 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 Ghidra bridge communication uses authenticated private local sockets. 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/dist/application/CapabilityInventory.js

@@ -44,6 +44,7 @@ export const buildCapabilityInventory = (sessionStatus, policy) => {
             available: availability.reason === "available",
             reason: availability.reason,
             remediation: availability.remediation,
+            effects: { ...contract.effects },
             annotations: {
                 read_only: contract.annotations.readOnlyHint ?? false,
                 destructive: contract.annotations.destructiveHint ?? false,
@@ -59,6 +60,23 @@ const availabilityFor = (name, kind, targetOpen, targetKind, descriptors, policy
             reason: "policy_disabled",
             remediation: "Enable or grant process_capture within the administrator ceiling.",
         };
+    if (name === "run_controlled_replay" && !policy.javascriptReplayEnabled)
+        return {
+            reason: "policy_disabled",
+            remediation: "Enable javascript_replay with exact source roots and sandbox executables.",
+        };
+    if (name === "run_controlled_replay")
+        return { reason: "available", remediation: null };
+    if (name === "plan_managed_runtime_correlation" &&
+        !policy.managedRuntimeEnabled)
+        return {
+            reason: "policy_disabled",
+            remediation: "Enable managed_runtime with exact artifact roots and a runtime executable.",
+        };
+    if (name === "plan_managed_runtime_correlation")
+        return { reason: "available", remediation: null };
+    if (kind === "application")
+        return { reason: "available", remediation: null };
     if (name === "import_evidence_bundle" && policy.evidenceFileRoots === 0)
         return {
             reason: "policy_disabled",

package/dist/application/CrossVersionInvestigation.js

@@ -14,16 +14,20 @@ export const runCrossVersionInvestigation = async (input, policy, execution) =>
         return err(new AnalysisInputError("find_changed_behavior", {
             cause: parsed.error,
         }));
-    const initial = await readInvestigationWorkspace(parsed.data.workspace_path, policy);
+    return runCrossVersionInvestigationValidated(parsed.data, policy, execution);
+};
+/** Run input already parsed by a trusted adapter boundary. */
+export const runCrossVersionInvestigationValidated = async (input, policy, execution) => {
+    const initial = await readInvestigationWorkspace(input.workspace_path, policy);
     if (!initial.ok)
         return initial;
-    const preflight = validateWorkspaceRequest(initial.value, parsed.data);
+    const preflight = validateWorkspaceRequest(initial.value, input);
     if (!preflight.ok)
         return preflight;
     if (isCancelled(execution.signal))
         return err(new AnalysisCancelledError("find_changed_behavior"));
-    if (parsed.data.replay_run_id !== undefined) {
-        const replay = selectCompletedInvestigationReplay(initial.value, parsed.data);
+    if (input.replay_run_id !== undefined) {
+        const replay = selectCompletedInvestigationReplay(initial.value, input);
         if (!replay.ok)
             return replay;
         return completeOutcome(replay.value.workspace, replay.value.run, true, execution.session);
@@ -39,7 +43,7 @@ export const runCrossVersionInvestigation = async (input, policy, execution) =>
         total: 4,
         message: "Scanning both version inputs",
     });
-    const snapshots = await scanVersions(parsed.data, execution.inputRoots, execution.signal, execution.integrityContinueEnabled);
+    const snapshots = await scanVersions(input, execution.inputRoots, execution.signal, execution.integrityContinueEnabled);
     if (!snapshots.ok)
         return snapshots;
     await execution.progress?.report({
@@ -49,7 +53,7 @@ export const runCrossVersionInvestigation = async (input, policy, execution) =>
         message: "Version inputs scanned",
     });
     return continueInvestigation({
-        input: parsed.data,
+        input,
         initial: initial.value,
         snapshots: snapshots.value,
         policy,

package/dist/application/Doctor.js

@@ -66,6 +66,9 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
             classification: "config_drift",
         }));
     const providerInspections = await inspectDoctorProviders(host, checks);
+    const javascriptReplayCheck = await host.javascriptReplayCheck?.();
+    if (javascriptReplayCheck !== undefined)
+        checks.push(javascriptReplayCheck);
     if (host.platform === "linux" && hopperPath !== undefined)
         checks.push(check("hopper-demo-runtime", await host.linuxDemoRuntimeReady(), undefined, {
             remediation: "Rerun rea setup to install the Xvfb, xauth, Python, X11, and XTEST packages required for Linux demo sessions.",
@@ -77,7 +80,33 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
             classification: "config_drift",
         }));
     const installationPaths = (await host.installationPaths?.()) ?? [];
-    const installedSkillVersion = await host.installedSkillVersion?.();
+    const observedSkillIdentity = await host.installedSkillIdentity?.();
+    const legacySkillVersion = observedSkillIdentity === undefined
+        ? await host.installedSkillVersion?.()
+        : undefined;
+    const installedSkillIdentity = observedSkillIdentity ??
+        (legacySkillVersion === undefined
+            ? undefined
+            : {
+                version: legacySkillVersion,
+                toolCount: null,
+                catalogDigest: null,
+            });
+    const installedSkillVersion = installedSkillIdentity?.version ?? undefined;
+    const skillAligned = installedSkillIdentity?.version === PRODUCT_IDENTITY.skillVersion &&
+        installedSkillIdentity.toolCount === CATALOG_IDENTITY.counts.mcp_tools &&
+        installedSkillIdentity.catalogDigest ===
+            CATALOG_IDENTITY.digests.combined_sha256;
+    if (!skillAligned)
+        checks.push({
+            name: "skill:identity",
+            ok: false,
+            classification: "config_drift",
+            detail: installedSkillIdentity === undefined
+                ? "Installed REA skill identity is missing."
+                : "Installed REA skill identity is stale.",
+            remediation: "Run rea setup to update the installed REA skill.",
+        });
     const registrations = (await host.clientRegistrations?.()) ?? [];
     for (const registration of registrations)
         if (registration.state !== "aligned")
@@ -120,13 +149,14 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
             },
             skill: {
                 installed_version: installedSkillVersion ?? null,
-                state: installedSkillVersion === undefined
-                    ? "unknown"
-                    : installedSkillVersion === PRODUCT_IDENTITY.skillVersion
+                installed_tool_count: installedSkillIdentity?.toolCount ?? null,
+                installed_catalog_digest: installedSkillIdentity?.catalogDigest ?? null,
+                state: installedSkillIdentity === undefined
+                    ? "missing"
+                    : skillAligned
                         ? "aligned"
                         : "stale",
-                remediation: installedSkillVersion === undefined ||
-                    installedSkillVersion === PRODUCT_IDENTITY.skillVersion
+                remediation: skillAligned
                     ? null
                     : "Run rea setup to update the installed REA skill.",
             },
@@ -220,6 +250,9 @@ export const systemDoctorHost = (options = {}) => ({
     ...(options.providerInspections === undefined
         ? {}
         : { providerInspections: options.providerInspections }),
+    ...(options.javascriptReplayCheck === undefined
+        ? {}
+        : { javascriptReplayCheck: options.javascriptReplayCheck }),
     async installationPaths() {
         try {
             const command = process.platform === "win32" ? "where" : "which";
@@ -239,6 +272,23 @@ export const systemDoctorHost = (options = {}) => ({
             return undefined;
         }
     },
+    async installedSkillIdentity() {
+        try {
+            const content = await readFile(join(homedir(), ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md"), "utf8");
+            const version = /^\s{2}version:\s*"([^"]+)"\s*$/mu.exec(content)?.[1] ?? null;
+            const countText = /^\s{2}tool_count:\s*(\d+)\s*$/mu.exec(content)?.[1];
+            const catalogDigest = /^\s{2}catalog_digest:\s*"([a-f0-9]{64})"\s*$/mu.exec(content)?.[1] ??
+                null;
+            return {
+                version,
+                toolCount: countText === undefined ? null : Number.parseInt(countText, 10),
+                catalogDigest,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    },
     clientRegistrations: () => readClientRegistrationStatuses(homedir()),
 });
 const parseMajor = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);

package/dist/application/ElectronBoundaryAnalysis.js

@@ -0,0 +1,96 @@
+import { resolveArtifactPath } from "./JavaScriptArtifactGraphContext.js";
+/** Flatten all per-file IPC facts into deterministic application records. */
+export const collectElectronIpcRecords = (analysis) => analysis.files
+    .flatMap(({ file, javascript }) => (javascript?.electron.ipc ?? []).map((finding) => ({
+    key: ipcRecordKey(file.path, finding),
+    file,
+    finding,
+})))
+    .sort((left, right) => compareCodePoints(left.key, right.key));
+/** Match only exact literal channels and retain ambiguous matches separately. */
+export const classifyElectronIpcPairings = (records) => {
+    const handlers = records.filter(isMainHandler);
+    return records.filter(isPairableRendererTransmission).map((transmission) => {
+        const candidates = transmission.finding.channel === null
+            ? []
+            : handlers.filter((handler) => handler.finding.channel === transmission.finding.channel &&
+                compatibleIpcModes(transmission.finding, handler.finding));
+        return {
+            transmission,
+            candidates,
+            status: candidates.length === 1
+                ? "paired"
+                : candidates.length > 1
+                    ? "ambiguous"
+                    : "unpaired",
+        };
+    });
+};
+/** Return only pairings supported by one unique literal main handler. */
+export const unambiguousElectronIpcPairings = (records) => classifyElectronIpcPairings(records).flatMap((state) => {
+    const handler = state.candidates[0];
+    return state.status === "paired" && handler !== undefined
+        ? [{ transmission: state.transmission, handler }]
+        : [];
+});
+/** Summarize static Electron findings without treating gaps as absence. */
+export const summarizeElectronBoundaries = (analysis) => {
+    const files = new Map(analysis.files.map(({ file }) => [file.path, file]));
+    const javascript = analysis.files.flatMap(({ javascript: value }) => value === null ? [] : [value]);
+    const windows = javascript.flatMap(({ electron }) => electron.browser_windows);
+    const bridges = javascript.flatMap(({ electron }) => electron.context_bridge_apis);
+    const validations = javascript.flatMap(({ electron }) => electron.sender_validations);
+    const utilities = analysis.files.flatMap(({ file, javascript: value }) => (value?.electron.utility_processes ?? []).map((finding) => ({
+        file,
+        finding,
+    })));
+    const nativeBindings = analysis.files.flatMap(({ file, javascript: value }) => (value?.electron.native_addon_bindings ?? []).map((finding) => ({
+        file,
+        finding,
+    })));
+    const ipc = collectElectronIpcRecords(analysis);
+    const pairing = classifyElectronIpcPairings(ipc);
+    const literalChannels = new Set(ipc.flatMap(({ finding }) => finding.channel === null ? [] : [finding.channel]));
+    return {
+        browser_windows: windows.length,
+        explicit_web_preferences: windows.reduce((count, window) => count + window.web_preferences.length, 0),
+        preload_entrypoints: windows.filter(({ preload_path: path }) => path !== null).length,
+        context_bridge_apis: bridges.length,
+        exposed_api_members: bridges.reduce((count, bridge) => count + bridge.members.length, 0),
+        ipc: {
+            operations: ipc.length,
+            literal_channels: literalChannels.size,
+            dynamic_channel_operations: ipc.filter(({ finding }) => finding.channel === null).length,
+            renderer_transmissions: ipc.filter(isRendererTransmission).length,
+            renderer_listeners: ipc.filter(({ finding }) => finding.side === "renderer" && finding.mode === "listen").length,
+            main_handlers: ipc.filter(isMainHandler).length,
+            paired_renderer_transmissions: pairing.filter(({ status }) => status === "paired").length,
+            ambiguous_renderer_transmissions: pairing.filter(({ status }) => status === "ambiguous").length,
+            unpaired_literal_renderer_transmissions: pairing.filter(({ status, transmission }) => status === "unpaired" && transmission.finding.channel !== null).length,
+        },
+        sender_validation_observations: validations.length,
+        utility_processes: utilities.length,
+        resolved_utility_entrypoints: utilities.filter(({ file, finding }) => resolvesToFile(file, finding.module_path, files)).length,
+        native_addon_bindings: nativeBindings.length,
+        resolved_native_addon_bindings: nativeBindings.filter(({ file, finding }) => resolvesToFile(file, finding.specifier, files, "native-addon")).length,
+    };
+};
+const compatibleIpcModes = (transmission, handler) => transmission.mode === "invoke"
+    ? handler.mode === "handle"
+    : transmission.operation === "send-to-host"
+        ? false
+        : transmission.mode === "send" && handler.mode === "listen";
+const isRendererTransmission = ({ finding }) => finding.side === "renderer" &&
+    (finding.mode === "send" || finding.mode === "invoke");
+const isPairableRendererTransmission = (record) => isRendererTransmission(record) && record.finding.operation !== "send-to-host";
+const isMainHandler = ({ finding }) => finding.side === "main" &&
+    (finding.mode === "listen" || finding.mode === "handle");
+const resolvesToFile = (file, specifier, files, kind) => {
+    if (specifier === null)
+        return false;
+    const resolved = resolveArtifactPath(specifier, file.path, files);
+    return (resolved !== null &&
+        (kind === undefined || files.get(resolved)?.kind === kind));
+};
+const ipcRecordKey = (path, finding) => `${path}\0${String(finding.location.start.line)}:${String(finding.location.start.column)}\0${finding.side}\0${finding.operation}`;
+const compareCodePoints = (left, right) => left < right ? -1 : left > right ? 1 : 0;

package/dist/application/ElectronBoundaryGraph.js

@@ -0,0 +1,9 @@
+import { addElectronIpcBoundaries } from "./ElectronBoundaryGraphIpc.js";
+import { addElectronNativeBoundaries } from "./ElectronBoundaryGraphNative.js";
+import { addElectronWindowBoundaries } from "./ElectronBoundaryGraphWindows.js";
+/** Add every static Electron process and security-boundary fact to the JAG. */
+export const addElectronBoundaries = (context) => {
+    addElectronWindowBoundaries(context);
+    addElectronIpcBoundaries(context);
+    addElectronNativeBoundaries(context);
+};

package/dist/application/ElectronBoundaryGraphContext.js

@@ -0,0 +1,62 @@
+import { sha256Text } from "../domain/javascriptStaticAnalysisHelpers.js";
+import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+/** Resolve the file or recovered bundle module that owns one finding. */
+export const electronFindingSourceNode = (context, file, moduleKey) => moduleKey === null
+    ? (context.assetNodes.get(file.path) ?? context.fileNodes.get(file.path))
+    : context.moduleNodes.get(`${file.path}\0${moduleKey}`);
+/** Observation-scoped identity shared safely across different artifact files. */
+export const electronObservationIdentity = (context, scope, key) => ({
+    strategy: "observation-fingerprint",
+    stability: "observation-only",
+    observation_sha256: sha256Text(`${context.snapshot.manifest.root_sha256}\0${scope}\0${key}`),
+    scope: scope.slice(0, 4_096),
+});
+/** Add a direct AST syntax relationship. */
+export const addElectronAstEdge = (context, input) => {
+    context.accumulator.addEdge({
+        source_node_id: input.source.node_id,
+        target_node_id: input.target.node_id,
+        relation: input.relation,
+        properties: input.properties,
+        evidence: astObservationEvidence({
+            sha256: input.file.sha256,
+            path: input.file.path,
+            range: input.range,
+            operation: input.operation,
+            coverage: input.coverage,
+            ...(input.limitations === undefined
+                ? {}
+                : { limitations: input.limitations }),
+        }),
+    });
+};
+/** Add an Electron relationship that static syntax suggests but cannot prove. */
+export const addElectronInferenceEdge = (context, input) => {
+    context.accumulator.addEdge({
+        source_node_id: input.source.node_id,
+        target_node_id: input.target.node_id,
+        relation: input.relation,
+        properties: input.properties,
+        evidence: staticInferenceEvidence({
+            sha256: input.file.sha256,
+            path: input.file.path,
+            range: input.range,
+            operation: input.operation,
+            coverage: input.coverage,
+            ...(input.confidence === undefined
+                ? {}
+                : { confidence: input.confidence }),
+            ...(input.limitations === undefined
+                ? {}
+                : { limitations: input.limitations }),
+        }),
+    });
+};
+/** Deterministic source-range key for artifact-local graph identities. */
+export const electronRangeKey = (range) => `${String(range.start.line)}:${String(range.start.column)}-${String(range.end.line)}:${String(range.end.column)}`;
+/** Test exact source-range containment without assuming runtime reachability. */
+export const electronRangeContains = (outer, inner) => comparePoint(outer.start, inner.start) <= 0 &&
+    comparePoint(outer.end, inner.end) >= 0;
+const comparePoint = (left, right) => left.line === right.line
+    ? left.column - right.column
+    : left.line - right.line;