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

Branch names default to agent/<task-id>[-<slug>]. Appconfig coordination.allowed_branch_prefixes (default ["agent/"]) is what branch allocate --name checks. coordination.branch_pattern (default agent/{task_id}[-{slug}]) is used when --name is omitted. Bracket groups in the pattern are dropped when there is no description slug. A refused name tells you to set coordination.allowed_branch_prefixes.

coordination.worktree_per_task (default false) keeps one active worktree per agent per repo. Set it to true to allow one checkout per task; the path then includes the task id. A second checkout while the flag is false names coordination.worktree_per_task.

--repository . and --repository self mean the git repository that holds the metagit definition. Stored records use ..

coordination.worktree.post_create runs after worktree create and before the record is saved. Each entry is exactly one of symlink, copy, or run. Symlink and copy paths must be relative and gitignored. A tracked path is refused and the message names coordination.worktree.post_create. run is split with shlex and executed in the new worktree without a shell. worktree adopt does not run these hooks.

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 adopt --repository project/repo --path /path/to/existing --agent-id agent-1 --task-id 412
metagit worktree status --agent-id agent-1 --json
metagit worktree manifest agent-1
metagit worktree destroy --worktree-id <id> --force
metagit worktree gc
metagit worktree gc --dry-run
metagit worktree gc --force

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

worktree gc removes active checkouts whose lease has expired or whose path is already gone. It skips a checkout that has uncommitted changes, untracked non-ignored files other than .metagit-agent.json, or commits that are not on a remote, and the skip message names --force. worktree destroy refuses the same way unless --force is passed. --dry-run only reports. A repository with no remotes is not treated as unpushed: removing the worktree leaves the branch in place.

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.