One task at a time per project

Two AI agents editing the same files at the same time is a recipe for corruption — half-applied diffs, partial commits, merge conflicts in the staging area. Build Station prevents this by default: at most one Claude session that writes runs at a time per project's working directory.

The rule

For each project enabled on this Build Station:

• Only one non-worktree Claude session is running in the project's working directory at any moment.
• It doesn't matter which agent owns the task. Different agents, same project lock.
• The next queued task — for the same agent OR any other agent on the project — waits for the running one to finish.

Reviews are exempt, in both directions

Since 1.4.0, a reviewer does not take part in the lock at all:

• A reviewer is not refused because a coding session holds the checkout.
• A running reviewer does not hold the checkout against anyone else.
• Two reviewers can run in one project at the same time.

The reason is what a review does: it reads the working tree and writes nothing to it, so nothing it does can corrupt what the coding session is doing. Serializing them bought no safety and cost real reviews — eight review requests were destroyed with project_busy on 2026-08-12, and one of three on 2026-08-14, each waiting behind a coding session with far longer left to run than the review had.

Reviews still count against the station-wide Concurrent sessions ceiling. See Concurrency limits.

When the running session ends (cleanly or otherwise), the project lock releases. The next queued task spawns on the next opportunity (immediately if the dispatcher is the trigger, within 30 seconds via the poller otherwise).

What this prevents

• Two agents running git add and git commit concurrently and producing tangled history.
• One agent editing a file while another reads a stale version into its context.
• Both agents trying to install dependencies simultaneously and corrupting node_modules.
• One agent generating a new branch name from the current timestamp while another commits to it.

What this does NOT prevent

• Different projects in parallel. Project A and Project B are completely independent. Build Station happily runs an agent in each simultaneously.
• Tasks across different Build Stations. If you have Build Station on two machines, both with the same project enabled, each machine's project lock is independent. The server-side "one task In Progress per agent" rule provides a coarser coordination at the agent identity level, but the project lock is per-machine.
• Anything outside the agent's working directory. If your test suite, a build server, or an unrelated tool is mutating files in the project dir from outside Build Station, the lock doesn't help. Build Station only synchronizes its own spawns.

The carve-out: worktree mode

When worktree mode is on for an agent, the project lock does NOT apply to its spawns. Worktree-mode spawns get their own isolated git worktree (a separate directory) — no collision risk.

So in a single project you can mix:

• An agent in worktree mode running 3 parallel tasks.
• An agent in serialized mode running 1 task at a time.

The serialized agent and the worktree agent's tasks don't block each other (different working directories per spawn). Two serialized agents would.

How the lock is enforced

Build Station tracks every spawn's project directory inside its in-memory process table. Before any new spawn, it checks whether another spawn (Running or Starting) is already in the target project directory with worktree mode off.

The check is atomic with the registration of the new spawn — two simultaneous arriving tasks can't both pass the check and both spawn. One wins, the other queues.

What you see when a task is queued

In the tray menu's status view, queued tasks appear under the project they're queued for, with a reason:

• "Waiting for project lock" — another agent's task is currently running in this project's directory.
• "Agent at concurrency limit" — this agent specifically is already at its max-concurrent setting.
• "Project disabled" — the project's enable toggle is off.

On the dashboard, queued tasks stay in To Do with no In Progress transition until they spawn.

Tuning

The project lock is on by default and there's no way to turn it off globally — it's the safe behavior we want as the default. If you want parallel work on a project, use worktree mode per-agent.

If a single project is bottlenecking your throughput, the right knobs in order:

1. Turn on worktree mode for the agent

Per-agent toggle. Each spawn gets its own dir.

2. Raise the agent's max concurrent

Lets the worktree mode actually run more than one in parallel. See Per-agent concurrency.

3. Split into multiple projects

If the project is monorepo-shaped, breaking it into per-service projects gives each its own independent lock.