@zhushanwen/pi-file-lock 0.1.1 → 0.2.0

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@zhushanwen/pi-file-lock",
-  "version": "0.1.1",
-  "description": "Shared async cross-process file lock for Pi extensions — proper-lockfile wrapper with stale takeover and exponential-backoff retries, aligned with the runtime-side lock protocol (shared library, not a Pi extension).",
+  "version": "0.2.0",
+  "description": "Shared cross-process file lock for Pi extensions — zero-dependency self-implemented mkdir lock (protocol-compatible with proper-lockfile 4.1.2) with stale takeover and exponential-backoff retries, aligned with the runtime-side lock protocol (shared library, not a Pi extension).",
   "type": "module",
   "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./core": "./src/lock-core.ts"
+  },
   "keywords": [
     "pi-package",
     "pi",
@@ -14,11 +18,10 @@
   ],
   "license": "MIT",
   "files": [
-    "src/",
-    "index.ts"
+    "src/"
   ],
   "dependencies": {
-    "proper-lockfile": "^4.1.2"
+    "@zhushanwen/pi-extension-logger": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/__tests__/file-lock-backoff.test.ts

@@ -0,0 +1,130 @@
+// src/__tests__/file-lock-backoff.test.ts
+//
+// async 版退避重试参数单测（mock lock-core + fake timers，不碰真实文件系统）。
+// 验收条款「async 退避参数 10×factor2 100ms~10s randomize」的精确断言：
+//   - 默认 retries=10 → 首试 + 10 次重试 = 11 次 acquire
+//   - 第 attempt 次失败后的等待 = min(round((random+1) * 100 * 2**attempt), 10_000)
+//     （照抄 proper-lockfile 内部 retry 库公式；randomize 倍率 [1,2)）
+//     → 前 6 段区间 [100*2^i, 200*2^i]，第 7 段起触顶 10s cap
+//   - staleMs 默认 30_000 透传 core；opts.retries 可覆盖次数（0 → 首试失败即抛）
+
+import * as path from "node:path";
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// mock 锁原语层：acquireLock 恒抛 ELOCKED（退避耗尽路径），调用时刻用 mock clock 记录
+const { acquireLockMock } = vi.hoisted(() => ({ acquireLockMock: vi.fn() }));
+
+vi.mock("../lock-core.ts", () => ({
+	DEFAULT_STALE_MS: 30_000,
+	acquireLock: acquireLockMock,
+	acquireLockSync: vi.fn(),
+}));
+
+import { DEFAULT_STALE_MS, withFileLock } from "../file-lock.ts";
+
+function elocked(): Error {
+	return Object.assign(new Error("Lock file is already being held"), { code: "ELOCKED" });
+}
+
+describe("withFileLock 退避重试编排（对齐 retry 库 10×factor2 100ms~10s randomize）", () => {
+	const target = path.join("/tmp", "file-lock-backoff-fake", "target.json");
+
+	beforeEach(() => {
+		acquireLockMock.mockReset();
+		acquireLockMock.mockImplementation(async () => {
+			throw elocked();
+		});
+	});
+
+	it("默认参数：11 次 acquire（首试 + 10 重试），staleMs 30s 透传，最终抛 ELOCKED", async () => {
+		vi.useFakeTimers();
+		try {
+			const acquisitionTimes: number[] = [];
+			acquireLockMock.mockImplementation(async () => {
+				acquisitionTimes.push(Date.now());
+				throw elocked();
+			});
+
+			const pending = withFileLock(target, async () => "never");
+			// 立即 attach 断言（reject 可能先于 timers 推进发生，晚 attach 会报 unhandledRejection）
+			const settled = expect(pending).rejects.toMatchObject({ code: "ELOCKED" });
+			// flush 首试 microtask（调度第一个退避 timer），再一次性推进全部退避等待
+			await vi.advanceTimersByTimeAsync(0);
+			await vi.advanceTimersByTimeAsync(1_000_000);
+			await settled;
+
+			expect(acquireLockMock).toHaveBeenCalledTimes(11);
+			// 透传参数：staleMs 默认 30_000，log 未注入时为 undefined
+			for (const call of acquireLockMock.mock.calls) {
+				expect(call[1]).toMatchObject({ staleMs: DEFAULT_STALE_MS });
+			}
+			expect(acquisitionTimes).toHaveLength(11);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("退避序列：第 i 段等待 ∈ [100*2^i, 200*2^i]（randomize），第 7 段起触顶 10s", async () => {
+		vi.useFakeTimers();
+		try {
+			const acquisitionTimes: number[] = [];
+			acquireLockMock.mockImplementation(async () => {
+				acquisitionTimes.push(Date.now());
+				throw elocked();
+			});
+
+			const pending = withFileLock(target, async () => "never");
+			const settled = expect(pending).rejects.toMatchObject({ code: "ELOCKED" });
+			await vi.advanceTimersByTimeAsync(0);
+			await vi.advanceTimersByTimeAsync(1_000_000);
+			await settled;
+
+			expect(acquisitionTimes).toHaveLength(11);
+			const gaps = acquisitionTimes.slice(1).map((t, i) => t - acquisitionTimes[i]!);
+			expect(gaps).toHaveLength(10);
+			for (let i = 0; i < gaps.length; i++) {
+				// 第 i 段等待 ∈ [min(100*2^i, cap), min(200*2^i, cap)]：randomize 倍率 [1,2)，
+				// i>=7 底数超 cap → 区间坍缩为 10000
+				const floor = Math.min(100 * 2 ** i, 10_000);
+				const ceiling = Math.min(200 * 2 ** i, 10_000);
+				expect(gaps[i]).toBeGreaterThanOrEqual(floor);
+				expect(gaps[i]).toBeLessThanOrEqual(ceiling);
+			}
+			// i=6 区间 [6400,12800) ∩ cap → [6400,10000]（不必然触顶）；i>=7 底数已超 cap，必然 10000
+			for (let i = 7; i < gaps.length; i++) {
+				expect(gaps[i]).toBe(10_000);
+			}
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("opts.retries: 0 → 仅首试 1 次即抛 ELOCKED（次数可覆盖）", async () => {
+		vi.useFakeTimers();
+		try {
+			const pending = withFileLock(target, async () => "never", { retries: 0 });
+			const settled = expect(pending).rejects.toMatchObject({ code: "ELOCKED" });
+			await vi.advanceTimersByTimeAsync(0);
+			await settled;
+			expect(acquireLockMock).toHaveBeenCalledTimes(1);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("非 ELOCKED 错误不重试，立即透传", async () => {
+		acquireLockMock.mockImplementation(async () => {
+			throw new Error("EPERM-ish");
+		});
+		await expect(withFileLock(target, async () => "never")).rejects.toThrow("EPERM-ish");
+		expect(acquireLockMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("获取成功后 fn 结果返回、release 被调用", async () => {
+		const release = vi.fn(async () => {});
+		acquireLockMock.mockImplementation(async () => release);
+		await expect(withFileLock(target, async () => "ok")).resolves.toBe("ok");
+		expect(release).toHaveBeenCalledTimes(1);
+	});
+});

package/src/__tests__/file-lock-external-removal.test.ts

@@ -0,0 +1,56 @@
+// src/__tests__/file-lock-external-removal.test.ts
+//
+// 锁目录被外部删除的容忍路径单测（真实文件系统）。前身 file-lock-compromise.test.ts
+// （proper-lockfile onCompromised：保活定时器 stat 发现锁被删 → ERELEASED → debug 留痕）。
+// D1-A 自实现无保活 touch（边界声明见 lock-core.ts 头注释），compromise 检测不存在：
+//   - fn 执行期间锁目录被外部删除 → 无定时器发现，fn 正常返回
+//   - release 时 rmdir 命中 ENOENT → 静默成功（照抄 proper-lockfile removeLock 容忍），
+//     不外抛、不影响 fn 结果；同目标随后可立即再锁（目录确已消失，非残留态）
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { withFileLock } from "../file-lock.ts";
+
+describe("withFileLock 锁目录被外部删除（原 compromise 场景的自实现语义）", () => {
+	let tmpDir: string;
+	let target: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "file-lock-extrem-"));
+		target = path.join(tmpDir, "target.json");
+	});
+	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+
+	it("fn 执行期间锁被外部删除 → fn 正常返回 + release 静默成功 + 可立即再锁", async () => {
+		const result = await withFileLock(
+			target,
+			async () => {
+				// 模拟外部清理（对端 stale 夺取会先 rmdir 再 mkdir；此处直接删）：
+				// 自实现无保活定时器，删除本身不触发任何回调
+				fs.rmSync(`${target}.lock`, { recursive: true, force: true });
+				return "fn-done";
+			},
+			{ staleMs: 2000 },
+		);
+
+		// fn 结果原样返回（无 compromised 拦截——该机制随保活一并移除）
+		expect(result).toBe("fn-done");
+		// release 对已消失的锁目录静默成功（ENOENT 容忍）——由下一断言间接证明：
+		// 若 release 抛错，withFileLock 会吞错但此处再锁也必然成功；直接再锁验证锁已释放
+		await expect(withFileLock(target, async () => "again")).resolves.toBe("again");
+	});
+
+	it("fn 抛错且锁目录已被外部删除 → 错误照常外抛 + release 不叠加失败", async () => {
+		await expect(
+			withFileLock(target, () => {
+				fs.rmSync(`${target}.lock`, { recursive: true, force: true });
+				throw new Error("boom");
+			}),
+		).rejects.toThrow("boom");
+		// finally 的 release 对 ENOENT 静默——不遮蔽原始 boom 错误（上方断言已过）
+	});
+});

package/src/__tests__/file-lock.test.ts

@@ -13,10 +13,14 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { withFileLock, withFileLockSync } from "../file-lock.ts";
 
+// 本文件全部用例都是真实文件系统 IO（跨进程锁、子进程 RMW），CI 慢盘上单次用例
+// 可达 7s+，统一放宽文件级预算（vitest 默认 5s）——断言强度不受影响
+vi.setConfig({ testTimeout: 20000 });
+
 const PKG_DIR = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
 
 describe("withFileLock (async)", () => {
@@ -56,6 +60,21 @@ describe("withFileLock (async)", () => {
 		await expect(withFileLock(target, async () => "ok")).resolves.toBe("ok");
 	});
 
+	it("嵌套取锁 → ELOCKED（retries:0 首试失败即抛，带 code；外层 finally 释放后可再锁）", async () => {
+		await expect(
+			withFileLock(
+				target,
+				() =>
+					withFileLock(target, async () => "never", {
+						retries: 0,
+						staleMs: 60_000, // stale 远大于临界区，锁不会被夺取
+					}),
+			),
+		).rejects.toMatchObject({ code: "ELOCKED" });
+		// 外层 finally 已释放 → 同一 target 立即可再锁
+		await expect(withFileLock(target, async () => "ok", { retries: 0 })).resolves.toBe("ok");
+	});
+
 	it("锁内 RMW：并发各 +1 一百次，文件终值 100（丢更新=锁失效）", async () => {
 		fs.writeFileSync(target, JSON.stringify({ n: 0 }), "utf-8");
 		const bump = (): Promise<void> =>
@@ -66,7 +85,9 @@ describe("withFileLock (async)", () => {
 			});
 		await Promise.all(Array.from({ length: 100 }, bump));
 		expect((JSON.parse(fs.readFileSync(target, "utf-8")) as { n: number }).n).toBe(100);
-	});
+		// 100 次并发锁 RMW 是真实文件系统 IO 密集测试，CI 慢盘上逼近 vitest 默认 5s，
+		// 放宽时间预算不改变断言强度（终值必须精确 100）
+	}, 20000);
 });
 
 describe("withFileLockSync", () => {
@@ -116,7 +137,7 @@ describe("真实跨进程互斥（D5a/D1e 验收形态）", () => {
 		const target = path.join(tmpDir, "shared.json");
 		fs.writeFileSync(target, JSON.stringify({ n: 0 }), "utf-8");
 		try {
-			// 子进程脚本：--experimental-strip-types 直接跑 TS（Node >= 22.6），
+			// 子进程脚本：--experimental-strip-types 直接跑 TS 源码（Node >= 22.6），
 			// 循环 50 次锁内读-改-写。exitCode 非 0 = 子进程自身失败（锁/IO 异常）。
 			const worker = `
 import * as fs from "node:fs";
@@ -130,16 +151,41 @@ for (let i = 0; i < 50; i++) {
 	});
 }
 `;
+			// src 内相对 import 无 .ts 后缀（runtime tsc 无 allowImportingTsExtensions 的
+			// 兼容形态，见 file-lock.ts 头注释），而 Node strip-types 的 ESM 严格扩展名解析
+			// 要求显式后缀——resolve 钩子在 ERR_MODULE_NOT_FOUND 时补 .ts，两个约束的交集。
+			// 纯 JS（钩子自身不经 strip-types），只对相对 specifier 生效。
+			const resolveHook = `
+export async function resolve(specifier, context, next) {
+	if (specifier.startsWith("./") || specifier.startsWith("../")) {
+		try {
+			return await next(specifier, context);
+		} catch (err) {
+			if (err && err.code === "ERR_MODULE_NOT_FOUND") return next(specifier + ".ts", context);
+			throw err;
+		}
+	}
+	return next(specifier, context);
+}
+`;
+			const registerScript = `
+import { register } from "node:module";
+register("./resolve-hook.mjs", import.meta.url);
+`;
+			fs.writeFileSync(path.join(tmpDir, "resolve-hook.mjs"), resolveHook, "utf-8");
+			fs.writeFileSync(path.join(tmpDir, "register-hooks.mjs"), registerScript, "utf-8");
 			const workerFile = path.join(tmpDir, "worker.ts");
 			fs.writeFileSync(workerFile, worker, "utf-8");
 			const procs = [1, 2].map(() =>
-				spawnSync(process.execPath, ["--experimental-strip-types", workerFile, target], {
-					encoding: "utf-8",
-					timeout: 60_000,
-				}),
+				spawnSync(
+					process.execPath,
+					["--experimental-strip-types", "--import", path.join(tmpDir, "register-hooks.mjs"), workerFile, target],
+					{ encoding: "utf-8", timeout: 60_000 },
+				),
 			);
 			for (const p of procs) {
-				expect(p.status).toBe(0);
+				// 失败消息带出 worker stderr/stdout，保证非零退出时调试信息不丢
+				expect(p.status, `worker stderr: ${p.stderr} stdout: ${p.stdout}`).toBe(0);
 			}
 			expect((JSON.parse(fs.readFileSync(target, "utf-8")) as { n: number }).n).toBe(100);
 		} finally {

package/src/__tests__/lock-core.test.ts

@@ -0,0 +1,208 @@
+// src/__tests__/lock-core.test.ts
+//
+// lock-core 零依赖锁原语单测（真实文件系统，不 mock fs）：
+//   - mkdir 上锁 / rmdir 释放（<目标>.lock 目录协议）
+//   - ELOCKED 错误码（async/sync 同构）
+//   - stale 判死夺取（先 rmdir 再 mkdir）+ stale 下限 clamp 2000ms
+//   - realpath:false 语义：不存在的目标可锁；symlink 目标锁在 symlink 路径（不解析）
+//   - graceful exit 兜底：子进程持锁正常退出后锁目录被 process.on('exit') 清理
+//
+// 协议参照：proper-lockfile@4.1.2 实装（pi 内嵌同款），逐字段兼容是 S3 互斥探针的前提。
+
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { acquireLock, acquireLockSync } from "../lock-core.ts";
+
+// 真实文件系统 IO（含子进程），放宽文件级预算（vitest 默认 5s）
+vi.setConfig({ testTimeout: 20000 });
+
+const PKG_DIR = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
+
+/** 手工构造一把「死亡进程遗留」的锁：mkdir + mtime 回拨 ageMs。 */
+function seedDeadLock(target: string, ageMs: number): string {
+	const lockPath = `${target}.lock`;
+	fs.mkdirSync(lockPath, { recursive: true });
+	const past = new Date(Date.now() - ageMs);
+	fs.utimesSync(lockPath, past, past);
+	return lockPath;
+}
+
+describe("acquireLock / release（async）", () => {
+	let tmpDir: string;
+	let target: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "lock-core-test-"));
+		target = path.join(tmpDir, "target.json");
+	});
+	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+
+	it("acquire 创建 <目标>.lock 目录，release 删除", async () => {
+		const release = await acquireLock(target);
+		const lockPath = `${target}.lock`;
+		expect(fs.existsSync(lockPath)).toBe(true);
+		expect(fs.statSync(lockPath).isDirectory()).toBe(true);
+		await release();
+		expect(fs.existsSync(lockPath)).toBe(false);
+	});
+
+	it("release 幂等（二调 no-op 不抛错）", async () => {
+		const release = await acquireLock(target);
+		await release();
+		await expect(release()).resolves.toBeUndefined();
+	});
+
+	it("重复 acquire 同一目标 → ELOCKED（code + file 字段）", async () => {
+		const release = await acquireLock(target);
+		try {
+			const err = await acquireLock(target).catch((e: unknown) => e);
+			expect((err as { code?: string }).code).toBe("ELOCKED");
+			expect((err as { file?: string }).file).toBe(target);
+			expect((err as Error).message).toContain("Lock file is already being held");
+		} finally {
+			await release();
+		}
+	});
+
+	it("stale 判死夺取：mtime 超龄 → 先 rmdir 再 mkdir，锁目录 mtime 刷新", async () => {
+		seedDeadLock(target, 31_000);
+		const logs: string[] = [];
+		const before = fs.statSync(`${target}.lock`).mtime.getTime();
+		const release = await acquireLock(target, { log: (m) => logs.push(m) });
+		try {
+			const lockPath = `${target}.lock`;
+			// 锁目录仍是目录（rmdir 后重新 mkdir），且 mtime 已刷新（夺取 = 新建）
+			expect(fs.statSync(lockPath).isDirectory()).toBe(true);
+			expect(fs.statSync(lockPath).mtime.getTime()).toBeGreaterThanOrEqual(before);
+			// 诊断日志注入可见（stale 夺取分支）
+			expect(logs.some((m) => m.includes("stale lock taken over"))).toBe(true);
+		} finally {
+			await release();
+		}
+	});
+
+	it("stale 下限 clamp 2000ms（照抄 proper-lockfile）：staleMs 50 实际按 2000 判死", async () => {
+		// mtime 老 1.5s（居中于 1s/2s 判定线之间，余量防 timing 抖动）：staleMs 50 →
+		// clamp 为 2000 → 1500 < 2000 不判死 → ELOCKED。若实现漏掉 clamp（直接用 50），
+		// 50 < 1500 将错误夺取 → 本用例红。超龄夺取路径由「stale 判死夺取」用例覆盖
+		seedDeadLock(target, 1_500);
+		await expect(acquireLock(target, { staleMs: 50 })).rejects.toMatchObject({ code: "ELOCKED" });
+		// 清理测试自造的锁目录（acquire 未持有，afterEach 的 rmSync 亦可清，显式表达意图）
+		fs.rmSync(`${target}.lock`, { recursive: true, force: true });
+	});
+
+	it("realpath:false：不存在的目标可锁；symlink 目标锁在 symlink 路径（不解析）", async () => {
+		// 目标文件不存在也可锁（realpath:true 时 ENOENT）
+		const release = await acquireLock(target);
+		expect(fs.existsSync(`${target}.lock`)).toBe(true);
+		await release();
+
+		// symlink 目标：锁必须落在 `${symlink}.lock`，不得解析到真实路径
+		const realTarget = path.join(tmpDir, "real.json");
+		fs.writeFileSync(realTarget, "{}", "utf-8");
+		const linkPath = path.join(tmpDir, "link.json");
+		fs.symlinkSync(realTarget, linkPath);
+		const releaseLink = await acquireLock(linkPath);
+		try {
+			expect(fs.existsSync(`${linkPath}.lock`)).toBe(true);
+			expect(fs.existsSync(`${realTarget}.lock`)).toBe(false);
+		} finally {
+			await releaseLink();
+		}
+	});
+
+	it("路径规范化：path.resolve 归一化（.. 消除后同锁）", async () => {
+		const release = await acquireLock(path.join(tmpDir, "sub", "..", "target.json"));
+		try {
+			// sub/.. 归一化为 tmpDir 本身 → 锁在 `${tmpDir}/target.json.lock`
+			expect(fs.existsSync(`${path.join(tmpDir, "target.json")}.lock`)).toBe(true);
+			expect(fs.existsSync(`${path.join(tmpDir, "sub")}`)).toBe(false);
+		} finally {
+			await release();
+		}
+	});
+});
+
+describe("acquireLockSync", () => {
+	let tmpDir: string;
+	let target: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "lock-core-sync-test-"));
+		target = path.join(tmpDir, "target.json");
+	});
+	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+
+	it("acquire/release 同构 async 版（目录创建与删除）", () => {
+		const release = acquireLockSync(target);
+		expect(fs.statSync(`${target}.lock`).isDirectory()).toBe(true);
+		release();
+		expect(fs.existsSync(`${target}.lock`)).toBe(false);
+	});
+
+	it("重复 acquireSync → ELOCKED", () => {
+		const release = acquireLockSync(target);
+		try {
+			try {
+				acquireLockSync(target);
+				expect.unreachable("must throw");
+			} catch (err) {
+				expect((err as Error).message).toContain("Lock file is already being held");
+				expect((err as { code?: string }).code).toBe("ELOCKED");
+			}
+		} finally {
+			release();
+		}
+	});
+
+	it("sync 版 stale 夺取", () => {
+		seedDeadLock(target, 31_000);
+		const logs: string[] = [];
+		const release = acquireLockSync(target, { log: (m) => logs.push(m) });
+		try {
+			expect(fs.statSync(`${target}.lock`).isDirectory()).toBe(true);
+			expect(logs.some((m) => m.includes("stale lock taken over"))).toBe(true);
+		} finally {
+			release();
+		}
+	});
+});
+
+describe("graceful exit 兜底（process.on('exit') 配对 rmdir）", () => {
+	it("子进程持锁正常退出后，锁目录被 exit hook 清理（无需等 stale）", () => {
+		const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "lock-core-exit-"));
+		const target = path.join(tmpDir, "target.json");
+		try {
+			// 子进程 acquire 后自然退出（graceful exit）——'exit' hook 必须清掉锁目录。
+			// 子进程内先断言锁已创建（证明「锁曾存在」），失败以非零退出码表达（不用
+			// console——extensions 日志规范禁 console；诊断信息由父进程断言消息带出）。
+			const worker = `
+import * as fs from "node:fs";
+import { acquireLock } from "${PKG_DIR}/src/lock-core.ts";
+const target = process.argv[2];
+await acquireLock(target);
+if (!fs.existsSync(target + ".lock")) {
+	process.exit(1);
+}
+`;
+			const workerFile = path.join(tmpDir, "worker.ts");
+			fs.writeFileSync(workerFile, worker, "utf-8");
+			const proc = spawnSync(process.execPath, ["--experimental-strip-types", workerFile, target], {
+				encoding: "utf-8",
+				timeout: 30_000,
+			});
+			// 失败消息带出 worker stderr/stdout，保证非零退出时调试信息不丢
+			expect(proc.status, `worker stderr: ${proc.stderr} stdout: ${proc.stdout}`).toBe(0);
+			// graceful exit 后锁目录不残留（等价 proper-lockfile signal-exit 清理语义）
+			expect(fs.existsSync(`${target}.lock`)).toBe(false);
+		} finally {
+			fs.rmSync(tmpDir, { recursive: true, force: true });
+		}
+	});
+});

package/src/file-lock.ts

@@ -1,6 +1,6 @@
 // src/file-lock.ts
 //
-// 跨进程异步文件锁（extension 侧共享 util，D5a/D1e，integrity-hardening.md §3.5）。
+// 跨进程异步/同步文件锁（extension 侧共享 util，D5a/D1e，integrity-hardening.md §3.5）。
 //
 // 为什么存在：worktrees.json（多 pi 进程各一份扩展实例写）与 ext-config 家族
 // （runtime + 扩展双写）都是跨进程 RMW——Node 单线程只能保证进程内不交错，
@@ -8,37 +8,46 @@
 //
 // 为什么是 async API 而非 runtime 侧的 withFileLockSync：扩展跑在 pi 子进程的
 // async hook 上下文（session_start 等），同步 busy-wait 会阻塞整个 event loop；
-// proper-lockfile 的 async lock() 原生支持 retries 指数退避（sync API 与 retries
-// 组合抛 ESYNC），不需要 runtime 侧那套自实现 busy-wait。
+// async 版用指数退避重试（本文件编排），sync 版保持同步 busy-wait。
+//
+// 锁原语：自实现 mkdir-lock（src/lock-core.ts，D1-A，零第三方依赖）。磁盘协议与
+// pi 内嵌 proper-lockfile@4.1.2 逐字段兼容（协议细节与行为边界声明见 lock-core.ts
+// 头注释——关键边界：无周期保活 touch，临界区必须远小于 stale）。本文件职责：
+// 重试编排 + 对外 API + 诊断 logger 装配（logger 本体由包入口 index.ts 注入，
+// 本文件不 import extension-logger——lock-core 的零依赖约束向上传导）。
 //
 // 锁协议（与 runtime 侧 packages/runtime/src/utils/file-lock.ts 对齐，登记表
 // docs/architecture/data-source-registry.md §6）：
-//   - lockfile 路径 = <目标文件>.lock（proper-lockfile 默认，双方路径一致才互斥）
-//   - realpath:false —— 目标文件不存在也可锁（realpath 默认 true 时 ENOENT），
-//     与 runtime 侧参数一致；锁前确保父目录存在
+//   - lockfile 路径 = <目标文件>.lock（双方路径一致才互斥）
+//   - realpath:false —— 目标文件不存在也可锁；不解析 symlink
 //   - stale 30s：持锁进程崩溃后锁可被夺取（对齐 auth 惯例）
-//   - async 版 retries 指数退避：10 次 / factor 2 / 100ms~10s / randomize（对齐 pi
-//     FileAuthStorageBackend.withLockAsync，见 runtime auth-storage.ts:48-74 范本）
+//   - async 版退避重试：10 次重试 / factor 2 / 100ms~10s / randomize（公式与
+//     proper-lockfile 内部 retry 库一致，对齐 pi FileAuthStorageBackend.withLockAsync
+//     及 runtime auth-storage.ts 范本；首试 + 10 重试 = 最多 11 次 acquire）
 //   - sync 版 busy-wait 重试（25ms / 预算 1s fail-fast）：对齐 runtime 侧
-//     withFileLockSync——proper-lockfile 的 sync API 与 retries 组合抛 ESYNC，
-//     重试必须在外层同步循环做；ext-config 家族的扩展侧写方（saveConfig）
-//     保持 sync 签名（调用链零波及），与 runtime 对端用同一把 lockfile 互斥
-//   - onCompromised：锁被判定 stale 夺取时标记，fn 执行前抛错——防止在失去
-//     互斥保证的锁下写盘（对齐 pi throwIfCompromised 语义）
+//     withFileLockSync；ext-config 家族的扩展侧写方（saveConfig）保持 sync 签名
+//     （调用链零波及），与 runtime 对端用同一把 lockfile 互斥
+//   - onCompromised 语义随保活 touch 一并移除（无保活则无 compromise 检测）：
+//     锁目录被外部删除时 release 静默成功（ENOENT 容忍，见 lock-core.ts removeLock）
 //
 // 契约：fn 内禁止任何 await / 再次对本文件加锁（嵌套取锁 ELOCKED → 重试耗尽 →
-// 抛错）；持锁范围应为「读文件 + 纯内存变更 + 原子写」，毫秒级。
+// 抛错）；持锁范围应为「读文件 + 纯内存变更 + 原子写」，毫秒级（必须远小于
+// stale 30s——无保活 touch，超时持锁会被对端夺取）。
 
-import { existsSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+import {
+	acquireLock,
+	acquireLockSync,
+	DEFAULT_STALE_MS,
+	type LockRelease,
+} from "./lock-core";
 
-import lockfile from "proper-lockfile";
+export { DEFAULT_STALE_MS };
 
 /** 锁参数（默认值对齐 auth-storage.ts 范本；测试可覆盖以缩短等待）。 */
 export interface FileLockOptions {
 	/** 锁 mtime 超过该值视为持锁者已死可夺取（stale 语义）。默认 30_000ms。 */
 	staleMs?: number;
-	/** retries 总次数。默认 10。 */
+	/** retries 重试次数（首试之外）。默认 10。 */
 	retries?: number;
 }
 
@@ -54,62 +63,80 @@ export interface SyncFileLockOptions {
 
 // 默认锁参数（sync 版导出供对照测试断言与 runtime 侧 utils/file-lock.ts 默认值相等
 // ——两侧参数漂移会破坏「同一把锁」的互斥语义；runtime 侧 test/file-lock-parity.test.ts）
-export const DEFAULT_STALE_MS = 30_000;
 const DEFAULT_RETRIES = 10;
 export const DEFAULT_RETRY_DELAY_MS = 25;
 export const DEFAULT_RETRY_BUDGET_MS = 1_000;
 
+// 退避参数（对齐 proper-lockfile 4.1.2 内部 retry 库的调用参数，即旧版
+// retries: { retries: 10, factor: 2, minTimeout: 100, maxTimeout: 10_000, randomize: true }）
+const RETRY_FACTOR = 2;
+const RETRY_MIN_TIMEOUT_MS = 100;
+const RETRY_MAX_TIMEOUT_MS = 10_000;
+
+// 诊断 logger：由包入口 index.ts 经 setFileLockLogger 注入（core 不沾 logger 依赖）。
+// 默认 no-op——不经入口直接 import 本文件的测试/工具静默无日志。
+let diagnosticsLogger: ((msg: string) => void) | undefined;
+
+/**
+ * 注入诊断日志函数（包入口装配点；传 undefined 恢复 no-op）。
+ * 诊断内容：stale 夺取、release 失败等关键分支。
+ */
+export function setFileLockLogger(log?: (msg: string) => void): void {
+	diagnosticsLogger = log;
+}
+
+/**
+ * 第 attempt 次尝试失败后的退避等待（attempt 从 0 计）。
+ * 公式照抄 proper-lockfile 内部 retry 库（retry.timeouts/createTimeout）：
+ *   randomize ? round((random()+1) * minTimeout * factor**attempt) capped maxTimeout
+ * 倍率区间 [1, 2)，故第 attempt 次等待 ∈ [minTimeout*factor**attempt, 2*...)，上限 10s。
+ */
+function backoffDelayMs(attempt: number): number {
+	const exponential = RETRY_MIN_TIMEOUT_MS * RETRY_FACTOR ** attempt;
+	return Math.min(Math.round((Math.random() + 1) * exponential), RETRY_MAX_TIMEOUT_MS);
+}
+
 /**
- * 跨进程文件锁内执行 async fn：拿不到锁时指数退避重试（100ms~10s/randomize），
- * 重试耗尽抛 proper-lockfile 的 ELOCKED 错误（调用方决定降级路径）；
- * unlock 放 finally（fn 抛错也释放，compromised 时 unlock 失败可忽略）。
+ * 跨进程文件锁内执行 async fn：拿不到锁时指数退避重试（100ms~10s/randomize，
+ * 首试 + retries 次 = 默认最多 11 次 acquire），重试耗尽抛 code:"ELOCKED" 错误
+ * （调用方决定降级路径）；unlock 放 finally（fn 抛错也释放；锁目录已被外部删除时
+ * release 静默成功）。
  */
 export async function withFileLock<T>(
 	filePath: string,
 	fn: () => Promise<T>,
 	opts?: FileLockOptions,
 ): Promise<T> {
-	// 锁前确保父目录存在：proper-lockfile 创建 lockfile（<目标>.lock）需要目录在
-	const dir = dirname(filePath);
-	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-
-	// onCompromised：锁被 stale 夺取（进程卡死超时等）时标记，fn 执行前抛错，
-	// 防止在失去互斥保证的锁下写盘（对齐 pi throwIfCompromised）。
-	let compromised: Error | undefined;
-	const release = await lockfile.lock(filePath, {
-		realpath: false,
-		retries: {
-			retries: opts?.retries ?? DEFAULT_RETRIES,
-			factor: 2,
-			minTimeout: 100,
-			maxTimeout: 10_000,
-			randomize: true,
-		},
-		stale: opts?.staleMs ?? DEFAULT_STALE_MS,
-		onCompromised: (err: Error) => {
-			compromised = err;
-		},
-	});
+	const retries = opts?.retries ?? DEFAULT_RETRIES;
+	const staleMs = opts?.staleMs ?? DEFAULT_STALE_MS;
+
+	let release: LockRelease | undefined;
+	for (let attempt = 0; release === undefined; attempt++) {
+		try {
+			release = await acquireLock(filePath, { staleMs, log: diagnosticsLogger });
+		} catch (err) {
+			if (!isElocked(err)) throw err;
+			// 首试 + retries 次重试全部失败 → 抛 ELOCKED（对齐 retry 库 retries 次数语义）
+			if (attempt >= retries) throw err;
+			await sleep(backoffDelayMs(attempt));
+		}
+	}
 	try {
-		if (compromised) throw compromised;
 		return await fn();
 	} finally {
 		try {
 			await release();
-		} catch (unlockErr) {
-			// 锁已 compromised（被 stale 夺取）时 unlock 必然失败且可忽略——
-			// 记录留痕（对齐 pi finally 的 catch 语义：不外抛、不静默）。
-			console.debug(
-				"[file-lock] unlock failed after compromise (ignorable):",
-				unlockErr instanceof Error ? unlockErr.message : String(unlockErr),
-			);
+		} catch (releaseErr) {
+			// release 仅在非 ENOENT 的 fs 错误（权限等）时失败——不外抛（fn 结果优先），
+			// 注入 logger 时留痕供排查
+			diagnosticsLogger?.(`[file-lock] release failed (ignorable): ${stringifyErr(releaseErr)}`);
 		}
 	}
 }
 
 /**
- * 同步跨进程文件锁内执行 fn：lockSync(realpath:false) + ELOCKED busy-wait 重试，
- * 预算耗尽抛带 ELOCKED code 的错误；unlock 放 finally（fn 抛错也释放）。
+ * 同步跨进程文件锁内执行 fn：ELOCKED busy-wait 重试，预算耗尽抛带 ELOCKED code
+ * 的错误；unlock 放 finally（fn 抛错也释放）。
  *
  * 与 async 版锁同一把 lockfile（<目标文件>.lock）——sync/async API 在磁盘上
  * 是同一协议，互斥不依赖调用形态。适用场景：调用链必须保持 sync 签名
@@ -125,14 +152,11 @@ export function withFileLockSync<T>(
 	const retryDelayMs = opts?.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
 	const retryBudgetMs = opts?.retryBudgetMs ?? DEFAULT_RETRY_BUDGET_MS;
 
-	const dir = dirname(filePath);
-	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-
 	const deadline = Date.now() + retryBudgetMs;
 	let release: (() => void) | undefined;
 	while (release === undefined) {
 		try {
-			release = lockfile.lockSync(filePath, { realpath: false, stale: staleMs });
+			release = acquireLockSync(filePath, { staleMs, log: diagnosticsLogger });
 		} catch (err) {
 			if (!isElocked(err)) throw err;
 			if (Date.now() >= deadline) {
@@ -140,7 +164,7 @@ export function withFileLockSync<T>(
 					new Error(
 						`[file-lock] ${filePath} 写锁获取失败：ELOCKED 重试预算 ${retryBudgetMs}ms 耗尽` +
 						`（持锁方临界区异常或已崩溃，stale ${staleMs}ms 后可夺取）。恢复指引：稍后重试本次写入。`,
-						// cause 挂原始 ELOCKED 错误，保留 proper-lockfile 诊断信息
+						// cause 挂原始 ELOCKED 错误，保留锁原语诊断信息
 						{ cause: err },
 					),
 					{ code: "ELOCKED" },
@@ -161,9 +185,17 @@ function isElocked(err: unknown): boolean {
 	return err instanceof Error && "code" in err && err.code === "ELOCKED";
 }
 
+function stringifyErr(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
 /** Atomics.wait 需要一个共享内存对象作等待目标；4 字节 = 一个 Int32 元素，仅占位不被写入。 */
 const SLEEP_WAIT_BUFFER = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
 
 function sleepSync(ms: number): void {
 	Atomics.wait(SLEEP_WAIT_BUFFER, 0, 0, ms);
 }
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/index.ts

@@ -1,6 +1,26 @@
+// src/index.ts
+//
+// 包入口 + logger 装配点（D1-A：锁实现文件不 import extension-logger——
+// lock-core 零依赖约束向上传导至本文件唯一的 logger import 处）。
+// runtime 侧经 `@zhushanwen/pi-file-lock/core` 子入口直接用锁原语，不经本文件、
+// 不拉 logger 依赖；extension 侧经本文件入口使用，logger 在此注入。
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+import {
+	setFileLockLogger,
+	withFileLock,
+	withFileLockSync,
+	type FileLockOptions,
+	type SyncFileLockOptions,
+} from "./file-lock";
+
+const logger = getLogger("file-lock");
+setFileLockLogger((msg) => logger.debug(msg));
+
 export {
 	withFileLock,
 	withFileLockSync,
 	type FileLockOptions,
 	type SyncFileLockOptions,
-} from "./file-lock.ts";
+};

package/src/lock-core.ts

@@ -0,0 +1,260 @@
+// src/lock-core.ts
+//
+// 零依赖跨进程 mkdir 锁原语（D1-A 自实现，docs/design/file-lock-unification-and-reaper-sink.md §3.2）。
+//
+// 为什么自实现：包名入口原先包 proper-lockfile，但 runtime 经 tsup bundle 复用它时，
+// 第三方对模块对象的内部操作（probe 精度缓存的 fs symbol）在 jiti 类加载器下失效——
+// 本次事故根因。本文件只用 node:fs / node:path 内置调用实现同一磁盘协议，天然免疫
+// 模块系统包装；runtime 经 `@zhushanwen/pi-file-lock/core` 子入口复用同一实现。
+//
+// 磁盘协议（逐字段照抄 proper-lockfile@4.1.2 实装 lib/lockfile.js——与 pi 内嵌版互斥
+// 同一把锁的兼容性权威源；4.1.2 的 acquireLock/releaseLock 已内联在该文件）：
+//   - 锁文件 = path.resolve(目标) + '.lock' 目录（mkdir 原子上锁）。realpath:false 分支：
+//     仅字符串绝对化（path.resolve），不解析 symlink
+//   - mkdir EEXIST → stat 锁目录 mtime，`mtime < Date.now() - stale` 判死；stale 下限
+//     clamp 2000ms（照抄 `options.stale = Math.max(options.stale || 0, 2000)`）
+//   - stale → 先 rmdir 再 mkdir 夺取。两步间存在竞态窗口（他方同时夺取），与
+//     proper-lockfile 语义一致，接受
+//   - 判死检查中锁目录 ENOENT（他方刚释放/刚夺取）→ 以 stale:0 重试（跳过判死直接
+//     mkdir，失败即 ELOCKED），照抄防无限递归的结构
+//   - 释放 = rmdir，容忍 ENOENT（照抄 removeLock）
+//   - graceful exit 兜底：process.on('exit') 配对 rmdirSync，避免优雅退出后锁残留
+//     要等 30s stale 才能夺取。覆盖范围边界：'exit' 只覆盖正常退出与 process.exit；
+//     信号默认终止（SIGINT/SIGTERM 无 handler）场景 'exit' 不触发（proper-lockfile
+//     经 signal-exit 额外覆盖该路径），锁残留回退 30s stale 夺取（同 SIGKILL 崩溃路径）
+//
+// 与 proper-lockfile 的行为边界（设计显式决策，非遗漏）：
+//   - 不做周期 utimes 保活（proper-lockfile 的 updateLock 定时器）：现有契约临界区
+//     毫秒级，远小于 stale/2；持锁超过 stale 的进程视为已死可被夺取。锁 mtime 即
+//     mkdir 时刻，此后不变
+//   - 因此无 compromise 检测（保活定时器 stat/utimes 失败路径不存在）；release 对
+//     锁目录已被外部删除的场景静默成功（ENOENT 容忍）
+//   - 被夺取后 release 的二阶后果：本方持锁被对端 stale 夺取后，本方 release 的
+//     rmdir（及 exit-hook）会删除夺取者新建的锁目录——proper-lockfile 同场景由
+//     updateLock 发现 mtime 非 ours 而拒绝 unlock，自实现无保活故无此防线。
+//     触发前提 = 临界区违约超 stale 30s（契约要求毫秒级，违约 30000 倍才可达），
+//     风险接受（设计显式决策，此处显式声明）
+//
+// 零依赖约束（D1-A）：本文件不得 import 任何项目内包或第三方包——extension-logger
+// 携带 pi SDK peerDep 链，经 runtime re-export 会穿越 pi 边界。诊断日志走 opts.log
+// 注入（包入口 index.ts 注入 extension-logger，runtime 不注入）。
+
+import { mkdirSync, rmdirSync, statSync } from "node:fs";
+import { mkdir, rmdir, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+/** 锁 mtime 超过该值视为持锁者已死可夺取。默认 30_000ms（对齐 auth 惯例）。 */
+export const DEFAULT_STALE_MS = 30_000;
+
+/** stale 判死下限 clamp（照抄 proper-lockfile：`Math.max(options.stale || 0, 2000)`）。 */
+const MIN_STALE_MS = 2_000;
+
+/** 锁原语选项。 */
+export interface LockCoreOptions {
+	/** 锁 mtime 超过该值视为持锁者已死可夺取。下限 clamp 2000ms。默认 DEFAULT_STALE_MS。 */
+	staleMs?: number;
+	/** 诊断日志注入（stale 夺取等关键分支）。core 自身零输出。 */
+	log?: (msg: string) => void;
+}
+
+/** async release 函数：释放锁目录（幂等；锁目录已消失时静默成功）。 */
+export type LockRelease = () => Promise<void>;
+
+// ──────────────────────── 协议原语（照抄 lockfile.js 对应函数） ────────────────────────
+
+/** realpath:false 分支：仅字符串绝对化，不解析 symlink（照抄 resolveCanonicalPath）。 */
+function resolveTarget(filePath: string): string {
+	return resolve(filePath);
+}
+
+/** 照抄 getLockFile：`options.lockfilePath || \`${file}.lock\``（不自定义 lockfilePath）。 */
+function lockPathOf(target: string): string {
+	return `${target}.lock`;
+}
+
+/** 照抄 isLockStale：`stat.mtime.getTime() < Date.now() - stale`。 */
+function isLockStale(mtimeMs: number, staleMs: number): boolean {
+	return mtimeMs < Date.now() - staleMs;
+}
+
+/** ELOCKED 错误（message/fields 照抄 proper-lockfile）。 */
+function elocked(target: string): Error {
+	return Object.assign(new Error("Lock file is already being held"), { code: "ELOCKED", file: target });
+}
+
+/** Node fs 错误 code 收窄（in 收窄，禁 as 断言——taste/no-unsafe-cast）。 */
+function errCode(err: unknown): string | undefined {
+	return err instanceof Error && "code" in err && typeof err.code === "string" ? err.code : undefined;
+}
+
+/** 锁前确保父目录存在（mkdir lockfile 需要；recursive 对已存在目录静默成功）。 */
+async function ensureParentDir(target: string): Promise<void> {
+	await mkdir(dirname(target), { recursive: true });
+}
+
+// ──────────────────────── graceful exit 兜底（照抄 signal-exit 清理语义） ────────────────────────
+
+/**
+ * 当前进程持有的活跃锁（key = lockfilePath，value = 该锁的诊断 log 注入）。
+ * release/夺取移除时同步删表。
+ */
+const activeLocks = new Map<string, ((msg: string) => void) | undefined>();
+
+let exitHookInstalled = false;
+
+/**
+ * 进程退出点配对清理（模块级注册一次）：exit handler 内只能同步操作，用 rmdirSync。
+ * 单把锁清理失败仅经注入 log 留痕、不阻断其余锁清理——进程已终止，无恢复动作
+ * （对齐 proper-lockfile onExit 的逐把 try/catch，可观测性略强）。
+ */
+function installExitHook(): void {
+	if (exitHookInstalled) return;
+	exitHookInstalled = true;
+	process.on("exit", () => {
+		for (const [lockfilePath, log] of activeLocks) {
+			try {
+				rmdirSync(lockfilePath);
+			} catch (err) {
+				log?.(`[lock-core] exit cleanup failed for ${lockfilePath}: ${errCode(err) ?? String(err)}`);
+			}
+		}
+		activeLocks.clear();
+	});
+}
+
+/** 单次释放（rmdir，容忍 ENOENT——照抄 removeLock）。 */
+async function removeLockAsync(lockfilePath: string): Promise<void> {
+	try {
+		await rmdir(lockfilePath);
+	} catch (err) {
+		if (errCode(err) !== "ENOENT") throw err;
+	}
+}
+
+/** removeLockAsync 的同步版。 */
+function removeLockSync(lockfilePath: string): void {
+	try {
+		rmdirSync(lockfilePath);
+	} catch (err) {
+		if (errCode(err) !== "ENOENT") throw err;
+	}
+}
+
+/** release 闭包：幂等（二调 no-op）；释放即出活跃锁表。 */
+function makeRelease(lockfilePath: string): LockRelease {
+	let released = false;
+	return async () => {
+		if (released) return;
+		released = true;
+		activeLocks.delete(lockfilePath);
+		await removeLockAsync(lockfilePath);
+	};
+}
+
+// ──────────────────────── acquire ────────────────────────
+
+/**
+ * 照抄 acquireLock（async 版）：mkdir 成功即获锁；EEXIST → stale 判死 → 夺取；
+ * stale<=0（重试轮）直接 ELOCKED，跳过判死防递归。
+ */
+async function acquireOnceAsync(target: string, lockfilePath: string, staleMs: number, log: ((msg: string) => void) | undefined): Promise<void> {
+	let acquired = false;
+	try {
+		await mkdir(lockfilePath);
+		acquired = true;
+	} catch (err) {
+		if (errCode(err) !== "EEXIST") throw err;
+	}
+
+	if (acquired) {
+		activeLocks.set(lockfilePath, log);
+		return;
+	}
+
+	// 重试轮（stale:0）：不再判死，失败即 ELOCKED（照抄 `options.stale <= 0` 分支）
+	if (staleMs <= 0) throw elocked(target);
+
+	let mtimeMs: number;
+	try {
+		mtimeMs = (await stat(lockfilePath)).mtime.getTime();
+	} catch (err) {
+		// 锁目录刚被释放/夺取：跳过判死直接重试（照抄 ENOENT → stale:0 重入，防递归）
+		if (errCode(err) === "ENOENT") return acquireOnceAsync(target, lockfilePath, 0, log);
+		throw err;
+	}
+
+	if (!isLockStale(mtimeMs, staleMs)) throw elocked(target);
+
+	log?.(`[lock-core] stale lock taken over: ${lockfilePath} (mtime age > ${staleMs}ms), removing and retrying`);
+	await removeLockAsync(lockfilePath);
+	return acquireOnceAsync(target, lockfilePath, 0, log);
+}
+
+/**
+ * acquireLockSync（照抄 acquireLock 的 sync 语义，同构 acquireOnceAsync）。
+ */
+function acquireOnceSync(target: string, lockfilePath: string, staleMs: number, log: ((msg: string) => void) | undefined): void {
+	let acquired = false;
+	try {
+		mkdirSync(lockfilePath);
+		acquired = true;
+	} catch (err) {
+		if (errCode(err) !== "EEXIST") throw err;
+	}
+
+	if (acquired) {
+		activeLocks.set(lockfilePath, log);
+		return;
+	}
+
+	if (staleMs <= 0) throw elocked(target);
+
+	let mtimeMs: number;
+	try {
+		mtimeMs = statSync(lockfilePath).mtime.getTime();
+	} catch (err) {
+		if (errCode(err) === "ENOENT") return acquireOnceSync(target, lockfilePath, 0, log);
+		throw err;
+	}
+
+	if (!isLockStale(mtimeMs, staleMs)) throw elocked(target);
+
+	log?.(`[lock-core] stale lock taken over: ${lockfilePath} (mtime age > ${staleMs}ms), removing and retrying`);
+	removeLockSync(lockfilePath);
+	return acquireOnceSync(target, lockfilePath, 0, log);
+}
+
+// ──────────────────────── 对外 API ────────────────────────
+
+/**
+ * 单次获取跨进程锁：成功返回 release（幂等）；锁被他人持有且未 stale 时抛
+ * code:"ELOCKED" 错误（重试编排属消费方：包入口 async 退避 / sync busy-wait）。
+ */
+export async function acquireLock(filePath: string, opts?: LockCoreOptions): Promise<LockRelease> {
+	const target = resolveTarget(filePath);
+	const lockfilePath = lockPathOf(target);
+	const staleMs = Math.max(opts?.staleMs ?? DEFAULT_STALE_MS, MIN_STALE_MS);
+	await ensureParentDir(target);
+	installExitHook();
+	await acquireOnceAsync(target, lockfilePath, staleMs, opts?.log);
+	return makeRelease(lockfilePath);
+}
+
+/**
+ * acquireLock 的同步版（sync 调用链专用；语义同 async 版，无事件循环依赖）。
+ */
+export function acquireLockSync(filePath: string, opts?: LockCoreOptions): () => void {
+	const target = resolveTarget(filePath);
+	const lockfilePath = lockPathOf(target);
+	const staleMs = Math.max(opts?.staleMs ?? DEFAULT_STALE_MS, MIN_STALE_MS);
+	mkdirSync(dirname(target), { recursive: true });
+	installExitHook();
+	acquireOnceSync(target, lockfilePath, staleMs, opts?.log);
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		activeLocks.delete(lockfilePath);
+		removeLockSync(lockfilePath);
+	};
+}

package/index.ts

@@ -1,7 +0,0 @@
-// Re-export barrel：pi 包惯例（源码在 src/，包根 index.ts 只做转发）。
-export {
-	withFileLock,
-	withFileLockSync,
-	type FileLockOptions,
-	type SyncFileLockOptions,
-} from "./src/file-lock.ts";