@gajae-code/coding-agent 0.16.3 → 0.16.6

package/src/config/file-lock.ts

@@ -2,8 +2,20 @@ import * as crypto from "node:crypto";
 import type { BigIntStats } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type { NativeDirectoryTreeResult, NativeExactUnlinkResult, NativeNoReplaceResult } from "@gajae-code/natives";
-import { renameDirectoryNoReplacePathAsync, renameNoReplacePathAsync } from "@gajae-code/natives";
+import type {
+	NativeDirectoryTreeResult,
+	NativeDirectoryTreeSnapshot,
+	NativeExactUnlinkResult,
+	NativeNoReplaceResult,
+	RecoveryFsPublishResult,
+} from "@gajae-code/natives";
+import {
+	openRecoveryFsRoot,
+	renameDirectoryNoReplacePathAsync,
+	renameNoReplacePathAsync,
+	snapshotDirectoryTree,
+} from "@gajae-code/natives";
+import { logger } from "@gajae-code/utils";
 import { isEnoent } from "@gajae-code/utils/fs-error";
 import { nativeProcessBindings } from "@gajae-code/utils/native-process";
 
@@ -19,6 +31,23 @@ export interface FileLockOptions {
 	previousOwnerHostIds?: readonly string[];
 }
 
+export class FileLockAcquireError extends Error {
+	readonly code = "acquire_timeout";
+
+	constructor(
+		readonly filePath: string,
+		readonly lockPath: string,
+		readonly attempts: number,
+		readonly holder: string,
+	) {
+		super(
+			`Failed to acquire lock for ${filePath} after ${attempts} attempts: ${holder} (${lockPath}); ` +
+				`a live owner is never displaced — if this is an SDK broker (gjc sdk status), it must finish or be stopped before retrying`,
+		);
+		this.name = "FileLockAcquireError";
+	}
+}
+
 const DEFAULT_OPTIONS: Required<
 	Omit<FileLockOptions, "ownerHostId" | "previousOwnerHostIds" | "signal" | "onAcquired">
 > = {
@@ -27,9 +56,9 @@ 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;
+/** Release retries cover transient handle denial and a competing exact-removal quarantine cleanup. */
+export const FILE_LOCK_RELEASE_RETRY_ATTEMPTS = 20;
+export const FILE_LOCK_RELEASE_RETRY_DELAY_MS = 25;
 const PROCESS_START_TIME_FORMAT = "utc-v1";
 
 type LocalLockState = {
@@ -90,12 +119,27 @@ export function processStartTime(pid: number): string | null {
 }
 
 let ownProcessStartTime: string | undefined;
+let ownProcessIncarnation: string | null | undefined;
 
 function currentProcessStartTime(): string {
 	if (ownProcessStartTime === undefined) ownProcessStartTime = processStartTime(process.pid) ?? "unknown";
 	return ownProcessStartTime;
 }
 
+function processIncarnation(pid: number): string | null {
+	try {
+		const incarnation = nativeProcessBindings().Process.fromPid(pid)?.incarnation;
+		return typeof incarnation === "string" && incarnation.length > 0 ? incarnation : null;
+	} catch {
+		return null;
+	}
+}
+
+function currentProcessIncarnation(): string | null {
+	if (ownProcessIncarnation === undefined) ownProcessIncarnation = processIncarnation(process.pid);
+	return ownProcessIncarnation;
+}
+
 function cachedProcessStartTime(owner: FileLockOwnerToken, cache?: Map<string, string | null>): string | null {
 	if (!cache) return processStartTime(owner.pid);
 	const key = `${owner.pid}:${owner.start_time ?? ""}`;
@@ -108,6 +152,10 @@ 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.process_incarnation) {
+		const currentIncarnation = processIncarnation(owner.pid);
+		return currentIncarnation === null || currentIncarnation === owner.process_incarnation;
+	}
 	if (!owner.start_time || owner.start_time === "unknown") return true;
 	const currentStartTime = cachedProcessStartTime(owner, startTimeCache);
 	if (currentStartTime === null || currentStartTime === owner.start_time) return true;
@@ -119,10 +167,12 @@ function ownerIsAlive(owner: FileLockOwnerToken, startTimeCache?: Map<string, st
 }
 
 function lockInfo(ownerHostId: string | undefined, ownerToken: string): LockInfo {
+	const incarnation = currentProcessIncarnation();
 	return {
 		pid: process.pid,
 		start_time: currentProcessStartTime(),
 		start_time_format: PROCESS_START_TIME_FORMAT,
+		...(incarnation === null ? {} : { process_incarnation: incarnation }),
 		timestamp: Date.now(),
 		owner_token: ownerToken,
 		...(ownerHostId === undefined ? {} : { owner_host_id: ownerHostId }),
@@ -316,7 +366,8 @@ async function readLockInfo(lockPath: string): Promise<LockInfo | 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>;
+	const { pid, start_time, start_time_format, process_incarnation, timestamp, owner_host_id, owner_token } =
+		parsed as Partial<LockInfo>;
 	if (
 		typeof pid !== "number" ||
 		!Number.isInteger(pid) ||
@@ -325,11 +376,12 @@ async function readLockInfo(lockPath: string): Promise<LockInfo | null> {
 		!Number.isFinite(timestamp) ||
 		(start_time !== undefined && (typeof start_time !== "string" || !start_time)) ||
 		(start_time_format !== undefined && (typeof start_time_format !== "string" || !start_time_format)) ||
+		(process_incarnation !== undefined && (typeof process_incarnation !== "string" || !process_incarnation)) ||
 		(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 };
+	return { pid, start_time, start_time_format, process_incarnation, timestamp, owner_host_id, owner_token };
 }
 
 function parseLockInfoBytes(bytes: string): LockInfo | null {
@@ -340,7 +392,8 @@ function parseLockInfoBytes(bytes: string): LockInfo | null {
 		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>;
+	const { pid, start_time, start_time_format, process_incarnation, timestamp, owner_host_id, owner_token } =
+		parsed as Partial<LockInfo>;
 	if (
 		typeof pid !== "number" ||
 		!Number.isInteger(pid) ||
@@ -349,11 +402,12 @@ function parseLockInfoBytes(bytes: string): LockInfo | null {
 		!Number.isFinite(timestamp) ||
 		(start_time !== undefined && (typeof start_time !== "string" || !start_time)) ||
 		(start_time_format !== undefined && (typeof start_time_format !== "string" || !start_time_format)) ||
+		(process_incarnation !== undefined && (typeof process_incarnation !== "string" || !process_incarnation)) ||
 		(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 };
+	return { pid, start_time, start_time_format, process_incarnation, timestamp, owner_host_id, owner_token };
 }
 
 /** @internal */
@@ -382,6 +436,8 @@ export async function readFileLockInfoForGc(lockDir: string): Promise<FileLockOw
 /** Owner identity stamped into a `<file>.lock/info` record. */
 export interface FileLockOwnerToken {
 	pid: number;
+	/** Kernel-derived identity for the exact process generation owning `pid`. */
+	process_incarnation?: string;
 	start_time?: string;
 	/** Encoding marker for the canonical UTC process-start identity. */
 	start_time_format?: string;
@@ -397,11 +453,114 @@ export interface FileLockOwnerToken {
  * another process may copy into a new lock generation.
  */
 const fileLockDirIdentities = new WeakMap<object, GenericFileLockDirIdentity>();
+const pendingDetachedLockCleanups = new WeakMap<object, { path: string; rootDev: string; rootIno: string }>();
+
+async function finishDetachedLockCleanup(owner: FileLockOwnerToken): Promise<boolean> {
+	const pending = pendingDetachedLockCleanups.get(owner);
+	if (!pending) return false;
+	try {
+		const current = await fs.lstat(pending.path, { bigint: true });
+		if (
+			!current.isDirectory() ||
+			current.isSymbolicLink() ||
+			current.dev.toString() !== pending.rootDev ||
+			current.ino.toString() !== pending.rootIno
+		) {
+			throw new Error("Detached file lock cleanup identity changed; refusing removal");
+		}
+		await fs.rm(pending.path, { recursive: true, force: true });
+	} catch (error) {
+		if (!isEnoent(error)) throw error;
+	}
+	pendingDetachedLockCleanups.delete(owner);
+	return true;
+}
 
 function getLockPath(filePath: string): string {
 	return `${filePath}.lock`;
 }
 
+function fileLockRemovalTransitionPath(lockPath: string): string {
+	return `${lockPath}.removing`;
+}
+
+async function fileLockRemovalTransitionExists(lockPath: string): Promise<boolean> {
+	try {
+		await fs.lstat(fileLockRemovalTransitionPath(lockPath));
+		return true;
+	} catch (error) {
+		if (isEnoent(error)) return false;
+		throw error;
+	}
+}
+
+function sameFileLockTreeAfterPublication(
+	staged: NativeDirectoryTreeSnapshot,
+	published: NativeDirectoryTreeSnapshot,
+): boolean {
+	return (
+		staged.rootDev === published.rootDev &&
+		staged.rootIno === published.rootIno &&
+		staged.entries.length === published.entries.length &&
+		staged.entries.every((entry, index) => {
+			const current = published.entries[index];
+			return (
+				current !== undefined &&
+				entry.relativePath === current.relativePath &&
+				entry.kind === current.kind &&
+				entry.dev === current.dev &&
+				entry.ino === current.ino &&
+				entry.nlink === current.nlink &&
+				entry.size === current.size &&
+				entry.mtimeNs === current.mtimeNs &&
+				(entry.relativePath === "" || entry.ctimeNs === current.ctimeNs) &&
+				entry.sha256 === current.sha256
+			);
+		})
+	);
+}
+
+function rollbackPublishedFileLock(
+	canonicalParent: string,
+	lockPath: string,
+	pendingPath: string,
+	stagedSnapshot: NativeDirectoryTreeSnapshot,
+): void {
+	const authority = openRecoveryFsRoot(canonicalParent);
+	let rollback: RecoveryFsPublishResult | undefined;
+	const errors: unknown[] = [];
+	try {
+		rollback = authority.renameManagedTreeNoReplace(
+			path.basename(lockPath),
+			path.basename(pendingPath),
+			stagedSnapshot,
+		);
+	} catch (error) {
+		errors.push(error);
+	}
+	if (rollback && !rollback.ok) {
+		const failure = new Error(
+			`Failed to roll back file lock published during removal transition: ${rollback.code ?? "unknown"}.`,
+		) as NodeJS.ErrnoException;
+		if (rollback.code) failure.code = rollback.code;
+		errors.push(failure);
+	}
+	try {
+		const closed = authority.close();
+		if (!closed.ok && closed.code !== "closed") {
+			const failure = new Error(
+				`Failed to close file lock rollback authority: ${closed.code ?? "unknown"}.`,
+			) as NodeJS.ErrnoException;
+			if (closed.code) failure.code = closed.code;
+			errors.push(failure);
+		}
+	} catch (error) {
+		errors.push(error);
+	}
+	if (errors.length > 0) throw new AggregateError(errors, "File lock rollback authority failed");
+	if (!rollback) throw new Error("File lock rollback returned no result");
+}
+
 async function ensureLockParent(directory: string): Promise<void> {
 	const missing: string[] = [];
 	let current = path.resolve(directory);
@@ -558,6 +717,11 @@ async function localLockKey(lockPath: string): Promise<string> {
 }
 
 function ownerIncarnationChanged(owner: FileLockOwnerToken, startTimeCache?: Map<string, string | null>): boolean {
+	if (owner.process_incarnation) {
+		if (ownerLiveness(owner.pid) !== "alive") return false;
+		const currentIncarnation = processIncarnation(owner.pid);
+		return currentIncarnation !== null && currentIncarnation !== owner.process_incarnation;
+	}
 	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;
@@ -639,6 +803,7 @@ export async function removeFileLockDirForGc(
 	if (!expectedIdentity) return "owner_changed";
 	if (
 		current.pid !== expected.pid ||
+		(expected.process_incarnation !== undefined && current.process_incarnation !== expected.process_incarnation) ||
 		(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) ||
@@ -704,17 +869,12 @@ export async function removeFileLockDirForGc(
 		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.
-		}
+		pendingDetachedLockCleanups.set(expected, {
+			path: detachedPath,
+			rootDev: captured.snapshot.rootDev,
+			rootIno: captured.snapshot.rootIno,
+		});
+		await finishDetachedLockCleanup(expected);
 		return "removed";
 	}
 	if (removed.code === "not_found") return "removed";
@@ -822,7 +982,15 @@ async function staleLockSnapshot(
 
 async function removeStaleLockForAcquire(lockPath: string, snapshot: LockStaleSnapshot): Promise<boolean> {
 	if (!snapshot.stale) return false;
-	return (await removeFileLockDirForGc(lockPath, snapshot.owner, snapshot.identity)) === "removed";
+	try {
+		return (await removeFileLockDirForGc(lockPath, snapshot.owner, snapshot.identity)) === "removed";
+	} catch {
+		// Exact removal refusal is not authority to fail or mutate by another path.
+		// Keep contending: a concurrent reclaimer may already be completing the same
+		// dead generation, while a persistent refusal remains fail-closed until the
+		// normal retry budget reports the still-held lock.
+		return false;
+	}
 }
 
 /**
@@ -880,8 +1048,10 @@ async function tryAcquireLock(
 	if (afterParentMkdir) await afterParentMkdir(lockPath);
 	const pendingPath = `${lockPath}.pending.${process.pid}.${crypto.randomUUID()}`;
 	const owner = lockInfo(ownerHostId, ownerToken);
+	let removePending = false;
 	try {
 		await fs.mkdir(pendingPath, { mode: 0o700 });
+		removePending = true;
 		await fs.chmod(pendingPath, 0o700);
 		await writeLockInfo(pendingPath, owner);
 		// A plain POSIX rename replaces an existing empty directory. The legacy
@@ -896,6 +1066,22 @@ async function tryAcquireLock(
 		// component would follow an attacker-replaced symlink before native no-follow
 		// validation gets a chance to reject it.
 		const canonicalPendingPath = path.join(canonicalParent, path.basename(pendingPath));
+		let stagedSnapshot: NativeDirectoryTreeSnapshot | undefined;
+		if (process.platform === "linux") {
+			// Linux exact tree removal owns this deterministic sibling from detach
+			// until cleanup. The outer acquisition loop supplies the existing bounded
+			// contention wait while the predecessor retains that namespace.
+			if (await fileLockRemovalTransitionExists(destinationPath)) return null;
+			const staged = snapshotDirectoryTree(canonicalPendingPath);
+			if (!staged.ok || !staged.snapshot) {
+				const failure = new Error(
+					`Failed to snapshot staged file lock: ${staged.code ?? "unknown"}.`,
+				) as NodeJS.ErrnoException;
+				if (staged.code) failure.code = staged.code;
+				throw failure;
+			}
+			stagedSnapshot = staged.snapshot;
+		}
 		const publication = FileLockTestHooks.nativePublicationBindings?.() ?? {
 			renameNoReplacePathAsync,
 			renameDirectoryNoReplacePathAsync,
@@ -924,12 +1110,34 @@ async function tryAcquireLock(
 			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.
+		removePending = false;
+		// The transition can appear after the pre-publication check only when the
+		// predecessor atomically detaches its lock before this no-replace publish.
+		// Roll this exact staged tree back to its UUID path before reporting
+		// contention; never delete or rename the predecessor's `.removing` tree.
+		if (stagedSnapshot && (await fileLockRemovalTransitionExists(destinationPath))) {
+			const publishedSnapshot = snapshotDirectoryTree(destinationPath);
+			if (
+				!publishedSnapshot.ok ||
+				!publishedSnapshot.snapshot ||
+				!sameFileLockTreeAfterPublication(stagedSnapshot, publishedSnapshot.snapshot)
+			) {
+				const failure = new Error(
+					`Failed to verify published file lock before transition rollback: ${publishedSnapshot.code ?? "identity_mismatch"}.`,
+				) as NodeJS.ErrnoException;
+				if (publishedSnapshot.code) failure.code = publishedSnapshot.code;
+				throw failure;
+			}
+			rollbackPublishedFileLock(canonicalParent, destinationPath, canonicalPendingPath, publishedSnapshot.snapshot);
+			removePending = true;
+			return null;
+		}
+		// Published and transition-free 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);
+		if (removePending) await fs.rm(pendingPath, { recursive: true, force: true }).catch(() => undefined);
 	}
 }
 
@@ -1025,7 +1233,12 @@ async function quarantineReleasedLock(
 			return false;
 		} catch (error) {
 			if (isEnoent(error)) {
-				nativeFileLockBindings().exactRemoveDirectoryTree(removed.detachedPath, captured.snapshot);
+				pendingDetachedLockCleanups.set(owner, {
+					path: removed.detachedPath,
+					rootDev: captured.snapshot.rootDev,
+					rootIno: captured.snapshot.rootIno,
+				});
+				await finishDetachedLockCleanup(owner);
 				return true;
 			}
 			throw error;
@@ -1035,6 +1248,7 @@ async function quarantineReleasedLock(
 }
 
 async function releaseOwnedLock(lockPath: string, owner: FileLockOwnerToken): Promise<void> {
+	if (await finishDetachedLockCleanup(owner)) return;
 	let preVerdictIdentity: GenericFileLockDirIdentity | undefined;
 	try {
 		preVerdictIdentity = (await captureFileLockDirIdentity(lockPath)) ?? undefined;
@@ -1045,6 +1259,7 @@ async function releaseOwnedLock(lockPath: string, owner: FileLockOwnerToken): Pr
 	let lastTransientError: unknown;
 	for (let attempt = 0; attempt < FILE_LOCK_RELEASE_RETRY_ATTEMPTS; attempt++) {
 		try {
+			if (await finishDetachedLockCleanup(owner)) return;
 			const outcome = await removeFileLockDirForGc(lockPath, owner, preVerdictIdentity);
 			if (outcome === "removed" || outcome === "missing") {
 				if (outcome === "missing") throw new Error("Failed to release file lock: missing.");
@@ -1134,6 +1349,9 @@ async function releaseLock(lockPath: string, owner: FileLockOwnerToken, knownKey
  */
 async function lockHolderDescription(lockPath: string): Promise<string> {
 	try {
+		if (process.platform === "linux" && (await fileLockRemovalTransitionExists(lockPath))) {
+			return "blocked by retained removal transition; retry the owning process cleanup or inspect the exact orphan manually; unproven transition ownership is never removed";
+		}
 		const info = await readLockInfo(lockPath);
 		if (info) {
 			// A lock record carrying a foreign owner_host_id belongs to another
@@ -1173,7 +1391,7 @@ async function lockHolderDescription(lockPath: string): Promise<string> {
 	}
 }
 
-async function acquireLock(filePath: string, options: FileLockOptions = {}): Promise<() => Promise<void>> {
+export async function acquireFileLock(filePath: string, options: FileLockOptions = {}): Promise<() => Promise<void>> {
 	const requestedFilePath: unknown = filePath;
 	if (typeof requestedFilePath !== "string" || requestedFilePath.length === 0 || !path.isAbsolute(requestedFilePath))
 		throw new TypeError("filePath must be a non-empty absolute path");
@@ -1185,11 +1403,21 @@ async function acquireLock(filePath: string, options: FileLockOptions = {}): Pro
 	if (opts.signal?.aborted) throw opts.signal.reason ?? new Error("File lock acquisition aborted");
 	const lockPath = getLockPath(filePath);
 	await ensureLockParent(path.dirname(lockPath));
+	try {
+		await reapOrphanedLockStagingDirs(lockPath);
+	} catch (error) {
+		logger.debug("Failed to reap orphaned file-lock staging directories", { lockPath, error: String(error) });
+	}
 	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 localKey = await localLockKey(lockPath);
+		const priorRelease = localLockStates.get(localKey);
+		if (priorRelease && priorRelease.status !== "held" && pendingDetachedLockCleanups.has(priorRelease.owner)) {
+			await retryPendingLocalRelease(lockPath, localKey);
+			continue;
+		}
 		const owner = await tryAcquireLock(lockPath, opts.ownerHostId, ownerToken, opts.onAcquired);
 		if (owner) {
 			localLockStates.set(localKey, { owner, status: "held" });
@@ -1228,10 +1456,7 @@ async function acquireLock(filePath: string, options: FileLockOptions = {}): Pro
 			opts.signal.removeEventListener("abort", onAbort);
 		}
 	}
-	throw new Error(
-		`Failed to acquire lock for ${filePath} after ${opts.retries} attempts: ${await lockHolderDescription(lockPath)} (${lockPath}); ` +
-			`a live owner is never displaced — if this is an SDK broker (gjc sdk status), it must finish or be stopped before retrying`,
-	);
+	throw new FileLockAcquireError(filePath, lockPath, opts.retries, await lockHolderDescription(lockPath));
 }
 
 /**
@@ -1245,7 +1470,7 @@ export async function withFileLock<T>(
 	fn: () => Promise<T>,
 	options: FileLockOptions = {},
 ): Promise<T> {
-	const release = await acquireLock(filePath, options);
+	const release = await acquireFileLock(filePath, options);
 	let result: T;
 	try {
 		result = await fn();
@@ -1260,3 +1485,126 @@ export async function withFileLock<T>(
 	await release();
 	return result;
 }
+
+/** Strictly recognize the staging names emitted by tryAcquireLock. */
+export function fileLockStagingOwnerPid(name: string): number | null {
+	const match = /^.+\.lock\.pending\.([1-9]\d*)\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.exec(
+		name,
+	);
+	if (!match) return null;
+	const pid = Number(match[1]);
+	return Number.isSafeInteger(pid) ? pid : null;
+}
+
+export interface FileLockStagingResult {
+	path: string;
+	pid?: number;
+	status: OwnerLiveness;
+	removed: boolean;
+	reason: string;
+}
+
+/** Observe identity before probing; neither a replacement nor a symlink inherits the verdict. */
+export async function inspectFileLockStagingDir(
+	stagingPath: string,
+	probe: (pid: number) => OwnerLiveness = ownerLiveness,
+	remove = false,
+): Promise<FileLockStagingResult> {
+	const kept: FileLockStagingResult = {
+		path: stagingPath,
+		status: "unknown",
+		removed: false,
+		reason: "unverified_staging_directory",
+	};
+	const namePid = fileLockStagingOwnerPid(path.basename(stagingPath));
+	if (namePid === null) return kept;
+	const canonical = await canonicalLockPathPreservingFinal(stagingPath);
+	const root = await fs.lstat(canonical, { bigint: true });
+	if (!root.isDirectory() || root.isSymbolicLink()) return kept;
+	const captured = nativeFileLockBindings().snapshotDirectoryTree(canonical);
+	if (
+		!captured.ok ||
+		!captured.snapshot ||
+		captured.snapshot.rootDev !== root.dev.toString() ||
+		captured.snapshot.rootIno !== root.ino.toString()
+	)
+		return kept;
+	const observation = await readFileLockObservationForGc(canonical);
+	let pid: number;
+	if (observation) {
+		if (
+			observation.identity.rootDev !== captured.snapshot.rootDev ||
+			observation.identity.rootIno !== captured.snapshot.rootIno
+		)
+			return kept;
+		pid = observation.info.pid;
+		if (observation.info.owner_host_id !== undefined) return { ...kept, pid, reason: "host_qualified_staging_owner" };
+	} else {
+		// Missing info is the only case where the filename is ownership evidence.
+		try {
+			await fs.lstat(path.join(canonical, "info"));
+			return kept;
+		} catch (error) {
+			if (!isEnoent(error)) throw error;
+		}
+		if (captured.snapshot.entries.some(entry => entry.relativePath !== "")) return kept;
+		pid = namePid;
+	}
+	if (pid === process.pid || namePid === process.pid) {
+		return { ...kept, pid, status: "alive", reason: "in_process_staging_owner" };
+	}
+	let status = probe(pid);
+	if (status === "alive" && observation && ownerIncarnationChanged(observation.info)) status = "dead";
+	const result: FileLockStagingResult = {
+		path: stagingPath,
+		pid,
+		status,
+		removed: false,
+		reason: `file_lock_staging_owner_${status}`,
+	};
+	if (status !== "dead" || !remove) return result;
+	if (observation) {
+		const removal = await removeFileLockDirForGc(canonical, observation.info, observation.identity);
+		return { ...result, removed: removal === "removed", reason: removal };
+	}
+	const removal = nativeFileLockBindings().exactRemoveDirectoryTree(canonical, captured.snapshot);
+	if (
+		removal.detachedPath &&
+		path.resolve(removal.detachedPath) !== path.resolve(canonical) &&
+		!removal.retainedSuccessorPath &&
+		!removal.retainedPlaceholderPath &&
+		!removal.retainedUnknownPath
+	) {
+		const detached = await fs.lstat(removal.detachedPath, { bigint: true });
+		if (
+			detached.isDirectory() &&
+			!detached.isSymbolicLink() &&
+			detached.dev.toString() === captured.snapshot.rootDev &&
+			detached.ino.toString() === captured.snapshot.rootIno
+		) {
+			await fs.rmdir(removal.detachedPath);
+			return { ...result, removed: true, reason: "removed" };
+		}
+	}
+	return { ...result, removed: removal.ok, reason: removal.ok ? "removed" : (removal.code ?? "cleanup_failed") };
+}
+
+/** Bounded opportunistic cleanup; the acquisition caller treats failures as diagnostic only. */
+export async function reapOrphanedLockStagingDirs(lockPath: string): Promise<{
+	removed: string[];
+	retained: FileLockStagingResult[];
+}> {
+	const summary: { removed: string[]; retained: FileLockStagingResult[] } = { removed: [], retained: [] };
+	const parent = path.dirname(lockPath);
+	const prefix = `${path.basename(lockPath)}.pending.`;
+	const entries = await fs.readdir(parent);
+	let candidates = 0;
+	for (const entry of entries) {
+		if (!entry.startsWith(prefix) || fileLockStagingOwnerPid(entry) === null) continue;
+		if (++candidates > 64) break;
+		const result = await inspectFileLockStagingDir(path.join(parent, entry), ownerLiveness, true);
+		if (result.removed) summary.removed.push(result.path);
+		else summary.retained.push(result);
+	}
+	return summary;
+}