@gajae-code/coding-agent 0.17.1 → 0.17.4

package/src/config/file-lock.ts

@@ -27,6 +27,7 @@ export interface FileLockOptions {
 	retryDelayMs?: number;
 	signal?: AbortSignal;
 	onAcquired?: () => void;
+	onContended?: () => void;
 	/** Stable host identity required to safely reclaim locks on a shared volume. */
 	ownerHostId?: string;
 	/** Previous local host identities accepted only when deciding stale-owner reclamation. */
@@ -84,13 +85,22 @@ export function isFileLockAcquireTimeout(error: unknown): error is FileLockAcqui
 }
 
 const DEFAULT_OPTIONS: Required<
-	Omit<FileLockOptions, "ownerHostId" | "previousOwnerHostIds" | "signal" | "onAcquired">
+	Omit<FileLockOptions, "ownerHostId" | "previousOwnerHostIds" | "signal" | "onAcquired" | "onContended">
 > = {
 	staleMs: 10_000,
 	retries: 50,
 	retryDelayMs: 100,
 };
 
+/**
+ * Windows can transiently deny a no-replace publication while another handle still
+ * has the staged or destination path open without delete sharing. The native result
+ * is explicitly pre-mutation in this case, so retrying the same source name cannot
+ * publish twice or clean up a committed namespace change.
+ */
+const PUBLICATION_SHARING_RETRY_ATTEMPTS = 3;
+const PUBLICATION_SHARING_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;
@@ -231,6 +241,7 @@ type LockInfoFileState = {
 	size: bigint;
 	mtimeNs: bigint;
 	ctimeNs: bigint;
+	birthtimeNs: bigint;
 	nlink: bigint;
 };
 
@@ -245,6 +256,10 @@ type LockInfoPathState = {
 
 function lockInfoFileState(stats: BigIntStats): LockInfoFileState | null {
 	if (stats.isSymbolicLink() || !stats.isFile()) return null;
+	// Some supported filesystems report creation time as missing or epoch zero. Keep
+	// the stable dev/inode identity and content evidence usable instead of wedging
+	// acquire/release/GC on a metadata field the filesystem cannot provide.
+	const birthtimeNs = typeof stats.birthtimeNs === "bigint" && stats.birthtimeNs > 0n ? stats.birthtimeNs : 0n;
 	return {
 		dev: stats.dev,
 		ino: stats.ino,
@@ -252,18 +267,21 @@ function lockInfoFileState(stats: BigIntStats): LockInfoFileState | null {
 		size: stats.size,
 		mtimeNs: stats.mtimeNs,
 		ctimeNs: stats.ctimeNs,
+		birthtimeNs,
 		nlink: stats.nlink,
 	};
 }
 
 function sameLockInfoFileState(left: LockInfoFileState, right: LockInfoFileState): boolean {
+	const birthtimeMatches =
+		left.birthtimeNs === 0n || right.birthtimeNs === 0n || left.birthtimeNs === right.birthtimeNs;
 	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 &&
+		birthtimeMatches &&
 		left.nlink === right.nlink
 	);
 }
@@ -312,6 +330,7 @@ function fileLockDirIdentityFromPathState(state: LockInfoPathState, bytes: strin
 		infoSize: String(state.file.size),
 		infoMtimeNs: String(state.file.mtimeNs),
 		infoCtimeNs: String(state.file.ctimeNs),
+		infoBirthtimeNs: String(state.file.birthtimeNs),
 		infoSha256: crypto.createHash("sha256").update(bytes).digest("hex"),
 	};
 }
@@ -679,6 +698,8 @@ function sameFileLockTreeAfterPublication(
 	staged: NativeDirectoryTreeSnapshot,
 	published: NativeDirectoryTreeSnapshot,
 ): boolean {
+	// ctime is intentionally omitted: native snapshots expose no birthtime, and a
+	// metadata-only change must not reject an otherwise identical published tree.
 	return (
 		staged.rootDev === published.rootDev &&
 		staged.rootIno === published.rootIno &&
@@ -694,7 +715,6 @@ function sameFileLockTreeAfterPublication(
 				entry.nlink === current.nlink &&
 				entry.size === current.size &&
 				entry.mtimeNs === current.mtimeNs &&
-				(entry.relativePath === "" || entry.ctimeNs === current.ctimeNs) &&
 				entry.sha256 === current.sha256
 			);
 		})
@@ -878,6 +898,7 @@ function isValidNativeNoReplaceResult(value: unknown): value is NativeNoReplaceR
 				"interrupted",
 				"identity_violation",
 				"durability_not_provable",
+				"sharing_violation",
 				"unknown",
 			] as const
 		).includes(value.reason as never) ||
@@ -953,25 +974,18 @@ function isValidNativeNoReplaceResult(value: unknown): value is NativeNoReplaceR
 function isSuccessfulNativePublication(value: unknown, operation: "primary" | "directory"): boolean {
 	if (!isValidNativeNoReplaceResult(value) || !value.ok) return false;
 	if (operation === "directory") return value.primitive === "mkdirat_renameat_noreplace";
-	switch (process.platform) {
-		case "linux":
-			return value.primitive === "renameat2_noreplace";
-		case "darwin":
-			return value.primitive === "renameatx_np_excl";
-		case "win32":
-			return value.primitive === "windows_rename_noreplace";
-		default:
-			return false;
-	}
+	// Native code records the primitive it actually invoked in the receipt. That
+	// primitive is the producer-platform evidence; process.platform is only ambient
+	// capability metadata and may be overridden by a coordinator discovery test.
+	return (
+		value.primitive === "renameat2_noreplace" ||
+		value.primitive === "renameatx_np_excl" ||
+		value.primitive === "windows_rename_noreplace"
+	);
 }
 
 function isCommittedDirectoryVerificationFailure(value: unknown): value is NativeNoReplaceResult {
-	return (
-		process.platform === "linux" &&
-		isValidNativeNoReplaceResult(value) &&
-		!value.ok &&
-		value.mutationState === "committed"
-	);
+	return isValidNativeNoReplaceResult(value) && !value.ok && value.mutationState === "committed";
 }
 
 /**
@@ -995,6 +1009,35 @@ function isPreMutationUnsupportedRenameResult(value: unknown): value is NativeNo
 	return true;
 }
 
+function isPreMutationSharingViolation(value: unknown): value is NativeNoReplaceResult {
+	return (
+		isValidNativeNoReplaceResult(value) &&
+		!value.ok &&
+		value.code === "sharing_violation" &&
+		value.mutationState === "not_committed" &&
+		value.durabilityState === "not_attempted" &&
+		value.reason === "sharing_violation" &&
+		value.phase === "rename"
+	);
+}
+
+async function publishNoReplaceWithSharingRetry(
+	publish: (sourcePath: string, destinationPath: string) => Promise<NativeNoReplaceResult>,
+	sourcePath: string,
+	destinationPath: string,
+): Promise<NativeNoReplaceResult> {
+	let result = await publish(sourcePath, destinationPath);
+	for (
+		let attempt = 1;
+		attempt < PUBLICATION_SHARING_RETRY_ATTEMPTS && isPreMutationSharingViolation(result);
+		attempt++
+	) {
+		await Bun.sleep(PUBLICATION_SHARING_RETRY_DELAY_MS * attempt);
+		result = await publish(sourcePath, destinationPath);
+	}
+	return result;
+}
+
 async function localLockKey(lockPath: string): Promise<string> {
 	try {
 		return normalizeLockKey(await fs.realpath(lockPath));
@@ -1033,7 +1076,14 @@ type LockStaleSnapshot =
 	| { stale: false }
 	| { stale: true; owner: FileLockOwnerToken; identity: GenericFileLockDirIdentity };
 
-/** Identity evidence carried by the generic stale verdict into a later removal. */
+/**
+ * Identity evidence carried by the generic stale verdict into a later removal.
+ *
+ * `ctimeNs` is a mutable metadata-change time on every supported filesystem, so
+ * it is retained for diagnostics/legacy consumers but is not part of the lock
+ * identity predicate. `infoBirthtimeNs` is the creation time that stays bound
+ * to the file object.
+ */
 export interface GenericFileLockDirIdentity {
 	rootDev: string;
 	rootIno: string;
@@ -1043,23 +1093,34 @@ export interface GenericFileLockDirIdentity {
 	infoSize: string;
 	infoMtimeNs: string;
 	infoCtimeNs: string;
+	infoBirthtimeNs: string;
 	infoSha256: string;
 }
 
-function sameGenericFileLockDirIdentity(left: GenericFileLockDirIdentity, right: GenericFileLockDirIdentity): boolean {
+function sameStableFileLockIdentity(left: GenericFileLockDirIdentity, right: GenericFileLockDirIdentity): boolean {
 	return (
 		left.rootDev === right.rootDev &&
 		left.rootIno === right.rootIno &&
 		left.infoDev === right.infoDev &&
 		left.infoIno === right.infoIno &&
+		left.infoBirthtimeNs === right.infoBirthtimeNs
+	);
+}
+
+/** Content/topology evidence kept separate from the stable file identity. */
+function sameFileLockContentEvidence(left: GenericFileLockDirIdentity, right: GenericFileLockDirIdentity): boolean {
+	return (
 		left.infoNlink === right.infoNlink &&
 		left.infoSize === right.infoSize &&
 		left.infoMtimeNs === right.infoMtimeNs &&
-		left.infoCtimeNs === right.infoCtimeNs &&
 		left.infoSha256 === right.infoSha256
 	);
 }
 
+function sameGenericFileLockDirIdentity(left: GenericFileLockDirIdentity, right: GenericFileLockDirIdentity): boolean {
+	return sameStableFileLockIdentity(left, right) && sameFileLockContentEvidence(left, right);
+}
+
 let nativeExactRemovalUsable: boolean | undefined;
 let nativeExactRemovalProbePromise: Promise<boolean> | undefined;
 
@@ -1170,26 +1231,54 @@ async function removeVerifiedOwnedLockDirWithoutNative(
 		return "cleanup_failed";
 	}
 	const current = await captureFileLockDirIdentity(lockDir);
-	if (!current || !sameGenericFileLockDirIdentity(current, expected)) return "owner_changed";
+	if (!current || !sameStableFileLockIdentity(current, expected)) return "owner_changed";
 	const captured = nativeFileLockBindings().snapshotDirectoryTree(lockDir);
 	if (!captured.ok || !captured.snapshot) return "owner_changed";
 	const infoEntry = captured.snapshot.entries.find(entry => entry.relativePath === "info");
 	if (
-		captured.snapshot.rootDev !== expected.rootDev ||
-		captured.snapshot.rootIno !== expected.rootIno ||
 		!infoEntry ||
-		infoEntry.dev !== expected.infoDev ||
-		infoEntry.ino !== expected.infoIno ||
-		infoEntry.nlink !== expected.infoNlink ||
-		infoEntry.size !== expected.infoSize ||
-		infoEntry.mtimeNs !== expected.infoMtimeNs ||
-		infoEntry.ctimeNs !== expected.infoCtimeNs ||
-		infoEntry.sha256 !== expected.infoSha256
+		!nativeFileLockInfoMatchesStableIdentity(
+			captured.snapshot.rootDev,
+			captured.snapshot.rootIno,
+			infoEntry,
+			expected,
+		) ||
+		!nativeFileLockInfoMatchesContentEvidence(infoEntry, expected)
 	)
 		return "owner_changed";
 	return await removeVerifiedLockDirWithoutNative(lockDir, captured.snapshot, owner);
 }
 
+function nativeFileLockInfoMatchesStableIdentity(
+	rootDev: string,
+	rootIno: string,
+	infoEntry: NativeDirectoryTreeSnapshot["entries"][number],
+	expected: GenericFileLockDirIdentity,
+): boolean {
+	return (
+		rootDev === expected.rootDev &&
+		rootIno === expected.rootIno &&
+		infoEntry.dev === expected.infoDev &&
+		infoEntry.ino === expected.infoIno
+	);
+}
+
+function nativeFileLockInfoMatchesContentEvidence(
+	infoEntry: NativeDirectoryTreeSnapshot["entries"][number],
+	expected: GenericFileLockDirIdentity,
+): boolean {
+	// Native snapshots expose a ctime-shaped field, but ctime is a mutable
+	// metadata-change timestamp on every supported filesystem. The stable file
+	// identity is checked separately; requiring ctime here would reject a
+	// legitimate lock after chmod/ACL/indexer activity.
+	return (
+		infoEntry.nlink === expected.infoNlink &&
+		infoEntry.size === expected.infoSize &&
+		infoEntry.mtimeNs === expected.infoMtimeNs &&
+		infoEntry.sha256 === expected.infoSha256
+	);
+}
+
 export type GenericFileLockDirStaleVerdict = { stale: false } | { stale: true; identity: GenericFileLockDirIdentity };
 
 /**
@@ -1253,17 +1342,17 @@ export async function removeFileLockDirForGc(
 	if (!infoEntry?.sha256) return "owner_changed";
 	const judgedDigest = crypto.createHash("sha256").update(onDiskBytes).digest("hex");
 	if (infoEntry.sha256 !== judgedDigest) return "owner_changed";
+	const currentIdentity = await captureFileLockDirIdentity(nativeCapturePath);
+	if (!currentIdentity || !sameStableFileLockIdentity(currentIdentity, expectedIdentity)) 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
+		!nativeFileLockInfoMatchesStableIdentity(
+			captured.snapshot.rootDev,
+			captured.snapshot.rootIno,
+			infoEntry,
+			expectedIdentity,
+		) ||
+		!nativeFileLockInfoMatchesContentEvidence(infoEntry, expectedIdentity)
 	)
 		return "owner_changed";
 	let removed: NativeExactUnlinkResult;
@@ -1363,6 +1452,28 @@ function ownerLiveness(pid: number): OwnerLiveness {
 	}
 }
 
+/**
+ * Does this owner record belong to a machine other than the acquirer's?
+ *
+ * A host-qualified record is foreign unless the acquirer can prove it is its own:
+ * either the identity matches, or it matches an identity this installation used
+ * before. An acquirer carrying no host identity can prove nothing, so every
+ * host-qualified record stays foreign to it. Foreign records fail closed — their
+ * PID values and clocks are not meaningful here, so they are neither reclaimable
+ * nor locally probeable for liveness.
+ *
+ * Shared by the reclamation verdict and the exhaustion diagnostic so the two can
+ * never disagree about whose pid a record names.
+ */
+function lockRecordIsForeignHost(
+	info: LockInfo,
+	ownerHostId: string | undefined,
+	previousOwnerHostIds: readonly string[],
+): boolean {
+	if (ownerHostId === undefined) return info.owner_host_id !== undefined;
+	return info.owner_host_id !== ownerHostId && !previousOwnerHostIds.includes(info.owner_host_id ?? "");
+}
+
 async function staleLockSnapshot(
 	lockPath: string,
 	_staleMs: number,
@@ -1402,13 +1513,7 @@ async function staleLockSnapshot(
 	// A host-qualified lock may only be reclaimed after proving that its owner is
 	// local. Foreign and malformed host-qualified records fail closed: PID values
 	// and clocks are not meaningful across hosts.
-	if (
-		ownerHostId !== undefined &&
-		info.owner_host_id !== ownerHostId &&
-		!previousOwnerHostIds.includes(info.owner_host_id ?? "")
-	)
-		return { stale: false };
-	if (ownerHostId === undefined && info.owner_host_id !== undefined) return { stale: false };
+	if (lockRecordIsForeignHost(info, ownerHostId, previousOwnerHostIds)) return { stale: false };
 	if (ownerIncarnationChanged(info, startTimeCache)) {
 		if (!judgedIdentity) return { stale: false };
 		let currentIdentity: GenericFileLockDirIdentity | null;
@@ -1619,12 +1724,20 @@ async function tryAcquireLock(
 			renameNoReplacePathAsync,
 			renameDirectoryNoReplacePathAsync,
 		};
-		const published = await publication.renameNoReplacePathAsync(canonicalPendingPath, destinationPath);
+		const published = await publishNoReplaceWithSharingRetry(
+			publication.renameNoReplacePathAsync,
+			canonicalPendingPath,
+			destinationPath,
+		);
 		let publishedSuccessfully = isSuccessfulNativePublication(published, "primary");
 		if (published.ok && !publishedSuccessfully)
 			throw new Error("Failed to publish file lock: invalid primary success receipt.");
 		if (!published.ok && isPreMutationUnsupportedRenameResult(published)) {
-			const fallback = await publication.renameDirectoryNoReplacePathAsync(canonicalPendingPath, destinationPath);
+			const fallback = await publishNoReplaceWithSharingRetry(
+				publication.renameDirectoryNoReplacePathAsync,
+				canonicalPendingPath,
+				destinationPath,
+			);
 			const fallbackSuccessfully = isSuccessfulNativePublication(fallback, "directory");
 			if (fallback.ok && !fallbackSuccessfully)
 				throw new Error("Failed to publish file lock: invalid directory success receipt.");
@@ -1783,16 +1896,16 @@ async function quarantineReleasedLock(
 	if (!captured.ok || !captured.snapshot) return false;
 	const infoEntry = captured.snapshot.entries.find(entry => entry.relativePath === "info");
 	if (!infoEntry?.sha256) return false;
+	const currentIdentity = await captureFileLockDirIdentity(nativeCapturePath);
+	if (!currentIdentity || !sameStableFileLockIdentity(currentIdentity, expectedIdentity)) 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
+		!nativeFileLockInfoMatchesStableIdentity(
+			captured.snapshot.rootDev,
+			captured.snapshot.rootIno,
+			infoEntry,
+			expectedIdentity,
+		) ||
+		!nativeFileLockInfoMatchesContentEvidence(infoEntry, expectedIdentity)
 	)
 		return false;
 	// Bind the owner generation to the snapshot before exact removal. A successor
@@ -1962,14 +2075,22 @@ async function lockHolderDescription(
 			info = bytes === null ? null : parseLockInfoBytes(bytes);
 		}
 		if (info) {
-			// A lock record carrying a foreign owner_host_id belongs to another
+			// A lock record carrying a FOREIGN owner_host_id belongs to another
 			// machine (shared-volume topic registry): its pid is meaningful only
 			// on that host, so probing the same numeric pid here could mislabel a
 			// coincident local process as the holder. Report the owner host with
-			// unknown liveness instead.
-			if (info.owner_host_id !== undefined) {
+			// unknown liveness instead. The same predicate that decides whether
+			// the record is reclaimable decides whether its pid is probeable, so a
+			// holder this acquirer *may* reclaim is never described as opaque.
+			if (lockRecordIsForeignHost(info, ownerHostId, previousOwnerHostIds)) {
+				// An unqualified record carries no host provenance at all. A host-aware
+				// acquirer still fails closed on it — its pid is never probed and its
+				// lock is never reclaimed — but the diagnostic must say the provenance
+				// is missing instead of naming a host it does not have.
+				const provenance =
+					info.owner_host_id === undefined ? "on an unrecorded host" : `on host ${info.owner_host_id}`;
 				return (
-					`held by pid ${info.pid} on host ${info.owner_host_id} (liveness unknown from this host)` +
+					`held by pid ${info.pid} ${provenance} (liveness unknown from this host)` +
 					` since ${new Date(info.timestamp).toISOString()}`
 				);
 			}
@@ -1977,13 +2098,18 @@ async function lockHolderDescription(
 			// record carries a start_time, the start-time identity match) so a dead
 			// holder whose pid was already reused is not mislabeled "(live)".
 			const alive = ownerIsAlive(info);
+			const liveness = alive
+				? "live"
+				: ownerLiveness(info.pid) === "dead"
+					? "dead but not reaped"
+					: "liveness unknown";
 			return (
 				`held by pid ${info.pid}` +
-				(alive
-					? " (live)"
-					: ownerLiveness(info.pid) === "dead"
-						? " (dead but not reaped)"
-						: " (liveness unknown)") +
+				// Keep the host on a host-qualified local record: on a shared volume the
+				// same pathname is contended from several hosts, so naming the one whose
+				// pid space this verdict came from is what makes it actionable.
+				(info.owner_host_id === undefined ? "" : " on this host") +
+				` (${liveness})` +
 				` since ${new Date(info.timestamp).toISOString()}`
 			);
 		}
@@ -2022,6 +2148,7 @@ export async function acquireFileLock(filePath: string, options: FileLockOptions
 	}
 	const ownerToken = crypto.randomUUID();
 	const contentionStartTimes = new Map<string, string | null>();
+	let contentionObserved = false;
 	let staleRemovalFailure: RecordedStaleRemovalFailure | undefined;
 	for (let attempt = 0; attempt < opts.retries; attempt++) {
 		if (opts.signal?.aborted) throw opts.signal.reason ?? new Error("File lock acquisition aborted");
@@ -2052,6 +2179,10 @@ export async function acquireFileLock(filePath: string, options: FileLockOptions
 			localLockStates.set(localKey, { owner: result, status: "held" });
 			return () => releaseLock(lockPath, result, localKey);
 		}
+		if (!contentionObserved) {
+			contentionObserved = true;
+			opts.onContended?.();
+		}
 		const pendingKey = await pendingLocalReleaseKey(lockPath, localKey);
 		const localState = localLockStates.get(pendingKey ?? localKey);
 		if (pendingKey !== undefined && localState?.status !== "held" && localState?.owner.owner_token !== undefined) {