@dotsetlabs/bellwether 2.1.1 → 2.1.3

package/dist/cli/commands/check.js

@@ -13,9 +13,9 @@ import { MCPClient } from '../../transport/mcp-client.js';
 import { discover } from '../../discovery/discovery.js';
 import { Interviewer } from '../../interview/interviewer.js';
 import { generateContractMd, generateJsonReport } from '../../docs/generator.js';
-import { loadConfig, ConfigNotFoundError, parseCommandString, } from '../../config/loader.js';
+import { loadConfig, ConfigNotFoundError, } from '../../config/loader.js';
 import { validateConfigForCheck, getConfigWarnings } from '../../config/validator.js';
-import { createBaseline, loadBaseline, saveBaseline, getToolFingerprints, toToolCapability, compareBaselines, acceptDrift, formatDiffText, formatDiffJson, formatDiffCompact, formatDiffGitHubActions, formatDiffMarkdown, formatDiffJUnit, formatDiffSarif, applySeverityConfig, shouldFailOnDiff, analyzeForIncremental, formatIncrementalSummary, runSecurityTests, parseSecurityCategories, getAllSecurityCategories, } from '../../baseline/index.js';
+import { createBaseline, loadBaseline, saveBaseline, getToolFingerprints, toToolCapability, compareBaselines, acceptDrift, applySeverityConfig, shouldFailOnDiff, analyzeForIncremental, formatIncrementalSummary, runSecurityTests, parseSecurityCategories, getAllSecurityCategories, } from '../../baseline/index.js';
 import { convertAssertions } from '../../baseline/converter.js';
 import { getMetricsCollector, resetMetricsCollector } from '../../metrics/collector.js';
 import { getGlobalCache, resetGlobalCache } from '../../cache/response-cache.js';
@@ -29,6 +29,10 @@ import { configureLogger } from '../../logging/logger.js';
 import { buildInterviewInsights } from '../../interview/insights.js';
 import { EXIT_CODES, SEVERITY_TO_EXIT_CODE, PATHS, SECURITY_TESTING, CHECK_SAMPLING, WORKFLOW, REPORT_SCHEMAS, PERCENTAGE_CONVERSION, MCP, } from '../../constants.js';
 import { getFeatureFlags, getExcludedFeatureNames } from '../../protocol/index.js';
+import { resolveServerRuntime } from '../utils/server-runtime.js';
+import { resolvePathFromOutputDir, resolvePathFromOutputDirOrCwd, } from '../utils/path-resolution.js';
+import { printCheckErrorHints } from '../utils/error-hints.js';
+import { formatDiffOutput, formatCheckResults } from './check-formatters.js';
 export const checkCommand = new Command('check')
     .description('Check MCP server schema and detect drift (free, fast, deterministic)')
     .allowUnknownOption() // Allow server flags like -y for npx to pass through
@@ -41,6 +45,7 @@ export const checkCommand = new Command('check')
     .option('--format <format>', 'Diff output format: text, json, compact, github, markdown, junit, sarif')
     .option('--min-severity <level>', 'Minimum severity to report (overrides config): none, info, warning, breaking')
     .option('--fail-on-severity <level>', 'Fail threshold (overrides config): none, info, warning, breaking')
+    .option('-H, --header <header...>', 'Custom headers for remote MCP requests (e.g., "Authorization: Bearer token")')
     .action(async (serverCommandArg, serverArgs, options) => {
     // Load configuration
     let config;
@@ -54,19 +59,27 @@ export const checkCommand = new Command('check')
         }
         throw error;
     }
-    // Determine server command (CLI arg overrides config)
-    // If command string contains spaces and no separate args, parse it
-    let serverCommand = serverCommandArg || config.server.command;
-    let args = serverArgs.length > 0 ? serverArgs : config.server.args;
-    // Handle command strings like "npx @package" in config when args is empty
-    if (!serverCommandArg && args.length === 0 && serverCommand.includes(' ')) {
-        const parsed = parseCommandString(serverCommand);
-        serverCommand = parsed.command;
-        args = parsed.args;
+    let serverCommand;
+    let args;
+    let transport;
+    let remoteUrl;
+    let remoteSessionId;
+    let remoteHeaders;
+    let serverIdentifier;
+    try {
+        const runtime = resolveServerRuntime(config, serverCommandArg, serverArgs, options.header);
+        serverCommand = runtime.serverCommand;
+        args = runtime.args;
+        transport = runtime.transport;
+        remoteUrl = runtime.remoteUrl;
+        remoteSessionId = runtime.remoteSessionId;
+        remoteHeaders = runtime.remoteHeaders;
+        serverIdentifier = runtime.serverIdentifier;
+    }
+    catch (error) {
+        output.error(error instanceof Error ? error.message : String(error));
+        process.exit(EXIT_CODES.ERROR);
     }
-    const transport = config.server.transport ?? 'stdio';
-    const remoteUrl = config.server.url?.trim();
-    const remoteSessionId = config.server.sessionId?.trim();
     // Validate config for check
     try {
         validateConfigForCheck(config, serverCommand);
@@ -90,9 +103,16 @@ export const checkCommand = new Command('check')
         const effectiveLogLevel = verbose ? logLevel : 'silent';
         configureLogger({ level: effectiveLogLevel });
     }
-    // Resolve baseline options from config (--fail-on-drift CLI flag can override)
-    const baselinePath = config.baseline.comparePath;
-    const saveBaselinePath = config.baseline.savePath;
+    // Resolve baseline options from config (--fail-on-drift CLI flag can override).
+    // Keep path semantics consistent with baseline subcommands:
+    // - savePath: relative to output.dir
+    // - comparePath: output.dir first, then cwd fallback for existing files
+    const baselinePath = config.baseline.comparePath
+        ? resolvePathFromOutputDirOrCwd(config.baseline.comparePath, outputDir)
+        : undefined;
+    const saveBaselinePath = config.baseline.savePath
+        ? resolvePathFromOutputDir(config.baseline.savePath, outputDir)
+        : undefined;
     const failOnDrift = options.failOnDrift ? true : config.baseline.failOnDrift;
     // Build severity config (CLI options override config file)
     const severityConfig = {
@@ -149,9 +169,6 @@ export const checkCommand = new Command('check')
     const fullExamples = config.output.examples.full;
     const exampleLength = config.output.examples.maxLength;
     const maxExamplesPerTool = config.output.examples.maxPerTool;
-    const serverIdentifier = transport === 'stdio'
-        ? `${serverCommand} ${args.join(' ')}`.trim()
-        : (remoteUrl ?? 'unknown');
     // Display startup banner
     if (!machineReadable) {
         const banner = formatCheckBanner({
@@ -193,6 +210,7 @@ export const checkCommand = new Command('check')
             await mcpClient.connectRemote(remoteUrl, {
                 transport,
                 sessionId: remoteSessionId || undefined,
+                headers: remoteHeaders,
             });
         }
         // Discovery phase
@@ -255,12 +273,18 @@ export const checkCommand = new Command('check')
             toolsDiscovered: discovery.tools.length,
             personasUsed: 0, // No personas in check mode
         });
-        if (discovery.tools.length === 0) {
-            output.info('No tools found. Nothing to check.');
+        const hasInterviewTargets = discovery.tools.length > 0 ||
+            discovery.prompts.length > 0 ||
+            (discovery.resources?.length ?? 0) > 0;
+        if (!hasInterviewTargets) {
+            output.info('No tools, prompts, or resources found. Nothing to check.');
             metricsCollector.endInterview();
             await mcpClient.disconnect();
             return;
         }
+        if (discovery.tools.length === 0) {
+            output.info('No tools found; continuing with prompt/resource checks.');
+        }
         // Incremental checking - load baseline and determine which tools to test
         let incrementalBaseline = null;
         let incrementalResult = null;
@@ -852,7 +876,7 @@ export const checkCommand = new Command('check')
                 output.info('\n--- Drift Report ---');
             }
             // Select formatter based on --format option
-            const formattedDiff = formatDiff(diff, diffFormat, baselinePath);
+            const formattedDiff = formatDiffOutput(diff, diffFormat, baselinePath);
             if (machineReadable) {
                 console.log(formattedDiff);
             }
@@ -948,21 +972,7 @@ export const checkCommand = new Command('check')
         const errorMessage = error instanceof Error ? error.message : String(error);
         output.error('\n--- Check Failed ---');
         output.error(`Error: ${errorMessage}`);
-        if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Connection refused')) {
-            output.error('\nPossible causes:');
-            output.error('  - The MCP server is not running');
-            output.error('  - The server address/port is incorrect');
-        }
-        else if (errorMessage.includes('timeout') || errorMessage.includes('Timeout')) {
-            output.error('\nPossible causes:');
-            output.error('  - The MCP server is taking too long to respond');
-            output.error('  - Increase server.timeout in bellwether.yaml');
-        }
-        else if (errorMessage.includes('ENOENT') || errorMessage.includes('not found')) {
-            output.error('\nPossible causes:');
-            output.error('  - The server command was not found');
-            output.error('  - Check that the command is installed and in PATH');
-        }
+        printCheckErrorHints(error, transport);
         pendingExitCode = EXIT_CODES.ERROR;
     }
     finally {
@@ -977,179 +987,4 @@ export const checkCommand = new Command('check')
         }
     }
 });
-/**
- * Format a diff using the specified output format.
- *
- * @param diff - The behavioral diff to format
- * @param format - Output format: text, json, compact, github, markdown, junit, sarif
- * @param baselinePath - Path to baseline file (used for SARIF location references)
- * @returns Formatted string
- */
-function formatDiff(diff, format, baselinePath) {
-    switch (format.toLowerCase()) {
-        case 'json':
-            return formatDiffJson(diff);
-        case 'compact':
-            return formatDiffCompact(diff);
-        case 'github':
-            return formatDiffGitHubActions(diff);
-        case 'markdown':
-        case 'md':
-            return formatDiffMarkdown(diff);
-        case 'junit':
-        case 'junit-xml':
-        case 'xml':
-            return formatDiffJUnit(diff, 'bellwether-check');
-        case 'sarif':
-            return formatDiffSarif(diff, baselinePath);
-        case 'text':
-        default:
-            return formatDiffText(diff);
-    }
-}
-/**
- * Format check results as JUnit XML (for CI systems that expect test results).
- * This is used when --format junit is specified but no baseline comparison occurs.
- */
-function formatCheckResultsJUnit(baseline) {
-    const tools = getToolFingerprints(baseline);
-    const lines = [];
-    const securityFailures = tools.filter((t) => t.securityFingerprint?.findings?.some((f) => f.riskLevel === 'critical' || f.riskLevel === 'high')).length;
-    lines.push('<?xml version="1.0" encoding="UTF-8"?>');
-    lines.push('<testsuites>');
-    lines.push(`  <testsuite name="bellwether-check" tests="${tools.length}" failures="${securityFailures}" errors="0">`);
-    for (const tool of tools) {
-        const successRate = tool.baselineSuccessRate ?? 1;
-        const status = successRate >= 0.9 ? 'passed' : 'warning';
-        lines.push(`    <testcase name="${tool.name}" classname="mcp-tools" time="0">`);
-        lines.push(`      <system-out>Success rate: ${(successRate * 100).toFixed(0)}%</system-out>`);
-        if (status === 'warning') {
-            lines.push(`      <system-err>Tool has success rate below 90%</system-err>`);
-        }
-        lines.push('    </testcase>');
-    }
-    // Add security findings as test cases if present
-    const securityTools = tools.filter((t) => t.securityFingerprint?.findings?.length);
-    if (securityTools.length > 0) {
-        lines.push(`    <!-- Security findings -->`);
-        for (const tool of securityTools) {
-            const findings = tool.securityFingerprint?.findings ?? [];
-            const criticalHigh = findings.filter((f) => f.riskLevel === 'critical' || f.riskLevel === 'high').length;
-            if (criticalHigh > 0) {
-                lines.push(`    <testcase name="${tool.name}-security" classname="security">`);
-                lines.push(`      <failure message="${criticalHigh} critical/high security findings">`);
-                for (const finding of findings.filter((f) => f.riskLevel === 'critical' || f.riskLevel === 'high')) {
-                    lines.push(`        ${finding.riskLevel.toUpperCase()}: ${finding.title} (${finding.cweId})`);
-                }
-                lines.push(`      </failure>`);
-                lines.push('    </testcase>');
-            }
-        }
-    }
-    lines.push('  </testsuite>');
-    lines.push('</testsuites>');
-    return lines.join('\n');
-}
-/**
- * Format check results as SARIF (for GitHub Code Scanning and other tools).
- * This is used when --format sarif is specified but no baseline comparison occurs.
- */
-function formatCheckResultsSarif(baseline) {
-    const tools = getToolFingerprints(baseline);
-    const serverUri = baseline.metadata?.serverCommand || baseline.server.name || 'mcp-server';
-    const results = [];
-    // Add results for tools with security findings
-    const securityTools = tools.filter((t) => t.securityFingerprint?.findings?.length);
-    for (const tool of securityTools) {
-        const findings = tool.securityFingerprint?.findings ?? [];
-        for (const finding of findings) {
-            const level = finding.riskLevel === 'critical' || finding.riskLevel === 'high'
-                ? 'error'
-                : finding.riskLevel === 'medium'
-                    ? 'warning'
-                    : 'note';
-            results.push({
-                ruleId: finding.cweId || 'BWH-SEC',
-                level,
-                message: { text: `[${tool.name}] ${finding.title}: ${finding.description}` },
-                locations: [
-                    {
-                        physicalLocation: {
-                            artifactLocation: { uri: serverUri },
-                            region: { startLine: 1 },
-                        },
-                    },
-                ],
-            });
-        }
-    }
-    // Add results for tools with low success rate
-    for (const tool of tools) {
-        const successRate = tool.baselineSuccessRate ?? 1;
-        if (successRate < 0.9) {
-            results.push({
-                ruleId: 'BWH-REL',
-                level: 'warning',
-                message: {
-                    text: `Tool "${tool.name}" has ${(successRate * 100).toFixed(0)}% success rate`,
-                },
-                locations: [
-                    {
-                        physicalLocation: {
-                            artifactLocation: { uri: serverUri },
-                            region: { startLine: 1 },
-                        },
-                    },
-                ],
-            });
-        }
-    }
-    const sarif = {
-        $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
-        version: '2.1.0',
-        runs: [
-            {
-                tool: {
-                    driver: {
-                        name: 'bellwether',
-                        version: '1.0.0',
-                        informationUri: 'https://github.com/dotsetlabs/bellwether',
-                        rules: [
-                            {
-                                id: 'BWH-SEC',
-                                name: 'SecurityFinding',
-                                shortDescription: { text: 'Security vulnerability detected' },
-                                defaultConfiguration: { level: 'warning' },
-                            },
-                            {
-                                id: 'BWH-REL',
-                                name: 'LowReliability',
-                                shortDescription: { text: 'Tool reliability below threshold' },
-                                defaultConfiguration: { level: 'warning' },
-                            },
-                        ],
-                    },
-                },
-                results,
-            },
-        ],
-    };
-    return JSON.stringify(sarif, null, 2);
-}
-/**
- * Format check results using the specified output format.
- * Used when no baseline comparison occurs.
- */
-function formatCheckResults(baseline, format) {
-    switch (format.toLowerCase()) {
-        case 'junit':
-        case 'junit-xml':
-        case 'xml':
-            return formatCheckResultsJUnit(baseline);
-        case 'sarif':
-            return formatCheckResultsSarif(baseline);
-        default:
-            return null; // No special formatting needed for other formats
-    }
-}
 //# sourceMappingURL=check.js.map

package/dist/cli/commands/contract.js

@@ -13,24 +13,12 @@ import { loadContract, findContractFile, validateContract, generateContract, gen
 import { MCPClient } from '../../transport/mcp-client.js';
 import { discover } from '../../discovery/discovery.js';
 import { EXIT_CODES, CONTRACT_TESTING } from '../../constants.js';
-import { loadConfig, ConfigNotFoundError } from '../../config/loader.js';
 import * as output from '../output.js';
+import { loadConfigOrExit } from '../utils/config-loader.js';
 /**
  * Default paths for contract files.
  */
 const DEFAULT_CONTRACT_FILENAMES = CONTRACT_TESTING.CONTRACT_FILENAMES;
-function loadConfigOrExit(configPath) {
-    try {
-        return loadConfig(configPath);
-    }
-    catch (error) {
-        if (error instanceof ConfigNotFoundError) {
-            output.error(error.message);
-            process.exit(EXIT_CODES.ERROR);
-        }
-        throw error;
-    }
-}
 /**
  * Find or use provided contract path.
  */

package/dist/cli/commands/dashboard.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const dashboardCommand: Command;
+//# sourceMappingURL=dashboard.d.ts.map

package/dist/cli/commands/dashboard.js

@@ -0,0 +1,69 @@
+import { Command } from 'commander';
+import { EXIT_CODES } from '../../constants.js';
+import { startDashboard } from '../../dashboard/index.js';
+import * as output from '../output.js';
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 7331;
+function parsePort(rawPort) {
+    const parsed = Number.parseInt(rawPort, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        throw new Error(`Invalid port "${rawPort}". Use a value between 1 and 65535.`);
+    }
+    return parsed;
+}
+export const dashboardCommand = new Command('dashboard')
+    .description('Start local web dashboard for Bellwether')
+    .option('--host <host>', 'Host interface to bind', DEFAULT_HOST)
+    .option('-p, --port <port>', 'Port to listen on', String(DEFAULT_PORT))
+    .action(async (options) => {
+    const host = String(options.host ?? DEFAULT_HOST).trim();
+    let port;
+    try {
+        port = parsePort(String(options.port ?? DEFAULT_PORT));
+    }
+    catch (error) {
+        output.error(error instanceof Error ? error.message : String(error));
+        process.exit(EXIT_CODES.ERROR);
+        return;
+    }
+    try {
+        const dashboard = await startDashboard({
+            host,
+            port,
+            cwd: process.cwd(),
+            cliEntrypoint: process.argv[1],
+        });
+        output.info('Bellwether Dashboard');
+        output.info(`URL: ${dashboard.url}`);
+        output.info('Available profiles: check, explore, validate-config, discover, watch, baseline.save, baseline.compare, baseline.show, baseline.diff, baseline.accept, registry.search, contract.validate, contract.generate, contract.show, golden.save, golden.compare, golden.list, golden.delete');
+        output.info('Press Ctrl+C to stop.');
+        let shuttingDown = false;
+        const shutdown = async (signal) => {
+            if (shuttingDown) {
+                return;
+            }
+            shuttingDown = true;
+            output.info(`\nReceived ${signal}. Stopping dashboard...`);
+            try {
+                await dashboard.stop();
+            }
+            catch (error) {
+                output.error(error instanceof Error ? error.message : String(error));
+                process.exit(EXIT_CODES.ERROR);
+                return;
+            }
+            process.exit(EXIT_CODES.CLEAN);
+        };
+        process.on('SIGINT', () => {
+            void shutdown('SIGINT');
+        });
+        process.on('SIGTERM', () => {
+            void shutdown('SIGTERM');
+        });
+    }
+    catch (error) {
+        output.error(`Failed to start dashboard: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+});
+//# sourceMappingURL=dashboard.js.map

package/dist/cli/commands/discover.js

@@ -4,6 +4,8 @@ import { discover, summarizeDiscovery } from '../../discovery/discovery.js';
 import { EXIT_CODES } from '../../constants.js';
 import { loadConfig, ConfigNotFoundError } from '../../config/loader.js';
 import * as output from '../output.js';
+import { ServerAuthError } from '../../errors/types.js';
+import { mergeHeaders, parseCliHeaders } from '../utils/headers.js';
 /**
  * Action handler for the discover command.
  */
@@ -28,6 +30,16 @@ async function discoverAction(command, args, options) {
     const outputJson = options.json ?? config?.discovery?.json ?? false;
     const remoteUrl = options.url ?? config?.discovery?.url;
     const sessionId = options.sessionId ?? config?.discovery?.sessionId;
+    const configuredHeaders = mergeHeaders(config?.server?.headers, config?.discovery?.headers);
+    let cliHeaders;
+    try {
+        cliHeaders = parseCliHeaders(options.header);
+    }
+    catch (error) {
+        output.error(error instanceof Error ? error.message : String(error));
+        process.exit(EXIT_CODES.ERROR);
+    }
+    const headers = mergeHeaders(configuredHeaders, cliHeaders);
     // Validate transport options
     if (isRemoteTransport && !remoteUrl) {
         output.error(`Error: --url is required when using --transport ${transportType}`);
@@ -49,10 +61,11 @@ async function discoverAction(command, args, options) {
             await client.connectRemote(remoteUrl, {
                 transport: transportType,
                 sessionId,
+                headers,
             });
         }
         else {
-            await client.connect(command, args);
+            await client.connect(command, args, config?.server?.env);
         }
         output.info('Discovering capabilities...\n');
         const result = await discover(client, isRemoteTransport ? remoteUrl : command, isRemoteTransport ? [] : args);
@@ -83,7 +96,15 @@ async function discoverAction(command, args, options) {
         }
     }
     catch (error) {
-        output.error(`Discovery failed: ${error instanceof Error ? error.message : String(error)}`);
+        const message = error instanceof Error ? error.message : String(error);
+        output.error(`Discovery failed: ${message}`);
+        if (error instanceof ServerAuthError ||
+            message.includes('401') ||
+            message.includes('403') ||
+            message.includes('407') ||
+            /unauthorized|forbidden|authentication|authorization/i.test(message)) {
+            output.error('Hint: configure discovery.headers/server.headers or pass --header.');
+        }
         process.exit(EXIT_CODES.ERROR);
     }
     finally {
@@ -101,5 +122,6 @@ export const discoverCommand = new Command('discover')
     .option('--transport <type>', 'Transport type: stdio, sse, streamable-http')
     .option('--url <url>', 'URL for remote MCP server (requires --transport sse or streamable-http)')
     .option('--session-id <id>', 'Session ID for remote server authentication')
+    .option('-H, --header <header...>', 'Custom headers for remote MCP requests (e.g., "Authorization: Bearer token")')
     .action(discoverAction);
 //# sourceMappingURL=discover.js.map

package/dist/cli/commands/explore.js

@@ -13,7 +13,7 @@ import { MCPClient } from '../../transport/mcp-client.js';
 import { discover } from '../../discovery/discovery.js';
 import { Interviewer } from '../../interview/interviewer.js';
 import { generateAgentsMd, generateJsonReport } from '../../docs/generator.js';
-import { loadConfig, ConfigNotFoundError, parseCommandString, } from '../../config/loader.js';
+import { loadConfig, ConfigNotFoundError, } from '../../config/loader.js';
 import { validateConfigForExplore } from '../../config/validator.js';
 import { CostTracker, estimateInterviewCost, estimateInterviewTime, formatCostAndTimeEstimate, suggestOptimizations, formatOptimizationSuggestions, } from '../../cost/index.js';
 import { getMetricsCollector, resetMetricsCollector } from '../../metrics/collector.js';
@@ -31,6 +31,8 @@ import { suppressLogs, restoreLogLevel, configureLogger, } from '../../logging/l
 import { extractServerContextFromArgs } from '../utils/server-context.js';
 import { isCI } from '../utils/env.js';
 import { buildInterviewInsights } from '../../interview/insights.js';
+import { resolveServerRuntime } from '../utils/server-runtime.js';
+import { printExploreErrorHints } from '../utils/error-hints.js';
 /**
  * Wrapper to parse personas with warning output.
  */
@@ -45,6 +47,7 @@ export const exploreCommand = new Command('explore')
     .argument('[server-command]', 'Server command (overrides config)')
     .argument('[args...]', 'Server arguments')
     .option('-c, --config <path>', 'Path to config file', PATHS.DEFAULT_CONFIG_FILENAME)
+    .option('-H, --header <header...>', 'Custom headers for remote MCP requests (e.g., "Authorization: Bearer token")')
     .action(async (serverCommandArg, serverArgs, options) => {
     // Load configuration
     let config;
@@ -58,19 +61,27 @@ export const exploreCommand = new Command('explore')
         }
         throw error;
     }
-    // Determine server command (CLI arg overrides config)
-    // If command string contains spaces and no separate args, parse it
-    let serverCommand = serverCommandArg || config.server.command;
-    let args = serverArgs.length > 0 ? serverArgs : config.server.args;
-    // Handle command strings like "npx @package" in config when args is empty
-    if (!serverCommandArg && args.length === 0 && serverCommand.includes(' ')) {
-        const parsed = parseCommandString(serverCommand);
-        serverCommand = parsed.command;
-        args = parsed.args;
+    let serverCommand;
+    let args;
+    let transport;
+    let remoteUrl;
+    let remoteSessionId;
+    let remoteHeaders;
+    let serverIdentifier;
+    try {
+        const runtime = resolveServerRuntime(config, serverCommandArg, serverArgs, options.header);
+        serverCommand = runtime.serverCommand;
+        args = runtime.args;
+        transport = runtime.transport;
+        remoteUrl = runtime.remoteUrl;
+        remoteSessionId = runtime.remoteSessionId;
+        remoteHeaders = runtime.remoteHeaders;
+        serverIdentifier = runtime.serverIdentifier;
+    }
+    catch (error) {
+        output.error(error instanceof Error ? error.message : String(error));
+        process.exit(EXIT_CODES.ERROR);
     }
-    const transport = config.server.transport ?? 'stdio';
-    const remoteUrl = config.server.url?.trim();
-    const remoteSessionId = config.server.sessionId?.trim();
     // Validate config for explore
     try {
         validateConfigForExplore(config, serverCommand);
@@ -100,9 +111,6 @@ export const exploreCommand = new Command('explore')
     const provider = config.llm.provider;
     const model = config.llm.model || undefined;
     // Display startup banner
-    const serverIdentifier = transport === 'stdio'
-        ? `${serverCommand} ${args.join(' ')}`.trim()
-        : (remoteUrl ?? 'unknown');
     const banner = formatExploreBanner({
         serverCommand: serverIdentifier,
         provider,
@@ -184,6 +192,7 @@ export const exploreCommand = new Command('explore')
             await mcpClient.connectRemote(remoteUrl, {
                 transport,
                 sessionId: remoteSessionId || undefined,
+                headers: remoteHeaders,
             });
         }
         // Discovery phase
@@ -211,12 +220,18 @@ export const exploreCommand = new Command('explore')
             toolsDiscovered: discovery.tools.length,
             personasUsed: selectedPersonas.length,
         });
-        if (discovery.tools.length === 0) {
-            output.info('No tools found. Nothing to explore.');
+        const hasInterviewTargets = discovery.tools.length > 0 ||
+            discovery.prompts.length > 0 ||
+            (discovery.resources?.length ?? 0) > 0;
+        if (!hasInterviewTargets) {
+            output.info('No tools, prompts, or resources found. Nothing to explore.');
             metricsCollector.endInterview();
             await mcpClient.disconnect();
             return;
         }
+        if (discovery.tools.length === 0) {
+            output.info('No tools found; continuing with prompt/resource exploration.');
+        }
         // Show cost/time estimate (unless in CI)
         if (!isCI()) {
             const costEstimate = estimateInterviewCost(model || 'default', discovery.tools.length, maxQuestions, selectedPersonas.length);
@@ -480,26 +495,7 @@ export const exploreCommand = new Command('explore')
         const errorMessage = error instanceof Error ? error.message : String(error);
         output.error('\n--- Exploration Failed ---');
         output.error(`Error: ${errorMessage}`);
-        if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Connection refused')) {
-            output.error('\nPossible causes:');
-            output.error('  - The MCP server is not running');
-            output.error('  - The server address/port is incorrect');
-        }
-        else if (errorMessage.includes('timeout') || errorMessage.includes('Timeout')) {
-            output.error('\nPossible causes:');
-            output.error('  - The MCP server is taking too long to respond');
-            output.error('  - Increase server.timeout in bellwether.yaml');
-        }
-        else if (errorMessage.includes('ENOENT') || errorMessage.includes('not found')) {
-            output.error('\nPossible causes:');
-            output.error('  - The server command was not found');
-            output.error('  - Check that the command is installed and in PATH');
-        }
-        else if (errorMessage.includes('API key') || errorMessage.includes('authentication')) {
-            output.error('\nPossible causes:');
-            output.error('  - Missing or invalid API key');
-            output.error('  - Run "bellwether auth" to configure API keys');
-        }
+        printExploreErrorHints(error, transport);
         pendingExitCode = EXIT_CODES.ERROR;
     }
     finally {