Q&A: Phase 12.5 CoalitionFormation — capability scoring, invitation TTL, consensus integration, and observer access

[web3guru888]

Community Q&A thread for Phase 12.5 CoalitionFormation. Post your implementation questions, design concerns, and integration scenarios below.

---

Q1: How do I set required_capabilities vs preferred_capabilities?

A: Use required_capabilities for hard dependencies — if an agent lacks any of these, it is excluded from the coalition entirely. Use preferred_capabilities as a soft tiebreaker (weight 0.5 vs 1.0):

Capability Type	Effect on Scoring	Agent Excluded if Missing?
required	+1.0 per cap	Yes
preferred	+0.5 per cap	No

# Example: coalition needs a planner + reasoner; memory is a bonus
request = FormationRequest(
    goal_id               = "goal-complex-planning",
    required_capabilities = ["PLANNING", "REASONING"],
    preferred_capabilities = ["MEMORY", "SEARCH"],
    min_members           = 2,
    max_members           = 5,
)

---

Q2: What happens if not enough agents accept within invitation_ttl_secs?

A: form_coalition() raises RuntimeError and sets the coalition to FAILED. The partially opened CollaborationChannel is closed immediately:

form_coalition() called
  _invite_members() waits up to invitation_ttl_secs (default 10 s)
  len(accepted) < min_members  -->  channel_mgr.close(channel_id)
                                -->  RuntimeError raised
                                -->  metrics.formations_failed.inc()

The caller (CognitiveCycle._coordinate_via_coalition) should catch this and fall back to single-agent execution or re-queue the goal.

---

Q3: Can I change the leader after coalition formation?

A: No — Coalition is a frozen dataclass; leader_id is immutable after form_coalition() returns. The leader is always the highest-scoring agent from _select_candidates(). If the leader becomes unavailable, dissolve the coalition and form a new one:

await cf.dissolve(coalition.coalition_id, reason="leader offline")
new_coalition = await cf.form_coalition(request)

---

Q4: How does ConsensusVoting integrate with CoalitionFormation?

A: CoalitionFormation calls _ratify_high_stakes_goal() from CognitiveCycle, which calls ConsensusVoting.open_ballot() with eligible = coalition.members. The flow:

form_coalition() --> Coalition(ACTIVE)
_ratify_high_stakes_goal(peer_ids = members - {self})
  ConsensusVoting.open_ballot(eligible = members, threshold = 0.6)
  Each member receives ballot_id via CollaborationChannel HELP_REQUEST
  Members call cast_vote(ballot_id, agent_id, "YES"|"NO"|"VETO")
  _close() publishes CONSENSUS_RESULT on channel
  VoteOutcome.PASS   --> coalition continues ACTIVE
  VoteOutcome.FAIL   --> dissolve(coalition_id, "consensus failed")
  VoteOutcome.VETO   --> dissolve(coalition_id, "veto received")

---

Q5: What is coalition_ttl_secs and when should I tune it?

A: The TTL is a hard deadline for the entire coalition lifecycle — from formation to dissolution. After coalition_ttl_secs seconds, _ttl_task calls dissolve() regardless of task state.

Scenario	Recommended TTL
Quick sub-task (API call)	30–60 s
Moderate goal (multi-step reasoning)	120–300 s (default)
Long-running coordination	600–1800 s
Background federated learning	Set TTL = None (manual dissolve)

---

Q6: How do I add OBSERVER agents to an existing coalition?

A: Phase 12.5 does not expose a direct "add observer" API on the immutable Coalition record. Instead, you can manually subscribe an agent to the coalition's CollaborationChannel with read-only access (no publish permission). The CoalitionRole.OBSERVER enum exists for role-tracking in _roles, but the invitation mechanism in Phase 12.5 only handles LEADER and MEMBER:

# Directly subscribe an observer to the channel (no invitation needed)
await channel_mgr.get(coalition.channel_id).subscribe(
    channel_id  = coalition.channel_id,
    subscriber_id = "observer-agent-007",
)
# Track role separately
cf._roles[coalition.coalition_id]["observer-agent-007"] = CoalitionRole.OBSERVER

---

Q7: How do I set up a Grafana alert for coalition formation failures?

A: Use the coalition_formations_failed_total counter:

alert: CoalitionFormationHighFailureRate
expr: |
  rate(coalition_formations_failed_total[5m])
    / (rate(coalition_formations_total[5m]) + rate(coalition_formations_failed_total[5m]))
    > 0.20
for: 2m
labels:
  severity: warning
annotations:
  summary: "Coalition formation failure rate > 20% for 2 min — check agent availability"
  runbook: "https://github.com/web3guru888/asi-build/wiki/Troubleshooting"

Also track coalition_active_gauge for a real-time view of coordination load.