@luckychen1993/pm-mcp 0.1.3 → 0.1.5

package/dist/security.js

@@ -1,8 +1,10 @@
+import fs from "node:fs";
+import path from "node:path";
 import { createHash } from "node:crypto";
 import { loadExtraRules, loadProject, loadSecurity, saveSecurity } from "./store.js";
 import { latestSnapshot } from "./audit.js";
 import { 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 { now } from "./types.js";
 const SECRET_PATTERNS = [
@@ -69,8 +71,37 @@ function findSecretRule(value) {
 function fingerprint(ruleId, rel, matched) {
     return createHash("sha1").update(ruleId + "|" + rel + "|" + matched).digest("hex").slice(0, 16);
 }
-function scanDetections(root) {
+/** 只有根内普通路径的 ENOENT 才证明删除；权限错误、目录和链接均不证明修复。 */
+function findingFileState(root, rel) {
+    const parts = rel.replace(/\\/g, "/").split("/");
+    if (path.isAbsolute(rel) || parts.some((part) => !part || part === "." || part === ".."))
+        return "unknown";
+    let current = root;
+    let stat;
+    for (const part of parts) {
+        current = path.join(current, part);
+        try {
+            stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink())
+                return "unknown";
+        }
+        catch (error) {
+            return error.code === "ENOENT" ? "missing" : "unknown";
+        }
+    }
+    return stat?.isFile() ? "file" : "unknown";
+}
+function scanDetections(root, forceContent = false, indexPrepared = false) {
     const out = [];
+    // 只跟踪已有 open 发现，不为百万文件仓库额外物化整棵扫描覆盖表。
+    const pending = loadSecurity(root).findings.filter((finding) => finding.status === "open");
+    const byFile = new Map();
+    for (const finding of pending) {
+        const entries = byFile.get(finding.file) ?? [];
+        entries.push(finding);
+        byFile.set(finding.file, entries);
+    }
+    const checkedFindings = new Map();
     const rules = [...SECRET_PATTERNS, ...DANGEROUS_PATTERNS];
     // 用户自定义规则
     for (const r of loadExtraRules(root).rules) {
@@ -87,7 +118,8 @@ function scanDetections(root) {
             /* 非法自定义规则跳过 */
         }
     }
-    ensureFresh(root);
+    if (!indexPrepared)
+        ensureFresh(root);
     const db = getIndex(root);
     // .env 类文件存在性检查（是否被 git 提交需人工确认）
     for (const row of iterateFileRows(db, { excludeOversize: false })) {
@@ -109,9 +141,10 @@ function scanDetections(root) {
             continue;
         if (rel.startsWith(".pm/"))
             continue;
-        const content = readText(root, rel);
+        const content = readText(root, rel, forceContent);
         if (content === null)
             continue;
+        const contentDigest = byFile.has(rel) ? createHash("sha256").update(content).digest("hex") : undefined;
         const lines = content.split("\n");
         for (const rule of rules) {
             if (rule.glob && !rule.glob.test(rel))
@@ -130,15 +163,33 @@ function scanDetections(root) {
                     message: rule.message,
                 });
             }
+            for (const finding of byFile.get(rel) ?? []) {
+                if (finding.rule === rule.id)
+                    checkedFindings.set(finding.fingerprint, contentDigest);
+            }
         }
     }
-    return out;
+    for (const finding of pending) {
+        if (!checkedFindings.has(finding.fingerprint) && findingFileState(root, finding.file) === "missing") {
+            checkedFindings.set(finding.fingerprint, null);
+        }
+    }
+    return { detections: out, checkedFindings };
+}
+/** 昂贵的全仓扫描阶段；调用方可在账本锁外完成，再把脱敏发现提交到账本。 */
+export function prepareSecurityAudit(root, options = {}) {
+    const forceIndex = options.forceIndex ?? true;
+    const forceContent = options.forceContent ?? true;
+    if (forceIndex)
+        walkRefresh(root, { forceContent: true });
+    return scanDetections(root, forceContent, forceIndex || options.indexPrepared === true);
 }
 /** 扫描并更新台账（幂等：重复扫描不产生重复条目） */
-export function auditSecurity(root) {
+export function auditSecurity(root, prepared) {
     const project = loadProject(root);
     const stamp = now();
-    const detections = scanDetections(root);
+    const scan = prepared ?? scanDetections(root);
+    const detections = scan.detections;
     const security = loadSecurity(root);
     const existing = new Map(security.findings.map((f) => [f.fingerprint, f]));
     const acceptedRefound = [];
@@ -177,10 +228,25 @@ export function auditSecurity(root) {
             });
         }
     }
-    // 不再检出且仍 open 的 → 自动转 fixed（附注说明）
+    // 没有命中不等于已修复：必须证明该旧发现的文件/规则已检查，或文件确已删除。
     let autoFixed = 0;
+    let unverified = 0;
+    const currentDigests = new Map();
     for (const f of security.findings) {
         if (f.status === "open" && !seen.has(f.fingerprint)) {
+            const expected = scan.checkedFindings?.get(f.fingerprint);
+            let confirmed = expected === null && findingFileState(root, f.file) === "missing";
+            if (typeof expected === "string") {
+                if (!currentDigests.has(f.file)) {
+                    const content = findingFileState(root, f.file) === "file" ? readText(root, f.file, true) : null;
+                    currentDigests.set(f.file, content === null ? null : createHash("sha256").update(content).digest("hex"));
+                }
+                confirmed = currentDigests.get(f.file) === expected;
+            }
+            if (!confirmed) {
+                unverified += 1;
+                continue;
+            }
             f.status = "fixed";
             f.note += "（自动：最近一次扫描未再检出）";
             autoFixed += 1;
@@ -227,7 +293,9 @@ export function auditSecurity(root) {
         }
     }
     if (autoFixed > 0)
-        L.push(`自动关闭 ${autoFixed} 个（代码中已不再出现）。`);
+        L.push(`自动关闭 ${autoFixed} 个（已成功重扫未命中或确认文件删除）。`);
+    if (unverified > 0)
+        L.push(`⚠️ 扫描覆盖不足：${unverified} 个旧发现未获得完整检查证据，保持未解决状态（检查文件大小、可读性、扫描范围和规则）。`);
     if (newDeps.length > 0)
         L.push(`⚠️ 上次快照后新增依赖: ${newDeps.join(", ")}（AI 引入的依赖请审查来源与必要性）`);
     if (riskyDeps.length > 0)

package/dist/setup.js

@@ -2,11 +2,15 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-export const PACKAGE_SPEC = "@luckychen1993/pm-mcp@0.1.3";
+import { createHash, randomUUID } from "node:crypto";
+import { initProject } from "./init.js";
+import { isInitialized } from "./paths.js";
+import { refreshDerived } from "./dashboard.js";
+export const PACKAGE_SPEC = "@luckychen1993/pm-mcp@0.1.5";
 export const SERVER_NAME = "pm-mcp";
 const CLIENTS = ["codex", "claude", "zcode", "cursor", "vscode"];
 export function parseSetupArgs(argv) {
-    const options = { client: "auto", force: false, dryRun: false, help: false };
+    const options = { client: "auto", force: false, dryRun: false, help: false, project: false };
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === "--client") {
@@ -17,6 +21,14 @@ export function parseSetupArgs(argv) {
             options.client = value;
             index += 1;
         }
+        else if (arg === "--project") {
+            options.project = true;
+            const value = argv[index + 1];
+            if (value && !value.startsWith("--")) {
+                options.projectDir = value;
+                index += 1;
+            }
+        }
         else if (arg === "--force") {
             options.force = true;
         }
@@ -82,7 +94,7 @@ export function mergeJsonServer(document, shape) {
 }
 function backupName(file) {
     const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "");
-    return `${file}.backup-${stamp}-${process.pid}`;
+    return `${file}.backup-${stamp}-${process.pid}-${randomUUID()}`;
 }
 export function writeJsonClientConfig(file, shape, dryRun = false) {
     const absolute = path.resolve(file);
@@ -146,6 +158,86 @@ function appendCodexConfig(file, dryRun, log) {
     const block = `${separator}\n[mcp_servers.${SERVER_NAME}]\ncommand = "npx"\nargs = ["-y", "${PACKAGE_SPEC}"]\n`;
     fs.appendFileSync(absolute, block, "utf8");
 }
+function canonicalProjectRoot(projectRoot) {
+    const absolute = path.resolve(projectRoot);
+    let resolved;
+    try {
+        resolved = fs.realpathSync.native(absolute);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        resolved = absolute;
+    }
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function legacyProjectServerKey(projectRoot) {
+    const base = path.basename(projectRoot);
+    const safe = base.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    return `${SERVER_NAME}-${safe || "project"}`;
+}
+/** 完整规范路径参与命名，区分中文目录和位于不同父目录下的同名项目。 */
+export function codexProjectServerKey(projectRoot) {
+    const canonical = canonicalProjectRoot(projectRoot);
+    return `${legacyProjectServerKey(canonical)}-${createHash("sha256").update(canonical).digest("hex").slice(0, 12)}`;
+}
+/** 只解析本安装器生成的单行 JSON 兼容 args；手写复杂 TOML 不猜测其绑定。 */
+function projectEntry(text, server) {
+    const header = new RegExp(`^\\s*\\[mcp_servers\\.(?:${server}|"${server}"|'${server}')\\]\\s*(?:#.*)?$`, "m").exec(text);
+    if (!header)
+        return undefined;
+    const tail = text.slice(header.index + header[0].length);
+    const nextHeader = tail.search(/^\s*\[/m);
+    const section = nextHeader < 0 ? tail : tail.slice(0, nextHeader);
+    const argsLine = /^\s*args\s*=\s*(\[[^\r\n]*\])\s*(?:#.*)?$/m.exec(section);
+    try {
+        const args = argsLine ? JSON.parse(argsLine[1]) : undefined;
+        if (!Array.isArray(args) || !args.every((value) => typeof value === "string"))
+            return {};
+        const positions = args.flatMap((value, index) => value === "--root" ? [index] : []);
+        if (positions.length !== 1 || !path.isAbsolute(args[positions[0] + 1] ?? ""))
+            return {};
+        return { root: canonicalProjectRoot(args[positions[0] + 1]) };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * --project 模式：把指定目录作为钉定项目写进 Codex config.toml（npx + --root）。
+ * 桌面版 Codex 起 MCP 服务时 cwd 不在工作区，必须逐项目钉根；同名条目已存在则跳过（fail-closed，不产生重复 TOML 表头）。
+ */
+export function appendCodexProjectConfig(file, projectRoot, force, dryRun, log) {
+    const absolute = path.resolve(file);
+    const server = codexProjectServerKey(projectRoot);
+    const canonical = canonicalProjectRoot(projectRoot);
+    const existing = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : "";
+    const entry = projectEntry(existing, server);
+    const legacy = legacyProjectServerKey(canonical);
+    const legacyEntry = projectEntry(existing, legacy);
+    if (entry && entry.root !== canonical) {
+        throw new Error(`已有 [mcp_servers.${server}] 指向不同项目或无法确认 --root；未修改配置。`);
+    }
+    if (entry || legacyEntry?.root === canonical) {
+        const reused = entry ? server : legacy;
+        if (!force)
+            log(`[skip] Codex already has [mcp_servers.${reused}] for this project; nothing to change.`);
+        else
+            throw new Error(`Codex already has [mcp_servers.${reused}]; 请先手工删除该段再 --force 重加。`);
+        return;
+    }
+    log(`[${dryRun ? "plan" : "write"}] Codex: ${absolute}`);
+    if (dryRun)
+        return;
+    fs.mkdirSync(path.dirname(absolute), { recursive: true });
+    if (fs.existsSync(absolute))
+        fs.copyFileSync(absolute, backupName(absolute), fs.constants.COPYFILE_EXCL);
+    const tomlRoot = path.resolve(projectRoot).replace(/\\/g, "/");
+    const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+    const block = `${separator}\n[mcp_servers.${server}]\ncommand = "npx"\nargs = ["-y", ${JSON.stringify(PACKAGE_SPEC)}, "--root", ${JSON.stringify(tomlRoot)}]\n`;
+    fs.appendFileSync(absolute, block, "utf8");
+    log(`[entry] [mcp_servers.${server}] → --root ${tomlRoot}`);
+}
 function run(command, args, visible) {
     const result = spawnSync(command, args, {
         shell: false,
@@ -177,8 +269,12 @@ function configureCliClient(client, options, available, log) {
         throw new Error(`${client} could not add ${SERVER_NAME}`);
     return true;
 }
-function configureClient(client, options, context, log) {
+function configureClient(client, options, context, log, projectRoot) {
     if (client === "codex") {
+        if (options.project && projectRoot) {
+            appendCodexProjectConfig(codexConfigPath(context.env, context.home), projectRoot, options.force, options.dryRun, log);
+            return;
+        }
         if (configureCliClient("codex", options, context.commandExists("codex"), log))
             return;
         appendCodexConfig(codexConfigPath(context.env, context.home), options.dryRun, log);
@@ -207,8 +303,9 @@ function configureClient(client, options, context, log) {
 function printHelp(log) {
     log("pm-mcp setup — configure local AI coding clients");
     log("");
-    log(`Usage: npx -y ${PACKAGE_SPEC} setup [--client auto|all|codex|claude|zcode|cursor|vscode|print] [--force] [--dry-run]`);
+    log(`Usage: npx -y ${PACKAGE_SPEC} setup [--client auto|all|codex|claude|zcode|cursor|vscode|print] [--project [dir]] [--force] [--dry-run]`);
     log("Default auto mode configures every detected supported client.");
+    log("--project [dir]: 在 Codex 把该目录注册为钉定项目并初始化 .pm（新项目一条命令上手；默认当前目录）");
 }
 export function runSetup(argv, overrides = {}) {
     const options = parseSetupArgs(argv);
@@ -226,24 +323,42 @@ export function runSetup(argv, overrides = {}) {
     const context = {
         env,
         home,
+        cwd: overrides.cwd,
         commandExists: overrides.commandExists ?? ((command) => commandExists(command, env)),
         exists: overrides.exists ?? fs.existsSync,
     };
+    const projectRoot = options.project ? path.resolve(options.projectDir?.trim() || context.cwd || process.cwd()) : undefined;
     const selected = options.client === "all"
         ? CLIENTS
         : options.client === "auto"
             ? detectClients(context)
             : [options.client];
-    if (selected.length === 0) {
+    if (selected.length === 0 && !options.project) {
         log("No supported client was detected. Use --client <name>, or --client print for generic JSON.");
         return 1;
     }
     log(`pm-mcp setup ${PACKAGE_SPEC}`);
-    log(`clients: ${selected.join(", ")}`);
+    if (selected.length > 0)
+        log(`clients: ${selected.join(", ")}`);
+    if (options.project && projectRoot) {
+        const name = path.basename(projectRoot) || "project";
+        log(`project: ${projectRoot}`);
+        if (options.dryRun) {
+            log(`[plan] init_project ${name}（.pm/ + PROJECT.md + AGENTS.md 工作规矩）`);
+        }
+        else if (isInitialized(projectRoot)) {
+            log("[skip] 项目已初始化（.pm/project.json 已存在）。");
+        }
+        else {
+            initProject(projectRoot, { name });
+            refreshDerived(projectRoot);
+            log(`[init] ✅ ${name} 已初始化：.pm/ 状态目录 + PROJECT.md 仪表盘 + AGENTS.md 工作规矩`);
+        }
+    }
     let failures = 0;
     for (const client of selected) {
         try {
-            configureClient(client, options, context, log);
+            configureClient(client, options, context, log, projectRoot);
         }
         catch (error) {
             failures += 1;
@@ -252,6 +367,11 @@ export function runSetup(argv, overrides = {}) {
     }
     if (failures > 0)
         return 1;
-    log("Done. Restart the configured client and ask it to call pm-mcp get_status.");
+    if (options.project && selected.includes("codex")) {
+        log("完成。请完全退出并重启 Codex，开新会话即可使用（工具名前缀 pm-mcp-<项目名>）。");
+    }
+    else {
+        log("Done. Restart the configured client and ask it to call pm-mcp get_status.");
+    }
     return 0;
 }

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;