beadboard/skills/beadboard-driver/references/coord-events-sessions-ack.md

Coordination Events, Sessions, and Acknowledgment

This guide defines how agents coordinate work using the live BeadBoard surface:

• bb agent send|inbox|read|ack
• bd mail delegated to bb agent through bb-mail-shim.mjs

For full command reference, see coordination-system.md.

Canonical Event Categories

Use only these categories:

• HANDOFF
• BLOCKED
• DECISION
• INFO

Do not use deprecated categories such as RESUME or INCURSION.

Message Lifecycle and ACK Rules

Message states are:

• unread
• read
• acked

Rules:

• HANDOFF and BLOCKED set requires_ack=true automatically.
• DECISION and INFO set requires_ack=false.
• bb agent ack on an unread message advances state to acked and sets both read/ack timestamps.
• Only the recipient can read/ack a message.

WHEN-to-Use Trigger Map

1. You finished your slice and someone else now owns the next step: send HANDOFF.
2. You are hard blocked by dependency/input/env: send BLOCKED and set your agent state to stuck.
3. You need a decision but can still make partial progress: send DECISION.
4. You want traceable FYI context (milestone, caveat, pointer): send INFO.
5. You receive HANDOFF/BLOCKED and have taken responsibility: run read then ack.
6. You receive actionable mail before claiming a bead: process inbox first, then claim.
7. You are stuck after retries: poll inbox, send/refresh BLOCKED, keep state stuck until unblocked.

Inbox Polling Protocol

Minimum checkpoints:

• session start
• immediately before claiming a bead
• before closing a bead
• whenever local execution becomes stuck

Recommended during active execution:

• poll every 60-120 seconds

Commands:

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

Worked BLOCKED Flow (End-to-End)

1. Agent hits a blocker and notifies coordinator/peer.

bb agent send \
  --from amber-otter \
  --to lead-orchestrator \
  --bead beadboard-maf.8 \
  --category BLOCKED \
  --subject "Cannot run mail contract test" \
  --body "bd mail delegate missing in this repo; need delegate config or approval to run preflight patch"

2. Agent marks itself stuck for BeadBoard liveness/Witness surface.

bd agent state amber-otter stuck

3. User sees the blocked signal in BeadBoard UI and intervenes (provides input, clears dependency, or updates config).

4. Agent checks inbox and reads response.

bb agent inbox --agent amber-otter --state unread
bb agent read --agent amber-otter --message <message-id>

5. If the response resolved the blocker, agent acknowledges and resumes.

bb agent ack --agent amber-otter --message <message-id>
bd agent state amber-otter running

6. Agent resumes bead execution and continues heartbeat + evidence updates.

bd mail Delegate Path (Alternative Invocation)

bd mail should delegate to the BeadBoard mail shim:

bd config set mail.delegate "node <abs-path>/skills/beadboard-driver/scripts/bb-mail-shim.mjs"
export BB_AGENT=<agent-id>

Delegate mapping:

• bd mail send ... -> bb agent send --from <BB_AGENT> ...
• bd mail inbox ... -> bb agent inbox --agent <BB_AGENT> ...
• bd mail read <id> -> bb agent read --agent <BB_AGENT> --message <id>
• bd mail ack <id> -> bb agent ack --agent <BB_AGENT> --message <id>

If delegate is missing or invalid, run:

node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs

Reservation Conflict Protocol

Use reservations before editing contested scope:

bb agent reserve --agent <agent-id> --scope <path-or-surface> --bead <bead-id>

Conflict handling:

• Active reservation conflict: stop and coordinate through mail.
• Stale reservation warning: retry with --takeover-stale only after explicit coordination.

Release when done:

bb agent release --agent <agent-id> --scope <path-or-surface>