@4da/mcp-server 5.0.3 → 6.0.0

package/dist/db.js

@@ -10,24 +10,22 @@ import * as fs from "fs";
 import * as os from "os";
 import { fileURLToPath } from "node:url";
 import { dirname } from "node:path";
+import { checkNativeBindings, isNativeBindingError, nativeBindingMessage } from "./native-bindings.js";
 let Database;
 try {
     Database = (await import("better-sqlite3")).default;
 }
 catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error("\n  [4DA] Failed to load better-sqlite3 native bindings.\n\n" +
-        "  This usually means your system is missing C++ build tools.\n" +
-        "  Install the appropriate tools for your platform:\n\n" +
-        "    macOS:   xcode-select --install\n" +
-        "    Ubuntu:  sudo apt install build-essential python3\n" +
-        "    Windows: npm install -g windows-build-tools\n\n" +
-        `  Error: ${msg}\n\n` +
-        "  After installing build tools, run: npm rebuild better-sqlite3\n");
+    console.error(`\n  [4DA] ${nativeBindingMessage(err)}\n`);
     process.exit(1);
 }
+/** Null when better-sqlite3 can open a database here; otherwise why not, with the fix. */
+export function nativeBindingProblem() {
+    return checkNativeBindings(Database);
+}
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+import { dbRecoveryNote, readDbRecoveredMarker, readEngineBlockMarker } from "./freshness-markers.js";
 /**
  * Resolve the database path by checking multiple locations in priority order:
  * 1. FOURDA_DB_PATH env var
@@ -51,23 +49,85 @@ function getDefaultDbPath() {
     if (fs.existsSync(projectRootPath)) {
         return projectRootPath;
     }
-    // 4. Platform-specific Tauri app data dirs (production)
-    const platform = process.platform;
-    let appDataPath;
+    // 4. The desktop app's own database, where the deployed app keeps it.
+    for (const appDataPath of desktopAppDbPaths()) {
+        if (fs.existsSync(appDataPath))
+            return appDataPath;
+    }
+    // 5. No desktop database: the standalone database, in the user's data dir.
+    return standaloneDbPath();
+}
+/**
+ * Where the deployed desktop app keeps its database, mirroring
+ * `src-tauri/src/state.rs::get_db_path` / `get_platform_data_dir`:
+ * FOURDA_DATA_DIR overrides; Windows `%APPDATA%\com.4da.app\data`, macOS
+ * `~/Library/Application Support/com.4da.app/data`, Linux
+ * `$XDG_DATA_HOME/4da/data` (default `~/.local/share/4da/data`).
+ *
+ * Measured 2026-10-03 (pre-publish verification): this looked in
+ * `~/.local/share/com.4da.app/data` on Linux, a directory the app never
+ * writes, so a Linux desktop user's server never found the app's database and
+ * never offered the desktop tools. The old path is still checked last, in case
+ * a database was ever placed there by hand.
+ */
+export function desktopAppDbPaths(platform = process.platform, env = process.env, home = os.homedir()) {
+    const join = platform === "win32" ? path.win32.join : path.posix.join;
+    const paths = [];
+    const dataDir = env.FOURDA_DATA_DIR?.trim();
+    if (dataDir)
+        paths.push(join(dataDir, "4da.db"));
     if (platform === "win32") {
-        appDataPath = path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "com.4da.app", "data", "4da.db");
+        paths.push(join(env.APPDATA || join(home, "AppData", "Roaming"), "com.4da.app", "data", "4da.db"));
     }
     else if (platform === "darwin") {
-        appDataPath = path.join(os.homedir(), "Library", "Application Support", "com.4da.app", "data", "4da.db");
+        paths.push(join(home, "Library", "Application Support", "com.4da.app", "data", "4da.db"));
     }
     else {
-        appDataPath = path.join(os.homedir(), ".local", "share", "com.4da.app", "data", "4da.db");
+        const xdg = env.XDG_DATA_HOME?.trim() || join(home, ".local", "share");
+        paths.push(join(xdg, "4da", "data", "4da.db"));
+        paths.push(join(home, ".local", "share", "com.4da.app", "data", "4da.db"));
+    }
+    return paths;
+}
+/**
+ * Where a standalone install keeps its database: a per-user data directory.
+ * It used to be `<cwd>/data/4da.db` — inside the user's own repository, where
+ * it could be committed, and one per directory the server happened to start
+ * in, so agent memory and decisions did not follow the user between projects.
+ */
+export function standaloneDbPath() {
+    const home = os.homedir();
+    const base = process.platform === "win32"
+        ? process.env.LOCALAPPDATA || path.join(home, "AppData", "Local")
+        : process.platform === "darwin"
+            ? path.join(home, "Library", "Application Support")
+            : process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
+    return path.join(base, "4da-mcp", "standalone.db");
+}
+/** Marker table written into every standalone database. */
+const STANDALONE_MARKER = "mcp_standalone";
+/**
+ * Whether an EXISTING database is a standalone one. The marker decides; a
+ * database created before the marker existed is recognised by its minimal
+ * schema (schema_version 1, a few dozen tables) — the desktop app's database
+ * carries 140+ tables and a schema version past 100. Getting this wrong was a
+ * bug: from the second session on, a standalone database read as the desktop
+ * app's, so tools/list advertised five tools with no data behind them and the
+ * project was never rescanned.
+ */
+function detectStandalone(db) {
+    try {
+        const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((t) => t.name);
+        if (tables.includes(STANDALONE_MARKER))
+            return true;
+        if (!tables.includes("schema_version") || tables.length >= 40)
+            return false;
+        const row = db.prepare("SELECT MAX(version) AS v FROM schema_version").get();
+        return row?.v === 1;
     }
-    if (fs.existsSync(appDataPath)) {
-        return appDataPath;
+    catch {
+        return false;
     }
-    // 5. Final fallback
-    return path.resolve(process.cwd(), "data", "4da.db");
 }
 /** Minutes a feed may go without a fetch before DB-backed tools flag it stale. */
 const STALE_AFTER_MINUTES = 60;
@@ -159,13 +219,22 @@ export class FourDADatabase {
             this.db.pragma("journal_mode = WAL");
         }
         catch (error) {
-            throw new Error(`Failed to open 4DA database at ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(isNativeBindingError(error)
+                ? nativeBindingMessage(error)
+                : `Failed to open 4DA database at ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
         }
-        // Standalone mode: create schema for a brand-new database
+        // Standalone mode: create schema for a brand-new database, and recognise
+        // an existing standalone database as one on every later session.
         if (isNew) {
             this.createMinimalSchema();
             this._isStandalone = true;
         }
+        else {
+            this._isStandalone = detectStandalone(this.db);
+        }
+        if (this._isStandalone) {
+            this.db.exec(`CREATE TABLE IF NOT EXISTS ${STANDALONE_MARKER} (created_at TEXT DEFAULT (datetime('now')))`);
+        }
         // Schema upgrade for standalone databases created before `is_direct` was
         // added to the minimal schema: the full-DB init branch queries that column
         // (DEPENDENCY_GROUP_QUERY), and without it session 2+ of a standalone
@@ -247,6 +316,7 @@ export class FourDADatabase {
             return {
                 valid: true,
                 tables: tables.map((t) => t.name),
+                standalone: detectStandalone(testDb),
             };
         }
         catch (error) {
@@ -400,6 +470,17 @@ export class FourDADatabase {
       CREATE INDEX IF NOT EXISTS idx_interactions_timestamp ON interactions(timestamp);
       CREATE INDEX IF NOT EXISTS idx_interactions_item ON interactions(source_item_id);
 
+      -- Explicit relevance labels — written by record_feedback (save / mark_irrelevant);
+      -- the desktop calibration fitter reads this table as ground truth. Same DDL as desktop.
+      CREATE TABLE IF NOT EXISTS feedback (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_item_id INTEGER NOT NULL,
+        relevant INTEGER NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        FOREIGN KEY (source_item_id) REFERENCES source_items(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_feedback_item ON feedback(source_item_id);
+
       -- Project dependencies — queried by project_health, tech_radar, developer_dna, knowledge_gaps
       CREATE TABLE IF NOT EXISTS project_dependencies (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -610,8 +691,11 @@ export class FourDADatabase {
         const insertDep = this.db.prepare("INSERT OR IGNORE INTO project_dependencies (project_path, manifest_type, package_name, version, is_dev, language) VALUES (?, ?, ?, ?, ?, ?)");
         const insertInterest = this.db.prepare("INSERT OR IGNORE INTO explicit_interests (topic, weight, source) VALUES (?, ?, ?)");
         const insertTechStack = this.db.prepare("INSERT OR IGNORE INTO tech_stack (technology) VALUES (?)");
-        // Run all inserts in a single transaction for speed
+        // Run all inserts in a single transaction for speed. A rescan replaces
+        // this project's dependency rows rather than accumulating removed ones.
+        const clearDeps = this.db.prepare("DELETE FROM project_dependencies WHERE project_path = ?");
         const populate = this.db.transaction(() => {
+            clearDeps.run(scan.projectPath);
             // Languages -> detected_tech + tech_stack + active_topics
             for (const lang of scan.languages) {
                 insertTech.run(lang, "language", 0.95, "project_scan");
@@ -683,15 +767,25 @@ export class FourDADatabase {
      * Get relevant content items scored by the Rust pipeline (preferred) or
      * TypeScript fallback scoring when Rust scores are unavailable.
      */
-    getRelevantContent(minScore = 0.35, sourceType, limit = 20, sinceHours = 24, requireCurrentVersion = false) {
+    getRelevantContent(minScore = 0.35, sourceType, limit = 20, sinceHours = 24, requireCurrentVersion = false, 
+    /**
+     * Restrict to items the scoring pipeline stamped with this signal_type.
+     * Lets a type-specific read (a security-only pass) fill its limit with
+     * matches instead of competing for the top-N slots across every type.
+     * Only meaningful over pipeline-stamped rows: without Rust scores there
+     * are no stored types, so the read returns nothing rather than pretend.
+     */
+    signalType) {
         const sinceDate = new Date(Date.now() - sinceHours * 60 * 60 * 1000)
             .toISOString()
             .replace("T", " ")
             .slice(0, 19);
         const hasRustScores = this.hasColumn("source_items", "relevance_score");
         if (hasRustScores) {
-            return this.getRelevantContentFromRust(minScore, sourceType, limit, sinceDate, requireCurrentVersion);
+            return this.getRelevantContentFromRust(minScore, sourceType, limit, sinceDate, requireCurrentVersion, signalType);
         }
+        if (signalType)
+            return [];
         // TypeScript fallback computes scores fresh per call — current by construction.
         return this.getRelevantContentFallback(minScore, sourceType, limit, sinceDate);
     }
@@ -722,10 +816,30 @@ export class FourDADatabase {
         }
         const ageMinutes = minutesSince(lastFetchAt);
         const isStale = ageMinutes === null || ageMinutes > STALE_AFTER_MINUTES;
-        const note = isStale
+        let note = isStale
             ? `Feed data ${ageMinutes === null ? "has never been fetched" : `is ~${ageMinutes} min old`} and may be stale: the MCP server reads the database but does not fetch. Run ` +
                 "`fourda-engine --once` (or open the 4DA app) to refresh."
             : `Feed data is ~${ageMinutes} min old (fresh).`;
+        // Engine-block marker: a scheduled refresh that can only REFUSE (binary
+        // older than the DB schema) cannot record its failure in the database, so
+        // the Rust engine leaves `data/.engine-blocked` beside it. That exact
+        // failure froze the feed for two days (2026-08-28→30) with ERROR-log-only
+        // symptoms; this reader is the one that caught it, so it now names the
+        // cause instead of just the staleness.
+        const engineBlock = readEngineBlockMarker(this.db.name);
+        if (engineBlock) {
+            note += ` ENGINE BLOCKED since ${engineBlock.at}: ${engineBlock.error} — a rebuilt/updated 4DA binary is required; a plain refresh will keep refusing.`;
+        }
+        // Database-recovery marker: when the headless refresh engine restores the
+        // database from a backup, or quarantines it and starts a fresh empty one,
+        // every answer read from it may be incomplete or empty, and a fresh
+        // database looks "fresh" by every other field here. The engine leaves
+        // `data/.db-recovered` beside the DB; it is surfaced on every DB-backed
+        // answer until the desktop app has shown it and deleted it. Read-only.
+        const recovered = readDbRecoveredMarker(this.db.name);
+        if (recovered) {
+            note += ` ${dbRecoveryNote(recovered)}`;
+        }
         return {
             source_items_total: total,
             newest_item_at: newestItemAt,
@@ -736,6 +850,16 @@ export class FourDADatabase {
             age_minutes: ageMinutes,
             is_stale: isStale,
             note,
+            ...(engineBlock
+                ? { engine_blocked_at: engineBlock.at, engine_blocked_error: engineBlock.error }
+                : {}),
+            ...(recovered
+                ? {
+                    db_recovered_at: recovered.at,
+                    db_recovery_kind: recovered.kind,
+                    db_recovery_detail: recovered.detail,
+                }
+                : {}),
         };
     }
     /** `MAX(sources.last_fetch)`, tolerant of a missing `sources` table (returns null). */
@@ -771,7 +895,7 @@ export class FourDADatabase {
      * Use Rust-computed relevance_score from the desktop app's scoring pipeline.
      * These scores are from the full 5-axis PASIFA engine — much more accurate.
      */
-    getRelevantContentFromRust(minScore, sourceType, limit, sinceDate, requireCurrentVersion = false) {
+    getRelevantContentFromRust(minScore, sourceType, limit, sinceDate, requireCurrentVersion = false, signalType) {
         // Grounding subquery — guarded: older/partial 4DA DBs may have relevance_score
         // (so the Rust path runs) but lack source_item_dependencies. Fall back to 0
         // (→ evidence_class "semantic_only") rather than throwing.
@@ -822,6 +946,17 @@ export class FourDADatabase {
         const curationGuard = this.hasColumn("source_items", "feed_relevant")
             ? ` AND (feed_relevant IS NULL OR feed_relevant = 1)`
             : ``;
+        // Historical-advisory guard: OSV/CVE backfills ingest decades-old advisories
+        // whose created_at (discovery time) is days old but whose published_at is
+        // ancient — and the scoring brain rates them 0.9 because they name the
+        // user's deps. Live 2026-08-30: half the top-20 was React XSS fixed in 0.14
+        // (2015) and tokio races fixed in 2021, on a react 19 / tokio 1.52 stack.
+        // A reading feed is about what is CURRENT; version-aware exposure checking
+        // is vulnerability_scan / knowledge_gaps territory. NULL published_at is
+        // kept — absence of a date is not evidence of age.
+        const advisoryFreshnessGuard = this.hasColumn("source_items", "published_at")
+            ? ` AND NOT (source_type IN ('osv', 'cve') AND published_at IS NOT NULL AND datetime(published_at) < datetime('now', '-90 days'))`
+            : ``;
         let query = `
       SELECT id, source_type, source_id, url, title, content, content_hash,
              created_at, last_seen, relevance_score, content_type,
@@ -829,14 +964,32 @@ export class FourDADatabase {
              ${depCount} AS dep_match_count
       FROM source_items
       WHERE relevance_score >= ?
-        AND datetime(created_at) >= datetime(?)${versionGuard}${curationGuard}
+        AND datetime(created_at) >= datetime(?)${versionGuard}${curationGuard}${advisoryFreshnessGuard}
     `;
         const params = [minScore, sinceDate];
         if (sourceType) {
             query += ` AND source_type = ?`;
             params.push(sourceType);
         }
-        query += ` ORDER BY relevance_score DESC LIMIT ?`;
+        if (signalType && this.hasColumn("source_items", "signal_type")) {
+            query += ` AND signal_type = ?`;
+            params.push(signalType);
+        }
+        // Ranked read (desktop audit items 12+26, schema 110): order by the
+        // batch-relative rank when the analysis cycle has ranked the item, falling
+        // back to the evidence score. This mirrors the Rust source of truth —
+        // `RANKED_ORDER_EXPR` in `src-tauri/src/db/scoring_queries.rs` — and must
+        // stay textually in sync with it. The `relevance_score >= ?` membership
+        // filter above deliberately stays on evidence: evidence decides membership,
+        // rank decides order. Guarded on column existence for pre-110 DBs.
+        // `id DESC` breaks ties deterministically: a hard score cap parks many
+        // items at exactly the same value (100 of 651 surfaced items sat at
+        // 0.5000), and without a tie-break their order was whatever SQLite
+        // emitted. The pre-110 fallback gets the same tie-break.
+        const rankedOrder = this.hasColumn("source_items", "rank_score")
+            ? `COALESCE(rank_score, relevance_score) DESC, id DESC`
+            : `relevance_score DESC, id DESC`;
+        query += ` ORDER BY ${rankedOrder} LIMIT ?`;
         // Over-fetch so near-duplicate collapsing below can still fill `limit`
         // (the same story arrives via reddit + rss + mastodon: live feeds showed
         // three copies of "Rust 1.98.0" in one 20-item response).
@@ -887,10 +1040,15 @@ export class FourDADatabase {
      */
     getRelevantContentFallback(minScore, sourceType, limit, sinceDate) {
         const context = this.getUserContext(true, true);
+        // Same historical-advisory guard as the Rust-score path: a backfilled
+        // 2015 advisory is not current reading, whatever its keyword score.
+        const advisoryFreshnessGuard = this.hasColumn("source_items", "published_at")
+            ? ` AND NOT (source_type IN ('osv', 'cve') AND published_at IS NOT NULL AND datetime(published_at) < datetime('now', '-90 days'))`
+            : ``;
         let query = `
       SELECT id, source_type, source_id, url, title, content, content_hash, created_at, last_seen
       FROM source_items
-      WHERE datetime(created_at) >= datetime(?)
+      WHERE datetime(created_at) >= datetime(?)${advisoryFreshnessGuard}
     `;
         const params = [sinceDate];
         if (sourceType) {
@@ -1146,12 +1304,19 @@ export class FourDADatabase {
      * Record user feedback on an item
      */
     recordFeedback(itemId, sourceType, action) {
-        // Verify item exists
-        const item = this.getSourceItem(itemId, sourceType);
-        if (!item) {
+        // Look the item up by id. source_type is optional and, when given, must
+        // match. It used to be a required filter restricted to three sources
+        // (hackernews / arxiv / reddit), so an agent could not rate an item from
+        // any of the other sources — about 75% of the corpus (measured 2026-09-24).
+        const row = this.db
+            .prepare(`SELECT id, source_type FROM source_items WHERE id = ?`)
+            .get(itemId);
+        if (!row || (sourceType && row.source_type !== sourceType)) {
             return {
                 success: false,
-                message: `Item ${itemId} of type ${sourceType} not found`,
+                message: sourceType
+                    ? `Item ${itemId} of type ${sourceType} not found`
+                    : `Item ${itemId} not found`,
             };
         }
         // Map action to signal strength — v19: unified onto the canonical ACE
@@ -1166,16 +1331,39 @@ export class FourDADatabase {
             dismiss: -0.8,
             mark_irrelevant: -1.0,
         };
+        // Only an explicit relevance statement becomes a label in `feedback` (the
+        // table the desktop calibration fitter treats as ground truth). A click or
+        // a dismiss is interaction history, not a relevance judgment. Mirrors the
+        // desktop rule in src/store/feedback-slice.ts.
+        const relevanceLabel = {
+            save: 1,
+            mark_irrelevant: 0,
+        };
+        const label = relevanceLabel[action];
         try {
-            const stmt = this.db.prepare(`
+            if (label !== undefined)
+                this.ensureFeedbackTable();
+            const insertInteraction = this.db.prepare(`
         INSERT INTO interactions (item_id, action_type, item_source, signal_strength, timestamp)
         VALUES (?, ?, ?, ?, datetime('now'))
       `);
-            const result = stmt.run(itemId, action, sourceType, signalStrength[action]);
+            const write = this.db.transaction(() => {
+                const r = insertInteraction.run(itemId, action, row.source_type, signalStrength[action]);
+                if (label !== undefined) {
+                    this.db
+                        .prepare(`INSERT INTO feedback (source_item_id, relevant) VALUES (?, ?)`)
+                        .run(itemId, label);
+                }
+                return r;
+            });
+            const result = write();
             return {
                 success: true,
-                message: `Recorded ${action} feedback for item ${itemId}`,
+                message: label === undefined
+                    ? `Recorded ${action} feedback for item ${itemId}`
+                    : `Recorded ${action} feedback for item ${itemId} (relevance label: ${label === 1 ? "relevant" : "not relevant"})`,
                 interaction_id: result.lastInsertRowid,
+                relevance_label: label === undefined ? null : label === 1,
             };
         }
         catch (error) {
@@ -1185,6 +1373,24 @@ export class FourDADatabase {
             };
         }
     }
+    /**
+     * Ensure the `feedback` table exists. The desktop app always has it; a
+     * standalone database created before record_feedback wrote labels does not
+     * (createMinimalSchema runs only for brand-new files). Same DDL as desktop,
+     * so against the desktop database this is a no-op.
+     */
+    ensureFeedbackTable() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS feedback (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_item_id INTEGER NOT NULL,
+        relevant INTEGER NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        FOREIGN KEY (source_item_id) REFERENCES source_items(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_feedback_item ON feedback(source_item_id);
+    `);
+    }
     // ===========================================================================
     // Agent Feedback
     // ===========================================================================

package/dist/doctor.js

@@ -13,14 +13,18 @@
  *   4da-mcp --doctor
  */
 import { existsSync } from "node:fs";
-import { FourDADatabase } from "./db.js";
+import { FourDADatabase, nativeBindingProblem } from "./db.js";
+import { checkBuildStaleness } from "./build-staleness.js";
 export function runDoctor() {
     console.log("\n  4DA MCP Server — Doctor\n");
     const checks = [];
     // 1. Node.js version
     const nodeVersion = process.version;
     const major = parseInt(nodeVersion.slice(1).split(".")[0], 10);
-    const nodeRequired = 20;
+    // 22, matching package.json engines: better-sqlite3 >= 12.10 ships no Node 20
+    // prebuild, so a Node 20 install compiles from source and fails without a
+    // C++ toolchain (measured 2026-10-03 on node:20-bookworm-slim and alpine).
+    const nodeRequired = 22;
     checks.push({
         name: "Node.js version",
         status: major >= nodeRequired ? "pass" : "fail",
@@ -28,12 +32,14 @@ export function runDoctor() {
             ? `${nodeVersion} (>= ${nodeRequired} required)`
             : `${nodeVersion} — Node.js ${nodeRequired}+ required`,
     });
-    // 2. Native bindings — if we reached here, the dynamic import in db.ts succeeded
-    // (it calls process.exit(1) with a diagnostic message on failure)
+    // 2. Native bindings — opening a database, not just importing the package:
+    // the import succeeds without the compiled module (npm 12 blocking its
+    // install script left none, and this check used to say "loaded").
+    const bindingProblem = nativeBindingProblem();
     checks.push({
         name: "SQLite native bindings",
-        status: "pass",
-        detail: "better-sqlite3 loaded successfully",
+        status: bindingProblem ? "fail" : "pass",
+        detail: bindingProblem ?? "better-sqlite3 opened an in-memory database",
     });
     // 3. Database discovery — deep integrity_check is appropriate here: --doctor is
     // an explicit, user-invoked diagnostic where a slow full scan is expected. The
@@ -70,7 +76,21 @@ export function runDoctor() {
             detail: envExists ? envDb : `Set to ${envDb} but file does not exist`,
         });
     }
-    // 5. Semantic recall provider (optional)
+    // 5. Build freshness — repo checkouts only. `.mcp.json` runs dist/, and
+    // nothing rebuilds it on a merge; a stale dist served two-day-old behavior
+    // on 2026-08-30 with zero symptoms. The published npm package ships no src/
+    // (check returns null there) so users never see a false alarm.
+    const staleness = checkBuildStaleness();
+    if (staleness) {
+        checks.push({
+            name: "Server build freshness",
+            status: staleness.stale ? "fail" : "pass",
+            detail: staleness.stale
+                ? staleness.note ?? "dist/ is older than src/ — rebuild"
+                : "dist/ is at least as new as src/",
+        });
+    }
+    // 6. Semantic recall provider (optional)
     const embedProvider = process.env.FOURDA_EMBED_PROVIDER;
     const hasOpenAI = !!process.env.OPENAI_API_KEY;
     const hasOllama = process.env.FOURDA_EMBED_PROVIDER === "ollama" ||

package/dist/embeddings.js

@@ -146,7 +146,13 @@ export async function embedText(text, config, signal) {
             const res = await fetch(`${base}/api/embeddings`, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ model: config.model, prompt: input }),
+                // The embedder runs on the CPU, as the 4DA app's does: on the GPU,
+                // Ollama evicts and reloads the local judge model around each call.
+                body: JSON.stringify({
+                    model: config.model,
+                    prompt: input,
+                    options: { num_gpu: 0 },
+                }),
                 signal,
             });
             if (!res.ok)

package/dist/freshness-markers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Marker files the Rust engine leaves beside `4da.db` when it cannot record
+ * an event in the database itself. `data_freshness` reads them so a
+ * DB-backed answer can say what happened to the data it was read from.
+ *
+ * Read-only by design: the app owns each marker's lifecycle. The engine
+ * clears `.engine-blocked` the moment a cycle opens the database again; the
+ * desktop app shows `.db-recovered` once and deletes it. Nothing here deletes
+ * either one, so every MCP answer keeps saying it until the app has.
+ */
+export interface EngineBlockMarker {
+    at: string;
+    error: string;
+}
+/**
+ * `data/.engine-blocked`: written by the Rust engine (`engine_block.rs`) when
+ * a scheduled refresh is refused by a newer database schema.
+ */
+export declare function readEngineBlockMarker(dbFile: string): EngineBlockMarker | null;
+/** The kinds the engine writes today. A newer engine's unknown kind is still surfaced. */
+export type DbRecoveryKind = "restored_from_backup" | "quarantined_no_backup" | "recovery_failed";
+export interface DbRecoveredMarker {
+    at: string;
+    kind: DbRecoveryKind | string;
+    detail: string;
+}
+/**
+ * `data/.db-recovered`: written by the headless refresh engine when it
+ * restored the database from a backup or quarantined it.
+ * `{"at": "<ISO UTC>", "kind": "...", "detail": "<path or reason>"}`.
+ */
+export declare function readDbRecoveredMarker(dbFile: string): DbRecoveredMarker | null;
+/** The sentence `data_freshness.note` carries for a recovery marker. */
+export declare function dbRecoveryNote(marker: DbRecoveredMarker): string;

package/dist/freshness-markers.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Marker files the Rust engine leaves beside `4da.db` when it cannot record
+ * an event in the database itself. `data_freshness` reads them so a
+ * DB-backed answer can say what happened to the data it was read from.
+ *
+ * Read-only by design: the app owns each marker's lifecycle. The engine
+ * clears `.engine-blocked` the moment a cycle opens the database again; the
+ * desktop app shows `.db-recovered` once and deletes it. Nothing here deletes
+ * either one, so every MCP answer keeps saying it until the app has.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+function markerPath(dbFile, name) {
+    // An in-memory database has no directory; do not read a marker out of the cwd.
+    if (!dbFile || dbFile === ":memory:")
+        return null;
+    return path.join(path.dirname(dbFile), name);
+}
+function readJsonMarker(dbFile, name) {
+    const file = markerPath(dbFile, name);
+    if (!file)
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `data/.engine-blocked`: written by the Rust engine (`engine_block.rs`) when
+ * a scheduled refresh is refused by a newer database schema.
+ */
+export function readEngineBlockMarker(dbFile) {
+    const v = readJsonMarker(dbFile, ".engine-blocked");
+    if (v && typeof v.at === "string" && typeof v.error === "string") {
+        return { at: v.at, error: v.error };
+    }
+    return null;
+}
+/**
+ * `data/.db-recovered`: written by the headless refresh engine when it
+ * restored the database from a backup or quarantined it.
+ * `{"at": "<ISO UTC>", "kind": "...", "detail": "<path or reason>"}`.
+ */
+export function readDbRecoveredMarker(dbFile) {
+    const v = readJsonMarker(dbFile, ".db-recovered");
+    if (!v)
+        return null;
+    const { at, kind, detail } = v;
+    if (typeof at !== "string" || typeof kind !== "string" || typeof detail !== "string")
+        return null;
+    if (!at.trim() || !kind.trim())
+        return null;
+    return { at, kind, detail };
+}
+/** The sentence `data_freshness.note` carries for a recovery marker. */
+export function dbRecoveryNote(marker) {
+    const { at, kind, detail } = marker;
+    switch (kind) {
+        case "restored_from_backup":
+            return `The database was restored from a backup by the background refresh at ${at} — results may be incomplete or empty; the preserved file is ${detail}.`;
+        case "quarantined_no_backup":
+            return `The database was replaced with a fresh empty database by the background refresh at ${at} — results may be incomplete or empty; the preserved file is ${detail}.`;
+        case "recovery_failed":
+            return `The background refresh failed to recover the database at ${at} — results may be incomplete or empty; ${detail}.`;
+        default:
+            return `The background refresh recorded a database recovery (${kind}) at ${at} — results may be incomplete or empty; ${detail}.`;
+    }
+}

package/dist/gitignore.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Enough of .gitignore to decide whether a directory or lockfile belongs to
+ * the project, for the standalone project-tree walk.
+ *
+ * A directory the repository ignores is not part of the project: scratch
+ * clones, generated output, a sibling tool checked out inside the tree.
+ * Measured 2026-10-02: walking 4DA's root without this scanned the ignored
+ * `victauri-gauntlet/` and `cli/` and reported their advisories (rustls, h2,
+ * scc) as the project's, where osv-scanner, which honours .gitignore, did not.
+ *
+ * Read from the files, never by running git: `git check-ignore` in a cloned
+ * repository honours that repository's config, and a config can name programs
+ * for git to run (core.fsmonitor). Reading a scanned folder must not execute
+ * anything it names.
+ *
+ * Supported: comments, blank lines, `dir/` (directory only), leading `/` and
+ * inner `/` anchoring, `*`, `?`, `**`, nested .gitignore files and
+ * .git/info/exclude. A negation (`!pattern`) is treated conservatively: a
+ * path that any negation could re-include is never skipped.
+ */
+/** Ignore rules gathered while walking down from a root. */
+export declare class IgnoreRules {
+    private readonly root;
+    private rules;
+    private loaded;
+    constructor(root: string);
+    /** Read the .gitignore of a directory (relative to the root) once. */
+    load(relDir: string): void;
+    /**
+     * Whether an absolute directory below the root lies in, or is, an ignored
+     * directory. Every ancestor is checked, loading nested .gitignore files on
+     * the way down. A directory outside the root is never "ignored" here.
+     */
+    ignoresDirectory(absDir: string): boolean;
+    /** Whether a path (relative to the root, `/`-separated) is ignored. */
+    ignores(relPath: string, isDir: boolean): boolean;
+}