rea-agents 4.1.0 → 5.0.0

package/dist/application/CapabilityInventory.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { providerCapability, } from "../contracts/toolOutputSchemaPrimitives.js";
-import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
+import { TOOL_CONTRACTS } from "../contracts/toolContracts.js";
 import { clientRequirementsFor, NO_CLIENT_FEATURES, } from "./CapabilityClientRequirements.js";
 const statusSchema = z.object({
     open: z.boolean(),
@@ -55,7 +55,7 @@ const NAVIGATION_CONTEXT_MODES = [
 export const buildCapabilityInventory = (sessionStatus, policy, clientFeatures = NO_CLIENT_FEATURES) => {
     const status = statusSchema.parse(sessionStatus);
     const descriptors = new Map(status.capabilities.map((descriptor) => [descriptor.operation, descriptor]));
-    return GENERATED_MCP_TOOL_CATALOG.map((contract) => {
+    return TOOL_CONTRACTS.map((contract) => {
         const availability = availabilityFor({
             name: contract.name,
             kind: contract.kind,
@@ -107,11 +107,21 @@ export const buildCapabilityInventory = (sessionStatus, policy, clientFeatures =
     }).sort((left, right) => left.name.localeCompare(right.name));
 };
 const availabilityFor = (context) => {
+    // These built-in workflows accept a caller-selected endpoint; they do not load the optional passive provider.
+    if (context.name === "observe_web_execution" ||
+        context.name === "inspect_web_event_listeners")
+        return { reason: "available", remediation: null };
     if (context.name === "get_navigation_context")
         return navigationContextAvailability(context.descriptors);
     const javascriptApplication = javascriptApplicationAvailability(context);
     if (javascriptApplication !== null)
         return javascriptApplication;
+    const failure = optionalProviderFailureFor(context);
+    if (failure !== undefined)
+        return {
+            reason: "provider_unavailable",
+            remediation: `Adapter ${failure.providerId} could not load: ${failure.reason}. Repair the adapter installation and restart REA; other capabilities remain available.`,
+        };
     const workflowAvailability = workflowAvailabilityFor(context);
     if (workflowAvailability !== null)
         return workflowAvailability;
@@ -120,6 +130,20 @@ const availabilityFor = (context) => {
         return targetDecision;
     return providerAvailability(context);
 };
+const optionalProviderFailureFor = ({ name, kind, policy, }) => {
+    const failures = policy.optionalProviderLoadFailures;
+    if (name === "capture_browser_scenario")
+        return failures?.browserScenarioCapture;
+    if (kind === "browser-provider")
+        return failures?.browserObservation;
+    if (name === "capture_electron_scenario")
+        return failures?.electronActiveObservation;
+    if (kind === "electron-provider")
+        return failures?.electronObservation;
+    if (kind === "runtime-provider")
+        return failures?.javascriptRuntimeObservation;
+    return undefined;
+};
 const javascriptApplicationAvailability = ({ name, }) => {
     if (name === "analyze_javascript_application")
         return { reason: "available", remediation: null };
@@ -128,6 +152,40 @@ const javascriptApplicationAvailability = ({ name, }) => {
         : null;
 };
 const workflowAvailabilityFor = ({ name, kind, policy, }) => {
+    if (name === "trace_web_module_imports")
+        return {
+            reason: "available",
+            remediation: null,
+            defaultModeAvailable: policy.webModuleResolutionEnabled === true,
+            modes: [
+                {
+                    name: "sources-without-literal-imports",
+                    available: true,
+                    missing_operations: [],
+                    remediation: null,
+                },
+                policy.webModuleResolutionEnabled === true
+                    ? {
+                        name: "native-literal-resolution",
+                        available: true,
+                        missing_operations: [],
+                        remediation: null,
+                    }
+                    : {
+                        name: "native-literal-resolution",
+                        available: false,
+                        missing_operations: ["native-module-resolver"],
+                        remediation: "Provide an absolute REA_BROWSER_EXECUTABLE supporting import.meta.resolve; no binary target is required.",
+                    },
+            ],
+        };
+    if (name === "recover_javascript_sources")
+        return policy.javascriptRecoveryEnabled === true
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "provider_missing",
+                remediation: "On Linux x64, provide an absolute REA_WAKARU_COMMAND for Wakaru 1.13.0 and util-linux prlimit. No binary target is required.",
+            };
     if (kind === "firmware-provider") {
         const enabled = name === "inspect_firmware_regions"
             ? policy.firmwareInspectionEnabled
@@ -136,7 +194,7 @@ const workflowAvailabilityFor = ({ name, kind, policy, }) => {
             ? { reason: "available", remediation: null }
             : {
                 reason: "provider_missing",
-                remediation: "On Linux, provide an absolute REA_BINWALK_COMMAND (Binwalk 3.1.0) or REA_UNBLOB_COMMAND (Unblob 26.6.4) path and util-linux prlimit. Extraction also requires the selected format’s external extractor.",
+                remediation: "On Linux, provide an absolute REA_BINWALK_COMMAND (Binwalk 3.1.x, verified with 3.1.0) or REA_UNBLOB_COMMAND (Unblob 26.6.x, verified with 26.6.4) path and util-linux prlimit. Extraction also requires the selected format’s external extractor.",
             };
     }
     if (kind === "android-provider")

package/dist/application/ClientConfigurationDocument.js

@@ -39,6 +39,8 @@ const parseDocument = (text, format) => {
         throw new SyntaxError(`Invalid JSON/JSONC at offset ${firstError.offset}: ${printParseErrorCode(firstError.error)}`);
     return objectSchema.parse(document);
 };
+/** Members of OpenCode V2's `mcp` object that are not server names. */
+const OPENCODE_V2_MCP_SETTINGS = new Set(["servers", "timeout"]);
 /** Parse a client document and reject malformed roots or MCP server tables. */
 export const parseClientConfiguration = (text, format) => {
     if (format === undefined || format === "unsupported")
@@ -47,27 +49,76 @@ export const parseClientConfiguration = (text, format) => {
     const serversKey = clientConfigurationServersKey(format);
     const value = document[serversKey];
     const servers = value === undefined ? {} : objectSchema.parse(value);
-    return { document, servers, serversKey };
+    const native = servers.servers;
+    // A V1 server named `servers` has a string `type` discriminator; the V2
+    // table may instead hold a server object named `type`.
+    if (format !== "opencode" ||
+        native === undefined ||
+        (typeof native === "object" &&
+            native !== null &&
+            "type" in native &&
+            typeof native.type === "string"))
+        return {
+            document,
+            servers,
+            serversPath: [serversKey],
+            dialect: format,
+            legacyServers: {},
+        };
+    return {
+        document,
+        servers: objectSchema.parse(native),
+        serversPath: [serversKey, "servers"],
+        dialect: "opencode_v2",
+        legacyServers: Object.fromEntries(Object.entries(servers).filter(([name]) => !OPENCODE_V2_MCP_SETTINGS.has(name))),
+    };
+};
+/** The registration a client loads for `name`, including OpenCode V1 entries. */
+export const effectiveClientServer = (parsed, name) => Object.hasOwn(parsed.servers, name)
+    ? parsed.servers[name]
+    : parsed.legacyServers[name];
+/**
+ * Return `parsed.document` with `servers` at its server table. A legacy OpenCode
+ * V1 member named in `removeLegacy` is removed beside a native V2 table.
+ */
+export const withClientServers = (parsed, servers, removeLegacy) => {
+    const [key = "", nested] = parsed.serversPath;
+    if (nested === undefined)
+        return { ...parsed.document, [key]: servers };
+    const outer = { ...objectSchema.parse(parsed.document[key]) };
+    if (removeLegacy !== undefined && !OPENCODE_V2_MCP_SETTINGS.has(removeLegacy))
+        delete outer[removeLegacy];
+    return { ...parsed.document, [key]: { ...outer, [nested]: servers } };
+};
+/** Read the value at a key path, or `undefined` when any member is absent. */
+const valueAt = (document, path) => {
+    let current = document;
+    for (const key of path) {
+        const object = objectSchema.safeParse(current);
+        if (!object.success || !Object.hasOwn(object.data, key))
+            return undefined;
+        current = object.data[key];
+    }
+    return current;
 };
 /** Serialize a validated client document, retaining JSONC comments. */
-export const serializeClientConfiguration = (document, format, originalText, editedServerName) => {
+export const serializeClientConfiguration = (document, format, originalText, editedPaths) => {
     if (format === undefined || format === "unsupported")
         throw new TypeError("client does not have a supported MCP config format");
     if (format === "toml")
         return stringifyToml(document);
-    if (originalText !== undefined && editedServerName !== undefined) {
-        const serversKey = clientConfigurationServersKey(format);
-        const servers = objectSchema.parse(document[serversKey] ?? {});
-        const editedValue = Object.hasOwn(servers, editedServerName)
-            ? servers[editedServerName]
-            : undefined;
-        const edits = modify(originalText, [serversKey, editedServerName], editedValue, {
+    if (originalText !== undefined && editedPaths !== undefined)
+        return editedPaths.reduce((text, path) => applyEdits(text, modify(text, [...path], valueAt(document, path), {
             formattingOptions: { insertSpaces: true, tabSize: 2, eol: "\n" },
-        });
-        return applyEdits(originalText, edits);
-    }
+        })), originalText);
     return `${JSON.stringify(document, null, 2)}\n`;
 };
+/** Key path of a named registration in the server table. */
+export const clientServerPath = (parsed, name) => [...parsed.serversPath, name];
+/** Key path of a present OpenCode V1 entry beside a native V2 table. */
+export const legacyClientServerPath = (parsed, name) => Object.hasOwn(parsed.legacyServers, name)
+    ? [parsed.serversPath[0] ?? "mcp", name]
+    : undefined;
 /** Build the stdio entry shape expected by one client's configuration dialect. */
 export const clientRegistrationEntry = (format, command, environment) => {
     const [executable = "rea", ...args] = command;
@@ -81,6 +132,15 @@ export const clientRegistrationEntry = (format, command, environment) => {
                     ? {}
                     : { environment: { ...environment } }),
             };
+        case "opencode_v2":
+            // V2 connects servers unless `disabled` is true.
+            return {
+                type: "local",
+                command: [...command],
+                ...(Object.keys(environment).length === 0
+                    ? {}
+                    : { environment: { ...environment } }),
+            };
         case "vscode":
             return {
                 type: "stdio",

package/dist/application/ClientRegistrationStatus.js

@@ -1,4 +1,4 @@
-import { parseClientConfiguration } from "./ClientConfigurationDocument.js";
+import { effectiveClientServer, parseClientConfiguration, } from "./ClientConfigurationDocument.js";
 import { access, readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { z } from "zod";
@@ -36,8 +36,7 @@ export const readClientRegistrationStatuses = async (home, currentCommandPath =
             continue;
         try {
             const content = await readFile(client.configPath, "utf8");
-            const { servers } = parseClientConfiguration(content, client.format);
-            const raw = servers[PRODUCT_IDENTITY.mcpServerKey];
+            const raw = effectiveClientServer(parseClientConfiguration(content, client.format), PRODUCT_IDENTITY.mcpServerKey);
             if (raw === undefined) {
                 statuses.push(unavailableStatus(client.name, client.configPath, "missing"));
                 continue;
@@ -63,11 +62,6 @@ const registrationAligned = (registration, client, currentCommandPath) => {
         return false;
     if (!isOwnedClientRegistrationCommand(command, currentCommandPath))
         return false;
-    if (command.length === 3 &&
-        command[2] === "mcp" &&
-        resolve(command[0] ?? "") === resolve(process.execPath) &&
-        resolve(command[1] ?? "") === currentCommandPath)
-        return true;
     if (client.name === "codex" &&
         registration.startup_timeout_sec !==
             MCP_STARTUP_POLICY.codexStartupTimeoutSeconds)
@@ -80,6 +74,11 @@ const registrationAligned = (registration, client, currentCommandPath) => {
         return false;
     if (client.format === "commandcode" && registration.transport !== "stdio")
         return false;
+    if (command.length === 3 &&
+        command[2] === "mcp" &&
+        resolve(command[0] ?? "") === resolve(process.execPath) &&
+        resolve(command[1] ?? "") === currentCommandPath)
+        return true;
     if (command.length === 4 &&
         command[0] === "npx" &&
         command[1] === "-y" &&

package/dist/application/DirectAnalysis.js

@@ -1,27 +1,25 @@
 import { parseConfig } from "../config.js";
 import { EnhancedTools } from "./EnhancedTools.js";
 import { executeFunctionAnalysisEvidence } from "./FunctionAnalysisEvidence.js";
-import { createBinarySession, createManagedBinarySession } from "./runtime.js";
 import { silentLogger } from "../logger.js";
 import { createEvidence } from "../domain/evidence.js";
-import { isManagedToolName, } from "../contracts/managedToolContracts.js";
+import { isManagedToolName, } from "../contracts/managed/managedToolContracts.js";
 import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import {} from "../domain/analysisErrorBase.js";
 import { access } from "node:fs/promises";
-import { readAnalysisSnapshot, writeAnalysisSnapshot, } from "./AnalysisSnapshotFiles.js";
+import { readAnalysisSnapshot, writeAnalysisSnapshot, } from "./binary/AnalysisSnapshotFiles.js";
 import { parseBinaryTarget } from "./BinaryTargetResolver.js";
 import { snapshotEvidenceForQuery, snapshotMatchesTarget, } from "../domain/analysisSnapshot.js";
 import { err, ok } from "../domain/result.js";
 import { REA_WORKFLOW_PROVIDER, workflowAnalysisProfile, } from "./InvestigationProviders.js";
 import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
-export { runCapabilityStatus, runProviderStatus, } from "./DirectAnalysisStatus.js";
 /**
  * Open one binary, execute one tool, and always release provider resources.
  * Unlike MCP mode, every CLI invocation is intentionally isolated and does not
  * retain a target or provider client for a subsequent command.
  */
-export const runDirectAnalysis = async (path, tool, arguments_, options = {}) => withProcessCancellation(options.signal, (signal) => runAnalysis(path, tool, arguments_, {
+export const runDirectAnalysis = async (dependencies, path, tool, arguments_, options = {}) => withProcessCancellation(options.signal, (signal) => runAnalysis(dependencies, path, tool, arguments_, {
     logger: options.logger ?? silentLogger,
     snapshotPath: options.snapshotPath,
     signal,
@@ -33,16 +31,16 @@ export const runDirectAnalysis = async (path, tool, arguments_, options = {}) =>
         : { providerId: options.providerId }),
 }));
 /** Execute one provider-native semantic operation with atomic provenance. */
-export const runProviderAnalysis = async (...[path, tool, arguments_, logger = silentLogger, signal]) => isManagedToolName(tool)
-    ? runManagedProviderAnalysis(path, tool, signal)
-    : withProcessCancellation(signal, (operationSignal) => runAnalysis(path, tool, arguments_, {
+export const runProviderAnalysis = async (dependencies, ...[path, tool, arguments_, logger = silentLogger, signal]) => isManagedToolName(tool)
+    ? runManagedProviderAnalysis(dependencies, path, tool, signal)
+    : withProcessCancellation(signal, (operationSignal) => runAnalysis(dependencies, path, tool, arguments_, {
         logger,
         snapshotPath: undefined,
         signal: operationSignal,
     }));
 /** Execute managed metadata inspection in an isolated managed-only session. */
-export const runManagedProviderExecution = async (path, tool, signal) => withProcessCancellation(signal, async (operationSignal) => {
-    const session = createManagedBinarySession();
+export const runManagedProviderExecution = async (dependencies, path, tool, signal) => withProcessCancellation(signal, async (operationSignal) => {
+    const session = dependencies.createManagedBinarySession();
     try {
         const opened = await session.open(path, { signal: operationSignal });
         if (!opened.ok)
@@ -53,8 +51,8 @@ export const runManagedProviderExecution = async (path, tool, signal) => withPro
         await session.close();
     }
 });
-const runManagedProviderAnalysis = async (path, tool, signal) => {
-    const execution = await runManagedProviderExecution(path, tool, signal);
+const runManagedProviderAnalysis = async (dependencies, path, tool, signal) => {
+    const execution = await runManagedProviderExecution(dependencies, path, tool, signal);
     if (!execution.ok)
         return cliError(execution.error);
     const value = execution.value;
@@ -67,12 +65,12 @@ const runManagedProviderAnalysis = async (path, tool, signal) => {
         locations: value.locations,
     });
 };
-const runAnalysis = async (path, tool, arguments_, options) => {
+const runAnalysis = async (dependencies, path, tool, arguments_, options) => {
     const { logger, signal, snapshotPath } = options;
     const config = parseConfig(options.environment ?? process.env);
     if (!config.ok)
         return cliError(config.error);
-    const session = createBinarySession(config.value, logger);
+    const session = dependencies.createBinarySession(config.value, logger);
     try {
         const prepared = await prepareSnapshot({
             path,

package/dist/application/DirectAnalysisStatus.js

@@ -3,12 +3,11 @@ import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { createServerIdentity } from "../serverIdentity.js";
 import { silentLogger } from "../logger.js";
-import { createBinarySession } from "./runtime.js";
-const runSessionStatus = async (logger = silentLogger, environment = process.env) => {
+const runSessionStatus = async (dependencies, logger = silentLogger, environment = process.env) => {
     const config = parseConfig(environment);
     if (!config.ok)
         return { error: projectAnalysisError(config.error) };
-    const session = createBinarySession(config.value, logger);
+    const session = dependencies.createBinarySession(config.value, logger);
     try {
         return {
             ...jsonObjectSchema.parse(session.status()),
@@ -22,6 +21,6 @@ const runSessionStatus = async (logger = silentLogger, environment = process.env
     }
 };
 /** List binary-session provider candidates and auxiliary operation availability. */
-export const runProviderStatus = (logger = silentLogger, environment = process.env) => runSessionStatus(logger, environment);
+export const runProviderStatus = (dependencies, logger = silentLogger, environment = process.env) => runSessionStatus(dependencies, logger, environment);
 /** List binary-session operation descriptors; this is not the full MCP catalog. */
-export const runCapabilityStatus = (logger = silentLogger, environment = process.env) => runSessionStatus(logger, environment);
+export const runCapabilityStatus = (dependencies, logger = silentLogger, environment = process.env) => runSessionStatus(dependencies, logger, environment);

package/dist/application/DoctorDiagnostics.js

@@ -1,5 +1,5 @@
 import { homedir } from "node:os";
-import { supportsNodeVersion } from "../domain/runtimeVersion.js";
+import { SUPPORTED_NODE_VERSION_PROSE, supportsNodeVersion, } from "../domain/runtimeVersion.js";
 import { linuxHopperLauncherPath } from "./LinuxHopper.js";
 const DEFAULT_HOPPER = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
 const SYSTEM_LINUX_HOPPER = "/opt/hopper/bin/Hopper";
@@ -52,7 +52,7 @@ export const doctorHealthy = (checks, providers) => {
             providers.providerInspections.some(({ available }) => available)));
 };
 const nodeCheck = (host) => check("node", supportsNodeVersion(host.nodeVersion), host.nodeVersion, {
-    remediation: "Install Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+.",
+    remediation: `Install ${SUPPORTED_NODE_VERSION_PROSE}.`,
     classification: "missing_dependency",
 });
 const hostCheck = async (host) => {
@@ -66,7 +66,7 @@ const hostCheck = async (host) => {
             ? `${host.platform} ${host.architecture}`
             : `${linuxDistribution.id} ${linuxDistribution.versionId ?? "unknown"}`);
     return check("host", supported, detail, {
-        remediation: "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, 64-bit Arch Linux, and the experimental Windows x64 Ghidra P0 boundary.",
+        remediation: "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, 64-bit Arch Linux, CachyOS, and the experimental Windows x64 Ghidra P0 boundary.",
         classification: "unsupported_host",
     });
 };

package/dist/application/EnhancedTools.js

@@ -6,14 +6,14 @@ import {} from "../domain/analysisErrorBase.js";
 import { addressDistance, functionDossierSchema, parseDocuments, parseFunctionDossier, parseListCount, parseRelatedAddresses, parseSegments, } from "../domain/hopperValues.js";
 import { err, ok } from "../domain/result.js";
 import { categorizeSwiftTypes, discoverObjcClasses, discoverObjcProtocols, } from "../domain/symbolAnalysis.js";
-import { inspectNativeDispatch } from "./NativeDispatchMetadataInspection.js";
-import { traceNativeValues } from "./NativeValueTrace.js";
-import { traceNativeUiAction } from "./NativeUiActionTrace.js";
+import { inspectNativeDispatch } from "./native/NativeDispatchMetadataInspection.js";
+import { traceNativeValues } from "./native/NativeValueTrace.js";
+import { traceNativeUiAction } from "./native/NativeUiActionTrace.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { invalidEnhancedInput, } from "./EnhancedToolTypes.js";
 import { traceCallPath } from "./CallPathTracing.js";
 import { traceLiteralFeature } from "./EnhancedLiteralTracing.js";
-import { projectNativeApiInspection } from "./NativeApiInspection.js";
+import { projectNativeApiInspection } from "./native/NativeApiInspection.js";
 /**
  * Composes direct provider operations into bounded reverse-engineering tools.
  * Direct callers use `execute`; adapters that own validation use

package/dist/application/EvidenceBundleCommands.js

@@ -3,7 +3,7 @@ import {} from "../domain/analysisErrorBase.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { compareBundles } from "../domain/bundleComparison.js";
-import { EvidenceLedger } from "./EvidenceLedger.js";
+import { EvidenceLedger } from "./investigation/EvidenceLedger.js";
 import { readEvidenceBundle, writeEvidenceBundle, } from "./EvidenceBundleFiles.js";
 /** Validate and merge one bundle using the session Evidence ledger. */
 export const importEvidenceBundleCommand = async (path) => {

package/dist/application/FilesystemSnapshot.js

@@ -5,6 +5,14 @@ import { dirname, join, relative, resolve } from "node:path";
 const hasSameIdentity = (before, after, expected) => before.dev === after.dev &&
     before.ino === after.ino &&
     (expected === "directory" ? after.isDirectory() : after.isSymbolicLink());
+const hasSameFileState = (before, after) => before.dev === after.dev &&
+    before.ino === after.ino &&
+    before.isFile() &&
+    after.isFile() &&
+    before.mode === after.mode &&
+    before.size === after.size &&
+    before.mtimeMs === after.mtimeMs &&
+    before.ctimeMs === after.ctimeMs;
 const lstatIfPresent = async (path) => {
     try {
         return await lstat(path);
@@ -15,11 +23,17 @@ const lstatIfPresent = async (path) => {
         throw cause;
     }
 };
-const hashFile = async (path, maxBytes, signal) => {
-    const handle = await open(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+/** Hash a file only when its opened descriptor still matches the captured path state. */
+export const hashFile = async (path, expected, maxBytes, signal) => {
+    signal?.throwIfAborted();
+    const handle = await open(path, fsConstants.O_RDONLY |
+        (fsConstants.O_NOFOLLOW ?? 0) |
+        (fsConstants.O_NONBLOCK ?? 0));
     try {
+        signal?.throwIfAborted();
         const stats = await handle.stat();
-        if (!stats.isFile() || stats.size > maxBytes)
+        signal?.throwIfAborted();
+        if (!hasSameFileState(expected, stats) || stats.size > maxBytes)
             return null;
         const hash = createHash("sha256");
         const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes));
@@ -33,7 +47,8 @@ const hashFile = async (path, maxBytes, signal) => {
             position += bytesRead;
         }
         const after = await handle.stat();
-        if (after.size !== stats.size || after.mtimeMs !== stats.mtimeMs)
+        signal?.throwIfAborted();
+        if (!hasSameFileState(stats, after))
             return null;
         return hash.digest("hex");
     }
@@ -76,7 +91,7 @@ export const snapshotRoots = async (scenario, signal) => {
         }
         if (stats.isFile()) {
             const sha256 = remainingBytes >= stats.size
-                ? await hashFile(path, remainingBytes, signal)
+                ? await hashFile(path, stats, remainingBytes, signal)
                 : null;
             remainingBytes -= sha256 === null ? 0 : stats.size;
             if (sha256 === null)

package/dist/application/InvestigationProviders.js

@@ -39,6 +39,12 @@ export const ANDROID_APPLICATION_PROVIDER = {
     name: "REA Android application workflows",
     version: "1",
 };
+/** Provider identity for verified publication of retained website scripts. */
+export const WEB_SCRIPT_EXPORT_PROVIDER = {
+    id: "rea-web-script-export",
+    name: "REA captured script export",
+    version: "1",
+};
 /** Provider identity for deterministic static JavaScript application analysis. */
 export const JAVASCRIPT_APPLICATION_PROVIDER = {
     id: "rea-javascript-application",

package/dist/application/LinuxHopper.js

@@ -9,7 +9,10 @@ import { execFileOutput } from "../process/ExecFileOutput.js";
 const execFileAsync = promisify(execFile);
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
 const MAX_PACKAGE_BYTES = 100_000_000;
-const SUPPORTED_HOPPER_SHA256 = "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded";
+const SUPPORTED_HOPPER_SHA256 = new Set([
+    "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded",
+    "1339f9e58377442b0c6fcb0dfc3cec20d593cc557408521fad9a00dbc6b8da13",
+]);
 const SUPPORTED_RELEASES = {
     deb: {
         filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.deb`,
@@ -58,6 +61,7 @@ export const parseLinuxDistribution = (text) => {
     const packageFamily = packageFamilyFor(id, fields.get("ID_LIKE"));
     const supported = packageFamily !== undefined &&
         (id === "arch" ||
+            id === "cachyos" ||
             (id === "ubuntu" && versionAtLeast(versionId, 24)) ||
             (id === "fedora" && versionAtLeast(versionId, 41)));
     const identity = {
@@ -159,7 +163,7 @@ export const linuxHopperBinarySupported = async (path) => {
         const hash = createHash("sha256");
         for await (const chunk of createReadStream(path))
             hash.update(chunk);
-        return hash.digest("hex") === SUPPORTED_HOPPER_SHA256;
+        return linuxHopperLauncherDigestSupported(hash.digest("hex"));
     }
     catch (cause) {
         // best-effort cleanup: optional build probing; unreadable means unsupported.
@@ -167,6 +171,8 @@ export const linuxHopperBinarySupported = async (path) => {
         return false;
     }
 };
+/** Match a launcher extracted from one of the pinned official Linux packages. */
+export const linuxHopperLauncherDigestSupported = (digest) => SUPPORTED_HOPPER_SHA256.has(digest);
 /** Interpret ldd output conservatively so a present but broken launcher is unhealthy. */
 export const linuxSharedLibrariesAvailable = (output) => !/(?:=>\s+not found|error while loading shared libraries)/iu.test(output);
 const installSystemPackage = async (family, archive) => {

package/dist/application/OptionalObservationProviders.js

@@ -0,0 +1,3 @@
+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+/** Preserve the module's failure reason through the existing tool error algebra. */
+export const optionalProviderUnavailable = (failure, operation) => new AnalysisCapabilityUnavailableError(failure.providerId, operation, `Adapter could not load: ${failure.reason}`);

package/dist/application/ProcessCaptureCapability.js

@@ -1,7 +1,7 @@
 import { tmpdir } from "node:os";
 /** Explain why process capture cannot claim owned-process cleanup on a host. */
 export const processCaptureOwnershipUnavailableReason = (platform) => platform === "win32"
-    ? "Windows process-tree ownership and cleanup are unavailable; REA cannot verify that descendants have stopped."
+    ? "Windows PTY process capture is unavailable because this adapter does not yet verify descendant cleanup. Use Linux (including WSL for Linux commands) or macOS. Reinstalling the PTY backend does not enable native Windows capture."
     : undefined;
 /** Probe the native PTY seam and explain loader failures at their source. */
 export const processCaptureProbeFailureReason = (cause) => {

package/dist/application/ProcessCaptureLifecycle.js

@@ -280,9 +280,9 @@ export const resolveProcessResult = (capture, executionFailure, cleanupFailure)
         throw new ProcessCaptureError("process capture produced no result");
     return capture;
 };
-export const prepareProcessCapture = async (scenario, signal, host = systemProcessPreparationHost) => {
+export const prepareProcessCapture = async (scenario, signal, captureSnapshot = snapshotRoots, host = systemProcessPreparationHost) => {
     assertNotCancelled(signal);
-    const before = await snapshotRoots(scenario, signal);
+    const before = await captureSnapshot(scenario, signal);
     const temporaryRoot = await host.createTemporaryRoot();
     try {
         const runId = randomUUID();

package/dist/application/ProcessCli.js

@@ -114,7 +114,11 @@ const readJson = async (path) => {
         throw new ProcessCliFailure("invalid_input", "Process input file could not be read. Check that the path exists and is readable.");
     }
     try {
-        const parsed = JSON.parse(bytes.toString("utf8"));
+        const text = new TextDecoder("utf-8", {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(bytes);
+        const parsed = JSON.parse(text);
         return parsed;
     }
     catch (cause) {

package/dist/application/ProcessHarness.js

@@ -131,6 +131,15 @@ const finishProcessRun = async (options) => {
     }
     return resolveProcessResult(verifiedCapture, executionFailure, cleanupFailure);
 };
+const normalizeCaptureFailure = (cause, signal) => {
+    if (cause instanceof ProcessCaptureError)
+        return cause;
+    if (signal?.aborted === true &&
+        (cause === signal.reason ||
+            (cause instanceof Error && cause.name === "AbortError")))
+        return processCaptureCancelled();
+    return cause;
+};
 const completeCapture = async (options) => {
     const { runtime, scenario } = options;
     const { reason } = options.exit;
@@ -140,7 +149,7 @@ const completeCapture = async (options) => {
     const samplingPartial = (await runtime.stopSampler()).partial;
     await settleProcessCaptureJournal(options.eventJournal);
     assertNotCancelled(options.signal);
-    const after = await snapshotRoots(scenario, options.signal);
+    const after = await options.captureSnapshot(scenario, options.signal);
     options.recordEvent("filesystem_checkpoints", 1);
     const renderedFrames = await runtime.renderer.frames();
     const checkpoints = [
@@ -185,8 +194,8 @@ const completeCapture = async (options) => {
     });
 };
 /** Execute one caller-selected scenario and return bounded observations. */
-const runProcessScenario = async (scenario, signal, hostEnvironment = process.env, hostPlatform = process.platform) => {
-    const { temporaryRoot, runId, before } = await prepareProcessCapture(scenario, signal);
+const runProcessScenario = async (scenario, signal, hostEnvironment = process.env, hostPlatform = process.platform, captureSnapshot = snapshotRoots) => {
+    const { temporaryRoot, runId, before } = await prepareProcessCapture(scenario, signal, captureSnapshot);
     const frames = [];
     const samples = [];
     const journal = createProcessCaptureJournal();
@@ -239,12 +248,13 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
             initiallyTruncated: before.truncated,
             eventJournal,
             recordEvent,
+            captureSnapshot,
             ...(signal === undefined ? {} : { signal }),
         });
     }
     catch (cause) {
         runtime?.terminal.kill("SIGKILL");
-        executionFailure = cause;
+        executionFailure = normalizeCaptureFailure(cause, signal);
     }
     return finishProcessRun({
         runtime,
@@ -258,18 +268,19 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
     });
 };
 /** Execute one scenario through a typed expected-failure channel. */
-export const captureProcessScenario = async (scenario, signal, platform = process.platform, environment = process.env) => {
+export const captureProcessScenario = async (scenario, signal, platform = process.platform, environment = process.env, captureSnapshot = snapshotRoots) => {
     const ownershipReason = processCaptureOwnershipUnavailableReason(platform);
     if (ownershipReason !== undefined)
-        return err(new AnalysisCapabilityUnavailableError("rea-process", "capture_process_scenario", ownershipReason));
+        return err(new AnalysisCapabilityUnavailableError("rea-process", "capture_process_scenario", ownershipReason, { userMessage: ownershipReason }));
     try {
         assertNotCancelled(signal);
         const resolvedScenario = await resolveProcessScenarioRuntimePaths(scenario, environment);
-        return ok(await runProcessScenario(resolvedScenario, signal, environment, platform));
+        return ok(await runProcessScenario(resolvedScenario, signal, environment, platform, captureSnapshot));
     }
     catch (cause) {
-        return err(cause instanceof ProcessCaptureError
-            ? cause
+        const failure = normalizeCaptureFailure(cause, signal);
+        return err(failure instanceof ProcessCaptureError
+            ? failure
             : new ProcessCaptureError("process capture failed", { cause }));
     }
 };