smart-web-mcp 0.44.0 → 1.0.0

package/dist/smartsearch.js

@@ -1,9 +1,19 @@
-import { configEnabled, fetchText, resolveDuckDuckGoUrl, smartWebProfile, stripTags, uniqueResults, validateOutboundUrl } from "./shared.js";
+import { configEnabled, fetchText, smartWebProfile, stripTags, uniqueResults, validateOutboundUrl } from "./shared.js";
 import { createAssessment, createHandoffSuggestion, detectInteractiveLikeText, firstMeaningfulBlockedReason } from "./assessment.js";
 import { configText } from "./settings.js";
 import { runSmartcrawl } from "./smartcrawl.js";
 import { budgetText, projectRetrievalAssessment } from "./extraction/budget.js";
 import { parseFeed } from "./smartfetch/generic-fallbacks.js";
+import { runBrowserSession } from "./browser-session.js";
+import { browserSearchMatchesQuery, parseNaverBrowserSearch, searchResultMatchesSite } from "./smartsearch-browser.js";
+import { parseBraveSearch } from "./smartsearch-brave.js";
+import { parseHTML } from "linkedom";
+import { parseDuckDuckGoSearch } from "./smartsearch-ddg.js";
+import { parsePythonDocsSearch, pythonDocsSearchUrl, unscopedPythonDocsTerms } from "./smartsearch-python.js";
+import { postgresqlDocsBodyHasSymbol, postgresqlDocsCandidates, postgresqlDocsIntent } from "./smartsearch-postgresql.js";
+import { nodeDocsIntent, nodeDocsOriginal } from "./smartsearch-node.js";
+import { parseYoutubeSearch, youtubeSearchUrl } from "./smartsearch-youtube.js";
+import { discoveryEvidenceScore, hasDiscoveryYield, isSearchTrackingRelay, koreanDiscoveryTerms, rankDiscoveryResults } from "./smartsearch-quality.js";
 const DEFAULT_TIMEOUT_MS = 12000;
 const DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36";
 const SMARTSEARCH_BUDGET_PRESETS = {
@@ -94,21 +104,46 @@ export function projectSmartsearchOutput(response, preset = "compact") {
             metadata[path] = projected.metadata;
         return projected.value;
     };
-    const results = budgetList(response.results, policy.maxResults);
-    recordListMetadata(metadata, "results", results.metadata);
+    // A clipped URL is not an original the caller can open; omit it rather than
+    // returning a plausible-looking but invalid link, and fill from later rows.
+    const usableResults = response.results.filter((item) => item.url.length <= policy.maxUrlChars);
+    const omittedUrls = response.results.length - usableResults.length;
+    const results = budgetList(usableResults, policy.maxResults);
+    if (omittedUrls > 0 || results.metadata.truncated) {
+        metadata.results = {
+            truncated: true,
+            original_items: response.results.length,
+            returned_items: results.items.length,
+            omitted_items: response.results.length - results.items.length,
+        };
+    }
     const projectedResults = results.items.map((item, index) => ({
         ...item,
         title: projectText(item.title, policy.maxTitleChars, `results.${index}.title`),
-        url: projectText(item.url, policy.maxUrlChars, `results.${index}.url`),
+        url: item.url,
         snippet: projectText(item.snippet || "", policy.maxSnippetChars, `results.${index}.snippet`),
         engine: projectText(item.engine, policy.maxEngineChars, `results.${index}.engine`),
     }));
     const notes = budgetList(response.notes, policy.maxNotes);
     recordListMetadata(metadata, "notes", notes.metadata);
     const projectedNotes = notes.items.map((note, index) => projectText(note, policy.maxNoteChars, `notes.${index}`));
+    if (omittedUrls > 0)
+        projectedNotes.push(`${omittedUrls} original URL(s) omitted because they exceed the ${policy.maxUrlChars}-character output limit.`);
     const fallbacks = budgetList(response.fallbacks_tried, policy.maxFallbacks);
     recordListMetadata(metadata, "fallbacks_tried", fallbacks.metadata);
     const projectedFallbacks = fallbacks.items.map((fallback, index) => projectText(fallback, policy.maxFallbackChars, `fallbacks_tried.${index}`));
+    const execution = response.execution ? (() => {
+        const attempts = budgetList(response.execution.attempts, policy.maxFallbacks);
+        recordListMetadata(metadata, "execution.attempts", attempts.metadata);
+        return {
+            ...response.execution,
+            attempts: attempts.items.map((attempt, index) => ({
+                ...attempt,
+                provider: projectText(attempt.provider, policy.maxEngineChars, `execution.attempts.${index}.provider`),
+                ...(attempt.error === undefined ? {} : { error: projectText(attempt.error, policy.maxNoteChars, `execution.attempts.${index}.error`) }),
+            })),
+        };
+    })() : undefined;
     const handoff = response.handoff ? (() => {
         const items = budgetList(response.handoff.items, policy.maxHandoffItems);
         recordListMetadata(metadata, "handoff.items", items.metadata);
@@ -139,6 +174,8 @@ export function projectSmartsearchOutput(response, preset = "compact") {
             maxUrlChars: policy.maxUrlChars,
         }, metadata)
         : undefined;
+    if (omittedUrls > 0 && assessment)
+        assessment.confidence = "low";
     const engine = projectText(response.engine, policy.maxEngineChars, "engine");
     const query = projectText(response.query, policy.maxQueryChars, "query");
     const truncated = Object.values(metadata).some((item) => item.truncated);
@@ -157,6 +194,7 @@ export function projectSmartsearchOutput(response, preset = "compact") {
         results: projectedResults,
         fallbacks_tried: projectedFallbacks,
         notes: projectedNotes,
+        ...(execution ? { execution } : {}),
         ...(handoff ? { handoff } : {}),
         ...(assessment ? { assessment } : {}),
         budget: {
@@ -166,6 +204,21 @@ export function projectSmartsearchOutput(response, preset = "compact") {
         },
     };
 }
+export function isSmartsearchExecutionFailure(response) {
+    return response.execution?.status === "failed";
+}
+function completedProviderSearch(results, note) {
+    return { ok: results.length > 0, status: "succeeded", results, note };
+}
+function failedProviderSearch(note) {
+    return { ok: false, status: "failed", results: [], note };
+}
+function smartsearchExecution(attempts) {
+    return {
+        status: attempts.some((attempt) => attempt.status === "succeeded") ? "succeeded" : "failed",
+        attempts,
+    };
+}
 function localOnlyMode() {
     return configEnabled("network.localOnly", false, { private: true });
 }
@@ -329,9 +382,13 @@ function buildSearchResponse(response, handoff) {
     return handoff ? { ...response, handoff, assessment } : { ...response, assessment };
 }
 function assessSearchResponse(response, handoff) {
-    const blockedReason = firstMeaningfulBlockedReason(response.notes);
-    const publicHtmlEngine = response.engine === "duckduckgo" || response.engine === "brave_html";
-    const confidence = response.results.length === 0
+    // A failed earlier engine remains in notes, but does not block an exact
+    // watch-page original recovered from the site's own search.
+    const blockedReason = response.engine === "youtube_browser" && response.results.length > 0 ? "" : firstMeaningfulBlockedReason(response.notes);
+    const publicHtmlEngine = ["duckduckgo", "brave_html", "naver_browser", "youtube_browser", "mixed"].includes(response.engine);
+    const weakDiscovery = (publicHtmlEngine || response.engine === "searxng")
+        && !hasDiscoveryYield(response.results, koreanDiscoveryTerms(response.query), response.results.length || 1);
+    const confidence = weakDiscovery ? "low" : response.results.length === 0
         ? (handoff?.performed ? "medium" : "low")
         : (response.results.length >= 3 && !publicHtmlEngine ? "high" : "medium");
     const interactiveFlowLikely = Boolean(handoff && !handoff.performed && detectInteractiveLikeText(handoff.reason));
@@ -379,6 +436,15 @@ async function maybeRunCrawlHandoff(response, options, runtime) {
     }
     const crawlQuery = stripSiteOperators(options.query);
     const mode = inferCrawlMode(startUrl, options.crawlMode);
+    const siteTokens = searchQueryTokens(options.query).filter(token => /^site:[^"']+$/i.test(token));
+    if (siteTokens.length === 1 && extractSiteScope(siteTokens[0])?.host === "news.ycombinator.com" && parseHnDateQuery(options.query).bounded) {
+        const reason = "site_crawl not performed: HN date constraints require native publication timestamps that crawl items do not verify";
+        const declined = buildSearchResponse({ ...response, notes: [...response.notes, reason] }, {
+            tool: "smartcrawl", performed: false, reason, start_url: startUrl, query: options.query, mode,
+            items: [], pages_attempted: 0, pages_loaded: 0, errors: [reason],
+        });
+        return { ...declined, assessment: createAssessment({ ...declined.assessment, recommended_handoff: null }) };
+    }
     const crawl = await (runtime.runSmartcrawl || runSmartcrawl)({
         url: startUrl,
         ...(crawlQuery ? { query: crawlQuery } : {}),
@@ -429,7 +495,7 @@ async function searchVelog(query, numResults, timeoutMs) {
         }),
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `Velog search error ${result.status}` };
+        return failedProviderSearch(result.error || `Velog search error ${result.status}`);
     try {
         const data = result.text ? JSON.parse(result.text) : {};
         const raw = Array.isArray(data?.data?.searchPosts?.posts) ? data.data.searchPosts.posts : [];
@@ -439,11 +505,11 @@ async function searchVelog(query, numResults, timeoutMs) {
             snippet: String(item?.short_description || "").trim(),
             engine: "velog",
         })).filter((item) => item.url)).slice(0, numResults);
-        return { ok: results.length > 0, results, note: results.length > 0 ? "" : "Velog search returned no results" };
+        return completedProviderSearch(results, results.length > 0 ? "" : "Velog search returned no results");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, note: `Velog search parse error: ${message}` };
+        return failedProviderSearch(`Velog search parse error: ${message}`);
     }
 }
 async function searchStackExchange(query, numResults, timeoutMs) {
@@ -463,7 +529,7 @@ async function searchStackExchange(query, numResults, timeoutMs) {
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `StackExchange error ${result.status}` };
+        return failedProviderSearch(result.error || `StackExchange error ${result.status}`);
     try {
         const data = result.text ? JSON.parse(result.text) : {};
         const raw = Array.isArray(data?.items) ? data.items : [];
@@ -473,27 +539,71 @@ async function searchStackExchange(query, numResults, timeoutMs) {
             snippet: String(item?.tags?.join(", ") || "").trim(),
             engine: "stackexchange",
         })).filter((item) => item.url)).slice(0, numResults);
-        return { ok: results.length > 0, results, note: results.length > 0 ? "" : "StackExchange search returned no results" };
+        return completedProviderSearch(results, results.length > 0 ? "" : "StackExchange search returned no results");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, note: `StackExchange parse error: ${message}` };
+        return failedProviderSearch(`StackExchange parse error: ${message}`);
     }
 }
-async function searchHackerNews(query, numResults, timeoutMs) {
-    const q = stripSiteOperators(query) || query;
-    const result = await fetchText(`https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(q)}&tags=story&hitsPerPage=${Math.min(numResults, 20)}`, timeoutMs, {
+function searchQueryTokens(query) {
+    return query.match(/"(?:\\.|[^"\\])*"|'[^']*'|[()]|[^\s()]+/g) || [];
+}
+function parseHnDateQuery(query) {
+    const tokens = searchQueryTokens(query).filter(token => !/^site:[^"']+$/i.test(token));
+    const parsed = { text: "", bounded: false };
+    const terms = [];
+    for (const token of tokens) {
+        const operator = /^(after|before):(.*)$/i.exec(token);
+        if (!operator) {
+            terms.push(token);
+            continue;
+        }
+        parsed.bounded = true;
+        const date = operator[2];
+        const timestamp = Date.parse(`${date}T00:00:00Z`);
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || !Number.isFinite(timestamp) || new Date(timestamp).toISOString().slice(0, 10) !== date) {
+            parsed.error = `Invalid HN date constraint: ${token}; use a real UTC calendar date YYYY-MM-DD`;
+            continue;
+        }
+        const seconds = timestamp / 1000;
+        if (operator[1].toLowerCase() === "after")
+            parsed.after = Math.max(parsed.after ?? -Infinity, seconds);
+        else
+            parsed.before = Math.min(parsed.before ?? Infinity, seconds);
+    }
+    parsed.text = terms.join(" ");
+    if (parsed.bounded && terms.some(term => /^(?:AND|OR|NOT)$/.test(term) || /[()]/.test(term.replace(/^(["']).*\1$/, ""))))
+        parsed.error = "HN date constraints with Boolean/grouped expressions are unsupported; refusing to change their scope";
+    if (parsed.after !== undefined && parsed.before !== undefined && parsed.after >= parsed.before)
+        parsed.error = "HN date constraints have an empty or reversed UTC interval";
+    return parsed;
+}
+async function searchHackerNews(query, numResults, timeoutMs, dates) {
+    const q = dates.bounded ? dates.text : stripSiteOperators(query) || query;
+    const params = new URLSearchParams({ query: q, tags: "story", hitsPerPage: String(Math.min(numResults, 20)) });
+    const filters = [dates.after === undefined ? "" : `created_at_i>=${dates.after}`, dates.before === undefined ? "" : `created_at_i<${dates.before}`].filter(Boolean);
+    if (filters.length)
+        params.set("numericFilters", filters.join(","));
+    const result = await fetchText(`https://hn.algolia.com/api/v1/search?${params}`, timeoutMs, {
         headers: {
             accept: "application/json,text/plain,*/*",
             "user-agent": DEFAULT_USER_AGENT,
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `Hacker News error ${result.status}` };
+        return failedProviderSearch(result.error || `Hacker News error ${result.status}`);
     try {
         const data = result.text ? JSON.parse(result.text) : {};
-        const raw = Array.isArray(data?.hits) ? data.hits : [];
-        const results = uniqueResults(raw.map((item) => {
+        if (!Array.isArray(data?.hits))
+            return failedProviderSearch("Hacker News returned an invalid hits payload");
+        const raw = data.hits;
+        const valid = dates.bounded ? raw.filter((item) => item && typeof item.objectID === "string" && /^\d+$/.test(item.objectID)
+            && typeof item.title === "string" && item.title.trim() && Number.isSafeInteger(item.created_at_i) && Math.abs(item.created_at_i) <= 8640000000000
+            && (dates.after === undefined || item.created_at_i >= dates.after) && (dates.before === undefined || item.created_at_i < dates.before)) : raw;
+        if (dates.bounded && raw.length && !valid.length)
+            return failedProviderSearch("Hacker News returned no verifiable stories satisfying the requested date constraints");
+        const results = uniqueResults(valid.map((item) => {
             const objectId = String(item?.objectID || "").trim();
             let linkedHost = "";
             try {
@@ -506,19 +616,20 @@ async function searchHackerNews(query, numResults, timeoutMs) {
                 title: String(item?.title || item?.story_title || `HN #${objectId}`).trim(),
                 url: objectId ? `https://news.ycombinator.com/item?id=${objectId}` : "",
                 snippet: [
+                    dates.bounded ? new Date(item.created_at_i * 1000).toISOString() : "",
                     item?.points ? `▲ ${item.points}` : "",
                     item?.author ? `by ${item.author}` : "",
-                    item?.created_at ? String(item.created_at).slice(0, 10) : "",
+                    !dates.bounded && item?.created_at ? String(item.created_at).slice(0, 10) : "",
                     linkedHost ? `→ ${linkedHost}` : "",
                 ].filter(Boolean).join(" · "),
                 engine: "hackernews",
             };
         }).filter((item) => item.url)).slice(0, numResults);
-        return { ok: results.length > 0, results, note: results.length > 0 ? "" : "Hacker News search returned no results" };
+        return { ...completedProviderSearch(results, results.length > 0 ? "" : "Hacker News search returned no results"), hnDateBoundsVerified: dates.bounded };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, note: `Hacker News parse error: ${message}` };
+        return failedProviderSearch(`Hacker News parse error: ${message}`);
     }
 }
 function redditSubredditScope(query) {
@@ -552,11 +663,12 @@ async function searchReddit(query, numResults, timeoutMs) {
     const subreddit = redditSubredditScope(query);
     const notes = [];
     let collected = [];
+    let completed = false;
     const collect = (results) => {
         collected = uniqueResults([...collected, ...results]).slice(0, numResults);
         return collected.length >= numResults;
     };
-    const success = () => ({ ok: true, results: collected, note: "" });
+    const success = () => completedProviderSearch(collected, "");
     const keepScope = (results) => {
         if (!subreddit)
             return results;
@@ -581,6 +693,7 @@ async function searchReddit(query, numResults, timeoutMs) {
         },
     });
     if (rss.ok) {
+        completed = true;
         const feed = parseFeed(rss.text, rssUrl);
         const results = keepScope(uniqueResults((feed?.entries || []).map((entry) => {
             let compatibleUrl = "";
@@ -631,6 +744,7 @@ async function searchReddit(query, numResults, timeoutMs) {
                 else {
                     notes.push("Arctic Shift returned no matching Reddit posts");
                 }
+                completed = true;
             }
             catch (error) {
                 notes.push(`Arctic Shift parse error: ${error instanceof Error ? error.message : String(error)}`);
@@ -659,6 +773,7 @@ async function searchReddit(query, numResults, timeoutMs) {
             else {
                 notes.push("PullPush returned no matching historical Reddit posts");
             }
+            completed = true;
         }
         catch (error) {
             notes.push(`PullPush parse error: ${error instanceof Error ? error.message : String(error)}`);
@@ -687,6 +802,7 @@ async function searchReddit(query, numResults, timeoutMs) {
             else {
                 notes.push("Reddit JSON returned no matching posts");
             }
+            completed = true;
         }
         catch (error) {
             notes.push(`Reddit JSON parse error: ${error instanceof Error ? error.message : String(error)}`);
@@ -697,7 +813,8 @@ async function searchReddit(query, numResults, timeoutMs) {
     }
     if (collected.length > 0)
         return success();
-    return { ok: false, note: notes.filter(Boolean).join("; ") || "Reddit search returned no results" };
+    const note = notes.filter(Boolean).join("; ") || "Reddit search returned no results";
+    return completed ? completedProviderSearch([], note) : failedProviderSearch(note);
 }
 async function searchGitHub(query, numResults, timeoutMs) {
     const q = stripSiteOperators(query) || query;
@@ -708,7 +825,7 @@ async function searchGitHub(query, numResults, timeoutMs) {
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `GitHub error ${result.status}` };
+        return failedProviderSearch(result.error || `GitHub error ${result.status}`);
     try {
         const data = result.text ? JSON.parse(result.text) : {};
         const raw = Array.isArray(data?.items) ? data.items : [];
@@ -722,17 +839,17 @@ async function searchGitHub(query, numResults, timeoutMs) {
             ].filter(Boolean).join(" · "),
             engine: "github",
         }))).slice(0, numResults);
-        return { ok: results.length > 0, results, note: results.length > 0 ? "" : "GitHub search returned no results" };
+        return completedProviderSearch(results, results.length > 0 ? "" : "GitHub search returned no results");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, note: `GitHub parse error: ${message}` };
+        return failedProviderSearch(`GitHub parse error: ${message}`);
     }
 }
 async function searchGitHubRepoDocs(query, numResults, timeoutMs) {
     const repoScope = parseGitHubRepoScope(query);
     if (!repoScope)
-        return { ok: false, note: "GitHub repository docs fallback skipped without owner/repo site scope" };
+        return failedProviderSearch("GitHub repository docs fallback skipped without owner/repo site scope");
     const repoResult = await fetchText(`https://api.github.com/repos/${encodeURIComponent(repoScope.owner)}/${encodeURIComponent(repoScope.repo)}`, timeoutMs, {
         headers: {
             accept: "application/vnd.github+json",
@@ -740,7 +857,7 @@ async function searchGitHubRepoDocs(query, numResults, timeoutMs) {
         },
     });
     if (!repoResult.ok)
-        return { ok: false, note: repoResult.error || `GitHub repository metadata error ${repoResult.status}` };
+        return failedProviderSearch(repoResult.error || `GitHub repository metadata error ${repoResult.status}`);
     let defaultBranch = "main";
     try {
         const repoData = repoResult.text ? JSON.parse(repoResult.text) : {};
@@ -756,7 +873,7 @@ async function searchGitHubRepoDocs(query, numResults, timeoutMs) {
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `GitHub repository docs error ${result.status}` };
+        return failedProviderSearch(result.error || `GitHub repository docs error ${result.status}`);
     try {
         const data = result.text ? JSON.parse(result.text) : {};
         const raw = Array.isArray(data?.tree) ? data.tree : [];
@@ -782,15 +899,18 @@ async function searchGitHubRepoDocs(query, numResults, timeoutMs) {
             snippet: `GitHub repository document · path:${item.path}`,
             engine: "github_repo_docs",
         }))).slice(0, numResults);
-        return { ok: results.length > 0, results, note: results.length > 0 ? "" : "GitHub repository docs search returned no matching documents" };
+        return completedProviderSearch(results, results.length > 0 ? "" : "GitHub repository docs search returned no matching documents");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, note: `GitHub repository docs parse error: ${message}` };
+        return failedProviderSearch(`GitHub repository docs parse error: ${message}`);
     }
 }
 async function searchMdn(query, numResults, timeoutMs) {
     const q = stripSiteOperators(query) || query;
+    const quoted = searchQueryTokens(query)
+        .filter(token => token.startsWith('"') && token.endsWith('"') && token.length > 2 && !token.includes("\\"))
+        .map(token => token.slice(1, -1).toLocaleLowerCase());
     const result = await fetchText(`https://developer.mozilla.org/api/v1/search?q=${encodeURIComponent(q)}&locale=en-US`, timeoutMs, {
         headers: {
             accept: "application/json,text/plain,*/*",
@@ -798,11 +918,13 @@ async function searchMdn(query, numResults, timeoutMs) {
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `MDN error ${result.status}` };
+        return failedProviderSearch(result.error || `MDN error ${result.status}`);
     try {
         const data = result.text ? JSON.parse(result.text) : {};
-        const raw = Array.isArray(data?.documents) ? data.documents : [];
-        const results = uniqueResults(raw.map((item) => {
+        if (!Array.isArray(data?.documents))
+            return failedProviderSearch("MDN returned an invalid documents payload");
+        const raw = data.documents;
+        const candidates = uniqueResults(raw.map((item) => {
             const mdnUrl = String(item?.mdn_url || item?.url || "").trim();
             return {
                 title: String(item?.title || item?.slug || mdnUrl).trim(),
@@ -810,12 +932,18 @@ async function searchMdn(query, numResults, timeoutMs) {
                 snippet: String(item?.summary || item?.excerpt || "").trim(),
                 engine: "mdn",
             };
-        }).filter((item) => item.url && item.url !== "https://developer.mozilla.org/")).slice(0, numResults);
-        return { ok: results.length > 0, results, note: results.length > 0 ? "" : "MDN search returned no results" };
+        }).filter((item) => item.url && item.url !== "https://developer.mozilla.org/"));
+        // Native index neighbors do not satisfy an explicit quote by proximity.
+        const results = quoted.length ? candidates.filter(item => quoted.every(phrase => item.title.toLocaleLowerCase().includes(phrase) || item.snippet.toLocaleLowerCase().includes(phrase))) : candidates;
+        if (quoted.length && candidates.length && !results.length)
+            return failedProviderSearch("MDN index has no title/summary evidence for the quoted phrase; continuing to full-query search");
+        return completedProviderSearch(results.slice(0, numResults), quoted.length && results.length
+            ? "MDN quoted phrase matched index title/summary only; original body remains unverified"
+            : results.length ? "" : "MDN search returned no results");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, note: `MDN parse error: ${message}` };
+        return failedProviderSearch(`MDN parse error: ${message}`);
     }
 }
 async function searchCrates(query, numResults, timeoutMs) {
@@ -827,10 +955,12 @@ async function searchCrates(query, numResults, timeoutMs) {
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `crates.io error ${result.status}` };
+        return failedProviderSearch(result.error || `crates.io error ${result.status}`);
     try {
         const data = result.text ? JSON.parse(result.text) : {};
-        const raw = Array.isArray(data?.crates) ? data.crates : [];
+        if (!Array.isArray(data?.crates))
+            return failedProviderSearch("crates.io returned an invalid crates payload");
+        const raw = data.crates;
         const results = uniqueResults(raw.map((item) => {
             const name = String(item?.name || item?.id || "").trim();
             const latest = String(item?.max_version || item?.newest_version || "").trim();
@@ -845,14 +975,14 @@ async function searchCrates(query, numResults, timeoutMs) {
                 engine: "crates",
             };
         }).filter((item) => item.url)).slice(0, numResults);
-        return { ok: results.length > 0, results, note: results.length > 0 ? "" : "crates.io search returned no results" };
+        return completedProviderSearch(results, results.length > 0 ? "" : "crates.io search returned no results");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, note: `crates.io parse error: ${message}` };
+        return failedProviderSearch(`crates.io parse error: ${message}`);
     }
 }
-async function searchNpmPackage(packageName, timeoutMs) {
+async function searchNpmPackage(packageName, timeoutMs, quoted = []) {
     const result = await fetchText(`https://registry.npmjs.org/${encodeURIComponent(packageName)}`, timeoutMs, {
         headers: {
             accept: "application/json,text/plain,*/*",
@@ -860,28 +990,37 @@ async function searchNpmPackage(packageName, timeoutMs) {
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `npm package error ${result.status}` };
+        return failedProviderSearch(result.error || `npm package error ${result.status}`);
     try {
         const data = result.text ? JSON.parse(result.text) : {};
         const record = data;
-        const name = String(record.name || packageName).trim();
+        // The requested URL is not evidence that a successful response describes
+        // that package. An empty or mismatched registry payload must not invent it.
+        if (typeof record.name !== "string" || record.name !== packageName) {
+            return failedProviderSearch("npm package metadata did not identify the requested package");
+        }
+        const name = record.name;
+        const description = typeof record.description === "string" ? record.description : "";
+        if (quoted.length && !quoted.every(phrase => name.toLocaleLowerCase().includes(phrase) || description.toLocaleLowerCase().includes(phrase))) {
+            return failedProviderSearch("npm package metadata has no evidence for the quoted phrase; continuing to full-query search");
+        }
         const latest = String(record["dist-tags"]?.latest || record.version || "").trim();
         const maintainer = Array.isArray(record.maintainers) ? String(record.maintainers[0]?.name || "").trim() : "";
         const results = uniqueResults([{
                 title: name,
                 url: `https://www.npmjs.com/package/${name}`,
                 snippet: [
-                    String(record.description || "").trim(),
+                    description.trim(),
                     latest ? `v${latest}` : "",
                     maintainer ? `by ${maintainer}` : "",
                 ].filter(Boolean).join(" · "),
                 engine: "npm",
             }]);
-        return { ok: results.length > 0, results, note: "" };
+        return completedProviderSearch(results, quoted.length ? "npm quoted phrase matched package metadata only; original body remains unverified" : "");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, note: `npm package parse error: ${message}` };
+        return failedProviderSearch(`npm package parse error: ${message}`);
     }
 }
 async function searchNpm(query, numResults, timeoutMs) {
@@ -893,10 +1032,12 @@ async function searchNpm(query, numResults, timeoutMs) {
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `npm error ${result.status}` };
+        return failedProviderSearch(result.error || `npm error ${result.status}`);
     try {
         const data = result.text ? JSON.parse(result.text) : {};
-        const raw = Array.isArray(data?.objects) ? data.objects : [];
+        if (!Array.isArray(data?.objects))
+            return failedProviderSearch("npm search returned an invalid objects payload");
+        const raw = data.objects;
         const results = uniqueResults(raw.map((item) => {
             const pkg = item?.package || {};
             const name = String(pkg?.name || "").trim();
@@ -911,11 +1052,11 @@ async function searchNpm(query, numResults, timeoutMs) {
                 engine: "npm",
             };
         }).filter((item) => item.url)).slice(0, numResults);
-        return { ok: results.length > 0, results, note: results.length > 0 ? "" : "npm search returned no results" };
+        return completedProviderSearch(results, results.length > 0 ? "" : "npm search returned no results");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, note: `npm parse error: ${message}` };
+        return failedProviderSearch(`npm parse error: ${message}`);
     }
 }
 function braveHtmlEnabled() {
@@ -935,10 +1076,12 @@ async function searchWikipedia(query, numResults, timeoutMs) {
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `Wikipedia error ${result.status}` };
+        return failedProviderSearch(result.error || `Wikipedia error ${result.status}`);
     try {
         const data = result.text ? JSON.parse(result.text) : {};
-        const raw = Array.isArray(data?.query?.search) ? data.query.search : [];
+        if (!Array.isArray(data?.query?.search))
+            return failedProviderSearch("Wikipedia returned an invalid search payload");
+        const raw = data.query.search;
         const results = uniqueResults(raw.map((item) => {
             const title = String(item?.title || "").trim();
             const pageId = item?.pageid;
@@ -950,11 +1093,24 @@ async function searchWikipedia(query, numResults, timeoutMs) {
                 engine: "wikipedia",
             };
         }).filter((item) => item.url)).slice(0, numResults);
-        return { ok: results.length > 0, results, note: results.length > 0 ? "" : "Wikipedia search returned no results" };
+        // Native API ordering can fill a Korean two-term query with articles whose
+        // excerpt only contains one incidental word (e.g. 기계식 계산기 for a keyboard
+        // query). Do not hide all leads if none has enough visible evidence.
+        const terms = wikiLang === "ko" ? koreanDiscoveryTerms(query) : [];
+        const topical = terms.length >= 2 ? results.filter(row => discoveryEvidenceScore(row, terms) >= 2) : results;
+        const phrase = terms.join("");
+        const folded = (value) => value.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+        const phraseScore = (row) => !phrase ? 0
+            : folded(row.title).includes(phrase) ? 2 : folded(row.snippet).includes(phrase) ? 1 : 0;
+        const selected = topical.length ? topical.sort((a, b) => phraseScore(b) - phraseScore(a)) : results;
+        const note = selected.length < results.length
+            ? `Excluded ${results.length - selected.length} Wikipedia result(s) without both query terms in title/snippet`
+            : selected.length ? "" : "Wikipedia search returned no results";
+        return completedProviderSearch(selected, note);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, note: `Wikipedia parse error: ${message}` };
+        return failedProviderSearch(`Wikipedia parse error: ${message}`);
     }
 }
 async function searchDuckDuckGo(query, numResults, timeoutMs) {
@@ -964,24 +1120,12 @@ async function searchDuckDuckGo(query, numResults, timeoutMs) {
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `DuckDuckGo error ${result.status}` };
+        return failedProviderSearch(result.error || `DuckDuckGo error ${result.status}`);
     if (/anomaly\.js|sending automated queries|captcha/i.test(result.text)) {
-        return { ok: false, note: "DuckDuckGo blocked the automated HTML fallback" };
+        return failedProviderSearch("DuckDuckGo blocked the automated HTML fallback");
     }
-    const blocks = result.text.split(/<div class="result[^"]*"/i).slice(1);
-    const results = uniqueResults(blocks.map((block) => {
-        const anchor = block.match(/<a[^>]*class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/i);
-        const snippet = block.match(/<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/i)
-            || block.match(/<div[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/div>/i);
-        const rawUrl = anchor?.[1] || "";
-        return {
-            title: stripTags(anchor?.[2] || ""),
-            url: resolveDuckDuckGoUrl(rawUrl),
-            snippet: stripTags(snippet?.[1] || ""),
-            engine: "duckduckgo",
-        };
-    }).filter((item) => item.url)).slice(0, numResults);
-    return { ok: results.length > 0, results, note: results.length > 0 ? "" : "DuckDuckGo returned no results" };
+    const results = parseDuckDuckGoSearch(result.text);
+    return completedProviderSearch(results, results.length > 0 ? "" : "DuckDuckGo returned no results");
 }
 async function searchBraveHtml(query, numResults, timeoutMs) {
     const result = await fetchText(`https://search.brave.com/search?q=${encodeURIComponent(query)}&source=web`, timeoutMs, {
@@ -991,21 +1135,16 @@ async function searchBraveHtml(query, numResults, timeoutMs) {
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `Brave HTML error ${result.status}` };
-    const results = [];
-    const regex = /<a href="(https?:\/\/[^"#]+)"[^>]*>[\s\S]*?<div class="title[^>]*"[^>]*>([\s\S]*?)<\/div>[\s\S]*?<\/a>[\s\S]*?<div class="generic-snippet[\s\S]*?<div class="content[^>]*"[^>]*>([\s\S]*?)<\/div>/gi;
-    for (const match of result.text.matchAll(regex)) {
-        results.push({
-            title: stripTags(match[2] || ""),
-            url: String(match[1] || "").trim(),
-            snippet: stripTags(match[3] || ""),
-            engine: "brave_html",
-        });
-        if (results.length >= numResults)
-            break;
+        return failedProviderSearch(result.error || `Brave HTML error ${result.status}`);
+    const unique = parseBraveSearch(result.text);
+    if (unique.length === 0 && result.text.trim()) {
+        const { document } = parseHTML(result.text);
+        const visible = `${document.title} ${document.body?.textContent || ""}`.slice(0, 10000);
+        if (/verify you are human|captcha|unusual traffic|automated quer(?:y|ies)|비정상적인 접근|자동입력 방지/i.test(visible)) {
+            return failedProviderSearch("Brave HTML stopped at a challenge");
+        }
     }
-    const unique = uniqueResults(results);
-    return { ok: unique.length > 0, results: unique, note: unique.length > 0 ? "" : "Brave HTML returned no results" };
+    return completedProviderSearch(unique, unique.length > 0 ? "" : "Brave HTML returned no results");
 }
 async function searchSearxng(baseUrl, query, numResults, timeoutMs) {
     const normalizedBase = baseUrl.replace(/\/+$/, "");
@@ -1016,44 +1155,205 @@ async function searchSearxng(baseUrl, query, numResults, timeoutMs) {
         },
     });
     if (!result.ok)
-        return { ok: false, note: result.error || `SearXNG error ${result.status}` };
+        return failedProviderSearch(result.error || `SearXNG error ${result.status}`);
     try {
-        const data = result.text ? JSON.parse(result.text) : {};
-        const raw = Array.isArray(data?.results) ? data.results : [];
+        const data = JSON.parse(result.text);
+        if (!data || typeof data !== "object" || !Array.isArray(data.results)) {
+            return failedProviderSearch("SearXNG invalid result envelope: expected a results array");
+        }
+        const raw = data.results;
         const results = uniqueResults(raw.map((item) => ({
             title: String(item?.title || item?.url || "").trim(),
             url: String(item?.url || "").trim(),
             snippet: String(item?.content || item?.description || item?.text || "").trim(),
             engine: "searxng",
-        }))).slice(0, numResults);
-        return { ok: results.length > 0, results, note: results.length > 0 ? "" : "SearXNG returned no results" };
+        }))).slice(0, Math.max(100, numResults));
+        return completedProviderSearch(results, results.length > 0 ? "" : "SearXNG returned no results");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, note: `SearXNG parse error: ${message}` };
+        return failedProviderSearch(`SearXNG parse error: ${message}`);
     }
 }
 export async function runSmartsearch(options, runtime = {}) {
+    const startedAt = Date.now();
     const query = options.query.trim();
     const numResults = Math.max(1, Math.min(20, Math.floor(Number(options.numResults || 8))));
     const searchType = options.searchType || "auto";
     const contextMaxCharacters = Math.max(1000, Math.floor(Number(options.contextMaxCharacters || 10000)));
     const timeoutMs = Math.max(1000, Math.floor(Number(options.timeoutMs || DEFAULT_TIMEOUT_MS)));
+    const cdpUrl = configText("fetch.browserCdpUrl");
+    const browserEnabled = Boolean(cdpUrl && /[가-힣a-z]/iu.test(stripSiteOperators(query)) && !localOnlyMode() && !privateProfileMode() && configEnabled("search.enableBrowserFallback", true));
+    const attemptTimeout = () => Math.max(1, Math.floor((timeoutMs - (Date.now() - startedAt)) / (browserEnabled ? 4 : 1)));
     const searxngBaseUrl = (options.searxngBaseUrl || configText("search.searxngBaseUrl") || "").trim();
     const fallbacks = [];
     const notes = [];
+    const attempts = [];
+    // A result outside an explicit site/path is not a useful provider success.
+    // Multiple positive site operators are left to the general engine; native
+    // first-site routing cannot preserve their Boolean semantics.
+    const tokens = searchQueryTokens(query);
+    const siteMatches = tokens.filter((token) => /^site:[^"']+$/i.test(token));
+    const scope = siteMatches.length === 1 ? extractSiteScope(siteMatches[0]) : null;
+    const unscopedDocsTerms = !siteMatches.length ? unscopedPythonDocsTerms(query) : undefined;
+    const pythonSearchUrl = browserEnabled ? pythonDocsSearchUrl(unscopedDocsTerms ? { host: "docs.python.org", path: "3" } : scope, unscopedDocsTerms || tokens.filter(token => token !== siteMatches[0]).join(" ")) : undefined;
+    const nativeYoutubeUrl = browserEnabled ? youtubeSearchUrl(scope, tokens.filter(token => token !== siteMatches[0]).join(" ")) : undefined;
+    const hnDates = scope?.host === "news.ycombinator.com" ? parseHnDateQuery(query) : undefined;
+    const nativeCandidateLimit = scope ? 20 : numResults;
+    const constrain = (outcome, limit = numResults) => {
+        if (hnDates?.bounded && outcome.status === "succeeded" && !outcome.hnDateBoundsVerified)
+            return failedProviderSearch("HN date constraints require verified native publication timestamps; undated search snippets were not accepted");
+        if (!outcome.ok)
+            return outcome;
+        const originals = outcome.results.filter((item) => !isSearchTrackingRelay(item));
+        if (originals.length !== outcome.results.length) {
+            notes.push(`Excluded ${outcome.results.length - originals.length} outbound tracking relay(s); discovery requires original pages`);
+            outcome = completedProviderSearch(originals, outcome.note);
+            if (!originals.length)
+                return failedProviderSearch("Search returned tracking relays without original results");
+        }
+        if (!scope)
+            return { ...outcome, results: outcome.results.slice(0, limit) };
+        const scoped = outcome.results.filter((item) => searchResultMatchesSite(item.url, scope.host, scope.path));
+        if (scoped.length !== outcome.results.length)
+            notes.push(`Filtered ${outcome.results.length - scoped.length} result(s) outside site:${scope.host}${scope.path ? `/${scope.path}` : ""}`);
+        const wikiArticleIntent = scope.host === "github.com" && /(?:^|\/)wiki(?:\/|$)/i.test(scope.path)
+            && !/\b(?:history|revisions?|edit)\b/i.test(stripSiteOperators(query));
+        const results = wikiArticleIntent
+            ? scoped.filter((item) => !/\/wiki\/(?:[^?#]+\/)?_(?:history|edit)(?:[/?#]|$)/i.test(new URL(item.url).pathname))
+            : scoped;
+        if (results.length !== scoped.length)
+            notes.push(`Excluded ${scoped.length - results.length} GitHub wiki history/edit page(s); original articles were requested`);
+        return results.length ? completedProviderSearch(results.slice(0, limit), outcome.note) : failedProviderSearch("No results satisfied the explicit site constraint");
+    };
+    const recordAttempt = (provider, outcome) => {
+        attempts.push({
+            provider,
+            status: outcome.status,
+            result_count: outcome.results.length,
+            ...(outcome.status === "failed" && outcome.note ? { error: outcome.note } : {}),
+        });
+    };
+    if (hnDates?.error)
+        return buildSearchResponse({ engine: "error", query, results: [], fallbacks_tried: [], notes: [hnDates.error], execution: { status: "failed", attempts: [{ provider: "query_constraints", status: "failed", result_count: 0, error: hnDates.error }] } });
+    const discoveryTerms = koreanDiscoveryTerms(query);
+    let discoveryResults = [];
+    const collectDiscovery = (outcome) => {
+        if (!outcome.ok)
+            return false;
+        discoveryResults = rankDiscoveryResults([...discoveryResults, ...outcome.results], discoveryTerms);
+        if (hasDiscoveryYield(discoveryResults, discoveryTerms, numResults))
+            return true;
+        notes.push("Low discovery yield in title/snippet evidence; continuing within the existing search budget. Unmatched originals are retained, not declared irrelevant.");
+        return false;
+    };
+    const finishDiscovery = () => {
+        const results = discoveryResults.slice(0, numResults);
+        const engines = new Set(results.map((row) => row.engine));
+        if (!hasDiscoveryYield(results, discoveryTerms, numResults))
+            notes.push("Limited topical evidence in discovery metadata; original-page relevance remains unverified");
+        return maybeRunCrawlHandoff({ engine: engines.size > 1 ? "mixed" : results[0]?.engine || "none", query, results, fallbacks_tried: fallbacks, notes, execution: smartsearchExecution(attempts) }, options, runtime);
+    };
+    const budgetExhausted = () => {
+        if (Date.now() - startedAt < timeoutMs)
+            return false;
+        notes.push("Search budget exhausted; no further discovery engine was started");
+        return true;
+    };
     try {
-        const siteOperator = extractSiteOperator(query);
+        // A full site:path can itself be the requested original. Check its authored
+        // body before relying on search indexes that only expose titles/summaries.
+        // Only quote-only queries are safe here: extra terms/operators need a real
+        // search engine rather than being silently discarded.
+        const remainder = tokens.filter(token => !/^site:[^"']+$/i.test(token));
+        const quoted = remainder.filter(token => /^"[^"\\]+"$/.test(token)).map(token => token.slice(1, -1));
+        if (scope?.path.includes("/") && !siteNativeFallbackBlockedReason("Scoped original") && !parseNpmPackageScope(query)
+            && quoted.length > 0 && quoted.length === remainder.length && !budgetExhausted()) {
+            const url = siteScopeToStartUrl(scope);
+            const validation = await validateOutboundUrl(url);
+            if (validation.ok && !budgetExhausted()) {
+                const original = await fetchText(url, attemptTimeout(), { redirect: "error", headers: { "user-agent": DEFAULT_USER_AGENT } });
+                if (original.ok && !budgetExhausted()) {
+                    const document = parseHTML(original.text).document;
+                    const article = document.querySelector("main article") || document.querySelector("main") || document.querySelector("article");
+                    if (article) {
+                        for (const node of article.querySelectorAll("script, style, nav, aside, header, footer, [hidden], [inert], [aria-hidden='true'], [style*='display:none'], [style*='display: none']"))
+                            node.remove();
+                        const body = (article.textContent || "").replace(/\s+/g, " ").trim();
+                        const heading = (document.title || article.querySelector("h1")?.textContent || "").replace(/\s+/g, " ").trim();
+                        const lower = body.toLocaleLowerCase();
+                        if (body.length >= 40 && heading.length >= 3 && quoted.every(phrase => lower.includes(phrase.toLocaleLowerCase()))
+                            && !detectInteractiveLikeText(`${heading} ${body.slice(0, 300)}`)) {
+                            const position = lower.indexOf(quoted[0].toLocaleLowerCase());
+                            const snippet = body.slice(Math.max(0, position - 90), position + quoted[0].length + 110);
+                            const outcome = constrain(completedProviderSearch([{ title: heading, url, snippet, engine: "scoped_original" }], ""));
+                            if (outcome.ok) {
+                                fallbacks.push("scoped_original");
+                                recordAttempt("scoped_original", outcome);
+                                return maybeRunCrawlHandoff({ engine: "scoped_original", query, results: outcome.results, fallbacks_tried: fallbacks, notes: ["Quoted phrase verified in the exact scoped original body"], execution: smartsearchExecution(attempts) }, options, runtime);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        const nodeIntent = !siteMatches.length ? nodeDocsIntent(query) : undefined;
+        if (nodeIntent && !budgetExhausted()) {
+            fallbacks.push("node_docs");
+            const original = await fetchText(nodeIntent.url, attemptTimeout(), { redirect: "error", headers: { "user-agent": DEFAULT_USER_AGENT } });
+            const result = original.ok && !budgetExhausted() ? nodeDocsOriginal(original.text, nodeIntent.url, nodeIntent.symbol) : undefined;
+            const outcome = result ? completedProviderSearch([result], "") : failedProviderSearch(original.ok
+                ? "Node.js 24 official filesystem original did not verify the requested symbol"
+                : `Node.js 24 official original unavailable: ${original.error || original.status}`);
+            recordAttempt("node_docs", outcome);
+            if (result) {
+                notes.push("Official Node.js 24 documentation section verified; complete page extraction remains a separate read");
+                collectDiscovery(outcome);
+                return finishDiscovery();
+            }
+            notes.push(outcome.note);
+        }
+        const postgresIntent = !siteMatches.length ? postgresqlDocsIntent(query) : undefined;
+        if (postgresIntent && !budgetExhausted()) {
+            fallbacks.push("postgresql_docs");
+            const searchUrl = new URL("https://www.postgresql.org/search/");
+            searchUrl.searchParams.set("q", `${postgresIntent.version} ${postgresIntent.symbol}`);
+            const index = await fetchText(searchUrl.href, attemptTimeout(), { redirect: "error", headers: { "user-agent": DEFAULT_USER_AGENT } });
+            let verified;
+            if (index.ok && !budgetExhausted()) {
+                for (const candidate of postgresqlDocsCandidates(index.text, postgresIntent.version)) {
+                    if (budgetExhausted())
+                        break;
+                    const original = await fetchText(candidate.url, attemptTimeout(), { redirect: "error", headers: { "user-agent": DEFAULT_USER_AGENT } });
+                    if (original.ok && postgresqlDocsBodyHasSymbol(original.text, postgresIntent.symbol) && !budgetExhausted()) {
+                        verified = candidate;
+                        break;
+                    }
+                }
+            }
+            const outcome = verified ? completedProviderSearch([verified], "") : failedProviderSearch(index.ok
+                ? "PostgreSQL search did not verify the requested symbol in a version-matched original"
+                : `PostgreSQL official search unavailable: ${index.error || index.status}`);
+            recordAttempt("postgresql_docs", outcome);
+            if (verified) {
+                notes.push("Official versioned documentation original contains the requested symbol; complete page extraction remains a separate read");
+                collectDiscovery(outcome);
+                return finishDiscovery();
+            }
+            notes.push(outcome.note);
+        }
+        const siteOperator = siteMatches.length !== 1 || tokens.some(token => token === "(" || token === ")") ? "" : extractSiteOperator(siteMatches[0]);
         if (siteOperator === "velog.io") {
             const blockedReason = siteNativeFallbackBlockedReason("Velog");
             if (blockedReason) {
                 notes.push(blockedReason);
             }
             else {
-                const velog = await searchVelog(query, numResults, timeoutMs);
+                const velog = constrain(await searchVelog(query, nativeCandidateLimit, attemptTimeout()));
                 fallbacks.push("velog");
+                recordAttempt("velog", velog);
                 if (velog.ok)
-                    return maybeRunCrawlHandoff({ engine: "velog", query, results: velog.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+                    return maybeRunCrawlHandoff({ engine: "velog", query, results: velog.results, fallbacks_tried: fallbacks, notes, execution: smartsearchExecution(attempts) }, options, runtime);
                 if (velog.note)
                     notes.push(velog.note);
             }
@@ -1064,10 +1364,11 @@ export async function runSmartsearch(options, runtime = {}) {
                 notes.push(blockedReason);
             }
             else {
-                const stackexchange = await searchStackExchange(query, numResults, timeoutMs);
+                const stackexchange = constrain(await searchStackExchange(query, nativeCandidateLimit, attemptTimeout()));
                 fallbacks.push("stackexchange");
+                recordAttempt("stackexchange", stackexchange);
                 if (stackexchange.ok)
-                    return maybeRunCrawlHandoff({ engine: "stackexchange", query, results: stackexchange.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+                    return maybeRunCrawlHandoff({ engine: "stackexchange", query, results: stackexchange.results, fallbacks_tried: fallbacks, notes, execution: smartsearchExecution(attempts) }, options, runtime);
                 if (stackexchange.note)
                     notes.push(stackexchange.note);
             }
@@ -1078,10 +1379,11 @@ export async function runSmartsearch(options, runtime = {}) {
                 notes.push(blockedReason);
             }
             else {
-                const hackernews = await searchHackerNews(query, numResults, timeoutMs);
+                const hackernews = constrain(await searchHackerNews(query, nativeCandidateLimit, attemptTimeout(), hnDates));
                 fallbacks.push("hackernews");
-                if (hackernews.ok)
-                    return maybeRunCrawlHandoff({ engine: "hackernews", query, results: hackernews.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+                recordAttempt("hackernews", hackernews);
+                if (hackernews.ok || (hnDates?.bounded && hackernews.status === "succeeded"))
+                    return maybeRunCrawlHandoff({ engine: "hackernews", query, results: hackernews.results, fallbacks_tried: fallbacks, notes: hackernews.note ? [...notes, hackernews.note] : notes, execution: smartsearchExecution(attempts) }, options, runtime);
                 if (hackernews.note)
                     notes.push(hackernews.note);
             }
@@ -1092,24 +1394,32 @@ export async function runSmartsearch(options, runtime = {}) {
                 notes.push(blockedReason);
             }
             else {
-                const reddit = await searchReddit(query, numResults, timeoutMs);
+                // Reddit already preserves subreddit scope while filling this count;
+                // oversampling here would trigger unnecessary secondary-provider reads.
+                const reddit = constrain(await searchReddit(query, numResults, attemptTimeout()));
                 fallbacks.push("reddit");
+                recordAttempt("reddit", reddit);
                 if (reddit.ok)
-                    return maybeRunCrawlHandoff({ engine: "reddit", query, results: reddit.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+                    return maybeRunCrawlHandoff({ engine: "reddit", query, results: reddit.results, fallbacks_tried: fallbacks, notes, execution: smartsearchExecution(attempts) }, options, runtime);
                 if (reddit.note)
                     notes.push(reddit.note);
             }
         }
         if (siteOperator === "github.com") {
             const blockedReason = siteNativeFallbackBlockedReason("GitHub");
+            const repoScope = parseGitHubRepoScope(query);
             if (blockedReason) {
                 notes.push(blockedReason);
             }
-            else if (parseGitHubRepoScope(query)) {
-                const githubRepoDocs = await searchGitHubRepoDocs(query, numResults, timeoutMs);
+            else if (repoScope?.scopePath && !repoScope.scopePath.startsWith("blob/")) {
+                notes.push("GitHub repository tree lookup cannot search this URL section; preserving the full query for general search");
+            }
+            else if (repoScope) {
+                const githubRepoDocs = constrain(await searchGitHubRepoDocs(query, nativeCandidateLimit, attemptTimeout()));
                 fallbacks.push("github_repo_docs");
+                recordAttempt("github_repo_docs", githubRepoDocs);
                 if (githubRepoDocs.ok)
-                    return maybeRunCrawlHandoff({ engine: "github_repo_docs", query, results: githubRepoDocs.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+                    return maybeRunCrawlHandoff({ engine: "github_repo_docs", query, results: githubRepoDocs.results, fallbacks_tried: fallbacks, notes, execution: smartsearchExecution(attempts) }, options, runtime);
                 if (githubRepoDocs.note)
                     notes.push(githubRepoDocs.note);
             }
@@ -1117,27 +1427,40 @@ export async function runSmartsearch(options, runtime = {}) {
                 notes.push("GitHub native repo fallback skipped for non-repository intent");
             }
             else {
-                const github = await searchGitHub(query, numResults, timeoutMs);
+                const github = constrain(await searchGitHub(query, nativeCandidateLimit, attemptTimeout()));
                 fallbacks.push("github");
+                recordAttempt("github", github);
                 if (github.ok)
-                    return maybeRunCrawlHandoff({ engine: "github", query, results: github.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+                    return maybeRunCrawlHandoff({ engine: "github", query, results: github.results, fallbacks_tried: fallbacks, notes, execution: smartsearchExecution(attempts) }, options, runtime);
                 if (github.note)
                     notes.push(github.note);
             }
         }
         if (siteOperator === "npmjs.com") {
             const blockedReason = siteNativeFallbackBlockedReason("npm");
+            const exactPackage = parseNpmPackageScope(query);
+            const remainder = searchQueryTokens(query).filter(token => !/^site:[^"']+$/i.test(token));
+            const quoted = remainder.filter(token => token.startsWith('"') && token.endsWith('"') && token.length > 2 && !token.includes("\\"))
+                .map(token => token.slice(1, -1).toLocaleLowerCase());
+            const nativeExact = Boolean(exactPackage && (remainder.length === 0 || (quoted.length === remainder.length && quoted.length > 0)));
             if (blockedReason) {
                 notes.push(blockedReason);
             }
+            else if (exactPackage && !nativeExact) {
+                // Metadata cannot evaluate free words, exclusions, dates or Boolean
+                // expressions. Only standalone quotes can be checked in its own fields.
+                notes.push("npm package metadata cannot evaluate the remaining query constraints; preserving the full query for general search");
+            }
             else {
-                const exactPackage = parseNpmPackageScope(query);
-                const npm = exactPackage
-                    ? await searchNpmPackage(exactPackage, timeoutMs)
-                    : await searchNpm(query, numResults, timeoutMs);
+                const npm = constrain(exactPackage
+                    ? await searchNpmPackage(exactPackage, attemptTimeout(), quoted)
+                    : await searchNpm(query, nativeCandidateLimit, attemptTimeout()));
                 fallbacks.push("npm");
+                recordAttempt("npm", npm);
+                if (npm.ok && npm.note)
+                    notes.push(npm.note);
                 if (npm.ok)
-                    return maybeRunCrawlHandoff({ engine: "npm", query, results: npm.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+                    return maybeRunCrawlHandoff({ engine: "npm", query, results: npm.results, fallbacks_tried: fallbacks, notes, execution: smartsearchExecution(attempts) }, options, runtime);
                 if (npm.note)
                     notes.push(npm.note);
             }
@@ -1148,10 +1471,13 @@ export async function runSmartsearch(options, runtime = {}) {
                 notes.push(blockedReason);
             }
             else {
-                const mdn = await searchMdn(query, numResults, timeoutMs);
+                const mdn = constrain(await searchMdn(query, nativeCandidateLimit, attemptTimeout()));
                 fallbacks.push("mdn");
+                recordAttempt("mdn", mdn);
+                if (mdn.ok && mdn.note)
+                    notes.push(mdn.note);
                 if (mdn.ok)
-                    return maybeRunCrawlHandoff({ engine: "mdn", query, results: mdn.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+                    return maybeRunCrawlHandoff({ engine: "mdn", query, results: mdn.results, fallbacks_tried: fallbacks, notes, execution: smartsearchExecution(attempts) }, options, runtime);
                 if (mdn.note)
                     notes.push(mdn.note);
             }
@@ -1162,10 +1488,11 @@ export async function runSmartsearch(options, runtime = {}) {
                 notes.push(blockedReason);
             }
             else {
-                const crates = await searchCrates(query, numResults, timeoutMs);
+                const crates = constrain(await searchCrates(query, nativeCandidateLimit, attemptTimeout()));
                 fallbacks.push("crates");
+                recordAttempt("crates", crates);
                 if (crates.ok)
-                    return maybeRunCrawlHandoff({ engine: "crates", query, results: crates.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+                    return maybeRunCrawlHandoff({ engine: "crates", query, results: crates.results, fallbacks_tried: fallbacks, notes, execution: smartsearchExecution(attempts) }, options, runtime);
                 if (crates.note)
                     notes.push(crates.note);
             }
@@ -1176,24 +1503,28 @@ export async function runSmartsearch(options, runtime = {}) {
                 notes.push(blockedReason);
             }
             else {
-                const wikipedia = await searchWikipedia(query, numResults, timeoutMs);
+                const wikipedia = constrain(await searchWikipedia(query, nativeCandidateLimit, attemptTimeout()));
                 fallbacks.push("wikipedia");
+                recordAttempt("wikipedia", wikipedia);
                 if (wikipedia.ok)
-                    return maybeRunCrawlHandoff({ engine: "wikipedia", query, results: wikipedia.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+                    return maybeRunCrawlHandoff({ engine: "wikipedia", query, results: wikipedia.results, fallbacks_tried: fallbacks, notes, execution: smartsearchExecution(attempts) }, options, runtime);
                 if (wikipedia.note)
                     notes.push(wikipedia.note);
             }
         }
+        if (budgetExhausted())
+            return finishDiscovery();
         if (searxngEnabled() && searxngBaseUrl) {
             const privacySensitive = localOnlyMode() || privateProfileMode();
             if (privacySensitive && !await privacySafeSearxngBase(searxngBaseUrl)) {
                 notes.push("SearXNG disabled by privacy mode because the configured base URL is not local or private");
             }
             else {
-                const searxng = await searchSearxng(searxngBaseUrl, query, numResults, timeoutMs);
+                const searxng = constrain(await searchSearxng(searxngBaseUrl, query, numResults, attemptTimeout()), 100);
                 fallbacks.push("searxng");
-                if (searxng.ok)
-                    return maybeRunCrawlHandoff({ engine: "searxng", query, results: searxng.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+                recordAttempt("searxng", searxng);
+                if (collectDiscovery(searxng))
+                    return finishDiscovery();
                 if (searxng.note)
                     notes.push(searxng.note);
             }
@@ -1201,33 +1532,190 @@ export async function runSmartsearch(options, runtime = {}) {
         else if (!searxngEnabled()) {
             notes.push("SearXNG disabled by configuration");
         }
+        if (budgetExhausted())
+            return finishDiscovery();
         if (duckduckgoEnabled()) {
-            const ddg = await searchDuckDuckGo(query, numResults, timeoutMs);
+            const ddg = constrain(await searchDuckDuckGo(query, numResults, attemptTimeout()), 100);
             fallbacks.push("duckduckgo");
-            if (ddg.ok)
-                return maybeRunCrawlHandoff({ engine: "duckduckgo", query, results: ddg.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+            recordAttempt("duckduckgo", ddg);
+            if (collectDiscovery(ddg))
+                return finishDiscovery();
             if (ddg.note)
                 notes.push(ddg.note);
         }
         else {
             notes.push("DuckDuckGo disabled by configuration");
         }
+        if (budgetExhausted())
+            return finishDiscovery();
         if (braveHtmlEnabled()) {
-            const braveHtml = await searchBraveHtml(query, numResults, timeoutMs);
+            const braveHtml = constrain(await searchBraveHtml(query, numResults, attemptTimeout()), 100);
             fallbacks.push("brave_html");
-            if (braveHtml.ok)
-                return maybeRunCrawlHandoff({ engine: "brave_html", query, results: braveHtml.results, fallbacks_tried: fallbacks, notes }, options, runtime);
+            recordAttempt("brave_html", braveHtml);
+            if (collectDiscovery(braveHtml))
+                return finishDiscovery();
             if (braveHtml.note)
                 notes.push(braveHtml.note);
         }
         else {
             notes.push("Brave HTML disabled by configuration");
         }
-        return maybeRunCrawlHandoff({ engine: "none", query, results: [], fallbacks_tried: fallbacks, notes }, options, runtime);
+        const remaining = timeoutMs - (Date.now() - startedAt);
+        let canContinueNative = false;
+        if (browserEnabled) {
+            fallbacks.push("naver_browser");
+            let outcome;
+            if (remaining <= 0)
+                outcome = failedProviderSearch("Search budget exhausted before operator-browser continuation");
+            else {
+                try {
+                    // Native search sometimes treats a site path as text. A second,
+                    // host-only discovery query may recover the same originals; the
+                    // original path remains a hard result constraint below.
+                    const searchQueries = scope?.path && siteMatches.length === 1 && /[가-힣]/u.test(query)
+                        && ["clien.net", "dcinside.com", "ppomppu.co.kr"].includes(scope.host)
+                        ? [query, query.replace(siteMatches[0], `site:${scope.host}`)] : [query];
+                    outcome = failedProviderSearch("Browser search exposed no verified result headlines satisfying supported query constraints");
+                    for (const [index, searchQuery] of searchQueries.entries()) {
+                        const budget = timeoutMs - (Date.now() - startedAt);
+                        if (budget <= 0)
+                            break;
+                        const url = `https://search.naver.com/search.naver?query=${encodeURIComponent(searchQuery)}`;
+                        const page = await (runtime.runBrowserSession || runBrowserSession)({ url, cdpUrl, timeoutMs: Math.max(1, Math.floor(budget / ((pythonSearchUrl || nativeYoutubeUrl ? 1 : 0) + searchQueries.length - index))), allowPrivateHosts: false });
+                        if (!page.ok) {
+                            outcome = failedProviderSearch(`Approved browser: ${page.error.code}: ${page.error.message}`);
+                            break;
+                        }
+                        const final = new URL(page.final_url);
+                        const sameQuery = final.origin === "https://search.naver.com" && !final.username && !final.password
+                            && final.pathname === "/search.naver" && final.searchParams.getAll("query").length === 1 && final.searchParams.get("query") === searchQuery;
+                        if (!sameQuery || /captcha|verify you are human|unusual traffic|자동입력 방지|비정상적인 접근/i.test(page.text.slice(0, 1000))) {
+                            outcome = failedProviderSearch("Browser search stopped at a challenge or changed query; user interaction may be required");
+                            break;
+                        }
+                        canContinueNative = true;
+                        const safeResults = [];
+                        for (const item of rankDiscoveryResults(parseNaverBrowserSearch(page), discoveryTerms)) {
+                            if (Date.now() - startedAt >= timeoutMs)
+                                break;
+                            if (!browserSearchMatchesQuery(item, query))
+                                continue;
+                            if (isSearchTrackingRelay(item))
+                                continue;
+                            if (scope && !searchResultMatchesSite(item.url, scope.host, scope.path))
+                                continue;
+                            let timer;
+                            const validation = await Promise.race([
+                                validateOutboundUrl(item.url, { allowPrivateHosts: false }),
+                                new Promise((resolve) => { timer = setTimeout(() => resolve({ ok: false }), Math.max(1, timeoutMs - (Date.now() - startedAt))); }),
+                            ]).finally(() => { if (timer)
+                                clearTimeout(timer); });
+                            if (Date.now() - startedAt >= timeoutMs)
+                                break;
+                            if (validation.ok)
+                                safeResults.push(item);
+                            if (safeResults.length >= numResults)
+                                break;
+                        }
+                        outcome = safeResults.length ? constrain(completedProviderSearch(safeResults, "")) : failedProviderSearch("Browser search exposed no verified result headlines satisfying supported query constraints");
+                        if (outcome.ok) {
+                            if (index > 0)
+                                notes.push("Host-only discovery preserved the requested site path on every returned original");
+                            notes.push("Recovered through the approved local browser. Search snippets are discovery evidence, not verification of article bodies or all comments.");
+                            break;
+                        }
+                    }
+                }
+                catch (error) {
+                    outcome = failedProviderSearch(`Approved browser search failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            recordAttempt("naver_browser", outcome);
+            if (outcome.ok) {
+                collectDiscovery(outcome);
+                if (!unscopedDocsTerms)
+                    return finishDiscovery();
+            }
+            if (outcome.note)
+                notes.push(outcome.note);
+        }
+        if (nativeYoutubeUrl && canContinueNative && !budgetExhausted()) {
+            fallbacks.push("youtube_browser");
+            let outcome;
+            try {
+                const page = await (runtime.runBrowserSession || runBrowserSession)({
+                    url: nativeYoutubeUrl, cdpUrl, timeoutMs: Math.max(1, timeoutMs - (Date.now() - startedAt)), allowPrivateHosts: false,
+                    waitForSelector: "ytd-video-renderer a#video-title",
+                });
+                if (Date.now() - startedAt >= timeoutMs)
+                    outcome = failedProviderSearch("YouTube native search exceeded the shared search budget");
+                else if (!page.ok)
+                    outcome = failedProviderSearch(`YouTube native browser: ${page.error.code}: ${page.error.message}`);
+                else {
+                    const rows = parseYoutubeSearch(page, nativeYoutubeUrl, query);
+                    outcome = Date.now() - startedAt >= timeoutMs ? failedProviderSearch("YouTube native search exceeded the shared search budget")
+                        : rows.length ? constrain(completedProviderSearch(rows, "")) : failedProviderSearch("YouTube native search exposed no exact watch-page headlines satisfying the quoted query");
+                    if (outcome.ok)
+                        notes.push("Recovered watch-page discovery through the approved local browser. Video title evidence does not verify the full video or transcript.");
+                }
+            }
+            catch (error) {
+                outcome = failedProviderSearch(`YouTube native search failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            recordAttempt("youtube_browser", outcome);
+            if (outcome.ok) {
+                collectDiscovery(outcome);
+                return finishDiscovery();
+            }
+            if (outcome.note)
+                notes.push(outcome.note);
+        }
+        if (pythonSearchUrl && canContinueNative && !budgetExhausted()) {
+            fallbacks.push("python_docs_browser");
+            let outcome;
+            try {
+                const page = await (runtime.runBrowserSession || runBrowserSession)({
+                    url: pythonSearchUrl, cdpUrl, timeoutMs: Math.max(1, timeoutMs - (Date.now() - startedAt)), allowPrivateHosts: false,
+                    waitForSelector: "#search-results .search-summary:not(:empty)",
+                });
+                if (Date.now() - startedAt >= timeoutMs)
+                    outcome = failedProviderSearch("Python native search exceeded the shared search budget");
+                else if (!page.ok)
+                    outcome = failedProviderSearch(`Python native browser: ${page.error.code}: ${page.error.message}`);
+                else {
+                    const rows = parsePythonDocsSearch(page, pythonSearchUrl, unscopedDocsTerms || query);
+                    outcome = Date.now() - startedAt >= timeoutMs ? failedProviderSearch("Python native search exceeded the shared search budget")
+                        : rows.length ? constrain(completedProviderSearch(rows, "")) : failedProviderSearch("Python native search exposed no completed results satisfying the original query");
+                    if (outcome.ok)
+                        notes.push("Recovered through official Python documentation search in the approved browser. Native index/headline evidence is discovery, not complete original-body verification.");
+                }
+            }
+            catch (error) {
+                outcome = failedProviderSearch(`Python native search failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            recordAttempt("python_docs_browser", outcome);
+            if (outcome.ok) {
+                // Explicit documentation intent: a verified official index supersedes
+                // adjacent general-web candidates; retain them if the native lane fails.
+                if (unscopedDocsTerms)
+                    discoveryResults = [];
+                collectDiscovery(outcome);
+            }
+            if (outcome.note)
+                notes.push(outcome.note);
+        }
+        return finishDiscovery();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return maybeRunCrawlHandoff({ engine: "error", query, results: [], fallbacks_tried: fallbacks, notes: [...notes, message] }, options, runtime);
+        return maybeRunCrawlHandoff({
+            engine: "error",
+            query,
+            results: [],
+            fallbacks_tried: fallbacks,
+            notes: [...notes, message],
+            execution: { status: "failed", attempts: [...attempts, { provider: "smartsearch", status: "failed", result_count: 0, error: message }] },
+        }, options, runtime);
     }
 }
 export function renderSmartsearch(response) {
@@ -1267,9 +1755,6 @@ export function renderSmartsearch(response) {
             lines.push(item.snippet);
         parts.push(lines.join("\n"));
     });
-    if (assessment.recommended_handoff && assessment.recommended_handoff.tool !== "smartcrawl") {
-        parts.push(`Recommended handoff:\n- tool: ${assessment.recommended_handoff.tool}\n- reason: ${assessment.recommended_handoff.reason}\n- url: ${assessment.recommended_handoff.url}`);
-    }
     if (response.notes.length > 0)
         parts.push(`Notes:\n${response.notes.map((item) => `- ${item}`).join("\n")}`);
     return parts.join("\n\n").trim();