Add file locking for concurrent session access

[nikblanchet]

Summary

Current implementation uses "last write wins" for concurrent access. Two CLI instances can corrupt session state when modifying the same session file simultaneously.

Current Behavior

• No file locking
• Race conditions possible
• Last write wins (may lose data)

Proposed Enhancement

Add file locking using standard libraries:

• Node.js: proper-lockfile (npm package)
• Python: filelock (pip package)

Usage (Internal)

TypeScript:

import lockfile from 'proper-lockfile';

async saveSessionState(state: SessionState) {
  const release = await lockfile.lock(targetPath);
  try {
    // Write file...
  } finally {
    await release();
  }
}

Python:

from filelock import FileLock

def save_session_state(state: dict) -> str:
    lock = FileLock(f"{target_path}.lock")
    with lock:
        # Write file...

Implementation

Files:

• cli/src/utils/session-state-manager.ts
• analyzer/src/utils/session_state_manager.py

Dependencies:

• Add proper-lockfile to package.json
• Add filelock to requirements.txt

Trade-offs

• Adds dependencies
• Slightly slower (lock acquisition overhead)
• Benefits: Safe concurrent access, prevents corruption

Effort

~4 hours

Related

• Code review PR Session 2: Audit State Schema & Persistence (Issue #216) #365