task-locking

Task Lock Coordination

This skill guides proper use of atomic task locking to prevent race conditions in multi-agent workflows.

Why Atomic Locking Matters

In multi-agent systems, multiple agents can try to work on the same task simultaneously. Without proper locking, you get race conditions:

Agent A reads task (unlocked) ─┐
Agent B reads task (unlocked) ─┤ Race condition!
Agent A acquires lock        ─┤ Both think they got it
Agent B acquires lock        ─┘ Data corruption!

Atomic locking prevents this with a single database operation that's guaranteed to succeed for only ONE agent.

The Atomic Pattern

# GOOD - Atomic single UPDATE (only ONE agent succeeds)
cursor.execute("""
    UPDATE tasks SET lock_holder = ?, lock_expires_at = ?
    WHERE id = ? AND (lock_holder IS NULL OR lock_expires_at < ?)
""", (agent_id, expires_at, task_id, current_time))

success = cursor.rowcount > 0  # Only 1 agent gets rowcount=1

# BAD - Race condition (don't do this!)
if not is_locked(task_id):      # Agent A checks: not locked
    set_lock(task_id, agent_id)  # Agent B can check before A sets!

Tested Under Load

The PM Dashboard locking system has been stress-tested:

• 20+ concurrent agents trying to lock the same task
• Exactly 1 agent succeeds every time
• 19 agents fail gracefully with clear error messages

This is proven to work under extreme concurrency.

Two Locking Approaches

1. Automatic Locking (Preferred)

Use update_task_status() for simple workflows:

# Automatically acquires lock when moving to IN_PROGRESS
update_task_status(
    task_id="42",
    status="IN_PROGRESS",
    agent_id="claude"
)
# Lock acquired automatically!

# Work on task...

# Automatically releases lock when moving to REVIEW or DONE
update_task_status(
    task_id="42",
    status="REVIEW",
    agent_id="claude"
)
# Lock released automatically!

Benefits:

• ✅ Simple - one call does everything
• ✅ No forgotten unlocks
• ✅ Correct workflow enforcement
• ✅ Perfect for single-agent work