curriculum-project-hub/docs/architecture/adr/0002-project-lock-owned-by-agent-run.md

ADR 0002: Project Lock Is Owned By AgentRun

Status

Accepted.

Context

The older model effectively made a long-lived teacher/project session hold the project lock. That breaks down once project groups become long-lived collaboration spaces and Claude is invoked on demand.

We need to prevent concurrent Claude executions from modifying the same project, while still allowing teachers to keep discussing the project in the group.

Decision

Use a project-scoped lock whose owner is the current AgentRun.

scope = project_id
owner = run_id
lifetime = one Claude processing task

The lock is acquired after @Claude creates an AgentRun, and released when the run completes, fails, times out or is canceled.

Consequences

• Group membership, teacher identity and Claude provider session do not directly own the lock.
• The same long-lived AgentSession can be reused by many runs.
• cancel current processing releases the lock by run_id.
• Admin force release remains an exceptional operation for stuck runs or lost processes.