Skip to content

Agent Coordination Layer (RFC-0007)#

Metagit’s Agent Coordination Layer (ACL) provides Git-isolation and advisory ownership primitives so many agents can work across repositories without sharing checkouts or colliding on the same branch.

This is not the same as handoff claim TTL leases (metagit context handoff claim --ttl). Handoff leases own a task queue row. ACL leases own a branch for an agent.

Principles#

  1. Agents never share worktrees.
  2. Agents never share agent/* working branches.
  3. Branch leases expire and can be renewed.
  4. File claims and repo presence are advisory — Git remains the authority.
  5. Task graphs ship in RFC-0008 (task-graph.md); semantic ownership ships in RFC-0010 (semantic-ownership.md); merge orchestration ships in RFC-0011 (merge-orchestrator.md); scheduling ships in RFC-0012 (agent-scheduler.md).

Persistence#

Under the session/manifest root:

.metagit/
  branches/branches.json
  leases/leases.json
  worktrees/worktrees.json
  claims/claims.json
  presence/presence.json
  agents/<agent-id>.json
  events/acl.jsonl
.worktrees/<agent-id>/<project>/<repo>/   # default; configurable

Checkout directory is controlled by appconfig workspace.worktrees_path (default .worktrees, env METAGIT_WORKSPACE_WORKTREES_PATH). Relative values resolve from the manifest/session root. The path basename (and the same name without a leading . / _) is reserved and cannot be used as a workspace project name.

CLI#

# Allocate an agent branch
metagit branch allocate --repository project/repo --agent-id agent-1 --task-id 412 --description auth

# Lease the branch (default TTL 30m)
metagit lease acquire --repository project/repo --agent-id agent-1 --task-id 412 --branch agent/412-auth

# Or allocate + lease in one step
metagit lease acquire --repository project/repo --agent-id agent-1 --task-id 412 --allocate

metagit lease renew --lease-id <id> --agent-id agent-1 --ttl 1h
metagit lease release --lease-id <id> --agent-id agent-1
metagit lease list --repository project/repo --json

# Isolated worktree (requires active lease)
metagit worktree create --repository project/repo --agent-id agent-1 --task-id 412 --branch agent/412-auth
metagit worktree status --agent-id agent-1 --json
metagit worktree manifest agent-1
metagit worktree destroy --worktree-id <id> --force
metagit worktree gc

# Advisory file claims
metagit claim declare --repository project/repo --agent-id agent-1 --pattern 'backend/auth/*'
metagit claim check --repository project/repo --pattern 'backend/auth/token.py'
metagit claim list --repository project/repo --json
metagit claim release --claim-id <id> --agent-id agent-1

MCP tools#

When the workspace gate is ACTIVE:

Tool Purpose
metagit_branch_allocate / list / release Branch allocations
metagit_lease_acquire / renew / release / list Branch leases
metagit_worktree_create / destroy / status / list Worktrees
metagit_claim_declare / check / list / release File claims

Events#

ACL lifecycle events append to .metagit/events/acl.jsonl and appear in metagit context events with source: acl (kinds such as BranchAllocated, LeaseGranted, LeaseExpired, WorktreeCreated, ClaimConflict).

Dispatch hints#

metagit agent dispatch-plan includes handoff.acl_commands when project and repo are set — suggested allocate / lease / worktree / claim CLI strings only (no automatic mutation).

Semantic Ownership Hints#

RFC-0010 semantic ownership can attach advisory concept_hints to claim checks when a requested claim pattern overlaps a concept-level ownership pattern. These hints never turn into hard locks or failed claims by themselves. See Semantic ownership for persistence, CLI/MCP commands, seed/ingest behavior, and the deferred GitNexus import path.

Task nodes may also store the same style of hints via metagit task bind-acl — see task-graph.md.

Merge Orchestration#

RFC-0011 can enqueue agent-branch merges, attempt local integration branches, record clean conflicts, run opt-in validators, and emit source=merge events. Conflict records include ACL command hints only; no branch allocation, lease, worktree, or claim is created automatically. See merge-orchestrator.md.

Agent Scheduler#

RFC-0012 scores ready task nodes and returns the next schedule decision with dispatch hints. It does not launch models or mutate git. Soft merge-queue backpressure is optional when RFC-0011 records exist. See agent-scheduler.md.

Agent Operating System#

RFC-0013 provides a composition façade (metagit aos|coord status|doctor|next) over ACL, task graph, and optional 0009–0012 subsystems. See aos.md.