xtctx 0.13.0 → 0.14.0

package/dist/src/handoff/sqlite-index.js

@@ -4,12 +4,36 @@ import { dirname, join } from "node:path";
 import Database from "better-sqlite3";
 import { DEFAULT_EMBEDDING_MODEL, TransformersEmbeddingProvider, poolVectors, splitTextForEmbedding, } from "./embeddings.js";
 import { cosineSimilarity, deserializeVector, serializeVector } from "./vector.js";
+/**
+ * How long a tool call will wait for a scan of every transcript store on the
+ * machine.
+ *
+ * A cold scan here takes about 55 seconds — 18GB of codex history is most of
+ * it — and it used to run inside the caller's first tool call. MCP servers are
+ * spawned per agent session, so that was paid on every handoff, and a host
+ * with a 30s tool timeout never got a first answer at all.
+ *
+ * The scan is not cancelled when the budget expires; the caller just stops
+ * waiting for it. Everything it has already written stays written, so the next
+ * call sees more, and the call after that sees all of it.
+ */
+const DEFAULT_REFRESH_BUDGET_MS = 4_000;
+/**
+ * How long one search spends building vectors before answering.
+ *
+ * The first semantic search used to vectorize the entire corpus inline: 530
+ * seconds on a 1,145-window index, inside a single tool call, with no cap and
+ * nothing to show for the wait. Each batch commits on its own, so stopping
+ * early costs nothing — the next search picks up where this one stopped, and
+ * recall improves call over call until the corpus is covered.
+ */
+const DEFAULT_VECTOR_BUDGET_MS = 6_000;
 /**
  * Bumped whenever the schema shape changes. The index is derived data, so a
  * version mismatch (older or newer) triggers a full rebuild rather than a
  * migration — the transcript stores remain authoritative.
  */
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 const DEFAULT_LIMIT = 5;
 const MAX_LIMIT = 100;
 const DEFAULT_WINDOW_SIZE = 8;
@@ -17,10 +41,34 @@ const DEFAULT_WINDOW_STRIDE = 4;
 const MAX_MATCHES_PER_SESSION = 3;
 /**
  * Minimum raw cosine similarity for a retrieval window to count as a semantic
- * match. Unrelated sentence-transformer pairs sit near 0; related ones are
+ * match.
+ *
+ * Unrelated sentence-transformer pairs sit near 0; related ones are
  * comfortably above this.
  */
 const MIN_SEMANTIC_COSINE = 0.15;
+/**
+ * How similar the *best* window has to be before a query counts as having
+ * found anything semantically.
+ *
+ * The per-window floor above cannot do this job. Raising it high enough to
+ * reject a nonsense query — which cleared 0.15 on 927 of 1,145 windows, 81% of
+ * the corpus — also discards genuine mid-range matches, and pure vector search
+ * has no keyword hits to fall back on: at a 0.35 per-window floor the eval
+ * lost recall@5 from 0.70 to 0.50.
+ *
+ * Whether a query found anything is a property of the query, not of each
+ * window. So when nothing clears this bar, semantic matches are dropped
+ * wholesale and only keyword hits remain — usually meaning "no matching
+ * sessions", which is the honest answer. When something does clear it, the
+ * weaker windows around it are kept.
+ *
+ * The value is bounded from both sides and the gap is narrow: gibberish tops
+ * out near 0.31 against this index, genuine queries reach 0.44-0.59, and the
+ * ranking eval starts losing vector recall above 0.32. If it needs to move,
+ * move it against the eval rather than against one query.
+ */
+const MIN_CONFIDENT_COSINE = 0.32;
 /**
  * Weight of the recency/continuity tie-break in the relevance modes. Small
  * enough that it only ever separates candidates that are otherwise equal.
@@ -36,7 +84,22 @@ export class SqliteHandoffIndex {
     initialized;
     refreshPromise = null;
     lastRefreshMs = 0;
-    refreshTtlMs = 5_000;
+    /**
+     * How long an indexed view is treated as current.
+     *
+     * A scan re-reads every transcript store on the machine, so at five seconds
+     * almost every tool call in a session started a fresh one and paid the wait
+     * budget again. The transcripts being read belong to sessions that ended
+     * before this one started; they do not change second to second.
+     */
+    refreshTtlMs = 30_000;
+    refreshBudgetMs;
+    vectorBudgetMs;
+    scanStartedMs = 0;
+    /** The embedding model is loading, so this answer came from keyword search alone. */
+    embeddingWarming = false;
+    /** Windows still waiting to be vectorized after the last search gave up its budget. */
+    vectorBacklog = 0;
     embeddingProvider;
     windowSize;
     windowStride;
@@ -48,32 +111,66 @@ export class SqliteHandoffIndex {
             options.embeddingProvider ?? new TransformersEmbeddingProvider(DEFAULT_EMBEDDING_MODEL);
         this.windowSize = Math.max(2, Math.floor(options.windowSize ?? DEFAULT_WINDOW_SIZE));
         this.windowStride = Math.max(1, Math.floor(options.windowStride ?? DEFAULT_WINDOW_STRIDE));
+        this.refreshBudgetMs = Math.max(0, options.refreshBudgetMs ?? DEFAULT_REFRESH_BUDGET_MS);
+        this.vectorBudgetMs = Math.max(0, options.vectorBudgetMs ?? DEFAULT_VECTOR_BUDGET_MS);
         this.initialized = this.initialize();
         // Attach a no-op handler so a failed open cannot become an unhandled
         // rejection (which would kill the process) before the first caller
         // awaits; each awaiter of `initialized` still observes the rejection.
         this.initialized.catch(() => { });
     }
-    async listRecentSessions(limit, toolFilter) {
+    async listRecentSessions(limit, toolFilter, branchFilter) {
         await this.refresh({ toolFilter });
         const db = this.getDb();
         const normalizedLimit = normalizeLimit(limit, DEFAULT_LIMIT);
         const filters = normalizeToolFilter(toolFilter);
-        const where = filters.length > 0 ? `WHERE tool IN (${placeholders(filters.length)})` : "";
+        const branches = normalizeToolFilter(branchFilter);
+        const clauses = [];
+        if (filters.length > 0) {
+            clauses.push(`tool IN (${placeholders(filters.length)})`);
+        }
+        if (branches.length > 0) {
+            // A session with no recorded branch is not evidence that it was on the
+            // requested one, so it is excluded rather than assumed in.
+            clauses.push(`git_branch IN (${placeholders(branches.length)})`);
+        }
+        const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
         const rows = db
-            .prepare(`SELECT session_ref, tool, started_at, last_activity_at, message_count, preview, source_path
+            .prepare(`SELECT session_ref, tool, started_at, last_activity_at, message_count, preview, source_path,
+                git_branch, git_commit
          FROM sessions
          ${where}
          ORDER BY last_activity_at DESC
          LIMIT ?`)
-            .all(...filters, normalizedLimit);
+            .all(...filters, ...branches, normalizedLimit);
+        return rows.map(formatSessionRow);
+    }
+    /**
+     * What is already indexed, with no scan and no waiting.
+     *
+     * The SessionStart hook runs before the user has typed anything, so it
+     * cannot afford the scan `listRecentSessions` starts — even bounded, that
+     * is four seconds added to every agent startup. Priming with slightly
+     * stale context instantly beats priming with fresh context late.
+     */
+    async listIndexedSessions(limit) {
+        await this.initialized;
+        const db = this.getDb();
+        const rows = db
+            .prepare(`SELECT session_ref, tool, started_at, last_activity_at, message_count, preview, source_path,
+                git_branch, git_commit
+         FROM sessions
+         ORDER BY last_activity_at DESC
+         LIMIT ?`)
+            .all(normalizeLimit(limit, DEFAULT_LIMIT));
         return rows.map(formatSessionRow);
     }
     async getSessionByRef(sessionRef) {
         await this.refresh({ sessionRef });
         const db = this.getDb();
         const row = db
-            .prepare(`SELECT session_ref, tool, started_at, last_activity_at, message_count, preview, source_path
+            .prepare(`SELECT session_ref, tool, started_at, last_activity_at, message_count, preview, source_path,
+                git_branch, git_commit
          FROM sessions
          WHERE session_ref = ?`)
             .get(sessionRef);
@@ -98,7 +195,7 @@ export class SqliteHandoffIndex {
             source_pointer: row.source_pointer ?? undefined,
         }));
     }
-    async searchSessions(query, limit, toolFilter, mode = "hybrid") {
+    async searchSessions(query, limit, toolFilter, mode = "hybrid", branchFilter) {
         await this.refresh({ toolFilter });
         const trimmed = query.trim();
         if (!trimmed) {
@@ -106,10 +203,21 @@ export class SqliteHandoffIndex {
         }
         const normalizedMode = normalizeSearchMode(mode);
         if (normalizedMode === "keyword") {
-            return this.keywordSearch(trimmed, limit, toolFilter);
+            return this.keywordSearch(trimmed, limit, toolFilter, branchFilter);
+        }
+        // Loading the embedding model is a one-off that takes minutes on a cold
+        // cache. Hybrid is the default mode, so blocking it on that made the first
+        // search of a session look broken. Start the load, answer from keyword,
+        // and let the next search use the model. An explicit `vector` request is a
+        // different matter: there is no other route, so that one waits.
+        if (normalizedMode === "hybrid" && this.embeddingProvider.isReady?.() === false) {
+            this.embeddingProvider.warm?.();
+            this.embeddingWarming = true;
+            return this.keywordSearch(trimmed, limit, toolFilter, branchFilter);
         }
+        this.embeddingWarming = false;
         try {
-            const results = await this.semanticSearch(trimmed, limit, toolFilter, normalizedMode);
+            const results = await this.semanticSearch(trimmed, limit, toolFilter, normalizedMode, branchFilter);
             clearSetting(this.getDb(), "last_error:embeddings");
             return results;
         }
@@ -121,7 +229,7 @@ export class SqliteHandoffIndex {
                 const message = error instanceof Error ? error.message : String(error);
                 setSetting(this.getDb(), "last_error:embeddings", message);
                 process.stderr.write(`xtctx: semantic search unavailable, using keyword only (${message})\n`);
-                return this.keywordSearch(trimmed, limit, toolFilter);
+                return this.keywordSearch(trimmed, limit, toolFilter, branchFilter);
             }
             throw error;
         }
@@ -171,6 +279,10 @@ export class SqliteHandoffIndex {
     }
     async close() {
         await this.initialized.catch(() => { });
+        // A scan may still be running because a caller stopped waiting for it.
+        // Closing the database underneath it would turn an ordinary shutdown into
+        // a write to a closed handle.
+        await this.whenScanSettled();
         this.db?.close();
         this.db = null;
     }
@@ -183,14 +295,66 @@ export class SqliteHandoffIndex {
             return;
         }
         if (!this.refreshPromise) {
-            this.refreshPromise = this.refreshNow().finally(() => {
+            const running = this.refreshNow().finally(() => {
                 // Stamp the TTL on failure as well as success so a persistently
                 // broken refresh backs off instead of re-running on every call.
                 this.lastRefreshMs = Date.now();
                 this.refreshPromise = null;
             });
+            // A caller may stop waiting on this promise, so it needs its own
+            // handler: an unhandled rejection would take the process down.
+            running.catch(() => { });
+            this.refreshPromise = running;
+            this.scanStartedMs = Date.now();
+        }
+        await this.waitWithBudget(this.refreshPromise);
+    }
+    /**
+     * Wait for the scan, but not past the budget. Nothing is cancelled on
+     * timeout — the scan keeps running and keeps committing — so a caller that
+     * stops waiting costs the index nothing, and the next call finds more.
+     */
+    async waitWithBudget(scan) {
+        if (this.refreshBudgetMs === 0) {
+            return;
+        }
+        // The budget is spent by the scan, not by each caller. Measuring it from
+        // when the scan started means one call pays the wait and the calls behind
+        // it return straight away with whatever has landed so far — rather than
+        // every call in a session paying the full budget over again.
+        const remaining = this.scanStartedMs + this.refreshBudgetMs - Date.now();
+        if (remaining <= 0) {
+            return;
+        }
+        let timer;
+        const budget = new Promise((resolve) => {
+            timer = setTimeout(resolve, remaining);
+            // Do not hold the process open just to enforce a deadline.
+            timer.unref?.();
+        });
+        try {
+            await Promise.race([scan.catch(() => { }), budget]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** True when a scan started by an earlier call is still running. */
+    isScanning() {
+        return this.refreshPromise !== null;
+    }
+    getIndexProgress() {
+        return {
+            scanning: this.isScanning(),
+            vectorBacklog: this.vectorBacklog,
+            embeddingWarming: this.embeddingWarming,
+        };
+    }
+    /** Resolves when no scan is in flight. Used by close() and by tests. */
+    async whenScanSettled() {
+        while (this.refreshPromise) {
+            await this.refreshPromise.catch(() => { });
         }
-        await this.refreshPromise;
     }
     async refreshNow() {
         const db = this.getDb();
@@ -259,6 +423,8 @@ export class SqliteHandoffIndex {
             chunk.tool,
             chunk.sessionId,
             this.projectRoot,
+            chunk.metadata?.gitBranch ?? null,
+            chunk.metadata?.gitCommit ?? null,
             timestamp,
             timestamp,
             sourcePointer,
@@ -345,9 +511,9 @@ export class SqliteHandoffIndex {
         }
         const db = this.getDb();
         const upsertSession = db.prepare(`INSERT INTO sessions
-       (session_ref, tool, source_session_id, project_root, started_at, last_activity_at,
-        message_count, preview, source_path, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, 0, NULL, ?, ?)
+       (session_ref, tool, source_session_id, project_root, git_branch, git_commit,
+        started_at, last_activity_at, message_count, preview, source_path, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, NULL, ?, ?)
        ON CONFLICT(session_ref) DO UPDATE SET
          started_at = CASE
            WHEN excluded.started_at < started_at THEN excluded.started_at
@@ -357,6 +523,10 @@ export class SqliteHandoffIndex {
            WHEN excluded.last_activity_at > last_activity_at THEN excluded.last_activity_at
            ELSE last_activity_at
          END,
+         -- First non-null wins: a session keeps the branch it started on
+         -- even if later records omit it.
+         git_branch = COALESCE(git_branch, excluded.git_branch),
+         git_commit = COALESCE(git_commit, excluded.git_commit),
          source_path = COALESCE(source_path, excluded.source_path),
          updated_at = excluded.updated_at`);
         const insertMessage = db.prepare(`INSERT OR IGNORE INTO messages
@@ -402,17 +572,21 @@ export class SqliteHandoffIndex {
         };
         return this.stmts;
     }
-    async keywordSearch(query, limit, toolFilter) {
-        const rows = this.queryKeywordUnits(query, limit, toolFilter);
+    async keywordSearch(query, limit, toolFilter, branchFilter) {
+        const rows = this.queryKeywordUnits(query, limit, toolFilter, branchFilter);
         // Rank by BM25 position so relevance, not recency, dominates ordering.
         return groupUnits(rows, rankKeywordRows(rows), "keyword", normalizeLimit(limit, DEFAULT_LIMIT));
     }
-    async semanticSearch(query, limit, toolFilter, mode) {
+    async semanticSearch(query, limit, toolFilter, mode, branchFilter) {
         const normalizedLimit = normalizeLimit(limit, DEFAULT_LIMIT);
         await this.ensureVectors(toolFilter);
         const db = this.getDb();
         const filters = normalizeToolFilter(toolFilter);
         const toolWhere = filters.length > 0 ? `AND u.tool IN (${placeholders(filters.length)})` : "";
+        const branches = normalizeToolFilter(branchFilter);
+        // Sessions with no recorded branch are excluded rather than assumed in:
+        // no branch is not evidence of this branch.
+        const branchWhere = branches.length > 0 ? `AND s.git_branch IN (${placeholders(branches.length)})` : "";
         const rows = db
             .prepare(`${retrievalUnitSelect()},
                 v.vector,
@@ -420,12 +594,12 @@ export class SqliteHandoffIndex {
          FROM retrieval_units u
          JOIN retrieval_unit_vectors v ON v.unit_id = u.id
          JOIN sessions s ON s.session_ref = u.session_ref
-         WHERE v.model = ? ${toolWhere}`)
-            .all(this.embeddingProvider.model, ...filters);
+         WHERE v.model = ? ${toolWhere} ${branchWhere}`)
+            .all(this.embeddingProvider.model, ...filters, ...branches);
         if (rows.length === 0) {
             return [];
         }
-        const keywordRows = mode === "hybrid" ? this.queryKeywordUnits(query, limit, toolFilter) : [];
+        const keywordRows = mode === "hybrid" ? this.queryKeywordUnits(query, limit, toolFilter, branchFilter) : [];
         const keywordScores = rankKeywordRows(keywordRows);
         const queryVector = await this.embeddingProvider.embed(query);
         const timeRange = getTimeRange(rows.map((row) => row.ended_at));
@@ -446,30 +620,48 @@ export class SqliteHandoffIndex {
             // on semantic similarity or a keyword match; "no matching sessions" is
             // a more useful answer than a nearest vector.
             .filter((item) => item.rawCosine >= MIN_SEMANTIC_COSINE || item.keywordScore > 0);
-        // Rescale cosine across this query's surviving candidates before blending.
-        // Mapping [-1,1] onto [0,1] globally left every candidate bunched near
-        // 0.5, so the semantic term barely varied while recency swung across its
-        // whole range — recency effectively outranked relevance. Measured on the
-        // ranking eval, this one change took hybrid from MRR 0.488 / recall@5
-        // 0.65 to 0.621 / 0.85.
-        const cosines = candidates.map((item) => item.rawCosine);
+        // Nothing here is actually similar to the query — keep only what matched
+        // on words. For a query that means nothing to this corpus that leaves
+        // nothing at all, which is the answer.
+        const bestCosine = candidates.reduce((best, item) => Math.max(best, item.rawCosine), 0);
+        const semanticallyConfident = bestCosine >= MIN_CONFIDENT_COSINE;
+        const surviving = semanticallyConfident
+            ? candidates
+            : candidates.filter((item) => item.keywordScore > 0);
+        if (surviving.length === 0) {
+            return [];
+        }
+        // Ordering and reporting are two different jobs, and conflating them is
+        // what made the score meaningless.
+        //
+        // Ordering wants contrast: rescaling this query's survivors onto [0,1]
+        // spreads them out and measurably ranks better (hybrid MRR 0.566 -> 0.613
+        // on the eval). Reporting wants an absolute: the rescale forces the best
+        // survivor to exactly 1.0 however weak it is, so three nonsense words
+        // scored 0.901 against a real query's 0.872 and an agent had no way to
+        // tell a find from a shrug.
+        //
+        // So candidates are ranked on the rescaled value and reported with the
+        // cosine itself.
+        const cosines = surviving.map((item) => item.rawCosine);
         const lowest = Math.min(...cosines);
         const highest = Math.max(...cosines);
         const spread = highest - lowest;
-        const scored = candidates
+        const scored = surviving
             .map((item) => {
             // A lone survivor is the best match by definition, not the worst.
             const semanticScore = spread > 0 ? (item.rawCosine - lowest) / spread : 1;
             return {
                 ...item,
                 semanticScore,
+                relevance: Math.max(0, Math.min(1, item.rawCosine)),
                 score: blendScores(mode, semanticScore, item.keywordScore, item.recencyScore, item.continuityScore),
             };
         })
             .sort((left, right) => right.score - left.score);
         return groupScoredUnits(scored, mode, normalizedLimit);
     }
-    queryKeywordUnits(query, limit, toolFilter) {
+    queryKeywordUnits(query, limit, toolFilter, branchFilter) {
         const ftsQuery = toFtsQuery(query);
         if (!ftsQuery) {
             return [];
@@ -478,15 +670,19 @@ export class SqliteHandoffIndex {
         const normalizedLimit = normalizeLimit(limit, DEFAULT_LIMIT);
         const filters = normalizeToolFilter(toolFilter);
         const toolWhere = filters.length > 0 ? `AND u.tool IN (${placeholders(filters.length)})` : "";
+        const branches = normalizeToolFilter(branchFilter);
+        // Sessions with no recorded branch are excluded rather than assumed in:
+        // no branch is not evidence of this branch.
+        const branchWhere = branches.length > 0 ? `AND s.git_branch IN (${placeholders(branches.length)})` : "";
         return db
             .prepare(`${retrievalUnitSelect()}
          FROM retrieval_units_fts f
          JOIN retrieval_units u ON u.id = f.unit_id
          JOIN sessions s ON s.session_ref = u.session_ref
-         WHERE retrieval_units_fts MATCH ? ${toolWhere}
+         WHERE retrieval_units_fts MATCH ? ${toolWhere} ${branchWhere}
          ORDER BY bm25(retrieval_units_fts), u.ended_at DESC
          LIMIT ?`)
-            .all(ftsQuery, ...filters, normalizedLimit * MAX_MATCHES_PER_SESSION);
+            .all(ftsQuery, ...filters, ...branches, normalizedLimit * MAX_MATCHES_PER_SESSION);
     }
     async ensureVectors(toolFilter) {
         const db = this.getDb();
@@ -502,6 +698,7 @@ export class SqliteHandoffIndex {
          WHERE v.unit_id IS NULL ${toolWhere}
          ORDER BY u.ended_at DESC`)
             .all(this.embeddingProvider.model, ...filters);
+        this.vectorBacklog = 0;
         if (rows.length === 0) {
             return;
         }
@@ -515,8 +712,19 @@ export class SqliteHandoffIndex {
          created_at = excluded.created_at`);
         // Bounded batches keep memory flat on a first-time index of a large
         // history, and each batch commits before the next one embeds.
-        const unitBatchSize = 64;
+        // Small enough that the budget below can actually bite. At 64 windows a
+        // single batch took 20-30s on the real index, so the deadline — checked
+        // between batches — could not stop a search from blowing straight past it.
+        const unitBatchSize = 8;
+        // Answer with the vectors that exist rather than making the caller wait
+        // for the whole corpus. Every batch below commits before the next starts,
+        // so an unfinished pass is progress, not wasted work.
+        const deadline = this.vectorBudgetMs > 0 ? Date.now() + this.vectorBudgetMs : Infinity;
         for (let start = 0; start < rows.length; start += unitBatchSize) {
+            if (Date.now() >= deadline) {
+                this.vectorBacklog = rows.length - start;
+                break;
+            }
             const batch = rows.slice(start, start + unitBatchSize);
             // Long windows are segmented to the model's sequence budget and
             // mean-pooled, so content beyond the window's opening still shapes
@@ -615,6 +823,8 @@ function createSchema(db) {
       tool TEXT NOT NULL,
       source_session_id TEXT NOT NULL,
       project_root TEXT NOT NULL,
+      git_branch TEXT,
+      git_commit TEXT,
       started_at TEXT NOT NULL,
       last_activity_at TEXT NOT NULL,
       message_count INTEGER NOT NULL DEFAULT 0,
@@ -707,6 +917,8 @@ function formatSessionRow(row) {
         message_count: row.message_count,
         preview: row.preview ?? undefined,
         source_path: row.source_path ?? undefined,
+        git_branch: row.git_branch ?? undefined,
+        git_commit: row.git_commit ?? undefined,
     };
 }
 function buildMessageWindows(messages, windowSize, windowStride) {
@@ -751,6 +963,10 @@ function groupUnits(rows, keywordScores, retrieval, limit) {
         return {
             row,
             score: blendScores("keyword", 0, keywordScore, recencyScore, continuityScore),
+            // Deliberately no relevance: keyword scores are reciprocal rank, so the
+            // top FTS hit is 1.0 whatever it actually matched. Reporting that as a
+            // strength of match is the same lie the cosine rescale was telling.
+            relevance: undefined,
             semanticScore: 0,
             keywordScore,
             recencyScore,
@@ -760,6 +976,10 @@ function groupUnits(rows, keywordScores, retrieval, limit) {
     return groupScoredUnits(scored, retrieval, limit);
 }
 function groupScoredUnits(scored, retrieval, limit) {
+    // `score` orders; `relevance` is what the caller is told. Kept apart here so
+    // the ranking the eval measures and the number an agent reads about a match
+    // can each be the right thing.
+    const ranks = new Map();
     const sessions = new Map();
     for (const item of scored) {
         const existing = sessions.get(item.row.session_ref);
@@ -768,9 +988,14 @@ function groupScoredUnits(scored, retrieval, limit) {
             if ((existing.matches?.length ?? 0) < MAX_MATCHES_PER_SESSION) {
                 existing.matches = [...(existing.matches ?? []), match];
             }
-            existing.score = Math.max(existing.score ?? 0, item.score);
+            existing.score =
+                item.relevance === undefined
+                    ? existing.score
+                    : Math.max(existing.score ?? 0, item.relevance);
+            ranks.set(item.row.session_ref, Math.max(ranks.get(item.row.session_ref) ?? 0, item.score));
             continue;
         }
+        ranks.set(item.row.session_ref, item.score);
         sessions.set(item.row.session_ref, {
             session_ref: item.row.session_ref,
             tool: item.row.tool,
@@ -779,7 +1004,7 @@ function groupScoredUnits(scored, retrieval, limit) {
             message_count: item.row.session_message_count,
             preview: item.row.session_preview ?? previewText(item.row.content),
             source_path: item.row.source_path ?? undefined,
-            score: item.score,
+            score: item.relevance,
             retrieval,
             matches: [match],
         });
@@ -787,7 +1012,7 @@ function groupScoredUnits(scored, retrieval, limit) {
             break;
         }
     }
-    return [...sessions.values()].sort((left, right) => (right.score ?? 0) - (left.score ?? 0));
+    return [...sessions.values()].sort((left, right) => (ranks.get(right.session_ref) ?? 0) - (ranks.get(left.session_ref) ?? 0));
 }
 function formatMatch(item) {
     return {