@luckychen1993/pm-mcp 0.1.3 → 0.1.4

package/README.md

@@ -25,7 +25,7 @@ AI 编码项目的典型失控（本工具逐一给出机制）：
 | 调试过程随会话消失 | `log_debug` 调试知识账（症状/根因/修法/验证） |
 | 长任务崩溃、上下文丢失 | 任务步骤清单 + `checkpoint` 断点存档，新会话从恢复点续做 |
 | 团队协作与知识传递 | Git 项目中共享 `.pm/` + 会话署名 + `onboard` 入职简报工作流 |
-| 多 Agent 重复读写 | 并行读请求跨进程合并；写工具支持业务幂等键并自动抑制瞬时完全重复调用 |
+| 多 Agent 重复读写 | 实际重叠的同参读跨进程合并；写工具支持业务幂等键、瞬时自动去重与故障不确定态 fail-closed |
 | token 猛烧 | 三段式定位 + 读类工具输出硬预算 + 文件用途索引 |
 | 法律知识产权 | `audit_license` 依赖许可证/copyleft 冲突 + 来源登记（provenance） |
 | 测试投机（删测试、skip 凑绿） | 禁用/蒸发/空测试检测 + 功能测试背书占比 + done 必附验证 |
@@ -53,7 +53,7 @@ npx -y @luckychen1993/pm-mcp@latest setup --dry-run
 Codex 的本地客户端共享同一份 MCP 配置。复制执行：
 
 ```bash
-codex mcp add pm-mcp -- npx -y @luckychen1993/pm-mcp@0.1.3
+codex mcp add pm-mcp -- npx -y @luckychen1993/pm-mcp@0.1.4
 ```
 
 重启客户端后可用 `codex mcp list` 检查。该命令遵循 [OpenAI 官方 MCP CLI 格式](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)。
@@ -61,7 +61,7 @@ codex mcp add pm-mcp -- npx -y @luckychen1993/pm-mcp@0.1.3
 #### Claude Code
 
 ```bash
-claude mcp add pm-mcp --scope user -- npx -y @luckychen1993/pm-mcp@0.1.3
+claude mcp add pm-mcp --scope user -- npx -y @luckychen1993/pm-mcp@0.1.4
 ```
 
 #### ZCode、Cursor、VS Code（Windows 备用脚本）
@@ -69,7 +69,7 @@ claude mcp add pm-mcp --scope user -- npx -y @luckychen1993/pm-mcp@0.1.3
 将 `<client>` 替换为 `zcode`、`cursor` 或 `vscode`，整行复制到 PowerShell：
 
 ```powershell
-$u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.3/install.ps1'; $f=Join-Path $env:TEMP 'install-pm-mcp.ps1'; Invoke-WebRequest $u -OutFile $f; & $f -Client <client>
+$u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.4/install.ps1'; $f=Join-Path $env:TEMP 'install-pm-mcp.ps1'; Invoke-WebRequest $u -OutFile $f; & $f -Client <client>
 ```
 
 脚本只写对应客户端的 MCP 配置；已有 JSON 配置会先生成带时间戳的备份。建议执行前先打开 [`install.ps1`](install.ps1) 审阅。ZCode 默认写入 `$ZCODE_HOME/cli/config.json` 或 `~/.zcode/cli/config.json`，Cursor 默认写入 `~/.cursor/mcp.json`；也可用 `-ConfigPath` 指定路径。
@@ -81,7 +81,7 @@ $u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.3/install.ps1'; $f=
   "mcpServers": {
     "pm-mcp": {
       "command": "npx",
-      "args": ["-y", "@luckychen1993/pm-mcp@0.1.3"],
+      "args": ["-y", "@luckychen1993/pm-mcp@0.1.4"],
       "env": {}
     }
   }
@@ -156,6 +156,8 @@ Resources：`pm://dashboard`、`pm://roadmap`、`pm://tasks`、`pm://changelog`
 
 所有写工具都接受可选 `idempotency_key`。同一业务的多个 Agent 应传同一个稳定键（例如 `T-123:add-login-task`）：同键同参数只执行一次并复用首次结果，同键不同参数直接拒绝。即使没有显式键，完全相同的并发写也会在短窗口内自动合并；完全相同的并行读会等待首个执行者并复用结果。
 
+并发保证有明确边界：正常运行的同键写只落一次，follower 最多等待 3 秒复用首次结果；仍未完成时以 MCP error 返回 pending，不把占位冒充成功。若进程在业务写入后、幂等完成记录前被强杀，pm-mcp 会把该键标为 `uncertain` 并禁止自动重放。它提供的是 **at-most-once + 不确定时 fail-closed**，不是跨多个 JSON 文件的事务型 exactly-once；核对目标账本后才能决定是否换新键。v0.1.3 的标准全局幂等记录会在首次复用时迁移到项目运行态，旧文件保留以便回滚。读合并只覆盖业务处理实际重叠的在途请求，完成结果不会继续缓存，避免外部代码刚变化却返回旧内容。每个项目由 SQLite 生命周期选举一个 watcher leader，其余进程低频待命；leader 被强杀后由一个 standby 接管。结构、安全、许可证与快照等权威审计强制重读内容，不把 `fs.watch` 或 mtime/size 缓存的最终一致性冒充强一致性。
+
 ## 数据模型（被管理项目内的 `.pm/`；JSON/Markdown 账本可 git diff，`index.db` 是忽略并可重建的缓存）
 
 ```
@@ -178,7 +180,7 @@ PROJECT.md        # 仓库根，自动生成的仪表盘（勿手改）
 changelog.md      # 自动生成
 ```
 
-全局注册表：`~/.pm-mcp/registry.json`。跨进程读合并/写幂等运行态位于 `~/.pm-mcp/idempotency/<项目路径哈希>/`，不会污染被管理项目或进入 Git。
+全局注册表：`~/.pm-mcp/registry.json`。跨进程读合并、写幂等、恢复锁与 watcher 选举运行态位于被管理项目的 `.pm/.runtime/`，由 `.pm/.gitignore` 排除；因此路径别名、不同客户端或不同 `PM_MCP_HOME` 仍共享同一协调域，但运行态不会进入 Git。
 
 ## 跨文件、跨模块、跨语言治理
 

package/dist/audit-tools.js

@@ -5,25 +5,26 @@ import { refreshDerived } from "./dashboard.js";
 import { auditLicense } from "./license.js";
 import { isInitialized, requireInitialized } from "./paths.js";
 import { listRegistry } from "./registry.js";
-import { auditSecurity, listFindings, resolveFinding } from "./security.js";
+import { auditSecurity, listFindings, prepareSecurityAudit, resolveFinding } from "./security.js";
 import { budgetLines, toolR, toolW } from "./tool-base.js";
+import { walkRefresh } from "./index-store.js";
 export function registerAuditTools(server, root) {
     toolW(server, root, "snapshot_codebase", "给代码结构拍快照（文件数/行数/目录分布/测试数/skip 标记/依赖清单）。之后 audit_structure 会与上次快照 diff。建议每个会话或每个里程碑结束时拍一次。", {}, () => {
         requireInitialized(root);
         const { snapshot, summary } = snapshotCodebase(root);
         refreshDerived(root);
         return [...summary, `下次 audit_structure 将以此为基线（${snapshot.file}）。`].join("\n");
-    });
+    }, () => { requireInitialized(root); walkRefresh(root, { forceContent: true }); });
     toolR(server, root, "audit_structure", "八项结构对账（定期做）：①增长与新增依赖 ②漂移对账（功能↔文件，防幻觉）③债务与重构配额 ④churn 热点 ⑤复杂度预算 ⑥索引覆盖率 ⑦足迹/产出 ⑧测试健康（禁用/蒸发/空测试/背书占比）。", {}, () => {
         requireInitialized(root);
-        return auditStructure(root, budgetLines(root));
+        return auditStructure(root, budgetLines(root), true);
     });
-    toolW(server, root, "audit_security", "安全体检（只扫描本地、不联网，结果写入安全台账）：密钥泄露 / 危险模式（eval、SQL 拼接、禁用证书校验等）/ 依赖风险。修复后重扫自动关闭；接受风险必须留理由。", {}, () => {
+    toolW(server, root, "audit_security", "安全体检（只扫描本地、不联网，结果写入安全台账）：密钥泄露 / 危险模式（eval、SQL 拼接、禁用证书校验等）/ 依赖风险。修复后重扫自动关闭；接受风险必须留理由。", {}, (_args, prepared) => {
         requireInitialized(root);
-        const report = auditSecurity(root);
+        const report = auditSecurity(root, prepared);
         refreshDerived(root);
         return report.text.join("\n");
-    });
+    }, () => { requireInitialized(root); return prepareSecurityAudit(root); });
     toolR(server, root, "list_findings", "查看安全台账（可按状态过滤）。", { status: z.enum(["open", "fixed", "accepted"]).optional() }, (args) => {
         requireInitialized(root);
         const list = listFindings(root, args.status);
@@ -44,7 +45,7 @@ export function registerAuditTools(server, root) {
     });
     toolR(server, root, "audit_license", "许可证审计（法律账）：依赖许可证清单与 copyleft 冲突、源码中的 GPL 家族许可证头、LICENSE 文件检查、来源登记清单。离线启发式，不替代法务。", {}, () => {
         requireInitialized(root);
-        return auditLicense(root, budgetLines(root));
+        return auditLicense(root, budgetLines(root), true);
     });
 }
 export function registerRegistryTools(server, root) {

package/dist/audit.js

@@ -5,7 +5,7 @@ import { loadFeatures, loadFileNotes, loadProject, loadRoadmap, loadSessions, lo
 import { decisionsDir, pmPath, snapshotsDir } from "./paths.js";
 import { normSep, foldLines } from "./budget.js";
 import { readDirectDeps } from "./scan.js";
-import { aggregates, ensureFresh, getIndex, getMeta } from "./index-store.js";
+import { aggregates, ensureFresh, freshness, getIndex, getMeta, walkRefresh } from "./index-store.js";
 import { quotaWarnings, milestoneStats } from "./roadmap.js";
 import { blastRadiusWarning, churnStats, debtAging, footprint } from "./health.js";
 import { now } from "./types.js";
@@ -21,8 +21,11 @@ export function annotatedCount(root, db) {
     }
     return n;
 }
-export function snapshotCodebase(root) {
-    ensureFresh(root);
+export function snapshotCodebase(root, forceFresh = false, indexPrepared = false) {
+    if (forceFresh)
+        walkRefresh(root, { forceContent: true });
+    else if (!indexPrepared)
+        ensureFresh(root);
     const db = getIndex(root);
     const agg = aggregates(db);
     const annotated = annotatedCount(root, db);
@@ -165,13 +168,15 @@ export function gitAudit(root) {
     return out;
 }
 /** 完整结构对账：九项报告 */
-export function auditStructure(root, maxLines = 150) {
+export function auditStructure(root, maxLines = 150, forceFresh = false, indexPrepared = false) {
     const project = loadProject(root);
     const { features } = loadFeatures(root);
     const { tasks } = loadTasks(root);
     const { milestones } = loadRoadmap(root);
     const { sessions } = loadSessions(root);
-    const fresh = ensureFresh(root);
+    const fresh = forceFresh
+        ? { used: "walk", freshness: (walkRefresh(root, { forceContent: true }), freshness(root)) }
+        : indexPrepared ? { used: "walk", freshness: freshness(root) } : ensureFresh(root);
     const db = getIndex(root);
     const agg = aggregates(db);
     const deps = readDirectDeps(root).deps;

package/dist/idempotency.js

@@ -1,9 +1,10 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { atomicWrite, withLedgerLock } from "./store.js";
-import { pmPath, registryFile } from "./paths.js";
+import { atomicWrite, withFileRecoveryLock, withLedgerLock } from "./store.js";
+import { ensurePmRuntimeIgnored, pmPath, registryFile } from "./paths.js";
 export const IdempotencyKeySchema = z.string()
     .trim()
     .min(1)
@@ -16,7 +17,7 @@ const OperationRecordSchema = z.object({
     tool: z.string().min(1),
     args_sha256: z.string().regex(/^[a-f0-9]{64}$/),
     mode: z.enum(["read", "write"]),
-    status: z.enum(["pending", "completed"]),
+    status: z.enum(["pending", "completed", "uncertain"]),
     owner_pid: z.number().int().positive(),
     owner_token: z.string().uuid(),
     created_at: z.string().datetime({ offset: true }),
@@ -24,8 +25,13 @@ const OperationRecordSchema = z.object({
     result: z.string().nullable(),
 });
 const AUTO_REPLAY_MS = 1_000;
-const READ_WAIT_MS = 30_000;
-const LOCK_STALE_MS = 10_000;
+const DEFAULT_PENDING_LEASE_MS = 60 * 60_000;
+const DEFAULT_WRITE_WAIT_MS = 3_000;
+const MAX_CLOCK_SKEW_MS = 5_000;
+const SYNC_WAIT = new Int32Array(new SharedArrayBuffer(4));
+let readWaitMs = 30_000;
+let pendingLeaseMs = DEFAULT_PENDING_LEASE_MS;
+let writeWaitMs = DEFAULT_WRITE_WAIT_MS;
 function sha256(value) {
     return createHash("sha256").update(value).digest("hex");
 }
@@ -60,7 +66,13 @@ function processAlive(pid) {
     }
 }
 function operationDirectory(root) {
-    return path.join(path.dirname(registryFile()), "idempotency", sha256(path.resolve(root)));
+    let canonical = path.resolve(root);
+    try {
+        canonical = fs.realpathSync.native(canonical);
+    }
+    catch { /* init_project may not exist yet */ }
+    ensurePmRuntimeIgnored(canonical);
+    return pmPath(canonical, ".runtime", "idempotency");
 }
 function revisionFile(root) {
     return path.join(operationDirectory(root), "revision");
@@ -80,6 +92,24 @@ function bumpRevision(root) {
 function operationFile(root, key) {
     return path.join(operationDirectory(root), `${sha256(key)}.json`);
 }
+function legacyOperationFiles(root, key) {
+    const resolved = path.resolve(root);
+    let real = resolved;
+    try {
+        real = fs.realpathSync.native(resolved);
+    }
+    catch { /* keep resolved */ }
+    const identities = new Set([resolved, real]);
+    if (process.platform === "win32") {
+        identities.add(resolved.toLowerCase());
+        identities.add(resolved.toUpperCase());
+        identities.add(real.toLowerCase());
+        identities.add(real.toUpperCase());
+    }
+    const homes = new Set([path.dirname(registryFile()), path.join(os.homedir(), ".pm-mcp")]);
+    const name = `${sha256(key)}.json`;
+    return [...homes].flatMap((home) => [...identities].map((identity) => path.join(home, "idempotency", sha256(identity), name)));
+}
 function readRecord(file) {
     if (!fs.existsSync(file))
         return null;
@@ -95,53 +125,26 @@ function readRecord(file) {
         throw new Error(`幂等记录 schema 无效，拒绝继续写入: ${file}`);
     return parsed.data;
 }
-function lockOwner(file) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
-        return typeof parsed.pid === "number" && typeof parsed.token === "string" ? { pid: parsed.pid, token: parsed.token } : null;
-    }
-    catch {
+function migrateLegacyRecord(root, key, currentFile) {
+    const legacy = [...new Set(legacyOperationFiles(root, key))].filter((file) => fs.existsSync(file));
+    if (legacy.length === 0)
         return null;
+    const records = legacy.map((file) => readRecord(file));
+    const first = JSON.stringify(records[0]);
+    if (records.some((record) => JSON.stringify(record) !== first)) {
+        throw new Error(`检测到多个不一致的 v0.1.3 幂等记录，拒绝自动迁移业务键: ${key}`);
     }
+    atomicWrite(currentFile, JSON.stringify(OperationRecordSchema.parse(records[0]), null, 2) + "\n");
+    return records[0];
+}
+function pendingLeaseExpired(record) {
+    const age = Date.now() - Date.parse(record.updated_at);
+    return !Number.isFinite(age) || age < -MAX_CLOCK_SKEW_MS || age >= pendingLeaseMs;
 }
 function withOperationLock(file, fn) {
-    const lock = `${file}.lock`;
-    const token = randomUUID();
-    const payload = JSON.stringify({ pid: process.pid, token });
-    let held = false;
-    for (let index = 0; index < 150 && !held; index += 1) {
-        try {
-            fs.writeFileSync(lock, payload, { flag: "wx" });
-            held = true;
-        }
-        catch {
-            try {
-                const current = lockOwner(lock);
-                const stale = Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS;
-                if (stale && (!current || !processAlive(current.pid)))
-                    fs.rmSync(lock, { force: true });
-            }
-            catch {
-                // The lock disappeared between checks; retry.
-            }
-            if (!held)
-                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
-        }
-    }
-    if (!held)
-        throw new Error("幂等键锁获取超时（3s），请稍后重试同一 idempotency_key。");
-    try {
-        return fn();
-    }
-    finally {
-        try {
-            if (lockOwner(lock)?.token === token)
-                fs.rmSync(lock, { force: true });
-        }
-        catch {
-            // Best-effort release; stale-owner recovery handles process crashes.
-        }
-    }
+    return withFileRecoveryLock(`${file}.lock`, fn, {
+        timeoutMessage: "幂等键锁获取超时（3s），请稍后重试同一 idempotency_key。",
+    });
 }
 function claim(root, tool, args, mode, explicitKey) {
     const argsHash = operationArgsHash(args);
@@ -149,18 +152,37 @@ function claim(root, tool, args, mode, explicitKey) {
     const file = operationFile(root, key);
     fs.mkdirSync(path.dirname(file), { recursive: true });
     return withOperationLock(file, () => {
-        const existing = readRecord(file);
+        const existing = readRecord(file) ?? migrateLegacyRecord(root, key, file);
         if (existing) {
             if (existing.key !== key || existing.tool !== tool || existing.mode !== mode || existing.args_sha256 !== argsHash) {
                 throw new Error(`idempotency_key 冲突：${key} 已绑定其他工具或参数，拒绝误复用。`);
             }
             if (existing.status === "completed") {
                 const age = Date.now() - Date.parse(existing.updated_at);
-                if (existing.explicit || (mode === "write" && age <= AUTO_REPLAY_MS))
+                if (existing.explicit ||
+                    (mode === "write" && age <= AUTO_REPLAY_MS))
                     return { kind: "replay", record: existing };
             }
-            else if (processAlive(existing.owner_pid)) {
-                return { kind: "pending", file, record: existing };
+            else if (existing.status === "uncertain") {
+                return { kind: "uncertain", record: existing };
+            }
+            else {
+                const expired = pendingLeaseExpired(existing);
+                const ownerAlive = processAlive(existing.owner_pid);
+                if (mode === "write") {
+                    if (!expired && ownerAlive)
+                        return { kind: "pending", file, record: existing };
+                    // A write may already have changed external or ledger state. Neither an
+                    // expired lease nor a dead/reused PID proves that replay is safe.
+                    existing.status = "uncertain";
+                    existing.updated_at = new Date().toISOString();
+                    atomicWrite(file, JSON.stringify(OperationRecordSchema.parse(existing), null, 2) + "\n");
+                    return { kind: "uncertain", record: existing };
+                }
+                // Reads are side-effect-free by contract. Keep a real active lease, but
+                // replace an expired or dead-owner reservation with a fresh execution.
+                if (!expired && ownerAlive)
+                    return { kind: "pending", file, record: existing };
             }
         }
         const timestamp = new Date().toISOString();
@@ -194,6 +216,21 @@ function complete(file, reservation, result) {
         atomicWrite(file, JSON.stringify(OperationRecordSchema.parse(current), null, 2) + "\n");
     });
 }
+function markUncertain(file, reservation) {
+    try {
+        withOperationLock(file, () => {
+            const current = readRecord(file);
+            if (current?.owner_token !== reservation.owner_token || current.status !== "pending")
+                return;
+            current.status = "uncertain";
+            current.updated_at = new Date().toISOString();
+            atomicWrite(file, JSON.stringify(OperationRecordSchema.parse(current), null, 2) + "\n");
+        });
+    }
+    catch {
+        // Preserve the business error. The pending explicit key remains fail-closed.
+    }
+}
 function abandon(file, reservation) {
     try {
         withOperationLock(file, () => {
@@ -207,50 +244,114 @@ function abandon(file, reservation) {
     }
 }
 function replay(record) {
+    const uncertain = record.status === "uncertain" || (record.status === "pending" && record.mode === "write" &&
+        (!processAlive(record.owner_pid) || pendingLeaseExpired(record)));
     return {
-        text: record.result ?? `⏳ 相同业务正在由另一 Agent 执行：${record.key}`,
+        text: record.result ?? (uncertain
+            ? `⚠️ 业务结果不确定，已禁止自动重放：${record.key}。请核对目标账本后决定是否使用新的业务键。`
+            : `⏳ 相同业务正在由另一 Agent 执行：${record.key}`),
         replayed: record.status === "completed",
-        pending: record.status === "pending",
+        pending: record.status !== "completed",
+        uncertain,
         key: record.key,
     };
 }
-export function runIdempotentWriteSync(root, tool, args, fn) {
+function currentWriteSettlement(file, reservation) {
+    const current = readRecord(file);
+    if (!current || current.owner_token !== reservation.owner_token)
+        return null;
+    if (current.status !== "pending")
+        return current;
+    if (!processAlive(current.owner_pid) || pendingLeaseExpired(current))
+        return null;
+    return undefined;
+}
+function waitForWriteSync(file, reservation) {
+    const deadline = Date.now() + writeWaitMs;
+    while (Date.now() < deadline) {
+        const current = currentWriteSettlement(file, reservation);
+        if (current !== undefined)
+            return current;
+        Atomics.wait(SYNC_WAIT, 0, 0, Math.min(25, Math.max(0, deadline - Date.now())));
+    }
+    return null;
+}
+async function waitForWrite(file, reservation) {
+    const deadline = Date.now() + writeWaitMs;
+    while (Date.now() < deadline) {
+        const current = currentWriteSettlement(file, reservation);
+        if (current !== undefined)
+            return current;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(25, Math.max(0, deadline - Date.now()))));
+    }
+    return null;
+}
+export function runIdempotentWriteSync(root, tool, args, fn, prepare) {
     const { businessArgs, explicitKey } = splitIdempotencyArgs(args);
-    const reservation = claim(root, tool, businessArgs, "write", explicitKey);
+    let reservation = claim(root, tool, businessArgs, "write", explicitKey);
+    if (reservation.kind === "pending") {
+        const settled = waitForWriteSync(reservation.file, reservation.record);
+        if (settled)
+            return replay(settled);
+        reservation = claim(root, tool, businessArgs, "write", explicitKey);
+    }
     if (reservation.kind !== "execute")
         return replay(reservation.record);
+    let handlerStarted = false;
     try {
+        const prepared = prepare?.(businessArgs);
         const text = withLedgerLock(root, () => {
-            const value = fn(businessArgs);
+            handlerStarted = true;
+            const value = fn(businessArgs, prepared);
+            idempotencyFault("after-business");
             bumpRevision(root);
+            idempotencyFault("after-revision");
             return value;
         });
+        idempotencyFault("before-complete");
         complete(reservation.file, reservation.record, text);
-        return { text, replayed: false, pending: false, key: reservation.record.key };
+        return { text, replayed: false, pending: false, uncertain: false, key: reservation.record.key };
     }
     catch (error) {
-        abandon(reservation.file, reservation.record);
+        if (handlerStarted)
+            markUncertain(reservation.file, reservation.record);
+        else
+            abandon(reservation.file, reservation.record);
         throw error;
     }
 }
 export async function runIdempotentWrite(root, tool, args, fn) {
     const { businessArgs, explicitKey } = splitIdempotencyArgs(args);
-    const reservation = claim(root, tool, businessArgs, "write", explicitKey);
+    let reservation = claim(root, tool, businessArgs, "write", explicitKey);
+    if (reservation.kind === "pending") {
+        const settled = await waitForWrite(reservation.file, reservation.record);
+        if (settled)
+            return replay(settled);
+        reservation = claim(root, tool, businessArgs, "write", explicitKey);
+    }
     if (reservation.kind !== "execute")
         return replay(reservation.record);
+    let handlerStarted = false;
     try {
+        handlerStarted = true;
         const text = await fn(businessArgs);
+        idempotencyFault("after-business");
         bumpRevision(root);
+        idempotencyFault("after-revision");
+        idempotencyFault("before-complete");
         complete(reservation.file, reservation.record, text);
-        return { text, replayed: false, pending: false, key: reservation.record.key };
+        return { text, replayed: false, pending: false, uncertain: false, key: reservation.record.key };
     }
     catch (error) {
-        abandon(reservation.file, reservation.record);
+        if (handlerStarted)
+            markUncertain(reservation.file, reservation.record);
+        else
+            abandon(reservation.file, reservation.record);
         throw error;
     }
 }
 async function waitForRead(file, record) {
-    const deadline = Date.now() + READ_WAIT_MS;
+    const deadline = Date.now() + readWaitMs;
     while (Date.now() < deadline) {
         await new Promise((resolve) => setTimeout(resolve, 25));
         const current = readRecord(file);
@@ -267,27 +368,60 @@ export async function runCoalescedRead(root, tool, args, fn) {
     // Read-only calls before project initialization must not create .pm state.
     if (!fs.existsSync(pmPath(root, "project.json"))) {
         const text = await fn(args);
-        return { text, replayed: false, pending: false, key: "uncached:uninitialized" };
+        return { text, replayed: false, pending: false, uncertain: false, key: "uncached:uninitialized" };
     }
     const readClaim = () => claim(root, tool, { revision: readRevision(root), args }, "read");
     let reservation = readClaim();
     if (reservation.kind === "replay")
         return replay(reservation.record);
+    if (reservation.kind === "uncertain")
+        throw new Error("并行读取状态不确定；请稍后重试。");
     if (reservation.kind === "pending") {
         const completed = await waitForRead(reservation.file, reservation.record);
         if (completed)
             return replay(completed);
         reservation = readClaim();
-        if (reservation.kind !== "execute")
+        if (reservation.kind === "pending")
+            throw new Error(`并行读取等待超过 ${readWaitMs}ms，leader 仍在执行；请稍后重试。`);
+        if (reservation.kind === "uncertain")
+            throw new Error("并行读取状态不确定；请稍后重试。");
+        if (reservation.kind === "replay")
             return replay(reservation.record);
     }
+    if (reservation.kind !== "execute")
+        throw new Error("并行读取未获得执行权；请稍后重试。");
     try {
         const text = await fn(args);
         complete(reservation.file, reservation.record, text);
-        return { text, replayed: false, pending: false, key: reservation.record.key };
+        return { text, replayed: false, pending: false, uncertain: false, key: reservation.record.key };
     }
     catch (error) {
         abandon(reservation.file, reservation.record);
         throw error;
     }
 }
+let faultHook;
+function idempotencyFault(stage) {
+    faultHook?.(stage);
+}
+/** 仅供故障注入测试；生产调用方不应设置。 */
+export function setIdempotencyFaultHookForTests(hook) {
+    faultHook = hook;
+}
+/** 仅供故障注入测试，传 undefined 恢复生产默认值。 */
+export function setReadWaitMsForTests(value) {
+    readWaitMs = value ?? 30_000;
+}
+/** 仅供 PID 复用与 lease 故障注入测试；传 undefined 恢复生产默认值。 */
+export function setPendingLeaseMsForTests(value) {
+    if (value !== undefined && (!Number.isFinite(value) || value <= 0)) {
+        throw new RangeError("pending lease 必须大于 0ms。");
+    }
+    pendingLeaseMs = value ?? DEFAULT_PENDING_LEASE_MS;
+}
+/** 仅供 follower 等待边界测试；传 undefined 恢复生产默认值。 */
+export function setWriteWaitMsForTests(value) {
+    if (value !== undefined && (!Number.isFinite(value) || value < 0))
+        throw new RangeError("write wait 不得小于 0ms。");
+    writeWaitMs = value ?? DEFAULT_WRITE_WAIT_MS;
+}