Coordination Events, Sessions, and Acknowledgment

Purpose

Define how agents communicate status, blockers, incursions, and handoffs in a machine-readable way that BeadBoard can render and users can act on.

Operating Model

Agent works in a target repository.
User watches and orchestrates from BeadBoard UI.
Agent communication must flow through coordination events and inbox state transitions, not ad-hoc notes.

Event Categories

Use explicit categories with clear intent:

HANDOFF: transfer ownership or next action.
BLOCKED: explicit dependency or missing input.
RESUME: adoption/resumption event.
INFO: milestone or important context.
INCURSION: overlap/collision signal for reserved scope.

Session Stream Expectations

Session feeds should be audit-friendly:

Every coordination event has sender, recipient/system target, bead id, and timestamp.
INCURSION and RESUME are first-class timeline rows, not hidden diagnostics.
Events should be understandable by humans without reading implementation code.

Message Lifecycle

Inbox state machine:

unread when message is delivered.
read when recipient opens/reads message.
acked when recipient explicitly acknowledges.

Required behavior:

Only recipient may ack.
Acks are explicit, not implied by read.
Blocker and handoff flows should request ack when coordination certainty is required.

Recommended Command Patterns

Send structured coordination event:

bb agent send \
  --from <agent-id> \
  --to <peer-agent-id> \
  --bead <bead-id> \
  --category <HANDOFF|BLOCKED|RESUME|INFO|INCURSION> \
  --subject "<short summary>" \
  --body "<actionable details>"

Read inbox for current bead/session work:

bb agent inbox --agent <agent-id> --state unread --bead <bead-id>
bb agent read --agent <agent-id> --message <message-id>
bb agent ack --agent <agent-id> --message <message-id>

Coordination Contracts

Handoff

A HANDOFF should include:

what is done,
what remains,
concrete next action,
whether ack is required.

Blocked

A BLOCKED should include:

blocker description,
requested action,
urgency,
ack requirement.

Incursion

An INCURSION should include:

overlap kind (exact or partial),
owner identity,
incoming identity,
owner liveness,
resolution hint.

Resume

A RESUME should include:

resume reason,
prior session identity,
adopted identity,
evidence summary for safe adoption.

UX Alignment

Session UI should map event semantics to plain-language actions:

Handoff label: "Passed to"
Blocked label: "Needs input"
Read action: "Seen"
Ack action: "Accepted"

Anti-Patterns

Using comments instead of coordination events for handoffs.
Silent reservation collisions with no INCURSION/INFO signal.
Treating read as ack.
Sending vague events with no actionable payload.
Closing a blocked bead without tracking unblock communication.

2.9 KiB Raw Blame History