ko-qmd 2.8.3-ko.6 → 2.8.3-ko.7

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 ## [Unreleased]
 
+## [2.8.3-ko.7] - 2026-10-02
+
+The query path is now observable and bounded. Every query-log row breaks its latency into
+stages, the daemon logs its heap once an hour, and expansion and rerank stop waiting past a
+deadline instead of holding a query for 85 s. The reranker also sees a note's first chunk by default.
+
+- `qmd mcp` (stdio and HTTP) no longer waits on a slow LLM stage without bound. Past
+  `QMD_EXPAND_DEADLINE_MS` (default 5 s) a query searches its original text alone, and past
+  `QMD_RERANK_DEADLINE_MS` (default 10 s) it answers in RRF order; `0` restores waiting. The clock
+  starts once the model is loaded, so a cold start or a reload after the idle unload is not a timeout;
+  the query log records that wait as a `load` stage. One MCP `query` with expansion and rerank took
+  85 s. The REST `/query` response and the MCP `query` tool say which stage timed out (`timeouts`),
+  the query log row lists it the same way, and a timed-out rerank reads `rerank: "timeout"` there.
+  A fallback does not apply `minScore` to its 1/rank scores. An abandoned expansion or rerank keeps
+  running and fills its cache; until it finishes, later queries skip that stage (logged once) instead
+  of queueing behind it. The CLI search commands and the SDK (`rerankDeadlineMs`, `expandDeadlineMs`
+  options) never set a deadline on their own.
+
+- The daemon's query log row now carries `stages`, the milliseconds spent in each stage of the
+  search: `refresh` (the pre-query re-index check), `expand`, `fts`, `embed`, `vec`, `chunk`,
+  `rerank` and `serialize`; a stage that did not run is absent. REST `rerank:false` queries had a p95 of 2.9–5.3 s
+  against a p50 of 0.2–0.5 s with no rerank in the path, and the single `ms` could not say which
+  stage the tail came from. Daemon log lines now start with a dated local ISO timestamp instead of
+  a UTC `HH:mm:ss.SSS`, so a slow line can be matched to its row.
+
+- The HTTP daemon logs a `health` line every hour: heap used and total, rss, and how many
+  `subscriptions/listen` and other `/mcp` requests have a handler still waiting on its response. A daemon that ran ten days died with
+  "Reached heap limit" after its heap crept to 3.8 GB under idle discover/cancelled traffic, and
+  nothing in the log showed the slope or what was holding memory. `QMD_HEALTH_LOG_INTERVAL_MS`
+  changes the interval; `0` turns it off.
+
+- `scripts/autoresearch/prepare.sh` builds the goldset from more than the collection folder and over
+  several runs. `AR_EXTRA_DIRS="outputs docs"` copies sibling folders of the collection into the corpus
+  (names only, so no vault path lands in git), `AR_RUN=N` writes `generated-N.json` from documents no
+  earlier run answered (`bench-vault-paraphrase.ts --dirs`, `--skip`), and `split` merges every run,
+  drops the query ids listed in `dropped.txt`, and splits only each run's new documents, so an earlier
+  train/held-out assignment never moves.
+
+- The reranker now gets a note's first chunk, its title and summary: the first chunk starts 16
+  points ahead in chunk selection (8 when an intent is given, so intent words can still pick a later
+  chunk). A later chunk needs 17 more points, about nine English words or seventeen Hangul syllable
+  pairs, so for a typical short query the first chunk is always sent. A second autoresearch loop found
+  this on a goldset of 320 train and 71 held-out queries drawn from four vault folders. Held-out full
+  MRR goes 0.7291 → 0.7459, ko-vault seam and hard lines are unchanged, and bm25, vector and hybrid
+  results are identical (`BASELINE.md` 2026-09-29).
+
 ## [2.8.3-ko.6] - 2026-09-29
 
 Korean queries are handled better before and during reranking. A query written

package/dist/cli/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "c544042",
-  "builtAt": "2026-09-29T00:59:00.970Z"
+  "commit": "ed12243",
+  "builtAt": "2026-10-02T04:28:17.608Z"
 }

package/dist/index.d.ts

@@ -90,6 +90,12 @@ export interface SearchOptions {
      * ANDed with `filter`.
      */
     scope?: DocumentFilter;
+    /** Past this many ms, answer in RRF order instead of waiting for the reranker (unset or 0 = wait) */
+    rerankDeadlineMs?: number;
+    /** Past this many ms, search the original query only instead of waiting for expansion (unset or 0 = wait) */
+    expandDeadlineMs?: number;
+    /** Progress callbacks for expansion, embedding and reranking */
+    hooks?: SearchHooks;
 }
 /**
  * Options for searchLex() — BM25 keyword search.

package/dist/index.js

@@ -122,6 +122,8 @@ export async function createStore(options) {
                     skipRerank,
                     chunkStrategy: opts.chunkStrategy,
                     scope: opts.scope,
+                    rerankDeadlineMs: opts.rerankDeadlineMs,
+                    hooks: opts.hooks,
                 });
             }
             // Simple query string — use hybridQuery (expand + search + rerank)
@@ -137,6 +139,9 @@ export async function createStore(options) {
                 skipRerank,
                 chunkStrategy: opts.chunkStrategy,
                 scope: opts.scope,
+                rerankDeadlineMs: opts.rerankDeadlineMs,
+                expandDeadlineMs: opts.expandDeadlineMs,
+                hooks: opts.hooks,
             });
         },
         searchLex: async (q, opts) => {

package/dist/llm.d.ts

@@ -122,6 +122,8 @@ export type RerankOptions = {
     model?: string;
     /** Per-call doc token cap; overrides QMD_RERANK_MAX_DOC_TOKENS, never raises the context budget. */
     maxDocTokens?: number;
+    /** Called once the rerank model and contexts are loaded, before any scoring (ko-qmd: deadlines start here). */
+    onModelReady?: () => void;
 };
 /**
  * Options for LLM sessions
@@ -143,6 +145,7 @@ export interface ILLMSession {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        onModelReady?: () => void;
     }): Promise<Queryable[]>;
     rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult>;
     /** Whether this session is still valid (not released or aborted) */
@@ -257,6 +260,7 @@ export interface LLM {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        onModelReady?: () => void;
     }): Promise<Queryable[]>;
     /**
      * Rerank documents by relevance to a query
@@ -483,6 +487,7 @@ export declare class LlamaCpp implements LLM {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        onModelReady?: () => void;
     }): Promise<Queryable[]>;
     private static readonly RERANK_TEMPLATE_OVERHEAD;
     private static readonly RERANK_TARGET_DOCS_PER_CONTEXT;

package/dist/llm.js

@@ -1320,6 +1320,7 @@ export class LlamaCpp {
         this.touchActivity();
         const llama = await this.ensureLlama();
         await this.ensureGenerateModel();
+        options.onModelReady?.();
         const includeLexical = options.includeLexical ?? true;
         const context = options.context;
         // The expansion prompt consumes ONLY the query text. Caller intent is
@@ -1399,6 +1400,7 @@ export class LlamaCpp {
         // Ping activity at start to keep models alive during this operation
         this.touchActivity();
         const contexts = await this.ensureRerankContexts();
+        options.onModelReady?.();
         if (contexts.length === 0) {
             return {
                 results: documents.map((d) => ({ ...d, score: 0.5, index: 0 })),

package/dist/mcp/daemon-health.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ko-qmd: periodic health line for the HTTP daemon's log.
+ *
+ * One daemon ran ten days and died with "Reached heap limit" after its heap
+ * crept to 3.8 GB under nothing but idle discover/cancelled traffic. A line an
+ * hour of heap, rss and open `subscriptions/listen` streams gives the slope of
+ * that growth and whether it tracks the listen count.
+ */
+export type DaemonRequestCounts = {
+    /** `subscriptions/listen` requests whose handler is still awaiting the response body — not open sockets */
+    listens: number;
+    /** the same for every /mcp request, listens included */
+    inflight: number;
+};
+export declare function formatDaemonHealthLine(memory: Pick<NodeJS.MemoryUsage, "heapUsed" | "heapTotal" | "rss">, counts: DaemonRequestCounts, uptimeMs: number): string;
+/** QMD_HEALTH_LOG_INTERVAL_MS: 0 = off, a positive integer up to 2^31-1 = that many ms, anything else = one hour. */
+export declare function resolveHealthLogIntervalMs(envValue?: string | undefined): number;

package/dist/mcp/daemon-health.js

@@ -0,0 +1,24 @@
+/**
+ * ko-qmd: periodic health line for the HTTP daemon's log.
+ *
+ * One daemon ran ten days and died with "Reached heap limit" after its heap
+ * crept to 3.8 GB under nothing but idle discover/cancelled traffic. A line an
+ * hour of heap, rss and open `subscriptions/listen` streams gives the slope of
+ * that growth and whether it tracks the listen count.
+ */
+const MB = 2 ** 20;
+const DEFAULT_INTERVAL_MS = 3_600_000;
+export function formatDaemonHealthLine(memory, counts, uptimeMs) {
+    const mb = (bytes) => `${Math.round(bytes / MB)}MB`;
+    return `health heap_used=${mb(memory.heapUsed)} heap_total=${mb(memory.heapTotal)} rss=${mb(memory.rss)}`
+        + ` listens=${counts.listens} mcp_inflight=${counts.inflight} uptime=${(uptimeMs / 3_600_000).toFixed(1)}h`;
+}
+/** Node clamps a longer setInterval delay to 1 ms, which would flood the log. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/** QMD_HEALTH_LOG_INTERVAL_MS: 0 = off, a positive integer up to 2^31-1 = that many ms, anything else = one hour. */
+export function resolveHealthLogIntervalMs(envValue = process.env.QMD_HEALTH_LOG_INTERVAL_MS) {
+    if (envValue === undefined || !/^\d+$/.test(envValue))
+        return DEFAULT_INTERVAL_MS;
+    const ms = Number(envValue);
+    return ms <= MAX_TIMER_MS ? ms : DEFAULT_INTERVAL_MS;
+}

package/dist/mcp/server.d.ts

@@ -7,6 +7,7 @@
  * Speaks MCP spec 2026-07-28 (stateless, no initialize handshake) and dual-speaks
  * 2025-era clients via the official SDK entries (`serveStdio` / `createMcpHandler`).
  */
+export declare function resolveDeadlineMs(envValue: string | undefined, fallback: number): number;
 export type McpStartupOptions = {
     dbPath?: string;
 };

package/dist/mcp/server.js

@@ -19,7 +19,8 @@ import { createStore, extractSnippet, addLineNumbers, getDefaultDbPath, DEFAULT_
 import { getConfigPath } from "../collections.js";
 import { enableProductionMode } from "../store.js";
 import { checkRequestOrigin, resolveOriginGuard } from "./origin-guard.js";
-import { entryFromMcp, entryFromRest, logQuery, queryLogStatus } from "../query-log.js";
+import { entryFromMcp, entryFromRest, isoWithOffset, logQuery, queryLogStatus } from "../query-log.js";
+import { formatDaemonHealthLine, resolveHealthLogIntervalMs } from "./daemon-health.js";
 import { createStoreIndexRefresher } from "../refresh.js";
 import { buildDocumentFilter, describeFilter } from "../filters.js";
 import { countFilteredDocuments } from "../store.js";
@@ -95,6 +96,63 @@ function getPackageVersion() {
  * its own last pass are what stop every query from walking the collection again.
  */
 const refreshers = new WeakMap();
+/**
+ * ko-qmd: per-stage milliseconds for the query log. The hooks fill `stages` as
+ * the search runs; the caller adds `refresh` and `serialize` around it. A stage
+ * past its deadline lands in `timeouts`, with the ms it was waited on.
+ */
+function stageTimer() {
+    const stages = {};
+    const timeouts = [];
+    return {
+        stages,
+        timeouts,
+        hooks: {
+            // A stage skipped outright (an abandoned call still running) gets no ms: absent, never 0.
+            onDeadline: (stage, ms) => { if (ms !== undefined)
+                stages[stage] = ms; timeouts.push(stage); },
+            onModelLoad: (_stage, ms) => { stages.load = (stages.load ?? 0) + ms; },
+            // An empty list means expansion was skipped (pre-typed searches, Hangul, strong BM25 signal)
+            // or the model returned nothing; either way there are no expanded queries to account for.
+            onExpand: (_query, expanded, ms) => { if (expanded.length > 0)
+                stages.expand = ms; },
+            onFtsDone: (ms) => { stages.fts = ms; },
+            onEmbedDone: (ms) => { stages.embed = ms; },
+            onVecDone: (ms) => { stages.vec = ms; },
+            onChunkDone: (ms) => { stages.chunk = ms; },
+            onRerankDone: (ms) => { stages.rerank = ms; },
+        },
+    };
+}
+/**
+ * ko-qmd: how long the daemon waits for query expansion and for the reranker before answering
+ * without them. QMD_EXPAND_DEADLINE_MS / QMD_RERANK_DEADLINE_MS: 0 = wait, a positive integer =
+ * that many ms, anything else = the default. One MCP query once took 85 s.
+ */
+const DEFAULT_EXPAND_DEADLINE_MS = 5_000;
+const DEFAULT_RERANK_DEADLINE_MS = 10_000;
+export function resolveDeadlineMs(envValue, fallback) {
+    return envValue !== undefined && /^\d+$/.test(envValue) ? Number(envValue) : fallback;
+}
+function searchDeadlines() {
+    return {
+        expandDeadlineMs: resolveDeadlineMs(process.env.QMD_EXPAND_DEADLINE_MS, DEFAULT_EXPAND_DEADLINE_MS),
+        rerankDeadlineMs: resolveDeadlineMs(process.env.QMD_RERANK_DEADLINE_MS, DEFAULT_RERANK_DEADLINE_MS),
+    };
+}
+/** `timeouts` for a search response — absent when every stage finished in time. */
+function timeoutField(timeouts) {
+    return timeouts.length > 0 ? { timeouts } : {};
+}
+/** A line telling an agent its results were not reranked or not expanded, so it does not read scores as confident. */
+function describeTimeouts(timeouts) {
+    if (timeouts.length === 0)
+        return "";
+    const parts = timeouts.map(t => t === "rerank"
+        ? "the reranker timed out, so results are in retrieval order and scores are 1/rank"
+        : "query expansion timed out, so only the original query was searched");
+    return `\n\nNote: ${parts.join("; ")}.`;
+}
 /**
  * Bring the text index up to date for the collections a query is about to search. Never
  * throws — a failed refresh is logged and the query runs against the index as it was.
@@ -398,7 +456,10 @@ Intent-aware lex (C++ performance, not sports):
         const searchOptions = query
             ? { query }
             : { queries: (searches ?? []).map(s => ({ type: s.type, query: s.query })) };
+        const timer = stageTimer();
+        const refreshStart = Date.now();
         await refreshBeforeQuery(store, effectiveCollections);
+        timer.stages.refresh = Date.now() - refreshStart;
         const results = await store.search({
             ...searchOptions,
             collections: effectiveCollections.length > 0 ? effectiveCollections : undefined,
@@ -411,7 +472,10 @@ Intent-aware lex (C++ performance, not sports):
             explain: rerank === false,
             intent,
             scope,
+            ...searchDeadlines(),
+            hooks: timer.hooks,
         });
+        const serializeStart = Date.now();
         // Use the plain query, or the first lex/vec sub-query, for snippet extraction
         const primaryQuery = query
             || searches?.find(s => s.type === 'lex')?.query
@@ -432,7 +496,9 @@ Intent-aware lex (C++ performance, not sports):
                 snippet: addLineNumbers(snippet, line),
             };
         });
-        // ko-qmd: opt-in query log (QMD_QUERY_LOG), HTTP transport only.
+        // ko-qmd: opt-in query log (QMD_QUERY_LOG), HTTP transport only. `serialize` here is snippet
+        // extraction only — the SDK writes the response after this handler returns.
+        timer.stages.serialize = Date.now() - serializeStart;
         if (httpHeaders) {
             logQuery(entryFromMcp({
                 headers: httpHeaders,
@@ -443,6 +509,8 @@ Intent-aware lex (C++ performance, not sports):
                 rerank,
                 results: filtered,
                 ms: Date.now() - startedAt,
+                stages: timer.stages,
+                timeouts: timer.timeouts,
             }), store);
         }
         return {
@@ -450,9 +518,9 @@ Intent-aware lex (C++ performance, not sports):
                     type: "text",
                     text: filtered.length === 0 && scope
                         ? describeEmptyFilteredSearch(store, scope, effectiveCollections)
-                        : formatSearchSummary(filtered, primaryQuery),
+                        : formatSearchSummary(filtered, primaryQuery) + describeTimeouts(timer.timeouts),
                 }],
-            structuredContent: { results: filtered },
+            structuredContent: { results: filtered, ...timeoutField(timer.timeouts) },
         };
     }));
     // ---------------------------------------------------------------------------
@@ -894,7 +962,7 @@ export async function startMcpHttpServer(port, options = {}) {
     const quiet = options?.quiet ?? false;
     /** Format timestamp for request logging */
     function ts() {
-        return new Date().toISOString().slice(11, 23); // HH:mm:ss.SSS
+        return isoWithOffset(new Date()); // ko-qmd: dated local time, so a log line can be matched to a query-log row
     }
     /** Extract a human-readable label from a JSON-RPC body */
     function describeRequest(body) {
@@ -921,6 +989,13 @@ export async function startMcpHttpServer(port, options = {}) {
         if (!quiet)
             console.error(msg);
     }
+    // ko-qmd: /mcp requests whose response has not ended — a `subscriptions/listen` stays open for
+    // as long as its client keeps it, so these are what the hourly health line counts.
+    const openMcp = { listens: 0, inflight: 0 };
+    const healthIntervalMs = resolveHealthLogIntervalMs();
+    const healthTimer = healthIntervalMs > 0
+        ? setInterval(() => log(`${ts()} ${formatDaemonHealthLine(process.memoryUsage(), openMcp, Date.now() - startTime)}`), healthIntervalMs).unref()
+        : null;
     function nodeHeadersToWeb(nodeReq) {
         const headers = new Headers();
         for (const [k, v] of Object.entries(nodeReq.headers)) {
@@ -1037,7 +1112,10 @@ export async function startMcpHttpServer(port, options = {}) {
                     nodeRes.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
                     return;
                 }
+                const timer = stageTimer();
+                const refreshStart = Date.now();
                 await refreshBeforeQuery(store, effectiveCollections);
+                timer.stages.refresh = Date.now() - refreshStart;
                 const rerank = typeof params.rerank === "boolean" ? params.rerank : undefined;
                 const results = await store.search({
                     queries,
@@ -1052,7 +1130,10 @@ export async function startMcpHttpServer(port, options = {}) {
                     // rerank:false scores are 1/rank; explain carries the raw backend scores.
                     explain: rerank === false,
                     scope: restScope,
+                    ...searchDeadlines(),
+                    hooks: timer.hooks,
                 });
+                const serializeStart = Date.now();
                 // Use first lex or vec query for snippet extraction
                 const primaryQuery = searches.find((s) => s.type === 'lex')?.query
                     || searches.find((s) => s.type === 'vec')?.query
@@ -1072,9 +1153,10 @@ export async function startMcpHttpServer(port, options = {}) {
                     };
                 });
                 nodeRes.writeHead(200, { "Content-Type": "application/json" });
-                nodeRes.end(JSON.stringify({ results: formatted }));
+                nodeRes.end(JSON.stringify({ results: formatted, ...timeoutField(timer.timeouts) }));
+                timer.stages.serialize = Date.now() - serializeStart;
                 // ko-qmd: opt-in query log (QMD_QUERY_LOG), written after the response.
-                logQuery(entryFromRest({ path: pathname, headers: nodeReq.headers, searches: queries, params, collections: effectiveCollections, results: formatted, ms: Date.now() - reqStart }), store);
+                logQuery(entryFromRest({ path: pathname, headers: nodeReq.headers, searches: queries, params, collections: effectiveCollections, results: formatted, ms: Date.now() - reqStart, stages: timer.stages, timeouts: timer.timeouts }), store);
                 log(`${ts()} POST /query ${params.searches.length} queries (${Date.now() - reqStart}ms)`);
                 return;
             }
@@ -1101,9 +1183,20 @@ export async function startMcpHttpServer(port, options = {}) {
                     headers: nodeHeadersToWeb(nodeReq),
                     ...(rawBody !== undefined ? { body: rawBody } : {}),
                 });
-                const response = await mcpHandler.fetch(request, parsedBody !== undefined ? { parsedBody } : undefined);
-                nodeRes.writeHead(response.status, Object.fromEntries(response.headers));
-                nodeRes.end(Buffer.from(await response.arrayBuffer()));
+                const isListen = label === "subscriptions/listen";
+                openMcp.inflight++;
+                if (isListen)
+                    openMcp.listens++;
+                try {
+                    const response = await mcpHandler.fetch(request, parsedBody !== undefined ? { parsedBody } : undefined);
+                    nodeRes.writeHead(response.status, Object.fromEntries(response.headers));
+                    nodeRes.end(Buffer.from(await response.arrayBuffer()));
+                }
+                finally {
+                    openMcp.inflight--;
+                    if (isListen)
+                        openMcp.listens--;
+                }
                 log(`${ts()} ${nodeReq.method} /mcp ${label} (${Date.now() - reqStart}ms)`);
                 return;
             }
@@ -1126,6 +1219,8 @@ export async function startMcpHttpServer(port, options = {}) {
         if (stopping)
             return;
         stopping = true;
+        if (healthTimer)
+            clearInterval(healthTimer);
         await mcpHandler.close();
         httpServer.close();
         await store.close();

package/dist/query-log.d.ts

@@ -36,6 +36,27 @@ export type QueryLogResult = {
     vec_score?: number;
     fts_score?: number;
 };
+/**
+ * Milliseconds each stage of one search took. A stage that did not run is
+ * absent, never 0: `refresh` is the pre-query re-index check, `expand` the LLM
+ * query expansion, `fts` the BM25 lookups, `embed` the query embeddings, `vec`
+ * the sqlite-vec lookups, `chunk` splitting candidates to pick each one's best
+ * chunk, `rerank` the LLM reranker, and `serialize` snippet extraction (plus
+ * writing the response on REST). RRF fusion and metadata lookups are not a
+ * stage, so the stages need not sum to `ms`.
+ */
+export type QueryLogTimeout = "expand" | "rerank";
+export type QueryLogStages = {
+    refresh?: number;
+    load?: number;
+    expand?: number;
+    fts?: number;
+    embed?: number;
+    vec?: number;
+    chunk?: number;
+    rerank?: number;
+    serialize?: number;
+};
 export type QueryLogEntry = {
     via: "rest" | "mcp";
     tool: string;
@@ -50,6 +71,9 @@ export type QueryLogEntry = {
     rerank: boolean | null;
     results: QueryLogResult[];
     ms: number;
+    stages?: QueryLogStages;
+    /** Stages that ran past their deadline; the search went on without them */
+    timeouts?: QueryLogTimeout[];
     /** Injectable clock for tests; defaults to the time of the call. */
     now?: Date;
 };
@@ -61,6 +85,8 @@ export type QueryLogStatus = {
 };
 /** Path of the log file for the local month containing `date`. */
 export declare const queryLogPath: (date?: Date) => string;
+/** ISO-8601 in local time with the UTC offset, e.g. 2026-09-17T16:05:03.123+09:00. */
+export declare const isoWithOffset: (date: Date) => string;
 /**
  * Queue one row. Returns immediately; the write happens after the response.
  * No-op unless the flag is on and the request did not ask to be skipped.
@@ -106,6 +132,8 @@ export declare const entryFromRest: (input: {
     collections: string[];
     results: QueryLogResult[];
     ms: number;
+    stages?: QueryLogStages;
+    timeouts?: QueryLogTimeout[];
 }) => QueryLogEntry;
 /** Map an MCP `query` tool call. Only the HTTP transport supplies headers. */
 export declare const entryFromMcp: (input: {
@@ -121,6 +149,8 @@ export declare const entryFromMcp: (input: {
     rerank: boolean;
     results: QueryLogResult[];
     ms: number;
+    stages?: QueryLogStages;
+    timeouts?: QueryLogTimeout[];
 }) => QueryLogEntry;
 export declare const _resetQueryLogForTesting: () => void;
 export {};

package/dist/query-log.js

@@ -36,7 +36,7 @@ const pad2 = (n) => String(n).padStart(2, "0");
 /** Path of the log file for the local month containing `date`. */
 export const queryLogPath = (date = new Date()) => join(queryLogDir(), `queries-${date.getFullYear()}-${pad2(date.getMonth() + 1)}.jsonl`);
 /** ISO-8601 in local time with the UTC offset, e.g. 2026-09-17T16:05:03.123+09:00. */
-const isoWithOffset = (date) => {
+export const isoWithOffset = (date) => {
     const offsetMin = -date.getTimezoneOffset();
     const sign = offsetMin >= 0 ? "+" : "-";
     const abs = Math.abs(offsetMin);
@@ -147,7 +147,8 @@ const queueRow = (entry, store) => {
         searches: entry.searches.map(({ type, query }) => ({ type, query })),
         collections: entry.collections,
         limit: entry.limit,
-        rerank: entry.rerank,
+        // A reranker past its deadline answered nothing: the results are in RRF order.
+        rerank: entry.timeouts?.includes("rerank") ? "timeout" : entry.rerank,
         results: entry.results.map((r, i) => ({
             file: normalizeResultFile(r.file),
             score: r.score,
@@ -156,6 +157,8 @@ const queueRow = (entry, store) => {
             rank: i + 1,
         })),
         ms: entry.ms,
+        ...(entry.stages && { stages: entry.stages }),
+        ...(entry.timeouts && entry.timeouts.length > 0 && { timeouts: entry.timeouts }),
         client: {
             tag: clip(readHeader(entry.headers, "x-qmd-tag"), TAG_MAX),
             qid: clip(readHeader(entry.headers, "x-qmd-qid"), QID_MAX),
@@ -220,6 +223,8 @@ export const entryFromRest = (input) => ({
     rerank: typeof input.params.rerank === "boolean" ? input.params.rerank : null,
     results: input.results,
     ms: input.ms,
+    stages: input.stages,
+    timeouts: input.timeouts,
 });
 /** Map an MCP `query` tool call. Only the HTTP transport supplies headers. */
 export const entryFromMcp = (input) => ({
@@ -232,6 +237,8 @@ export const entryFromMcp = (input) => ({
     rerank: input.rerank,
     results: input.results,
     ms: input.ms,
+    stages: input.stages,
+    timeouts: input.timeouts,
 });
 export const _resetQueryLogForTesting = () => {
     writeChain = Promise.resolve();

package/dist/rerank-input.d.ts

@@ -22,9 +22,22 @@ export declare const INTENT_WEIGHT_CHUNK = 1;
 /** The reranker's query: intent, a blank line, then the query; the query alone without intent. */
 export declare const formatRerankQuery: (query: string, intent?: string) => string;
 /**
- * Index of the chunk to rerank: the one containing the most query words longer than two
- * characters with no Hangul (two points each) plus query Hangul syllable bigrams, each intent word adding one point (half a non-Hangul query word, as before bigrams).
- * Case-insensitive substring match; a tie keeps the earlier chunk, and no match picks the first.
+ * Head start of the first chunk (title, summary); a later chunk must out-score it by more than this,
+ * which a typical short query cannot do, so its first chunk is always sent.
+ */
+export declare const FIRST_CHUNK_HEAD_START = 16;
+/** The head start when intent is given: halved, so intent words can still steer selection to a later chunk. */
+export declare const FIRST_CHUNK_HEAD_START_WITH_INTENT = 8;
+/**
+ * Scorer for one chunk's text against `query`: two points per query word longer than two characters
+ * with no Hangul, one per query Hangul syllable bigram, and one per intent word (half a non-Hangul
+ * query word). Case-insensitive substring match.
+ */
+export declare const rerankChunkScorer: (query: string, intentTerms: string[]) => ((text: string) => number);
+/**
+ * Index of the chunk to rerank: the highest `rerankChunkScorer` score, with the first chunk starting
+ * FIRST_CHUNK_HEAD_START ahead (FIRST_CHUNK_HEAD_START_WITH_INTENT with intent), so the note's lead is
+ * sent unless a later chunk matches far more of the query. A tie keeps the earlier chunk.
  */
 export declare const selectRerankChunk: (chunks: RerankChunk[], query: string, intentTerms: string[]) => number;
 /** The document text sent for one candidate: the selected chunk, led by the note title when the chunk lacks it. */

package/dist/rerank-input.js

@@ -16,26 +16,42 @@ export const formatRerankQuery = (query, intent) => intent ? `${intent}\n\n${que
  */
 const hangulBigrams = (text) => (text.match(/[가-힣]{3,}/g) ?? []).flatMap((run) => Array.from({ length: run.length - 1 }, (_, i) => run.slice(i, i + 2)));
 /**
- * Index of the chunk to rerank: the one containing the most query words longer than two
- * characters with no Hangul (two points each) plus query Hangul syllable bigrams, each intent word adding one point (half a non-Hangul query word, as before bigrams).
- * Case-insensitive substring match; a tie keeps the earlier chunk, and no match picks the first.
+ * Head start of the first chunk (title, summary); a later chunk must out-score it by more than this,
+ * which a typical short query cannot do, so its first chunk is always sent.
  */
-export const selectRerankChunk = (chunks, query, intentTerms) => {
+export const FIRST_CHUNK_HEAD_START = 16;
+/** The head start when intent is given: halved, so intent words can still steer selection to a later chunk. */
+export const FIRST_CHUNK_HEAD_START_WITH_INTENT = 8;
+/**
+ * Scorer for one chunk's text against `query`: two points per query word longer than two characters
+ * with no Hangul, one per query Hangul syllable bigram, and one per intent word (half a non-Hangul
+ * query word). Case-insensitive substring match.
+ */
+export const rerankChunkScorer = (query, intentTerms) => {
     const queryLower = query.toLowerCase();
     const queryTerms = queryLower.split(/\s+/).filter((t) => t.length > 2 && !/[가-힣]/.test(t));
     const bigrams = hangulBigrams(queryLower);
+    return (text) => {
+        const lower = text.toLowerCase();
+        return queryTerms.reduce((acc, term) => acc + (lower.includes(term) ? 2 : 0), 0)
+            + bigrams.reduce((acc, bg) => acc + (lower.includes(bg) ? 1 : 0), 0)
+            + intentTerms.reduce((acc, term) => acc + (lower.includes(term) ? INTENT_WEIGHT_CHUNK : 0), 0);
+    };
+};
+/**
+ * Index of the chunk to rerank: the highest `rerankChunkScorer` score, with the first chunk starting
+ * FIRST_CHUNK_HEAD_START ahead (FIRST_CHUNK_HEAD_START_WITH_INTENT with intent), so the note's lead is
+ * sent unless a later chunk matches far more of the query. A tie keeps the earlier chunk.
+ */
+export const selectRerankChunk = (chunks, query, intentTerms) => {
+    const score = rerankChunkScorer(query, intentTerms);
+    const headStart = intentTerms.length === 0 ? FIRST_CHUNK_HEAD_START : FIRST_CHUNK_HEAD_START_WITH_INTENT;
     let bestIdx = 0;
     let bestScore = -1;
     for (let i = 0; i < chunks.length; i++) {
-        const chunkLower = chunks[i].text.toLowerCase();
-        let score = queryTerms.reduce((acc, term) => acc + (chunkLower.includes(term) ? 2 : 0), 0);
-        score += bigrams.reduce((acc, bg) => acc + (chunkLower.includes(bg) ? 1 : 0), 0);
-        for (const term of intentTerms) {
-            if (chunkLower.includes(term))
-                score += INTENT_WEIGHT_CHUNK;
-        }
-        if (score > bestScore) {
-            bestScore = score;
+        const s = score(chunks[i].text) + (i === 0 ? headStart : 0);
+        if (s > bestScore) {
+            bestScore = s;
             bestIdx = i;
         }
     }

package/dist/store.d.ts

@@ -276,7 +276,10 @@ export type Store = {
     toVirtualPath: (absolutePath: string) => string | null;
     searchFTS: (query: string, limit?: number, collectionName?: string | readonly string[], filter?: MetadataFilter, scope?: DocumentFilter) => SearchResult[];
     searchVec: (query: string, model: string, limit?: number, collectionName?: string | readonly string[], session?: ILLMSession, precomputedEmbedding?: number[], filter?: MetadataFilter, scope?: DocumentFilter) => Promise<SearchResult[]>;
-    expandQuery: (query: string, model?: string) => Promise<ExpandedQuery[]>;
+    /** `onModelReady` fires once the generation model is loaded (not at all on a cache hit). */
+    expandQuery: (query: string, model?: string, options?: {
+        onModelReady?: () => void;
+    }) => Promise<ExpandedQuery[]>;
     /** Drop the cached expansion for a query so the next call regenerates. */
     invalidateExpansionCache: (query: string) => void;
     rerank: (query: string, documents: {
@@ -886,7 +889,9 @@ export declare function clearAllEmbeddings(db: Database, collection?: string): v
  * vec0 virtual tables silently ignore the OR REPLACE conflict clause.
  */
 export declare function insertEmbedding(db: Database, hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string, totalChunks?: number, fingerprint?: string): void;
-export declare function expandQuery(query: string, model: string | undefined, db: Database, llmOverride?: LlamaCpp): Promise<ExpandedQuery[]>;
+export declare function expandQuery(query: string, model: string | undefined, db: Database, llmOverride?: LlamaCpp, options?: {
+    onModelReady?: () => void;
+}): Promise<ExpandedQuery[]>;
 /**
  * Delete the cached expansion for a query. hybridQuery() calls this when an
  * expansion's sub-queries all came back empty — left in place, the dud entry
@@ -897,6 +902,8 @@ export declare function deleteExpansionCacheEntry(db: Database, query: string, m
 export type StoreRerankOptions = {
     /** Doc token cap for this request; overrides QMD_RERANK_MAX_DOC_TOKENS. */
     maxDocTokens?: number;
+    /** Called once the rerank model is loaded (not at all when every chunk is cached). */
+    onModelReady?: () => void;
 };
 export declare function rerank(query: string, documents: {
     file: string;
@@ -1007,6 +1014,20 @@ export interface SearchHooks {
     onEmbedStart?: (count: number) => void;
     /** Embedding complete */
     onEmbedDone?: (elapsedMs: number) => void;
+    /** Every BM25 lookup of the search finished; elapsedMs is their total */
+    onFtsDone?: (elapsedMs: number) => void;
+    /** Every sqlite-vec lookup of the search finished (embedding excluded); elapsedMs is their total */
+    onVecDone?: (elapsedMs: number) => void;
+    /** Candidates were chunked and each one's best chunk picked (runs with or without rerank) */
+    onChunkDone?: (elapsedMs: number) => void;
+    /**
+     * A stage went without its LLM (expansion: original query only, rerank: RRF order). elapsedMs is
+     * how long it was waited on after its model loaded; undefined when it was skipped outright because
+     * an earlier call of that stage, abandoned at its deadline, is still running.
+     */
+    onDeadline?: (stage: DeadlineStage, elapsedMs?: number) => void;
+    /** The stage's model finished loading (cold start or reload after idle unload); elapsedMs is the wait */
+    onModelLoad?: (stage: DeadlineStage, elapsedMs: number) => void;
     /** Reranking is about to start */
     onRerankStart?: (chunkCount: number) => void;
     /** Reranking finished */
@@ -1022,6 +1043,8 @@ export interface HybridQueryOptions {
     explain?: boolean;
     intent?: string;
     skipRerank?: boolean;
+    rerankDeadlineMs?: number;
+    expandDeadlineMs?: number;
     chunkStrategy?: ChunkStrategy;
     scope?: DocumentFilter;
     hooks?: SearchHooks;
@@ -1088,6 +1111,7 @@ export declare function getStructuredRrfWeights(rankedListMeta: RankedListMeta[]
  * decimals, which is what "the reranker cannot move rank 1" looks like as a number.
  */
 export declare function blendRerankScore(rrfRank: number, rerankScore: number, candidateLimit: number): number;
+export type DeadlineStage = "expand" | "rerank";
 /**
  * Hybrid search: BM25 + vector + query expansion + RRF + chunked reranking.
  *
@@ -1147,6 +1171,7 @@ export interface StructuredSearchOptions {
     intent?: string;
     /** Skip LLM reranking, use only RRF scores */
     skipRerank?: boolean;
+    rerankDeadlineMs?: number;
     chunkStrategy?: ChunkStrategy;
     /** Narrow the corpus by path glob and modified_at before anything is ranked */
     scope?: DocumentFilter;

package/dist/store.js

@@ -1826,7 +1826,7 @@ export function createStore(dbPath) {
         searchFTS: (query, limit, collectionName, filter, scope) => searchFTS(db, query, limit, collectionName, filter, scope),
         searchVec: (query, model, limit, collectionName, session, precomputedEmbedding, filter, scope) => searchVec(db, query, model, limit, collectionName, session, precomputedEmbedding, getLlm(store), filter, scope),
         // Query expansion & reranking
-        expandQuery: (query, model) => expandQuery(query, model ?? store.llm?.generateModelName ?? DEFAULT_QUERY_MODEL, db, store.llm),
+        expandQuery: (query, model, options) => expandQuery(query, model ?? store.llm?.generateModelName ?? DEFAULT_QUERY_MODEL, db, store.llm, options),
         invalidateExpansionCache: (query) => deleteExpansionCacheEntry(db, query, store.llm?.generateModelName ?? DEFAULT_QUERY_MODEL),
         rerank: (query, documents, model, intent, options) => {
             // Cache keys must use the resolved rerank model (store.llm or the global
@@ -3782,7 +3782,7 @@ function removeIncompleteEmbeddings(db, expectedChunksByHash, model) {
 // =============================================================================
 // Query expansion
 // =============================================================================
-export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db, llmOverride) {
+export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db, llmOverride, options = {}) {
     // Check cache first — stored as JSON preserving types. Intent is
     // deliberately absent from both the cache key and the generation call:
     // feeding caller intent to the expansion model contaminates sub-queries
@@ -3810,7 +3810,7 @@ export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db, llmOve
     }
     const llm = llmOverride ?? getDefaultLlamaCpp();
     // Note: LlamaCpp uses hardcoded model, model parameter is ignored
-    const results = await llm.expandQuery(query);
+    const results = await llm.expandQuery(query, { onModelReady: options.onModelReady });
     // Map Queryable[] → ExpandedQuery[] (same shape, decoupled from llm.ts internals).
     // Filter out entries that duplicate the original query text.
     const expanded = results
@@ -3865,6 +3865,7 @@ export async function rerank(query, documents, model = DEFAULT_RERANK_MODEL, db,
         const rerankResult = await llm.rerank(rerankQuery, uncachedDocs, {
             model: cacheModel,
             ...(requestMaxDocTokens ? { maxDocTokens: requestMaxDocTokens } : {}),
+            onModelReady: options.onModelReady,
         });
         // Cache results by chunk text so identical chunks across files are scored once.
         // A "fallback" result (no rerank context could be created) is a flat 0.5, not a score:
@@ -4637,6 +4638,90 @@ export function blendRerankScore(rrfRank, rerankScore, candidateLimit) {
     const positionScore = 1 - (rrfRank - 1) / candidateLimit;
     return (1 - POSITION_TIEBREAK_WEIGHT) * rerankScore + POSITION_TIEBREAK_WEIGHT * positionScore;
 }
+const TIMED_OUT = Symbol("timed out");
+/**
+ * The promise's value, or TIMED_OUT once `deadlineMs` passes (unset or 0 = no deadline). The
+ * promise is not cancelled: a late rerank still lands in the rerank cache for the next query.
+ */
+async function withDeadline(promise, deadlineMs) {
+    if (!deadlineMs || deadlineMs <= 0)
+        return promise;
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(TIMED_OUT), deadlineMs);
+    });
+    try {
+        return await Promise.race([promise, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * LLM calls abandoned at their deadline and still running, per store and stage. While one runs, the
+ * next call of that stage would only queue behind it on the same model and time out too, so it is
+ * skipped instead: this caps the backlog at one abandoned call per stage instead of one per query.
+ */
+const abandoned = new WeakMap();
+/**
+ * Run one LLM stage under a deadline. The clock starts once the stage's model is loaded
+ * (`onModelReady`): the deadline bounds computation, not a cold load, which is reported through
+ * `onModelLoad`. TIMED_OUT when the deadline passes, or at once while an earlier abandoned call of
+ * the stage is still running. Unset or 0 deadline = plain await.
+ */
+async function runWithDeadline(store, stage, deadlineMs, hooks, start) {
+    const started = Date.now();
+    let loadedAt;
+    const reportLoad = () => { if (loadedAt !== undefined)
+        hooks?.onModelLoad?.(stage, loadedAt - started); };
+    if (!deadlineMs || deadlineMs <= 0) {
+        const value = await start(() => { loadedAt = Date.now(); });
+        reportLoad();
+        return value;
+    }
+    const byStage = abandoned.get(store) ?? { expand: { running: 0, warned: false }, rerank: { running: 0, warned: false } };
+    abandoned.set(store, byStage);
+    const state = byStage[stage];
+    if (state.running > 0) {
+        if (!state.warned) {
+            state.warned = true;
+            process.stderr.write(`qmd: a ${stage} abandoned at its deadline is still running — answering without ${stage} until it finishes\n`);
+        }
+        hooks?.onDeadline?.(stage);
+        return TIMED_OUT;
+    }
+    let markReady = () => { };
+    const ready = new Promise((resolve) => { markReady = () => { loadedAt = Date.now(); resolve(); }; });
+    const pending = start(markReady);
+    // Wait out the model load with no deadline; a cache hit or a fast call may finish before it fires.
+    const finishedFirst = await Promise.race([ready.then(() => false), pending.then(() => true, () => true)]);
+    reportLoad();
+    if (finishedFirst)
+        return pending;
+    const result = await withDeadline(pending, deadlineMs);
+    if (result === TIMED_OUT) {
+        state.running++;
+        const settle = () => {
+            state.running--;
+            if (state.running === 0)
+                state.warned = false;
+        };
+        pending.then(settle, settle);
+        hooks?.onDeadline?.(stage, Date.now() - (loadedAt ?? started));
+    }
+    return result;
+}
+/** Rerank `chunks`, or null when the reranker misses `deadlineMs` (the caller then answers in RRF order). */
+async function rerankWithDeadline(store, query, chunks, intent, options) {
+    const hooks = options?.hooks;
+    hooks?.onRerankStart?.(chunks.length);
+    const start = Date.now();
+    const reranked = await runWithDeadline(store, "rerank", options?.rerankDeadlineMs, hooks, (onModelReady) => store.rerank(query, chunks, undefined, intent, { maxDocTokens: options?.rerankMaxDocTokens, onModelReady }));
+    if (reranked === TIMED_OUT)
+        return null;
+    hooks?.onRerankDone?.(Date.now() - start);
+    return reranked;
+}
 /**
  * Cut each candidate into chunks and pick the one to rerank (`selectRerankChunk`). A document
  * with no chunks is left out of the map.
@@ -4697,7 +4782,9 @@ export async function hybridQuery(store, rawQuery, options) {
     // Pass collection and metadata filter directly into FTS query (filter at
     // SQL level, not post-hoc) — the strong-signal decision must be based only
     // on eligible documents.
+    let ftsStart = Date.now();
     const initialFts = store.searchFTS(query, 20, collection, filter, scope);
+    let ftsMs = Date.now() - ftsStart;
     const topScore = initialFts[0]?.score ?? 0;
     const secondScore = initialFts[1]?.score ?? 0;
     // ko-qmd: a relaxed match is never a strong signal — it did not match all the words.
@@ -4714,9 +4801,10 @@ export async function hybridQuery(store, rawQuery, options) {
     const skipsExpansion = hasStrongSignal || containsHangul(query);
     hooks?.onExpandStart?.();
     const expandStart = Date.now();
-    const expanded = skipsExpansion
+    const expansion = skipsExpansion
         ? []
-        : await store.expandQuery(query);
+        : await runWithDeadline(store, "expand", options?.expandDeadlineMs, hooks, (onModelReady) => store.expandQuery(query, undefined, { onModelReady }));
+    const expanded = expansion === TIMED_OUT ? [] : expansion;
     hooks?.onExpand?.(query, expanded, Date.now() - expandStart);
     // Seed with initial FTS results (avoid re-running original query FTS)
     if (initialFts.length > 0) {
@@ -4737,6 +4825,7 @@ export async function hybridQuery(store, rawQuery, options) {
     // batch-embed all vector queries in one embedBatch() call, then run
     // sqlite-vec lookups with pre-computed embeddings.
     // 3a: Run FTS for all lex expansions right away (no LLM needed)
+    ftsStart = Date.now();
     for (const q of expanded) {
         if (q.type === 'lex') {
             const ftsResults = store.searchFTS(q.query, 20, collection, filter, scope);
@@ -4754,6 +4843,7 @@ export async function hybridQuery(store, rawQuery, options) {
             }
         }
     }
+    hooks?.onFtsDone?.(ftsMs + Date.now() - ftsStart);
     // 3b: Collect all texts that need vector search (original query + vec/hyde expansions)
     if (hasVectors) {
         const vecQueries = [
@@ -4773,6 +4863,7 @@ export async function hybridQuery(store, rawQuery, options) {
         const embeddings = await llm.embedBatch(textsToEmbed);
         hooks?.onEmbedDone?.(Date.now() - embedStart);
         // Run sqlite-vec lookups with pre-computed embeddings
+        const vecStart = Date.now();
         for (let i = 0; i < vecQueries.length; i++) {
             const embedding = embeddings[i]?.embedding;
             if (!embedding)
@@ -4792,6 +4883,7 @@ export async function hybridQuery(store, rawQuery, options) {
                 });
             }
         }
+        hooks?.onVecDone?.(Date.now() - vecStart);
     }
     // Step 3c: drop a cached expansion whose sub-queries all came back empty —
     // the dud is cached per (query, model), so left in place it deterministically
@@ -4815,8 +4907,14 @@ export async function hybridQuery(store, rawQuery, options) {
         return [];
     // Step 5: Chunk documents, pick best chunk per doc for reranking.
     // Reranking full bodies is O(tokens) — the critical perf lesson that motivated this refactor.
+    const chunkStart = Date.now();
     const docChunkMap = await chunkCandidatesForRerank(candidates, query, intent, options?.chunkStrategy);
-    if (skipRerank) {
+    hooks?.onChunkDone?.(Date.now() - chunkStart);
+    // Step 6: Rerank chunks (NOT full bodies). No reranker, or one past its deadline, means RRF order.
+    const reranked = skipRerank
+        ? null
+        : await rerankWithDeadline(store, query, rerankDocuments(candidates, docChunkMap), intent, options);
+    if (reranked === null) {
         // Skip LLM reranking — return candidates scored by RRF only
         const seenFiles = new Set();
         const rrfResults = candidates
@@ -4862,16 +4960,12 @@ export async function hybridQuery(store, rawQuery, options) {
             seenFiles.add(r.file);
             return true;
         })
-            .filter(r => r.score >= minScore)
+            // minScore is a threshold on blended rerank scores; a deadline fallback's 1/rank scores would
+            // cut a 0.5 threshold to two results, so only a caller that skipped rerank gets it applied here.
+            .filter(r => !skipRerank || r.score >= minScore)
             .slice(0, limit);
         return attachResultMetadata(store.db, rrfResults);
     }
-    // Step 6: Rerank chunks (NOT full bodies)
-    const chunksToRerank = rerankDocuments(candidates, docChunkMap);
-    hooks?.onRerankStart?.(chunksToRerank.length);
-    const rerankStart = Date.now();
-    const reranked = await store.rerank(query, chunksToRerank, undefined, intent, { maxDocTokens: options?.rerankMaxDocTokens });
-    hooks?.onRerankDone?.(Date.now() - rerankStart);
     // Step 7: Blend RRF position score with reranker score
     // Position-aware weights: top retrieval results get more protection from reranker disagreement
     const candidateMap = new Map(candidates.map(c => [c.file, {
@@ -5040,6 +5134,7 @@ export async function structuredSearch(store, rawSearches, options) {
     // Helper to run search across collections (or all if undefined)
     const collectionList = collections ?? [undefined]; // undefined = all collections
     // Step 1: Run FTS for all lex searches (sync, instant)
+    const ftsStart = Date.now();
     for (const search of searches) {
         if (search.type === 'lex') {
             for (const coll of collectionList) {
@@ -5061,6 +5156,8 @@ export async function structuredSearch(store, rawSearches, options) {
             }
         }
     }
+    if (searches.some(s => s.type === 'lex'))
+        hooks?.onFtsDone?.(Date.now() - ftsStart);
     // Step 2: Batch embed and run vector searches for vec/hyde
     if (hasVectors) {
         const vecSearches = searches.filter((s) => s.type === 'vec' || s.type === 'hyde');
@@ -5072,6 +5169,7 @@ export async function structuredSearch(store, rawSearches, options) {
             const embedStart = Date.now();
             const embeddings = await llm.embedBatch(textsToEmbed);
             hooks?.onEmbedDone?.(Date.now() - embedStart);
+            const vecStart = Date.now();
             for (let i = 0; i < vecSearches.length; i++) {
                 const embedding = embeddings[i]?.embedding;
                 if (!embedding)
@@ -5093,6 +5191,7 @@ export async function structuredSearch(store, rawSearches, options) {
                     }
                 }
             }
+            hooks?.onVecDone?.(Date.now() - vecStart);
         }
     }
     if (rankedLists.length === 0)
@@ -5111,8 +5210,14 @@ export async function structuredSearch(store, rawSearches, options) {
     const primaryQuery = searches.find(s => s.type === 'lex')?.query
         || searches.find(s => s.type === 'vec')?.query
         || searches[0]?.query || "";
+    const chunkStart = Date.now();
     const docChunkMap = await chunkCandidatesForRerank(candidates, primaryQuery, intent, options?.chunkStrategy);
-    if (skipRerank) {
+    hooks?.onChunkDone?.(Date.now() - chunkStart);
+    // Step 5: Rerank chunks. No reranker, or one past its deadline, means RRF order.
+    const reranked = skipRerank
+        ? null
+        : await rerankWithDeadline(store, primaryQuery, rerankDocuments(candidates, docChunkMap), intent, options);
+    if (reranked === null) {
         // Skip LLM reranking — return candidates scored by RRF only
         const seenFiles = new Set();
         const rrfResults = candidates
@@ -5158,16 +5263,12 @@ export async function structuredSearch(store, rawSearches, options) {
             seenFiles.add(r.file);
             return true;
         })
-            .filter(r => r.score >= minScore)
+            // minScore is a threshold on blended rerank scores; a deadline fallback's 1/rank scores would
+            // cut a 0.5 threshold to two results, so only a caller that skipped rerank gets it applied here.
+            .filter(r => !skipRerank || r.score >= minScore)
             .slice(0, limit);
         return attachResultMetadata(store.db, rrfResults);
     }
-    // Step 5: Rerank chunks
-    const chunksToRerank = rerankDocuments(candidates, docChunkMap);
-    hooks?.onRerankStart?.(chunksToRerank.length);
-    const rerankStart2 = Date.now();
-    const reranked = await store.rerank(primaryQuery, chunksToRerank, undefined, intent, { maxDocTokens: options?.rerankMaxDocTokens });
-    hooks?.onRerankDone?.(Date.now() - rerankStart2);
     // Step 6: Blend RRF position score with reranker score
     const candidateMap = new Map(candidates.map(c => [c.file, {
             displayPath: c.displayPath, title: c.title, body: c.body,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ko-qmd",
-  "version": "2.8.3-ko.6",
+  "version": "2.8.3-ko.7",
   "description": "Local hybrid search for Korean Markdown notes and Obsidian vaults — BM25 with Korean particle stripping, Hangul bigram FTS, Qwen3 vector search and LLM reranking, as CLI, MCP server and SDK",
   "type": "module",
   "main": "dist/index.js",