feat: add FileLockManager for parallel agent file coordination (Phase 7a)

Implements a readers-writer lock manager to coordinate file access
across concurrent tasks/agents. This is the foundational service
for Phase 7 parallel agent execution (Issue #12330).

- FileLockManager with read/write lock semantics
- Concurrent readers, exclusive writers
- FIFO queue with writer priority and timeout support
- Auto-release on task disposal via releaseAllForTask()
- Comprehensive test suite (24 tests)
- Wired into Task.dispose() for automatic cleanup

Author: roomote

src/core/task/Task.ts

@@ -15,6 +15,7 @@ import pWaitFor from "p-wait-for"
 import { serializeError } from "serialize-error"
 import { Package } from "../../shared/package"
 import { formatToolInvocation } from "../tools/helpers/toolResultFormatting"
+import { fileLockManager } from "../../services/file-lock"
 
 import {
 	type TaskLike,
@@ -2293,6 +2294,13 @@ export class Task extends EventEmitter<TaskEvents> implements TaskLike {
 			console.error("Error releasing terminals:", error)
 		}
 
+		// Release any file locks held by this task
+		try {
+			fileLockManager.releaseAllForTask(this.taskId)
+		} catch (error) {
+			console.error("Error releasing file locks:", error)
+		}
+
 		// Cleanup command output artifacts
 		getTaskDirectoryPath(this.globalStoragePath, this.taskId)
 			.then((taskDir) => {

src/services/file-lock/FileLockManager.ts

@@ -0,0 +1,326 @@
+import * as path from "path"
+
+import type { LockType, LockRequest, LockHandle, FileLockState, PendingLock } from "./types"
+
+const DEFAULT_TIMEOUT_MS = 30_000
+
+/**
+ * FileLockManager coordinates file access across concurrent tasks/agents.
+ *
+ * It implements a readers-writer lock per file path:
+ * - Multiple tasks can hold read locks on the same file concurrently.
+ * - Only one task can hold a write lock on a file at a time.
+ * - A write lock blocks all other readers and writers.
+ * - Pending requests are queued FIFO with writer priority.
+ *
+ * This manager operates at the logical/agent level, above the OS-level
+ * advisory locking provided by `proper-lockfile` in `safeWriteJson`.
+ * It coordinates between in-process tasks, not between OS processes.
+ */
+export class FileLockManager {
+	private locks: Map<string, FileLockState> = new Map()
+
+	/**
+	 * Normalize a file path to an absolute, OS-consistent key.
+	 */
+	private normalizePath(filePath: string): string {
+		return path.resolve(filePath)
+	}
+
+	/**
+	 * Get or create the lock state for a file.
+	 */
+	private getOrCreateState(normalizedPath: string): FileLockState {
+		let state = this.locks.get(normalizedPath)
+
+		if (!state) {
+			state = {
+				readers: new Set(),
+				writer: null,
+				queue: [],
+			}
+			this.locks.set(normalizedPath, state)
+		}
+
+		return state
+	}
+
+	/**
+	 * Clean up empty lock state entries to prevent memory leaks.
+	 */
+	private cleanupIfEmpty(normalizedPath: string): void {
+		const state = this.locks.get(normalizedPath)
+
+		if (state && state.readers.size === 0 && state.writer === null && state.queue.length === 0) {
+			this.locks.delete(normalizedPath)
+		}
+	}
+
+	/**
+	 * Create a LockHandle for a granted lock.
+	 */
+	private createHandle(taskId: string, normalizedPath: string, lockType: LockType): LockHandle {
+		let released = false
+
+		return {
+			taskId,
+			filePath: normalizedPath,
+			lockType,
+			acquiredAt: Date.now(),
+			release: () => {
+				if (released) {
+					return // Idempotent
+				}
+
+				released = true
+				this.releaseLock(normalizedPath, taskId, lockType)
+			},
+		}
+	}
+
+	/**
+	 * Release a specific lock and process the queue.
+	 */
+	private releaseLock(normalizedPath: string, taskId: string, lockType: LockType): void {
+		const state = this.locks.get(normalizedPath)
+
+		if (!state) {
+			return
+		}
+
+		if (lockType === "read") {
+			state.readers.delete(taskId)
+		} else if (lockType === "write" && state.writer === taskId) {
+			state.writer = null
+		}
+
+		this.processQueue(normalizedPath)
+		this.cleanupIfEmpty(normalizedPath)
+	}
+
+	/**
+	 * Try to grant the next pending lock(s) in the queue.
+	 *
+	 * Writer priority: if the next item in the queue is a write request,
+	 * it will be granted before any subsequent read requests (once current
+	 * readers/writer finish). This prevents writer starvation.
+	 */
+	private processQueue(normalizedPath: string): void {
+		const state = this.locks.get(normalizedPath)
+
+		if (!state || state.queue.length === 0) {
+			return
+		}
+
+		// Process as many requests as we can from the front of the queue
+		while (state.queue.length > 0) {
+			const next = state.queue[0]
+
+			if (next.request.lockType === "write") {
+				// Write lock: need no readers and no writer
+				if (state.readers.size === 0 && state.writer === null) {
+					state.queue.shift()
+					clearTimeout(next.timer)
+					state.writer = next.request.taskId
+					next.resolve(this.createHandle(next.request.taskId, normalizedPath, "write"))
+				}
+
+				// Whether granted or not, stop processing -- a pending writer
+				// blocks subsequent requests to maintain FIFO + writer priority.
+				break
+			} else {
+				// Read lock: allowed if no writer and no pending writer ahead
+				if (state.writer === null) {
+					state.queue.shift()
+					clearTimeout(next.timer)
+					state.readers.add(next.request.taskId)
+					next.resolve(this.createHandle(next.request.taskId, normalizedPath, "read"))
+					// Continue processing: more reads can be granted concurrently
+				} else {
+					// Writer is active, can't grant reads
+					break
+				}
+			}
+		}
+	}
+
+	/**
+	 * Acquire a lock on a file.
+	 *
+	 * @param request - The lock request details.
+	 * @returns A promise that resolves with a LockHandle when the lock is granted.
+	 * @throws Error if the request times out.
+	 */
+	async acquireLock(request: LockRequest): Promise<LockHandle> {
+		const normalizedPath = this.normalizePath(request.filePath)
+		const state = this.getOrCreateState(normalizedPath)
+		const timeout = request.timeout ?? DEFAULT_TIMEOUT_MS
+
+		// Try immediate grant
+		if (request.lockType === "read") {
+			if (state.writer === null && state.queue.length === 0) {
+				state.readers.add(request.taskId)
+				return this.createHandle(request.taskId, normalizedPath, "read")
+			}
+		} else {
+			// Write lock
+			if (state.writer === null && state.readers.size === 0 && state.queue.length === 0) {
+				state.writer = request.taskId
+				return this.createHandle(request.taskId, normalizedPath, "write")
+			}
+		}
+
+		// Queue the request
+		return new Promise<LockHandle>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				// Remove from queue on timeout
+				const idx = state.queue.findIndex((p) => p === pending)
+
+				if (idx !== -1) {
+					state.queue.splice(idx, 1)
+				}
+
+				this.cleanupIfEmpty(normalizedPath)
+				reject(
+					new Error(
+						`Lock acquisition timed out after ${timeout}ms for ${request.lockType} lock on "${request.filePath}" (task: ${request.taskId})`,
+					),
+				)
+			}, timeout)
+
+			const pending: PendingLock = {
+				request,
+				resolve,
+				reject,
+				timer,
+			}
+
+			state.queue.push(pending)
+		})
+	}
+
+	/**
+	 * Release all locks held by a specific task.
+	 * Called when a task completes, is aborted, or is disposed.
+	 */
+	releaseAllForTask(taskId: string): void {
+		// Collect paths to process (avoid mutating map during iteration)
+		const pathsToProcess: string[] = []
+
+		for (const [normalizedPath, state] of this.locks) {
+			if (state.readers.has(taskId) || state.writer === taskId) {
+				pathsToProcess.push(normalizedPath)
+			}
+
+			// Also remove any pending requests from this task
+			const pendingIndices: number[] = []
+
+			for (let i = 0; i < state.queue.length; i++) {
+				if (state.queue[i].request.taskId === taskId) {
+					pendingIndices.push(i)
+				}
+			}
+
+			// Remove pending requests in reverse order to maintain indices
+			for (let i = pendingIndices.length - 1; i >= 0; i--) {
+				const pending = state.queue[pendingIndices[i]]
+				clearTimeout(pending.timer)
+				pending.reject(new Error(`Lock request cancelled: task ${taskId} was released`))
+				state.queue.splice(pendingIndices[i], 1)
+			}
+		}
+
+		// Release held locks and process queues
+		for (const normalizedPath of pathsToProcess) {
+			const state = this.locks.get(normalizedPath)
+
+			if (!state) {
+				continue
+			}
+
+			state.readers.delete(taskId)
+
+			if (state.writer === taskId) {
+				state.writer = null
+			}
+
+			this.processQueue(normalizedPath)
+			this.cleanupIfEmpty(normalizedPath)
+		}
+	}
+
+	/**
+	 * Check if a file is currently locked for writing.
+	 */
+	isWriteLocked(filePath: string): boolean {
+		const normalizedPath = this.normalizePath(filePath)
+		const state = this.locks.get(normalizedPath)
+		return state?.writer !== null && state?.writer !== undefined
+	}
+
+	/**
+	 * Check if a specific task holds a lock on a file.
+	 */
+	hasLock(taskId: string, filePath: string, lockType?: LockType): boolean {
+		const normalizedPath = this.normalizePath(filePath)
+		const state = this.locks.get(normalizedPath)
+
+		if (!state) {
+			return false
+		}
+
+		if (lockType === "read") {
+			return state.readers.has(taskId)
+		}
+
+		if (lockType === "write") {
+			return state.writer === taskId
+		}
+
+		// No lockType specified: check both
+		return state.readers.has(taskId) || state.writer === taskId
+	}
+
+	/**
+	 * Get the current lock state for a file (for debugging/UI).
+	 * Returns undefined if no locks exist for the file.
+	 */
+	getLockState(filePath: string): FileLockState | undefined {
+		const normalizedPath = this.normalizePath(filePath)
+		return this.locks.get(normalizedPath)
+	}
+
+	/**
+	 * Get all active lock handles for a specific task.
+	 * Note: These are informational snapshots, not actual handles.
+	 */
+	getLocksForTask(taskId: string): Array<{ filePath: string; lockType: LockType }> {
+		const result: Array<{ filePath: string; lockType: LockType }> = []
+
+		for (const [normalizedPath, state] of this.locks) {
+			if (state.readers.has(taskId)) {
+				result.push({ filePath: normalizedPath, lockType: "read" })
+			}
+
+			if (state.writer === taskId) {
+				result.push({ filePath: normalizedPath, lockType: "write" })
+			}
+		}
+
+		return result
+	}
+
+	/**
+	 * Reset all state. Primarily for testing.
+	 */
+	reset(): void {
+		// Cancel all pending timeouts
+		for (const [, state] of this.locks) {
+			for (const pending of state.queue) {
+				clearTimeout(pending.timer)
+			}
+		}
+
+		this.locks.clear()
+	}
+}