@gajae-code/coding-agent 0.15.5 → 0.15.6

package/src/config/file-lock.ts

@@ -1,8 +1,10 @@
 import * as crypto from "node:crypto";
-import type { Stats } from "node:fs";
+import type { BigIntStats, Stats } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { hasFsCode, isEnoent } from "@gajae-code/utils/fs-error";
+import type { NativeDirectoryTreeResult, NativeExactUnlinkResult } from "@gajae-code/natives";
+import { renameNoReplacePathAsync } from "@gajae-code/natives";
+import { isEnoent } from "@gajae-code/utils/fs-error";
 import { nativeProcessBindings } from "@gajae-code/utils/native-process";
 
 export interface FileLockOptions {
@@ -25,10 +27,29 @@ const DEFAULT_OPTIONS: Required<
 	retryDelayMs: 100,
 };
 
+/** Release retries cover transient Windows/Dropbox handle denial without extending the lock indefinitely. */
+export const FILE_LOCK_RELEASE_RETRY_ATTEMPTS = 5;
+export const FILE_LOCK_RELEASE_RETRY_DELAY_MS = 10;
+const PROCESS_START_TIME_FORMAT = "utc-v1";
+
+type LocalLockState = {
+	owner: FileLockOwnerToken;
+	status: "held" | "release_pending" | "releasing";
+	releasePromise?: Promise<void>;
+};
+
+/**
+ * Process-local ownership is deliberately separate from PID liveness. A PID only says
+ * that a process exists; this table says which exact acquisition generation this process
+ * created, so a nested contender cannot steal a lock from a still-running holder.
+ */
+const localLockStates = new Map<string, LocalLockState>();
+
 type LockInfo = FileLockOwnerToken;
 
 export const FileLockTestHooks: {
 	afterParentMkdir?: (lockPath: string) => void | Promise<void>;
+	nativeQuarantineBindings?: () => NativeFileLockBindings;
 } = {};
 
 /**
@@ -51,7 +72,11 @@ export function processStartTime(pid: number): string | null {
 		}
 	}
 	try {
-		const result = Bun.spawnSync(["ps", "-o", "lstart=", "-p", String(pid)], { stdout: "pipe", stderr: "ignore" });
+		const result = Bun.spawnSync(["ps", "-o", "lstart=", "-p", String(pid)], {
+			stdout: "pipe",
+			stderr: "ignore",
+			env: { ...process.env, LC_ALL: "C", LANG: "C", TZ: "UTC" },
+		});
 		if (result.exitCode !== 0) return null;
 		const startTime = new TextDecoder().decode(result.stdout).trim();
 		return startTime || null;
@@ -79,35 +104,239 @@ function cachedProcessStartTime(owner: FileLockOwnerToken, cache?: Map<string, s
 
 function ownerIsAlive(owner: FileLockOwnerToken, startTimeCache?: Map<string, string | null>): boolean {
 	if (ownerLiveness(owner.pid) !== "alive") return false;
-	if (!owner.start_time) return true;
+	if (!owner.start_time || owner.start_time === "unknown") return true;
 	const currentStartTime = cachedProcessStartTime(owner, startTimeCache);
-	return currentStartTime === null || currentStartTime === owner.start_time;
+	if (currentStartTime === null || currentStartTime === owner.start_time) return true;
+	// A start-time mismatch proves PID reuse only for records that identify the
+	// canonical UTC encoding. Legacy records did not identify their timestamp format,
+	// so a locale/timezone change can make a live holder look different and must never
+	// authorize its removal.
+	return owner.start_time_format !== PROCESS_START_TIME_FORMAT;
 }
 
-function lockInfo(ownerHostId?: string): LockInfo {
+function lockInfo(ownerHostId: string | undefined, ownerToken: string): LockInfo {
 	return {
 		pid: process.pid,
 		start_time: currentProcessStartTime(),
+		start_time_format: PROCESS_START_TIME_FORMAT,
 		timestamp: Date.now(),
+		owner_token: ownerToken,
 		...(ownerHostId === undefined ? {} : { owner_host_id: ownerHostId }),
 	};
 }
 
 function writeLockInfo(lockPath: string, info: LockInfo): Promise<LockInfo> {
-	return Bun.write(`${lockPath}/info`, JSON.stringify(info)).then(() => info);
+	// Owner metadata must stay readable by its own process under a restrictive
+	// umask: release re-reads this record to authorize removal, and an info file
+	// born mode 000 under umask 0777 would wedge the lock at first release.
+	return Bun.write(`${lockPath}/info`, JSON.stringify(info), { mode: 0o600 })
+		.then(() => fs.chmod(`${lockPath}/info`, 0o600))
+		.then(() => info);
+}
+
+type LockInfoFileState = {
+	dev: bigint;
+	ino: bigint;
+	mode: bigint;
+	size: bigint;
+	mtimeNs: bigint;
+	ctimeNs: bigint;
+	nlink: bigint;
+};
+
+type LockInfoPathState = {
+	root: {
+		dev: bigint;
+		ino: bigint;
+		mode: bigint;
+	};
+	file: LockInfoFileState;
+};
+
+function lockInfoFileState(stats: BigIntStats): LockInfoFileState | null {
+	if (stats.isSymbolicLink() || !stats.isFile()) return null;
+	return {
+		dev: stats.dev,
+		ino: stats.ino,
+		mode: stats.mode,
+		size: stats.size,
+		mtimeNs: stats.mtimeNs,
+		ctimeNs: stats.ctimeNs,
+		nlink: stats.nlink,
+	};
+}
+
+function sameLockInfoFileState(left: LockInfoFileState, right: LockInfoFileState): boolean {
+	return (
+		left.dev === right.dev &&
+		left.ino === right.ino &&
+		left.mode === right.mode &&
+		left.size === right.size &&
+		left.mtimeNs === right.mtimeNs &&
+		left.ctimeNs === right.ctimeNs &&
+		left.nlink === right.nlink
+	);
+}
+
+async function lockInfoPathState(lockPath: string): Promise<LockInfoPathState | null> {
+	let root: BigIntStats;
+	try {
+		root = await fs.lstat(lockPath, { bigint: true });
+	} catch (error) {
+		if (isEnoent(error)) return null;
+		throw error;
+	}
+	if (root.isSymbolicLink() || !root.isDirectory()) return null;
+
+	let info: BigIntStats;
+	try {
+		info = await fs.lstat(path.join(lockPath, "info"), { bigint: true });
+	} catch (error) {
+		if (isEnoent(error)) return null;
+		throw error;
+	}
+	const file = lockInfoFileState(info);
+	if (!file) return null;
+	return {
+		root: { dev: root.dev, ino: root.ino, mode: root.mode },
+		file,
+	};
+}
+
+function sameLockInfoPathState(left: LockInfoPathState, right: LockInfoPathState): boolean {
+	return (
+		left.root.dev === right.root.dev &&
+		left.root.ino === right.root.ino &&
+		left.root.mode === right.root.mode &&
+		sameLockInfoFileState(left.file, right.file)
+	);
+}
+
+function fileLockDirIdentityFromPathState(state: LockInfoPathState, bytes: string): GenericFileLockDirIdentity {
+	return {
+		rootDev: String(state.root.dev),
+		rootIno: String(state.root.ino),
+		infoDev: String(state.file.dev),
+		infoIno: String(state.file.ino),
+		infoNlink: String(state.file.nlink),
+		infoSize: String(state.file.size),
+		infoMtimeNs: String(state.file.mtimeNs),
+		infoCtimeNs: String(state.file.ctimeNs),
+		infoSha256: crypto.createHash("sha256").update(bytes).digest("hex"),
+	};
+}
+
+/** Capture the exact root/info identity that a later stale verdict may authorize. */
+async function captureFileLockDirIdentity(lockDir: string): Promise<GenericFileLockDirIdentity | null> {
+	const observation = await readLockInfoObservation(lockDir);
+	return observation ? fileLockDirIdentityFromPathState(observation.state, observation.bytes) : null;
+}
+
+/** Resolve parent aliases without following the mutable lock-dir final component. */
+async function canonicalLockPathPreservingFinal(lockPath: string): Promise<string> {
+	const parent = path.dirname(lockPath);
+	try {
+		return path.join(await fs.realpath(parent), path.basename(lockPath));
+	} catch (error) {
+		if (!isEnoent(error) && !isTransientReleaseError(error)) throw error;
+		return lockPath;
+	}
+}
+
+function normalizeLockKey(lockPath: string): string {
+	return path.normalize(lockPath);
+}
+
+const LOCK_INFO_OPEN_FLAGS =
+	fs.constants.O_RDONLY |
+	(process.platform === "win32" ? 0 : (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+
+/**
+ * Read metadata from the exact regular file that was validated, never through a
+ * pathname after the descriptor is opened. The no-follow flag prevents final
+ * component symlinks on POSIX; lstat/fstat/path revalidation supplies the same
+ * rejection on Windows, where O_NOFOLLOW is unavailable.
+ */
+type LockInfoObservation = { bytes: string; state: LockInfoPathState };
+
+async function readLockInfoObservation(lockPath: string): Promise<LockInfoObservation | null> {
+	const infoPath = path.join(lockPath, "info");
+	const initial = await lockInfoPathState(lockPath);
+	if (!initial) return null;
+
+	let handle: fs.FileHandle | undefined;
+	try {
+		handle = await fs.open(infoPath, LOCK_INFO_OPEN_FLAGS);
+		const opened = lockInfoFileState(await handle.stat({ bigint: true }));
+		const beforeRead = await lockInfoPathState(lockPath);
+		if (
+			!opened ||
+			!beforeRead ||
+			!sameLockInfoFileState(initial.file, opened) ||
+			!sameLockInfoPathState(initial, beforeRead)
+		)
+			return null;
+
+		const bytes = await handle.readFile();
+		const afterRead = lockInfoFileState(await handle.stat({ bigint: true }));
+		const afterPath = await lockInfoPathState(lockPath);
+		if (
+			!afterRead ||
+			!afterPath ||
+			!sameLockInfoFileState(initial.file, afterRead) ||
+			!sameLockInfoPathState(initial, afterPath)
+		)
+			return null;
+		return { bytes: bytes.toString("utf8"), state: afterPath };
+	} catch (error) {
+		if (isEnoent(error)) return null;
+		throw error;
+	} finally {
+		await handle?.close().catch(() => undefined);
+	}
+}
+
+async function readLockInfoBytes(lockPath: string): Promise<string | null> {
+	return (await readLockInfoObservation(lockPath))?.bytes ?? null;
 }
 
 async function readLockInfo(lockPath: string): Promise<LockInfo | null> {
 	let parsed: unknown;
 	try {
-		parsed = JSON.parse(await fs.readFile(`${lockPath}/info`, "utf-8"));
+		const bytes = await readLockInfoBytes(lockPath);
+		if (bytes === null) return null;
+		parsed = JSON.parse(bytes);
 	} catch (error) {
 		if (isEnoent(error) || error instanceof SyntaxError) return null;
 		throw error;
 	}
 
 	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
-	const { pid, start_time, timestamp, owner_host_id } = parsed as Partial<LockInfo>;
+	const { pid, start_time, start_time_format, timestamp, owner_host_id, owner_token } = parsed as Partial<LockInfo>;
+	if (
+		typeof pid !== "number" ||
+		!Number.isInteger(pid) ||
+		pid <= 0 ||
+		typeof timestamp !== "number" ||
+		!Number.isFinite(timestamp) ||
+		(start_time !== undefined && (typeof start_time !== "string" || !start_time)) ||
+		(start_time_format !== undefined && (typeof start_time_format !== "string" || !start_time_format)) ||
+		(owner_host_id !== undefined && (typeof owner_host_id !== "string" || !owner_host_id)) ||
+		(owner_token !== undefined && (typeof owner_token !== "string" || !owner_token))
+	)
+		return null;
+	return { pid, start_time, start_time_format, timestamp, owner_host_id, owner_token };
+}
+
+function parseLockInfoBytes(bytes: string): LockInfo | null {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(bytes);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+	const { pid, start_time, start_time_format, timestamp, owner_host_id, owner_token } = parsed as Partial<LockInfo>;
 	if (
 		typeof pid !== "number" ||
 		!Number.isInteger(pid) ||
@@ -115,31 +344,113 @@ async function readLockInfo(lockPath: string): Promise<LockInfo | null> {
 		typeof timestamp !== "number" ||
 		!Number.isFinite(timestamp) ||
 		(start_time !== undefined && (typeof start_time !== "string" || !start_time)) ||
-		(owner_host_id !== undefined && (typeof owner_host_id !== "string" || !owner_host_id))
+		(start_time_format !== undefined && (typeof start_time_format !== "string" || !start_time_format)) ||
+		(owner_host_id !== undefined && (typeof owner_host_id !== "string" || !owner_host_id)) ||
+		(owner_token !== undefined && (typeof owner_token !== "string" || !owner_token))
 	)
 		return null;
-	return { pid, start_time, timestamp, owner_host_id };
+	return { pid, start_time, start_time_format, timestamp, owner_host_id, owner_token };
+}
+
+/** @internal */
+export interface FileLockGcObservation {
+	info: FileLockOwnerToken;
+	bytes: string;
+	identity: GenericFileLockDirIdentity;
+}
+
+/** Capture owner bytes and the identity proving those exact bytes came from this tree. */
+export async function readFileLockObservationForGc(lockDir: string): Promise<FileLockGcObservation | null> {
+	const observation = await readLockInfoObservation(lockDir);
+	if (!observation) return null;
+	const info = parseLockInfoBytes(observation.bytes);
+	if (!info) return null;
+	const identity = fileLockDirIdentityFromPathState(observation.state, observation.bytes);
+	fileLockDirIdentities.set(info, identity);
+	return { info, bytes: observation.bytes, identity };
 }
 
 /** @internal */
 export async function readFileLockInfoForGc(lockDir: string): Promise<FileLockOwnerToken | null> {
-	return await readLockInfo(lockDir);
+	return (await readFileLockObservationForGc(lockDir))?.info ?? null;
 }
 
 /** Owner identity stamped into a `<file>.lock/info` record. */
 export interface FileLockOwnerToken {
 	pid: number;
 	start_time?: string;
+	/** Encoding marker for the canonical UTC process-start identity. */
+	start_time_format?: string;
 	owner_host_id?: string;
+	/** Unique acquisition generation, present on locks created by this runtime. */
+	owner_token?: string;
 	timestamp: number;
 }
 
+/**
+ * Identity captured before a stale/liveness verdict. Kept out of the owner JSON: it is
+ * authorization evidence for the in-memory call that produced the verdict, not metadata
+ * another process may copy into a new lock generation.
+ */
+const fileLockDirIdentities = new WeakMap<object, GenericFileLockDirIdentity>();
+
 function getLockPath(filePath: string): string {
 	return `${filePath}.lock`;
 }
 
+async function ensureLockParent(directory: string): Promise<void> {
+	const missing: string[] = [];
+	let current = path.resolve(directory);
+	for (;;) {
+		try {
+			await fs.lstat(current);
+			break;
+		} catch (error) {
+			if (!isEnoent(error)) throw error;
+			missing.push(current);
+			const parent = path.dirname(current);
+			if (parent === current) throw error;
+			current = parent;
+		}
+	}
+	for (const created of missing.reverse()) {
+		try {
+			await fs.mkdir(created, { mode: 0o700 });
+			await fs.chmod(created, 0o700);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		}
+	}
+}
+
+async function localLockKey(lockPath: string): Promise<string> {
+	try {
+		return normalizeLockKey(await fs.realpath(lockPath));
+	} catch (error) {
+		if (!isEnoent(error) && !isTransientReleaseError(error)) throw error;
+	}
+	const parent = path.dirname(lockPath);
+	let canonicalParent: string;
+	try {
+		canonicalParent = await fs.realpath(parent);
+	} catch (error) {
+		if (!isEnoent(error) && !isTransientReleaseError(error)) throw error;
+		canonicalParent = path.resolve(parent);
+	}
+	const key = path.join(canonicalParent, path.basename(lockPath));
+	return normalizeLockKey(key);
+}
+
+function ownerIncarnationChanged(owner: FileLockOwnerToken, startTimeCache?: Map<string, string | null>): boolean {
+	if (owner.start_time_format !== PROCESS_START_TIME_FORMAT || !owner.start_time || owner.start_time === "unknown")
+		return false;
+	if (ownerLiveness(owner.pid) !== "alive") return false;
+	const currentStartTime = cachedProcessStartTime(owner, startTimeCache);
+	return currentStartTime !== null && currentStartTime !== owner.start_time;
+}
+
 /** Outcome of a guarded lock-dir removal attempt (`removeFileLockDirForGc`). */
-export type FileLockGcRemoval = "removed" | "owner_changed" | "missing";
+export type FileLockGcRemoval = "removed" | "owner_changed" | "missing" | "cleanup_failed";
 
 interface LockDirStatToken {
 	dev: number;
@@ -150,9 +461,38 @@ interface LockDirStatToken {
 
 type LockStaleSnapshot =
 	| { stale: false }
-	| { stale: true; owner: FileLockOwnerToken }
+	| { stale: true; owner: FileLockOwnerToken; identity: GenericFileLockDirIdentity }
 	| { stale: true; owner: null; stat: LockDirStatToken };
 
+/** Identity evidence carried by the generic stale verdict into a later removal. */
+export interface GenericFileLockDirIdentity {
+	rootDev: string;
+	rootIno: string;
+	infoDev: string;
+	infoIno: string;
+	infoNlink: string;
+	infoSize: string;
+	infoMtimeNs: string;
+	infoCtimeNs: string;
+	infoSha256: string;
+}
+
+function sameGenericFileLockDirIdentity(left: GenericFileLockDirIdentity, right: GenericFileLockDirIdentity): boolean {
+	return (
+		left.rootDev === right.rootDev &&
+		left.rootIno === right.rootIno &&
+		left.infoDev === right.infoDev &&
+		left.infoIno === right.infoIno &&
+		left.infoNlink === right.infoNlink &&
+		left.infoSize === right.infoSize &&
+		left.infoMtimeNs === right.infoMtimeNs &&
+		left.infoCtimeNs === right.infoCtimeNs &&
+		left.infoSha256 === right.infoSha256
+	);
+}
+
+export type GenericFileLockDirStaleVerdict = { stale: false } | { stale: true; identity: GenericFileLockDirIdentity };
+
 /**
  * @internal
  * Fail-closed removal of a lock dir whose owner is expected to be dead or
@@ -173,19 +513,109 @@ type LockStaleSnapshot =
 export async function removeFileLockDirForGc(
 	lockDir: string,
 	expected: FileLockOwnerToken,
+	preVerdictIdentity?: GenericFileLockDirIdentity,
 ): Promise<FileLockGcRemoval> {
-	const current = await readLockInfo(lockDir);
-	if (!current) return "missing";
+	// A generic release/quarantine call is only authorized by evidence captured
+	// before its stale verdict. Capturing the current pathname here would let a
+	// fresh successor inherit an old owner's release authority.
+	const expectedIdentity = preVerdictIdentity ?? fileLockDirIdentities.get(expected);
+	let onDiskBytes: string | null;
+	try {
+		onDiskBytes = await readLockInfoBytes(lockDir);
+	} catch (error) {
+		if (isEnoent(error)) return "missing";
+		throw error;
+	}
+	const current = onDiskBytes === null ? null : parseLockInfoBytes(onDiskBytes);
+	if (!current || onDiskBytes === null) return "missing";
+	if (!expectedIdentity) return "owner_changed";
 	if (
 		current.pid !== expected.pid ||
 		(expected.start_time !== undefined && current.start_time !== expected.start_time) ||
 		current.owner_host_id !== expected.owner_host_id ||
+		(expected.owner_token !== undefined && current.owner_token !== expected.owner_token) ||
 		current.timestamp !== expected.timestamp
 	) {
 		return "owner_changed";
 	}
-	await fs.rm(lockDir, { recursive: true, force: true });
-	return "removed";
+	// The token comparison above authorizes the content that was judged, not the
+	// pathname. When the caller carried pre-verdict root/info identity, require
+	// the post-verdict native snapshot to match that same object before removal;
+	// a clone or successor can therefore never inherit the stale authorization.
+	// The canonical native path may refuse a symlinked parent ("reparse_point");
+	// canonicalize first so the identity-bound capture sees the real directory,
+	// mirroring how localLockKey canonicalizes the lock pathname.
+	let nativeCapturePath = lockDir;
+	try {
+		nativeCapturePath = await canonicalLockPathPreservingFinal(lockDir);
+	} catch (error) {
+		if (!isEnoent(error) && !isTransientReleaseError(error)) return "cleanup_failed";
+	}
+	const captured = nativeFileLockBindings().snapshotDirectoryTree(nativeCapturePath);
+	if (captured.code === "sharing_violation") throwTransientNativeResult(captured.code);
+	if (!captured.ok || !captured.snapshot) return "owner_changed";
+	const infoEntry = captured.snapshot.entries.find(entry => entry.relativePath === "info");
+	if (!infoEntry?.sha256) return "owner_changed";
+	const judgedDigest = crypto.createHash("sha256").update(onDiskBytes).digest("hex");
+	if (infoEntry.sha256 !== judgedDigest) return "owner_changed";
+	if (
+		!captured.snapshot.rootDev ||
+		captured.snapshot.rootDev !== expectedIdentity.rootDev ||
+		captured.snapshot.rootIno !== expectedIdentity.rootIno ||
+		infoEntry.dev !== expectedIdentity.infoDev ||
+		infoEntry.ino !== expectedIdentity.infoIno ||
+		infoEntry.nlink !== expectedIdentity.infoNlink ||
+		infoEntry.size !== expectedIdentity.infoSize ||
+		infoEntry.mtimeNs !== expectedIdentity.infoMtimeNs ||
+		infoEntry.ctimeNs !== expectedIdentity.infoCtimeNs ||
+		infoEntry.sha256 !== expectedIdentity.infoSha256
+	)
+		return "owner_changed";
+	let removed: NativeExactUnlinkResult;
+	try {
+		removed = nativeFileLockBindings().exactRemoveDirectoryTree(nativeCapturePath, captured.snapshot);
+	} catch (error) {
+		// Keep the #2478 transient retry contract: sharing denials surface with
+		// their transient code so callers retry, everything else is a refusal.
+		if (isTransientReleaseError(error)) throw error;
+		return "cleanup_failed";
+	}
+	if (removed.ok) return "removed";
+	// The canonical name may already be detached: the security-critical phase is
+	// done once the verified tree is durably scrubbed and parked under the
+	// no-replace quarantine name with no successor retained. Finish that replay
+	// deterministically by deleting the retained quarantine — the same completion
+	// contract gc-runtime applies to its own exact removals. Any other outcome —
+	// including a retained successor or placeholder — leaves the judged object (or
+	// its replacement) in place and reports the removal as refused.
+	const detachedPath = removed.detachedPath;
+	const verifiedDetach =
+		detachedPath !== undefined &&
+		path.resolve(detachedPath) !== path.resolve(lockDir) &&
+		removed.retainedSuccessorPath === undefined &&
+		removed.retainedPlaceholderPath === undefined &&
+		removed.retainedUnknownPath === undefined;
+	if (verifiedDetach && detachedPath !== undefined) {
+		// The security-critical phase is done: the verified tree was detached from
+		// the canonical name and durably parked under the no-replace quarantine
+		// name with no successor retained. Finish that replay deterministically by
+		// deleting the retained quarantine — the same completion contract gc-runtime
+		// applies to its own exact removals — then report the release as done.
+		try {
+			await fs.rm(detachedPath, { recursive: true, force: true });
+		} catch {
+			// The canonical pathname is free either way; a retained quarantine is
+			// recoverable debris, not a live lock.
+		}
+		return "removed";
+	}
+	if (removed.code === "not_found") return "removed";
+	if (removed.code === "identity_mismatch") return "owner_changed";
+	const refusal: NodeJS.ErrnoException = new Error(
+		`Failed to remove file lock tree: ${removed.code ?? "unknown"}.`,
+	) as NodeJS.ErrnoException;
+	refusal.code = "EACCES";
+	throw refusal;
 }
 
 type OwnerLiveness = "alive" | "dead" | "unknown";
@@ -224,6 +654,15 @@ async function staleLockSnapshot(
 	previousOwnerHostIds: readonly string[] = [],
 	startTimeCache?: Map<string, string | null>,
 ): Promise<LockStaleSnapshot> {
+	// Capture the root and info inode BEFORE asking whether the owner is stale. A later
+	// snapshot alone would let a copied successor inherit the stale verdict's authority.
+	let judgedIdentity: GenericFileLockDirIdentity | null = null;
+	try {
+		judgedIdentity = await captureFileLockDirIdentity(lockPath);
+	} catch (error) {
+		if (isTransientReleaseError(error)) return { stale: false };
+		throw error;
+	}
 	let info: LockInfo | null;
 	try {
 		info = await readLockInfo(lockPath);
@@ -231,11 +670,21 @@ async function staleLockSnapshot(
 		// Windows can transiently deny reads of a just-created lock metadata file
 		// while another contender is publishing it. Treat that as active
 		// contention and retry rather than failing the caller or reaping by path.
-		if (hasFsCode(error, "EPERM")) return { stale: false };
+		if (isTransientReleaseError(error)) return { stale: false };
 		throw error;
 	}
 	if (!info && ownerHostId !== undefined) return { stale: false };
 	if (!info) {
+		// A present but malformed owner record is not equivalent to a lock directory
+		// caught between mkdir and metadata publication. Refuse stale fallback when the
+		// metadata path exists: an unreadable live holder must never be reclaimed by
+		// elapsed mtime alone.
+		try {
+			await fs.lstat(path.join(lockPath, "info"));
+			return { stale: false };
+		} catch (error) {
+			if (!isEnoent(error)) throw error;
+		}
 		try {
 			const stats = await fs.stat(lockPath);
 			if (Date.now() - stats.mtimeMs <= staleMs) return { stale: false };
@@ -255,12 +704,37 @@ async function staleLockSnapshot(
 		!previousOwnerHostIds.includes(info.owner_host_id ?? "")
 	)
 		return { stale: false };
+	if (ownerHostId === undefined && info.owner_host_id !== undefined) return { stale: false };
+	if (ownerIncarnationChanged(info, startTimeCache)) {
+		if (!judgedIdentity) return { stale: false };
+		let currentIdentity: GenericFileLockDirIdentity | null;
+		try {
+			currentIdentity = await captureFileLockDirIdentity(lockPath);
+		} catch (error) {
+			if (isTransientReleaseError(error)) return { stale: false };
+			throw error;
+		}
+		if (!currentIdentity || !sameGenericFileLockDirIdentity(judgedIdentity, currentIdentity)) return { stale: false };
+		fileLockDirIdentities.set(info, judgedIdentity);
+		return { stale: true, owner: info, identity: judgedIdentity };
+	}
 	// Never reap a live owner by elapsed time: a long legitimate critical section must
-	// not have its lock stolen (#652). Reclaim a dead owner immediately. Only when owner
-	// liveness is indeterminate do we fall back to the staleMs elapsed-time heuristic.
+	// not have its lock stolen (#652). Reclaim only when the OS proves the owner is dead;
+	// indeterminate liveness remains protected regardless of elapsed time.
 	if (ownerIsAlive(info, startTimeCache)) return { stale: false };
-	if (ownerLiveness(info.pid) === "dead" || Date.now() - info.timestamp > staleMs) {
-		return { stale: true, owner: info };
+	const liveness = ownerLiveness(info.pid);
+	if (liveness === "dead") {
+		if (!judgedIdentity) return { stale: false };
+		let currentIdentity: GenericFileLockDirIdentity | null;
+		try {
+			currentIdentity = await captureFileLockDirIdentity(lockPath);
+		} catch (error) {
+			if (isTransientReleaseError(error)) return { stale: false };
+			throw error;
+		}
+		if (!currentIdentity || !sameGenericFileLockDirIdentity(judgedIdentity, currentIdentity)) return { stale: false };
+		fileLockDirIdentities.set(info, judgedIdentity);
+		return { stale: true, owner: info, identity: judgedIdentity };
 	}
 	return { stale: false };
 }
@@ -268,18 +742,35 @@ async function staleLockSnapshot(
 async function removeStaleLockForAcquire(lockPath: string, snapshot: LockStaleSnapshot): Promise<boolean> {
 	if (!snapshot.stale) return false;
 	if (snapshot.owner) {
-		return (await removeFileLockDirForGc(lockPath, snapshot.owner)) === "removed";
+		return (await removeFileLockDirForGc(lockPath, snapshot.owner, snapshot.identity)) === "removed";
 	}
 
-	const currentInfo = await readLockInfo(lockPath);
+	let currentInfo: LockInfo | null;
+	try {
+		currentInfo = await readLockInfo(lockPath);
+	} catch (error) {
+		if (isTransientReleaseError(error)) return false;
+		throw error;
+	}
 	if (currentInfo) return false;
 	try {
-		const currentStats = await fs.stat(lockPath);
+		const currentStats = await fs.lstat(lockPath);
+		if (currentStats.isSymbolicLink() || !currentStats.isDirectory()) return false;
 		if (!sameStatToken(statToken(currentStats), snapshot.stat)) return false;
-		await fs.rm(lockPath, { recursive: true, force: true });
-		return true;
+		const nativeCapturePath = await canonicalLockPathPreservingFinal(lockPath);
+		const captured = nativeFileLockBindings().snapshotDirectoryTree(nativeCapturePath);
+		if (captured.code === "sharing_violation") throwTransientNativeResult(captured.code);
+		if (!captured.ok || !captured.snapshot) return false;
+		if (
+			captured.snapshot.rootDev !== String(currentStats.dev) ||
+			captured.snapshot.rootIno !== String(currentStats.ino)
+		)
+			return false;
+		const removed = nativeFileLockBindings().exactRemoveDirectoryTree(nativeCapturePath, captured.snapshot);
+		return removed.ok || removed.code === "not_found";
 	} catch (err) {
 		if (isEnoent(err)) return false;
+		if (isTransientReleaseError(err)) return false;
 		throw err;
 	}
 }
@@ -306,58 +797,265 @@ export async function genericFileLockDirIsStale(
 	staleMs: number,
 	ownerHostId?: string,
 ): Promise<boolean> {
-	return (await staleLockSnapshot(lockDir, staleMs, ownerHostId)).stale;
+	return (await genericFileLockDirStaleVerdict(lockDir, staleMs, ownerHostId)).stale;
+}
+
+/**
+ * Render a generic stale verdict together with the root and owner-file identity that
+ * verdict actually observed. A caller that removes the directory must require a later
+ * native snapshot to carry this same identity; a snapshot taken only after a clone was
+ * installed is not authority for the stale verdict.
+ */
+export async function genericFileLockDirStaleVerdict(
+	lockDir: string,
+	staleMs: number,
+	ownerHostId?: string,
+): Promise<GenericFileLockDirStaleVerdict> {
+	const verdict = await staleLockSnapshot(lockDir, staleMs, ownerHostId);
+	if (!verdict.stale || verdict.owner === null) return { stale: false };
+	return {
+		stale: true,
+		identity: verdict.identity,
+	};
 }
 
 async function tryAcquireLock(
 	lockPath: string,
 	ownerHostId?: string,
+	ownerToken = crypto.randomUUID(),
 	onAcquired?: () => void,
 ): Promise<LockInfo | null> {
-	await fs.mkdir(path.dirname(lockPath), { recursive: true });
+	await ensureLockParent(path.dirname(lockPath));
 	const afterParentMkdir = FileLockTestHooks.afterParentMkdir;
 	if (afterParentMkdir) await afterParentMkdir(lockPath);
-	if (ownerHostId === undefined) {
+	const pendingPath = `${lockPath}.pending.${process.pid}.${crypto.randomUUID()}`;
+	const owner = lockInfo(ownerHostId, ownerToken);
+	try {
+		await fs.mkdir(pendingPath, { mode: 0o700 });
+		await fs.chmod(pendingPath, 0o700);
+		await writeLockInfo(pendingPath, owner);
+		// A plain POSIX rename replaces an existing empty directory. The legacy
+		// directory lock is a real holder, so publication must use the native
+		// no-replace primitive rather than treating an empty destination as free.
+		// The native primitive also rejects symlinked/reparse parents. Resolve the
+		// already-created staging entry and its parent before publication so aliases
+		// retain the same lock identity as the ordinary path.
+		const canonicalParent = await fs.realpath(path.dirname(lockPath));
+		const published = await renameNoReplacePathAsync(
+			await fs.realpath(pendingPath),
+			path.join(canonicalParent, path.basename(lockPath)),
+		);
+		if (!published.ok) {
+			if (published.reason === "destination_exists") return null;
+			const failure = new Error(
+				`Failed to publish file lock: ${published.code ?? published.reason ?? "unknown"}.`,
+			) as NodeJS.ErrnoException;
+			if (published.code) failure.code = published.code;
+			throw failure;
+		}
+		// Published above, so an onAcquired failure must propagate instead of
+		// retrying an acquisition that already owns the lock.
+		onAcquired?.();
+		return owner;
+	} finally {
+		await fs.rm(pendingPath, { recursive: true, force: true }).catch(() => undefined);
+	}
+}
+
+function isTransientReleaseError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException).code;
+	return (
+		code === "EBUSY" || code === "EPERM" || code === "EACCES" || code === "ENOTEMPTY" || code === "sharing_violation"
+	);
+}
+
+function throwTransientNativeResult(code: string): never {
+	throw Object.assign(new Error(`Native lock operation is transiently unavailable: ${code}.`), { code });
+}
+
+type NativeFileLockBindings = {
+	snapshotDirectoryTree(lockPath: string): NativeDirectoryTreeResult;
+	exactRemoveDirectoryTree(
+		lockPath: string,
+		snapshot: NonNullable<NativeDirectoryTreeResult["snapshot"]>,
+	): NativeExactUnlinkResult;
+};
+
+let nativeFileLockBindingCache: NativeFileLockBindings | undefined;
+
+function nativeFileLockBindings(): NativeFileLockBindings {
+	if (FileLockTestHooks.nativeQuarantineBindings) return FileLockTestHooks.nativeQuarantineBindings();
+	if (nativeFileLockBindingCache) return nativeFileLockBindingCache;
+	try {
+		nativeFileLockBindingCache = require("@gajae-code/natives") as NativeFileLockBindings;
+		return nativeFileLockBindingCache;
+	} catch (error) {
+		throw Object.assign(new Error("Native identity-bound lock quarantine is unavailable."), { cause: error });
+	}
+}
+
+async function quarantineReleasedLock(
+	lockPath: string,
+	owner: FileLockOwnerToken,
+	preVerdictIdentity?: GenericFileLockDirIdentity,
+): Promise<boolean> {
+	const expectedIdentity = preVerdictIdentity ?? fileLockDirIdentities.get(owner);
+	// Quarantine is only a release fallback after earlier transient failures. It must not
+	// make a fresh post-failure snapshot authoritative for an object this release never
+	// judged; without pre-verdict evidence, refuse and let the caller surface the retry
+	// failure instead of risking a successor lock.
+	if (!expectedIdentity) return false;
+	let captured: NativeDirectoryTreeResult;
+	const nativeCapturePath = await canonicalLockPathPreservingFinal(lockPath);
+	try {
+		captured = nativeFileLockBindings().snapshotDirectoryTree(nativeCapturePath);
+		if (captured.code === "sharing_violation") throwTransientNativeResult(captured.code);
+	} catch (error) {
+		if (isTransientReleaseError(error)) return false;
+		throw error;
+	}
+	if (!captured.ok || !captured.snapshot) return false;
+	const infoEntry = captured.snapshot.entries.find(entry => entry.relativePath === "info");
+	if (!infoEntry?.sha256) return false;
+	if (
+		captured.snapshot.rootDev !== expectedIdentity.rootDev ||
+		captured.snapshot.rootIno !== expectedIdentity.rootIno ||
+		infoEntry.dev !== expectedIdentity.infoDev ||
+		infoEntry.ino !== expectedIdentity.infoIno ||
+		infoEntry.nlink !== expectedIdentity.infoNlink ||
+		infoEntry.size !== expectedIdentity.infoSize ||
+		infoEntry.mtimeNs !== expectedIdentity.infoMtimeNs ||
+		infoEntry.ctimeNs !== expectedIdentity.infoCtimeNs ||
+		infoEntry.sha256 !== expectedIdentity.infoSha256
+	)
+		return false;
+	// Bind the owner generation to the snapshot before exact removal. A successor
+	// installed after this snapshot is rejected by the native identity check instead of
+	// being moved into quarantine by a pathname-only rename.
+	const expectedDigest = crypto.createHash("sha256").update(JSON.stringify(owner)).digest("hex");
+	if (infoEntry.sha256 !== expectedDigest) return false;
+	let removed: NativeExactUnlinkResult;
+	try {
+		removed = nativeFileLockBindings().exactRemoveDirectoryTree(nativeCapturePath, captured.snapshot);
+	} catch (error) {
+		if (isTransientReleaseError(error)) return false;
+		throw error;
+	}
+	if (removed.ok || removed.code === "not_found") return true;
+	if (
+		removed.detachedPath !== undefined &&
+		path.resolve(removed.detachedPath) !== path.resolve(lockPath) &&
+		removed.retainedSuccessorPath === undefined &&
+		removed.retainedPlaceholderPath === undefined &&
+		removed.retainedUnknownPath === undefined
+	) {
 		try {
-			await fs.mkdir(lockPath);
-			onAcquired?.();
-			return await writeLockInfo(lockPath, lockInfo());
+			await fs.lstat(nativeCapturePath);
+			return false;
 		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code === "EEXIST") return null;
+			if (isEnoent(error)) {
+				nativeFileLockBindings().exactRemoveDirectoryTree(removed.detachedPath, captured.snapshot);
+				return true;
+			}
 			throw error;
 		}
 	}
+	return false;
+}
 
-	const pendingPath = `${lockPath}.pending.${process.pid}.${crypto.randomUUID()}`;
-	const owner = lockInfo(ownerHostId);
+async function releaseOwnedLock(lockPath: string, owner: FileLockOwnerToken): Promise<void> {
+	let preVerdictIdentity: GenericFileLockDirIdentity | undefined;
 	try {
-		await fs.mkdir(pendingPath);
-		await writeLockInfo(pendingPath, owner);
+		preVerdictIdentity = (await captureFileLockDirIdentity(lockPath)) ?? undefined;
+		if (preVerdictIdentity) fileLockDirIdentities.set(owner, preVerdictIdentity);
+	} catch (error) {
+		if (!isTransientReleaseError(error)) throw error;
+	}
+	let lastTransientError: unknown;
+	for (let attempt = 0; attempt < FILE_LOCK_RELEASE_RETRY_ATTEMPTS; attempt++) {
 		try {
-			await fs.rename(pendingPath, lockPath);
-			onAcquired?.();
-			return owner;
-		} catch (error) {
-			const code = (error as NodeJS.ErrnoException).code;
-			if (code === "EEXIST" || code === "ENOTEMPTY") return null;
-			if (code === "EPERM") {
-				try {
-					await fs.stat(lockPath);
-					return null;
-				} catch (statError) {
-					if (!isEnoent(statError)) throw statError;
-				}
+			const outcome = await removeFileLockDirForGc(lockPath, owner, preVerdictIdentity);
+			if (outcome === "removed" || outcome === "missing") {
+				if (outcome === "missing") throw new Error("Failed to release file lock: missing.");
+				return;
 			}
-			throw error;
+			throw new Error(`Failed to release file lock: ${outcome}.`);
+		} catch (error) {
+			if (!isTransientReleaseError(error)) throw error;
+			lastTransientError = error;
+			if (attempt + 1 < FILE_LOCK_RELEASE_RETRY_ATTEMPTS) await Bun.sleep(FILE_LOCK_RELEASE_RETRY_DELAY_MS);
 		}
+	}
+	if (await quarantineReleasedLock(lockPath, owner, preVerdictIdentity)) return;
+	throw lastTransientError ?? new Error("Failed to release file lock: transient removal failure.");
+}
+
+async function retryPendingLocalRelease(lockPath: string, knownKey?: string): Promise<void> {
+	const key = knownKey ?? (await localLockKey(lockPath));
+	const state = localLockStates.get(key);
+	if (!state || state.status === "held") return;
+	if (state.releasePromise) {
+		await state.releasePromise.catch(() => undefined);
+		return;
+	}
+	state.status = "releasing";
+	const releasePromise = releaseOwnedLock(lockPath, state.owner);
+	state.releasePromise = releasePromise;
+	try {
+		await releasePromise;
+		if (localLockStates.get(key) === state) localLockStates.delete(key);
+	} catch (error) {
+		state.status = "release_pending";
+		throw error;
 	} finally {
-		await fs.rm(pendingPath, { recursive: true, force: true }).catch(() => undefined);
+		if (state.releasePromise === releasePromise) state.releasePromise = undefined;
+	}
+}
+
+async function pendingLocalReleaseKey(lockPath: string, localKey: string): Promise<string | undefined> {
+	const direct = localLockStates.get(localKey);
+	if (direct) return direct.status === "held" ? undefined : localKey;
+	let info: LockInfo | null;
+	try {
+		info = await readLockInfo(lockPath);
+	} catch (error) {
+		if (isTransientReleaseError(error)) return undefined;
+		throw error;
+	}
+	const ownerToken = info?.owner_token;
+	if (!ownerToken) return undefined;
+	for (const [key, state] of localLockStates) {
+		if (key !== localKey && state.status !== "held" && state.owner.owner_token === ownerToken) return key;
 	}
+	return undefined;
 }
 
-async function releaseLock(lockPath: string, owner: FileLockOwnerToken): Promise<void> {
-	const outcome = await removeFileLockDirForGc(lockPath, owner);
-	if (outcome !== "removed") throw new Error(`Failed to release file lock: ${outcome}.`);
+async function releaseLock(lockPath: string, owner: FileLockOwnerToken, knownKey?: string): Promise<void> {
+	const key = knownKey ?? (await localLockKey(lockPath));
+	const state = localLockStates.get(key);
+	if (!state || state.owner.owner_token !== owner.owner_token) {
+		throw new Error("Failed to release file lock: local owner generation is unknown.");
+	}
+	if (state.status === "release_pending") {
+		await retryPendingLocalRelease(lockPath, key);
+		return;
+	}
+	if (state.releasePromise) {
+		await state.releasePromise;
+		return;
+	}
+	state.status = "releasing";
+	const releasePromise = releaseOwnedLock(lockPath, owner);
+	state.releasePromise = releasePromise;
+	try {
+		await releasePromise;
+		if (localLockStates.get(key) === state) localLockStates.delete(key);
+	} catch (error) {
+		state.status = "release_pending";
+		throw error;
+	} finally {
+		if (state.releasePromise === releasePromise) state.releasePromise = undefined;
+	}
 }
 /**
  * Bounded, actionable description of who holds `lockPath` at exhaustion time.
@@ -409,12 +1107,30 @@ async function acquireLock(filePath: string, options: FileLockOptions = {}): Pro
 	if (options.previousOwnerHostIds?.some(hostId => !hostId))
 		throw new Error("previousOwnerHostIds must contain only non-empty identities");
 	const opts = { ...DEFAULT_OPTIONS, ...options };
+	if (opts.signal?.aborted) throw opts.signal.reason ?? new Error("File lock acquisition aborted");
 	const lockPath = getLockPath(filePath);
+	await ensureLockParent(path.dirname(lockPath));
+	const ownerToken = crypto.randomUUID();
 	const contentionStartTimes = new Map<string, string | null>();
 	for (let attempt = 0; attempt < opts.retries; attempt++) {
 		if (opts.signal?.aborted) throw opts.signal.reason ?? new Error("File lock acquisition aborted");
-		const owner = await tryAcquireLock(lockPath, opts.ownerHostId, opts.onAcquired);
-		if (owner) return () => releaseLock(lockPath, owner);
+		const localKey = await localLockKey(lockPath);
+		const owner = await tryAcquireLock(lockPath, opts.ownerHostId, ownerToken, opts.onAcquired);
+		if (owner) {
+			localLockStates.set(localKey, { owner, status: "held" });
+			return () => releaseLock(lockPath, owner, localKey);
+		}
+		const pendingKey = await pendingLocalReleaseKey(lockPath, localKey);
+		const localState = localLockStates.get(pendingKey ?? localKey);
+		if (pendingKey !== undefined && localState?.status !== "held" && localState?.owner.owner_token !== undefined) {
+			try {
+				await retryPendingLocalRelease(lockPath, pendingKey);
+				continue;
+			} catch {
+				// Keep contending below. A failed local retry is not authority to steal a
+				// lock; the owner generation remains fenced until release succeeds.
+			}
+		}
 		const stale = await staleLockSnapshot(
 			lockPath,
 			opts.staleMs,