@4da/mcp-server 6.0.2 → 6.1.0

package/dist/tools/briefing-task-scope.js

@@ -95,10 +95,103 @@ export function detectTaskPackages(task, files, deps, limit = 5) {
     packages.sort((a, b) => Number(b.direct) - Number(a.direct));
     return packages.slice(0, limit);
 }
-/** Major version of a version or a `7.x` / `v7` request; null when unreadable. */
-export function majorOf(version) {
-    const m = version ? /^v?(\d+)/.exec(version) : null;
-    return m ? Number(m[1]) : null;
+/** Words after a name that make it a family: "tauri plugins", "@tauri-apps packages". */
+const FAMILY_NOUNS = /^(?:plugins?|packages?|crates?|family|families|ecosystem|deps|dependencies|libraries|libs|modules|siblings)$/i;
+/**
+ * The package families a task names, as base names: "all tauri plugins",
+ * "tauri and its plugins", "@tauri-apps packages", "tauri-plugin-*",
+ * "@tauri-apps/*". A name alone ("bump tauri") is not a family.
+ */
+export function detectFamilyBases(task, files = []) {
+    const tokens = tokenize(`${task} ${files.join(" ")}`);
+    const bases = new Set();
+    let lastName = null;
+    tokens.forEach((token, i) => {
+        // Globs: "tauri-plugin-*" -> tauri, "@tauri-apps/*" -> @tauri-apps.
+        const glob = /^(@?[a-z0-9][\w.-]*?)(?:-plugin)?(?:[-_/]\*)$/.exec(token);
+        if (glob) {
+            bases.add(glob[1]);
+            return;
+        }
+        const next = tokens[i + 1];
+        if (next && FAMILY_NOUNS.test(next) && /^@?[a-z][\w.@/-]*$/.test(token) && !FAMILY_NOUNS.test(token)) {
+            if (!/^(?:all|every|its|their|the|other|any|some|these|those|related|official|first-party|in|of|for|with|from|our|my|your|and|or|to|dev|npm|cargo|pip|go|rust|js|node|python|workspace|root|outdated|vulnerable|new|old|unused|direct|transitive)$/.test(token)) {
+                bases.add(token);
+            }
+            else if (token === "its" || token === "their") {
+                // "tauri and its plugins": the name the possessive refers to.
+                if (lastName)
+                    bases.add(lastName);
+            }
+        }
+        if (/^@?[a-z][\w.@/-]*$/.test(token) && !FAMILY_NOUNS.test(token) && !/^(?:and|or|its|their|all|every|to|the|bump|upgrade|update)$/.test(token)) {
+            lastName = token;
+        }
+    });
+    return [...bases];
+}
+/** True when `name` belongs to the family of `base`: base-*, base_*, @base/*, @base-apps/*. */
+export function inFamily(name, base) {
+    const n = name.toLowerCase();
+    const b = base.toLowerCase();
+    if (n === b)
+        return false;
+    if (b.startsWith("@"))
+        return n.startsWith(`${b}/`);
+    return (n.startsWith(`${b}-`) ||
+        n.startsWith(`${b}_`) ||
+        n.startsWith(`@${b}/`) ||
+        n.startsWith(`@${b}-`) // @tauri-apps/api, @tauri-apps/plugin-shell
+    );
+}
+/**
+ * The direct dependencies in the families the task names, other than the
+ * packages it names exactly. Only packages this project actually declares:
+ * a family is expanded against the lockfiles, never guessed. Measured
+ * 2026-10-07: "bump tauri and all tauri plugins" matched only `tauri`.
+ */
+export function detectFamilyPackages(task, files, deps, exact, limit = 25) {
+    const bases = detectFamilyBases(task, files);
+    if (bases.length === 0)
+        return [];
+    const taken = new Set(exact.map((p) => `${p.ecosystem}\0${p.name}`));
+    const groups = new Map();
+    for (const dep of deps) {
+        if (!dep.name || !dep.isDirect)
+            continue;
+        const key = `${dep.ecosystem}\0${dep.name}`;
+        if (taken.has(key))
+            continue;
+        const base = bases.find((b) => inFamily(dep.name, b));
+        if (!base)
+            continue;
+        const group = groups.get(key) ?? { base, copies: [] };
+        group.copies.push(dep);
+        groups.set(key, group);
+    }
+    const out = [...groups.values()].map(({ base, copies }) => ({
+        name: copies[0].name,
+        ecosystem: copies[0].ecosystem,
+        installed: [...new Set(copies.map((d) => d.version).filter((v) => Boolean(v)))],
+        direct: true,
+        dev: copies.every((d) => d.isDev),
+        requested_from: null,
+        requested_to: null,
+        family: base,
+    }));
+    out.sort((a, b) => a.ecosystem.localeCompare(b.ecosystem) || a.name.localeCompare(b.name));
+    return out.slice(0, limit);
+}
+/** True when the task asks for the newest release ("to latest", "newest major"). */
+export function wantsLatest(task) {
+    return /\b(?:latest|newest|most recent)\b/i.test(task);
+}
+/** The caret line a version sits on: "2" for 2.12.1, "0.13" for 0.13.5. */
+export function caretLine(version) {
+    const m = version ? /^v?(\d+)\.(\d+)/.exec(version) : null;
+    if (!m)
+        return null;
+    return m[1] === "0" ? `0.${m[2]}` : m[1];
 }
 /** Actionable advisories on the installed copies of one package, highest presented severity first. */
 export function advisoriesFor(pkg, vulns) {

package/dist/tools/decision-memory.js

@@ -5,6 +5,7 @@
  * Manage developer decisions - record, list, check alignment, update, and supersede.
  * Decisions persist and inform signal classification, tech radar, and agent context.
  */
+import { writeMeta, writerOf } from "../memory-store.js";
 import { executeCheckDecisionAlignment } from "./decision-enforcement.js";
 // ============================================================================
 // Tool Definition
@@ -132,7 +133,10 @@ export function executeDecisionMemory(db, params) {
                     error: "subject and decision are required for record action",
                 };
             }
-            const stmt = rawDb.prepare(`INSERT INTO developer_decisions
+            // The app's own developer_decisions table (separate write connection), or
+            // the server's store when the app's schema cannot hold the row.
+            const to = writerOf(db, "developer_decisions", ["decision_type", "subject", "decision", "rationale", "alternatives_rejected", "context_tags", "confidence", "status"]);
+            const stmt = to.raw.prepare(`INSERT INTO developer_decisions
            (decision_type, subject, decision, rationale,
             alternatives_rejected, context_tags, confidence, status)
          VALUES (?, ?, ?, ?, ?, ?, ?, 'active')`);
@@ -141,6 +145,7 @@ export function executeDecisionMemory(db, params) {
                 success: true,
                 id: result.lastInsertRowid,
                 message: `Decision recorded: ${params.subject}`,
+                ...writeMeta(to),
             };
         }
         case "list": {
@@ -207,7 +212,8 @@ export function executeDecisionMemory(db, params) {
             }
             sets.push("updated_at = datetime('now')");
             values.push(params.id);
-            const updated = rawDb
+            const updater = writerOf(db, "developer_decisions", ["id", "updated_at", ...sets.map((s) => s.split(" ")[0])]);
+            const updated = updater.raw
                 .prepare(`UPDATE developer_decisions SET ${sets.join(", ")} WHERE id = ?`)
                 .run(...values);
             if (updated.changes === 0) {
@@ -229,7 +235,7 @@ export function executeDecisionMemory(db, params) {
             if (missing.length > 0) {
                 return { error: `No decision with id ${missing.join(" or ")}. Use action "list" to find ids.` };
             }
-            rawDb
+            writerOf(db, "developer_decisions", ["id", "status", "superseded_by", "updated_at"]).raw
                 .prepare(`UPDATE developer_decisions
            SET status = 'superseded',
                superseded_by = ?,

package/dist/tools/dependency-check-signals.d.ts

@@ -65,6 +65,13 @@ export declare function publishTrustSignal(item: CheckItem, to: ReleaseRecord, b
 export declare function installScriptSignal(item: CheckItem, to: ReleaseRecord, from: ReleaseRecord | null): Signal;
 export declare function newDependenciesSignal(to: ReleaseRecord, base: ReturnType<typeof selectBaseline>, introduced: string[] | null, created: Map<string, CreatedAtFact>): Signal;
 export declare function withdrawnSignal(item: CheckItem, to: ReleaseRecord): Signal;
+/**
+ * The bump's semver class. A breaking range (a major, or below 1.0 a minor or
+ * 0.0.x patch) is `review`: the supply-chain signals say nothing about whether
+ * the project's code survives it. Until 6.0.2 this was information only, so
+ * vitest 3 -> 5, reqwest 0.12 -> 0.13 and stripe 22 -> 23 all came back
+ * "proceed" and the summary told the agent to apply them (2026-10-07 eval).
+ */
 export declare function upgradeTypeSignal(item: CheckItem): Signal;
 export declare function upgradeType(from: string | undefined, to: string): "patch" | "minor" | "major" | "downgrade" | "none" | "new_dependency" | "unknown";
 /** The item verdict and its one-line reason, from the strongest signal effect. */

package/dist/tools/dependency-check-signals.js

@@ -222,11 +222,26 @@ export function withdrawnSignal(item, to) {
     }
     return { id: "yanked_or_deprecated", value: null, effect: "proceed", evidence: `${item.to} is neither yanked nor deprecated.` };
 }
+/**
+ * The bump's semver class. A breaking range (a major, or below 1.0 a minor or
+ * 0.0.x patch) is `review`: the supply-chain signals say nothing about whether
+ * the project's code survives it. Until 6.0.2 this was information only, so
+ * vitest 3 -> 5, reqwest 0.12 -> 0.13 and stripe 22 -> 23 all came back
+ * "proceed" and the summary told the agent to apply them (2026-10-07 eval).
+ */
 export function upgradeTypeSignal(item) {
     const kind = upgradeType(item.from, item.to);
     const text = item.from ? `${item.from} -> ${item.to}: ${kind}` : `new dependency at ${item.to}`;
-    const zeroX = kind === "major" && /^0\./.test(item.from ?? "") ? " (0.x: a minor bump is breaking)" : "";
-    return { id: "upgrade_type", value: kind, evidence: `${text}${zeroX}.`, effect: "info" };
+    if (kind === "major") {
+        const zeroX = /^0\./.test(item.from ?? "") ? " (below 1.0 a minor bump is a major one)" : "";
+        return {
+            id: "upgrade_type",
+            value: kind,
+            evidence: `${text}${zeroX}: breaking version range, run upgrade_impact to see what changes for this project.`,
+            effect: "review",
+        };
+    }
+    return { id: "upgrade_type", value: kind, evidence: `${text}.`, effect: "info" };
 }
 export function upgradeType(from, to) {
     if (!from)

package/dist/tools/dependency-check.d.ts

@@ -77,7 +77,7 @@ interface ItemResult {
     reason: string;
     signals: Signal[];
 }
-export declare function executeDependencyCheck(_db: FourDADatabase, params: DependencyCheckParams, liveIntel: LiveIntelligence | null, opts?: {
+export declare function executeDependencyCheck(_db: FourDADatabase | null, params: DependencyCheckParams, liveIntel: LiveIntelligence | null, opts?: {
     now?: Date;
 }): Promise<{
     checked_at: string;

package/dist/tools/dependency-check.js

@@ -45,7 +45,7 @@ export const dependencyCheckTool = {
         "- install_script_added (npm): `to` runs preinstall/install/postinstall and `from` did not -> review. For a new dependency, information only.",
         "- new_dependencies: runtime dependencies added since the baseline, each with its first-publish age. Any under 30 days old, or no longer on the registry -> review.",
         "- yanked_or_deprecated: `to` yanked, unpublished or deprecated -> avoid.",
-        "- upgrade_type: patch | minor | major (a 0.x minor counts as major) | downgrade | new_dependency. Information only.",
+        "- upgrade_type: patch | minor | major (a 0.x minor counts as major) | downgrade | new_dependency. major (a breaking version range) -> review: call upgrade_impact for what it changes. The others are information only.",
         "",
         "Verdict precedence: avoid > review > unknown > wait > proceed. `unknown` means a registry or OSV.dev lookup failed, or the package is not on the public registry (private package, or a misspelled/hallucinated name); it is never a silent proceed. Apply only `proceed` items; report the others with their evidence. For WHAT the bump changes in your code, call upgrade_impact.",
         "",

package/dist/tools/dependency-health.d.ts

@@ -41,4 +41,4 @@ export declare const dependencyHealthTool: {
         };
     };
 };
-export declare function executeDependencyHealth(_db: FourDADatabase, params: DependencyHealthParams, liveIntel: LiveIntelligence | null): Promise<DependencyHealthResult>;
+export declare function executeDependencyHealth(_db: FourDADatabase | null, params: DependencyHealthParams, liveIntel: LiveIntelligence | null): Promise<DependencyHealthResult>;

package/dist/tools/dependency-health.js

@@ -8,6 +8,7 @@
  */
 import { isActionableVulnerability } from "../live/maintenance.js";
 import { driftFor } from "./install-drift-notes.js";
+import { discoveryNote } from "../project-tree.js";
 /** How long a health check waits for its own OSV scan before answering without CVE data (the scan keeps running). */
 const HEALTH_SCAN_TIMEOUT_MS = 60_000;
 export const dependencyHealthTool = {
@@ -209,6 +210,10 @@ export async function executeDependencyHealth(_db, params, liveIntel) {
     if (hidden > 0) {
         parts.push(`${hidden} advisor${hidden !== 1 ? "ies" : "y"} not counted (platform-inactive or maintenance notices)`);
     }
+    // "all healthy" over a partial walk must say it is partial.
+    const partial = discoveryNote(liveIntel.getDiscovery());
+    if (partial)
+        parts.push(partial.replace(/[.]$/, ""));
     if (!vulnResult) {
         parts.push(liveIntel.isEnabled()
             ? `CVE data not loaded: the OSV scan did not finish within ${HEALTH_SCAN_TIMEOUT_MS / 1000}s or OSV was unreachable. Call again to use it once it completes`

package/dist/tools/knowledge-gap-ranges.d.ts

@@ -35,7 +35,7 @@ export declare function rangesContain(ranges: AdvisoryRangeEvent[][], installed:
  * An advisory naming your dependency is only a gap if you are actually
  * exposed: the live tool once graded three Hono CVEs `critical` on hono
  * 4.13.2 when all three are fixed in 4.12.34, a version this repo had already
- * pinned past via `pnpm.overrides`.
+ * pinned past via pnpm overrides.
  *
  * Conservative by construction: a missing or unreadable installed version
  * counts as AFFECTED. Never claim someone is safe on missing information.

package/dist/tools/knowledge-gap-ranges.js

@@ -105,7 +105,7 @@ export function rangesContain(ranges, installed) {
  * An advisory naming your dependency is only a gap if you are actually
  * exposed: the live tool once graded three Hono CVEs `critical` on hono
  * 4.13.2 when all three are fixed in 4.12.34, a version this repo had already
- * pinned past via `pnpm.overrides`.
+ * pinned past via pnpm overrides.
  *
  * Conservative by construction: a missing or unreadable installed version
  * counts as AFFECTED. Never claim someone is safe on missing information.

package/dist/tools/knowledge-gap-scope.d.ts

@@ -4,10 +4,10 @@
  * `temporal::{active_repo_roots, dep_within_active_root, shares_active_root}`
  * and `knowledge_decay::{get_active_project_paths, linked_to}`.
  */
-import type BetterSqlite3 from "better-sqlite3";
+import type { SqliteStatement } from "../sqlite-driver.js";
 import type { FourDADatabase } from "../db.js";
 /** `stmt.all(...)`, or [] when the statement cannot run: a read here never throws out of the tool. */
-export declare function allRows<T>(stmt: BetterSqlite3.Statement, ...args: unknown[]): T[];
+export declare function allRows<T>(stmt: SqliteStatement, ...args: unknown[]): T[];
 /** Lowercase, forward slashes, no trailing slash (`knowledge_decay::normalize_project_path`). */
 export declare function normPath(p: string): string;
 /**

package/dist/tools/project-scope.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Which project a planning or briefing answer is about.
+ *
+ * Measured 2026-10-07: upgrade_planner called from D:\4DA returned the 4DA
+ * app's cross-project plan, and its top steps were for navcal, verax and
+ * 4da-ledger. upgrade_planner and what_should_i_know now take `project_path`:
+ * omitted, it is the project the server was started for (FOURDA_PROJECT_DIR,
+ * else the working directory) when that directory is a project; `"*"` asks
+ * for every project.
+ */
+import type { FourDADatabase } from "../db.js";
+import { LiveIntelligence } from "../live/index.js";
+export declare const ALL_PROJECTS = "*";
+/** The project the server was started for: FOURDA_PROJECT_DIR (an unsubstituted "${...}" template is ignored), else cwd. */
+export declare function serverProjectDir(): string;
+/** True when `dir` holds a manifest or lockfile of a supported ecosystem. */
+export declare function isProjectDir(dir: string): boolean;
+/** Lowercased, forward slashes, no trailing slash: the form the app's plan stores project paths in. */
+export declare function normalizeProjectPath(p: string): string;
+/** True when `candidate` is `root` or inside it. */
+export declare function isWithin(candidate: string, root: string): boolean;
+export type ProjectScope = {
+    kind: "project";
+    path: string;
+    source: "argument" | "server_project";
+} | {
+    kind: "all";
+    reason: string;
+} | {
+    kind: "error";
+    error: string;
+};
+/**
+ * The scope for one call. An explicit path must be a directory on this
+ * machine; `"*"` is every project; omitted, the server's project when it is
+ * one, otherwise every project (a server started in a home directory has no
+ * project to narrow to).
+ */
+export declare function resolveProjectScope(projectPath: string | undefined): ProjectScope;
+/**
+ * The live layer for `scope`: the server's own when it already covers that
+ * root, otherwise a fresh one resolved from the project tree at that path (as
+ * vulnerability_scan does for its `project_path`).
+ */
+export declare function liveIntelFor<T extends Pick<LiveIntelligence, "getProjectRoot">>(liveIntel: T | null, db: FourDADatabase | null, scope: ProjectScope): T | LiveIntelligence | null;

package/dist/tools/project-scope.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Which project a planning or briefing answer is about.
+ *
+ * Measured 2026-10-07: upgrade_planner called from D:\4DA returned the 4DA
+ * app's cross-project plan, and its top steps were for navcal, verax and
+ * 4da-ledger. upgrade_planner and what_should_i_know now take `project_path`:
+ * omitted, it is the project the server was started for (FOURDA_PROJECT_DIR,
+ * else the working directory) when that directory is a project; `"*"` asks
+ * for every project.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getServerCacheDb } from "../live/cache.js";
+import { LiveIntelligence } from "../live/index.js";
+import { scanProjectTree, treeResolutionGroups } from "../project-tree.js";
+/** Files that make a directory a project (manifests and lockfiles of the supported ecosystems). */
+const PROJECT_MARKERS = [
+    "package.json",
+    "Cargo.toml",
+    "pyproject.toml",
+    "setup.py",
+    "requirements.txt",
+    "Pipfile",
+    "go.mod",
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "yarn.lock",
+    "bun.lock",
+    "Cargo.lock",
+    "poetry.lock",
+    "uv.lock",
+];
+export const ALL_PROJECTS = "*";
+/** The project the server was started for: FOURDA_PROJECT_DIR (an unsubstituted "${...}" template is ignored), else cwd. */
+export function serverProjectDir() {
+    const dir = process.env.FOURDA_PROJECT_DIR?.trim();
+    if (dir && !dir.includes("${"))
+        return dir;
+    return process.cwd();
+}
+/** True when `dir` holds a manifest or lockfile of a supported ecosystem. */
+export function isProjectDir(dir) {
+    return PROJECT_MARKERS.some((m) => {
+        try {
+            return fs.statSync(path.join(dir, m)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Lowercased, forward slashes, no trailing slash: the form the app's plan stores project paths in. */
+export function normalizeProjectPath(p) {
+    return path.resolve(p).replace(/\\/g, "/").toLowerCase().replace(/\/+$/, "");
+}
+/** True when `candidate` is `root` or inside it. */
+export function isWithin(candidate, root) {
+    const c = normalizeProjectPath(candidate);
+    const r = normalizeProjectPath(root);
+    return c === r || c.startsWith(`${r}/`);
+}
+/**
+ * The scope for one call. An explicit path must be a directory on this
+ * machine; `"*"` is every project; omitted, the server's project when it is
+ * one, otherwise every project (a server started in a home directory has no
+ * project to narrow to).
+ */
+export function resolveProjectScope(projectPath) {
+    const given = projectPath?.trim();
+    if (given === ALL_PROJECTS)
+        return { kind: "all", reason: 'project_path "*" asks for every project' };
+    if (given) {
+        const abs = path.resolve(given);
+        let isDir = false;
+        try {
+            isDir = fs.statSync(abs).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir) {
+            return {
+                kind: "error",
+                error: `project_path "${given}" is not a directory on this machine. Pass the absolute path of a project root, "*" for every project, or omit it for ${serverProjectDir()}.`,
+            };
+        }
+        return { kind: "project", path: abs, source: "argument" };
+    }
+    const own = serverProjectDir();
+    if (isProjectDir(own))
+        return { kind: "project", path: path.resolve(own), source: "server_project" };
+    return { kind: "all", reason: `the server's directory ${own} is not a project (no manifest or lockfile)` };
+}
+/**
+ * The live layer for `scope`: the server's own when it already covers that
+ * root, otherwise a fresh one resolved from the project tree at that path (as
+ * vulnerability_scan does for its `project_path`).
+ */
+export function liveIntelFor(liveIntel, db, scope) {
+    if (scope.kind !== "project" || !liveIntel)
+        return liveIntel;
+    const root = liveIntel.getProjectRoot();
+    if (root && normalizeProjectPath(root) === normalizeProjectPath(scope.path))
+        return liveIntel;
+    // A scope the server did not start for: resolve that tree. The connection
+    // is only used for its cache (LiveCache never writes to the app's database).
+    let raw;
+    try {
+        raw = db?.getRawDb();
+    }
+    catch {
+        raw = undefined;
+    }
+    const scoped = new LiveIntelligence(raw ?? getServerCacheDb());
+    const { entries, discovery } = scanProjectTree(scope.path);
+    scoped.initFromProjectTree(scope.path, treeResolutionGroups(entries), discovery);
+    return scoped;
+}

package/dist/tools/record-feedback.js

@@ -17,7 +17,7 @@ Feedback actions:
 - "dismiss": User dismissed the item
 - "mark_irrelevant": User said the item is not relevant (also records a relevance label)
 
-Only "save" and "mark_irrelevant" are relevance labels; they are what 4DA's accuracy measurement reads. Use them only when the user actually says whether the item matters to them. This does not train content preferences.`,
+Only "save" and "mark_irrelevant" are relevance labels. Use them only when the user actually says whether the item matters to them. This does not train content preferences. Recorded in the 4DA desktop app's own interactions/feedback tables.`,
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/upgrade-impact-literals.js

@@ -74,7 +74,7 @@ export async function flagOldSyntax(sections, files, root) {
     const candidates = sections
         .flatMap((s) => s.entries)
         .filter((e) => e.kind === "breaking" || e.kind === "deprecation")
-        .map((entry) => ({ entry, shapes: oldSyntaxShapes(entry.text) }))
+        .map((entry) => ({ entry, shapes: [entry.text, ...(entry.details ?? [])].flatMap(oldSyntaxShapes) }))
         .filter((c) => c.shapes.length > 0);
     if (!root || candidates.length === 0 || files.length === 0)
         return { newlyTouching: 0, examples: [] };

package/dist/tools/upgrade-impact-report.d.ts

@@ -24,6 +24,8 @@ export interface ReportEntry {
     text: string;
     /** The changelog heading or parent bullet the entry sits under ("Removed", "Breaking Changes"). */
     under?: string;
+    /** Bullets nested under the entry: part of it, not counted as entries of their own. */
+    details?: string[];
     touches_your_code?: boolean;
     matched_symbols?: string[];
     /** String literals in your code that use the syntax this entry retires (route patterns and the like). */
@@ -62,6 +64,14 @@ export type UpgradeType = "patch" | "minor" | "major" | "prerelease" | "unknown"
 export declare function upgradeType(from: string, to: string): UpgradeType;
 /** Major versions crossed (0.x minors count as majors, matching `upgradeType`). */
 export declare function majorsCrossed(from: string, to: string): number;
+/**
+ * `majorsCrossed` for versions as a task names them: "0.13", "7.x", "v2",
+ * "1.4.0". A partial version is read as the start of its line (0.13 ->
+ * 0.13.0, 7.x -> 7.0.0). Null when either side is unreadable. A plain
+ * major-number compare read reqwest 0.12 -> 0.13 as 0 majors crossed, and
+ * the briefing called a breaking upgrade safe to delegate.
+ */
+export declare function majorsCrossedLoose(from: string | null, to: string | null): number | null;
 /** Up to `count` published versions nearest to `wanted` by precedence, for "version not found" errors. */
 export declare function nearestVersions(published: string[], requested: string, count?: number): string[];
 export interface SummaryInput {

package/dist/tools/upgrade-impact-report.js

@@ -50,9 +50,15 @@ export function shapeChangelog(sections, symbols, format) {
             return true;
         });
         const entries = unique.map((e) => {
-            const entry = { kind: e.kind, text: e.text, ...(e.under ? { under: e.under } : {}) };
+            const entry = {
+                kind: e.kind,
+                text: e.text,
+                ...(e.under ? { under: e.under } : {}),
+                ...(e.details?.length ? { details: e.details } : {}),
+            };
             if (e.kind === "breaking" || e.kind === "deprecation") {
-                const matched = matchSymbols(e.text, symbols);
+                // The nested points name the affected functions (date-fns 3.0) as often as the entry does.
+                const matched = matchSymbols([e.text, ...(e.details ?? [])].join(" "), symbols);
                 if (matched.length > 0) {
                     entry.touches_your_code = true;
                     entry.matched_symbols = matched;
@@ -120,6 +126,9 @@ export function upgradeType(from, to) {
         return "major";
     if (a.major === 0 && a.minor !== b.minor)
         return "major";
+    // ^0.0.3 admits only 0.0.3: any 0.0.x change is breaking (dependency_health and dependency_check agree).
+    if (a.major === 0 && a.minor === 0 && a.patch !== b.patch)
+        return "major";
     if (a.minor !== b.minor)
         return "minor";
     return "patch";
@@ -134,6 +143,27 @@ export function majorsCrossed(from, to) {
         return Math.max(0, b.minor - a.minor);
     return Math.max(0, b.major - a.major);
 }
+/**
+ * `majorsCrossed` for versions as a task names them: "0.13", "7.x", "v2",
+ * "1.4.0". A partial version is read as the start of its line (0.13 ->
+ * 0.13.0, 7.x -> 7.0.0). Null when either side is unreadable. A plain
+ * major-number compare read reqwest 0.12 -> 0.13 as 0 majors crossed, and
+ * the briefing called a breaking upgrade safe to delegate.
+ */
+export function majorsCrossedLoose(from, to) {
+    const pad = (v) => {
+        const m = v ? /^v?(\d+)(?:\.(\d+|[x*]))?(?:\.(\d+|[x*]))?/i.exec(v.trim()) : null;
+        if (!m)
+            return null;
+        const num = (s) => (s === undefined || /[x*]/i.test(s) ? "0" : s);
+        return `${m[1]}.${num(m[2])}.${num(m[3])}`;
+    };
+    const a = pad(from);
+    const b = pad(to);
+    if (!a || !b)
+        return null;
+    return majorsCrossed(a, b);
+}
 /** Up to `count` published versions nearest to `wanted` by precedence, for "version not found" errors. */
 export function nearestVersions(published, requested, count = 5) {
     // "7" / "7.x" / "7.1" are not semver: read them as the start of that line,

package/dist/tools/upgrade-impact.js

@@ -287,7 +287,7 @@ function cacheFor(db) {
         return cache;
     }
     catch {
-        return null; // a read-only or closed database: run uncached rather than fail
+        return null; // a closed database: run uncached rather than fail (a read-only one uses the server cache file)
     }
 }
 export async function executeUpgradeImpact(db, params, liveIntel) {

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

@@ -0,0 +1,40 @@
+/**
+ * Fix-path verification for upgrade_planner steps (see live/fix-paths.ts):
+ * the target must clear EVERY known advisory of the package, and a
+ * transitive step is "waiting on upstream" only when a parent's declared
+ * requirement actually excludes every clean version.
+ *
+ * Runs on the steps the plan returns, within a time budget. A step whose
+ * lookups fail or run out of time keeps its unverified answer and says so in
+ * `fixPathChecked`.
+ */
+import type { LiveIntelligence } from "../live/index.js";
+/** The planner fields this step reads and rewrites. */
+export interface FixPathStep {
+    package: string;
+    ecosystem: string;
+    currentVersion: string | null;
+    targetVersion: string | null;
+    latestVersion?: string | null;
+    upgradeType: "patch" | "minor" | "major" | "unknown";
+    reasons: string[];
+    breaking: boolean;
+    scope: "direct" | "transitive";
+    action: string;
+    /** How the target was checked: against every advisory of the package, or only the installed version's. */
+    fixPathChecked?: "all_advisories" | "installed_advisories_only";
+    /** lockfile_refresh: the command per lockfile directory. */
+    refreshCommands?: Array<{
+        dir: string;
+        command: string;
+    }>;
+}
+export interface FixPathInput {
+    step: FixPathStep;
+    /** Per-advisory fixes on the installed line (each advisory's own fixedVersion). */
+    fixes: string[];
+    /** Manifest directories that pin this copy (the scan's sourceDirs). */
+    sourceDirs: string[];
+}
+/** Verify and rewrite the steps in place. Returns how many could not be verified (offline, failure, budget). */
+export declare function verifyFixPaths(inputs: FixPathInput[], liveIntel: Pick<LiveIntelligence, "getFixPathSources" | "lockfileFor" | "getProjectRoot">, budgetMs?: number): Promise<number>;