File Locking

File Locking prevents multiple agents from editing the same file simultaneously. When an agent locks a file, other agents are blocked from modifying it until the lock is released. Locks are tied to tasks and auto-release after inactivity.

How It Works

Before editing any file, an agent must acquire a lock via the acs_lock_file tool. The lock is registered in ETS for fast lookups and tied to the agent's current task. When the task is released, all associated locks are released automatically.

Key Capabilities

Exclusive access — Only one agent can hold a lock on a file at a time. Attempts to lock an already-locked file return a clear conflict error.
Task-scoped locks — Locks are associated with a specific task. Releasing the task releases all its locks.
Auto-release — Locks automatically release after a period of inactivity, preventing deadlocks from crashed or disconnected agents.
Unique constraint — File paths have a uniqueness constraint, ensuring no two agents can lock the same file.

Typical Flow

Agent Lock + Edit + Release

1. Agent → acs_lock_file(agent_id, task_id, "lib/foo.ex")
       → Lock acquired — safe to edit

2. Agent edits lib/foo.ex
       → No other agent can lock this file

3. Agent → acs_release_work(agent_id, task_id)
       → All task locks released automatically

MCP Tools

Tool	Description
`acs_lock_file`	Acquire an exclusive lock on a file path
`acs_unlock_file`	Release a file lock (single or all for a task)
`acs_get_locked_files`	View all currently locked files