@lorekit/cli 1.33.0 → 1.33.2

package/bin/lorekit.mjs

@@ -718,8 +718,38 @@ async function main() {
 }
 
 main()
-  .then((code) => process.exit(code ?? 0))
+  .then((code) => flushThenExit(code ?? 0))
   .catch((e) => {
     err(`${c.red('Error:')} ${e && e.stack ? e.stack : e}`);
-    process.exit(1);
+    flushThenExit(1);
   });
+
+// Exit only after stdout/stderr have drained.
+//
+// `process.exit()` truncates any output still buffered for a PIPE (the shape a
+// spawned child's stdout has), because pipe writes are asynchronous. `lorekit
+// mcp` streams newline-delimited JSON-RPC frames to stdout, and a large frame —
+// e.g. a `memory.list` result for a big scope — overflows the pipe buffer, so
+// exiting the instant `main()` resolves drops the tail of that write and the
+// client sees a silent "no response" (this reproduced deterministically once a
+// scope's payload crossed ~½ MB). Flushing first makes the final frame whole.
+// The unref'd safety timer guarantees the process still exits if a stream never
+// drains, so this can never turn a finished command into a hang.
+function flushThenExit(code) {
+  let pending = 2;
+  const done = () => {
+    pending -= 1;
+    if (pending === 0) process.exit(code);
+  };
+  const safety = setTimeout(() => process.exit(code), 2000);
+  safety.unref?.();
+  for (const stream of [process.stdout, process.stderr]) {
+    try {
+      // An empty write's callback fires only after every previously-queued write
+      // has flushed to the fd, so it is a reliable drain barrier.
+      stream.write('', done);
+    } catch {
+      done();
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.33.0",
+  "version": "1.33.2",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/core/lessons.mjs

@@ -3,11 +3,12 @@
 // Storage is reached through the resolved store (local | remote), never a
 // backend directly, so the same read path serves every mode.
 import { deriveScope } from '../scope.mjs';
-// The precedence merge and the literal substring matcher come from the
-// dependency-free `lessons-pure.mjs` — the SAME primitives `tree` and `search`
-// use, so the hook can't drift from them, and the hot path never pulls in the
-// `lessons-view.mjs` render/`util` stack.
-import { resolvePrecedence, matchesQuery } from '../lessons-pure.mjs';
+// The cross-scope precedence merge comes from the dependency-free
+// `lessons-pure.mjs` — the SAME `resolvePrecedence` `tree` uses, so the hook
+// can't drift from it, and the hot path never pulls in the `lessons-view.mjs`
+// render/`util` stack. (Failure-relevance matching is the store's job now, so
+// the hook no longer needs `matchesQuery` — `search` still does.)
+import { resolvePrecedence } from '../lessons-pure.mjs';
 // The deep-link builder is the SAME pure module the `link` command and the
 // `--link` flag use, so the hook's confirmation/nudge links are JSON-encoded
 // correctly (a raw `?scope=global` silently means "all scopes") and can't drift
@@ -135,100 +136,55 @@ export function failureQuery(toolName, toolResponse) {
   return terms;
 }
 
-// Lessons whose key OR value literally contains ANY of the failure `terms`
-// (case-insensitive, via the shared `matchesQuery` — never a regex), capped at
-// `cap`. Pure and best-effort: no terms or no lessons → empty (the caller then
-// falls back to the write-nudge alone). Preserves `lessons` order, so the
-// most-specific scope's relevant lesson surfaces first.
-//
-// This is the LITERAL, client-side matcher — it can only ever narrow a list it
-// is handed. On the failure hot path it has been superseded by
-// `relevantLessonsFromStore`, which QUERIES the store instead of post-filtering
-// the already-injected set (see that function's note). Kept for its unit tests
-// and as the pure building block behind the store-delegated ranking.
-export function relevantLessons(lessons, terms, cap = MAX_RELEVANT) {
-  if (!Array.isArray(lessons) || !lessons.length || !Array.isArray(terms) || !terms.length) {
-    return [];
-  }
+// De-duplicate store-search hits by `scope::key` and cap them, PRESERVING the
+// store's order — which is NOT relevance ordering: the remote store filters by
+// FTS but orders by `updated_at desc` (recency), and the local one yields scope
+// precedence (most-specific first) only WITHIN a tier — `LocalStore.search`
+// walks the scope hierarchy in `readOrder`, but `TwoTierStore.search` merges
+// project-tier hits ahead of home-tier ones, so a `global` lesson in the project
+// tier outranks a `repo::` one in home. Pure and total — any non-array input
+// degrades to [] rather than throwing (this runs inside the best-effort failure
+// hook).
+export function dedupeRelevant(entries, cap = MAX_RELEVANT) {
+  if (!Array.isArray(entries)) return [];
+  const limit = Math.max(0, cap);
+  const seen = new Set();
   const out = [];
-  for (const l of lessons) {
-    if (terms.some((t) => matchesQuery(l, t))) out.push(l);
-    if (out.length >= cap) break;
+  for (const e of entries) {
+    if (out.length >= limit) break; // checked BEFORE the push, so cap 0 yields []
+    if (!e || !e.key) continue;
+    const id = `${e.scope ?? ''}::${e.key}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(e);
   }
   return out;
 }
 
-// Rank the store-search hits for a failure lookup. `resultsPerTerm` is one entry
-// list per failure term (a term that errored or matched nothing contributes an
-// empty list). A lesson that matched MORE terms is more relevant, so it ranks
-// higher; ties break toward the MORE-SPECIFIC scope (its position in
-// `readOrder`, which is most-specific-first) and then toward first-seen order
-// for a stable result. De-duplicates by `scope::key` across every term/scope,
-// keeping the first-seen entry. Pure and total — any non-array input degrades to
-// [] rather than throwing (this runs inside the best-effort failure hook).
-// Capped at `cap`.
-export function rankRelevant(resultsPerTerm, readOrder = [], cap = MAX_RELEVANT) {
-  if (!Array.isArray(resultsPerTerm)) return [];
-  const order = new Map(
-    (Array.isArray(readOrder) ? readOrder : []).map((s, i) => [s, i]),
-  );
-  const UNKNOWN = Number.MAX_SAFE_INTEGER; // a scope not in readOrder sorts last
-  const byId = new Map();
-  let seq = 0;
-  for (const entries of resultsPerTerm) {
-    if (!Array.isArray(entries)) continue;
-    const seenThisTerm = new Set(); // one term can't count a lesson twice
-    for (const e of entries) {
-      if (!e || !e.key) continue;
-      const id = `${e.scope ?? ''}::${e.key}`;
-      if (seenThisTerm.has(id)) continue;
-      seenThisTerm.add(id);
-      const cur = byId.get(id);
-      if (cur) {
-        cur.matches += 1;
-      } else {
-        byId.set(id, {
-          entry: e,
-          matches: 1,
-          rank: order.has(e.scope) ? order.get(e.scope) : UNKNOWN,
-          seq: seq++,
-        });
-      }
-    }
-  }
-  return [...byId.values()]
-    .sort((a, b) => b.matches - a.matches || a.rank - b.rank || a.seq - b.seq)
-    .slice(0, Math.max(0, cap))
-    .map((r) => r.entry);
-}
-
 // Retrieve lessons relevant to a tool failure by QUERYING the store across the
-// scope hierarchy — as opposed to `relevantLessons`, which post-filtered the
-// already-injected set and could therefore only ever resurface a lesson that was
-// going to be shown anyway (a lesson in a sibling scope, or one past the
-// per-scope read cap, was unreachable). Runs one search per distilled term
-// (bounded by `failureQuery`'s MAX_TERMS), concurrently and best-effort: a failed
-// or throwing search contributes nothing. Matching is DELEGATED to the store — a
-// literal substring over the full scope for the local store, server-side FTS
-// (with stemming, so `connect` matches `connection`) for the remote — then the
-// union is ranked by the pure `rankRelevant`. Returns [] on any failure so the
+// scope hierarchy — as opposed to post-filtering the SessionStart-injected set,
+// which could only ever resurface a lesson that was going to be shown anyway (a
+// lesson in a sibling scope, or one past the per-scope read cap, was
+// unreachable). A SINGLE `store.search` carries ALL the distilled failure terms
+// (OR semantics), so the offline store is walked once rather than once per term.
+// MATCHING is DELEGATED to the store — substring over the full scope for local,
+// server-side FTS (with stemming, so `connect` matches `connection`) for remote.
+// ORDERING is not: the remote returns `updated_at desc`, so the top-`cap` slice
+// is the most RECENT matches, not the most relevant ones. Hits are de-duped and
+// capped by the pure `dedupeRelevant`, keeping the store's own ordering (see its
+// docblock). Best-effort: an unusable/throwing store returns [] so the
 // caller falls back to the write-nudge alone.
 export async function relevantLessonsFromStore(store, scope, terms, { cap = MAX_RELEVANT } = {}) {
   if (!store || typeof store.search !== 'function') return [];
   if (!scope || !Array.isArray(scope.readOrder) || scope.readOrder.length === 0) return [];
   if (!Array.isArray(terms) || terms.length === 0) return [];
-  const scopes = scope.readOrder;
-  const resultsPerTerm = await Promise.all(
-    terms.map(async (t) => {
-      try {
-        const res = await store.search({ q: t, scopes });
-        return res && res.ok && Array.isArray(res.entries) ? res.entries : [];
-      } catch {
-        return []; // best-effort: one failed term never sinks the lookup
-      }
-    }),
-  );
-  return rankRelevant(resultsPerTerm, scopes, cap);
+  try {
+    const res = await store.search({ q: terms, scopes: scope.readOrder });
+    if (!res || !res.ok || !Array.isArray(res.entries)) return [];
+    return dedupeRelevant(res.entries, cap);
+  } catch {
+    return []; // best-effort: a failed search falls back to the nudge alone
+  }
 }
 
 // Render the relevant-lessons block injected alongside the failure nudge, or

package/src/store/local.mjs

@@ -205,14 +205,22 @@ class LocalStore {
   }
 
   // search({ q, scopes, tags }) → { ok, entries } — keyword over key/tags/body.
+  // `q` is a single needle (string) OR a list of needles (string[]); a list
+  // matches an entry when ANY needle is a substring (OR semantics). Either way
+  // this walks each scope EXACTLY ONCE — the failure hook passes all its terms
+  // in one call rather than one call per term, so N terms no longer re-read the
+  // store N times. An empty query (or empty list) returns everything, unchanged.
   async search({ q, scopes, tags } = {}) {
-    const needle = String(q || '').toLowerCase();
+    const needles = (Array.isArray(q) ? q : [q])
+      .map((n) => String(n || '').toLowerCase())
+      .filter(Boolean);
+    const matchAll = needles.length === 0;
     const out = [];
     for (const scope of scopes || []) {
       const { entries } = await this.list({ scope, tags });
       for (const e of entries) {
         const hay = `${e.key}\n${(e.tags || []).join(' ')}\n${e.value || ''}`.toLowerCase();
-        if (!needle || hay.includes(needle)) out.push(e);
+        if (matchAll || needles.some((n) => hay.includes(n))) out.push(e);
       }
     }
     return { ok: true, entries: out };

package/src/store/remote.mjs

@@ -71,8 +71,13 @@ class RemoteStore {
   }
 
   async search({ q, scopes, tags } = {}) {
+    // A list of terms collapses into ONE `websearch` query joined by `OR`, so a
+    // multi-term failure lookup is a single round-trip (the server FTS ORs them
+    // and stems each). `failureQuery` distils terms to `[a-z0-9]+` tokens, so no
+    // FTS metacharacter reaches the query string. A plain string passes through.
+    const query = Array.isArray(q) ? q.filter(Boolean).join(' OR ') : q;
     const body = {};
-    if (q) body.q = q;
+    if (query) body.q = query;
     if (scopes?.length) body.scopes = scopes;
     if (tags?.length) body.tags = tags;
     const res = await this._rest('/memories/search', { method: 'POST', body });