@luckychen1993/pm-mcp 0.1.3 → 0.1.4

package/dist/store.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
 import { DebugLogFileSchema, FeaturesFileSchema, FileNotesFileSchema, now, ProjectSchema, RoadmapFileSchema, SecurityFileSchema, SessionsFileSchema, TasksFileSchema, } from "./types.js";
 import { DEBUGLOG_JSON, EXTRA_RULES_FILE, FEATURES_JSON, FILE_NOTES_JSON, PROJECT_JSON, ROADMAP_JSON, SECURITY_JSON, SESSIONS_JSON, TASKS_JSON, pmPath, } from "./paths.js";
 import { ExtraRulesFileSchema } from "./types.js";
@@ -38,92 +39,208 @@ export function atomicWrite(file, content) {
 export function saveJson(file, data) {
     atomicWrite(file, JSON.stringify(data, null, 2) + "\n");
 }
+const FILE_LOCK_TIMEOUT_MS = 3_000;
+const FILE_LOCK_STALE_MS = 10_000;
+const FILE_LOCK_POLL_MS = 20;
+const FILE_LOCK_PROTOCOL = "sqlite-guard-v1";
+const FILE_LOCK_WAIT = new Int32Array(new SharedArrayBuffer(4));
+function readFileLockOwner(lockFile) {
+    let raw;
+    try {
+        raw = fs.readFileSync(lockFile, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Number.isSafeInteger(parsed.pid) || parsed.pid <= 0)
+            return null;
+        return {
+            pid: parsed.pid,
+            ...(typeof parsed.token === "string" && parsed.token.length > 0 ? { token: parsed.token } : {}),
+            ...(typeof parsed.created_at === "string" && parsed.created_at.length > 0 ? { created_at: parsed.created_at } : {}),
+            ...(typeof parsed.protocol === "string" && parsed.protocol.length > 0 ? { protocol: parsed.protocol } : {}),
+        };
+    }
+    catch {
+        const pid = Number(raw.trim());
+        return Number.isSafeInteger(pid) && pid > 0 ? { pid } : null;
+    }
+}
+function fileLockOwnerAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM proves that the process exists even when signalling it is forbidden.
+        return error.code === "EPERM";
+    }
+}
+function sqliteBusy(error) {
+    const candidate = error;
+    return candidate.errcode === 5 ||
+        (typeof candidate.message === "string" && /database is (?:locked|busy)/i.test(candidate.message));
+}
+function rollbackRecoveryGuard(db) {
+    if (!db.isTransaction)
+        return;
+    try {
+        db.exec("ROLLBACK");
+    }
+    catch {
+        // close() below is the final fail-safe and also rolls an open transaction back.
+    }
+}
 /**
- * 账本互斥锁：把「读账本 → 改 → 写」整个事务串行化，多客户端（如 ZCode+Codex 并行）
- * 不再互相覆盖丢数据。锁文件 .pm/.lock（O_EXCL 创建）；超过 10s 且持锁进程已死亡
- * 才视为残留并接管。活着的长任务不会被误抢锁；释放时也只删除自己的 token。
- * 等待上限 3s，超时明确报错而非静默丢写。
+ * 通用跨进程文件锁。SQLite 写事务覆盖 .lock 的检查、接管、创建、调用方临界区和
+ * 释放，从而消除 check-then-rm ABA，并在进程崩溃时由操作系统释放真实所有权。
+ * 成功取得同一 guard 后，带当前 protocol 的残留 .lock 可立即核销，即使 PID 已复用；
+ * 无 protocol 的旧版锁仍须「超过 staleMs 且 PID 已死」才接管，以兼容滚动升级。
+ * 释放必须完整匹配 protocol、PID、token 与 created_at，否则保留并 fail-closed。
+ * 共享同一 guardFile 的不同 lockFile 会串行，调用方应只在短元数据事务中共享 guard。
  */
-export function withLedgerLock(root, fn) {
-    const lockFile = pmPath(root, ".lock");
-    fs.mkdirSync(pmPath(root), { recursive: true });
+export function withFileRecoveryLock(lockFile, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? FILE_LOCK_TIMEOUT_MS;
+    const staleMs = options.staleMs ?? FILE_LOCK_STALE_MS;
+    const guardFile = options.guardFile ?? path.join(path.dirname(lockFile), ".file-recovery-guard.db");
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || !Number.isFinite(staleMs) || staleMs < 0) {
+        throw new RangeError("文件锁 timeoutMs 必须大于 0，staleMs 不得小于 0。");
+    }
+    fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+    fs.mkdirSync(path.dirname(guardFile), { recursive: true });
     const token = randomUUID();
-    const payload = JSON.stringify({ pid: process.pid, token, created_at: new Date().toISOString() });
-    const owner = () => {
+    const createdAt = new Date().toISOString();
+    const payload = JSON.stringify({ pid: process.pid, token, created_at: createdAt, protocol: FILE_LOCK_PROTOCOL });
+    const deadline = Date.now() + timeoutMs;
+    let fileLockHeld = false;
+    const acquireFileLock = () => {
         try {
-            const raw = fs.readFileSync(lockFile, "utf8");
-            try {
-                const parsed = JSON.parse(raw);
-                return typeof parsed.pid === "number"
-                    ? { pid: parsed.pid, ...(typeof parsed.token === "string" ? { token: parsed.token } : {}) }
-                    : null;
-            }
-            catch {
-                const pid = Number(raw.trim());
-                return Number.isInteger(pid) && pid > 0 ? { pid } : null;
-            }
+            fs.writeFileSync(lockFile, payload, { flag: "wx" });
+            return true;
         }
-        catch {
-            return null;
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
         }
-    };
-    const alive = (pid) => {
+        let stat;
         try {
-            process.kill(pid, 0);
-            return true;
+            stat = fs.statSync(lockFile);
         }
         catch (error) {
-            return error.code === "EPERM";
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+        const current = readFileLockOwner(lockFile);
+        const guardedResidual = current?.protocol === FILE_LOCK_PROTOCOL;
+        if (!guardedResidual && (Date.now() - stat.mtimeMs <= staleMs || (current && fileLockOwnerAlive(current.pid)))) {
+            return false;
+        }
+        // Every current-version acquirer and releaser holds the SQLite write transaction
+        // here, so no compliant peer can replace .lock between this removal and creation.
+        try {
+            fs.rmSync(lockFile);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
         }
-    };
-    const acquire = () => {
         try {
             fs.writeFileSync(lockFile, payload, { flag: "wx" });
             return true;
         }
-        catch {
+        catch (error) {
+            if (error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+    };
+    const beginGuard = (db, until) => {
+        while (Date.now() < until) {
+            const remaining = until - Date.now();
+            if (remaining <= 0)
+                return false;
+            db.exec(`PRAGMA busy_timeout=${Math.max(1, Math.min(100, remaining))}`);
             try {
-                const st = fs.statSync(lockFile);
-                const current = owner();
-                if (Date.now() - st.mtimeMs > 10_000 && (!current || !alive(current.pid))) {
-                    fs.rmSync(lockFile, { force: true });
-                    try {
-                        fs.writeFileSync(lockFile, payload, { flag: "wx" });
-                        return true;
-                    }
-                    catch {
-                        return false;
-                    }
-                }
+                db.exec("BEGIN IMMEDIATE");
+                return true;
             }
-            catch {
-                /* 锁文件刚好消失，下轮重试 */
+            catch (error) {
+                if (!sqliteBusy(error))
+                    throw error;
+                const pause = Math.min(FILE_LOCK_POLL_MS, Math.max(0, until - Date.now()));
+                if (pause > 0)
+                    Atomics.wait(FILE_LOCK_WAIT, 0, 0, pause);
             }
-            return false;
         }
+        return false;
     };
-    let held = false;
-    for (let i = 0; i < 150 && !held; i++) {
-        held = acquire();
-        if (!held)
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
-    }
-    if (!held) {
-        throw new Error("账本锁获取超时（3s）：另一进程正在写入本项目，请稍后重试。");
-    }
+    const acquisitionGuard = new DatabaseSync(guardFile);
     try {
-        return fn();
+        while (!fileLockHeld && Date.now() < deadline) {
+            if (!beginGuard(acquisitionGuard, deadline))
+                break;
+            try {
+                fileLockHeld = acquireFileLock();
+            }
+            catch (error) {
+                rollbackRecoveryGuard(acquisitionGuard);
+                throw error;
+            }
+            if (!fileLockHeld) {
+                rollbackRecoveryGuard(acquisitionGuard);
+                const pause = Math.min(FILE_LOCK_POLL_MS, Math.max(0, deadline - Date.now()));
+                if (pause > 0)
+                    Atomics.wait(FILE_LOCK_WAIT, 0, 0, pause);
+            }
+        }
+        if (!fileLockHeld) {
+            throw new Error(options.timeoutMessage ?? "文件锁获取超时（3s），请稍后重试。");
+        }
+        try {
+            return fn();
+        }
+        finally {
+            try {
+                const current = readFileLockOwner(lockFile);
+                if (current?.protocol === FILE_LOCK_PROTOCOL &&
+                    current.pid === process.pid &&
+                    current.token === token &&
+                    current.created_at === createdAt) {
+                    fs.rmSync(lockFile);
+                }
+            }
+            catch {
+                // Ownership cannot be proven: leave the file for guarded recovery.
+            }
+        }
     }
     finally {
+        rollbackRecoveryGuard(acquisitionGuard);
         try {
-            if (owner()?.token === token)
-                fs.rmSync(lockFile, { force: true });
+            acquisitionGuard.close();
         }
         catch {
-            /* 尽力释放 */
+            /* close after rollback is best effort */
         }
     }
 }
+/**
+ * 账本专用互斥锁：把「读账本 → 改 → 写」整个事务串行化。活着的长任务不会被误抢，
+ * 等待上限 3s，超时明确报错而非静默丢写。
+ */
+export function withLedgerLock(root, fn) {
+    const runtimeDirectory = pmPath(root, ".runtime");
+    return withFileRecoveryLock(pmPath(root, ".lock"), fn, {
+        guardFile: path.join(runtimeDirectory, "ledger-lock.db"),
+        timeoutMessage: "账本锁获取超时（3s）：另一进程正在写入本项目，请稍后重试。",
+    });
+}
 export function loadJson(file, schema, fallback) {
     if (!fs.existsSync(file))
         return fallback;

package/dist/tool-base.js

@@ -20,12 +20,12 @@ function writeSchema(schema) {
     };
 }
 /** 同步写工具：业务幂等占位 + 跨进程账本锁覆盖完整读-改-写。 */
-export function toolW(server, root, name, description, schema, fn) {
+export function toolW(server, root, name, description, schema, fn, prepare) {
     server.registerTool(name, { description: `${description} ${idempotencyDescription}`, inputSchema: writeSchema(schema), annotations: { readOnlyHint: false } }, ((args) => {
         try {
-            const result = runIdempotentWriteSync(root, name, args, fn);
+            const result = runIdempotentWriteSync(root, name, args, fn, prepare);
             const prefix = result.replayed ? `↩️ 幂等复用 ${result.key}\n` : result.pending ? `⏳ 幂等占位 ${result.key}\n` : "";
-            return { content: [{ type: "text", text: prefix + result.text }] };
+            return { content: [{ type: "text", text: prefix + result.text }], ...(result.pending ? { isError: true } : {}) };
         }
         catch (error) {
             return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };
@@ -38,7 +38,7 @@ export function toolI(server, root, name, description, schema, fn) {
         try {
             const result = await runIdempotentWrite(root, name, args, fn);
             const prefix = result.replayed ? `↩️ 幂等复用 ${result.key}\n` : result.pending ? `⏳ 幂等占位 ${result.key}\n` : "";
-            return { content: [{ type: "text", text: prefix + result.text }] };
+            return { content: [{ type: "text", text: prefix + result.text }], ...(result.pending ? { isError: true } : {}) };
         }
         catch (error) {
             return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };

package/dist/watcher-coordinator.js

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+const ELECTION_POLL_MS = 1_000;
+const ELECTION_BUSY_MS = 20;
+export function watcherDirtyFile(root) {
+    return path.join(path.resolve(root), ".pm", ".runtime", "watcher-dirty");
+}
+export function markWatcherDirty(root) {
+    const file = watcherDirtyFile(root);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${new Date().toISOString()}\n`, "utf8");
+}
+export function clearWatcherDirty(root) {
+    try {
+        fs.rmSync(watcherDirtyFile(root));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+export function watcherIsClean(root) {
+    return !fs.existsSync(watcherDirtyFile(root));
+}
+function sqliteBusy(error) {
+    const candidate = error;
+    return candidate.errcode === 5 ||
+        (typeof candidate.message === "string" && /database is (?:locked|busy)/i.test(candidate.message));
+}
+function openElection(root) {
+    const file = path.join(path.resolve(root), ".pm", ".runtime", "watcher-leader.db");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const db = new DatabaseSync(file);
+    try {
+        db.exec(`PRAGMA busy_timeout=${ELECTION_BUSY_MS}`);
+        return db;
+    }
+    catch (error) {
+        try {
+            db.close();
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+function acquire(db) {
+    if (db.isTransaction)
+        return true;
+    try {
+        // Avoid startup DDL so late standbys can join while a leader holds the DB.
+        // The transactional header write forces ownership even when an empty DB
+        // would otherwise defer materializing the write reservation on this OS.
+        db.exec("BEGIN IMMEDIATE");
+        db.exec("PRAGMA user_version=1");
+        return true;
+    }
+    catch (error) {
+        if (db.isTransaction) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch { /* close remains the fail-safe */ }
+        }
+        if (sqliteBusy(error))
+            return false;
+        throw error;
+    }
+}
+function release(db) {
+    if (db.isTransaction)
+        db.exec("ROLLBACK");
+}
+/**
+ * Elect exactly one watcher with a dedicated SQLite write transaction held for
+ * its lifetime. The OS releases the transaction after a force kill; standbys
+ * poll and take over without PID guesses, leases, or stale-file deletion.
+ */
+export function coordinateWatcherLeader(root, activate, report) {
+    let election;
+    try {
+        election = openElection(root);
+    }
+    catch (error) {
+        report("leader election unavailable", error);
+        return null;
+    }
+    let cleanup = null;
+    let timer = null;
+    let stopped = false;
+    let unavailable = false;
+    const relinquish = () => {
+        try {
+            cleanup?.();
+        }
+        catch (error) {
+            report("leader cleanup", error);
+        }
+        cleanup = null;
+        try {
+            release(election);
+        }
+        catch (error) {
+            report("leadership release", error);
+            unavailable = true;
+            try {
+                election.close();
+            }
+            catch { /* OS close releases the transaction */ }
+        }
+    };
+    const elect = () => {
+        if (stopped || unavailable || cleanup)
+            return;
+        let acquired = false;
+        try {
+            acquired = acquire(election);
+        }
+        catch (error) {
+            report("leader election", error);
+            unavailable = true;
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            try {
+                election.close();
+            }
+            catch { /* best effort */ }
+            return;
+        }
+        if (!acquired)
+            return;
+        try {
+            const activated = activate();
+            if (!activated)
+                unavailable = true;
+            else
+                cleanup = activated;
+        }
+        catch (error) {
+            report("leader activation", error);
+        }
+        if (!cleanup)
+            relinquish();
+        if (unavailable) {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            stopped = true;
+            try {
+                election.close();
+            }
+            catch { /* best effort */ }
+        }
+    };
+    elect();
+    if (unavailable) {
+        try {
+            election.close();
+        }
+        catch { /* best effort */ }
+        return null;
+    }
+    timer = setInterval(elect, ELECTION_POLL_MS);
+    timer.unref();
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            relinquish();
+            try {
+                election.close();
+            }
+            catch { /* best effort */ }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckychen1993/pm-mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "AI 编码项目的单一事实来源 + 健康台账 MCP 服务（事实来源 / 路线图 / 防幻觉 / 七本账 / 断点续做 / token 经济）",
   "keywords": [
     "mcp",