> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enagrams.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File and Symbol Locking

> How Enagrams prevents two agents from editing the same code at the same time

## Overview

Locking prevents simultaneous edits at two levels:

* **Symbol level** for TypeScript and JavaScript, using the [symbol graph](/concepts/symbol-graph). Two agents can edit the same file as long as they touch different functions or classes.
* **File level** for everything else, or when a change spans an entire file.

Whichever level applies, the flow is the same: an edit creates a reservation; a conflicting edit from another session is denied with a specific message.

## How Reservations Work

```
Agent A writes src/auth/login.ts (changes validateToken)
  ↓
postToolUse hook fires
  ↓
Enagrams parses the file, diffs it against symbol_graph_nodes
  ↓
Reservation inserted:
  workspace_id, file_path="src/auth/login.ts",
  symbol_ids=["validateToken"], session_id, expires_at (+10 min)
```

```
Agent B tries to edit src/auth/login.ts (also touches validateToken)
  ↓
preToolUse hook fires
  ↓
Enagrams looks up reservations for this file + touched symbols
  ↓
Returns: { permission: "deny",
           message: "symbol validateToken owned by Developer A — 'Build JWT auth flow' (6 min remaining). Suggest: negotiate_open or pick a different symbol." }
  ↓
IDE blocks the write
```

If Agent B instead touches `refreshToken` in the same file, no conflict — the write goes through and creates a separate symbol reservation.

## Reservation Rules

| Rule             | Detail                                                                                         |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| Duration         | 10 minutes, sliding window (reset on every edit by the owning session)                         |
| Scope            | Workspace + file + (optional) symbol ID + session                                              |
| Uniqueness       | `UNIQUE(workspace_id, file_path, symbol_id)` at the DB level — race-free                       |
| Self-reservation | Same user, different conversation → still locks (two tabs lock each other)                     |
| Auto-release     | On `sessionEnd` or expiry                                                                      |
| Fallback         | If we can't resolve symbols (parse failure, non-TS/JS), we fall back to whole-file reservation |

## Coexistence with `must`-tier Conventions

`preToolUse` runs two checks in parallel:

1. Reservation conflict (someone else holds this file/symbol).
2. [Convention](/concepts/conventions) match (`must`-tier rule matches this file + change).

Either one can deny the write, and the message explains which.

## IDE Support

| IDE         | Enforcement level                                                                 |
| ----------- | --------------------------------------------------------------------------------- |
| Cursor      | Full — `preToolUse`/`postToolUse` hooks intercept `write_file`, `edit_file`, etc. |
| Claude Code | Full — hooks intercept both `Edit` and `Write` tools                              |
| Codex       | Full — hook intercepts tool calls in the same way                                 |

## Viewing Reservations

* **Dashboard** — workstream view shows owned files and symbols per member.
* **`sync`** — returns a `reservations` array in the response.
* **API** — `GET /workspaces/:id/reservations`.

```json theme={null}
[
  {
    "file_path": "src/auth/login.ts",
    "symbol_ids": ["validateToken"],
    "reserved_by": "Developer A",
    "session_id": "sess_…",
    "task": "Build JWT auth flow",
    "workstream_slug": "auth-refactor",
    "expires_at": "2026-04-18T10:35:00Z",
    "minutes_remaining": 6
  }
]
```

## When You Really Need Someone's Symbol

Open a [negotiation](/concepts/negotiation). Actions include yielding the symbol, holding it, deferring, proposing a split, or counter-offering — all within a bounded number of turns so the conversation doesn't stall.

## Why Not Just Use Git?

Git catches conflicts at merge time, after hours of duplicate work. Enagrams catches them at write time — before the first conflicting line is written — and gives agents the protocol to resolve them immediately.