feat: Phase 7a - FileLockManager for parallel agent file coordination

[roomote-v0]

Related GitHub Issue

Closes: #12330

Description

This PR attempts to address Issue #12330 by implementing Phase 7a: File Lock Manager, the foundational service for parallel agent execution.

The FileLockManager provides a centralized, in-process coordination layer for file access across multiple concurrent tasks/agents. It implements readers-writer lock semantics:

• Concurrent readers: Multiple tasks can hold read locks on the same file simultaneously
• Exclusive writers: Only one task can hold a write lock at a time, blocking all other access
• FIFO queue with writer priority: Pending requests are queued fairly, with writer priority to prevent starvation
• Timeout support: Lock requests time out after a configurable period (default 30s)
• Auto-release on task disposal: All locks held by a task are automatically released when the task is disposed/aborted via releaseAllForTask() wired into Task.dispose()

Key design decisions:

• Lock granularity is per-file (normalized absolute paths)
• No lock upgrade from read to write (prevents deadlocks)
• The lock manager sits above the existing proper-lockfile mechanism in safeWriteJson (which handles inter-process locking) -- this manager coordinates between in-process agents/tasks
• Complementary to RooProtectedController (access control) -- locks coordinate "can this task access this file right now" vs "can this mode access this file at all"

Files changed:

• src/services/file-lock/types.ts - Lock type definitions
• src/services/file-lock/FileLockManager.ts - Core lock manager implementation
• src/services/file-lock/index.ts - Singleton export
• src/services/file-lock/__tests__/FileLockManager.spec.ts - 24 comprehensive tests
• src/core/task/Task.ts - Wired releaseAllForTask into dispose()

This is Phase 7a only (foundational service). Phase 7b (Write-Capable Background Tasks) will integrate this with tool execution. Feedback and guidance are welcome.

Test Procedure

• Run: cd src && npx vitest run services/file-lock/__tests__/FileLockManager.spec.ts
• All 24 tests pass covering: basic acquisition, concurrent reads, exclusive writes, writer priority, timeouts, idempotent release, releaseAllForTask, query methods, FIFO ordering, and reset

Pre-Submission Checklist

• Issue Linked: This PR is linked to an approved GitHub Issue (see "Related GitHub Issue" above).
• Scope: My changes are focused on the linked issue (one major feature/fix per PR).
• Self-Review: I have performed a thorough self-review of my code.
• Testing: New and/or updated tests have been added to cover my changes (if applicable).
• Documentation Impact: No user-facing documentation updates required for this foundational service.
• Contribution Guidelines: I have read and agree to the Contributor Guidelines.

Documentation Updates

• No documentation updates are required for this internal service.

Additional Notes

This PR also includes design recommendations for Phase 7b and 7c posted in the issue comments, addressing the UX questions about write-capable background tasks and history visibility.

Interactively review PR in Roo Code Cloud

[easonLiangWorldedtech]

@roomote please check is any unit test error

[roomote-v0]

Proofessor   See task

All 39 unit tests pass with no errors (cd src && npx vitest run services/file-lock/__tests__/FileLockManager.spec.ts). No fixes were needed.

Note: There is a pre-existing TypeScript error in src/core/prompts/tools/native-tools/new_task.ts:57 on the base branch (feature/remaining-phases-4-5-6), but it is unrelated to this PR's changes.

[easonLiangWorldedtech]

@roomote please fix that error for that pr #12349

[roomote-v0]

Fixaroo   See task

Fixed the TypeScript errors in new_task.ts (missing closing brace for permissions property, incomplete required array) and tools.ts (duplicate new_task / params entries consolidated). All 39 FileLockManager tests pass.

_{View commit | Revert commit}

[roomote-v0]

Closing this draft PR as the work has been consolidated into #12356.