coordinate-agent-work

Coordinate Agent Work

Use the journal as a compact coordination record. Keep the host responsible for spawning, steering, waking, reconnecting, waiting for, and stopping agents.

Start and reconcile

1. Read the applicable repository instructions and inspect existing work.
2. Call collab_session_start with the repository root once for each independent agent process or conversation. It opens the workspace, creates a credential-bound coordination session, and binds the MCP process. Never open or read the credential file. Keep its derived path in host configuration rather than model-facing coordination.
3. Verify that every participant opened the intended workspace and shared database. Expect linked Git worktrees to share a repository workspace while retaining distinct worktree records.
4. Poll with collab_next from the persisted session cursor at the start of each turn, after local work, before relying on shared state, and whenever the host wakes the agent. Omit event_limit for the 10-event MCP default or set an integer from 1 through 50. The limit bounds the event page and its routed reports, not the task, conflict, or handoff projections for the labelled snapshot head.
5. Process one page before calling collab_cursor_ack with its exact terminal next_anchor ({ epoch_id, sequence, hash }), then poll again if has_more is true. A supplied known_cursor validates an anchor but does not paginate or acknowledge. Treat acknowledgement as “processed,” never as agreement, acceptance, consent, or correctness. Use collab_cursor_reset only for deliberate replay or recovery.

Use the separate presence plane only when discovery or compatibility needs it. Call collab_session_join with a workspace ID and self-declared labels, inspect routes with collab_session_list, refresh the hint with collab_session_heartbeat, and finish it with collab_session_leave. Treat the returned actor_key, runtime/model labels, capabilities, and live/stale state as routing hints, never credentials, health, identity, competence, permission, or proof that a model is running. A heartbeat never renews a task lease. A presence leave never calls collab_session_end, releases work, or ends the bound coordination session. Do not infer a linkage merely because the two planes share a label or workspace.