File and Symbol Locking

Overview

Locking prevents simultaneous edits at two levels:

Symbol level for TypeScript and JavaScript, using the 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:

Reservation conflict (someone else holds this file/symbol).
Convention 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.

[
  {
    "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. 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.

Getting Started

Setup Guides

Concepts

File and Symbol Locking

Overview

How Reservations Work

Reservation Rules

Coexistence with `must`-tier Conventions

IDE Support

Viewing Reservations

When You Really Need Someone’s Symbol

Why Not Just Use Git?

​Overview

​How Reservations Work

​Reservation Rules

​Coexistence with must-tier Conventions

​IDE Support

​Viewing Reservations

​When You Really Need Someone’s Symbol

​Why Not Just Use Git?

Overview

How Reservations Work

Reservation Rules

Coexistence with `must`-tier Conventions

IDE Support

Viewing Reservations

When You Really Need Someone’s Symbol

Why Not Just Use Git?