rea-agents 4.1.0 → 6.0.0

package/dist/application/DirectAnalysis.js

@@ -1,27 +1,26 @@
 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 { analysisProfileSchema, committedProviderSchema, } from "../domain/analysisProfile.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 +32,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 +52,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 +66,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,
@@ -84,7 +83,42 @@ const runAnalysis = async (path, tool, arguments_, options) => {
         if (!prepared.ok)
             return cliError(prepared.error);
         const { snapshot } = prepared.value;
-        const opened = await session.open(path, {
+        let resolvedTarget;
+        if (snapshot !== undefined && prepared.value.target !== undefined) {
+            const preview = await session.previewTarget(prepared.value.target, {
+                signal,
+                snapshot,
+                ...(options.formatHint === undefined
+                    ? {}
+                    : { formatHint: options.formatHint }),
+                ...(options.providerId === undefined
+                    ? {}
+                    : { providerId: options.providerId }),
+            });
+            if (!preview.ok)
+                return cliError(preview.error);
+            resolvedTarget = preview.value;
+            const route = preview.value.route;
+            const bindingProfile = route.profile ?? undefined;
+            const evidenceProfile = analysisProfileForRoute(route, tool);
+            if (bindingProfile !== undefined &&
+                evidenceProfile !== undefined &&
+                allowsSnapshotReplay(route, tool)) {
+                const cached = snapshotEvidenceForQuery(snapshot, {
+                    target: preview.value.target,
+                    bindingProfile,
+                    operation: tool,
+                    parameters: arguments_,
+                    provider: isWorkflowEvidenceTool(tool)
+                        ? REA_WORKFLOW_PROVIDER
+                        : providerIdentityForRoute(route, tool),
+                    evidenceProfile,
+                });
+                if (cached !== undefined)
+                    return cached;
+            }
+        }
+        const openOptions = {
             signal,
             ...(options.formatHint === undefined
                 ? {}
@@ -93,26 +127,13 @@ const runAnalysis = async (path, tool, arguments_, options) => {
             ...(options.providerId === undefined
                 ? {}
                 : { providerId: options.providerId }),
-        });
+        };
+        const opened = resolvedTarget === undefined
+            ? await session.open(path, openOptions)
+            : await session.openResolvedTarget(resolvedTarget, openOptions);
         if (!opened.ok)
             return cliError(opened.error);
         const evidenceProfile = analysisProfileForEvidence(session, tool);
-        const bindingProfile = session.analysisProfile();
-        if (canReplayDirectTool(session, tool) &&
-            snapshot !== undefined &&
-            evidenceProfile !== undefined &&
-            bindingProfile !== undefined) {
-            const cached = snapshotEvidenceForQuery(snapshot, {
-                target: opened.value,
-                bindingProfile,
-                operation: tool,
-                parameters: arguments_,
-                provider: replayProviderFor(session, tool),
-                evidenceProfile,
-            });
-            if (cached !== undefined)
-                return cached;
-        }
         const { output, evidence } = await executeAnalysisTool({
             session,
             openedTarget: opened.value,
@@ -123,6 +144,37 @@ const runAnalysis = async (path, tool, arguments_, options) => {
         });
         if (evidence !== undefined)
             session.recordEvidence(evidence);
+        if (isWorkflowEvidenceTool(tool) &&
+            tool !== "trace_native_ui_action" &&
+            snapshotPath !== undefined &&
+            evidence !== undefined &&
+            "analysis_profile" in evidence &&
+            session.allowsSnapshotReplay(tool)) {
+            const recorded = session.recordWorkflowSnapshot({
+                operation: tool,
+                parameters: arguments_,
+                execution: {
+                    result: evidence.normalized_result,
+                    rawResult: evidence.raw_result,
+                    provider: committedProviderSchema.parse(evidence.provider),
+                    analysisProfile: analysisProfileSchema.parse(evidence.analysis_profile),
+                    limitations: evidence.limitations,
+                    locations: evidence.locations,
+                    subject: evidence.subject === null
+                        ? null
+                        : {
+                            path: evidence.subject.local_path,
+                            sha256: evidence.subject.digest.sha256,
+                            format: evidence.subject.format,
+                            ...(evidence.subject.architecture === null
+                                ? {}
+                                : { architecture: evidence.subject.architecture }),
+                        },
+                },
+            });
+            if (!recorded.ok)
+                return cliError(recorded.error);
+        }
         if (tool !== "trace_native_ui_action" &&
             snapshotPath !== undefined &&
             evidence !== undefined) {
@@ -139,7 +191,6 @@ const runAnalysis = async (path, tool, arguments_, options) => {
         await session.close();
     }
 };
-const canReplayDirectTool = (session, tool) => tool !== "trace_native_ui_action" && session.allowsSnapshotReplay(tool);
 const executeAnalysisTool = async (input) => {
     const { session, tool, signal, evidenceProfile } = input;
     if (tool === "analyze_function") {
@@ -214,11 +265,32 @@ const prepareSnapshot = async (options) => {
         return target;
     if (!snapshotMatchesTarget(loaded.value.target, target.value))
         return err(new EvidenceIntegrityError("Analysis snapshot target does not match the requested binary"));
-    return ok({ snapshot: loaded.value });
+    return ok({ snapshot: loaded.value, target: target.value });
+};
+const allowsSnapshotReplay = (route, tool) => {
+    if (tool === "trace_native_ui_action")
+        return false;
+    const descriptor = route.capabilities?.get(tool);
+    return descriptor === undefined
+        ? ![...(route.capabilities?.values() ?? [])].some(({ cachePolicy }) => cachePolicy === "live")
+        : descriptor.cachePolicy !== "live";
+};
+const analysisProfileForRoute = (route, tool) => {
+    const profile = route.profile;
+    if (profile === null || profile === undefined)
+        return undefined;
+    if (isWorkflowEvidenceTool(tool))
+        return workflowAnalysisProfile(profile);
+    const provider = providerIdentityForRoute(route, tool);
+    return provider.id === profile.provider.id ? profile : undefined;
+};
+/** Mirror BinarySession.providerIdentity for a route not opened yet. */
+const providerIdentityForRoute = (route, operation) => {
+    const selected = route.capabilities?.get(operation)?.provider ?? route.identity;
+    return route.profile?.provider.id === selected.id
+        ? route.profile.provider
+        : selected;
 };
-const replayProviderFor = (session, tool) => isWorkflowEvidenceTool(tool)
-    ? REA_WORKFLOW_PROVIDER
-    : session.providerIdentity(tool);
 const analysisProfileForEvidence = (session, tool) => {
     if (!isWorkflowEvidenceTool(tool))
         return session.analysisProfile(tool);

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/EvidenceBundleFiles.js

@@ -1,7 +1,7 @@
 import { parseEvidenceBundle, serializeEvidenceBundle, } from "../domain/evidenceBundle.js";
 import { EvidenceFileError, EvidenceIntegrityError, } from "../domain/evidenceErrors.js";
 import { err, ok } from "../domain/result.js";
-import { parseProcessCapture } from "../domain/processCapture.js";
+import { parseProcessCapture } from "../domain/process/processCapture.js";
 import { readJsonFile, writeTextFile } from "./JsonFiles.js";
 /** Read and validate an evidence bundle at the caller-supplied path. */
 export const readEvidenceBundle = async (path) => {

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/ReconstructionCoverageService.js

@@ -1,13 +1,9 @@
-import { z } from "zod";
+import { reconstructionCoverageEvaluationInputSchema } from "../domain/reconstructionCoverageInput.js";
 import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import {} from "../domain/analysisErrorBase.js";
-import { evaluateReconstructionClosure, reconstructionCoverageDataSchema, } from "../domain/reconstructionCoverage.js";
+import { evaluateReconstructionClosure } from "../domain/reconstructionCoverage.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
-export const reconstructionCoverageEvaluationInputSchema = z.strictObject({
-    coverage: reconstructionCoverageDataSchema,
-    boundary_id: z.string().min(1),
-});
 /** Evaluate inline reconstruction coverage against a named boundary. */
 export const evaluateReconstructionCoverage = (rawInput, nowEpochMs = Date.now()) => {
     const parsed = reconstructionCoverageEvaluationInputSchema.safeParse(rawInput);

package/dist/application/ReconstructionObligationCandidates.js

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { parseEvidenceBundle, } from "../domain/evidenceBundle.js";
-import { parseProcessCapture } from "../domain/processCapture.js";
-import { parseApplicationGraphEvidence } from "./JavaScriptApplicationEvidenceGraph.js";
+import { parseProcessCapture } from "../domain/process/processCapture.js";
+import { parseApplicationGraphEvidence } from "./javascript/JavaScriptApplicationEvidenceGraph.js";
 import { applicationObligationPolicy, semanticObligationPolicy, } from "./ReconstructionObligationPolicies.js";
 /** Derive conservative candidates from graph, process, and reviewed inputs. */
 export const deriveReconstructionObligationCandidates = (bundleInput, reviewed) => {
@@ -32,8 +32,11 @@ const deriveApplicationCandidates = (evidence, records, candidates, limitations)
         const source = parseApplicationGraphEvidence(evidence);
         for (const node of source.graph.nodes) {
             const candidatePolicy = applicationObligationPolicy(node.kind);
-            if (candidatePolicy === undefined)
+            if (candidatePolicy === undefined) {
+                if (node.kind === "unknown")
+                    limitations.add(`Application graph ${source.graph.graph_id} contains unresolved node ${node.node_id}; reconstruction obligations remain unknown.`);
                 continue;
+            }
             const reference = node.observations.map((observation) => graphReference(evidence, records, observation.evidence, `${source.graph.graph_id}/node/${node.node_id}/observation/${observation.observation_id}`));
             addCandidate(candidates, generatedCandidate({
                 key: `application:${node.node_id}:${candidatePolicy.family}`,
@@ -98,6 +101,10 @@ const deriveProcessCandidate = (evidence, candidates, limitations) => {
                 ]
                 : []),
         ];
+        if (capture.manifest.executable_sha256 === null) {
+            limitations.add(`Process capture ${evidence.evidence_id} has no validated executable artifact identity; packaged-process lifecycle obligation was not bound to an artifact.`);
+            return;
+        }
         addCandidate(candidates, {
             obligation_id: obligationId(`process:${capture.manifest.executable_sha256}:${capture.manifest.full_scenario_sha256}`),
             obligation_version: 1,

package/dist/application/ReferenceSourceImport.js

@@ -106,6 +106,8 @@ export const importReferenceSource = async (options) => {
         const error = readResult.error;
         if (error.code === "cancelled")
             return err(cancelled());
+        if (error.code === "unsupported")
+            return err(failure("unsupported", error.message));
         return err(failure("io", error.message));
     }
     if (isAborted(options.signal))

package/dist/application/ReferenceSourceImportEntries.js

@@ -3,12 +3,13 @@ import { posix } from "node:path";
 import { classifyReferenceSourcePath, detectReferenceSourceLanguage, } from "../domain/referenceSourceClassification.js";
 import { parseReferenceSourceImports } from "../domain/referenceSourceImportParsing.js";
 import { PARSEABLE_REFERENCE_SOURCE_LANGUAGES } from "./ReferenceSourceImportTypes.js";
-/** Project a low-level entry failure into safe import guidance. */
-export const projectReferenceSourceEntryFailure = (entry) => {
+/** Preserve the observed reader failure and add entry-specific recovery guidance. */
+export const projectReferenceSourceEntryFailure = (entry) => `${entry.message} ${entryRecoveryGuidance(entry)}`;
+const entryRecoveryGuidance = (entry) => {
     if (entry.code === "cancelled")
         return "This entry was not read because the import was cancelled. Start the import again when ready.";
     if (entry.code === "unsupported")
-        return "This entry cannot be read safely on this system. Exclude it or import the directory on a supported system.";
+        return "Exclude this entry or replace it with a regular file.";
     if (entry.kind === "directory")
         return "This directory could not be read. Check its permissions, then try again.";
     if (entry.kind === "symlink")
@@ -58,6 +59,22 @@ const resolveInternalSpecifier = (fromPath, specifier, filePaths) => {
         `${normalized}${suffix}`,
         `${normalized}/index${suffix}`,
     ]);
+    // TypeScript source commonly names the extension emitted for NodeNext.
+    // Retain present runtime files first; substitute only a missing counterpart.
+    // Counterparts cover explicit filenames, not directory/index resolution.
+    if (/\.(?:ts|tsx|mts|cts)$/u.test(fromPath)) {
+        const sourceSuffixes = normalized.endsWith(".js")
+            ? [".ts", ".tsx", ".d.ts"]
+            : normalized.endsWith(".mjs")
+                ? [".mts", ".d.mts"]
+                : normalized.endsWith(".cjs")
+                    ? [".cts", ".d.cts"]
+                    : normalized.endsWith(".jsx")
+                        ? [".tsx", ".d.ts"]
+                        : [];
+        const stem = normalized.slice(0, -posix.extname(normalized).length);
+        candidates.push(...sourceSuffixes.map((suffix) => `${stem}${suffix}`));
+    }
     const match = candidates.find((candidate) => filePaths.has(candidate));
     return match === undefined
         ? { to: normalized, resolution: "unresolved" }

package/dist/application/ReferenceSourceImportTypes.js

@@ -10,6 +10,11 @@ export const projectReferenceSourceImportError = (error) => {
             category: "invalid_input",
             message: "Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",
         };
+    if (error.code === "unsupported")
+        return {
+            category: "unsupported_host",
+            message: "Safe no-follow file opens are unavailable on this host. Import the source tree with REA on Linux (including WSL) or macOS.",
+        };
     if (error.code === "io")
         return {
             category: "execution_failure",

package/dist/application/Setup.js

@@ -12,14 +12,22 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     const unsupported = await hostRemediation(host, false);
     if (unsupported !== undefined)
         return fail(unsupported);
-    let hopperPath = await host.hopperPath();
-    let providerEnvironment = await initialProviderEnvironment(host, hopperPath);
+    const initialState = await host.initialSetupState?.(options.readinessScope);
+    let hopperPath = initialState === undefined
+        ? await host.hopperPath()
+        : initialState.hopperPath;
+    let providerEnvironment = initialState === undefined
+        ? await initialProviderEnvironment(host, hopperPath)
+        : initialState.providerEnvironment;
     const discovery = await discoverSetupState({
         host,
         providerEnvironment,
         forceHopperInstall: options.installHopper,
         proposeHopper: options.proposeHopper ?? (confirm !== undefined && !options.structured),
         doctorScope: options.readinessScope,
+        ...(initialState === undefined
+            ? {}
+            : { initialDoctor: initialState.doctor }),
     });
     clientStates = discovery.clientStates;
     const clientSelectionAllowed = options.clientIds === undefined &&

package/dist/application/SetupClientConfiguration.js

@@ -1,4 +1,4 @@
-import { clientRegistrationEntry, clientConfigurationValuesEqual, parseClientConfiguration, serializeClientConfiguration, } from "./ClientConfigurationDocument.js";
+import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerPath, legacyClientServerPath, parseClientConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
 import { constants as fsConstants } from "node:fs";
 import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -43,21 +43,23 @@ const configureClientDocument = async (client, environment, command, format) =>
         void cause;
         return { status: "failed", reason: "readback" };
     }
-    const { document, servers, serversKey } = parsed;
-    const desired = clientConfigurationDesired(client, environment, command, format);
-    if (clientConfigurationValuesEqual(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+    const desired = clientConfigurationDesired(client, environment, command, parsed.dialect);
+    if (registrationCurrent(parsed, desired))
         return { status: "unchanged" };
     const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
     if (backupPath !== undefined &&
         !(await preserveConfigBackup(transactionPath, backupPath)))
         return { status: "failed", reason: "backup" };
-    document[serversKey] = {
-        ...servers,
-        [PRODUCT_IDENTITY.mcpServerKey]: desired,
-    };
+    // A native OpenCode V2 entry replaces REA's legacy V1 entry, which would
+    // otherwise conflict with it.
+    const legacyPath = legacyClientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey);
+    const document = withClientServers(parsed, { ...parsed.servers, [PRODUCT_IDENTITY.mcpServerKey]: desired }, PRODUCT_IDENTITY.mcpServerKey);
     try {
         await mkdir(dirname(client.configPath), { recursive: true });
-        await writeFileAtomic(transactionPath, serializeClientConfiguration(document, format, original, PRODUCT_IDENTITY.mcpServerKey), {
+        await writeFileAtomic(transactionPath, serializeClientConfiguration(document, format, original, [
+            clientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey),
+            ...(legacyPath === undefined ? [] : [legacyPath]),
+        ]), {
             encoding: "utf8",
             mode: 0o600,
         });
@@ -69,7 +71,7 @@ const configureClientDocument = async (client, environment, command, format) =>
     }
     try {
         const readback = parseClientConfiguration(await readFile(transactionPath, "utf8"), format);
-        if (!clientConfigurationValuesEqual(readback.servers[PRODUCT_IDENTITY.mcpServerKey], desired)) {
+        if (!registrationCurrent(readback, desired)) {
             await restoreConfig(transactionPath, original);
             return { status: "failed", reason: "readback" };
         }
@@ -87,11 +89,10 @@ const configureClientDocument = async (client, environment, command, format) =>
 };
 /** Determine whether an existing client configuration matches the desired registration. */
 export const clientConfigurationAligned = async (client, providerEnvironment, command) => {
-    const desired = clientConfigurationDesired(client, providerEnvironment, command, client.format);
     try {
         const original = await readFile(client.configPath, "utf8");
-        const { servers } = parseClientConfiguration(original, client.format);
-        return clientConfigurationValuesEqual(servers[PRODUCT_IDENTITY.mcpServerKey], desired);
+        const parsed = parseClientConfiguration(original, client.format);
+        return registrationCurrent(parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed.dialect));
     }
     catch (cause) {
         // Unreadable configuration is treated as not aligned so setup repairs it.
@@ -121,10 +122,10 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
             remediation: "The configuration file could not be read. Check its permissions before rerunning setup.",
         };
     }
-    const desired = clientConfigurationDesired(client, providerEnvironment, command, client.format);
     try {
-        const { servers } = parseClientConfiguration(original, client.format);
-        if (clientConfigurationValuesEqual(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+        const parsed = parseClientConfiguration(original, client.format);
+        const desired = clientConfigurationDesired(client, providerEnvironment, command, parsed.dialect);
+        if (registrationCurrent(parsed, desired))
             return { status: "already_current" };
     }
     catch (cause) {
@@ -162,6 +163,8 @@ const restoreConfig = async (path, original) => {
         void cause;
     }
 };
+/** Whether REA's entry matches and no conflicting legacy entry remains. */
+const registrationCurrent = (parsed, desired) => clientConfigurationValuesEqual(parsed.servers[PRODUCT_IDENTITY.mcpServerKey], desired) && !Object.hasOwn(parsed.legacyServers, PRODUCT_IDENTITY.mcpServerKey);
 const clientConfigurationDesired = (client, providerEnvironment, command, format) => {
     const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
     const registration = clientRegistrationEntry(format ?? "json", command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command, environment);