claude-mem-lite 3.6.0 → 3.7.1

package/lib/atomic-write.mjs

@@ -0,0 +1,38 @@
+// lib/atomic-write.mjs — crash-safe file writes with optional one-time backup.
+//
+// Why: several write paths mutate user-global config that, if torn or clobbered,
+// breaks the user outside the plugin's control — most acutely ~/.claude.json
+// (the WHOLE Claude Code config) in hook-update's post-update MCP dedup, and
+// ~/.claude/settings.json in install. A plain writeFileSync can leave a
+// half-written file on crash, and a fixed ".tmp" name races concurrent writers.
+// This writes to a pid-unique temp then renames (atomic on POSIX), and can drop
+// a one-time ".bak" so a logic bug in the caller's merge is recoverable.
+
+import { writeFileSync, renameSync, existsSync, copyFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * Atomically write `data` to `filePath` (temp + rename). Optionally back up the
+ * existing file once to `<filePath>.bak` before the first overwrite.
+ * @param {string} filePath
+ * @param {string} data
+ * @param {object} [opts]
+ * @param {boolean} [opts.backup=false]  Create <filePath>.bak if absent and the
+ *   target exists, before writing. Only the first call creates it, so the backup
+ *   preserves the last-known-good rather than being overwritten each run.
+ */
+export function atomicWriteFileSync(filePath, data, { backup = false } = {}) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  if (backup && existsSync(filePath) && !existsSync(filePath + '.bak')) {
+    try { copyFileSync(filePath, filePath + '.bak'); } catch { /* best-effort backup */ }
+  }
+
+  // pid-unique temp: a fixed ".tmp" name lets two concurrent installs clobber
+  // each other's temp mid-write. Same-dir temp keeps the rename atomic (no
+  // cross-device move).
+  const tmp = `${filePath}.tmp-${process.pid}`;
+  writeFileSync(tmp, data);
+  renameSync(tmp, filePath);
+}

package/lib/doctor-benchmark.mjs

@@ -16,7 +16,7 @@ import { sanitizeFtsQuery, OBS_BM25 } from '../utils.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SERVER_PATH = join(__dirname, '..', 'server.mjs');
-const SERVER_INTERNALS_PATH = join(__dirname, '..', 'server-internals.mjs');
+const SEARCH_SCORING_PATH = join(__dirname, '..', 'search-scoring.mjs');
 const BENCHMARK_VERSION = '1';
 
 function extractStringArrayBody(body) {
@@ -40,7 +40,7 @@ function extractStringArrayBody(body) {
  *   1. template literal in server.mjs:  instructions: `...`
  *   2. array-join in server.mjs:        instructions: [ '...', '...' ].join('\n')
  *   3. (v2.31.3+) builder call in server.mjs referencing INSTRUCTIONS_BASE +
- *      INSTRUCTIONS_VERBOSE arrays in server-internals.mjs. Measured at the
+ *      INSTRUCTIONS_VERBOSE arrays in search-scoring.mjs. Measured at the
  *      verbose form — this is the cost-per-turn baseline the benchmark tracks.
  * Returns '' if no shape matches (caller treats byte count as 0).
  */
@@ -56,10 +56,10 @@ function readMcpInstructions() {
   if (arr) return extractStringArrayBody(arr[1]).join('\n');
 
   // Form 3: buildServerInstructions() — reconstruct verbose form from
-  // server-internals.mjs INSTRUCTIONS_BASE + INSTRUCTIONS_VERBOSE arrays.
+  // search-scoring.mjs INSTRUCTIONS_BASE + INSTRUCTIONS_VERBOSE arrays.
   if (/instructions:\s*buildServerInstructions\(/.test(src)) {
     let internals;
-    try { internals = readFileSync(SERVER_INTERNALS_PATH, 'utf8'); } catch { return ''; }
+    try { internals = readFileSync(SEARCH_SCORING_PATH, 'utf8'); } catch { return ''; }
     const base = internals.match(/INSTRUCTIONS_BASE\s*=\s*\[([\s\S]*?)\];/);
     const verbose = internals.match(/INSTRUCTIONS_VERBOSE\s*=\s*\[([\s\S]*?)\];/);
     const parts = [];

package/lib/err-sampler.mjs

@@ -17,6 +17,7 @@
 
 import { appendFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
+import { scrubSecrets } from '../secret-scrub.mjs';
 
 const DAY_MS = 86400000;
 
@@ -47,11 +48,14 @@ export function maybeSampleError(e, ctx, dbDir) {
     const errDir = join(dbDir, 'errors');
     if (!existsSync(errDir)) mkdirSync(errDir, { recursive: true, mode: 0o700 });
 
+    // Scrub BEFORE truncating: a connection string / Authorization header / 401
+    // body can ride along in an error message or stack frame. Scrub the full
+    // string first so a secret straddling the slice boundary is still caught.
     const line = JSON.stringify({
       ts: new Date().toISOString(),
-      ctx: String(ctx || '').slice(0, 120),
-      msg: String(e?.message ?? e ?? '').slice(0, 500),
-      stack: typeof e?.stack === 'string' ? e.stack.split('\n').slice(0, 6).join('\n') : undefined,
+      ctx: scrubSecrets(String(ctx || '')).slice(0, 120),
+      msg: scrubSecrets(String(e?.message ?? e ?? '')).slice(0, 500),
+      stack: typeof e?.stack === 'string' ? scrubSecrets(e.stack.split('\n').slice(0, 6).join('\n')) : undefined,
     }) + '\n';
 
     appendFileSync(join(errDir, `${today()}.jsonl`), line, { mode: 0o600 });

package/lib/lesson-idents.mjs

@@ -0,0 +1,32 @@
+// lib/lesson-idents.mjs — pure, zero-dependency extractor of code identifiers a
+// lesson names, for the bind-salience PostToolUse "dropped a required reference"
+// check (scripts/post-tool-recall.js). Imported by hot standalone hooks → NO
+// heavy imports (lesson #8447): regex over a string only.
+//
+// Identifier shapes: backtick-quoted, camelCase, snake_case, length >= MIN_LEN.
+// These name functions/columns a lesson tells you to keep (recoverChildrenOf,
+// compressed_into). Plain prose ("recover", "delete") is intentionally excluded.
+
+const MIN_LEN = 5;
+const BACKTICK = /`([A-Za-z_][A-Za-z0-9_]*)`/g;
+const CAMEL = /\b([a-z][a-z0-9]*[A-Z][A-Za-z0-9]*)\b/g;
+const SNAKE = /\b([a-z][a-z0-9]*(?:_[a-z0-9]+)+)\b/g;
+
+export function extractIdents(text) {
+  const s = text || '';
+  if (!s) return [];
+  const out = new Set();
+  for (const re of [BACKTICK, CAMEL, SNAKE]) {
+    for (const m of s.matchAll(re)) if (m[1].length >= MIN_LEN) out.add(m[1]);
+  }
+  return [...out];
+}
+
+// Of the identifiers a lesson names, keep only those literally present in the
+// pre-edit file — so the PostToolUse check flags "you removed X" and never
+// "you didn't add X that was never here" (the false positive). '' content → [].
+export function presentIdents(lessonText, content) {
+  const c = content || '';
+  if (!c) return [];
+  return extractIdents(lessonText).filter((id) => c.includes(id));
+}

package/lib/proc-lock.mjs

@@ -0,0 +1,112 @@
+// lib/proc-lock.mjs — best-effort inter-process advisory lock (O_EXCL file).
+//
+// Why: multiple Claude Code sessions can fire SessionStart hooks (and their
+// self-heal / auto-update write paths) at the same instant. install(),
+// install.mjs repair, and hook-update.installExtractedRelease all rename source
+// files into the live install dir; two of them interleaving produces a torn /
+// mixed-version install (server vN + hook vN+1). The launcher's 6h cooldown
+// only RATE-LIMITS re-spawns — it is not mutual exclusion (two processes can
+// both observe "no recent attempt" and both spawn). This gives the write paths
+// a real cross-process gate.
+//
+// Semantics: acquireLock() atomically creates the lock file with O_EXCL. If it
+// already exists it is stolen only when STALE (holder's timestamp older than
+// staleMs, or the recorded pid is provably dead on this host). A live holder →
+// acquire returns null and the caller no-ops (someone else is already doing the
+// write). Release unlinks the file. Crash-safe: a crashed holder's lock ages
+// out via staleMs so the next session reclaims it.
+
+import { writeFileSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+// 5 min: comfortably longer than any install/update write phase (npm install in
+// staging is timeout-capped at 60s) but short enough that a crashed holder does
+// not block self-heal for long.
+const DEFAULT_STALE_MS = 5 * 60 * 1000;
+
+function pidAlive(pid) {
+  if (typeof pid !== 'number' || pid <= 0) return false;
+  try {
+    // Signal 0 = existence check, no signal delivered. EPERM means the process
+    // exists but is owned by another user (still "alive" for our purposes).
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+function isStale(lockPath, staleMs, now) {
+  try {
+    const { pid, ts } = JSON.parse(readFileSync(lockPath, 'utf8'));
+    if (typeof ts === 'number' && now() - ts > staleMs) return true;
+    // Same-host fast reclaim: holder pid is gone. Cross-host (shared homedir)
+    // the pid is meaningless, but ts-staleness above still reclaims it.
+    if (typeof pid === 'number' && !pidAlive(pid)) return true;
+    return false;
+  } catch {
+    return true; // unparseable / unreadable lock → treat as stale and reclaim
+  }
+}
+
+function makeRelease(lockPath) {
+  let released = false;
+  return function release() {
+    if (released) return;
+    released = true;
+    try { unlinkSync(lockPath); } catch { /* already gone — fine */ }
+  };
+}
+
+/**
+ * Try to acquire an advisory lock. Non-blocking.
+ * @param {string} lockPath  Absolute path to the lock file.
+ * @param {object} [opts]
+ * @param {number} [opts.staleMs]  Age after which a held lock is stolen.
+ * @param {() => number} [opts.now]  Clock injection seam (tests).
+ * @returns {(() => void)|null}  A release() fn, or null if a live peer holds it.
+ */
+export function acquireLock(lockPath, { staleMs = DEFAULT_STALE_MS, now = Date.now } = {}) {
+  try { mkdirSync(dirname(lockPath), { recursive: true }); } catch { /* best-effort */ }
+  const payload = JSON.stringify({ pid: process.pid, ts: now() });
+  try {
+    writeFileSync(lockPath, payload, { flag: 'wx' }); // O_EXCL — atomic create
+    return makeRelease(lockPath);
+  } catch (e) {
+    if (e.code !== 'EEXIST') return null; // permission / fs error → fail closed
+    if (!isStale(lockPath, staleMs, now)) return null; // live peer holds it
+    // Stale: steal it. unlink + re-create exclusively; lose the race → null.
+    try { unlinkSync(lockPath); } catch { /* raced */ }
+    try {
+      writeFileSync(lockPath, payload, { flag: 'wx' });
+      return makeRelease(lockPath);
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Run `fn` while holding the lock; release in a finally. No-op if not acquired.
+ * @returns {{acquired: boolean, result?: any}}
+ */
+export function withLock(lockPath, fn, opts) {
+  const release = acquireLock(lockPath, opts);
+  if (!release) return { acquired: false };
+  try {
+    return { acquired: true, result: fn() };
+  } finally {
+    release();
+  }
+}
+
+/** Async variant of withLock — awaits `fn`. */
+export async function withLockAsync(lockPath, fn, opts) {
+  const release = acquireLock(lockPath, opts);
+  if (!release) return { acquired: false };
+  try {
+    return { acquired: true, result: await fn() };
+  } finally {
+    release();
+  }
+}

package/lib/search-core.mjs

@@ -1,26 +1,33 @@
-// Shared cross-source search core (query build / source queries / scoring
-// normalization / sort / pagination math).
+// Shared cross-source search core for cmdSearch (CLI) and mem_search (MCP).
 //
-// Single source of truth for cmdSearch (CLI) and mem_search (MCP). The
-// observation path already converged in search-engine.mjs (#8198/#8212); the
-// sessions/prompts FTS queries, CJK precision + LIKE fallback, cross-source
-// score normalization, user-sort, over-fetch sizing, and date-bound parsing
-// were still copy-pasted and synced by "paired-path" comments — the drift
-// class compress-core (ARCH-1), recall-core, and timeline-core were extracted
-// to close. Call sites keep what legitimately differs: flag/schema parsing,
-// result-row dialect (CLI `_source`+raw columns vs MCP `source`+mapped
-// fields), error-message wording, and output rendering.
+// coreRunSearchPipeline (below) is the SINGLE orchestration body — deep /
+// auto-escalation → per-source query (obs hybrid + sessions + prompts) →
+// cross-source normalize+sort → context re-rank + supersede → tier filter →
+// user sort → count+paginate. The two ~180-line bodies that cmdSearch and
+// runSearchPipeline used to keep hand-synced via "paired-path" comments are
+// gone (audit P1-2); each surface is now a thin adapter that parses/validates
+// in and renders out. Cross-surface equivalence is enforced by
+// tests/search-parity.test.mjs, not by comments.
 //
-// Behavioral asymmetries that are PRESERVED, not converged (documented so a
-// future "fix" is a deliberate contract change, not an accident):
-//   • CLI forces source=observations when --type/--tier/--importance/--branch
-//     is set; MCP only forces it for obs_type.
+// Surfaces legitimately differ on a few policy points; each is an explicit opt
+// on coreRunSearchPipeline (obsTypeFallback / crossSourceEpochSortNoFts /
+// rerankPolicy / recentListingNoFts / tolerateMissingFts / tierPosition …) so
+// behavior is strictly preserved and any future convergence is a deliberate
+// change, not an accident. Notable preserved asymmetries:
+//   • CLI forces source=observations for --type/--tier/--importance/--branch;
+//     MCP only forces it for obs_type. (effectiveSource is computed per-adapter.)
 //   • CLI warns on inverted --from/--to ranges; MCP does not.
-//   • CLI wraps session/prompt FTS in try/catch for pre-FTS legacy DBs.
+//   • CLI tolerates missing session/prompt FTS (pre-FTS legacy DBs); MCP does not.
+//   • MCP lists-recent-by-type on a 0-match obs_type query; CLI does not (#8217).
+//
+// Result rows use one canonical `source` key; session/prompt rows carry dual
+// keys (date=created_at, text=prompt_text, session=content_session_id) so each
+// surface's renderer reads its own field names off a single row shape.
 
 import { sanitizeFtsQuery, relaxFtsQueryToOr, SESS_BM25, DEFAULT_DECAY_HALF_LIFE_MS } from '../utils.mjs';
 import { cjkPrecisionOk, extractCjkLikePatterns } from '../nlp.mjs';
 import { computeTier } from '../tier.mjs';
+import { countSearchTotal, attachBodyTokens } from '../search-engine.mjs';
 
 /** Sanitize a user query to FTS5 syntax; optionally force OR semantics. */
 export function buildSearchFtsQuery(query, { or = false } = {}) {
@@ -198,3 +205,252 @@ export function applyTierFilter(db, results, { tier, sourceKey, currentProject }
     return full && computeTier(full, tierCtx) === tier;
   });
 }
+
+/**
+ * Finalize a merged, scored result set into one page: compute the TRUE
+ * (limit/offset-invariant) population, slice the requested page, and attach the
+ * ~Nt fetch-cost hint. Single source of truth for the count+paginate+enrich tail
+ * of cmdSearch (CLI) and runSearchPipeline (MCP) — exactly where #8635 drifted
+ * (the over-fetch cap leaked into the reported total on BOTH sides independently).
+ *
+ * `total`: every source over-fetched from offset 0 (computePerSourceWindow), so
+ * results.length is the over-fetched candidate pool, NOT the population —
+ * countSearchTotal re-derives the real MATCH+filter count. Clamp to
+ * >= results.length so vector/concept-augmented obs rows are never undercounted
+ * (#8217/#8638). For deep (explicit or auto-escalated) the population IS the fused
+ * variant set already in `results` (deepSearch is obs-only, capped at
+ * perSourceLimit); countSearchTotal would instead count the ORIGINAL query's FTS
+ * matches — wrong, and ~0 on the vocabulary-mismatch queries deep exists for (F1).
+ *
+ * Pagination always slices: single-source results can exceed SQL LIMIT via
+ * expansion (concept co-occurrence / PRF / vector), and `offset` is applied
+ * exactly ONCE here (the per-source SQL always saw offset 0).
+ *
+ * @returns {{ total: number, page: object[] }}
+ */
+export function finalizeSearchPage(db, results, {
+  isDeep, offset, limit, effectiveSource, ftsQuery, orFallbackFired,
+  project = null, obsType = null, importance = null, branch = null,
+  epochFrom = null, epochTo = null, includeNoise = false,
+}) {
+  const total = isDeep
+    ? results.length
+    : Math.max(countSearchTotal(db, {
+      effectiveSource: effectiveSource || null,
+      ftsQuery,
+      obsFtsQuery: effectiveObsFtsQuery(ftsQuery, orFallbackFired),
+      args: { project: project || null, obs_type: obsType || null, importance: importance || null, branch: branch || null },
+      project: project || null,
+      epochFrom, epochTo, includeNoise,
+    }), results.length);
+  const page = results.slice(offset, offset + limit);
+  attachBodyTokens(db, page);
+  return { total, page };
+}
+
+/**
+ * Unified cross-source search orchestrator — single source of truth for the CLI
+ * (cmdSearch) and MCP (mem_search) search bodies: deep / auto-escalation →
+ * per-source query (obs hybrid + sessions + prompts) → cross-source
+ * normalize+sort → context re-rank + supersede → tier post-filter → user sort →
+ * count+paginate. The two surfaces legitimately differ on a handful of policy
+ * points; each is a named opt so a future "fix" is a deliberate contract change,
+ * not an accident (see the per-opt comments).
+ *
+ * The core does NO flag/schema parsing, NO stdout/stderr, NO formatting — adapters
+ * validate+parse on the way in and render on the way out. Session/prompt rows
+ * carry dual keys (`date`=created_at, `text`=prompt_text, `session`=content_session_id)
+ * so both renderers read their own field names off one canonical row.
+ *
+ * #8743: `db` comes ONLY from `ctx.db` — there is no module-global fallback, so a
+ * per-source leg can never silently query the wrong database.
+ *
+ * @returns {Promise<{ page:object[], total:number, preFinalizeCount:number, isDeep:boolean,
+ *   escalated:boolean, escalatedObsCount:number, variants:object[]|null,
+ *   reranked:boolean, orFallbackFired:boolean, effectiveSource:string|null, ftsQuery:string }>}
+ */
+export async function coreRunSearchPipeline(ctx, opts) {
+  const {
+    db, currentProject = null, env = process.env,
+    searchObservationsHybrid, deepSearch, shouldEscalateToDeep,
+    autoDeepLlmReady, reRankWithContext, markSuperseded,
+    llm = null, rerankLlm = undefined,
+  } = ctx;
+  const {
+    query, ftsQuery, effectiveSource = null, deepMode = 'normal', rerank = false,
+    limit, offset, project = null, obsType = null, importance = null, branch = null,
+    includeNoise = false, epochFrom = null, epochTo = null, sort = 'relevance', tier = null,
+    // ── surface policy (strict behavior-preservation; the two surfaces differ) ──
+    obsTypeFallback = false,           // A5: list-recent-by-type when 0 matches — MCP true, CLI false (#8217 removed it from CLI)
+    crossSourceEpochSortNoFts = false, // A3: epoch-sort the cross-source set when no ftsQuery — MCP true, CLI false
+    rerankPolicy = 'mcp',              // A4: re-rank/supersede gate + re-sort condition — 'mcp' | 'cli'
+    rerankProject = null,              // reRankWithContext project — MCP currentProject, CLI project||inferProject()
+    recentListingNoFts = false,        // session/prompt recent-listing when no ftsQuery (explicit --source) — MCP true, CLI false
+    tolerateMissingFts = false,        // wrap session/prompt FTS in try/catch for pre-FTS legacy DBs — CLI true, MCP false
+    tierPosition = 'late',             // tier filter vs re-rank ordering — MCP 'late' (after re-rank), CLI 'early' (in obs block)
+    tierProject = null,                // applyTierFilter project — MCP project||currentProject, CLI project||inferProject()
+  } = opts;
+
+  const { perSourceLimit, perSourceOffset } = computePerSourceWindow(limit, offset);
+  const isCrossSource = !effectiveSource;
+  const results = [];
+  let orFallbackFired = false;
+  let deepVariants = null;
+  let deepReranked = false;
+  let isDeep = deepMode === 'deep';
+  let escalated = false;
+  let escalatedObsCount = 0;
+
+  const obsCtx = {
+    db, ftsQuery,
+    args: { project, obs_type: obsType, importance, branch, include_noise: includeNoise },
+    epochFrom, epochTo, perSourceLimit, perSourceOffset, currentProject, limit,
+    orFallbackFired: false,
+  };
+
+  const runDeep = async ({ auto = false } = {}) => {
+    const ds = await deepSearch(db, {
+      query, project, type: obsType, importance, branch, includeNoise,
+      epochFrom, epochTo, limit: perSourceLimit, currentProject,
+    }, llm ? { llm, rerank: rerank && !auto, rerankLlm } : { auto, rerank: rerank && !auto, rerankLlm });
+    deepVariants = ds.variants;
+    deepReranked = ds.reranked;
+    return ds.results;
+  };
+
+  // ── Observations (hybrid engine; deep / auto-escalation; obs rows already carry source:'obs') ──
+  if (!effectiveSource || effectiveSource === 'observations') {
+    if (deepMode === 'deep') {
+      results.push(...await runDeep());
+    } else {
+      results.push(...searchObservationsHybrid(db, obsCtx));
+      if (obsCtx.orFallbackFired) orFallbackFired = true;
+      const obsCountBefore = results.filter((r) => r.source === 'obs').length;
+      if (deepMode === 'auto' && autoDeepLlmReady(env, llm) &&
+          shouldEscalateToDeep(results.filter((r) => r.source === 'obs'), obsCtx, { db, project })) {
+        const deepRows = await runDeep({ auto: true });
+        results.length = 0;
+        results.push(...deepRows);
+        isDeep = true;
+        escalated = true;
+        escalatedObsCount = obsCountBefore;
+      }
+    }
+  }
+
+  // ── Tier post-filter, CLI position: obs-only (tier forces observations), before re-rank ──
+  if (tier && tierPosition === 'early') {
+    const filtered = applyTierFilter(db, results, { tier, sourceKey: 'source', currentProject: tierProject });
+    results.length = 0; results.push(...filtered);
+  }
+
+  // ── Sessions (FTS via shared helper; optional recent-listing when no ftsQuery) ──
+  if ((!effectiveSource || effectiveSource === 'sessions') && !isDeep) {
+    const pushSessions = () => {
+      if (ftsQuery) {
+        const rows = searchSessionsFts(db, { ftsQuery, project, projectBoost: project ? null : currentProject, epochFrom, epochTo, perSourceLimit, perSourceOffset });
+        for (const r of rows) results.push({ ...r, source: 'session', date: r.created_at });
+      } else if (recentListingNoFts && effectiveSource === 'sessions') {
+        const params = []; const wheres = [];
+        if (project) { wheres.push('project = ?'); params.push(project); }
+        if (epochFrom !== null) { wheres.push('created_at_epoch >= ?'); params.push(epochFrom); }
+        if (epochTo !== null) { wheres.push('created_at_epoch <= ?'); params.push(epochTo); }
+        const where = wheres.length ? `WHERE ${wheres.join(' AND ')}` : '';
+        params.push(perSourceLimit, perSourceOffset);
+        const rows = db.prepare(`
+          SELECT id, request, completed, project, created_at, created_at_epoch
+          FROM session_summaries ${where}
+          ORDER BY created_at_epoch DESC
+          LIMIT ? OFFSET ?
+        `).all(...params);
+        for (const r of rows) results.push({ ...r, source: 'session', date: r.created_at });
+      }
+    };
+    if (tolerateMissingFts) { try { pushSessions(); } catch { /* session FTS may not exist in older DBs */ } } else pushSessions();
+  }
+
+  // ── Prompts (FTS via shared helper incl. CJK gate; optional recent-listing) ──
+  if ((!effectiveSource || effectiveSource === 'prompts') && !isDeep) {
+    const pushPrompts = () => {
+      if (ftsQuery) {
+        const rows = searchPromptsFts(db, { query, ftsQuery, project, epochFrom, epochTo, perSourceLimit, perSourceOffset });
+        for (const r of rows) results.push({ ...r, source: 'prompt', date: r.created_at, text: r.prompt_text, session: r.content_session_id });
+      } else if (recentListingNoFts && effectiveSource === 'prompts') {
+        const params = []; const wheres = [];
+        if (project) { wheres.push('s.project = ?'); params.push(project); }
+        if (epochFrom !== null) { wheres.push('p.created_at_epoch >= ?'); params.push(epochFrom); }
+        if (epochTo !== null) { wheres.push('p.created_at_epoch <= ?'); params.push(epochTo); }
+        const where = wheres.length ? `WHERE ${wheres.join(' AND ')}` : '';
+        params.push(perSourceLimit, perSourceOffset);
+        const rows = db.prepare(`
+          SELECT p.id, p.prompt_text, p.content_session_id, p.created_at, p.created_at_epoch
+          FROM user_prompts p
+          JOIN sdk_sessions s ON p.content_session_id = s.content_session_id
+          ${where}
+          ORDER BY p.created_at_epoch DESC
+          LIMIT ? OFFSET ?
+        `).all(...params);
+        for (const r of rows) results.push({ ...r, source: 'prompt', date: r.created_at, text: r.prompt_text, session: r.content_session_id });
+      }
+    };
+    if (tolerateMissingFts) { try { pushPrompts(); } catch { /* prompt FTS may not exist in older DBs */ } } else pushPrompts();
+  }
+
+  // ── Type-list fallback (MCP): obs_type set + 0 matches → list recent of that type ──
+  if (obsTypeFallback && results.length === 0 && obsType) {
+    const typeWheres = ['COALESCE(compressed_into, 0) = 0', 'superseded_at IS NULL', 'type = ?'];
+    const typeParams = [obsType];
+    if (project) { typeWheres.push('project = ?'); typeParams.push(project); }
+    if (epochFrom !== null) { typeWheres.push('created_at_epoch >= ?'); typeParams.push(epochFrom); }
+    if (epochTo !== null) { typeWheres.push('created_at_epoch <= ?'); typeParams.push(epochTo); }
+    if (importance) { typeWheres.push('COALESCE(importance, 1) >= ?'); typeParams.push(importance); }
+    typeParams.push(limit);
+    const typeRows = db.prepare(`
+      SELECT id, type, title, subtitle, project, created_at, importance, files_modified
+      FROM observations WHERE ${typeWheres.join(' AND ')}
+      ORDER BY created_at_epoch DESC LIMIT ?
+    `).all(...typeParams);
+    for (const r of typeRows) results.push({ source: 'obs', id: r.id, type: r.type, title: r.title, subtitle: r.subtitle, project: r.project, date: r.created_at, importance: r.importance, files_modified: r.files_modified, score: 0, snippet: '' });
+  }
+
+  // ── Cross-source normalize + sort ──
+  if (isCrossSource && results.length > 0 && ftsQuery) normalizeCrossSourceScores(results, 'source');
+  if (isCrossSource && results.length > 0) {
+    if (ftsQuery) results.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
+    else if (crossSourceEpochSortNoFts) results.sort((a, b) => (b.created_at_epoch ?? 0) - (a.created_at_epoch ?? 0));
+  }
+
+  // ── Context re-rank + superseded marking (markSuperseded is pure stale-tagging) ──
+  const hasObs = results.some((r) => r.source === 'obs');
+  const rerankGate = rerankPolicy === 'mcp' ? ((ftsQuery || isDeep) && hasObs) : hasObs;
+  if (rerankGate) {
+    const obsResults = results.filter((r) => r.source === 'obs');
+    const doReRank = rerankPolicy === 'mcp' ? (ftsQuery && !deepReranked) : !deepReranked;
+    if (doReRank) reRankWithContext(db, obsResults, rerankProject);
+    markSuperseded(obsResults);
+    const doReSort = rerankPolicy === 'mcp' ? (ftsQuery && !deepReranked) : isCrossSource;
+    if (doReSort) results.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
+  }
+
+  // ── Tier post-filter, MCP position: after re-rank, on the merged set ──
+  if (tier && tierPosition === 'late') {
+    const filtered = applyTierFilter(db, results, { tier, sourceKey: 'source', currentProject: tierProject });
+    results.length = 0; results.push(...filtered);
+  }
+
+  // ── User-requested sort (after relevance scoring) ──
+  applyUserSort(results, sort);
+
+  // ── Count + paginate + ~Nt enrich. preFinalizeCount lets the CLI adapter
+  //    distinguish "nothing matched" from "this page is empty" (its two messages). ──
+  const preFinalizeCount = results.length;
+  const { total, page } = finalizeSearchPage(db, results, {
+    isDeep, offset, limit, effectiveSource, ftsQuery, orFallbackFired,
+    project, obsType, importance, branch, epochFrom, epochTo, includeNoise,
+  });
+
+  return {
+    page, total, preFinalizeCount, isDeep, escalated, escalatedObsCount,
+    variants: deepVariants, reranked: deepReranked, orFallbackFired, effectiveSource, ftsQuery,
+  };
+}