@zhushanwen/pi-file-lock 0.2.0 → 0.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-file-lock",
-  "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).",
+  "version": "0.4.0",
+  "description": "Shared sync 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 busy-wait retry, aligned with the runtime-side lock protocol (shared library, not a Pi extension).",
   "type": "module",
   "main": "src/index.ts",
   "exports": {
@@ -21,7 +21,7 @@
     "src/"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.4.0"
+    "@zhushanwen/pi-extension-logger": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

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

@@ -13,9 +13,9 @@ import * as path from "node:path";
 
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
-import { withFileLock } from "../file-lock.ts";
+import { withFileLockSync } from "../file-lock.ts";
 
-describe("withFileLock 锁目录被外部删除（原 compromise 场景的自实现语义）", () => {
+describe("withFileLockSync 锁目录被外部删除（原 compromise 场景的自实现语义）", () => {
 	let tmpDir: string;
 	let target: string;
 
@@ -23,15 +23,15 @@ describe("withFileLock 锁目录被外部删除（原 compromise 场景的自实
 		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "file-lock-extrem-"));
 		target = path.join(tmpDir, "target.json");
 	});
-	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 }));
 
-	it("fn 执行期间锁被外部删除 → fn 正常返回 + release 静默成功 + 可立即再锁", async () => {
-		const result = await withFileLock(
+	it("fn 执行期间锁被外部删除 → fn 正常返回 + release 静默成功 + 可立即再锁", () => {
+		const result = withFileLockSync(
 			target,
-			async () => {
+			() => {
 				// 模拟外部清理（对端 stale 夺取会先 rmdir 再 mkdir；此处直接删）：
 				// 自实现无保活定时器，删除本身不触发任何回调
-				fs.rmSync(`${target}.lock`, { recursive: true, force: true });
+				fs.rmSync(`${target}.lock`, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 				return "fn-done";
 			},
 			{ staleMs: 2000 },
@@ -40,17 +40,17 @@ describe("withFileLock 锁目录被外部删除（原 compromise 场景的自实
 		// fn 结果原样返回（无 compromised 拦截——该机制随保活一并移除）
 		expect(result).toBe("fn-done");
 		// release 对已消失的锁目录静默成功（ENOENT 容忍）——由下一断言间接证明：
-		// 若 release 抛错，withFileLock 会吞错但此处再锁也必然成功；直接再锁验证锁已释放
-		await expect(withFileLock(target, async () => "again")).resolves.toBe("again");
+		// 若 release 抛错，sync 版 finally 不吞错会直接外抛；直接再锁验证锁已释放
+		expect(withFileLockSync(target, () => "again")).toBe("again");
 	});
 
-	it("fn 抛错且锁目录已被外部删除 → 错误照常外抛 + release 不叠加失败", async () => {
-		await expect(
-			withFileLock(target, () => {
-				fs.rmSync(`${target}.lock`, { recursive: true, force: true });
+	it("fn 抛错且锁目录已被外部删除 → 错误照常外抛 + release 不叠加失败", () => {
+		expect(() =>
+			withFileLockSync(target, () => {
+				fs.rmSync(`${target}.lock`, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 				throw new Error("boom");
 			}),
-		).rejects.toThrow("boom");
+		).toThrow("boom");
 		// finally 的 release 对 ENOENT 静默——不遮蔽原始 boom 错误（上方断言已过）
 	});
 });

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

@@ -1,7 +1,7 @@
 // src/__tests__/file-lock.test.ts
 //
 // 跨进程文件锁单测（真实文件系统，不 mock fs）：
-//   - async/sync 版临界区互斥（并发不交错）
+//   - sync 版临界区互斥（并发不交错）
 //   - unlock 后可再锁（finally 释放语义）
 //   - sync 版 fail-fast（ELOCKED 预算耗尽抛错，不用默认 1s——测试覆盖盖短预算）
 //   - 真实跨进程互斥：两个 node 子进程并发 RMW 同一 JSON 文件，计数零丢失
@@ -15,7 +15,7 @@ import { fileURLToPath } from "node:url";
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { withFileLock, withFileLockSync } from "../file-lock.ts";
+import { withFileLockSync } from "../file-lock.ts";
 
 // 本文件全部用例都是真实文件系统 IO（跨进程锁、子进程 RMW），CI 慢盘上单次用例
 // 可达 7s+，统一放宽文件级预算（vitest 默认 5s）——断言强度不受影响
@@ -23,73 +23,6 @@ vi.setConfig({ testTimeout: 20000 });
 
 const PKG_DIR = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
 
-describe("withFileLock (async)", () => {
-	let tmpDir: string;
-	let target: string;
-
-	beforeEach(() => {
-		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "file-lock-test-"));
-		target = path.join(tmpDir, "target.json");
-	});
-	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-	it("并发临界区互斥：计数无交错丢失", async () => {
-		let counter = 0;
-		const inside: number[] = [];
-		const tasks = Array.from({ length: 20 }, () =>
-			withFileLock(target, async () => {
-				counter += 1;
-				inside.push(counter);
-				// 让出 event loop 制造无锁时必交错的窗口
-				await new Promise((r) => setTimeout(r, 1));
-			}),
-		);
-		await Promise.all(tasks);
-		expect(counter).toBe(20);
-		// 每个临界区进入时的 counter 单调 +1（无两个临界区读到同值）
-		expect(new Set(inside).size).toBe(20);
-	});
-
-	it("fn 抛错也释放锁（finally 语义：后续可再锁）", async () => {
-		await expect(
-			withFileLock(target, async () => {
-				throw new Error("boom");
-			}),
-		).rejects.toThrow("boom");
-		// 同一 target 立即可再锁 = 前次已释放
-		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> =>
-			withFileLock(target, async () => {
-				const cur = JSON.parse(fs.readFileSync(target, "utf-8")) as { n: number };
-				cur.n += 1;
-				fs.writeFileSync(target, JSON.stringify(cur), "utf-8");
-			});
-		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", () => {
 	let tmpDir: string;
 	let target: string;
@@ -98,7 +31,7 @@ describe("withFileLockSync", () => {
 		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "file-lock-sync-test-"));
 		target = path.join(tmpDir, "target.json");
 	});
-	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 }));
 
 	it("返回 fn 结果且锁已释放（可立即再锁）", () => {
 		expect(withFileLockSync(target, () => 42)).toBe(42);
@@ -136,19 +69,35 @@ describe("真实跨进程互斥（D5a/D1e 验收形态）", () => {
 		const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "file-lock-xproc-"));
 		const target = path.join(tmpDir, "shared.json");
 		fs.writeFileSync(target, JSON.stringify({ n: 0 }), "utf-8");
-		try {
-			// 子进程脚本：--experimental-strip-types 直接跑 TS 源码（Node >= 22.6），
-			// 循环 50 次锁内读-改-写。exitCode 非 0 = 子进程自身失败（锁/IO 异常）。
-			const worker = `
+	try {
+		// 子进程脚本：--experimental-strip-types 直接跑 TS 源码（Node >= 22.6），
+		// 循环 50 次锁内读-改-写。exitCode 非 0 = 子进程自身失败（锁/IO 异常）。
+		// 锁获取形态：withFileLockSync 传 retryBudgetMs:0（单次 fail-fast）+ 外层
+		// ELOCKED 固定 20ms 间隔重试自旋、30s 预算（对齐 runtime 侧
+		// pi-settings-store.test.ts 的 acquireLikePi 修复形态）——满载下临界区持有
+		// 窗口可能被 OS 抢占拉长，默认 fail-fast 预算会被偶发耗尽致子进程非零退出；
+		// 重试预算保证合理时间内必能拿到锁，互斥语义（lock-core 层）不受等待形态影响。
+		const worker = `
 import * as fs from "node:fs";
-import { withFileLock } from "${PKG_DIR}/src/file-lock.ts";
+import { withFileLockSync } from "${PKG_DIR}/src/file-lock.ts";
 const target = process.argv[2];
+async function lockedRmw() {
+	const deadline = Date.now() + 30_000;
+	for (;;) {
+		try {
+			return withFileLockSync(target, () => {
+				const cur = JSON.parse(fs.readFileSync(target, "utf-8"));
+				cur.n += 1;
+				fs.writeFileSync(target, JSON.stringify(cur), "utf-8");
+			}, { retryBudgetMs: 0 });
+		} catch (err) {
+			if (!err || err.code !== "ELOCKED" || Date.now() >= deadline) throw err;
+			await new Promise((r) => setTimeout(r, 20));
+		}
+	}
+}
 for (let i = 0; i < 50; i++) {
-	await withFileLock(target, async () => {
-		const cur = JSON.parse(fs.readFileSync(target, "utf-8"));
-		cur.n += 1;
-		fs.writeFileSync(target, JSON.stringify(cur), "utf-8");
-	});
+	await lockedRmw();
 }
 `;
 			// src 内相对 import 无 .ts 后缀（runtime tsc 无 allowImportingTsExtensions 的
@@ -189,7 +138,9 @@ register("./resolve-hook.mjs", import.meta.url);
 			}
 			expect((JSON.parse(fs.readFileSync(target, "utf-8")) as { n: number }).n).toBe(100);
 		} finally {
-			fs.rmSync(tmpDir, { recursive: true, force: true });
+			fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 		}
-	});
+		// 用例级预算须覆盖子进程 spawnSync timeout（60s，内含自旋重试预算 30s）：
+		// 文件级 20s 会在子进程合法重试期间先红——预算放宽不改变断言强度（终值精确 100）
+	}, 90_000);
 });

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

@@ -41,7 +41,7 @@ describe("acquireLock / release（async）", () => {
 		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "lock-core-test-"));
 		target = path.join(tmpDir, "target.json");
 	});
-	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 }));
 
 	it("acquire 创建 <目标>.lock 目录，release 删除", async () => {
 		const release = await acquireLock(target);
@@ -94,7 +94,7 @@ describe("acquireLock / release（async）", () => {
 		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 });
+		fs.rmSync(`${target}.lock`, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 	});
 
 	it("realpath:false：不存在的目标可锁；symlink 目标锁在 symlink 路径（不解析）", async () => {
@@ -137,7 +137,7 @@ describe("acquireLockSync", () => {
 		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 }));
+	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 }));
 
 	it("acquire/release 同构 async 版（目录创建与删除）", () => {
 		const release = acquireLockSync(target);
@@ -202,7 +202,7 @@ if (!fs.existsSync(target + ".lock")) {
 			// graceful exit 后锁目录不残留（等价 proper-lockfile signal-exit 清理语义）
 			expect(fs.existsSync(`${target}.lock`)).toBe(false);
 		} finally {
-			fs.rmSync(tmpDir, { recursive: true, force: true });
+			fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 		}
 	});
 });

package/src/file-lock.ts

@@ -1,56 +1,36 @@
 // 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 单线程只能保证进程内不交错，
 // 挡不住跨进程「后写者基于旧快照覆盖先写者」。
 //
-// 为什么是 async API 而非 runtime 侧的 withFileLockSync：扩展跑在 pi 子进程的
-// async hook 上下文（session_start 等），同步 busy-wait 会阻塞整个 event loop；
-// 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 的零依赖约束向上传导）。
+// sync busy-wait 重试编排 + 对外 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（双方路径一致才互斥）
 //   - realpath:false —— 目标文件不存在也可锁；不解析 symlink
 //   - stale 30s：持锁进程崩溃后锁可被夺取（对齐 auth 惯例）
-//   - 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；ext-config 家族的扩展侧写方（saveConfig）保持 sync 签名
 //     （调用链零波及），与 runtime 对端用同一把 lockfile 互斥
 //   - onCompromised 语义随保活 touch 一并移除（无保活则无 compromise 检测）：
 //     锁目录被外部删除时 release 静默成功（ENOENT 容忍，见 lock-core.ts removeLock）
 //
-// 契约：fn 内禁止任何 await / 再次对本文件加锁（嵌套取锁 ELOCKED → 重试耗尽 →
-// 抛错）；持锁范围应为「读文件 + 纯内存变更 + 原子写」，毫秒级（必须远小于
-// stale 30s——无保活 touch，超时持锁会被对端夺取）。
+// 契约：fn 内仅做既定读改写（读目标文件 + 纯内存变更 + 原子写），禁其他 I/O /
+// 再次对本文件加锁（嵌套取锁 ELOCKED → 重试耗尽 → 抛错），毫秒级完成（必须
+// 远小于 stale 30s——无保活 touch，超时持锁会被对端夺取）。
 
-import {
-	acquireLock,
-	acquireLockSync,
-	DEFAULT_STALE_MS,
-	type LockRelease,
-} from "./lock-core";
+import { acquireLockSync, DEFAULT_STALE_MS } from "./lock-core";
 
 export { DEFAULT_STALE_MS };
 
-/** 锁参数（默认值对齐 auth-storage.ts 范本；测试可覆盖以缩短等待）。 */
-export interface FileLockOptions {
-	/** 锁 mtime 超过该值视为持锁者已死可夺取（stale 语义）。默认 30_000ms。 */
-	staleMs?: number;
-	/** retries 重试次数（首试之外）。默认 10。 */
-	retries?: number;
-}
-
 /** sync 版锁参数（对齐 runtime withFileLockSync 默认值；测试可覆盖以缩短等待）。 */
 export interface SyncFileLockOptions {
 	/** 锁 mtime 超过该值视为持锁者已死可夺取（stale 语义）。默认 30_000ms。 */
@@ -62,17 +42,11 @@ export interface SyncFileLockOptions {
 }
 
 // 默认锁参数（sync 版导出供对照测试断言与 runtime 侧 utils/file-lock.ts 默认值相等
-// ——两侧参数漂移会破坏「同一把锁」的互斥语义；runtime 侧 test/file-lock-parity.test.ts）
-const DEFAULT_RETRIES = 10;
+// ——互斥由 lockfile 路径 + mkdir 原子协议保证，默认值对齐锚定的是两侧夺取时机
+// （stale）与失败速度（重试参数）行为一致；runtime 侧 test/file-lock-parity.test.ts）
 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;
@@ -85,62 +59,14 @@ 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，
- * 首试 + retries 次 = 默认最多 11 次 acquire），重试耗尽抛 code:"ELOCKED" 错误
- * （调用方决定降级路径）；unlock 放 finally（fn 抛错也释放；锁目录已被外部删除时
- * release 静默成功）。
- */
-export async function withFileLock<T>(
-	filePath: string,
-	fn: () => Promise<T>,
-	opts?: FileLockOptions,
-): Promise<T> {
-	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 {
-		return await fn();
-	} finally {
-		try {
-			await release();
-		} catch (releaseErr) {
-			// release 仅在非 ENOENT 的 fs 错误（权限等）时失败——不外抛（fn 结果优先），
-			// 注入 logger 时留痕供排查
-			diagnosticsLogger?.(`[file-lock] release failed (ignorable): ${stringifyErr(releaseErr)}`);
-		}
-	}
-}
-
 /**
  * 同步跨进程文件锁内执行 fn：ELOCKED busy-wait 重试，预算耗尽抛带 ELOCKED code
  * 的错误；unlock 放 finally（fn 抛错也释放）。
  *
- * 与 async 版锁同一把 lockfile（<目标文件>.lock）——sync/async API 在磁盘上
- * 是同一协议，互斥不依赖调用形态。适用场景：调用链必须保持 sync 签名
- * （如 llm-shared saveConfig，permission/rename-session 的命令回调零波及）。
+ * 与 runtime 侧 sync 实现（packages/runtime/src/utils/file-lock.ts 的
+ * withFileLockSync）同协议——同一把 lockfile（<目标文件>.lock），互斥不依赖
+ * 实现归属。适用场景：调用链必须保持 sync 签名（如 llm-shared saveConfig，
+ * permission/rename-session 的命令回调零波及）。
  * sleep 用 Atomics.wait（真 sleep 不烧 CPU，对齐 runtime 侧实现）。
  */
 export function withFileLockSync<T>(
@@ -185,17 +111,9 @@ 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

@@ -7,20 +7,9 @@
 
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
-import {
-	setFileLockLogger,
-	withFileLock,
-	withFileLockSync,
-	type FileLockOptions,
-	type SyncFileLockOptions,
-} from "./file-lock";
+import { setFileLockLogger, withFileLockSync } from "./file-lock";
 
 const logger = getLogger("file-lock");
 setFileLockLogger((msg) => logger.debug(msg));
 
-export {
-	withFileLock,
-	withFileLockSync,
-	type FileLockOptions,
-	type SyncFileLockOptions,
-};
+export { withFileLockSync };

package/src/lock-core.ts

@@ -49,8 +49,8 @@ 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 {
+/** 锁原语选项（内部参数类型：重试/常量编排属消费方，runtime 传字面量不 import 本类型）。 */
+interface LockCoreOptions {
 	/** 锁 mtime 超过该值视为持锁者已死可夺取。下限 clamp 2000ms。默认 DEFAULT_STALE_MS。 */
 	staleMs?: number;
 	/** 诊断日志注入（stale 夺取等关键分支）。core 自身零输出。 */
@@ -228,7 +228,8 @@ function acquireOnceSync(target: string, lockfilePath: string, staleMs: number,
 
 /**
  * 单次获取跨进程锁：成功返回 release（幂等）；锁被他人持有且未 stale 时抛
- * code:"ELOCKED" 错误（重试编排属消费方：包入口 async 退避 / sync busy-wait）。
+ * code:"ELOCKED" 错误（重试编排属消费方：extension 侧 sync busy-wait——
+ * src/file-lock.ts / runtime 侧 async 退避——packages/runtime/src/utils/file-lock.ts）。
  */
 export async function acquireLock(filePath: string, opts?: LockCoreOptions): Promise<LockRelease> {
 	const target = resolveTarget(filePath);

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

@@ -1,130 +0,0 @@
-// 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);
-	});
-});