Lazy Session Branch Creation
Relevant source files
The following files were used as context for generating this wiki page:
- dev/adr/0005-lazy-session-branch-creation.md
- src/infrahub_mcp/tools/session.py
- specs/archive/20260604-141223-session-branch-recovery/spec.md
- specs/archive/20260604-141223-session-branch-recovery/plan.md
- specs/archive/20260604-141223-session-branch-recovery/data-model.md
- specs/archive/20260421-144953-production-ready-mcp-server/spec.md
Lazy Session Branch Creation provides isolated infrastructure environments for AI agents by deferring branch creation until the first write operation occurs. This mechanism ensures that the default branch remains protected while allowing agents to perform mutations within a session-specific context.
Sources: dev/adr/0005-lazy-session-branch-creation.md, specs/archive/20260604-141223-session-branch-recovery/spec.md:16-24
Core Architecture
The system avoids creating branches at the start of a session. Instead, it triggers branch creation only when a tool tagged as a "write" operation is invoked. This approach reduces unnecessary branch sprawl in Infrahub.
Per-Session Scoping
Branch state is managed per MCP session rather than globally for the server process. The server uses a WeakKeyDictionary to map session objects to branch names, ensuring that state is automatically cleaned up when a session terminates.
Sources: specs/archive/20260604-141223-session-branch-recovery/data-model.md:12-28, specs/archive/20260604-141223-session-branch-recovery/spec.md:95-98
Logic Flow for Write Operations
The following diagram illustrates the decision logic when a write tool is called:
The system validates branch writability before execution, checking for deleted or merged statuses. Sources: specs/archive/20260604-141223-session-branch-recovery/plan.md:73-82, specs/archive/20260604-141223-session-branch-recovery/data-model.md:65-79
Branch Naming and Configuration
Branch names are generated based on a configurable branch_pattern. This pattern supports placeholders that are expanded at runtime.
Configuration Placeholders
| Placeholder | Description | Example Replacement |
|---|---|---|
{date} | Current date in YYYYMMDD format | 20260421 |
{hex} | A random 8-character hexadecimal string | a3f2b1c9 |
{user} | The sanitized identity of the authenticated user | jane_doe |
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:76-85, specs/archive/20260604-141223-session-branch-recovery/data-model.md:50-58
Collision Handling
If a generated branch name already exists, the system retries the creation process. It generates a new {hex} value for each attempt, up to a maximum defined by max_branch_retries.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:86-88, dev/adr/0005-lazy-session-branch-creation.md
Recovery and Reset Mechanisms
The system handles scenarios where a session branch becomes unwritable, such as when it is merged or deleted by an external process.
Writability Validation
Before routing a write operation, the system inspects the BranchData.status. Branches marked with specific statuses are considered "unwritable" and trigger recovery.
| Status | Classification | Resulting Action |
|---|---|---|
MERGED | Unwritable | Clear cache, recreate branch, issue warning |
DELETING | Unwritable | Clear cache, recreate branch, issue warning |
OPEN | Writable | Reuse cached branch |
NEED_REBASE | Writable | Reuse cached branch |
Sources: specs/archive/20260604-141223-session-branch-recovery/data-model.md:40-48, specs/archive/20260604-141223-session-branch-recovery/plan.md:73-82
Manual Session Reset
Users can manually reset or override the session branch using the reset_session_branch tool.
- Without Arguments: Clears the current session branch cache. The next write operation will provision a new branch.
- With
branchArgument: Switches the session to the specified branch name. The system validates that the target is conformant to the naming pattern and is not the default branch.
Sources: specs/archive/20260604-141223-session-branch-recovery/spec.md:80-92, src/infrahub_mcp/tools/session.py
Implementation Components
Key Functions
get_or_create_session_branch(ctx): Resolves the branch for the current request. It handles cache lookups, writability checks, and creation logic.branch_name_conforms(name, pattern): Uses regex to verify if an explicitly provided branch name matches the expected format defined in settings._assert_no_privileged_mutations(): Prevents agents from executing schema or branch management mutations via GraphQL that would bypass branch isolation.
Sources: specs/archive/20260604-141223-session-branch-recovery/data-model.md:83-92, specs/archive/20260604-141223-session-branch-recovery/plan.md:144-150
State Transitions
The lifecycle of a session branch involves the following transitions:
Summary
Lazy Session Branch Creation ensures infrastructure safety by isolating agent actions. By combining lazy creation, per-session state management, and proactive recovery from merged branches, the system provides a robust environment for infrastructure mutations while protecting the integrity of the default branch.