@4da/mcp-server 4.6.2 → 4.6.3

package/dist/db.d.ts

@@ -53,14 +53,26 @@ export declare class FourDADatabase {
      */
     get isStandalone(): boolean;
     /**
-     * Validate that a database file exists, is readable, and passes integrity checks.
+     * Validate that a database file exists and is a readable SQLite database.
      *
      * Use this before accepting tool calls to ensure the database is in a good state.
      *
+     * By default this runs a CHEAP probe (open + list tables, ~0.1s) which surfaces
+     * a missing, locked, or corrupt-header file. It deliberately does NOT run a full
+     * `PRAGMA integrity_check`: that is an O(database-size) scan (~11s on a 1.7 GB DB,
+     * and growing) and, because better-sqlite3 is synchronous, it blocks the event
+     * loop — running it on the startup path stalls the MCP stdio handshake until it
+     * finishes, so the host's connect timeout can fire and the server looks like it
+     * "failed to start". Pass `{ deep: true }` for the full integrity_check on the
+     * explicit `--doctor` diagnostic path, where a slow, thorough scan is expected.
+     *
      * @param dbPath - Path to the database file. If omitted, uses the default resolution.
+     * @param opts.deep - Run the full `PRAGMA integrity_check` (slow, blocking). Default false.
      * @returns Validation result with table list on success, or error details on failure.
      */
-    static validateDatabase(dbPath?: string): DatabaseValidationResult;
+    static validateDatabase(dbPath?: string, opts?: {
+        deep?: boolean;
+    }): DatabaseValidationResult;
     /**
      * Get the raw better-sqlite3 database instance for custom queries
      */

package/dist/db.js

@@ -121,14 +121,24 @@ export class FourDADatabase {
         return this._isStandalone;
     }
     /**
-     * Validate that a database file exists, is readable, and passes integrity checks.
+     * Validate that a database file exists and is a readable SQLite database.
      *
      * Use this before accepting tool calls to ensure the database is in a good state.
      *
+     * By default this runs a CHEAP probe (open + list tables, ~0.1s) which surfaces
+     * a missing, locked, or corrupt-header file. It deliberately does NOT run a full
+     * `PRAGMA integrity_check`: that is an O(database-size) scan (~11s on a 1.7 GB DB,
+     * and growing) and, because better-sqlite3 is synchronous, it blocks the event
+     * loop — running it on the startup path stalls the MCP stdio handshake until it
+     * finishes, so the host's connect timeout can fire and the server looks like it
+     * "failed to start". Pass `{ deep: true }` for the full integrity_check on the
+     * explicit `--doctor` diagnostic path, where a slow, thorough scan is expected.
+     *
      * @param dbPath - Path to the database file. If omitted, uses the default resolution.
+     * @param opts.deep - Run the full `PRAGMA integrity_check` (slow, blocking). Default false.
      * @returns Validation result with table list on success, or error details on failure.
      */
-    static validateDatabase(dbPath) {
+    static validateDatabase(dbPath, opts) {
         const resolvedPath = dbPath || getDefaultDbPath();
         const absolutePath = path.isAbsolute(resolvedPath)
             ? resolvedPath
@@ -141,21 +151,24 @@ export class FourDADatabase {
                 error: `No existing database at ${absolutePath}. Standalone mode will create one on startup.`,
             };
         }
-        // Try to open and run integrity check
         let testDb = null;
         try {
             testDb = new Database(absolutePath, { readonly: true });
-            // Run integrity check
-            const integrityResult = testDb.pragma("integrity_check");
-            const integrityStatus = integrityResult[0]?.integrity_check;
-            if (integrityStatus !== "ok") {
-                return {
-                    valid: false,
-                    error: `Database integrity check failed: ${integrityStatus}. `
-                        + "The database file may be corrupt. Try deleting data/4da.db and restarting 4DA.",
-                };
+            // Deep, opt-in integrity check (slow: full-database scan). Only on --doctor.
+            if (opts?.deep) {
+                const integrityResult = testDb.pragma("integrity_check");
+                const integrityStatus = integrityResult[0]?.integrity_check;
+                if (integrityStatus !== "ok") {
+                    return {
+                        valid: false,
+                        error: `Database integrity check failed: ${integrityStatus}. `
+                            + "The database file may be corrupt. Try deleting data/4da.db and restarting 4DA.",
+                    };
+                }
             }
-            // List tables
+            // List tables. This reads the schema, so a truncated/corrupt-header file
+            // (not a valid SQLite DB) throws here and is reported below — giving the
+            // cheap path meaningful corruption detection without a full scan.
             const tables = testDb
                 .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
                 .all();
@@ -710,10 +723,17 @@ export class FourDADatabase {
      * These scores are from the full 5-axis PASIFA engine — much more accurate.
      */
     getRelevantContentFromRust(minScore, sourceType, limit, sinceDate) {
+        // 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.
+        const depCount = this.hasColumn("source_item_dependencies", "source_item_id")
+            ? `(SELECT COUNT(*) FROM source_item_dependencies d WHERE d.source_item_id = source_items.id)`
+            : `0`;
         let query = `
       SELECT id, source_type, source_id, url, title, content, content_hash,
              created_at, last_seen, relevance_score, content_type,
-             signal_type, signal_priority
+             signal_type, signal_priority,
+             ${depCount} AS dep_match_count
       FROM source_items
       WHERE relevance_score >= ?
         AND datetime(created_at) >= datetime(?)
@@ -737,6 +757,14 @@ export class FourDADatabase {
                     ? `${hoursAgo} hours ago`
                     : `${Math.round(hoursAgo / 24)} days ago`;
             const necessity = this.getNecessityForItem(item.id);
+            // Provenance: grounded (matched one of the user's installed deps) vs
+            // semantic-only. A grounded security advisory is the OSV-verified gold tier.
+            const grounded = (item.dep_match_count ?? 0) > 0;
+            const evidence_class = grounded
+                ? item.content_type === "security_advisory"
+                    ? "osv_verified"
+                    : "dependency_grounded"
+                : "semantic_only";
             return {
                 id: item.id,
                 source_type: item.source_type,
@@ -753,6 +781,7 @@ export class FourDADatabase {
                 necessity_urgency: necessity.urgency,
                 signal_type: item.signal_type ?? null,
                 signal_priority: item.signal_priority ?? null,
+                evidence_class,
             };
         });
     }
@@ -804,6 +833,8 @@ export class FourDADatabase {
                     necessity_urgency: necessity.urgency,
                     signal_type: null,
                     signal_priority: null,
+                    // Standalone keyword scorer — no Rust pipeline, no dependency grounding.
+                    evidence_class: "keyword_heuristic",
                 });
             }
         }

package/dist/doctor.js

@@ -34,8 +34,10 @@ export function runDoctor() {
         status: "pass",
         detail: "better-sqlite3 loaded successfully",
     });
-    // 3. Database discovery
-    const validation = FourDADatabase.validateDatabase();
+    // 3. Database discovery — deep integrity_check is appropriate here: --doctor is
+    // an explicit, user-invoked diagnostic where a slow full scan is expected. The
+    // startup path uses the cheap default to keep the MCP handshake responsive.
+    const validation = FourDADatabase.validateDatabase(undefined, { deep: true });
     if (validation.valid) {
         checks.push({
             name: "4DA database",

package/dist/index.d.ts

@@ -12,7 +12,7 @@
  * do NOT expose it over a network without putting your own auth in front.
  */
 /**
- * 4DA MCP Server v4.6.2 — Dependency Intelligence for AI Coding Agents
+ * 4DA MCP Server v4.6.3 — Dependency Intelligence for AI Coding Agents
  *
  * 14 tools across 5 categories. Live vulnerability scanning (OSV.dev),
  * ecosystem news, persistent memory, and tech stack awareness for any MCP host.

package/dist/index.js

@@ -13,7 +13,7 @@
  * do NOT expose it over a network without putting your own auth in front.
  */
 /**
- * 4DA MCP Server v4.6.2 — Dependency Intelligence for AI Coding Agents
+ * 4DA MCP Server v4.6.3 — Dependency Intelligence for AI Coding Agents
  *
  * 14 tools across 5 categories. Live vulnerability scanning (OSV.dev),
  * ecosystem news, persistent memory, and tech stack awareness for any MCP host.
@@ -51,7 +51,7 @@ import { createDatabase, FourDADatabase } from "./db.js";
 // =============================================================================
 const server = new Server({
     name: "4da-server",
-    version: "4.6.2",
+    version: "4.6.3",
 }, {
     capabilities: {
         tools: { listChanged: true },
@@ -293,7 +293,7 @@ async function main() {
     const args = process.argv.slice(2);
     // Version
     if (args.includes("--version") || args.includes("-v")) {
-        console.log("@4da/mcp-server 4.6.2");
+        console.log("@4da/mcp-server 4.6.3");
         return;
     }
     // Help
@@ -382,7 +382,7 @@ async function main() {
         process.exit(0);
     });
     const toolCount = getSlimToolList().length;
-    console.error(`4DA MCP Server v4.6.2 started — ${toolCount} tools, stdio transport`);
+    console.error(`4DA MCP Server v4.6.3 started — ${toolCount} tools, stdio transport`);
     console.error("  Use --http for Streamable HTTP, --setup to configure editors, --doctor to check health");
 }
 main().catch((error) => {

package/dist/live/index.d.ts

@@ -25,6 +25,7 @@ export declare class LiveIntelligence {
     private resolvedDeps;
     private auditDeps;
     private initialized;
+    private projectRoot;
     constructor(db: Database.Database);
     /**
      * Initialize with project data. Call once after project scan.
@@ -56,6 +57,13 @@ export declare class LiveIntelligence {
         deps: string[];
         devDeps: string[];
     }>): void;
+    /**
+     * Root directory the dependency set was resolved from, or null before init.
+     * For multi-manifest (grouped) init this is the deepest common ancestor of
+     * the group directories — honest scope reporting for tool output, instead
+     * of whatever `process.cwd()` happens to be.
+     */
+    getProjectRoot(): string | null;
     /**
      * Run vulnerability scan (returns cached if fresh, fetches otherwise).
      */

package/dist/live/index.js

@@ -32,6 +32,7 @@ export class LiveIntelligence {
     resolvedDeps = [];
     auditDeps = [];
     initialized = false;
+    projectRoot = null;
     constructor(db) {
         this.enabled = process.env.FOURDA_OFFLINE !== "true";
         this.cache = new LiveCache(db);
@@ -50,6 +51,7 @@ export class LiveIntelligence {
     initFromProject(projectPath, deps, devDeps, language) {
         this.resolvedDeps = resolveVersions(projectPath, deps, devDeps, language);
         this.auditDeps = resolveAuditVersions(projectPath, deps, devDeps, language);
+        this.projectRoot = projectPath;
         this.initialized = true;
     }
     /**
@@ -66,6 +68,7 @@ export class LiveIntelligence {
         }
         this.resolvedDeps = dedupeDependencies(allResolved);
         this.auditDeps = dedupeDependencies(allAudit);
+        this.projectRoot = projectPath;
         this.initialized = true;
     }
     /**
@@ -87,8 +90,18 @@ export class LiveIntelligence {
         }
         this.resolvedDeps = dedupeDependencies(allResolved);
         this.auditDeps = dedupeDependencies(allAudit);
+        this.projectRoot = commonPathRoot(groups.map((g) => g.dir));
         this.initialized = true;
     }
+    /**
+     * Root directory the dependency set was resolved from, or null before init.
+     * For multi-manifest (grouped) init this is the deepest common ancestor of
+     * the group directories — honest scope reporting for tool output, instead
+     * of whatever `process.cwd()` happens to be.
+     */
+    getProjectRoot() {
+        return this.projectRoot;
+    }
     /**
      * Run vulnerability scan (returns cached if fresh, fetches otherwise).
      */
@@ -227,6 +240,26 @@ export class LiveIntelligence {
         };
     }
 }
+/**
+ * Deepest common ancestor of a set of directories (segment-wise, both slash
+ * styles). Null for an empty set; a single dir is its own root.
+ */
+function commonPathRoot(dirs) {
+    if (dirs.length === 0)
+        return null;
+    const split = (p) => p.replace(/\\/g, "/").replace(/\/+$/, "").split("/");
+    let common = split(dirs[0]);
+    for (const dir of dirs.slice(1)) {
+        const parts = split(dir);
+        let i = 0;
+        while (i < common.length && i < parts.length && common[i].toLowerCase() === parts[i].toLowerCase())
+            i++;
+        common = common.slice(0, i);
+        if (common.length === 0)
+            break;
+    }
+    return common.length > 0 ? common.join("/") : null;
+}
 function dedupeDependencies(deps) {
     const unique = new Map();
     for (const dep of deps) {

package/dist/live/types.d.ts

@@ -1,4 +1,4 @@
-export type OsvEcosystem = "npm" | "crates.io" | "PyPI" | "Go" | "Maven" | "NuGet" | "RubyGems" | "Packagist";
+export type OsvEcosystem = "npm" | "crates.io" | "PyPI" | "Go" | "Maven" | "NuGet" | "RubyGems" | "Packagist" | "Pub";
 export interface ResolvedDependency {
     name: string;
     version: string | null;

package/dist/live/version-resolver.d.ts

@@ -6,6 +6,16 @@
  * Uses only Node.js built-ins — no external parsers.
  */
 import type { OsvEcosystem, ResolvedDependency } from "./types.js";
+/**
+ * Map a language/ecosystem alias to its OSV ecosystem id (case-insensitive).
+ *
+ * Falls back to "npm" ONLY for genuinely unrecognized input — a last resort, not
+ * a real default. OSV-unindexed languages (Swift, C/C++) and unknowns produce no
+ * OSV matches anyway (their package names don't collide with the npm namespace),
+ * so this never fabricates a vulnerability. Ecosystems that lack a version
+ * resolver here (NuGet/Maven/Packagist/RubyGems/Pub) still get the CORRECT label,
+ * so the moment a resolver is added the scan is right by construction.
+ */
 export declare function mapEcosystem(language: string): OsvEcosystem;
 export declare function resolveVersions(cwd: string, deps: string[], devDeps: string[], language: string, targets?: Record<string, string>): ResolvedDependency[];
 /**

package/dist/live/version-resolver.js

@@ -9,18 +9,58 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { targetActiveOnHost } from "./platform.js";
+// Alias -> OSV ecosystem. Mirrors the desktop app's canonical
+// `Ecosystem::parse` (src-tauri/src/ecosystem.rs) so both sides recognize the
+// SAME aliases — they previously drifted (the Rust side knew csharp/dart/php
+// while this map keyed C# as "dotnet" and omitted Dart entirely, mislabeling
+// those deps). Keep this in sync with that enum.
 const ECOSYSTEM_MAP = {
     npm: "npm",
+    javascript: "npm",
+    typescript: "npm",
+    node: "npm",
+    js: "npm",
+    ts: "npm",
     rust: "crates.io",
+    cargo: "crates.io",
+    "crates.io": "crates.io",
+    crates: "crates.io",
     python: "PyPI",
+    pypi: "PyPI",
+    pip: "PyPI",
+    py: "PyPI",
     go: "Go",
+    golang: "Go",
     java: "Maven",
+    maven: "Maven",
+    kotlin: "Maven",
+    gradle: "Maven",
+    csharp: "NuGet",
+    "c#": "NuGet",
     dotnet: "NuGet",
-    ruby: "RubyGems",
+    nuget: "NuGet",
     php: "Packagist",
+    composer: "Packagist",
+    packagist: "Packagist",
+    ruby: "RubyGems",
+    rubygems: "RubyGems",
+    gem: "RubyGems",
+    dart: "Pub",
+    flutter: "Pub",
+    pub: "Pub",
 };
+/**
+ * Map a language/ecosystem alias to its OSV ecosystem id (case-insensitive).
+ *
+ * Falls back to "npm" ONLY for genuinely unrecognized input — a last resort, not
+ * a real default. OSV-unindexed languages (Swift, C/C++) and unknowns produce no
+ * OSV matches anyway (their package names don't collide with the npm namespace),
+ * so this never fabricates a vulnerability. Ecosystems that lack a version
+ * resolver here (NuGet/Maven/Packagist/RubyGems/Pub) still get the CORRECT label,
+ * so the moment a resolver is added the scan is right by construction.
+ */
 export function mapEcosystem(language) {
-    return ECOSYSTEM_MAP[language] || "npm";
+    return ECOSYSTEM_MAP[language.trim().toLowerCase()] || "npm";
 }
 export function resolveVersions(cwd, deps, devDeps, language, targets = {}) {
     const ecosystem = mapEcosystem(language);

package/dist/schemas/get-relevant-content.json

@@ -1,6 +1,6 @@
 {
   "name": "get_relevant_content",
-  "description": "Get filtered relevant content from 4DA's personalized feed.\n\nReturns content items that match the user's interests, tech stack, and learned preferences.\nItems are scored based on:\n- Explicit interests declared by the user\n- Tech stack and domains\n- ACE-detected context (recent files, projects, git activity)\n- Learned preferences from past interactions\n\nCall when the user asks what to read, what is relevant to them, or for content on a topic.",
+  "description": "Get filtered relevant content from 4DA's personalized feed.\n\nReturns content items that match the user's interests, tech stack, and learned preferences.\nItems are scored based on:\n- Explicit interests declared by the user\n- Tech stack and domains\n- ACE-detected context (recent files, projects, git activity)\n- Learned preferences from past interactions\n\nIMPORTANT for autonomous use: each item carries an `evidence_class` describing how it is grounded. The relevance_score float is NOT comparable across classes — gate actions on evidence_class, not the number:\n- \"osv_verified\": a security advisory matching one of the user's INSTALLED dependencies — safe to act on\n- \"dependency_grounded\": matched one of the user's declared dependencies — trustworthy\n- \"semantic_only\": topical/embedding relevance with NO dependency edge — surface to the human, verify before acting\n- \"keyword_heuristic\": standalone-mode keyword score (no Rust pipeline) — weakest signal\n\nCall when the user asks what to read, what is relevant to them, or for content on a topic.",
   "inputSchema": {
     "type": "object",
     "properties": {

package/dist/schemas/upgrade-planner.json

@@ -1,6 +1,6 @@
 {
   "name": "upgrade_planner",
-  "description": "Ranked upgrade recommendations for project dependencies. Combines vulnerability severity, deprecation status, and version distance to produce a prioritized upgrade plan.\n\nShows quick wins (safe patch/minor upgrades) separately from breaking changes (major version bumps). Call after dependency_health to plan your upgrade strategy.\n\nPrivacy: uses cached registry data. No additional network calls beyond what dependency_health already fetched.",
+  "description": "Ranked standalone upgrade recommendations for project dependencies — call before upgrading, adding, or auditing any dependency to pick the safest order. Combines vulnerability severity, deprecation status, and version distance into a prioritized plan.\n\nSplits recommendations three ways: quick wins (safe patch/minor upgrades), breaking changes (major version bumps), and transitive CVEs marked waiting_on_upstream (not declared in your manifest — the fix arrives via a parent package update or a lockfile refresh). Call dependency_health first for registry context and vulnerability_scan first for a CVE-aware plan; without a scan the output says it is CVE-blind.\n\nProvenance: standalone heuristic — a point-in-time plan from local lockfiles plus live registry/OSV lookups, not the 4DA desktop app's cross-project, version-confirmed plan.\n\nPrivacy: live mode may query public registries and OSV with package names and versions. It never sends source code.",
   "inputSchema": {
     "type": "object",
     "properties": {

package/dist/schemas/what-should-i-know.json

@@ -1,6 +1,6 @@
 {
   "name": "what_should_i_know",
-  "description": "Pre-task intelligence briefing. Given a task description and optional file paths, returns filtered advisories (security alerts, breaking changes), active decision windows, signal chains, relevant past decisions/memories, and a delegation assessment. Call this before starting any non-trivial task to get caught up on what matters.",
+  "description": "Pre-task intelligence briefing. Given a task description and optional file paths, returns filtered advisories (security alerts, breaking changes), active decision windows, signal chains, relevant past decisions/memories, and a delegation assessment. Call this before starting any non-trivial task to get caught up on what matters. If the task involves upgrading, adding, or auditing dependencies, follow with upgrade_planner for the ranked plan.",
   "inputSchema": {
     "type": "object",
     "properties": {

package/dist/tools/dependency-health.js

@@ -137,7 +137,7 @@ export async function executeDependencyHealth(_db, params, liveIntel) {
         parts.push("all healthy");
     return {
         scannedAt: new Date().toISOString(),
-        projectPath: process.cwd(),
+        projectPath: liveIntel.getProjectRoot() ?? process.cwd(),
         ecosystemsScanned: ecosystems,
         totalDeps: total,
         outdatedCount: outdated,

package/dist/tools/upgrade-planner.d.ts

@@ -1,9 +1,20 @@
 /**
  * upgrade_planner tool
  *
- * Ranked upgrade recommendations for project dependencies.
+ * Ranked standalone upgrade recommendations for project dependencies.
  * Combines version freshness, vulnerability data, and deprecation status
  * to produce a prioritized upgrade plan.
+ *
+ * Honesty contract (Phase 0 hardening):
+ * - Transitive CVEs are surfaced as `waiting_on_upstream` steps instead of
+ *   being counted-but-never-recommended. No dependency-graph parsing happens
+ *   here — parent mapping is the desktop core's job; the honest label is ours.
+ * - Output carries explicit heuristic provenance: this is a point-in-time
+ *   standalone plan, not the 4DA app's cross-project, version-confirmed plan.
+ * - `projectPath` reports the directory set the dependencies were actually
+ *   resolved from, not whatever `process.cwd()` happens to be.
+ * - When no vulnerability scan has run, the plan says so instead of silently
+ *   producing a CVE-blind ranking.
  */
 import type { FourDADatabase } from "../db.js";
 import type { LiveIntelligence } from "../live/index.js";
@@ -22,6 +33,12 @@ interface UpgradeRecommendation {
     reasons: string[];
     breaking: boolean;
     isDev: boolean;
+    /** Whether this package is declared in a manifest (direct) or only present via the lockfile (transitive). */
+    scope: "direct" | "transitive";
+    /** Direct deps you can bump yourself; transitive fixes arrive via a parent update or lockfile refresh. */
+    action: "upgrade_direct" | "waiting_on_upstream";
+    /** False when the dependency is gated behind a target spec not active on this host (label, never suppressed). */
+    platformActive: boolean;
 }
 interface UpgradePlanResult {
     generatedAt: string;
@@ -31,6 +48,13 @@ interface UpgradePlanResult {
     summary: string;
     quickWins: number;
     breakingChanges: number;
+    waitingOnUpstream: number;
+    /** False when no vulnerability scan has run this session — the ranking is then CVE-blind and says so. */
+    vulnerabilityDataAvailable: boolean;
+    provenance: {
+        mode: "standalone_heuristic";
+        note: string;
+    };
 }
 export declare const upgradePlannerTool: {
     name: string;

package/dist/tools/upgrade-planner.js

@@ -2,13 +2,27 @@
 /**
  * upgrade_planner tool
  *
- * Ranked upgrade recommendations for project dependencies.
+ * Ranked standalone upgrade recommendations for project dependencies.
  * Combines version freshness, vulnerability data, and deprecation status
  * to produce a prioritized upgrade plan.
+ *
+ * Honesty contract (Phase 0 hardening):
+ * - Transitive CVEs are surfaced as `waiting_on_upstream` steps instead of
+ *   being counted-but-never-recommended. No dependency-graph parsing happens
+ *   here — parent mapping is the desktop core's job; the honest label is ours.
+ * - Output carries explicit heuristic provenance: this is a point-in-time
+ *   standalone plan, not the 4DA app's cross-project, version-confirmed plan.
+ * - `projectPath` reports the directory set the dependencies were actually
+ *   resolved from, not whatever `process.cwd()` happens to be.
+ * - When no vulnerability scan has run, the plan says so instead of silently
+ *   producing a CVE-blind ranking.
  */
+import { maxSemver } from "../live/semver-utils.js";
+const PROVENANCE_NOTE = "Point-in-time heuristic from local lockfiles plus live registry/OSV lookups. " +
+    "Not the 4DA desktop app's cross-project, version-confirmed plan.";
 export const upgradePlannerTool = {
     name: "upgrade_planner",
-    description: "Ranked upgrade recommendations for dependencies. Prioritizes by vulnerability severity, deprecation, and version distance. Shows quick wins (patch/minor) vs breaking changes (major).",
+    description: "Ranked standalone upgrade recommendations for dependencies — call before upgrading, adding, or auditing any dependency to pick the safest order. Prioritizes by vulnerability severity (direct AND transitive), deprecation, and version distance. Splits quick wins (patch/minor) from breaking changes (major) and from transitive CVEs waiting on upstream. Run vulnerability_scan first for a CVE-aware plan. Privacy: live mode may query public registries and OSV with package names and versions; it never sends source code.",
     inputSchema: {
         type: "object",
         properties: {
@@ -28,6 +42,14 @@ export const upgradePlannerTool = {
         },
     },
 };
+const RISK_LEVELS = { low: 0, medium: 1, high: 2, critical: 3 };
+function severityToRisk(severities) {
+    if (severities.includes("critical"))
+        return "critical";
+    if (severities.includes("high"))
+        return "high";
+    return "medium";
+}
 export async function executeUpgradePlanner(_db, params, liveIntel) {
     if (!liveIntel || !liveIntel.isInitialized()) {
         return {
@@ -38,16 +60,20 @@ export async function executeUpgradePlanner(_db, params, liveIntel) {
             summary: "No project detected. Run from a directory with package.json, Cargo.toml, pyproject.toml, or go.mod.",
             quickWins: 0,
             breakingChanges: 0,
+            waitingOnUpstream: 0,
+            vulnerabilityDataAvailable: false,
+            provenance: { mode: "standalone_heuristic", note: PROVENANCE_NOTE },
         };
     }
     const includeDev = params.include_dev ?? false;
     let deps = liveIntel.getResolvedDeps();
     if (!includeDev)
         deps = deps.filter((d) => !d.isDev);
-    // Fetch registry data
+    // Fetch registry data (live lookups for direct deps; cached where fresh)
     const registryData = await liveIntel.fetchRegistryHealth(deps);
-    // Get vulnerability data
+    // Vulnerability data from the last scan this session (no network here).
     const vulnResult = liveIntel.getVulnerabilities();
+    const vulnerabilityDataAvailable = vulnResult !== null;
     const vulnsByPackage = new Map();
     if (vulnResult) {
         for (const v of vulnResult.vulnerabilities) {
@@ -58,31 +84,32 @@ export async function executeUpgradePlanner(_db, params, liveIntel) {
                 vulnId: v.vulnId,
                 summary: v.summary,
                 fixedVersion: v.fixedVersion,
+                platformActive: v.platformActive,
             });
         }
     }
-    // Build recommendations
+    // Build recommendations — direct deps (registry-informed)
     const recommendations = [];
+    const directPackages = new Set();
     for (const dep of registryData) {
+        directPackages.add(`${dep.ecosystem}\0${dep.name}`);
         const reasons = [];
         let risk = "low";
         let targetVersion = dep.latestStableVersion || dep.latestVersion;
+        let platformActive = true;
         // Check vulnerabilities
         const vulns = vulnsByPackage.get(dep.name);
         if (vulns && vulns.length > 0) {
-            const hasCritical = vulns.some((v) => v.severity === "critical");
-            const hasHigh = vulns.some((v) => v.severity === "high");
-            if (hasCritical)
-                risk = "critical";
-            else if (hasHigh)
-                risk = "high";
-            else
-                risk = "medium";
+            risk = severityToRisk(vulns.map((v) => v.severity));
             reasons.push(`${vulns.length} known CVE${vulns.length !== 1 ? "s" : ""} (${vulns.map((v) => v.vulnId).join(", ")})`);
+            if (vulns.every((v) => !v.platformActive)) {
+                platformActive = false;
+                reasons.push("Affected code is gated behind a target not active on this platform");
+            }
             // Use fixed version as target if available
-            const fixedVersions = vulns.map((v) => v.fixedVersion).filter(Boolean);
+            const fixedVersions = vulns.map((v) => v.fixedVersion).filter((f) => Boolean(f));
             if (fixedVersions.length > 0 && !targetVersion) {
-                targetVersion = fixedVersions[0];
+                targetVersion = maxSemver(fixedVersions);
             }
         }
         // Check deprecation
@@ -121,45 +148,101 @@ export async function executeUpgradePlanner(_db, params, liveIntel) {
             reasons,
             breaking: dep.versionsBehind?.label === "major",
             isDev: dep.isDev,
+            scope: "direct",
+            action: "upgrade_direct",
+            platformActive,
         });
     }
+    // Transitive vulnerable packages — previously counted in scan totals but
+    // never recommended. Surfaced as waiting_on_upstream with honest labels.
+    if (vulnResult) {
+        const transitive = new Map();
+        for (const v of vulnResult.vulnerabilities) {
+            if (v.isDirect)
+                continue;
+            if (directPackages.has(`${v.ecosystem}\0${v.package}`))
+                continue;
+            if (!includeDev && v.isDev && v.devScopeKnown)
+                continue;
+            const key = `${v.ecosystem}\0${v.package}`;
+            if (!transitive.has(key))
+                transitive.set(key, []);
+            transitive.get(key).push(v);
+        }
+        for (const entries of transitive.values()) {
+            const first = entries[0];
+            const fixedVersions = entries.map((e) => e.fixedVersion).filter((f) => Boolean(f));
+            const platformActive = !entries.every((e) => !e.platformActive);
+            const reasons = [
+                `${entries.length} known CVE${entries.length !== 1 ? "s" : ""} (${entries.map((e) => e.vulnId).join(", ")})`,
+                "Transitive dependency — not declared in your manifest; the fix arrives via a parent package update or a lockfile refresh",
+            ];
+            if (!platformActive) {
+                reasons.push("Affected code is gated behind a target not active on this platform");
+            }
+            recommendations.push({
+                package: first.package,
+                ecosystem: first.ecosystem,
+                currentVersion: first.currentVersion,
+                targetVersion: fixedVersions.length > 0 ? maxSemver(fixedVersions) : null,
+                upgradeType: "unknown",
+                risk: severityToRisk(entries.map((e) => e.severity)),
+                reasons,
+                breaking: false,
+                isDev: entries.every((e) => e.isDev),
+                scope: "transitive",
+                action: "waiting_on_upstream",
+                platformActive,
+            });
+        }
+    }
     // Filter by risk threshold
-    const riskLevels = { low: 0, medium: 1, high: 2, critical: 3 };
     const threshold = params.risk_threshold ?? "all";
     const filtered = threshold === "all"
         ? recommendations
-        : recommendations.filter((r) => riskLevels[r.risk] >= riskLevels[threshold]);
-    // Sort: critical > high > medium > low, then by breaking (non-breaking first for quick wins)
+        : recommendations.filter((r) => RISK_LEVELS[r.risk] >= RISK_LEVELS[threshold]);
+    // Sort: critical > high > medium > low, then fixable-now (direct) before
+    // waiting-on-upstream (transitive), then non-breaking first (quick wins).
     filtered.sort((a, b) => {
-        const riskDiff = riskLevels[b.risk] - riskLevels[a.risk];
+        const riskDiff = RISK_LEVELS[b.risk] - RISK_LEVELS[a.risk];
         if (riskDiff !== 0)
             return riskDiff;
+        if (a.scope !== b.scope)
+            return a.scope === "direct" ? -1 : 1;
         if (a.breaking !== b.breaking)
             return a.breaking ? 1 : -1;
         return 0;
     });
     const maxRecs = params.max_recommendations ?? 20;
     const limited = filtered.slice(0, maxRecs);
-    const quickWins = limited.filter((r) => !r.breaking).length;
-    const breakingChanges = limited.filter((r) => r.breaking).length;
+    const direct = limited.filter((r) => r.scope === "direct");
+    const quickWins = direct.filter((r) => !r.breaking).length;
+    const breakingChanges = direct.filter((r) => r.breaking).length;
+    const waitingOnUpstream = limited.filter((r) => r.scope === "transitive").length;
     // Summary
     const parts = [];
-    parts.push(`${limited.length} upgrade${limited.length !== 1 ? "s" : ""} recommended`);
-    if (quickWins > 0)
-        parts.push(`${quickWins} quick win${quickWins !== 1 ? "s" : ""} (patch/minor)`);
-    if (breakingChanges > 0)
-        parts.push(`${breakingChanges} breaking change${breakingChanges !== 1 ? "s" : ""} (major)`);
+    parts.push(`${limited.length} recommendation${limited.length !== 1 ? "s" : ""}`);
+    if (direct.length > 0)
+        parts.push(`${direct.length} fixable directly (${quickWins} quick win${quickWins !== 1 ? "s" : ""}, ${breakingChanges} breaking)`);
+    if (waitingOnUpstream > 0)
+        parts.push(`${waitingOnUpstream} transitive, waiting on upstream`);
     const criticalCount = limited.filter((r) => r.risk === "critical").length;
     if (criticalCount > 0)
         parts.push(`${criticalCount} critical`);
+    if (!vulnerabilityDataAvailable) {
+        parts.push("CVE data not loaded — run vulnerability_scan first for a security-aware plan");
+    }
     return {
         generatedAt: new Date().toISOString(),
-        projectPath: process.cwd(),
+        projectPath: liveIntel.getProjectRoot() ?? vulnResult?.projectPath ?? process.cwd(),
         totalDeps: deps.length,
         recommendations: limited,
         summary: parts.join(". ") + ".",
         quickWins,
         breakingChanges,
+        waitingOnUpstream,
+        vulnerabilityDataAvailable,
+        provenance: { mode: "standalone_heuristic", note: PROVENANCE_NOTE },
     };
 }
 //# sourceMappingURL=upgrade-planner.js.map

package/dist/tools/what-should-i-know.js

@@ -20,7 +20,7 @@ import { memoryEmbedText } from "./agent-memory.js";
 // ============================================================================
 export const whatShouldIKnowTool = {
     name: "what_should_i_know",
-    description: "Pre-task intelligence briefing. Given a task description and optional file paths, returns filtered advisories, decision windows, signal chains, relevant wisdom, and a delegation assessment. Call before starting any non-trivial task.",
+    description: "Pre-task intelligence briefing. Given a task description and optional file paths, returns filtered advisories, decision windows, signal chains, relevant wisdom, and a delegation assessment. Call before starting any non-trivial task. If the task involves upgrading, adding, or auditing dependencies, follow with upgrade_planner for the ranked plan.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/types.d.ts

@@ -42,6 +42,15 @@ export interface RelevantItem {
     signal_type: string | null;
     /** Pipeline-computed signal priority (critical, high, medium, low) */
     signal_priority: string | null;
+    /**
+     * Provenance of this item's relevance — how an autonomous agent should weight it.
+     * Scores alone are NOT comparable across classes; gate actions on this, not the float:
+     *  - "osv_verified": a security advisory matching one of YOUR installed dependencies — safe to act on
+     *  - "dependency_grounded": matched one of your declared dependencies — trustworthy
+     *  - "semantic_only": topical/embedding relevance with NO dependency edge — verify before acting
+     *  - "keyword_heuristic": standalone-mode keyword score (no Rust pipeline) — weakest signal
+     */
+    evidence_class: "osv_verified" | "dependency_grounded" | "semantic_only" | "keyword_heuristic";
 }
 /**
  * Explicit user interest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4da/mcp-server",
-  "version": "4.6.2",
+  "version": "4.6.3",
   "mcpName": "io.github.runyourempire/4da-mcp-server",
   "description": "Dependency intelligence for AI coding agents. Live CVE scanning, dependency health, upgrade planning, ecosystem news, decision memory — zero config, privacy-first. 9 tools standalone, 14 total with desktop app.",
   "type": "module",
@@ -85,8 +85,9 @@
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.11",
-    "@types/node": "^25.6.0",
+    "@types/node": "^26.0.1",
     "typescript": "^5.3.0",
+    "vite": "~7.3.5",
     "vitest": "^4.1.5"
   },
   "engines": {
@@ -99,7 +100,9 @@
     ],
     "overrides": {
       "fast-uri": ">=3.1.2",
-      "ip-address": "^10.1.1"
+      "ip-address": "^10.1.1",
+      "vite": ">=7.3.5 <8",
+      "esbuild": ">=0.28.1"
     }
   }
 }