agentic-qe 3.15.11 → 3.15.13

package/dist/mcp/handlers/task-orchestrate-handler.js

@@ -0,0 +1,361 @@
+/**
+ * Agentic QE v3 - task_orchestrate MCP handler
+ * ADR-051: Integrated with Model Router for intelligent tier selection
+ * Issue #206: Workflow auto-execution for task types with associated workflows
+ */
+import { getFleetState, isFleetInitialized } from './core-handlers.js';
+import { getTaskRouter } from '../services/task-router.js';
+import { getReasoningBankService, startTaskTrajectory } from '../services/reasoning-bank-service.js';
+import { scoreUnjudgedTrajectories } from './trajectory-judge.js';
+import { toErrorMessage } from '../../shared/error-utils.js';
+import { invalidPriorityMessage, isPriority } from '../../shared/types/index.js';
+import { validateIndexPaths } from '../../domains/code-intelligence/index-path-guard.js';
+import { routeInferredTask } from './orchestrate-routes.js';
+import { getTaskExecutor } from './handler-factory.js';
+import { TASK_WORKFLOW_MAP, inferDomainFromDescription, inferTaskType } from './task-inference.js';
+/**
+ * #1022: gather experience guidance and pattern hints for task_orchestrate.
+ * Learned guidance is optional: a missing embedder, or a ReasoningBank that
+ * cannot start, must not fail the orchestration. The returned status says
+ * which kind of matching produced the hints.
+ */
+async function getOrchestrateLearningContext(task, guidanceDomain, patternDomain) {
+    let service;
+    try {
+        service = await getReasoningBankService();
+    }
+    catch (error) {
+        return {
+            experienceGuidance: null,
+            patternHintMatches: [],
+            learning: { patternSearch: 'unavailable', reason: toErrorMessage(error) },
+        };
+    }
+    // #1204: a background embedder retry can finish while this call runs.
+    // Report vector matching only if the embedder was usable for the whole
+    // call, so hints found by text alone are never labelled vector.
+    const patternStatusBefore = service.getPatternSearchStatus();
+    const experienceStatusBefore = service.getExperienceGuidanceStatus();
+    const experienceGuidance = await service.getExperienceGuidance(task, guidanceDomain);
+    // Bring HNSW A (qe_patterns) into the routing decision alongside HNSW C
+    // (experienceGuidance). Without this, only past trajectories influenced
+    // routing — the catalog of consolidated long-term patterns was never
+    // consulted for new tasks. Fail-soft: empty array on error.
+    const patternHintMatches = await service
+        .searchPatternMatches(task, { limit: 5, domain: patternDomain })
+        .catch(() => []);
+    const status = notVectorIfEither(patternStatusBefore, service.getPatternSearchStatus());
+    const experienceStatusAfter = service.getExperienceGuidanceStatus();
+    const experienceStatus = experienceStatusBefore && experienceStatusAfter
+        ? notVectorIfEither(experienceStatusBefore, experienceStatusAfter)
+        : experienceStatusAfter;
+    return {
+        experienceGuidance,
+        patternHintMatches,
+        learning: {
+            patternSearch: status.mode,
+            ...(status.reason ? { reason: status.reason } : {}),
+            ...(experienceStatus ? { experienceGuidance: experienceStatus } : {}),
+        },
+    };
+}
+/** #1204: the status before the call unless it was vector; otherwise the one after. */
+function notVectorIfEither(before, after) {
+    return before.mode === 'vector' ? after : before;
+}
+export async function handleTaskOrchestrate(params) {
+    if (!isFleetInitialized()) {
+        return {
+            success: false,
+            error: 'Fleet not initialized. Call fleet_init first.',
+        };
+    }
+    // #1096: filePaths feeds task payloads (sourceFiles, index paths), so a
+    // non-array value is rejected up front with a clear message.
+    if (params.filePaths !== undefined) {
+        const filePaths = validateIndexPaths(params.filePaths, 'filePaths', 'Invalid task_orchestrate params');
+        if (!filePaths.success) {
+            return { success: false, error: filePaths.error.message };
+        }
+    }
+    // #1117: an unrecognised priority used to fall through to p1 (and a
+    // requested p0 was downgraded). Reject it up front, as task_submit does.
+    if (params.priority !== undefined && mapPriority(params.priority) === undefined) {
+        return { success: false, error: invalidOrchestratePriorityMessage(params.priority) };
+    }
+    const { queen, workflowOrchestrator } = getFleetState();
+    try {
+        // ADR-051: Route task to optimal model tier BEFORE execution
+        // Fix #282: Enrich routing input with inferred domain (same as handleModelRoute)
+        const inferredDomain = params.context?.project || inferDomainFromDescription(params.task);
+        const inferredIsCritical = params.priority === 'critical' ||
+            /\b(security|vulnerability|cve|owasp|critical|production|exploit)\b/i.test(params.task);
+        const router = await getTaskRouter();
+        const routingResult = await router.routeTask({
+            task: params.task,
+            codeContext: params.codeContext,
+            filePaths: params.filePaths,
+            manualTier: params.manualTier,
+            isCritical: inferredIsCritical,
+            agentType: `qe-${inferredDomain}`,
+            domain: inferredDomain,
+            metadata: {
+                inferredDomain,
+                hasCodeContext: !!params.codeContext,
+                fileCount: params.filePaths?.length,
+            },
+        });
+        // INTEGRATION FIX: Get ReasoningBank guidance for the task
+        const { experienceGuidance, patternHintMatches, learning } = await getOrchestrateLearningContext(params.task, params.context?.project, params.context?.project ?? inferredDomain);
+        // Parse task description to determine task type
+        const taskType = inferTaskType(params.task);
+        const priority = mapPriority(params.priority ?? 'medium') ?? 'p2';
+        // Issue #206: Check if this task type has an associated workflow
+        const workflowId = TASK_WORKFLOW_MAP[taskType];
+        if (workflowId && workflowOrchestrator) {
+            // Execute the associated workflow directly
+            console.log(`[TaskOrchestrate] Task type '${taskType}' has workflow '${workflowId}' - executing workflow`);
+            // Detect URL in task description for live website analysis
+            const urlMatch = params.task.match(/https?:\/\/[^\s]+/i);
+            const detectedUrl = urlMatch ? urlMatch[0] : undefined;
+            if (detectedUrl) {
+                console.log(`[TaskOrchestrate] Detected URL for analysis: ${detectedUrl}`);
+            }
+            // Build workflow input from task params and context
+            const workflowInput = {
+                // Pass through context fields as workflow input
+                targetId: params.context?.project || detectedUrl || `task-${Date.now()}`,
+                targetType: detectedUrl ? 'website' : 'epic',
+                description: params.task,
+                acceptanceCriteria: params.context?.requirements || [],
+                // Pass URL if detected (enables website content extraction)
+                url: detectedUrl,
+                // Include routing info for downstream processing
+                routing: {
+                    tier: routingResult.decision.tier,
+                    modelId: routingResult.modelId,
+                    executionStrategy: routingResult.executionStrategy,
+                    complexity: routingResult.decision.complexityAnalysis.overall,
+                },
+                // HNSW A pattern hints (mirrors the submitTask payload below); the
+                // workflow branch routes through executeWorkflow, so the same catalog
+                // of consolidated long-term patterns should reach it.
+                patternHints: patternHintMatches.length > 0
+                    ? patternHintMatches.map(({ pattern: p, similarity, score, matchType, canReuse }) => ({
+                        patternId: p.id,
+                        name: p.name,
+                        description: p.description,
+                        confidence: p.confidence,
+                        similarity,
+                        score,
+                        matchType,
+                        canReuse,
+                    }))
+                    : undefined,
+            };
+            const workflowResult = await workflowOrchestrator.executeWorkflow(workflowId, workflowInput);
+            if (!workflowResult.success) {
+                return {
+                    success: false,
+                    error: `Workflow execution failed: ${workflowResult.error.message}`,
+                };
+            }
+            return {
+                success: true,
+                data: {
+                    taskId: workflowResult.value, // This is the workflow execution ID
+                    type: taskType,
+                    priority,
+                    strategy: params.strategy || 'adaptive',
+                    status: 'workflow-started',
+                    message: `Workflow '${workflowId}' started for task: ${params.task}`,
+                    routing: {
+                        tier: routingResult.decision.tier,
+                        tierName: routingResult.tierInfo.name,
+                        modelId: routingResult.modelId,
+                        executionStrategy: routingResult.executionStrategy,
+                        complexity: routingResult.decision.complexityAnalysis.overall,
+                        confidence: routingResult.decision.confidence,
+                        useAgentBooster: routingResult.useAgentBooster,
+                        rationale: routingResult.decision.rationale,
+                        decisionTimeMs: routingResult.decision.metadata.decisionTimeMs,
+                    },
+                    learning,
+                },
+            };
+        }
+        // No workflow - submit as a regular task.
+        // #1125: an inferred type without a handler of its own runs the domain's
+        // concrete handler, with a payload built only from the request, or is
+        // refused with the input it needs.
+        const route = await routeInferredTask(taskType, params);
+        if (route.kind === 'needs-input') {
+            return { success: false, error: route.error };
+        }
+        const submitType = route.kind === 'route' ? route.type : taskType;
+        const targetDomains = route.kind === 'route' ? [route.domain] : [];
+        // #1200: a caller-owned task runs through the MCP task executor, as the
+        // domain's own tool does; the Queen does not dispatch it.
+        const callerExecutor = route.kind === 'route' && route.executionOwner === 'caller' ? getTaskExecutor() : null;
+        // #1081: the type must have a domain handler. Otherwise the Queen can
+        // only fail the task at dispatch, so reject it here with the reason.
+        const executable = queen.validateTaskExecutable(submitType, targetDomains);
+        if (!executable.success) {
+            return {
+                success: false,
+                error: `${executable.error.message}. task_orchestrate inferred '${taskType}' from the description; ` +
+                    'use task_submit with a supported type and its payload, or the domain\'s MCP tool.',
+            };
+        }
+        // Issue N2: Build domain-appropriate payload.
+        // Forward caller-provided filePaths/codeContext into the payload fields
+        // that domain plugins expect, so generate-tests doesn't reject with
+        // "missing sourceFiles" when called via task_orchestrate.
+        const taskPayload = {
+            description: params.task,
+            strategy: params.strategy || 'adaptive',
+            maxAgents: params.maxAgents,
+            context: params.context,
+        };
+        if (taskType === 'generate-tests') {
+            taskPayload.sourceFiles = params.filePaths || [];
+            taskPayload.sourceCode = params.codeContext || '';
+            taskPayload.language = taskPayload.language || 'typescript';
+            taskPayload.testType = taskPayload.testType || 'unit';
+        }
+        if (taskType === 'index-code') {
+            taskPayload.paths = params.filePaths || [];
+        }
+        if (route.kind === 'route')
+            Object.assign(taskPayload, route.payload);
+        const result = await queen.submitTask({
+            type: submitType,
+            ...(callerExecutor ? { executionOwner: 'caller' } : {}),
+            priority,
+            targetDomains,
+            payload: {
+                ...taskPayload,
+                // ADR-051: Include routing decision in payload for downstream processing
+                routing: {
+                    tier: routingResult.decision.tier,
+                    modelId: routingResult.modelId,
+                    executionStrategy: routingResult.executionStrategy,
+                    useAgentBooster: routingResult.useAgentBooster,
+                    agentBoosterTransform: routingResult.decision.agentBoosterTransform,
+                    complexity: routingResult.decision.complexityAnalysis.overall,
+                    confidence: routingResult.decision.confidence,
+                },
+                // INTEGRATION FIX: Include experience guidance if available
+                experienceGuidance: experienceGuidance ? {
+                    strategy: experienceGuidance.recommendedStrategy,
+                    actions: experienceGuidance.suggestedActions,
+                    confidence: experienceGuidance.confidence,
+                    tokenSavings: experienceGuidance.estimatedTokenSavings,
+                } : undefined,
+                // HNSW A pattern hints for the executing agent
+                patternHints: patternHintMatches.length > 0
+                    ? patternHintMatches.map(({ pattern: p, similarity, score, matchType, canReuse }) => ({
+                        patternId: p.id,
+                        name: p.name,
+                        description: p.description,
+                        confidence: p.confidence,
+                        similarity,
+                        score,
+                        matchType,
+                        canReuse,
+                    }))
+                    : undefined,
+            },
+            timeout: 600000, // 10 minutes for orchestrated tasks
+        });
+        if (!result.success) {
+            return {
+                success: false,
+                error: result.error.message,
+            };
+        }
+        // INTEGRATION FIX: Start trajectory tracking for learning
+        const taskId = result.value;
+        if (learning.patternSearch !== 'unavailable') {
+            await startTaskTrajectory(taskId, params.task, {
+                agent: 'queen-coordinator',
+                domain: params.context?.project,
+            });
+        }
+        // Issue N1: Trajectory auto-close is handled by subscribeTrajectoryEvents(),
+        // which listens for TaskCompleted/TaskFailed on the event router.
+        // No per-task polling needed.
+        // #1200: run a caller-owned task after its trajectory started, without
+        // waiting: the executor's TaskCompleted / TaskFailed settle it for task_status.
+        const execution = callerExecutor ? queen.getTaskStatus(taskId) : undefined;
+        if (callerExecutor && execution) {
+            void callerExecutor.execute(execution.task).catch(error => {
+                console.error(`[TaskOrchestrate] Task ${taskId} failed to execute: ${toErrorMessage(error)}`);
+            });
+        }
+        // Trajectory judge: opt-in LLM scoring of recent unscored trajectories.
+        // Hook-created rows in qe_trajectories never receive feedback unless
+        // something goes back and judges them. This catches up by scoring ≤5
+        // rows per task_orchestrate call. Opt-in (AQE_TRAJECTORY_JUDGE=1)
+        // because it makes paid LLM calls.
+        if (process.env.AQE_TRAJECTORY_JUDGE === '1' && process.env.ANTHROPIC_API_KEY) {
+            void scoreUnjudgedTrajectories().catch(err => {
+                console.warn('[TrajectoryJudge] failed:', err instanceof Error ? err.message : err);
+            });
+        }
+        return {
+            success: true,
+            data: {
+                taskId,
+                type: submitType,
+                ...(submitType !== taskType ? { inferredType: taskType } : {}),
+                priority,
+                strategy: params.strategy || 'adaptive',
+                status: 'submitted',
+                message: `Task orchestrated: ${params.task}${experienceGuidance ? ' (with experience guidance)' : ''}`,
+                // ADR-051: Include routing info in response
+                routing: {
+                    tier: routingResult.decision.tier,
+                    tierName: routingResult.tierInfo.name,
+                    modelId: routingResult.modelId,
+                    executionStrategy: routingResult.executionStrategy,
+                    complexity: routingResult.decision.complexityAnalysis.overall,
+                    confidence: routingResult.decision.confidence,
+                    useAgentBooster: routingResult.useAgentBooster,
+                    rationale: routingResult.decision.rationale,
+                    decisionTimeMs: routingResult.decision.metadata.decisionTimeMs,
+                },
+                learning,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to orchestrate task: ${toErrorMessage(error)}`,
+        };
+    }
+}
+/**
+ * Map a task_orchestrate priority to the canonical Priority type.
+ * Accepts the named levels and the canonical p0-p3 values; returns
+ * undefined for anything else so the caller can reject it (#1117).
+ */
+function mapPriority(priority) {
+    switch (priority) {
+        case 'critical':
+            return 'p0';
+        case 'high':
+            return 'p1';
+        case 'medium':
+            return 'p2';
+        case 'low':
+            return 'p3';
+        default:
+            return isPriority(priority) ? priority : undefined;
+    }
+}
+function invalidOrchestratePriorityMessage(value) {
+    return `${invalidPriorityMessage(value)} (or critical, high, medium, low)`;
+}
+//# sourceMappingURL=task-orchestrate-handler.js.map

package/dist/mcp/protocol-server.js

@@ -45,6 +45,14 @@ import { formatErrorForLog } from '../logging/redaction.js';
 import { BEHAVIOR_EXAMPLE_ITEM_SCHEMA } from '../domains/test-generation/services/behavior-example-validation.js';
 import { SAVE_RESULTS_HINT, saveResultsParameter } from './handlers/save-results-option.js';
 import { requestOwnedShutdown } from '../kernel/process-lifecycle.js';
+/**
+ * Read-only status tools a client polls while work runs. Repeating one is
+ * the status protocol, not a loop, so loop detection skips them (#1227).
+ */
+const LOOP_EXEMPT_STATUS_TOOLS = new Set([
+    'pipeline_status', 'task_status', 'task_list', 'fleet_status', 'fleet_health',
+    'agent_status', 'team_health', 'infra_healing_status', 'migration_status', 'aqe_health',
+]);
 import { createRequire } from 'module';
 const _require = createRequire(import.meta.url);
 const _pkg = _require('../../package.json');
@@ -440,8 +448,10 @@ export class MCPProtocolServer {
         let loopSteeringPrefix = '';
         // Polling a known execution is a normal status protocol, not a repeated
         // action loop. The default three-strike detector would block the third
-        // pipeline_status call within 30 seconds while a workflow is running.
-        if (process.env.AQE_LOOP_DETECTION_ENABLED !== 'false' && name !== 'pipeline_status') {
+        // identical status call within 30 seconds while the work is running
+        // (pipeline_status; #1227: task_status after task_submit, and the other
+        // read-only status tools a client polls).
+        if (process.env.AQE_LOOP_DETECTION_ENABLED !== 'false' && !LOOP_EXEMPT_STATUS_TOOLS.has(name)) {
             try {
                 const loopResult = this.loopTracker.trackCall('mcp-client', name, args);
                 if (loopResult.action === 'steer') {
@@ -684,6 +694,8 @@ export class MCPProtocolServer {
                 isCacheable: false,
                 parameters: [
                     { name: 'status', type: 'string', description: 'Filter by status' },
+                    { name: 'priority', type: 'string', description: 'Filter by priority', enum: ['p0', 'p1', 'p2', 'p3'] },
+                    { name: 'domain', type: 'string', description: 'Filter by assigned domain' },
                     { name: 'limit', type: 'number', description: 'Maximum results', default: 50 },
                 ],
             },
@@ -722,6 +734,7 @@ export class MCPProtocolServer {
                     { name: 'task', type: 'string', description: 'Task description', required: true },
                     { name: 'strategy', type: 'string', description: 'Execution strategy', enum: ['parallel', 'sequential', 'adaptive'] },
                     { name: 'filePaths', type: 'array', description: 'Project files the task works on. A security scan or quality assessment runs on these files and is refused without them.', items: { type: 'string' } },
+                    { name: 'priority', type: 'string', description: 'Task priority (default: medium/p2)', enum: ['p0', 'p1', 'p2', 'p3', 'critical', 'high', 'medium', 'low'] },
                 ],
             },
             handler: (params) => handleTaskOrchestrate(params),

package/dist/mcp/services/reasoning-bank-service.d.ts

@@ -11,7 +11,7 @@
  * - Pattern evolution and consolidation
  * - Synchronous learning (no fire-and-forget)
  */
-import { type Trajectory, type TrajectoryStep as TrackerTrajectoryStep, type TrajectoryOptions, type ExperienceGuidance, type EnhancedReasoningBankAdapterStats } from '../../integrations/agentic-flow/reasoning-bank/index.js';
+import { type Trajectory, type TrajectoryStep as TrackerTrajectoryStep, type TrajectoryOptions, type ExperienceGuidance, type ExperienceGuidanceStatus, type EnhancedReasoningBankAdapterStats } from '../../integrations/agentic-flow/reasoning-bank/index.js';
 import { type RealQERoutingRequest, type RealQERoutingResult, type RealQEReasoningBankStats, type PatternSearchStatus, type RealQEPatternSearchResult } from '../../learning/real-qe-reasoning-bank.js';
 import type { QEPattern, QEDomain } from '../../learning/qe-patterns.js';
 /**
@@ -210,6 +210,11 @@ export declare class ReasoningBankService {
     }): Promise<RealQEPatternSearchResult[]>;
     /** #1022: whether pattern search uses vectors or text matching only. */
     getPatternSearchStatus(): PatternSearchStatus;
+    /**
+     * #1204: whether similar-experience guidance can use vectors; null when
+     * experience replay is disabled or the service is disposed.
+     */
+    getExperienceGuidanceStatus(): ExperienceGuidanceStatus | null;
     /**
      * Get service statistics
      */

package/dist/mcp/services/reasoning-bank-service.js

@@ -519,6 +519,15 @@ export class ReasoningBankService {
     getPatternSearchStatus() {
         return this.enhancedAdapter.getPatternSearchStatus();
     }
+    /**
+     * #1204: whether similar-experience guidance can use vectors; null when
+     * experience replay is disabled or the service is disposed.
+     */
+    getExperienceGuidanceStatus() {
+        if (!this.config.enableExperienceReplay || this.disposed)
+            return null;
+        return this.enhancedAdapter.getExperienceGuidanceStatus();
+    }
     /**
      * Get service statistics
      */

package/dist/mcp/tools/code-intelligence/analyze.js

@@ -164,13 +164,10 @@ export class CodeAnalyzeTool extends MCPToolBase {
             scope: paths.length > 0 && paths[0] !== '.' ? paths : undefined,
         });
         const searchTime = Date.now() - startTime;
-        // If search failed, return error
+        // #1224: a search that could not run (e.g. nothing indexed) is an error,
+        // not an empty result.
         if (!result.success) {
-            return {
-                results: [],
-                total: 0,
-                searchTime,
-            };
+            throw result.error;
         }
         // Empty results is a valid state - no matches found
         if (result.value.results.length === 0) {

package/dist/mcp/tools/coverage-analysis/index.d.ts

@@ -39,6 +39,8 @@ export interface CoverageAnalyzeResult {
     language?: string;
     /** Coverage format used for parsing */
     format?: string;
+    /** Parts of the coverage report that could not be attributed to a file and are not reported (#1232). */
+    warnings?: string[];
 }
 export interface CoverageSummary {
     lines: CoverageMetric;
@@ -90,6 +92,8 @@ export interface CoverageGapsResult {
         description: string;
         confidence: number;
     }>;
+    /** Parts of the coverage report that could not be attributed to a file and are not reported (#1232). */
+    warnings?: string[];
 }
 export interface CoverageGap {
     file: string;

package/dist/mcp/tools/coverage-analysis/index.js

@@ -33,6 +33,10 @@ async function confineCoverageInputs(tool, target, coverageFile) {
         return { error: f.error.message };
     return { target: confinedTarget, coverageFile: f.value };
 }
+/** The parser's warnings as an error-message suffix (#1232), or ''. */
+function describeWarnings(report) {
+    return report?.warnings?.length ? ` ${report.warnings.join('. ')}.` : '';
+}
 // ============================================================================
 // Helper: Calculate Coverage Summary from Files
 // ============================================================================
@@ -155,7 +159,7 @@ export class CoverageAnalyzeTool extends MCPToolBase {
             if (!parsedReport || parsedReport.files.size === 0) {
                 return {
                     success: false,
-                    error: `No coverage data found in '${target}'. Run your test suite with coverage enabled (e.g., 'npm test -- --coverage') and ensure coverage reports are generated (lcov.info, coverage-final.json, etc.)`,
+                    error: `No coverage data found in '${target}'. Run your test suite with coverage enabled (e.g., 'npm test -- --coverage') and ensure coverage reports are generated (lcov.info, coverage-final.json, etc.)${describeWarnings(parsedReport)}`,
                 };
             }
             // Mark as real data - we have actual coverage
@@ -250,6 +254,7 @@ export class CoverageAnalyzeTool extends MCPToolBase {
                     trends,
                     language: detectedLanguage,
                     format: detectedFormat,
+                    ...(parsedReport.warnings ? { warnings: parsedReport.warnings } : {}),
                 },
             };
         }
@@ -376,7 +381,7 @@ export class CoverageGapsTool extends MCPToolBase {
                 if (coverageFile) {
                     return {
                         success: false,
-                        error: `Coverage file '${coverageFile}' contains no usable coverage data (parsed 0 files). Verify the file is a non-empty Istanbul/LCOV/JaCoCo/etc. report.`,
+                        error: `Coverage file '${coverageFile}' contains no usable coverage data (parsed 0 files). Verify the file is a non-empty Istanbul/LCOV/JaCoCo/etc. report.${describeWarnings(parsedReport)}`,
                     };
                 }
                 return {
@@ -462,6 +467,7 @@ export class CoverageGapsTool extends MCPToolBase {
                     criticalGaps: gaps.filter((g) => g.severity === 'critical').length,
                     suggestedTests,
                     ...(ghostGaps ? { ghostGaps } : {}),
+                    ...(parsedReport.warnings ? { warnings: parsedReport.warnings } : {}),
                 },
             };
         }

package/dist/mcp/tools/visual-accessibility/index.d.ts

@@ -75,11 +75,15 @@ export interface A11yAuditResult {
 }
 export interface UrlAudit {
     url: string;
+    /** 0-100 when measured; -1 when the URL was not measured (#1145). */
     score: number;
     passed: boolean;
     violations: A11yViolation[];
     warnings: A11yWarning[];
     passedRules: number;
+    /** False when no browser audited the URL; it is then neither passing nor failing (#1145). */
+    measured?: boolean;
+    notMeasuredReason?: string;
 }
 export interface A11yViolation {
     id: string;
@@ -103,7 +107,10 @@ export interface A11yWarning {
 }
 export interface A11ySummary {
     totalUrls: number;
+    /** URLs a browser actually audited; passing/score/violation counts cover only these (#1145). */
+    measuredUrls?: number;
     passingUrls: number;
+    /** Mean over measured URLs; -1 when none was measured (#1145). */
     avgScore: number;
     criticalViolations: number;
     seriousViolations: number;

package/dist/mcp/tools/visual-accessibility/index.js

@@ -218,19 +218,24 @@ export class A11yAuditTool extends MCPToolBase {
                     wcagLevel,
                     includeWarnings,
                 });
-                if (!auditResult.success) {
-                    // Add failed audit with error info
+                if (!auditResult.success || auditResult.value.measured !== true) {
+                    // #1145: an unmeasured URL carries no findings and no verdict
                     audits.push({
                         url,
-                        score: 0,
+                        score: -1,
                         passed: false,
                         violations: [],
                         warnings: [],
                         passedRules: 0,
+                        measured: false,
+                        notMeasuredReason: auditResult.success
+                            ? auditResult.value.notMeasuredReason ?? 'not measured'
+                            : auditResult.error.message,
                     });
                     continue;
                 }
                 const report = auditResult.value;
+                const notMeasuredWarnings = [];
                 // Optionally check contrast
                 let contrastViolations = [];
                 if (checkContrast) {
@@ -256,6 +261,9 @@ export class A11yAuditTool extends MCPToolBase {
                             }));
                         }
                     }
+                    else {
+                        notMeasuredWarnings.push({ id: 'color-contrast-not-measured', description: contrastResult.error.message, nodes: 0 });
+                    }
                 }
                 // Optionally check keyboard navigation
                 const keyboardViolations = [];
@@ -302,6 +310,9 @@ export class A11yAuditTool extends MCPToolBase {
                             });
                         }
                     }
+                    else {
+                        notMeasuredWarnings.push({ id: 'keyboard-not-measured', description: keyboardResult.error.message, nodes: 0 });
+                    }
                 }
                 // Convert report violations to output format
                 const violations = [
@@ -323,11 +334,11 @@ export class A11yAuditTool extends MCPToolBase {
                     ...keyboardViolations,
                 ];
                 // Convert warnings (from incomplete checks)
-                const warnings = report.incomplete.map((i) => ({
-                    id: i.id,
-                    description: i.description,
-                    nodes: i.nodes.length,
-                }));
+                const warnings = [...report.incomplete.map((i) => ({
+                        id: i.id,
+                        description: i.description,
+                        nodes: i.nodes.length,
+                    })), ...notMeasuredWarnings];
                 const hasCriticalOrSerious = violations.some((v) => v.impact === 'critical' || v.impact === 'serious');
                 audits.push({
                     url,
@@ -336,14 +347,17 @@ export class A11yAuditTool extends MCPToolBase {
                     violations,
                     warnings,
                     passedRules: report.passes.length,
+                    measured: true,
                 });
             }
+            const measuredAudits = audits.filter((a) => a.measured === true);
             const summary = {
                 totalUrls: audits.length,
-                passingUrls: audits.filter((a) => a.passed).length,
-                avgScore: audits.length > 0
-                    ? Math.round(audits.reduce((sum, a) => sum + a.score, 0) / audits.length)
-                    : 0,
+                measuredUrls: measuredAudits.length,
+                passingUrls: measuredAudits.filter((a) => a.passed).length,
+                avgScore: measuredAudits.length > 0
+                    ? Math.round(measuredAudits.reduce((sum, a) => sum + a.score, 0) / measuredAudits.length)
+                    : -1,
                 criticalViolations: audits.reduce((sum, a) => sum + a.violations.filter((v) => v.impact === 'critical').length, 0),
                 seriousViolations: audits.reduce((sum, a) => sum + a.violations.filter((v) => v.impact === 'serious').length, 0),
                 totalViolations: audits.reduce((sum, a) => sum + a.violations.length, 0),
@@ -352,7 +366,9 @@ export class A11yAuditTool extends MCPToolBase {
             const remediationPlan = generateRemediationPlan(topIssues);
             this.emitStream(context, {
                 status: 'complete',
-                message: `Audit complete: avg score ${summary.avgScore}%`,
+                message: summary.avgScore < 0
+                    ? `Audit complete: no URL measured (0/${summary.totalUrls}); no score`
+                    : `Audit complete: ${summary.measuredUrls}/${summary.totalUrls} URL(s) measured, avg score ${summary.avgScore}%`,
                 progress: 100,
             });
             return {