@poolzin/pool-bot 2026.2.25 → 2026.2.26

package/dist/memory/qmd-manager.js

@@ -6,6 +6,7 @@ import readline from "node:readline";
 import { resolveAgentWorkspaceDir } from "../agents/agent-scope.js";
 import { resolveStateDir } from "../config/paths.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
+import { isFileMissingError, statRegularFile } from "./fs-utils.js";
 import { deriveQmdScopeChannel, deriveQmdScopeChatType, isQmdScopeAllowed } from "./qmd-scope.js";
 import { listSessionFilesForAgent, buildSessionEntry, } from "./session-files.js";
 import { requireNodeSqlite } from "./sqlite.js";
@@ -15,6 +16,23 @@ const SNIPPET_HEADER_RE = /@@\s*-([0-9]+),([0-9]+)/;
 const SEARCH_PENDING_UPDATE_WAIT_MS = 500;
 const MAX_QMD_OUTPUT_CHARS = 200_000;
 const NUL_MARKER_RE = /(?:\^@|\\0|\\x00|\\u0000|null\s*byte|nul\s*byte)/i;
+const QMD_EMBED_BACKOFF_BASE_MS = 60_000;
+const QMD_EMBED_BACKOFF_MAX_MS = 60 * 60 * 1000;
+let qmdEmbedQueueTail = Promise.resolve();
+async function runWithQmdEmbedLock(task) {
+    const previous = qmdEmbedQueueTail;
+    let release;
+    qmdEmbedQueueTail = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous.catch(() => undefined);
+    try {
+        return await task();
+    }
+    finally {
+        release?.();
+    }
+}
 export class QmdMemoryManager {
     static async create(params) {
         const resolved = params.resolved.qmd;
@@ -50,6 +68,8 @@ export class QmdMemoryManager {
     db = null;
     lastUpdateAt = null;
     lastEmbedAt = null;
+    embedBackoffUntil = null;
+    embedFailureCount = 0;
     attemptedNullByteCollectionRepair = false;
     constructor(params) {
         this.cfg = params.cfg;
@@ -179,6 +199,7 @@ export class QmdMemoryManager {
         catch {
             // ignore; older qmd versions might not support list --json.
         }
+        await this.migrateLegacyUnscopedCollections(existing);
         for (const collection of this.qmd.collections) {
             const listed = existing.get(collection.name);
             if (listed && !this.shouldRebindCollection(collection, listed)) {
@@ -208,6 +229,52 @@ export class QmdMemoryManager {
             }
         }
     }
+    async migrateLegacyUnscopedCollections(existing) {
+        for (const collection of this.qmd.collections) {
+            if (existing.has(collection.name)) {
+                continue;
+            }
+            const legacyName = this.deriveLegacyCollectionName(collection.name);
+            if (!legacyName) {
+                continue;
+            }
+            const listedLegacy = existing.get(legacyName);
+            if (!listedLegacy) {
+                continue;
+            }
+            if (!this.canMigrateLegacyCollection(collection, listedLegacy)) {
+                log.debug(`qmd legacy collection migration skipped for ${legacyName} (path/pattern mismatch)`);
+                continue;
+            }
+            try {
+                await this.removeCollection(legacyName);
+                existing.delete(legacyName);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (!this.isCollectionMissingError(message)) {
+                    log.warn(`qmd collection remove failed for ${legacyName}: ${message}`);
+                }
+            }
+        }
+    }
+    deriveLegacyCollectionName(scopedName) {
+        const agentSuffix = `-${this.sanitizeCollectionNameSegment(this.agentId)}`;
+        if (!scopedName.endsWith(agentSuffix)) {
+            return null;
+        }
+        const legacyName = scopedName.slice(0, -agentSuffix.length).trim();
+        return legacyName || null;
+    }
+    canMigrateLegacyCollection(collection, listedLegacy) {
+        if (listedLegacy.path && !this.pathsMatch(listedLegacy.path, collection.path)) {
+            return false;
+        }
+        if (typeof listedLegacy.pattern === "string" && listedLegacy.pattern !== collection.pattern) {
+            return false;
+        }
+        return true;
+    }
     async ensureCollectionPath(collection) {
         if (!this.isDirectoryGlobPattern(collection.pattern)) {
             return;
@@ -238,8 +305,8 @@ export class QmdMemoryManager {
     shouldRebindCollection(collection, listed) {
         if (!listed.path) {
             // Older qmd versions may only return names from `collection list --json`.
-            // Force sessions collections to rebind so per-agent session export paths stay isolated.
-            return collection.kind === "sessions";
+            // Rebind managed collections so stale path bindings cannot survive upgrades.
+            return true;
         }
         if (!this.pathsMatch(listed.path, collection.path)) {
             return true;
@@ -312,11 +379,40 @@ export class QmdMemoryManager {
             log.warn("qmd query skipped: no managed collections configured");
             return [];
         }
-        const qmdSearchCommand = this.qmd.searchMode ?? "query";
+        const qmdSearchCommand = this.qmd.searchMode;
+        const mcporterEnabled = this.qmd.mcporter.enabled;
         let parsed;
         try {
-            if (qmdSearchCommand === "query" && collectionNames.length > 1) {
-                parsed = await this.runQueryAcrossCollections(trimmed, limit, collectionNames);
+            if (mcporterEnabled) {
+                const tool = qmdSearchCommand === "search"
+                    ? "search"
+                    : qmdSearchCommand === "vsearch"
+                        ? "vector_search"
+                        : "deep_search";
+                const minScore = opts?.minScore ?? 0;
+                if (collectionNames.length > 1) {
+                    parsed = await this.runMcporterAcrossCollections({
+                        tool,
+                        query: trimmed,
+                        limit,
+                        minScore,
+                        collectionNames,
+                    });
+                }
+                else {
+                    parsed = await this.runQmdSearchViaMcporter({
+                        mcporter: this.qmd.mcporter,
+                        tool,
+                        query: trimmed,
+                        limit,
+                        minScore,
+                        collection: collectionNames[0],
+                        timeoutMs: this.qmd.limits.timeoutMs,
+                    });
+                }
+            }
+            else if (collectionNames.length > 1) {
+                parsed = await this.runQueryAcrossCollections(trimmed, limit, collectionNames, qmdSearchCommand);
             }
             else {
                 const args = this.buildSearchArgs(qmdSearchCommand, trimmed, limit);
@@ -328,11 +424,13 @@ export class QmdMemoryManager {
             }
         }
         catch (err) {
-            if (qmdSearchCommand !== "query" && this.isUnsupportedQmdOptionError(err)) {
+            if (!mcporterEnabled &&
+                qmdSearchCommand !== "query" &&
+                this.isUnsupportedQmdOptionError(err)) {
                 log.warn(`qmd ${qmdSearchCommand} does not support configured flags; retrying search with qmd query`);
                 try {
                     if (collectionNames.length > 1) {
-                        parsed = await this.runQueryAcrossCollections(trimmed, limit, collectionNames);
+                        parsed = await this.runQueryAcrossCollections(trimmed, limit, collectionNames, "query");
                     }
                     else {
                         const fallbackArgs = this.buildSearchArgs("query", trimmed, limit);
@@ -349,13 +447,17 @@ export class QmdMemoryManager {
                 }
             }
             else {
-                log.warn(`qmd ${qmdSearchCommand} failed: ${String(err)}`);
+                const label = mcporterEnabled ? "mcporter/qmd" : `qmd ${qmdSearchCommand}`;
+                log.warn(`${label} failed: ${String(err)}`);
                 throw err instanceof Error ? err : new Error(String(err));
             }
         }
         const results = [];
         for (const entry of parsed) {
-            const doc = await this.resolveDocLocation(entry.docid);
+            const doc = await this.resolveDocLocation(entry.docid, {
+                preferredCollection: entry.collection,
+                preferredFile: entry.file,
+            });
             if (!doc) {
                 continue;
             }
@@ -375,7 +477,7 @@ export class QmdMemoryManager {
                 source: doc.source,
             });
         }
-        return this.clampResultsByInjectedChars(results.slice(0, limit));
+        return this.clampResultsByInjectedChars(this.diversifyResultsBySource(results, limit));
     }
     async sync(params) {
         if (params?.progress) {
@@ -395,19 +497,25 @@ export class QmdMemoryManager {
         if (!absPath.endsWith(".md")) {
             throw new Error("path required");
         }
-        const stat = await fs.lstat(absPath);
-        if (stat.isSymbolicLink() || !stat.isFile()) {
-            throw new Error("path required");
+        const statResult = await statRegularFile(absPath);
+        if (statResult.missing) {
+            return { text: "", path: relPath };
         }
         if (params.from !== undefined || params.lines !== undefined) {
-            const text = await this.readPartialText(absPath, params.from, params.lines);
-            return { text, path: relPath };
+            const partial = await this.readPartialText(absPath, params.from, params.lines);
+            if (partial.missing) {
+                return { text: "", path: relPath };
+            }
+            return { text: partial.text, path: relPath };
+        }
+        const full = await this.readFullText(absPath);
+        if (full.missing) {
+            return { text: "", path: relPath };
         }
-        const content = await fs.readFile(absPath, "utf-8");
         if (!params.from && !params.lines) {
-            return { text: content, path: relPath };
+            return { text: full.text, path: relPath };
         }
-        const lines = content.split("\n");
+        const lines = full.text.split("\n");
         const start = Math.max(1, params.from ?? 1);
         const count = Math.max(1, params.lines ?? lines.length);
         const slice = lines.slice(start - 1, start - 1 + count);
@@ -491,26 +599,18 @@ export class QmdMemoryManager {
             if (this.sessionExporter) {
                 await this.exportSessions();
             }
-            try {
-                await this.runQmd(["update"], { timeoutMs: this.qmd.update.updateTimeoutMs });
-            }
-            catch (err) {
-                if (!(await this.tryRepairNullByteCollections(err, reason))) {
-                    throw err;
-                }
-                await this.runQmd(["update"], { timeoutMs: this.qmd.update.updateTimeoutMs });
-            }
-            const embedIntervalMs = this.qmd.update.embedIntervalMs;
-            const shouldEmbed = Boolean(force) ||
-                this.lastEmbedAt === null ||
-                (embedIntervalMs > 0 && Date.now() - this.lastEmbedAt > embedIntervalMs);
-            if (shouldEmbed) {
+            await this.runQmdUpdateWithRetry(reason);
+            if (this.shouldRunEmbed(force)) {
                 try {
-                    await this.runQmd(["embed"], { timeoutMs: this.qmd.update.embedTimeoutMs });
+                    await runWithQmdEmbedLock(async () => {
+                        await this.runQmd(["embed"], { timeoutMs: this.qmd.update.embedTimeoutMs });
+                    });
                     this.lastEmbedAt = Date.now();
+                    this.embedBackoffUntil = null;
+                    this.embedFailureCount = 0;
                 }
                 catch (err) {
-                    log.warn(`qmd embed failed (${reason}): ${String(err)}`);
+                    this.noteEmbedFailure(reason, err);
                 }
             }
             this.lastUpdateAt = Date.now();
@@ -521,6 +621,62 @@ export class QmdMemoryManager {
         });
         await this.pendingUpdate;
     }
+    async runQmdUpdateWithRetry(reason) {
+        const isBootRun = reason === "boot" || reason.startsWith("boot:");
+        const maxAttempts = isBootRun ? 3 : 1;
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            try {
+                await this.runQmdUpdateOnce(reason);
+                return;
+            }
+            catch (err) {
+                if (attempt >= maxAttempts || !this.isRetryableUpdateError(err)) {
+                    throw err;
+                }
+                const delayMs = 500 * 2 ** (attempt - 1);
+                log.warn(`qmd update retry ${attempt}/${maxAttempts - 1} after failure (${reason}): ${String(err)}`);
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
+        }
+    }
+    async runQmdUpdateOnce(reason) {
+        try {
+            await this.runQmd(["update"], { timeoutMs: this.qmd.update.updateTimeoutMs });
+        }
+        catch (err) {
+            if (!(await this.tryRepairNullByteCollections(err, reason))) {
+                throw err;
+            }
+            await this.runQmd(["update"], { timeoutMs: this.qmd.update.updateTimeoutMs });
+        }
+    }
+    isRetryableUpdateError(err) {
+        if (this.isSqliteBusyError(err)) {
+            return true;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        const normalized = message.toLowerCase();
+        return normalized.includes("timed out");
+    }
+    shouldRunEmbed(force) {
+        if (this.qmd.searchMode === "search") {
+            return false;
+        }
+        const now = Date.now();
+        if (this.embedBackoffUntil !== null && now < this.embedBackoffUntil) {
+            return false;
+        }
+        const embedIntervalMs = this.qmd.update.embedIntervalMs;
+        return (Boolean(force) ||
+            this.lastEmbedAt === null ||
+            (embedIntervalMs > 0 && now - this.lastEmbedAt > embedIntervalMs));
+    }
+    noteEmbedFailure(reason, err) {
+        this.embedFailureCount += 1;
+        const delayMs = Math.min(QMD_EMBED_BACKOFF_MAX_MS, QMD_EMBED_BACKOFF_BASE_MS * 2 ** Math.max(0, this.embedFailureCount - 1));
+        this.embedBackoffUntil = Date.now() + delayMs;
+        log.warn(`qmd embed failed (${reason}): ${String(err)}; backing off for ${Math.ceil(delayMs / 1000)}s`);
+    }
     enqueueForcedUpdate(reason) {
         this.queuedForcedRuns += 1;
         if (!this.queuedForcedUpdate) {
@@ -650,10 +806,144 @@ export class QmdMemoryManager {
             });
         });
     }
+    async ensureMcporterDaemonStarted(mcporter) {
+        if (!mcporter.enabled) {
+            return;
+        }
+        if (!mcporter.startDaemon) {
+            const g = globalThis;
+            if (!g.__poolbotMcporterColdStartWarned) {
+                g.__poolbotMcporterColdStartWarned = true;
+                log.warn("mcporter qmd bridge enabled but startDaemon=false; each query may cold-start QMD MCP. Consider setting memory.qmd.mcporter.startDaemon=true to keep it warm.");
+            }
+            return;
+        }
+        const g = globalThis;
+        if (!g.__poolbotMcporterDaemonStart) {
+            g.__poolbotMcporterDaemonStart = (async () => {
+                try {
+                    await this.runMcporter(["daemon", "start"], { timeoutMs: 10_000 });
+                }
+                catch (err) {
+                    log.warn(`mcporter daemon start failed: ${String(err)}`);
+                    // Allow future searches to retry daemon start on transient failures.
+                    delete g.__poolbotMcporterDaemonStart;
+                }
+            })();
+        }
+        await g.__poolbotMcporterDaemonStart;
+    }
+    async runMcporter(args, opts) {
+        return await new Promise((resolve, reject) => {
+            const child = spawn("mcporter", args, {
+                // Keep mcporter and direct qmd commands on the same agent-scoped XDG state.
+                env: this.env,
+                cwd: this.workspaceDir,
+            });
+            let stdout = "";
+            let stderr = "";
+            let stdoutTruncated = false;
+            let stderrTruncated = false;
+            const timer = opts?.timeoutMs
+                ? setTimeout(() => {
+                    child.kill("SIGKILL");
+                    reject(new Error(`mcporter ${args.join(" ")} timed out after ${opts.timeoutMs}ms`));
+                }, opts.timeoutMs)
+                : null;
+            child.stdout.on("data", (data) => {
+                const next = appendOutputWithCap(stdout, data.toString("utf8"), this.maxQmdOutputChars);
+                stdout = next.text;
+                stdoutTruncated = stdoutTruncated || next.truncated;
+            });
+            child.stderr.on("data", (data) => {
+                const next = appendOutputWithCap(stderr, data.toString("utf8"), this.maxQmdOutputChars);
+                stderr = next.text;
+                stderrTruncated = stderrTruncated || next.truncated;
+            });
+            child.on("error", (err) => {
+                if (timer) {
+                    clearTimeout(timer);
+                }
+                reject(err);
+            });
+            child.on("close", (code) => {
+                if (timer) {
+                    clearTimeout(timer);
+                }
+                if (stdoutTruncated || stderrTruncated) {
+                    reject(new Error(`mcporter ${args.join(" ")} produced too much output (limit ${this.maxQmdOutputChars} chars)`));
+                    return;
+                }
+                if (code === 0) {
+                    resolve({ stdout, stderr });
+                }
+                else {
+                    reject(new Error(`mcporter ${args.join(" ")} failed (code ${code}): ${stderr || stdout}`));
+                }
+            });
+        });
+    }
+    async runQmdSearchViaMcporter(params) {
+        await this.ensureMcporterDaemonStarted(params.mcporter);
+        const selector = `${params.mcporter.serverName}.${params.tool}`;
+        const callArgs = {
+            query: params.query,
+            limit: params.limit,
+            minScore: params.minScore,
+        };
+        if (params.collection) {
+            callArgs.collection = params.collection;
+        }
+        const result = await this.runMcporter([
+            "call",
+            selector,
+            "--args",
+            JSON.stringify(callArgs),
+            "--output",
+            "json",
+            "--timeout",
+            String(Math.max(0, params.timeoutMs)),
+        ], { timeoutMs: Math.max(params.timeoutMs + 2_000, 5_000) });
+        const parsedUnknown = JSON.parse(result.stdout);
+        const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+        const structured = isRecord(parsedUnknown) && isRecord(parsedUnknown.structuredContent)
+            ? parsedUnknown.structuredContent
+            : parsedUnknown;
+        const results = isRecord(structured) && Array.isArray(structured.results)
+            ? structured.results
+            : Array.isArray(structured)
+                ? structured
+                : [];
+        const out = [];
+        for (const item of results) {
+            if (!isRecord(item)) {
+                continue;
+            }
+            const docidRaw = item.docid;
+            const docid = typeof docidRaw === "string" ? docidRaw.replace(/^#/, "").trim() : "";
+            if (!docid) {
+                continue;
+            }
+            const scoreRaw = item.score;
+            const score = typeof scoreRaw === "number" ? scoreRaw : Number(scoreRaw);
+            const snippet = typeof item.snippet === "string" ? item.snippet : "";
+            out.push({ docid, score: Number.isFinite(score) ? score : 0, snippet });
+        }
+        return out;
+    }
     async readPartialText(absPath, from, lines) {
         const start = Math.max(1, from ?? 1);
         const count = Math.max(1, lines ?? Number.POSITIVE_INFINITY);
-        const handle = await fs.open(absPath);
+        let handle;
+        try {
+            handle = await fs.open(absPath);
+        }
+        catch (err) {
+            if (isFileMissingError(err)) {
+                return { missing: true };
+            }
+            throw err;
+        }
         const stream = handle.createReadStream({ encoding: "utf-8" });
         const rl = readline.createInterface({
             input: stream,
@@ -677,7 +967,19 @@ export class QmdMemoryManager {
             rl.close();
             await handle.close();
         }
-        return selected.slice(0, count).join("\n");
+        return { missing: false, text: selected.slice(0, count).join("\n") };
+    }
+    async readFullText(absPath) {
+        try {
+            const text = await fs.readFile(absPath, "utf-8");
+            return { missing: false, text };
+        }
+        catch (err) {
+            if (isFileMissingError(err)) {
+                return { missing: true };
+            }
+            throw err;
+        }
     }
     ensureDb() {
         if (this.db) {
@@ -762,7 +1064,7 @@ export class QmdMemoryManager {
         const trimmed = lower.replace(/^-+|-+$/g, "");
         return trimmed || "agent";
     }
-    async resolveDocLocation(docid) {
+    async resolveDocLocation(docid, hints) {
         if (!docid) {
             return null;
         }
@@ -770,21 +1072,21 @@ export class QmdMemoryManager {
         if (!normalized) {
             return null;
         }
-        const cached = this.docPathCache.get(normalized);
+        const cacheKey = `${hints?.preferredCollection ?? "*"}:${normalized}`;
+        const cached = this.docPathCache.get(cacheKey);
         if (cached) {
             return cached;
         }
         const db = this.ensureDb();
-        let row;
+        let rows = [];
         try {
-            const exact = db
-                .prepare("SELECT collection, path FROM documents WHERE hash = ? AND active = 1 LIMIT 1")
-                .get(normalized);
-            row = exact;
-            if (!row) {
-                row = db
-                    .prepare("SELECT collection, path FROM documents WHERE hash LIKE ? AND active = 1 LIMIT 1")
-                    .get(`${normalized}%`);
+            rows = db
+                .prepare("SELECT collection, path FROM documents WHERE hash = ? AND active = 1")
+                .all(normalized);
+            if (rows.length === 0) {
+                rows = db
+                    .prepare("SELECT collection, path FROM documents WHERE hash LIKE ? AND active = 1")
+                    .all(`${normalized}%`);
             }
         }
         catch (err) {
@@ -794,16 +1096,49 @@ export class QmdMemoryManager {
             }
             throw err;
         }
-        if (!row) {
+        if (rows.length === 0) {
             return null;
         }
-        const location = this.toDocLocation(row.collection, row.path);
+        const location = this.pickDocLocation(rows, hints);
         if (!location) {
             return null;
         }
-        this.docPathCache.set(normalized, location);
+        this.docPathCache.set(cacheKey, location);
         return location;
     }
+    pickDocLocation(rows, hints) {
+        if (hints?.preferredCollection) {
+            for (const row of rows) {
+                if (row.collection !== hints.preferredCollection) {
+                    continue;
+                }
+                const location = this.toDocLocation(row.collection, row.path);
+                if (location) {
+                    return location;
+                }
+            }
+        }
+        if (hints?.preferredFile) {
+            const preferred = path.normalize(hints.preferredFile);
+            for (const row of rows) {
+                const rowPath = path.normalize(row.path);
+                if (rowPath !== preferred && !rowPath.endsWith(path.sep + preferred)) {
+                    continue;
+                }
+                const location = this.toDocLocation(row.collection, row.path);
+                if (location) {
+                    return location;
+                }
+            }
+        }
+        for (const row of rows) {
+            const location = this.toDocLocation(row.collection, row.path);
+            if (location) {
+                return location;
+            }
+        }
+        return null;
+    }
     extractSnippetLines(snippet) {
         const match = SNIPPET_HEADER_RE.exec(snippet);
         if (match) {
@@ -962,6 +1297,48 @@ export class QmdMemoryManager {
         }
         return clamped;
     }
+    diversifyResultsBySource(results, limit) {
+        const target = Math.max(0, limit);
+        if (target <= 0) {
+            return [];
+        }
+        if (results.length <= 1) {
+            return results.slice(0, target);
+        }
+        const bySource = new Map();
+        for (const entry of results) {
+            const list = bySource.get(entry.source) ?? [];
+            list.push(entry);
+            bySource.set(entry.source, list);
+        }
+        const hasSessions = bySource.has("sessions");
+        const hasMemory = bySource.has("memory");
+        if (!hasSessions || !hasMemory) {
+            return results.slice(0, target);
+        }
+        const sourceOrder = Array.from(bySource.entries())
+            .toSorted((a, b) => (b[1][0]?.score ?? 0) - (a[1][0]?.score ?? 0))
+            .map(([source]) => source);
+        const diversified = [];
+        while (diversified.length < target) {
+            let emitted = false;
+            for (const source of sourceOrder) {
+                const next = bySource.get(source)?.shift();
+                if (!next) {
+                    continue;
+                }
+                diversified.push(next);
+                emitted = true;
+                if (diversified.length >= target) {
+                    break;
+                }
+            }
+            if (!emitted) {
+                break;
+            }
+        }
+        return diversified;
+    }
     shouldSkipUpdate(force) {
         if (force) {
             return false;
@@ -1003,14 +1380,50 @@ export class QmdMemoryManager {
             new Promise((resolve) => setTimeout(resolve, SEARCH_PENDING_UPDATE_WAIT_MS)),
         ]);
     }
-    async runQueryAcrossCollections(query, limit, collectionNames) {
-        log.debug(`qmd query multi-collection workaround active (${collectionNames.length} collections)`);
+    async runQueryAcrossCollections(query, limit, collectionNames, command) {
+        log.debug(`qmd ${command} multi-collection workaround active (${collectionNames.length} collections)`);
         const bestByDocId = new Map();
         for (const collectionName of collectionNames) {
-            const args = this.buildSearchArgs("query", query, limit);
+            const args = this.buildSearchArgs(command, query, limit);
             args.push("-c", collectionName);
             const result = await this.runQmd(args, { timeoutMs: this.qmd.limits.timeoutMs });
             const parsed = parseQmdQueryJson(result.stdout, result.stderr);
+            for (const entry of parsed) {
+                const normalizedDocId = typeof entry.docid === "string" && entry.docid.trim().length > 0
+                    ? entry.docid
+                    : undefined;
+                if (!normalizedDocId) {
+                    continue;
+                }
+                const withCollection = {
+                    ...entry,
+                    docid: normalizedDocId,
+                    collection: entry.collection ?? collectionName,
+                };
+                const prev = bestByDocId.get(normalizedDocId);
+                const prevScore = typeof prev?.score === "number" ? prev.score : Number.NEGATIVE_INFINITY;
+                const nextScore = typeof withCollection.score === "number"
+                    ? withCollection.score
+                    : Number.NEGATIVE_INFINITY;
+                if (!prev || nextScore > prevScore) {
+                    bestByDocId.set(normalizedDocId, withCollection);
+                }
+            }
+        }
+        return [...bestByDocId.values()].toSorted((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    }
+    async runMcporterAcrossCollections(params) {
+        const bestByDocId = new Map();
+        for (const collectionName of params.collectionNames) {
+            const parsed = await this.runQmdSearchViaMcporter({
+                mcporter: this.qmd.mcporter,
+                tool: params.tool,
+                query: params.query,
+                limit: params.limit,
+                minScore: params.minScore,
+                collection: collectionName,
+                timeoutMs: this.qmd.limits.timeoutMs,
+            });
             for (const entry of parsed) {
                 if (typeof entry.docid !== "string" || !entry.docid.trim()) {
                     continue;