refactor(search): tighten fanout merge, cooldown error, and skip-list lookup (FEAT-047)

Final PR #128 review polish. Fanout merge now sets number_of_results to the
merged result count so the JSON envelope is self-consistent. The all-instances-
failed error emits a distinct cooldown-specific message (no misleading "failed",
no double space) when every instance was skipped due to cooldown rather than
attempted. skippedInstances membership now uses a Set instead of Array.includes.
URL/result behavior is otherwise unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Codex <noreply@openai.com>

Author: 3 people

__tests__/unit/search.test.ts

@@ -1953,6 +1953,7 @@ async function runTests() {
         return createMockFetch({
           json: {
             query: 'fanout',
+            number_of_results: 2,
             results: [
               { title: 'Lower Duplicate', content: 'Low', url: 'https://Example.com/same#section', score: 0.2 },
               { title: 'Missing Score', content: 'No score', url: 'not a url', score: undefined },
@@ -1963,6 +1964,7 @@ async function runTests() {
       return createMockFetch({
         json: {
           query: 'fanout',
+          number_of_results: 3,
           results: [
             { title: 'Highest', content: 'High', url: 'https://example.com/high', score: 0.95 },
             { title: 'Higher Duplicate', content: 'Better', url: 'https://example.com/same', score: 0.7 },
@@ -1978,6 +1980,40 @@ async function runTests() {
     assert.deepEqual(requestedHosts.sort(), ['https://one.example.com', 'https://two.example.com']);
     assert.deepEqual(payload.servedBy, ['https://one.example.com', 'https://two.example.com']);
     assert.deepEqual(payload.results.map((entry: any) => entry.title), ['Highest', 'Higher Duplicate', 'Raw URL Copy']);
+    assert.equal(payload.number_of_results, payload.results.length);
+    assert.equal(payload.number_of_results, 3);
+
+    fetchMocker.restore();
+    envManager.restore();
+  }, results);
+
+  await testFunction('all cooled down instances throw cooldown-specific message without double spaces', async () => {
+    clearSearxngInstanceStateForTests();
+    envManager.set('SEARXNG_URL', 'https://cooled-one.example.com;https://cooled-two.example.com');
+
+    for (const instanceUrl of ['https://cooled-one.example.com', 'https://cooled-two.example.com']) {
+      recordSearxngInstanceFailure(instanceUrl, Date.now());
+      recordSearxngInstanceFailure(instanceUrl, Date.now());
+      recordSearxngInstanceFailure(instanceUrl, Date.now());
+    }
+
+    const mockServer = createMockServer();
+    let fetchCalled = false;
+    fetchMocker.mock(async () => {
+      fetchCalled = true;
+      return createMockFetch({ json: { results: [] } })('https://unused.example.com');
+    });
+
+    try {
+      await performWebSearch(mockServer as any, 'all cooled');
+      assert.fail('Expected all-cooled error');
+    } catch (error: any) {
+      assert.ok(error.message.includes('All configured SearXNG instances are in cooldown after repeated failures'), error.message);
+      assert.ok(error.message.includes('https://cooled-one.example.com'), error.message);
+      assert.ok(error.message.includes('https://cooled-two.example.com'), error.message);
+      assert.ok(!error.message.includes('  '), error.message);
+    }
+    assert.equal(fetchCalled, false);
 
     fetchMocker.restore();
     envManager.restore();

src/search.ts

@@ -576,6 +576,12 @@ function hasSearchResults(data: SearXNGWeb): boolean {
 }
 
 function createAllInstancesFailedError(failures: FailedInstanceResult[], skippedInstances: string[]): MCPSearXNGError {
+  if (failures.length === 0 && skippedInstances.length > 0) {
+    return new MCPSearXNGError(
+      `All configured SearXNG instances are in cooldown after repeated failures: ${skippedInstances.join(", ")}.`
+    );
+  }
+
   const failureDetails = failures
     .map(({ instanceUrl, error }) => `${instanceUrl}: ${error instanceof Error ? error.message : String(error)}`)
     .join("; ");
@@ -592,7 +598,8 @@ async function performFailoverSearch(
   request: SearchRequest,
 ): Promise<MultiInstanceSearchResult> {
   const healthyInstances = getHealthySearxngInstances(instances);
-  const skippedInstances = instances.filter((instanceUrl) => !healthyInstances.includes(instanceUrl));
+  const healthySet = new Set(healthyInstances);
+  const skippedInstances = instances.filter((instanceUrl) => !healthySet.has(instanceUrl));
   const failures: FailedInstanceResult[] = [];
   const emptyResults: EmptyInstanceResult[] = [];
 
@@ -656,9 +663,12 @@ function mergeFanoutResults(results: InstanceSearchResult[]): SearXNGWeb {
     }
   }
 
+  const mergedResults = [...byUrl.values()].sort((a, b) => resultScore(b) - resultScore(a));
+
   return {
     ...base,
-    results: [...byUrl.values()].sort((a, b) => resultScore(b) - resultScore(a)),
+    number_of_results: mergedResults.length,
+    results: mergedResults,
   };
 }
 
@@ -668,7 +678,8 @@ async function performFanoutSearch(
   request: SearchRequest,
 ): Promise<MultiInstanceSearchResult> {
   const healthyInstances = getHealthySearxngInstances(instances);
-  const skippedInstances = instances.filter((instanceUrl) => !healthyInstances.includes(instanceUrl));
+  const healthySet = new Set(healthyInstances);
+  const skippedInstances = instances.filter((instanceUrl) => !healthySet.has(instanceUrl));
   const settledResults = await Promise.all(healthyInstances.map(async (instanceUrl) => {
     try {
       const result = await fetchSearchFromInstance(mcpServer, instanceUrl, request);