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

# File Reservations

> Advisory locks that prevent editing conflicts

# File Reservations

**Advisory locks prevent merge conflicts.** Agents reserve files before editing, others see what's reserved and work elsewhere.

<Note>
  Like "caution tape" at a construction site — respectful coordination, not enforcement.
</Note>

***

## Quick Start

**Reserve before editing:**

```typescript theme={null}
// Agent wants to edit file
reserve_file_paths({
  file_patterns: ["src/components/UserProfile.tsx"],
  reservation_type: "exclusive",
  duration_minutes: 30
})
```

**Check who has what:**

```typescript theme={null}
list_file_reservations({})
// Shows: GreenCastle reserved UserProfile.tsx (expires in 25 min)
```

**Release when done:**

```typescript theme={null}
release_file_paths({
  file_patterns: ["src/components/UserProfile.tsx"]
})
```

***

## How It Works

**Without Reservations:**

```
2:00 PM → Agent A edits UserProfile.tsx
2:05 PM → Agent B edits UserProfile.tsx
Result: Merge conflict 💥
```

**With Reservations:**

```
2:00 PM → Agent A reserves UserProfile.tsx
2:05 PM → Agent B tries to reserve → Blocked
2:05 PM → Agent B works on different file
2:20 PM → Agent A releases
2:21 PM → Agent B reserves → Success ✅
```

***

## Reservation Types

<Tabs>
  <Tab title="Exclusive">
    **One agent, full control**

    **Use for:** Writing code, modifying files, refactoring

    ```typescript theme={null}
    reserve_file_paths({
      file_patterns: ["src/auth/AuthService.php"],
      reservation_type: "exclusive"
    })
    ```

    **Behavior:**

    * Only 1 agent can hold exclusive reservation
    * Blocks all other reservations (exclusive and shared)
    * Agent can read and write

    **Example:**

    ```
    Agent A: Reserve auth.php (exclusive) ✅
    Agent B: Reserve auth.php (exclusive) ❌ Blocked
    Agent C: Reserve auth.php (shared) ❌ Blocked
    ```
  </Tab>

  <Tab title="Shared">
    **Multiple agents, read-only**

    **Use for:** Code review, reading context, documentation

    ```typescript theme={null}
    reserve_file_paths({
      file_patterns: ["src/types/User.ts"],
      reservation_type: "shared"
    })
    ```

    **Behavior:**

    * Multiple agents can hold shared reservations
    * Blocks exclusive reservations
    * Agents commit to read-only

    **Example:**

    ```
    Agent A: Reserve types.ts (shared) ✅
    Agent B: Reserve types.ts (shared) ✅
    Agent C: Reserve types.ts (shared) ✅
    Agent D: Reserve types.ts (exclusive) ❌ Blocked
    ```
  </Tab>
</Tabs>

***

## Glob Patterns

**Reserve multiple files at once:**

<CardGroup cols={2}>
  <Card title="Directory" icon="folder">
    **All files in directory**

    ```typescript theme={null}
    "src/features/auth/*"
    ```

    Reserves all files in auth folder (one level)
  </Card>

  <Card title="Recursive" icon="folder-tree">
    **All files recursively**

    ```typescript theme={null}
    "src/features/auth/**/*"
    ```

    Reserves all files in auth folder and subfolders
  </Card>

  <Card title="File Type" icon="file-code">
    **All TypeScript files**

    ```typescript theme={null}
    "src/components/**/*.tsx"
    ```

    Reserves all .tsx files in components
  </Card>

  <Card title="Multiple Types" icon="files">
    **Multiple extensions**

    ```typescript theme={null}
    "src/components/**/*.{tsx,ts}"
    ```

    Reserves both .tsx and .ts files
  </Card>
</CardGroup>

**Common Patterns:**

```typescript theme={null}
"src/auth/*"                    // One directory level
"src/auth/**/*"                 // Recursive
"**/*.tsx"                      // All .tsx anywhere
"src/**/*.{tsx,ts}"             // Multiple types
"!src/components/test/**"       // Exclude tests
```

***

## Managing Reservations

<Tabs>
  <Tab title="List Active">
    **See all reservations:**

    ```typescript theme={null}
    list_file_reservations({})
    ```

    **Returns:**

    ```
    📋 Active Reservations (5)

    1. src/components/UserProfile.tsx
       - Agent: GreenCastle
       - Type: exclusive
       - Expires: 25 minutes
       - Reason: Implementing export

    2. src/types/User.ts
       - Agents: SwiftEagle, BoldMountain
       - Type: shared
       - Expires: 15 minutes

    3. src/services/AuthService.ts
       - Agent: ClearRiver
       - Type: exclusive
       - Expires: 5 minutes
    ```
  </Tab>

  <Tab title="Check Specific File">
    **Before editing, check:**

    ```typescript theme={null}
    check_file_reservations({
      file_patterns: ["src/components/UserProfile.tsx"]
    })
    ```

    **If reserved:**

    ```
    ⚠️ Reserved by GreenCastle
    - Type: exclusive
    - Expires: 25 minutes
    - Reason: Implementing export

    💡 Wait for expiration or message GreenCastle
    ```

    **If not reserved:**

    ```
    ✅ Available
    You can reserve it now
    ```
  </Tab>

  <Tab title="Extend">
    **Extend expiration:**

    ```typescript theme={null}
    extend_file_reservations({
      file_patterns: ["src/components/UserProfile.tsx"],
      additional_minutes: 30
    })
    ```

    **When to extend:**

    * Work taking longer than expected
    * Complex refactoring
    * Waiting for input
    * Testing requires more time
  </Tab>

  <Tab title="Release">
    **Release when done:**

    ```typescript theme={null}
    // Release specific file
    release_file_paths({
      file_patterns: ["src/components/UserProfile.tsx"]
    })

    // Release all your reservations
    release_all_file_paths({})
    ```

    **Why release promptly:**

    * Unblocks other agents
    * Good coordination etiquette
    * Prevents unnecessary waiting
  </Tab>
</Tabs>

***

## Conflict Detection

**ULPI prevents conflicts automatically:**

<Tabs>
  <Tab title="Exclusive vs. Exclusive">
    ```
    Agent A: Reserve file.ts (exclusive) ✅
    Agent B: Reserve file.ts (exclusive) ❌

    Error: File already reserved by Agent A
    Expires in: 25 minutes
    ```

    **Resolution:**

    * Wait for expiration
    * Message Agent A to ask status
    * Work on different file
  </Tab>

  <Tab title="Exclusive vs. Shared">
    ```
    Agent A: Reserve file.ts (exclusive) ✅
    Agent B: Reserve file.ts (shared) ❌

    Error: Exclusive lock held by Agent A
    ```

    **Why blocked:**
    Exclusive lock means Agent A is writing, can't allow readers
  </Tab>

  <Tab title="Shared vs. Exclusive">
    ```
    Agent A: Reserve file.ts (shared) ✅
    Agent B: Reserve file.ts (shared) ✅
    Agent C: Reserve file.ts (exclusive) ❌

    Error: 2 shared locks active
    ```

    **Why blocked:**
    Shared locks mean agents are reading, can't allow writer
  </Tab>

  <Tab title="Shared vs. Shared">
    ```
    Agent A: Reserve file.ts (shared) ✅
    Agent B: Reserve file.ts (shared) ✅
    Agent C: Reserve file.ts (shared) ✅

    No conflict - multiple readers allowed
    ```
  </Tab>
</Tabs>

### Glob Pattern Conflicts

**Patterns can overlap:**

```typescript theme={null}
// Agent A reserves directory
Agent A: Reserve "src/components/*" (exclusive)

// Agent B tries specific file
Agent B: Reserve "src/components/UserProfile.tsx" (exclusive)
Result: ❌ Conflict (file matches Agent A's pattern)
```

```typescript theme={null}
// Agent A reserves all TypeScript
Agent A: Reserve "src/**/*.tsx" (exclusive)

// Agent B tries components only
Agent B: Reserve "src/components/*.tsx" (exclusive)
Result: ❌ Conflict (patterns overlap)
```

```typescript theme={null}
// Different directories
Agent A: Reserve "src/features/auth/*" (exclusive)
Agent B: Reserve "src/features/profile/*" (exclusive)
Result: ✅ No conflict
```

***

## Common Patterns

<AccordionGroup>
  <Accordion title="Single File Edit" icon="file-pen">
    **Pattern:** Check → Reserve → Edit → Release

    ```typescript theme={null}
    // 1. Check availability
    check_file_reservations({
      file_patterns: ["src/components/UserProfile.tsx"]
    })

    // 2. Reserve (if available)
    reserve_file_paths({
      file_patterns: ["src/components/UserProfile.tsx"],
      reservation_type: "exclusive",
      reason: "Implementing export button"
    })

    // 3. Edit the file
    [Make changes]

    // 4. Release
    release_file_paths({
      file_patterns: ["src/components/UserProfile.tsx"]
    })
    ```

    **Duration:** 10-20 minutes for simple changes
  </Accordion>

  <Accordion title="Multi-File Feature" icon="files">
    **Pattern:** Reserve all files together, work, release all

    ```typescript theme={null}
    // Reserve everything needed
    reserve_file_paths({
      file_patterns: [
        "src/components/UserProfile.tsx",
        "src/components/UserAvatar.tsx",
        "src/styles/profile.css"
      ],
      reservation_type: "exclusive",
      reason: "User profile export feature",
      duration_minutes: 60
    })

    // Work on all files
    [Implement feature across all files]

    // Test
    [Run tests]

    // Release all
    release_file_paths({
      file_patterns: [
        "src/components/UserProfile.tsx",
        "src/components/UserAvatar.tsx",
        "src/styles/profile.css"
      ]
    })
    ```

    **Duration:** 30-60 minutes for feature work
  </Accordion>

  <Accordion title="Module Refactor" icon="code">
    **Pattern:** Reserve entire module with glob pattern

    ```typescript theme={null}
    // Reserve entire auth module
    reserve_file_paths({
      file_patterns: ["src/features/auth/**/*"],
      reservation_type: "exclusive",
      reason: "Refactoring authentication flow",
      duration_minutes: 120
    })

    // Message other agents
    send_message({
      recipient_ids: [],  // Broadcast
      subject: "Auth Module Refactor",
      body: "Refactoring auth module for 2 hours. Reserved all auth files."
    })

    // Perform refactor
    [Refactor across multiple files]

    // Release
    release_file_paths({
      file_patterns: ["src/features/auth/**/*"]
    })
    ```

    **Duration:** 1-2 hours for module refactors

    **Why broadcast:** Let everyone know you're doing big changes
  </Accordion>

  <Accordion title="Code Review (Read-Only)" icon="magnifying-glass">
    **Pattern:** Shared reservation for reading

    ```typescript theme={null}
    // Reserve for reading
    reserve_file_paths({
      file_patterns: [
        "src/types/User.ts",
        "src/types/Auth.ts"
      ],
      reservation_type: "shared",
      reason: "Reviewing type definitions",
      duration_minutes: 15
    })

    // Read files for context
    [Review code, understand types]

    // Release when done reading
    release_file_paths({
      file_patterns: [
        "src/types/User.ts",
        "src/types/Auth.ts"
      ]
    })
    ```

    **Duration:** 10-15 minutes for review

    **Why shared:** Multiple agents can review simultaneously
  </Accordion>

  <Accordion title="Blocked File - Wait Strategy" icon="clock">
    **Pattern:** File reserved? Work on something else

    ```typescript theme={null}
    // Try to reserve
    check_file_reservations({
      file_patterns: ["src/components/UserProfile.tsx"]
    })

    // Response: Reserved by GreenCastle, expires in 15 min

    // Option 1: Message GreenCastle
    send_message({
      recipient_ids: [GreenCastle_ID],
      subject: "UserProfile.tsx status?",
      body: "Are you still working on UserProfile.tsx? I need to edit it for export feature."
    })

    // Option 2: Work on different file
    reserve_file_paths({
      file_patterns: ["src/components/UserAvatar.tsx"],
      reservation_type: "exclusive",
      reason: "Work on avatar while waiting for UserProfile"
    })

    // Option 3: Wait for expiration (15 min)
    [Wait 15 minutes, then try again]
    ```
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Always Check First" icon="magnifying-glass">
    **Before editing, check reservations**

    ✅ Check → Reserve → Edit → Release

    ❌ Edit → Conflict → Fix merge issues

    **Why:** Prevents conflicts before they happen
  </Card>

  <Card title="Reserve Together" icon="layer-group">
    **Reserve all related files at once**

    ✅ Reserve \[A, B, C] → Edit all → Release all

    ❌ Reserve A → Edit A → Reserve B → Edit B

    **Why:** Atomic operations, clearer intent
  </Card>

  <Card title="Release Promptly" icon="unlock">
    **Don't hold longer than needed**

    ✅ Reserve → Work → Release (15 min)

    ❌ Reserve → Break → Lunch → Work (2 hours)

    **Why:** Unblocks other agents
  </Card>

  <Card title="Communicate Large Changes" icon="megaphone">
    **Broadcast before big refactors**

    ✅ Message team → Reserve module → Refactor

    ❌ Reserve silently → Surprise everyone

    **Why:** Sets expectations, enables planning
  </Card>

  <Card title="Use Specific Patterns" icon="bullseye">
    **Avoid over-reserving with globs**

    ✅ `src/features/auth/**/*.ts` (just auth)

    ❌ `**/*.ts` (entire codebase!)

    **Why:** Better resource sharing
  </Card>

  <Card title="Choose Right Type" icon="toggle-on">
    **Exclusive for writing, shared for reading**

    ✅ Editing? Use exclusive

    ✅ Reviewing? Use shared

    **Why:** Correct semantics enable coordination
  </Card>
</CardGroup>

***

## Human Oversight

**Human Overseers have special powers:**

### Force Release

When agents crash or take too long:

```typescript theme={null}
// Human can force release any reservation
force_release_file_paths({
  agent_id: "crashed_agent_id",
  file_patterns: ["src/components/UserProfile.tsx"],
  reason: "Agent crashed, unblocking file"
})
```

**Use cases:**

* Agent crashed without releasing
* Emergency requires immediate access
* Agent taking excessively long

### View All Reservations

Dashboard shows:

* All active reservations across agents
* Expiration times
* Reservation reasons
* Quick actions (extend, force release)

### Extend Reservations

Extend any agent's reservation:

```typescript theme={null}
extend_file_reservations({
  agent_id: "other_agent_id",
  file_patterns: ["src/components/UserProfile.tsx"],
  additional_minutes: 60,
  reason: "Complex refactor legitimately needs more time"
})
```

***

## Automatic Expiration

**Reservations expire automatically:**

**Default TTL:** 30 minutes

**Lifecycle:**

```
2:00 PM → Reserve (expires 2:30 PM)
2:25 PM → Should extend if still working
2:30 PM → Auto-expires
2:31 PM → File available again
```

**Why auto-expiration:**

* Prevents deadlock if agent crashes
* Unblocks files automatically
* No manual cleanup needed
* Safety net for coordination

**If you need longer:**

```typescript theme={null}
// Extend before expiration
extend_file_reservations({
  file_patterns: ["src/components/UserProfile.tsx"],
  additional_minutes: 30  // Now expires in 60 min total
})
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Can't reserve - already reserved">
    **Cause:** Another agent holds reservation

    **Check who:**

    ```typescript theme={null}
    check_file_reservations({
      file_patterns: ["src/components/UserProfile.tsx"]
    })
    // Shows: GreenCastle, expires in 15 min
    ```

    **Solutions:**

    1. Message GreenCastle to ask status
    2. Wait 15 minutes for expiration
    3. Work on different file
    4. Ask Human Overseer for force release (if urgent)
  </Accordion>

  <Accordion title="Reservation expired while working">
    **Cause:** Didn't extend before 30-minute TTL

    **Solution:**

    ```typescript theme={null}
    // Re-reserve immediately
    reserve_file_paths({
      file_patterns: ["src/components/UserProfile.tsx"],
      reservation_type: "exclusive"
    })
    ```

    **Prevention:**

    * Extend before expiration for long tasks
    * Set reminders at 25-minute mark
  </Accordion>

  <Accordion title="Glob pattern not matching files">
    **Cause:** Incorrect pattern syntax

    **Test pattern:**

    ```typescript theme={null}
    list_file_reservations({
      file_pattern: "src/components/*.tsx"
    })
    // See what files match
    ```

    **Common mistakes:**

    * Missing `**` for recursive: `src/components/**/*.tsx`
    * Wrong base path
    * Incorrect exclude pattern
  </Accordion>

  <Accordion title="Shared reservation blocking me">
    **Cause:** Shared reservations block exclusive (expected)

    **Check who has shared locks:**

    ```typescript theme={null}
    check_file_reservations({
      file_patterns: ["src/types/User.ts"]
    })
    // Shows: SwiftEagle, BoldMountain (shared)
    ```

    **Solutions:**

    1. Wait for shared locks to expire
    2. Message agents to ask if they're done reading
    3. If you only need to read, request shared instead
  </Accordion>
</AccordionGroup>

***

## MCP Tools Reference

**Reserve files:**

```typescript theme={null}
reserve_file_paths({
  file_patterns: ["src/file.ts", "src/**/*.tsx"],
  reservation_type: "exclusive" | "shared",
  duration_minutes: 30,
  reason: "Why you need this"
})
```

**Check reservations:**

```typescript theme={null}
check_file_reservations({
  file_patterns: ["src/file.ts"]
})
```

**List all reservations:**

```typescript theme={null}
list_file_reservations({})
```

**Extend reservation:**

```typescript theme={null}
extend_file_reservations({
  file_patterns: ["src/file.ts"],
  additional_minutes: 30
})
```

**Release files:**

```typescript theme={null}
release_file_paths({
  file_patterns: ["src/file.ts"]
})

// Or release all
release_all_file_paths({})
```

[Full API Reference →](/coordination/api-reference#file-reservations)

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Getting Started" icon="rocket" href="/coordination/getting-started">
    Set up file reservations
  </Card>

  <Card title="Messaging" icon="messages" href="/coordination/messaging">
    Coordinate via agent messages
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/coordination/workflows">
    Complete coordination patterns
  </Card>
</CardGroup>

***

*Advisory locks prevent conflicts without blocking humans. It's coordination, not enforcement.*