@4da/mcp-server 5.0.4 → 6.0.1

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"));
     }
-    if (fs.existsSync(appDataPath)) {
-        return appDataPath;
+    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;
+    }
+    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,
@@ -587,17 +668,6 @@ export class FourDADatabase {
       );
       CREATE INDEX IF NOT EXISTS idx_advantage_period ON advantage_score(period, computed_at);
 
-      -- Agent feedback — queried by record_agent_feedback, get_agent_feedback_stats
-      CREATE TABLE IF NOT EXISTS agent_feedback (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        item_id TEXT NOT NULL,
-        outcome TEXT NOT NULL,
-        context TEXT,
-        session_task TEXT,
-        recorded_at TEXT DEFAULT (datetime('now'))
-      );
-      CREATE INDEX IF NOT EXISTS idx_agent_feedback_item ON agent_feedback(item_id);
-      CREATE INDEX IF NOT EXISTS idx_agent_feedback_outcome ON agent_feedback(outcome);
     `);
     }
     /**
@@ -610,8 +680,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 +756,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 +805,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 +839,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 +884,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 +935,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,13 +953,17 @@ 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);
         }
+        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 —
@@ -843,9 +971,13 @@ export class FourDADatabase {
         // 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`
-            : `relevance_score DESC`;
+            ? `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
@@ -897,10 +1029,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) {
@@ -949,17 +1086,6 @@ export class FourDADatabase {
             .sort((a, b) => b.relevance_score - a.relevance_score)
             .slice(0, limit);
     }
-    /**
-     * Get a single source item by ID and type
-     */
-    getSourceItem(itemId, sourceType) {
-        const stmt = this.db.prepare(`
-      SELECT id, source_type, source_id, url, title, content, content_hash, created_at, last_seen
-      FROM source_items
-      WHERE id = ? AND source_type = ?
-    `);
-        return stmt.get(itemId, sourceType) || null;
-    }
     /**
      * Look up persisted necessity scores for an item (written by Rust analysis pipeline).
      * Returns defaults (0.0/null) if no necessity data exists yet.
@@ -1057,111 +1183,25 @@ export class FourDADatabase {
         return context;
     }
     // ===========================================================================
-    // Relevance Explanation
-    // ===========================================================================
-    /**
-     * Explain why an item was considered relevant
-     */
-    explainRelevance(itemId, sourceType) {
-        const item = this.getSourceItem(itemId, sourceType);
-        if (!item) {
-            return null;
-        }
-        const context = this.getUserContext(true, true);
-        const itemTopics = this.extractTopics(item.title + " " + item.content);
-        // Compute matching elements
-        const matchingInterests = context.interests
-            .filter((i) => itemTopics.some((t) => this.topicMatches(t, i.topic)))
-            .map((i) => i.topic);
-        const matchingTech = context.tech_stack.filter((tech) => itemTopics.some((t) => this.topicMatches(t, tech)));
-        const matchingTopics = context.ace?.active_topics
-            .filter((at) => itemTopics.some((t) => this.topicMatches(t, at.topic)))
-            .map((at) => at.topic) || [];
-        const matchingAffinities = context.learned?.topic_affinities
-            .filter((ta) => ta.affinity_score > 0 && itemTopics.some((t) => this.topicMatches(t, ta.topic)))
-            .map((ta) => ta.topic) || [];
-        // Compute score breakdown
-        const staticScore = matchingInterests.length * 0.3 +
-            matchingTech.length * 0.2 +
-            (context.domains.some((d) => itemTopics.some((t) => this.topicMatches(t, d)))
-                ? 0.15
-                : 0);
-        const aceScore = context.ace
-            ? matchingTopics.length * 0.1 +
-                context.ace.detected_tech.filter((dt) => itemTopics.some((t) => this.topicMatches(t, dt.name))).length *
-                    0.05
-            : 0;
-        // Learned affinity score DEMOTED in v19 (AD-029) — must mirror
-        // computeRelevanceScore so the explanation matches what actually
-        // scored (the two previously diverged on the anti-penalty weight too:
-        // scorer used *0.3, this explanation used *0.5).
-        const learnedScore = 0;
-        // Anti-penalty from user-authored exclusions only (learned anti-topics
-        // demoted with the rest of the behavioral stack, AD-029).
-        let antiPenalty = 0;
-        for (const exclusion of context.exclusions) {
-            if (itemTopics.some((t) => this.topicMatches(t, exclusion))) {
-                antiPenalty = 1.0; // Hard exclusion
-                break;
-            }
-        }
-        const finalScore = Math.max(0, Math.min(1, staticScore + aceScore + learnedScore - antiPenalty));
-        const scoreBreakdown = {
-            embedding_similarity: null, // Not computing embedding similarity in MCP server
-            static_match_score: Math.round(staticScore * 100) / 100,
-            ace_match_score: Math.round(aceScore * 100) / 100,
-            learned_affinity_score: Math.round(learnedScore * 100) / 100,
-            anti_penalty: Math.round(antiPenalty * 100) / 100,
-            final_score: Math.round(finalScore * 100) / 100,
-        };
-        const matchingContext = {
-            matching_interests: matchingInterests,
-            matching_tech: matchingTech,
-            matching_topics: matchingTopics,
-            matching_affinities: matchingAffinities,
-        };
-        // Generate human-readable explanation
-        const explanationParts = [];
-        if (matchingInterests.length > 0) {
-            explanationParts.push(`Matches your interests: ${matchingInterests.slice(0, 3).join(", ")}`);
-        }
-        if (matchingTech.length > 0) {
-            explanationParts.push(`Related to your tech stack: ${matchingTech.slice(0, 3).join(", ")}`);
-        }
-        if (matchingTopics.length > 0) {
-            explanationParts.push(`Relevant to recent work: ${matchingTopics.slice(0, 3).join(", ")}`);
-        }
-        if (matchingAffinities.length > 0) {
-            explanationParts.push(`You've shown interest in: ${matchingAffinities.slice(0, 3).join(", ")}`);
-        }
-        if (antiPenalty > 0) {
-            explanationParts.push(`Score reduced due to excluded topics`);
-        }
-        const explanation = explanationParts.length > 0
-            ? explanationParts.join(". ") + "."
-            : "No specific matches found - may be based on general relevance.";
-        return {
-            item_id: itemId,
-            source_type: sourceType,
-            title: item.title,
-            score_breakdown: scoreBreakdown,
-            matching_context: matchingContext,
-            explanation,
-        };
-    }
-    // ===========================================================================
     // Feedback
     // ===========================================================================
     /**
      * 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
@@ -1176,16 +1216,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) {
@@ -1195,160 +1258,24 @@ export class FourDADatabase {
             };
         }
     }
-    // ===========================================================================
-    // Agent Feedback
-    // ===========================================================================
     /**
-     * Ensure the agent_feedback table exists.
-     * Called on first use so existing databases (created before this feature)
-     * get the table added without requiring a migration.
+     * 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.
      */
-    ensureAgentFeedbackTable() {
+    ensureFeedbackTable() {
         this.db.exec(`
-      CREATE TABLE IF NOT EXISTS agent_feedback (
+      CREATE TABLE IF NOT EXISTS feedback (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
-        item_id TEXT NOT NULL,
-        outcome TEXT NOT NULL,
-        context TEXT,
-        session_task TEXT,
-        recorded_at TEXT DEFAULT (datetime('now'))
+        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_agent_feedback_item ON agent_feedback(item_id);
-      CREATE INDEX IF NOT EXISTS idx_agent_feedback_outcome ON agent_feedback(outcome);
+      CREATE INDEX IF NOT EXISTS idx_feedback_item ON feedback(source_item_id);
     `);
     }
-    /**
-     * Record agent feedback on recommended content items
-     */
-    recordAgentFeedback(itemIds, outcome, context, sessionTask) {
-        this.ensureAgentFeedbackTable();
-        const validOutcomes = ["used", "rejected", "partially_used"];
-        if (!validOutcomes.includes(outcome)) {
-            return {
-                success: false,
-                message: `Invalid outcome: ${outcome}. Valid outcomes: ${validOutcomes.join(", ")}`,
-                recorded_count: 0,
-            };
-        }
-        if (!itemIds || itemIds.length === 0) {
-            return {
-                success: false,
-                message: "item_ids must contain at least one item ID",
-                recorded_count: 0,
-            };
-        }
-        try {
-            const stmt = this.db.prepare(`
-        INSERT INTO agent_feedback (item_id, outcome, context, session_task)
-        VALUES (?, ?, ?, ?)
-      `);
-            const insertMany = this.db.transaction((ids) => {
-                let count = 0;
-                for (const id of ids) {
-                    stmt.run(id, outcome, context || null, sessionTask || null);
-                    count++;
-                }
-                return count;
-            });
-            const count = insertMany(itemIds);
-            return {
-                success: true,
-                message: `Recorded ${outcome} feedback for ${count} item(s)`,
-                recorded_count: count,
-            };
-        }
-        catch (error) {
-            return {
-                success: false,
-                message: `Failed to record agent feedback: ${error instanceof Error ? error.message : String(error)}`,
-                recorded_count: 0,
-            };
-        }
-    }
-    /**
-     * Get agent feedback statistics for the given period
-     */
-    getAgentFeedbackStats(days = 30) {
-        this.ensureAgentFeedbackTable();
-        const cutoff = `datetime('now', '-${Math.max(1, Math.min(365, days))} days')`;
-        // Outcome totals
-        const outcomeRows = this.db
-            .prepare(`SELECT outcome, COUNT(*) as cnt
-         FROM agent_feedback
-         WHERE recorded_at >= ${cutoff}
-         GROUP BY outcome`)
-            .all();
-        const outcomes = { used: 0, rejected: 0, partially_used: 0, total: 0 };
-        for (const row of outcomeRows) {
-            if (row.outcome === "used")
-                outcomes.used = row.cnt;
-            else if (row.outcome === "rejected")
-                outcomes.rejected = row.cnt;
-            else if (row.outcome === "partially_used")
-                outcomes.partially_used = row.cnt;
-            outcomes.total += row.cnt;
-        }
-        // By source type — join with source_items to get source_type
-        const sourceRows = this.db
-            .prepare(`SELECT COALESCE(si.source_type, 'unknown') as source_type, af.outcome, COUNT(*) as cnt
-         FROM agent_feedback af
-         LEFT JOIN source_items si ON CAST(af.item_id AS INTEGER) = si.id
-         WHERE af.recorded_at >= ${cutoff}
-         GROUP BY source_type, af.outcome
-         ORDER BY cnt DESC`)
-            .all();
-        // Aggregate source rows into per-source stats
-        const sourceMap = new Map();
-        for (const row of sourceRows) {
-            if (!sourceMap.has(row.source_type)) {
-                sourceMap.set(row.source_type, { used: 0, rejected: 0, partially_used: 0, total: 0 });
-            }
-            const entry = sourceMap.get(row.source_type);
-            if (row.outcome === "used")
-                entry.used += row.cnt;
-            else if (row.outcome === "rejected")
-                entry.rejected += row.cnt;
-            else if (row.outcome === "partially_used")
-                entry.partially_used += row.cnt;
-            entry.total += row.cnt;
-        }
-        const bySource = Array.from(sourceMap.entries()).map(([source_type, stats]) => ({
-            source_type,
-            ...stats,
-            usefulness_rate: stats.total > 0 ? (stats.used + stats.partially_used * 0.5) / stats.total : 0,
-        }));
-        // Top used items
-        const topItems = this.db
-            .prepare(`SELECT
-           af.item_id,
-           si.title,
-           si.source_type,
-           SUM(CASE WHEN af.outcome = 'used' THEN 1 ELSE 0 END) as used_count,
-           SUM(CASE WHEN af.outcome = 'rejected' THEN 1 ELSE 0 END) as rejected_count
-         FROM agent_feedback af
-         LEFT JOIN source_items si ON CAST(af.item_id AS INTEGER) = si.id
-         WHERE af.recorded_at >= ${cutoff}
-         GROUP BY af.item_id
-         HAVING used_count > 0
-         ORDER BY used_count DESC
-         LIMIT 10`)
-            .all();
-        // Recent feedback entries
-        const recentFeedback = this.db
-            .prepare(`SELECT item_id, outcome, context, session_task, recorded_at
-         FROM agent_feedback
-         WHERE recorded_at >= ${cutoff}
-         ORDER BY recorded_at DESC
-         LIMIT 20`)
-            .all();
-        return {
-            period_days: days,
-            outcomes,
-            by_source: bySource,
-            top_used_items: topItems,
-            recent_feedback: recentFeedback,
-        };
-    }
     // ===========================================================================
     // Helper Methods
     // ===========================================================================