Lock mechanism for concurrent KB install/update prevention

[rucka]

Context

Follow-up from PR #133 (Story #92) code review. The lock mechanism for preventing concurrent KB installations was marked as incomplete in the story DoD and was not implemented in the PR.

Problem

Multiple concurrent pair install or pair update commands could interfere with each other, potentially causing:

• Corrupted KB installation (partial writes)
• Race conditions in temp file cleanup
• Inconsistent registry state

Proposed Solution

Implement lock file mechanism at target location:

• Lock file: .pair/.install-lock at target directory
• Acquire: Before starting install/update operations
• Release: After completion (success or failure)
• Timeout: Fail fast if lock held > 30s (stale lock detection)
• Error message: Clear message when operation blocked by concurrent process

Acceptance Criteria

• Lock acquired before KB install/update begins
• Lock released after operation completes (success path)
• Lock released after operation fails (error path)
• Stale lock detection (> 30s old locks are overridden with warning)
• Clear error message when lock held by another process
• Unit tests for lock acquire/release/timeout scenarios
• Smoke test for concurrent install attempts (one succeeds, one blocks)

Technical Notes

Location: apps/pair-cli/src/kb-manager/lock-manager.ts

Interface:

interface LockManager {
  acquire(targetDir: string): Promise<LockHandle>
  release(handle: LockHandle): Promise<void>
  isLocked(targetDir: string): Promise<boolean>
}

Implementation approach:

• Use fs.writeFile with exclusive flag for atomic lock creation
• Store PID in lock file for diagnostics
• Check lock file mtime for staleness detection

Priority

Low - Concurrent usage unlikely in MVP (single-user CLI tool), but good practice for robustness.

Related

• PR [#92] feat: flexible KB source resolution #133 (story Flexible KB Source Resolution #92 implementation)
• Epic Simple KB Distribution & Installation #65 (Enhanced CLI Packaging & Distribution)