Agent coordination
Multi-agent lanes, session isolation, git mirror, claims, and the live lane dashboard.
Trellis 3.2.5+ ships a coordination wedge for running multiple AI agents on one repo without git stash wars or overlapping edits. 4.0.0+ (ADR 0038): git owns file bytes; the op-log holds provenance and semantics.
Mental model
| Layer | What it is |
|---|---|
| Integration journal | Branch head (main) — promoted lane ops land here |
| Lane journal | Per-agent isolated op log under .trellis/lanes/lane-{uuid}/ |
| Worktree | Optional git checkout at .trellis/worktrees/<shortId>/ when worktreeBind is on |
| Git (4.0+) | Sole authority over file bytes; trellis git sync commits the working tree as-is |
| Op-log | Provenance — issues, lanes, milestones, decisions; no file materialization (4.0+) |
Promote merges lane bytes via git (4.0+) and rechains annotation ops onto integration. Close can auto-promote. Git sync commits the working tree when configured.
Do not use git stash, git checkout, or manual commits inside agent
workflows — hooks and lane guards block these when session lanes are active.
Init defaults
Every trellis init writes:
{
"lanes": { "worktreeBind": true },
"git": { "syncOnPromote": true, "remote": "origin", "pushOnClose": false }
}
Existing repos can merge this into .trellis/config.json or re-run smoke
(below).
Session-scoped lanes (Cursor)
Each Agent tab gets its own lane via
trellis lane ensure --session <conversation-id>. Global Cursor hooks call this
automatically when installed on your desk.
| Env var | Purpose |
|---|---|
TRELLIS_LANE_ID | Active VCS lane |
TRELLIS_SESSION_ID | Cursor conversation id |
TRELLIS_EDIT_ROOT | Lane worktree path when bound |
Profile-static lanes like agent:agent-b are not used for isolation —
session binding owns lane_id.
Requires global hooks: trellis-session-lane.mjs, trellis-session-start.mjs,
trellis-bind-role.mjs, trellis-lane-guard.mjs under ~/.cursor/hooks/.
Verify: node scripts/trellis-coordination-smoke.mjs from a trellis-node
checkout.
Golden path
trellis issue start TRL-1 # branch + lane + claim
# edit under .trellis/worktrees/<shortId>/ when worktreeBind on
trellis lane promote <lane-id> # → integration (+ auto git sync)
trellis issue close TRL-1 --confirm
Or let close auto-promote (default). Use --no-promote to require manual
promote first; --push to push git after close.
Concurrency
Issue claim: one active session per in-progress issue. A second tab gets a
hard error on issue start for the same issue. issue pause releases the
claim.
Promote lock: only one lane promote at a time per repo
(.trellis/locks/promote.lock).
trellis lane lock-status
trellis lane promote <id> --force-lock # clear stale lock
Git adapter
trellis git sync # commit working tree to main (4.0+: no op-log materialization)
trellis git sync --push # + push to configured remote
When git.syncOnPromote is true, successful lane promote runs sync
automatically. 4.0.0+: promote merges the lane git branch into integration,
then sync commits disk bytes and records a vcs:gitSync annotation.
See also: Git Bridge (import/export + ongoing mirror).
Lane watch dashboard
Live SSE view for demos and multi-tab sanity:
trellis lane watch # http://localhost:3939
trellis lane watch --no-open --port 3940
Shows lanes, session ids, op/file counts, worktrees, promote lock, in-progress issues with claims.
Test gates
.trellis/tests.json is seeded on init. Issues can reference suite ids; promote
can require tests:
trellis test
trellis test --list
trellis lane promote <id> --require-test
trellis issue check TRL-1 --suite unit
3.4.0+: promote.require in .trellis/config.json also runs check
(pnpm run check or project equivalent) alongside smoke tests.
4.0.0 git byte authority (ADR 0038)
Git owns file bytes; the op-log owns provenance. trellis git sync commits
the working tree as-is — it never materializes file ops from the journal onto
disk. Lane promote merges the lane git branch into integration, then sync
records a vcs:gitSync annotation.
Disk edits to tracked files flow through git commits, not file-materializing ops. See Git Bridge.
3.4.0 reliability and safety
Promote hardening: snapshot-head invariant and coordination hard-conflict skip reduce spurious "Integration head moved during promote" failures when closing issue branches.
Domain lanes without an issue:
trellis lane split --domain <name> # open a lane without issue start
Pre-write probe:
trellis doctor # mutation safety before contested writes
Criterion retraction (stale AC blocking close):
trellis issue ac-rm TRL-1 1 # tombstone AC index 1 (ids not reused)
Milestone + git:
trellis milestone create "M1" --commit # integration branch only
See CLI commands.
Handoffs and re-entry
trellis protocol send --parent TRL-41 --from reviewer --to strategist \
--re TRL-41 --status HANDOFF --body "REVIEW: PASS"
trellis whereami
trellis whereami checkpoint
See Issue tracking and ADR 0015 (handoff protocol).
Related
- CLI commands — full lane/git/test reference
- VCS API — engine-level lane APIs
- Version control — branches, milestones, promote semantics