windows-exe-decompiler-mcp-server 0.1.0 → 0.1.3

package/dist/workflows/reconstruct.js

@@ -9,13 +9,19 @@ import { createRuntimeDetectHandler } from '../tools/runtime-detect.js';
 import { createCodeReconstructPlanHandler } from '../tools/code-reconstruct-plan.js';
 import { createCodeReconstructExportHandler } from '../tools/code-reconstruct-export.js';
 import { createDotNetReconstructExportHandler } from '../tools/dotnet-reconstruct-export.js';
-import { findBestGhidraAnalysis } from '../ghidra-analysis-status.js';
+import { findBestGhidraAnalysis, isGhidraCapabilityReady, } from '../ghidra-analysis-status.js';
 import { loadDynamicTraceEvidence } from '../dynamic-trace.js';
 import { loadSemanticFunctionExplanationIndex, loadSemanticNameSuggestionIndex, } from '../semantic-name-suggestion-artifacts.js';
+import { BinaryRoleProfileDataSchema, createBinaryRoleProfileHandler, } from '../tools/binary-role-profile.js';
+import { ComRoleProfileDataSchema, createComRoleProfileHandler, } from '../tools/com-role-profile.js';
+import { DllExportProfileDataSchema, createDllExportProfileHandler, } from '../tools/dll-export-profile.js';
+import { createRustBinaryAnalyzeHandler, } from '../tools/rust-binary-analyze.js';
+import { createFunctionIndexRecoverWorkflowHandler } from './function-index-recover.js';
 import { AnalysisProvenanceSchema, buildRuntimeArtifactProvenance, buildSemanticArtifactProvenance, } from '../analysis-provenance.js';
 import { AnalysisSelectionDiffSchema, buildArtifactSelectionDiff, } from '../selection-diff.js';
+import { RequiredUserInputSchema, SetupActionSchema, collectSetupGuidanceFromWorkerResult, mergeRequiredUserInputs, mergeSetupActions, } from '../setup-guidance.js';
 const TOOL_NAME = 'workflow.reconstruct';
-const TOOL_VERSION = '0.1.3';
+const TOOL_VERSION = '0.1.5';
 const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 export const ReconstructWorkflowInputSchema = z.object({
     sample_id: z.string().describe('Sample ID (format: sha256:<hex>)'),
@@ -96,6 +102,14 @@ export const ReconstructWorkflowInputSchema = z.object({
         .string()
         .optional()
         .describe('Optional baseline semantic artifact session selector used when compare_semantic_scope=session'),
+    include_preflight: z
+        .boolean()
+        .default(true)
+        .describe('Run binary role and language-specific preflight profiling before planning and export'),
+    auto_recover_function_index: z
+        .boolean()
+        .default(true)
+        .describe('When native function-index coverage is missing, automatically run workflow.function_index_recover before export'),
     include_plan: z
         .boolean()
         .default(true)
@@ -196,29 +210,115 @@ const ExportSummarySchema = z.object({
     binary_profile: BinaryProfileSchema.nullable(),
     managed_profile: ManagedProfileSchema.nullable(),
 });
+const PreflightRustProfileSchema = z.object({
+    suspected_rust: z.boolean(),
+    confidence: z.number().min(0).max(1),
+    primary_runtime: z.string().nullable(),
+    runtime_hints: z.array(z.string()),
+    crate_hints: z.array(z.string()),
+    cargo_paths: z.array(z.string()),
+    recovered_function_count: z.number().int().nonnegative(),
+    recovered_symbol_count: z.number().int().nonnegative(),
+    importable_with_code_functions_define: z.boolean(),
+    analysis_priorities: z.array(z.string()),
+});
+const PreflightDllProfileSchema = z.object({
+    library_like: z.boolean(),
+    role_confidence: z.number().min(0).max(1),
+    likely_entry_model: z.string(),
+    dll_entry_hints: z.array(z.string()),
+    dispatch_model: z.string(),
+    host_hints: z.array(z.string()),
+    lifecycle_surface: DllExportProfileDataSchema.shape.lifecycle_surface,
+    class_factory_surface: DllExportProfileDataSchema.shape.class_factory_surface,
+    callback_surface: DllExportProfileDataSchema.shape.callback_surface,
+    analysis_priorities: z.array(z.string()),
+});
+const PreflightComProfileSchema = z.object({
+    likely_com_server: z.boolean(),
+    com_confidence: z.number().min(0).max(1),
+    activation_model: z.string(),
+    class_factory_exports: z.array(z.string()),
+    registration_exports: z.array(z.string()),
+    clsid_strings: z.array(z.string()),
+    progid_strings: z.array(z.string()),
+    interface_hints: z.array(z.string()),
+    class_factory_surface: ComRoleProfileDataSchema.shape.class_factory_surface,
+    activation_steps: z.array(z.string()),
+    analysis_priorities: z.array(z.string()),
+});
+const RoleAwareExportTuningSchema = z.object({
+    topk: z.number().int().positive(),
+    module_limit: z.number().int().positive(),
+    min_module_size: z.number().int().positive(),
+    include_imports: z.boolean(),
+    include_strings: z.boolean(),
+});
+const RoleAwareStrategySchema = z.object({
+    target_role: z.string(),
+    priority_order: z.array(z.string()),
+    focus_areas: z.array(z.string()),
+    rationale: z.array(z.string()),
+    export_tuning: RoleAwareExportTuningSchema,
+});
+const FunctionIndexRecoverySummarySchema = z.object({
+    applied: z.boolean(),
+    define_from: z.enum(['smart_recover', 'symbols_recover']).nullable(),
+    recovered_function_count: z.number().int().nonnegative(),
+    recovered_symbol_count: z.number().int().nonnegative(),
+    imported_count: z.number().int().nonnegative(),
+    function_index_status: z.enum(['ready']).nullable(),
+    decompile_status: z.enum(['missing']).nullable(),
+    cfg_status: z.enum(['missing']).nullable(),
+    recovery_strategy: z.array(z.string()),
+    next_steps: z.array(z.string()),
+});
+const PreflightSummarySchema = z.object({
+    binary_profile: BinaryRoleProfileDataSchema.nullable(),
+    dll_profile: PreflightDllProfileSchema.nullable(),
+    com_profile: PreflightComProfileSchema.nullable(),
+    rust_profile: PreflightRustProfileSchema.nullable(),
+    function_index_recovery: FunctionIndexRecoverySummarySchema.nullable(),
+    role_strategy: RoleAwareStrategySchema.nullable(),
+});
+const ReconstructQueuedDataSchema = z.object({
+    job_id: z.string(),
+    status: z.literal('queued'),
+    tool: z.literal(TOOL_NAME),
+    sample_id: z.string(),
+    requested_path: z.enum(['auto', 'native', 'dotnet']),
+    progress: z.number().int().min(0).max(100),
+});
+const ReconstructCompletedDataSchema = z.object({
+    sample_id: z.string(),
+    selected_path: z.enum(['native', 'dotnet']),
+    degraded: z.boolean(),
+    stage_status: z.object({
+        runtime: z.enum(['ok', 'failed']),
+        preflight_binary_profile: z.enum(['ok', 'failed', 'skipped']),
+        preflight_dll_profile: z.enum(['ok', 'failed', 'skipped']),
+        preflight_com_profile: z.enum(['ok', 'failed', 'skipped']),
+        preflight_rust_profile: z.enum(['ok', 'failed', 'skipped']),
+        function_index_recovery: z.enum(['ok', 'failed', 'skipped']),
+        plan: z.enum(['ok', 'failed', 'skipped']),
+        export_primary: z.enum(['ok', 'failed', 'skipped']),
+        export_fallback: z.enum(['ok', 'failed', 'skipped']),
+    }),
+    provenance: AnalysisProvenanceSchema,
+    selection_diffs: AnalysisSelectionDiffSchema.optional(),
+    runtime: RuntimeSummarySchema,
+    preflight: PreflightSummarySchema.optional(),
+    plan: PlanSummarySchema.nullable(),
+    export: ExportSummarySchema.nullable(),
+    notes: z.array(z.string()),
+});
 export const ReconstructWorkflowOutputSchema = z.object({
     ok: z.boolean(),
-    data: z
-        .object({
-        sample_id: z.string(),
-        selected_path: z.enum(['native', 'dotnet']),
-        degraded: z.boolean(),
-        stage_status: z.object({
-            runtime: z.enum(['ok', 'failed']),
-            plan: z.enum(['ok', 'failed', 'skipped']),
-            export_primary: z.enum(['ok', 'failed', 'skipped']),
-            export_fallback: z.enum(['ok', 'failed', 'skipped']),
-        }),
-        provenance: AnalysisProvenanceSchema,
-        selection_diffs: AnalysisSelectionDiffSchema.optional(),
-        runtime: RuntimeSummarySchema,
-        plan: PlanSummarySchema.nullable(),
-        export: ExportSummarySchema.nullable(),
-        notes: z.array(z.string()),
-    })
-        .optional(),
+    data: z.union([ReconstructCompletedDataSchema, ReconstructQueuedDataSchema]).optional(),
     warnings: z.array(z.string()).optional(),
     errors: z.array(z.string()).optional(),
+    setup_actions: z.array(SetupActionSchema).optional(),
+    required_user_inputs: z.array(RequiredUserInputSchema).optional(),
     artifacts: z.array(z.any()).optional(),
     metrics: z
         .object({
@@ -235,7 +335,7 @@ export const ReconstructWorkflowOutputSchema = z.object({
 });
 export const reconstructWorkflowToolDefinition = {
     name: TOOL_NAME,
-    description: 'Run a complete source-reconstruction workflow with auto routing (native/.NET), planning, export, and cache observability.',
+    description: 'Run a complete source-reconstruction workflow with auto routing (native/.NET), binary/language preflight profiling, optional function-index recovery, planning, export, and cache observability.',
     inputSchema: ReconstructWorkflowInputSchema,
     outputSchema: ReconstructWorkflowOutputSchema,
 };
@@ -261,7 +361,174 @@ function summarizeRuntime(runtimeData) {
         primary_runtime: pickPrimaryRuntime(runtimeData),
     };
 }
-export function createReconstructWorkflowHandler(workspaceManager, database, cacheManager, dependencies) {
+function pickLatestAnalysisMarker(analyses, predicate) {
+    const sorted = [...analyses]
+        .filter(predicate)
+        .sort((left, right) => {
+        const leftTs = new Date(left.finished_at || left.started_at || 0).getTime();
+        const rightTs = new Date(right.finished_at || right.started_at || 0).getTime();
+        return rightTs - leftTs;
+    });
+    const selected = sorted[0];
+    if (!selected) {
+        return null;
+    }
+    return {
+        stage: selected.stage,
+        backend: selected.backend,
+        status: selected.status,
+        finished_at: selected.finished_at || selected.started_at || null,
+    };
+}
+function summarizeRustPreflight(data) {
+    return {
+        suspected_rust: data.suspected_rust,
+        confidence: data.confidence,
+        primary_runtime: data.primary_runtime,
+        runtime_hints: data.runtime_hints,
+        crate_hints: data.crate_hints,
+        cargo_paths: data.cargo_paths,
+        recovered_function_count: data.recovered_function_count,
+        recovered_symbol_count: data.recovered_symbol_count,
+        importable_with_code_functions_define: data.importable_with_code_functions_define,
+        analysis_priorities: data.analysis_priorities,
+    };
+}
+function summarizeDllPreflight(data) {
+    return {
+        library_like: data.library_like,
+        role_confidence: data.role_confidence,
+        likely_entry_model: data.likely_entry_model,
+        dll_entry_hints: data.dll_entry_hints,
+        dispatch_model: data.export_dispatch_profile.likely_dispatch_model,
+        host_hints: data.host_interaction_profile.host_hints,
+        lifecycle_surface: data.lifecycle_surface,
+        class_factory_surface: data.class_factory_surface,
+        callback_surface: data.callback_surface,
+        analysis_priorities: data.analysis_priorities,
+    };
+}
+function summarizeComPreflight(data) {
+    return {
+        likely_com_server: data.likely_com_server,
+        com_confidence: data.com_confidence,
+        activation_model: data.activation_model,
+        class_factory_exports: data.class_factory_exports,
+        registration_exports: data.registration_exports,
+        clsid_strings: data.clsid_strings,
+        progid_strings: data.progid_strings,
+        interface_hints: data.interface_hints,
+        class_factory_surface: data.class_factory_surface,
+        activation_steps: data.activation_steps,
+        analysis_priorities: data.analysis_priorities,
+    };
+}
+function buildRoleAwareStrategy(args) {
+    const rationale = [];
+    const focusAreas = new Set();
+    const priorityOrder = new Set();
+    let targetRole = 'native_executable';
+    const exportTuning = {
+        topk: 16,
+        module_limit: 8,
+        min_module_size: 1,
+        include_imports: true,
+        include_strings: true,
+    };
+    if (args.runtimeData?.is_dotnet) {
+        targetRole = 'managed_assembly';
+        rationale.push('runtime.detect reported CLR/.NET metadata');
+        focusAreas.add('managed_metadata_and_il');
+    }
+    else if (args.comProfile?.likely_com_server) {
+        targetRole = 'com_server';
+        rationale.push(`COM preflight suggests activation model ${args.comProfile.activation_model}`);
+        focusAreas.add('class_factory_and_registration');
+        exportTuning.topk = 20;
+        exportTuning.module_limit = 10;
+    }
+    else if (args.dllProfile?.library_like && args.dllProfile.dispatch_model !== 'none') {
+        targetRole = 'export_dispatch_dll';
+        rationale.push(`DLL preflight suggests dispatch model ${args.dllProfile.dispatch_model}`);
+        focusAreas.add('export_dispatch_surface');
+        exportTuning.topk = 18;
+        exportTuning.module_limit = 10;
+    }
+    else if (args.dllProfile?.library_like && args.dllProfile.host_hints.length > 0) {
+        targetRole = 'hosted_plugin_or_service_dll';
+        rationale.push('DLL preflight suggests hosted/plugin lifecycle');
+        focusAreas.add('host_callbacks_and_attach_detach');
+        exportTuning.topk = 18;
+        exportTuning.module_limit = 9;
+    }
+    else if (args.dllProfile?.library_like) {
+        targetRole = 'dll_library';
+        rationale.push(`DLL preflight suggests entry model ${args.dllProfile.likely_entry_model}`);
+        focusAreas.add('dllmain_and_export_surface');
+        exportTuning.topk = 18;
+        exportTuning.module_limit = 9;
+    }
+    else if (args.rustProfile?.suspected_rust) {
+        targetRole = 'native_rust_executable';
+        rationale.push(`Rust preflight confidence ${args.rustProfile.confidence.toFixed(2)}`);
+        focusAreas.add('pdata_recovery_and_runtime_wrappers');
+        exportTuning.topk = 20;
+        exportTuning.module_limit = 9;
+    }
+    else if (args.binaryProfile?.indicators.service_binary.likely) {
+        targetRole = 'service_binary';
+        rationale.push('binary.role.profile found service-oriented indicators');
+        focusAreas.add('service_entrypoints_and_hooks');
+        exportTuning.topk = 18;
+        exportTuning.module_limit = 9;
+    }
+    for (const item of args.binaryProfile?.analysis_priorities || []) {
+        priorityOrder.add(item);
+    }
+    for (const item of args.dllProfile?.analysis_priorities || []) {
+        priorityOrder.add(item);
+    }
+    for (const item of args.comProfile?.analysis_priorities || []) {
+        priorityOrder.add(item);
+    }
+    for (const item of args.rustProfile?.analysis_priorities || []) {
+        priorityOrder.add(item);
+    }
+    if (args.comProfile?.class_factory_exports.length) {
+        focusAreas.add('class_factory_exports');
+    }
+    if (args.dllProfile?.dll_entry_hints.length) {
+        focusAreas.add('dll_entry_lifecycle');
+    }
+    if (args.binaryProfile?.export_dispatch_profile.likely_dispatch_model !== 'none') {
+        focusAreas.add('dispatch_model_reconstruction');
+    }
+    if (args.binaryProfile?.host_interaction_profile.likely_hosted) {
+        focusAreas.add('host_interaction_model');
+    }
+    return {
+        target_role: targetRole,
+        priority_order: Array.from(priorityOrder),
+        focus_areas: Array.from(focusAreas),
+        rationale,
+        export_tuning: exportTuning,
+    };
+}
+function summarizeFunctionIndexRecovery(data) {
+    return {
+        applied: true,
+        define_from: data.define_from,
+        recovered_function_count: data.recovered_function_count,
+        recovered_symbol_count: data.recovered_symbol_count,
+        imported_count: data.imported_count,
+        function_index_status: data.function_index_status,
+        decompile_status: data.decompile_status,
+        cfg_status: data.cfg_status,
+        recovery_strategy: data.recovery_strategy,
+        next_steps: data.next_steps,
+    };
+}
+export function createReconstructWorkflowHandler(workspaceManager, database, cacheManager, dependencies, jobQueue) {
     const runtimeDetectHandler = dependencies?.runtimeDetectHandler ||
         createRuntimeDetectHandler(workspaceManager, database, cacheManager);
     const planHandler = dependencies?.planHandler ||
@@ -270,6 +537,20 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
         createCodeReconstructExportHandler(workspaceManager, database, cacheManager);
     const dotnetExportHandler = dependencies?.dotnetExportHandler ||
         createDotNetReconstructExportHandler(workspaceManager, database, cacheManager);
+    const binaryRoleProfileHandler = dependencies?.binaryRoleProfileHandler ||
+        createBinaryRoleProfileHandler(workspaceManager, database, cacheManager);
+    const dllExportProfileHandler = dependencies?.dllExportProfileHandler ||
+        createDllExportProfileHandler(workspaceManager, database, cacheManager, {
+            binaryRoleProfileHandler,
+        });
+    const comRoleProfileHandler = dependencies?.comRoleProfileHandler ||
+        createComRoleProfileHandler(workspaceManager, database, cacheManager, {
+            binaryRoleProfileHandler,
+        });
+    const rustBinaryAnalyzeHandler = dependencies?.rustBinaryAnalyzeHandler ||
+        createRustBinaryAnalyzeHandler(workspaceManager, database, cacheManager);
+    const functionIndexRecoverHandler = dependencies?.functionIndexRecoverHandler ||
+        createFunctionIndexRecoverWorkflowHandler(workspaceManager, database, cacheManager);
     return async (args) => {
         const input = ReconstructWorkflowInputSchema.parse(args);
         const startTime = Date.now();
@@ -281,10 +562,48 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                     errors: [`Sample not found: ${input.sample_id}`],
                 };
             }
+            if (jobQueue) {
+                const jobTimeoutMs = Math.max(input.build_timeout_ms + input.run_timeout_ms + 45 * 60 * 1000, 60 * 60 * 1000);
+                const jobId = jobQueue.enqueue({
+                    type: 'static',
+                    tool: TOOL_NAME,
+                    sampleId: input.sample_id,
+                    args: input,
+                    priority: 5,
+                    timeout: jobTimeoutMs,
+                    retryPolicy: {
+                        maxRetries: 1,
+                        backoffMs: 5000,
+                        retryableErrors: ['E_TIMEOUT', 'E_RESOURCE_EXHAUSTED'],
+                    },
+                });
+                return {
+                    ok: true,
+                    data: {
+                        job_id: jobId,
+                        status: 'queued',
+                        tool: TOOL_NAME,
+                        sample_id: input.sample_id,
+                        requested_path: input.path,
+                        progress: 0,
+                    },
+                    metrics: {
+                        elapsed_ms: Date.now() - startTime,
+                        tool: TOOL_NAME,
+                    },
+                };
+            }
             const warnings = [];
             const notes = [];
+            let setupActions = [];
+            let requiredUserInputs = [];
             const stageStatus = {
                 runtime: 'failed',
+                preflight_binary_profile: 'skipped',
+                preflight_dll_profile: 'skipped',
+                preflight_com_profile: 'skipped',
+                preflight_rust_profile: 'skipped',
+                function_index_recovery: 'skipped',
                 plan: 'skipped',
                 export_primary: 'skipped',
                 export_fallback: 'skipped',
@@ -303,6 +622,11 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
             else {
                 stageStatus.runtime = 'ok';
             }
+            {
+                const setupGuidance = collectSetupGuidanceFromWorkerResult(runtimeResult);
+                setupActions = mergeSetupActions(setupActions, setupGuidance.setupActions);
+                requiredUserInputs = mergeRequiredUserInputs(requiredUserInputs, setupGuidance.requiredUserInputs);
+            }
             let selectedPath;
             if (input.path === 'auto') {
                 selectedPath = runtimeData?.is_dotnet ? 'dotnet' : 'native';
@@ -330,7 +654,145 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
             if (selectedPath === 'native' && runtimeData?.is_dotnet) {
                 warnings.push('Selected native path while runtime indicates .NET; forcing native as requested.');
             }
-            const completedGhidraAnalysis = findBestGhidraAnalysis(database.findAnalysesBySample(input.sample_id), 'function_index');
+            let analyses = database.findAnalysesBySample(input.sample_id);
+            let completedGhidraAnalysis = findBestGhidraAnalysis(analyses, 'function_index');
+            const hasReadyGhidraFunctionIndex = Boolean(completedGhidraAnalysis && isGhidraCapabilityReady(completedGhidraAnalysis, 'function_index'));
+            const hasFunctionDefinitionIndex = analyses.some((analysis) => analysis.stage === 'function_definition' && analysis.status === 'done');
+            let binaryProfileData = null;
+            let dllProfileData = null;
+            let comProfileData = null;
+            let rustProfileData = null;
+            let functionIndexRecoveryData = null;
+            let functionIndexRecoveryApplied = false;
+            let roleStrategy = null;
+            if (input.include_preflight) {
+                const binaryProfileResult = await binaryRoleProfileHandler({
+                    sample_id: input.sample_id,
+                    force_refresh: !input.reuse_cached,
+                });
+                if (binaryProfileResult.ok && binaryProfileResult.data) {
+                    binaryProfileData = binaryProfileResult.data;
+                    stageStatus.preflight_binary_profile = 'ok';
+                }
+                else {
+                    stageStatus.preflight_binary_profile = 'failed';
+                    warnings.push(`binary.role.profile unavailable: ${(binaryProfileResult.errors || ['unknown error']).join('; ')}`);
+                }
+                if (binaryProfileResult.warnings?.length) {
+                    warnings.push(...binaryProfileResult.warnings.map((item) => `binary.role.profile: ${item}`));
+                }
+                {
+                    const setupGuidance = collectSetupGuidanceFromWorkerResult(binaryProfileResult);
+                    setupActions = mergeSetupActions(setupActions, setupGuidance.setupActions);
+                    requiredUserInputs = mergeRequiredUserInputs(requiredUserInputs, setupGuidance.requiredUserInputs);
+                }
+            }
+            if (selectedPath === 'native' && !runtimeData?.is_dotnet && input.include_preflight) {
+                const dllProfileResult = await dllExportProfileHandler({
+                    sample_id: input.sample_id,
+                    force_refresh: !input.reuse_cached,
+                });
+                if (dllProfileResult.ok && dllProfileResult.data) {
+                    dllProfileData = summarizeDllPreflight(dllProfileResult.data);
+                    stageStatus.preflight_dll_profile = 'ok';
+                }
+                else {
+                    stageStatus.preflight_dll_profile = 'failed';
+                    warnings.push(`dll.export.profile unavailable: ${(dllProfileResult.errors || ['unknown error']).join('; ')}`);
+                }
+                if (dllProfileResult.warnings?.length) {
+                    warnings.push(...dllProfileResult.warnings.map((item) => `dll.export.profile: ${item}`));
+                }
+                {
+                    const setupGuidance = collectSetupGuidanceFromWorkerResult(dllProfileResult);
+                    setupActions = mergeSetupActions(setupActions, setupGuidance.setupActions);
+                    requiredUserInputs = mergeRequiredUserInputs(requiredUserInputs, setupGuidance.requiredUserInputs);
+                }
+                const comProfileResult = await comRoleProfileHandler({
+                    sample_id: input.sample_id,
+                    force_refresh: !input.reuse_cached,
+                });
+                if (comProfileResult.ok && comProfileResult.data) {
+                    comProfileData = summarizeComPreflight(comProfileResult.data);
+                    stageStatus.preflight_com_profile = 'ok';
+                }
+                else {
+                    stageStatus.preflight_com_profile = 'failed';
+                    warnings.push(`com.role.profile unavailable: ${(comProfileResult.errors || ['unknown error']).join('; ')}`);
+                }
+                if (comProfileResult.warnings?.length) {
+                    warnings.push(...comProfileResult.warnings.map((item) => `com.role.profile: ${item}`));
+                }
+                {
+                    const setupGuidance = collectSetupGuidanceFromWorkerResult(comProfileResult);
+                    setupActions = mergeSetupActions(setupActions, setupGuidance.setupActions);
+                    requiredUserInputs = mergeRequiredUserInputs(requiredUserInputs, setupGuidance.requiredUserInputs);
+                }
+            }
+            if (selectedPath === 'native' && !runtimeData?.is_dotnet && input.include_preflight) {
+                const rustProfileResult = await rustBinaryAnalyzeHandler({
+                    sample_id: input.sample_id,
+                    force_refresh: !input.reuse_cached,
+                });
+                if (rustProfileResult.ok && rustProfileResult.data) {
+                    rustProfileData = rustProfileResult.data;
+                    stageStatus.preflight_rust_profile = 'ok';
+                }
+                else {
+                    stageStatus.preflight_rust_profile = 'failed';
+                    warnings.push(`rust_binary.analyze unavailable: ${(rustProfileResult.errors || ['unknown error']).join('; ')}`);
+                }
+                if (rustProfileResult.warnings?.length) {
+                    warnings.push(...rustProfileResult.warnings.map((item) => `rust_binary.analyze: ${item}`));
+                }
+                {
+                    const setupGuidance = collectSetupGuidanceFromWorkerResult(rustProfileResult);
+                    setupActions = mergeSetupActions(setupActions, setupGuidance.setupActions);
+                    requiredUserInputs = mergeRequiredUserInputs(requiredUserInputs, setupGuidance.requiredUserInputs);
+                }
+            }
+            if (input.include_preflight) {
+                roleStrategy = buildRoleAwareStrategy({
+                    runtimeData,
+                    binaryProfile: binaryProfileData,
+                    dllProfile: dllProfileData,
+                    comProfile: comProfileData,
+                    rustProfile: rustProfileData ? summarizeRustPreflight(rustProfileData) : null,
+                });
+            }
+            if (selectedPath === 'native' &&
+                input.auto_recover_function_index &&
+                !hasReadyGhidraFunctionIndex &&
+                !hasFunctionDefinitionIndex) {
+                const functionIndexRecoverResult = await functionIndexRecoverHandler({
+                    sample_id: input.sample_id,
+                    define_from: 'auto',
+                    include_rank_preview: false,
+                    persist_artifact: true,
+                    register_analysis: true,
+                    replace_all: true,
+                    force_refresh: !input.reuse_cached,
+                });
+                if (functionIndexRecoverResult.ok && functionIndexRecoverResult.data) {
+                    functionIndexRecoveryData = summarizeFunctionIndexRecovery(functionIndexRecoverResult.data);
+                    functionIndexRecoveryApplied = true;
+                    stageStatus.function_index_recovery = 'ok';
+                    analyses = database.findAnalysesBySample(input.sample_id);
+                    completedGhidraAnalysis = findBestGhidraAnalysis(analyses, 'function_index');
+                }
+                else {
+                    stageStatus.function_index_recovery = 'failed';
+                    warnings.push(`workflow.function_index_recover unavailable: ${(functionIndexRecoverResult.errors || ['unknown error']).join('; ')}`);
+                }
+                if (functionIndexRecoverResult.warnings?.length) {
+                    warnings.push(...functionIndexRecoverResult.warnings.map((item) => `workflow.function_index_recover: ${item}`));
+                }
+                {
+                    const setupGuidance = collectSetupGuidanceFromWorkerResult(functionIndexRecoverResult);
+                    setupActions = mergeSetupActions(setupActions, setupGuidance.setupActions);
+                    requiredUserInputs = mergeRequiredUserInputs(requiredUserInputs, setupGuidance.requiredUserInputs);
+                }
+            }
             const dynamicEvidence = await loadDynamicTraceEvidence(workspaceManager, database, input.sample_id, {
                 evidenceScope: input.evidence_scope,
                 sessionTag: input.evidence_session_tag,
@@ -368,7 +830,17 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                 selectionDiffs.semantic_names = buildArtifactSelectionDiff('semantic_names', provenance.semantic_names, buildSemanticArtifactProvenance('semantic naming artifacts', baselineSemanticNameIndex, input.compare_semantic_scope, input.compare_semantic_session_tag));
                 selectionDiffs.semantic_explanations = buildArtifactSelectionDiff('semantic_explanations', provenance.semantic_explanations, buildSemanticArtifactProvenance('semantic explanation artifacts', baselineSemanticExplanationIndex, input.compare_semantic_scope, input.compare_semantic_session_tag));
             }
-            const analysisMarker = completedGhidraAnalysis?.finished_at || completedGhidraAnalysis?.id || 'none';
+            const functionDefinitionMarker = pickLatestAnalysisMarker(analyses, (analysis) => analysis.stage === 'function_definition');
+            const analysisMarker = JSON.stringify({
+                ghidra_function_index: completedGhidraAnalysis
+                    ? {
+                        id: completedGhidraAnalysis.id,
+                        status: completedGhidraAnalysis.status,
+                        finished_at: completedGhidraAnalysis.finished_at || completedGhidraAnalysis.started_at || null,
+                    }
+                    : null,
+                function_definition: functionDefinitionMarker,
+            });
             const cacheKey = generateCacheKey({
                 sampleSha256: sample.sha256,
                 toolName: TOOL_NAME,
@@ -391,6 +863,8 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                     compare_evidence_session_tag: input.compare_evidence_session_tag || null,
                     compare_semantic_scope: input.compare_semantic_scope || null,
                     compare_semantic_session_tag: input.compare_semantic_session_tag || null,
+                    include_preflight: input.include_preflight,
+                    auto_recover_function_index: input.auto_recover_function_index,
                     include_plan: input.include_plan,
                     include_obfuscation_fallback: input.include_obfuscation_fallback,
                     fallback_on_error: input.fallback_on_error,
@@ -449,11 +923,23 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                 if (planResult.warnings && planResult.warnings.length > 0) {
                     warnings.push(...planResult.warnings.map((item) => `plan: ${item}`));
                 }
+                {
+                    const setupGuidance = collectSetupGuidanceFromWorkerResult(planResult);
+                    setupActions = mergeSetupActions(setupActions, setupGuidance.setupActions);
+                    requiredUserInputs = mergeRequiredUserInputs(requiredUserInputs, setupGuidance.requiredUserInputs);
+                }
             }
             let exportSummary = null;
             let artifacts = [];
             const primaryPath = selectedPath;
             const fallbackPath = primaryPath === 'dotnet' ? 'native' : 'dotnet';
+            const nativeExportTuning = roleStrategy?.export_tuning || {
+                topk: Math.max(input.topk, 16),
+                module_limit: 8,
+                min_module_size: 1,
+                include_imports: true,
+                include_strings: true,
+            };
             const runExport = async (pathToRun) => {
                 if (pathToRun === 'dotnet') {
                     const dotnetResult = await dotnetExportHandler({
@@ -463,13 +949,14 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                         include_obfuscation_fallback: input.include_obfuscation_fallback,
                         evidence_scope: input.evidence_scope,
                         evidence_session_tag: input.evidence_session_tag,
-                        reuse_cached: input.reuse_cached,
+                        reuse_cached: input.reuse_cached && !functionIndexRecoveryApplied,
                     });
                     if (!dotnetResult.ok || !dotnetResult.data) {
                         return {
                             ok: false,
                             errors: dotnetResult.errors || ['dotnet.reconstruct.export failed'],
                             warnings: dotnetResult.warnings || [],
+                            setupGuidance: collectSetupGuidanceFromWorkerResult(dotnetResult),
                         };
                     }
                     const data = dotnetResult.data;
@@ -477,6 +964,7 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                         ok: true,
                         warnings: dotnetResult.warnings || [],
                         artifacts: dotnetResult.artifacts || [],
+                        setupGuidance: collectSetupGuidanceFromWorkerResult(dotnetResult),
                         summary: {
                             tool: 'dotnet.reconstruct.export',
                             export_root: data.export_root,
@@ -503,11 +991,11 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                 }
                 const nativeResult = await nativeExportHandler({
                     sample_id: input.sample_id,
-                    topk: input.topk,
-                    module_limit: 8,
-                    min_module_size: 1,
-                    include_imports: true,
-                    include_strings: true,
+                    topk: Math.max(input.topk, nativeExportTuning.topk),
+                    module_limit: nativeExportTuning.module_limit,
+                    min_module_size: nativeExportTuning.min_module_size,
+                    include_imports: nativeExportTuning.include_imports,
+                    include_strings: nativeExportTuning.include_strings,
                     export_name: input.export_name,
                     validate_build: input.validate_build,
                     run_harness: input.run_harness,
@@ -518,13 +1006,17 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                     evidence_session_tag: input.evidence_session_tag,
                     semantic_scope: input.semantic_scope,
                     semantic_session_tag: input.semantic_session_tag,
-                    reuse_cached: input.reuse_cached,
+                    role_target: roleStrategy?.target_role,
+                    role_focus_areas: roleStrategy?.focus_areas || [],
+                    role_priority_order: roleStrategy?.priority_order || [],
+                    reuse_cached: input.reuse_cached && !functionIndexRecoveryApplied,
                 });
                 if (!nativeResult.ok || !nativeResult.data) {
                     return {
                         ok: false,
                         errors: nativeResult.errors || ['code.reconstruct.export failed'],
                         warnings: nativeResult.warnings || [],
+                        setupGuidance: collectSetupGuidanceFromWorkerResult(nativeResult),
                     };
                 }
                 const data = nativeResult.data;
@@ -532,6 +1024,7 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                     ok: true,
                     warnings: nativeResult.warnings || [],
                     artifacts: nativeResult.artifacts || [],
+                    setupGuidance: collectSetupGuidanceFromWorkerResult(nativeResult),
                     summary: {
                         tool: 'code.reconstruct.export',
                         export_root: data.export_root,
@@ -561,12 +1054,16 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                 stageStatus.export_primary = 'ok';
                 exportSummary = primaryExportResult.summary;
                 artifacts = primaryExportResult.artifacts || [];
+                setupActions = mergeSetupActions(setupActions, primaryExportResult.setupGuidance.setupActions);
+                requiredUserInputs = mergeRequiredUserInputs(requiredUserInputs, primaryExportResult.setupGuidance.requiredUserInputs);
                 if (primaryExportResult.warnings.length > 0) {
                     warnings.push(...primaryExportResult.warnings.map((item) => `${primaryPath === 'dotnet' ? 'dotnet_export' : 'native_export'}: ${item}`));
                 }
             }
             else {
                 stageStatus.export_primary = 'failed';
+                setupActions = mergeSetupActions(setupActions, primaryExportResult.setupGuidance.setupActions);
+                requiredUserInputs = mergeRequiredUserInputs(requiredUserInputs, primaryExportResult.setupGuidance.requiredUserInputs);
                 warnings.push(`primary export(${primaryPath}) failed: ${(primaryExportResult.errors || ['unknown error']).join('; ')}`);
                 if (primaryExportResult.warnings.length > 0) {
                     warnings.push(...primaryExportResult.warnings.map((item) => `${primaryPath === 'dotnet' ? 'dotnet_export' : 'native_export'}: ${item}`));
@@ -578,6 +1075,8 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                     stageStatus.export_fallback = 'ok';
                     exportSummary = fallbackExportResult.summary;
                     artifacts = fallbackExportResult.artifacts || [];
+                    setupActions = mergeSetupActions(setupActions, fallbackExportResult.setupGuidance.setupActions);
+                    requiredUserInputs = mergeRequiredUserInputs(requiredUserInputs, fallbackExportResult.setupGuidance.requiredUserInputs);
                     selectedPath = fallbackPath;
                     notes.push(`Primary export path failed; switched to fallback path: ${fallbackPath}.`);
                     if (fallbackExportResult.warnings.length > 0) {
@@ -586,6 +1085,8 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                 }
                 else {
                     stageStatus.export_fallback = 'failed';
+                    setupActions = mergeSetupActions(setupActions, fallbackExportResult.setupGuidance.setupActions);
+                    requiredUserInputs = mergeRequiredUserInputs(requiredUserInputs, fallbackExportResult.setupGuidance.requiredUserInputs);
                     warnings.push(`fallback export(${fallbackPath}) failed: ${(fallbackExportResult.errors || ['unknown error']).join('; ')}`);
                     if (fallbackExportResult.warnings.length > 0) {
                         warnings.push(...fallbackExportResult.warnings.map((item) => `${fallbackPath === 'dotnet' ? 'dotnet_export' : 'native_export'}: ${item}`));
@@ -600,6 +1101,8 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                     ok: false,
                     errors: ['All export paths failed and allow_partial=false.'],
                     warnings,
+                    setup_actions: setupActions.length > 0 ? setupActions : undefined,
+                    required_user_inputs: requiredUserInputs.length > 0 ? requiredUserInputs : undefined,
                     metrics: {
                         elapsed_ms: Date.now() - startTime,
                         tool: TOOL_NAME,
@@ -615,6 +1118,32 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
             else {
                 notes.push('Runtime signal indicates native path; exact original source text is not recoverable.');
             }
+            if (binaryProfileData?.export_dispatch_profile?.likely_dispatch_model &&
+                binaryProfileData.export_dispatch_profile.likely_dispatch_model !== 'none') {
+                notes.push(`Binary role preflight suggests dispatch model: ${binaryProfileData.export_dispatch_profile.likely_dispatch_model}.`);
+            }
+            if (dllProfileData?.dll_entry_hints.length) {
+                notes.push(`DLL/export preflight hints: ${dllProfileData.dll_entry_hints.slice(0, 3).join(' ')}`);
+            }
+            if (comProfileData?.likely_com_server) {
+                notes.push(`COM preflight suggests activation model: ${comProfileData.activation_model}.`);
+            }
+            if (binaryProfileData?.host_interaction_profile?.likely_hosted) {
+                notes.push('Binary role preflight suggests the sample is likely hosted as a DLL/plugin/service component.');
+            }
+            if (rustProfileData?.suspected_rust) {
+                notes.push(`Rust preflight recovered ${rustProfileData.recovered_function_count} function candidates and ${rustProfileData.recovered_symbol_count} symbol hints.`);
+                if (rustProfileData.crate_hints.length > 0) {
+                    notes.push(`Rust crate hints: ${rustProfileData.crate_hints.slice(0, 4).join(', ')}.`);
+                }
+            }
+            if (functionIndexRecoveryData?.applied) {
+                notes.push(`Function index recovery imported ${functionIndexRecoveryData.imported_count} recovered functions before export.`);
+            }
+            if (roleStrategy) {
+                notes.push(`Role-aware strategy selected target role ${roleStrategy.target_role}${roleStrategy.focus_areas.length ? ` with focus on ${roleStrategy.focus_areas.join(', ')}` : ''}.`);
+                notes.push(`Role-aware export tuning: topk=${roleStrategy.export_tuning.topk}, module_limit=${roleStrategy.export_tuning.module_limit}, min_module_size=${roleStrategy.export_tuning.min_module_size}, imports=${roleStrategy.export_tuning.include_imports ? 'on' : 'off'}, strings=${roleStrategy.export_tuning.include_strings ? 'on' : 'off'}.`);
+            }
             if (exportSummary?.binary_profile?.analysis_priorities?.length) {
                 notes.push(`Binary profile priorities: ${exportSummary.binary_profile.analysis_priorities.join(', ')}.`);
             }
@@ -635,6 +1164,16 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                 provenance,
                 selection_diffs: Object.keys(selectionDiffs).length > 0 ? selectionDiffs : undefined,
                 runtime: summarizeRuntime(runtimeData),
+                preflight: input.include_preflight || stageStatus.function_index_recovery !== 'skipped'
+                    ? {
+                        binary_profile: binaryProfileData,
+                        dll_profile: dllProfileData,
+                        com_profile: comProfileData,
+                        rust_profile: rustProfileData ? summarizeRustPreflight(rustProfileData) : null,
+                        function_index_recovery: functionIndexRecoveryData,
+                        role_strategy: roleStrategy,
+                    }
+                    : undefined,
                 plan: planSummary,
                 export: exportSummary,
                 notes,
@@ -644,6 +1183,8 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
                 ok: true,
                 data: outputData,
                 warnings: warnings.length > 0 ? warnings : undefined,
+                setup_actions: setupActions.length > 0 ? setupActions : undefined,
+                required_user_inputs: requiredUserInputs.length > 0 ? requiredUserInputs : undefined,
                 artifacts: artifacts,
                 metrics: {
                     elapsed_ms: Date.now() - startTime,
@@ -655,6 +1196,8 @@ export function createReconstructWorkflowHandler(workspaceManager, database, cac
             return {
                 ok: false,
                 errors: [normalizeError(error)],
+                setup_actions: undefined,
+                required_user_inputs: undefined,
                 metrics: {
                     elapsed_ms: Date.now() - startTime,
                     tool: TOOL_NAME,