@luckychen1993/pm-mcp 0.1.2 → 0.1.4

package/dist/index-store.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { isInitialized } from "./paths.js";
 import { normSep } from "./budget.js";
 import { getIndex, getMeta, setMeta } from "./index-db.js";
+import { clearWatcherDirty, coordinateWatcherLeader, markWatcherDirty, watcherIsClean } from "./watcher-coordinator.js";
 export { aggregates, closeIndex, getIndex, getMeta, iterateFileRows, setMeta } from "./index-db.js";
 import { BINARY_EXTS, countLoc, isLockfile, isTestFile, extOf, countSkipLines, needsSkipCount, looksTrivialTest, DEFAULT_IGNORE_DIRS, walkStatEntries, } from "./scan.js";
 /**
@@ -160,7 +161,10 @@ export function walkRefresh(root, opts = {}) {
         const watcherSession = getMeta(db, "watcherSession");
         if (watcherSession !== null)
             setMeta(db, "lastWalkSession", watcherSession);
+        setMeta(db, "watcherError", "");
     }
+    clearWatcherDirty(root);
+    activeWatchers.get(path.resolve(root))?.reconciled();
     return { totalFiles: total, changed: processed, deleted: Number(del.changes ?? 0), hits: total - processed, skippedDeep };
 }
 const BEAT_STALE_MS = 90_000;
@@ -178,6 +182,8 @@ export function freshness(root) {
     const eventAge = lastEvent ? Date.now() - Date.parse(lastEvent) : Number.POSITIVE_INFINITY;
     const watcherSession = getMeta(db, "watcherSession");
     const sessionReconciled = watcherSession !== null && getMeta(db, "lastWalkSession") === watcherSession;
+    const watcherHealthy = !(getMeta(db, "watcherError") ?? "");
+    const watcherClean = watcherIsClean(root);
     // 卡死计数自愈：防抖 150ms，若计数>0 但 30s 无任何事件推进，说明计数器失真（如持锁期抛错），不再信任
     const pendingClean = pending === 0 || eventAge > 30_000;
     const fresh = files > 0 &&
@@ -185,6 +191,8 @@ export function freshness(root) {
         owned &&
         mode === "watcher" &&
         sessionReconciled &&
+        watcherHealthy &&
+        watcherClean &&
         pendingClean &&
         beatAge < BEAT_STALE_MS;
     return { mode, fresh, files, lastWalk, lastBeat, pendingEvents: pending };
@@ -232,29 +240,71 @@ export function drainWatcher(root) {
  */
 export function startWatcher(root) {
     const abs = path.resolve(root);
-    const db = getIndex(abs);
+    let db = null;
     let pending = 0;
     const timers = new Map();
-    let closed = false;
-    const ignored = (rel) => {
-        const first = rel.split("/")[0];
-        return DEFAULT_IGNORE_DIRS.has(first) || first === ".pm";
+    let watcher = null;
+    let beat = null;
+    let leader = false;
+    let stopped = false;
+    let locallyUnhealthy = false;
+    const active = {
+        timers,
+        closed: () => stopped || !leader,
+        reconciled: () => { locallyUnhealthy = false; },
+    };
+    const ignored = (rel) => DEFAULT_IGNORE_DIRS.has(rel.split("/")[0]) || rel.split("/")[0] === ".pm";
+    const recordWatcherError = (stage, error) => {
+        locallyUnhealthy = true;
+        try {
+            markWatcherDirty(abs);
+        }
+        catch (markerError) {
+            console.error(`[pm-mcp] watcher dirty marker failed: ${markerError instanceof Error ? markerError.message : String(markerError)}`);
+        }
+        console.error(`[pm-mcp] watcher ${stage} failed: ${error instanceof Error ? error.message : String(error)}`);
+        if (!db)
+            return;
+        try {
+            setMeta(db, "watcherError", new Date().toISOString());
+        }
+        catch (metaError) {
+            console.error(`[pm-mcp] watcher error state persistence failed: ${metaError instanceof Error ? metaError.message : String(metaError)}`);
+        }
     };
-    const bumpPending = (d) => {
+    const bumpPending = (d, allowClean = false) => {
         pending = Math.max(0, pending + d);
         try {
-            setMeta(db, "pending", String(pending));
+            if (pending > 0)
+                markWatcherDirty(abs);
+            if (db)
+                setMeta(db, "pending", String(pending));
+            if (pending === 0 && allowClean && !locallyUnhealthy)
+                clearWatcherDirty(abs);
         }
-        catch {
-            /* 库忙时持久化失败无所谓——内存计数仍准，meta 会随后续写收敛 */
+        catch (error) {
+            recordWatcherError("persist pending", error);
         }
     };
     const process = (rel) => {
-        if (closed)
+        if (stopped || !leader || !db)
             return;
+        let succeeded = false;
         try {
             const full = path.join(abs, ...rel.split("/"));
-            const st = fs.statSync(full);
+            let st;
+            try {
+                st = fs.statSync(full);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+                deleteFile(db, rel);
+                deleteSubtree(db, rel);
+                setMeta(db, "lastEvent", new Date().toISOString());
+                succeeded = true;
+                return;
+            }
             if (st.isDirectory()) {
                 // 新目录：补扫该子树（走 walkStatEntries 的 include 限定）
                 for (const e of walkStatEntries(abs, { include: [rel + "/**"] }, () => undefined)) {
@@ -267,107 +317,126 @@ export function startWatcher(root) {
                     return;
                 upsertFile(abs, db, rel, st, computeEntry(abs, rel, st));
             }
+            setMeta(db, "lastEvent", new Date().toISOString());
+            succeeded = true;
         }
-        catch {
-            // 消失了 → 删行
-            try {
-                deleteFile(db, rel);
-                deleteSubtree(db, rel);
-            }
-            catch {
-                /* ignore */
-            }
+        catch (error) {
+            // In particular, SQLITE_BUSY must never be reported as a successful
+            // watcher event. Mark the shared cache unhealthy; the next audit walks.
+            recordWatcherError(`event ${rel}`, error);
         }
         finally {
-            bumpPending(-1);
+            bumpPending(-1, succeeded);
+        }
+    };
+    const deactivateLeader = () => {
+        if (!leader)
+            return;
+        leader = false;
+        if (activeWatchers.get(abs) === active)
+            activeWatchers.delete(abs);
+        if (beat)
+            clearInterval(beat);
+        beat = null;
+        for (const entry of timers.values())
+            clearTimeout(entry.timer);
+        timers.clear();
+        pending = 0;
+        try {
+            watcher?.close();
+        }
+        catch { /* best effort */ }
+        watcher = null;
+        if (db) {
             try {
-                setMeta(db, "lastEvent", new Date().toISOString());
+                setMeta(db, "pending", "0");
+                setMeta(db, "mode", "walk");
             }
-            catch {
-                /* ignore */
+            catch (error) {
+                if (!(error instanceof Error && /database is not open/i.test(error.message)))
+                    recordWatcherError("demotion", error);
             }
         }
     };
-    let watcher;
-    try {
-        watcher = fs.watch(abs, { recursive: true }, (_event, filename) => {
-            if (closed || !filename)
-                return;
-            let rel;
-            try {
-                rel = normSep(String(filename));
-                if (ignored(rel))
+    const activateLeader = () => {
+        db = getIndex(abs);
+        try {
+            watcher = fs.watch(abs, { recursive: true }, (_event, filename) => {
+                if (stopped || !leader || !filename)
                     return;
-            }
-            catch {
-                return;
-            }
-            // 先建定时器再计数：即使计数持久化撞锁抛错，定时器也已就位（否则计数永不归零）
-            const prev = timers.get(rel);
-            if (prev) {
-                clearTimeout(prev.timer);
-                bumpPending(-1);
-            }
-            bumpPending(1);
-            const run = () => {
-                timers.delete(rel);
+                let rel;
                 try {
-                    process(rel);
+                    rel = normSep(String(filename));
+                    if (ignored(rel))
+                        return;
                 }
                 catch {
-                    bumpPending(-1);
+                    return;
                 }
-            };
-            timers.set(rel, { timer: setTimeout(run, 150), due: Date.now() + 150, run });
-        });
-    }
-    catch {
-        setMeta(db, "mode", "walk");
-        return null;
-    }
-    watcher.unref();
-    // 每次 watcher 启动都换一个会话代次。只有本次会话建立后的精确走查
-    // 会把 lastWalkSession 对齐，因此停机窗口内的增删改不可能被旧心跳掩盖。
-    setMeta(db, "watcherSession", randomUUID());
-    setMeta(db, "pending", "0");
-    setMeta(db, "mode", "watcher");
-    let stopped = false;
-    activeWatchers.set(abs, { timers, closed: () => stopped });
-    const beat = setInterval(() => {
-        if (closed)
-            return;
-        try {
-            setMeta(db, "lastBeat", new Date().toISOString());
-        }
-        catch {
-            /* ignore */
+                // 先建定时器再计数：即使计数持久化撞锁抛错，定时器也已就位（否则计数永不归零）
+                const prev = timers.get(rel);
+                if (prev) {
+                    clearTimeout(prev.timer);
+                }
+                else
+                    bumpPending(1);
+                const run = () => {
+                    timers.delete(rel);
+                    try {
+                        process(rel);
+                    }
+                    catch {
+                        bumpPending(-1);
+                    }
+                };
+                timers.set(rel, { timer: setTimeout(run, 150), due: Date.now() + 150, run });
+            });
         }
-    }, 10_000);
-    beat.unref();
-    // 立刻打一次心跳（避免刚启动的 90s 空窗被判不新鲜）
-    setMeta(db, "lastBeat", new Date().toISOString());
-    return {
-        stop() {
-            stopped = true;
-            activeWatchers.delete(abs);
-            closed = true;
-            clearInterval(beat);
-            for (const t of timers.values())
-                clearTimeout(t.timer);
-            try {
-                watcher.close();
-            }
-            catch {
-                /* ignore */
-            }
+        catch (error) {
             try {
                 setMeta(db, "mode", "walk");
             }
-            catch {
-                /* 库可能已被关闭（closeIndex 先行）——telemetry 失败无所谓 */
-            }
-        },
+            catch { /* freshness also requires a live heartbeat */ }
+            recordWatcherError("activation", error);
+            return null;
+        }
+        try {
+            watcher.unref();
+            leader = true;
+            // 每位 leader 都换一个会话代次。强杀/接管之间的停机窗口必须先精确走查。
+            setMeta(db, "watcherSession", randomUUID());
+            setMeta(db, "pending", "0");
+            setMeta(db, "watcherError", "");
+            setMeta(db, "mode", "watcher");
+            setMeta(db, "lastBeat", new Date().toISOString());
+            activeWatchers.set(abs, active);
+            beat = setInterval(() => {
+                if (stopped || !leader || !db)
+                    return;
+                try {
+                    setMeta(db, "lastBeat", new Date().toISOString());
+                    if (!(getMeta(db, "watcherError") ?? "") && watcherIsClean(abs))
+                        locallyUnhealthy = false;
+                }
+                catch (error) {
+                    recordWatcherError("heartbeat", error);
+                }
+            }, 10_000);
+            beat.unref();
+            return deactivateLeader;
+        }
+        catch (error) {
+            deactivateLeader();
+            throw error;
+        }
     };
+    const coordinator = coordinateWatcherLeader(abs, activateLeader, recordWatcherError);
+    if (!coordinator)
+        return null;
+    return { stop() { if (!stopped) {
+            stopped = true;
+            coordinator.stop();
+        } } };
 }
 /** 巡检/诊断用：索引概况一行 */
 export function indexSummary(root) {

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { resolveRoot, isInitialized } from "./paths.js";
+import { resolveRoot, isInitialized, ensurePmRuntimeIgnored } from "./paths.js";
 import { registerAllTools } from "./tools.js";
 import { loadRoadmap, loadTasks } from "./store.js";
 import { renderRoadmap } from "./roadmap.js";
@@ -14,6 +14,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { listAcceptanceBaselines } from "./acceptance-tools.js";
 import { AcceptanceReportSchema } from "./acceptance-report.js";
+import { runCoalescedRead } from "./idempotency.js";
 /* --root 参数 > PM_ROOT 环境变量 > 启动时工作目录 */
 const argv = process.argv.slice(2);
 let explicitRoot;
@@ -22,7 +23,13 @@ for (let i = 0; i < argv.length; i++) {
         explicitRoot = argv[i + 1];
 }
 const root = resolveRoot(explicitRoot);
-const server = new McpServer({ name: "pm-mcp", version: "0.1.2" });
+const server = new McpServer({ name: "pm-mcp", version: "0.1.4" }, {
+    instructions: [
+        "多 Agent 规则：相同业务的所有写工具调用必须携带相同 idempotency_key（建议 task-id:operation）；同键同参数只执行一次，同键不同参数会被拒绝。",
+        "完全相同的并行读请求会由服务端合并并复用结果；不要让多个分支重复请求同一工具和参数。",
+        "看到“幂等复用”时直接采用首次结果；看到“幂等占位/正在执行”时等待负责该业务的 Agent，不要换键重试。",
+    ].join(" "),
+});
 registerAllTools(server, root);
 /* -------------------------------- Resources ------------------------------- */
 function safeText(fn) {
@@ -33,30 +40,33 @@ function safeText(fn) {
         return `（不可用: ${e.message}）`;
     }
 }
-server.registerResource("dashboard", "pm://dashboard", { description: "项目仪表盘（与仓库根 PROJECT.md 同源），路线图/健康摘要/任务/功能清单" }, (uri) => ({
+async function resourceText(name, fn) {
+    return (await runCoalescedRead(root, `resource:${name}`, {}, () => safeText(fn))).text;
+}
+server.registerResource("dashboard", "pm://dashboard", { description: "项目仪表盘（与仓库根 PROJECT.md 同源），路线图/健康摘要/任务/功能清单" }, async (uri) => ({
     contents: [
         {
             uri: uri.href,
             mimeType: "text/markdown",
-            text: safeText(() => fs.readFileSync(dashboardFile(root), "utf8")),
+            text: await resourceText("dashboard", () => fs.readFileSync(dashboardFile(root), "utf8")),
         },
     ],
 }));
-server.registerResource("roadmap", "pm://roadmap", { description: "路线图（里程碑进度 + 活跃里程碑任务明细）" }, (uri) => ({
+server.registerResource("roadmap", "pm://roadmap", { description: "路线图（里程碑进度 + 活跃里程碑任务明细）" }, async (uri) => ({
     contents: [
         {
             uri: uri.href,
             mimeType: "text/markdown",
-            text: safeText(() => renderRoadmap(loadRoadmap(root).milestones, loadTasks(root).tasks, 2).join("\n")),
+            text: await resourceText("roadmap", () => renderRoadmap(loadRoadmap(root).milestones, loadTasks(root).tasks, 2).join("\n")),
         },
     ],
 }));
-server.registerResource("tasks", "pm://tasks", { description: "任务清单原始数据（tasks.json；超 100 条截断，完整数据用 list_tasks 过滤）" }, (uri) => ({
+server.registerResource("tasks", "pm://tasks", { description: "任务清单原始数据（tasks.json；超 100 条截断，完整数据用 list_tasks 过滤）" }, async (uri) => ({
     contents: [
         {
             uri: uri.href,
             mimeType: "application/json",
-            text: safeText(() => {
+            text: await resourceText("tasks", () => {
                 const tasks = loadTasks(root).tasks;
                 // 资源也要守 token 预算：全量 dump 大账本会吃爆上下文（截断后仍是合法 JSON）
                 if (tasks.length <= 100)
@@ -71,30 +81,30 @@ server.registerResource("tasks", "pm://tasks", { description: "任务清单原
         },
     ],
 }));
-server.registerResource("changelog", "pm://changelog", { description: "变更日志（由 sessions.json 生成的人类可读版本）" }, (uri) => ({
+server.registerResource("changelog", "pm://changelog", { description: "变更日志（由 sessions.json 生成的人类可读版本）" }, async (uri) => ({
     contents: [
         {
             uri: uri.href,
             mimeType: "text/markdown",
-            text: safeText(() => buildChangelog(root)),
+            text: await resourceText("changelog", () => buildChangelog(root)),
         },
     ],
 }));
-server.registerResource("architecture", "pm://architecture", { description: "跨文件/模块/语言治理审计：语义覆盖、依赖边界、接口、循环与质量矩阵" }, (uri) => ({
-    contents: [{ uri: uri.href, mimeType: "text/markdown", text: safeText(() => auditGovernance(root, 150).report) }],
+server.registerResource("architecture", "pm://architecture", { description: "跨文件/模块/语言治理审计：语义覆盖、依赖边界、接口、循环与质量矩阵" }, async (uri) => ({
+    contents: [{ uri: uri.href, mimeType: "text/markdown", text: await resourceText("architecture", () => auditGovernance(root, 150).report) }],
 }));
-server.registerResource("portfolio", "pm://portfolio", { description: "当前项目的组合视图与跨仓依赖/版本风险" }, (uri) => ({
+server.registerResource("portfolio", "pm://portfolio", { description: "当前项目的组合视图与跨仓依赖/版本风险" }, async (uri) => ({
     contents: [{
             uri: uri.href,
             mimeType: "application/json",
-            text: safeText(() => JSON.stringify(buildPortfolioReport({ projects: [loadPortfolioProject(root)], projectsRequested: 1 }), null, 2)),
+            text: await resourceText("portfolio", () => JSON.stringify(buildPortfolioReport({ projects: [loadPortfolioProject(root)], projectsRequested: 1 }), null, 2)),
         }],
 }));
-server.registerResource("acceptance", "pm://acceptance", { description: "标准化产品验收概览：版本化预批准基线与最近一次机器判定报告" }, (uri) => ({
+server.registerResource("acceptance", "pm://acceptance", { description: "标准化产品验收概览：版本化预批准基线与最近一次机器判定报告" }, async (uri) => ({
     contents: [{
             uri: uri.href,
             mimeType: "application/json",
-            text: safeText(() => {
+            text: await resourceText("acceptance", () => {
                 const reportDir = pmPath(root, "acceptance", "reports");
                 let latestReport = null;
                 if (fs.existsSync(reportDir)) {
@@ -203,8 +213,9 @@ await server.connect(new StdioServerTransport());
 // 超大项目核心：server 常驻期间用递归 watcher 持续保鲜 SQLite 索引，
 // audit/快照稳态下免全量走查（失败自动降级为纯走查模式）
 if (isInitialized(root)) {
+    ensurePmRuntimeIgnored(root);
     const watcher = startWatcher(root);
-    console.error(`[pm-mcp] watcher: ${watcher ? "active" : "unavailable（降级为按需全量走查）"}`);
+    console.error(`[pm-mcp] watcher coordinator: ${watcher ? "active（同项目单 leader）" : "unavailable（降级为按需全量走查）"}`);
 }
 // stdio 是协议通道，日志只能走 stderr
 console.error(`[pm-mcp] ready. project root: ${root}`);

package/dist/knowledge-tools.js

@@ -6,7 +6,7 @@ import { refreshDerived } from "./dashboard.js";
 import { decisionsDir, requireInitialized } from "./paths.js";
 import { formatCodeSearch, searchCode, searchKnowledge } from "./search.js";
 import { loadDebugLog, loadFeatures, loadFileNotes, loadProject, loadSessions, nextId, saveDebugLog, saveFeatures, saveFileNotes, saveSessions, } from "./store.js";
-import { budgetLines, tool, toolW } from "./tool-base.js";
+import { budgetLines, toolR, toolW } from "./tool-base.js";
 import { now } from "./types.js";
 export function registerFeatureTools(server, root) {
     toolW(server, root, "register_feature", "登记功能（回答「这个项目有哪些功能」）。entry_files=入口文件（漂移对账锚点），test_files=测试文件（测试背书）。", {
@@ -41,7 +41,7 @@ export function registerFeatureTools(server, root) {
             : "";
         return `✅ 功能 ${id}「${args.name}」已登记${args.module ? `（${args.module}）` : ""}。audit_structure 会核对其入口文件是否真实存在（防幻觉对账）。${hint}`;
     });
-    tool(server, "list_features", "列出功能清单（可按模块/状态过滤）。", { module: z.string().optional(), status: z.enum(["planned", "implemented", "deprecated"]).optional() }, (args) => {
+    toolR(server, root, "list_features", "列出功能清单（可按模块/状态过滤）。", { module: z.string().optional(), status: z.enum(["planned", "implemented", "deprecated"]).optional() }, (args) => {
         requireInitialized(root);
         let list = loadFeatures(root).features;
         if (args.module)
@@ -95,7 +95,7 @@ export function registerDecisionTools(server, root) {
         refreshDerived(root);
         return `✅ 决策已记录: .pm/decisions/${file}（不可变编号，git 友好）。search_knowledge 可检索。`;
     });
-    tool(server, "list_decisions", "列出全部架构决策（ADR）。", {}, () => {
+    toolR(server, root, "list_decisions", "列出全部架构决策（ADR）。", {}, () => {
         requireInitialized(root);
         const dir = decisionsDir(root);
         const names = fs.existsSync(dir) ? fs.readdirSync(dir).filter((n) => n.endsWith(".md")).sort() : [];
@@ -164,7 +164,7 @@ export function registerSessionTools(server, root) {
     });
 }
 export function registerSearchTools(server, root) {
-    tool(server, "search_code", "在真实代码里检索（防幻觉事中防线）：谈某个功能/文件之前先搜实码。返回 file:line 片段而非整文件（token 经济）。默认按字面量匹配；regex=true 时按 JavaScript 正则（仅在你确需时开启）。", {
+    toolR(server, root, "search_code", "在真实代码里检索（防幻觉事中防线）：谈某个功能/文件之前先搜实码。返回 file:line 片段而非整文件（token 经济）。默认按字面量匹配；regex=true 时按 JavaScript 正则（仅在你确需时开启）。", {
         query: z.string().min(1).describe("关键词（默认字面量匹配）"),
         glob: z.string().optional().describe("限定文件范围，如 src/**/*.ts"),
         max_results: z.number().int().min(1).max(100).optional().describe("默认 30"),
@@ -174,7 +174,7 @@ export function registerSearchTools(server, root) {
         const res = searchCode(root, args.query, args.glob, args.max_results ?? 30, args.regex ?? false);
         return formatCodeSearch(res, args.query);
     });
-    tool(server, "search_knowledge", "检索六类项目知识源（ADR/任务/功能/会话/调试记录/文件索引）——回答「之前为什么这么做」「上次这个错怎么解的」，用历史结论代替重新推理。代码内容请用 search_code。", { query: z.string().min(1) }, (args) => {
+    toolR(server, root, "search_knowledge", "检索六类项目知识源（ADR/任务/功能/会话/调试记录/文件索引）——回答「之前为什么这么做」「上次这个错怎么解的」，用历史结论代替重新推理。代码内容请用 search_code。", { query: z.string().min(1) }, (args) => {
         requireInitialized(root);
         return searchKnowledge(root, args.query);
     });

package/dist/license.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { loadFileNotes, loadProject } from "./store.js";
 import { isTestFile, readDirectDeps } from "./scan.js";
-import { ensureFresh, getIndex, iterateFileRows } from "./index-store.js";
+import { ensureFresh, getIndex, iterateFileRows, walkRefresh } from "./index-store.js";
 import { readText } from "./search.js";
 import { foldLines } from "./budget.js";
 /**
@@ -130,7 +130,9 @@ function readNodeLicenses(root) {
     return { list, truncated };
 }
 const GPL_HEADER = /GNU (LESSER |AFFERO )?GENERAL PUBLIC LICENSE/i;
-export function auditLicense(root, maxLines = 150) {
+export function auditLicense(root, maxLines = 150, forceFresh = false, indexPrepared = false) {
+    if (forceFresh)
+        walkRefresh(root, { forceContent: true });
     const project = loadProject(root);
     const rootPkg = path.join(root, "package.json");
     let pkgLicense = "";
@@ -207,7 +209,8 @@ export function auditLicense(root, maxLines = 150) {
     /* ③ 可疑许可证头 */
     L.push("");
     L.push("### ③ 源码中的 GPL 家族许可证头（复制带许可证代码的常见痕迹）");
-    ensureFresh(root);
+    if (!forceFresh && !indexPrepared)
+        ensureFresh(root);
     const hits = [];
     for (const row of iterateFileRows(getIndex(root))) {
         const rel = row.rel;
@@ -216,7 +219,7 @@ export function auditLicense(root, maxLines = 150) {
         // 测试文件常内嵌许可证字符串作为 fixture，不参与该启发式（信号针对混入源码的复制代码）
         if (isTestFile(rel))
             continue;
-        const content = readText(root, rel);
+        const content = readText(root, rel, forceFresh);
         if (content === null)
             continue;
         if (GPL_HEADER.test(content.split("\n").slice(0, 40).join("\n")))

package/dist/paths.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import fs from "node:fs";
 import os from "node:os";
+import { randomUUID } from "node:crypto";
 /** 项目根解析顺序：--root 参数 > PM_ROOT 环境变量 > 当前工作目录 */
 export function resolveRoot(explicit) {
     const raw = explicit?.trim() || process.env.PM_ROOT?.trim() || process.cwd();
@@ -48,4 +49,38 @@ export function ensurePmDirs(root) {
     fs.mkdirSync(pmPath(root), { recursive: true });
     fs.mkdirSync(decisionsDir(root), { recursive: true });
     fs.mkdirSync(snapshotsDir(root), { recursive: true });
+    ensurePmRuntimeIgnored(root);
+}
+/** 本机协调/缓存状态必须留在 .pm 内共享，但绝不能进入项目 Git。 */
+export function ensurePmRuntimeIgnored(root) {
+    const directory = pmPath(root);
+    fs.mkdirSync(directory, { recursive: true });
+    fs.mkdirSync(path.join(directory, ".runtime", "idempotency"), { recursive: true });
+    const file = path.join(directory, ".gitignore");
+    const required = [".lock", ".runtime/", "benchmarks/", "index.db*"];
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+        const lines = current.split(/\r?\n/).map((line) => line.trim());
+        const missing = required.filter((entry) => !lines.includes(entry));
+        if (missing.length === 0)
+            return;
+        const separator = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+        const content = `${current}${separator}${missing.join("\n")}\n`;
+        const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+        fs.writeFileSync(temporary, content, "utf8");
+        try {
+            fs.renameSync(temporary, file);
+        }
+        catch (error) {
+            try {
+                fs.rmSync(temporary, { force: true });
+            }
+            catch { /* best effort */ }
+            const converged = fs.existsSync(file) && required.every((entry) => fs.readFileSync(file, "utf8").split(/\r?\n/).map((line) => line.trim()).includes(entry));
+            if (converged)
+                return;
+            if (attempt === 2)
+                throw error;
+        }
+    }
 }

package/dist/project-tools.js

@@ -7,7 +7,7 @@ import { foldLines } from "./budget.js";
 import { loadGovernance } from "./governance-model.js";
 import { loadProject, loadRoadmap, loadSecurity, loadSessions, loadTasks, saveProject, saveRoadmap, } from "./store.js";
 import { now } from "./types.js";
-import { budgetLines, tool, toolW } from "./tool-base.js";
+import { budgetLines, toolI, toolR, toolW } from "./tool-base.js";
 function taskLine(t, withNext = false) {
     const parts = [`[${t.status}]`, t.id, t.title, `(${t.type}${t.milestone ? `,${t.milestone}` : ""})`];
     if (withNext && t.checkpoint) {
@@ -34,7 +34,7 @@ export function registerProjectTools(server, root) {
             "建议顺序: upsert_module 声明模块/owner/语言 → add_milestone 建里程碑 → add_task 拆任务 → 开工前 get_status / 收工后 log_session。",
         ].join("\n");
     });
-    tool(server, "get_status", "一站式「我在哪」：项目阶段 + 里程碑进度 + 进行中任务（含断点下一步）+ 健康摘要 + 最近变更。会话开工第一件事。since 可只看某日期以来的任务/会话变化。", { since: z.string().optional().describe("ISO 日期，如 2026-09-01：只看该日期以来的任务/会话变化") }, (args) => {
+    toolR(server, root, "get_status", "一站式「我在哪」：项目阶段 + 里程碑进度 + 进行中任务（含断点下一步）+ 健康摘要 + 最近变更。会话开工第一件事。since 可只看某日期以来的任务/会话变化。", { since: z.string().optional().describe("ISO 日期，如 2026-09-01：只看该日期以来的任务/会话变化") }, (args) => {
         requireInitialized(root);
         const project = loadProject(root);
         const { milestones } = loadRoadmap(root);
@@ -136,7 +136,7 @@ export function registerProjectTools(server, root) {
         refreshDerived(root);
         return `✅ 项目信息已更新（阶段: ${project.phase || "—"}，模块: ${project.modules.join(", ") || "—"}）。仪表盘已刷新。`;
     });
-    tool(server, "regenerate_dashboard", "手动重新生成 PROJECT.md 仪表盘与 changelog.md（正常情况下每次写操作已自动刷新）。", {}, () => {
+    toolI(server, root, "regenerate_dashboard", "手动重新生成 PROJECT.md 仪表盘与 changelog.md（正常情况下每次写操作已自动刷新）。", {}, () => {
         requireInitialized(root);
         refreshDerived(root);
         return "✅ PROJECT.md 与 changelog.md 已重新生成。";
@@ -196,7 +196,7 @@ export function registerRoadmapTools(server, root) {
         const s = milestoneStats(tasks, m.id);
         return [`✅ ${m.id} 已更新（${m.status}）。进度: ${s.done}/${s.total}（${s.pct}%）。`, ...warnings].join("\n");
     });
-    tool(server, "get_roadmap", "查看路线图。depth=1 每个里程碑一行摘要（功能再多也不乱）；depth=2 额外展开活跃里程碑的任务明细与断点。", { depth: z.number().int().min(1).max(2).optional().describe("默认 1") }, (args) => {
+    toolR(server, root, "get_roadmap", "查看路线图。depth=1 每个里程碑一行摘要（功能再多也不乱）；depth=2 额外展开活跃里程碑的任务明细与断点。", { depth: z.number().int().min(1).max(2).optional().describe("默认 1") }, (args) => {
         requireInitialized(root);
         const { milestones } = loadRoadmap(root);
         const { tasks } = loadTasks(root);

package/dist/search.js

@@ -74,7 +74,7 @@ let diskReadBytes = 0;
 let cacheHits = 0;
 let contentReadObserver = null;
 /** 读取文本内容：mtime+size 未变走进程缓存（server 常驻，二次搜索/扫描免重读）。返回 null=不可读/二进制。 */
-export function readText(root, rel) {
+export function readText(root, rel, force = false) {
     const abs = path.join(root, rel);
     // 缓存必须按“项目根 + 相对路径”隔离；仅用 rel 会让两个项目在
     // mtime/size 恰好相同时串用彼此内容，安全与许可证扫描会随之失真。
@@ -87,7 +87,7 @@ export function readText(root, rel) {
         return null;
     }
     const hit = contentCache.get(cacheKey);
-    if (hit && hit.mtime === st.mtimeMs && hit.size === st.size) {
+    if (!force && hit && hit.mtime === st.mtimeMs && hit.size === st.size) {
         // LRU touch
         contentCache.delete(cacheKey);
         contentCache.set(cacheKey, hit);