feat: implement Phase 7a File Lock Manager for concurrent task write coordination

Advisory file-level locking so concurrent tasks coordinate write access safely.

- FileLockManager class with acquire/release/releaseAll operations
- Per-file locks with automatic expiration (configurable timeout, default 2min)
- Re-entrant lock support (same task can re-acquire its own lock)
- Lock conflict detection with detailed conflict info
- Event system for lock lifecycle (acquired/released/expired)
- Reverse index for efficient per-task lock lookup
- Path normalization for consistent lock keys
- 39 comprehensive unit tests covering all operations

Part of Phase 7 (Controlled Write Parallelism) for Issue #12330

Author: roomote

src/services/file-lock/FileLockManager.ts

@@ -0,0 +1,348 @@
+import path from "path"
+
+/**
+ * Information about a file lock held by a task.
+ */
+export interface FileLockInfo {
+	/** Absolute normalized path of the locked file */
+	filePath: string
+	/** ID of the task holding the lock */
+	taskId: string
+	/** Timestamp (ms) when the lock was acquired */
+	acquiredAt: number
+}
+
+/**
+ * Result returned when a lock acquisition attempt fails.
+ */
+export interface LockConflict {
+	/** The file that is already locked */
+	filePath: string
+	/** The task that currently holds the lock */
+	holdingTaskId: string
+	/** How long (ms) the lock has been held */
+	heldForMs: number
+}
+
+/**
+ * Events emitted by the FileLockManager.
+ */
+export type FileLockEvent =
+	| { type: "lock-acquired"; filePath: string; taskId: string }
+	| { type: "lock-released"; filePath: string; taskId: string }
+	| { type: "lock-expired"; filePath: string; taskId: string }
+	| { type: "all-locks-released"; taskId: string; count: number }
+
+export type FileLockEventListener = (event: FileLockEvent) => void
+
+export interface FileLockManagerOptions {
+	/**
+	 * Maximum duration (ms) a lock can be held before it is forcibly released.
+	 * Default: 120_000 (2 minutes).
+	 */
+	lockTimeoutMs?: number
+}
+
+const DEFAULT_LOCK_TIMEOUT_MS = 120_000
+
+/**
+ * Advisory file-level lock manager for coordinating writes across concurrent tasks.
+ *
+ * Locks are "advisory" -- they do not use OS-level file locks. Instead, the
+ * tool execution layer checks the lock manager before allowing write operations.
+ * This keeps the system portable and testable.
+ *
+ * All file paths are normalized to absolute paths using `path.resolve` before
+ * being used as map keys, ensuring consistent lookup regardless of how the
+ * path is specified (relative, absolute, trailing slashes, etc.).
+ */
+export class FileLockManager {
+	/**
+	 * Map from normalized absolute file path to lock info.
+	 */
+	private locks = new Map<string, FileLockInfo>()
+
+	/**
+	 * Reverse index: taskId -> set of normalized file paths locked by that task.
+	 */
+	private taskLocks = new Map<string, Set<string>>()
+
+	/**
+	 * Event listeners.
+	 */
+	private listeners: FileLockEventListener[] = []
+
+	/**
+	 * Maximum lock hold duration in milliseconds.
+	 */
+	private readonly lockTimeoutMs: number
+
+	constructor(options?: FileLockManagerOptions) {
+		this.lockTimeoutMs = options?.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS
+	}
+
+	/**
+	 * Attempt to acquire a write lock on a file for a specific task.
+	 *
+	 * If the file is already locked by the same task, refreshes the timestamp
+	 * and returns true (re-entrant). If locked by a different task, checks
+	 * for expiration first -- if the existing lock has expired it is forcibly
+	 * released before granting the new lock.
+	 *
+	 * @returns `true` if the lock was acquired, `false` if another task holds it.
+	 */
+	acquireLock(filePath: string, taskId: string): boolean {
+		const normalized = this.normalizePath(filePath)
+		const existing = this.locks.get(normalized)
+
+		if (existing) {
+			// Re-entrant: same task already holds the lock -- refresh timestamp
+			if (existing.taskId === taskId) {
+				existing.acquiredAt = Date.now()
+				return true
+			}
+
+			// Check if the existing lock has expired
+			if (this.isLockExpired(existing)) {
+				this.forceReleaseLock(normalized, existing.taskId)
+			} else {
+				return false
+			}
+		}
+
+		// Acquire the lock
+		const lockInfo: FileLockInfo = {
+			filePath: normalized,
+			taskId,
+			acquiredAt: Date.now(),
+		}
+
+		this.locks.set(normalized, lockInfo)
+
+		let taskSet = this.taskLocks.get(taskId)
+		if (!taskSet) {
+			taskSet = new Set()
+			this.taskLocks.set(taskId, taskSet)
+		}
+		taskSet.add(normalized)
+
+		this.emit({ type: "lock-acquired", filePath: normalized, taskId })
+		return true
+	}
+
+	/**
+	 * Release a lock held by a specific task.
+	 * No-op if the task does not hold the lock.
+	 */
+	releaseLock(filePath: string, taskId: string): void {
+		const normalized = this.normalizePath(filePath)
+		const existing = this.locks.get(normalized)
+
+		if (!existing || existing.taskId !== taskId) {
+			return
+		}
+
+		this.locks.delete(normalized)
+
+		const taskSet = this.taskLocks.get(taskId)
+		if (taskSet) {
+			taskSet.delete(normalized)
+			if (taskSet.size === 0) {
+				this.taskLocks.delete(taskId)
+			}
+		}
+
+		this.emit({ type: "lock-released", filePath: normalized, taskId })
+	}
+
+	/**
+	 * Release all locks held by a specific task.
+	 * Called when a task completes, is cancelled, or errors out.
+	 */
+	releaseAllLocks(taskId: string): void {
+		const taskSet = this.taskLocks.get(taskId)
+		if (!taskSet || taskSet.size === 0) {
+			this.taskLocks.delete(taskId)
+			return
+		}
+
+		const count = taskSet.size
+
+		for (const normalized of taskSet) {
+			this.locks.delete(normalized)
+		}
+
+		this.taskLocks.delete(taskId)
+
+		this.emit({ type: "all-locks-released", taskId, count })
+	}
+
+	/**
+	 * Check which task (if any) holds the lock on a file.
+	 * Checks for expiration -- if the lock is expired, it is released and
+	 * `undefined` is returned.
+	 *
+	 * @returns The taskId of the lock holder, or `undefined` if unlocked.
+	 */
+	getLockHolder(filePath: string): string | undefined {
+		const normalized = this.normalizePath(filePath)
+		const existing = this.locks.get(normalized)
+
+		if (!existing) {
+			return undefined
+		}
+
+		if (this.isLockExpired(existing)) {
+			this.forceReleaseLock(normalized, existing.taskId)
+			return undefined
+		}
+
+		return existing.taskId
+	}
+
+	/**
+	 * Get detailed lock info for a file, or undefined if not locked.
+	 * Checks for expiration.
+	 */
+	getLockInfo(filePath: string): FileLockInfo | undefined {
+		const normalized = this.normalizePath(filePath)
+		const existing = this.locks.get(normalized)
+
+		if (!existing) {
+			return undefined
+		}
+
+		if (this.isLockExpired(existing)) {
+			this.forceReleaseLock(normalized, existing.taskId)
+			return undefined
+		}
+
+		return { ...existing }
+	}
+
+	/**
+	 * Get the conflict details when a lock acquisition would fail.
+	 * Returns undefined if the file is not locked by another task.
+	 */
+	getLockConflict(filePath: string, taskId: string): LockConflict | undefined {
+		const normalized = this.normalizePath(filePath)
+		const existing = this.locks.get(normalized)
+
+		if (!existing || existing.taskId === taskId) {
+			return undefined
+		}
+
+		if (this.isLockExpired(existing)) {
+			this.forceReleaseLock(normalized, existing.taskId)
+			return undefined
+		}
+
+		return {
+			filePath: normalized,
+			holdingTaskId: existing.taskId,
+			heldForMs: Date.now() - existing.acquiredAt,
+		}
+	}
+
+	/**
+	 * List all files currently locked by a specific task.
+	 */
+	getLockedFiles(taskId: string): string[] {
+		const taskSet = this.taskLocks.get(taskId)
+		if (!taskSet) {
+			return []
+		}
+		return Array.from(taskSet)
+	}
+
+	/**
+	 * Get all currently held locks. Primarily for debugging/UI display.
+	 * Expired locks are cleaned up during this call.
+	 */
+	getAllLocks(): FileLockInfo[] {
+		const result: FileLockInfo[] = []
+		const expired: Array<{ normalized: string; taskId: string }> = []
+
+		for (const [normalized, info] of this.locks) {
+			if (this.isLockExpired(info)) {
+				expired.push({ normalized, taskId: info.taskId })
+			} else {
+				result.push({ ...info })
+			}
+		}
+
+		// Clean up expired locks
+		for (const { normalized, taskId } of expired) {
+			this.forceReleaseLock(normalized, taskId)
+		}
+
+		return result
+	}
+
+	/**
+	 * Get the total number of active locks.
+	 */
+	get lockCount(): number {
+		return this.locks.size
+	}
+
+	/**
+	 * Register an event listener.
+	 */
+	onEvent(listener: FileLockEventListener): void {
+		this.listeners.push(listener)
+	}
+
+	/**
+	 * Remove an event listener.
+	 */
+	offEvent(listener: FileLockEventListener): void {
+		const idx = this.listeners.indexOf(listener)
+		if (idx !== -1) {
+			this.listeners.splice(idx, 1)
+		}
+	}
+
+	/**
+	 * Clear all locks and listeners. Primarily for testing.
+	 */
+	dispose(): void {
+		this.locks.clear()
+		this.taskLocks.clear()
+		this.listeners = []
+	}
+
+	// --- Private helpers ---
+
+	private normalizePath(filePath: string): string {
+		return path.resolve(filePath)
+	}
+
+	private isLockExpired(info: FileLockInfo): boolean {
+		return Date.now() - info.acquiredAt > this.lockTimeoutMs
+	}
+
+	private forceReleaseLock(normalized: string, taskId: string): void {
+		this.locks.delete(normalized)
+
+		const taskSet = this.taskLocks.get(taskId)
+		if (taskSet) {
+			taskSet.delete(normalized)
+			if (taskSet.size === 0) {
+				this.taskLocks.delete(taskId)
+			}
+		}
+
+		this.emit({ type: "lock-expired", filePath: normalized, taskId })
+	}
+
+	private emit(event: FileLockEvent): void {
+		for (const listener of this.listeners) {
+			try {
+				listener(event)
+			} catch {
+				// Swallow listener errors to avoid breaking lock operations
+			}
+		}
+	}
+}