Coordination model

What

Castellan agents coordinate through a shared coordination field, not through conversation. A typed blackboard, decaying pheromone zones, and a pressure-driven scheduler decide who wakes and when — there is no router LLM picking the next agent, no natural-language handoff, and no agent-to-agent chat.

Why

Coordination geometry (topology, zones, wake thresholds) is the thing that gets tuned and evolved, not prompt text. Vocabulary: Conventions.

If you are wiring up a plugin, debugging why an agent never wakes, or trying to understand what castellan run --mux actually does under the hood, this page is the mental model you need.

Substrate primitives

Wake pressure is computed as min(base_pressure, min(dependency signals)), optionally boosted by multiplexer pane activity (pane_status_wake_boost). A task with unmet dependencies stays deferred no matter how high its own base pressure is — the field, not an individual agent, decides readiness.

Quorum = colony phase gate. Unlike task wake (deps ∩ pressure), quorum locks a phase transition until multi-contributor density clears — ablate to a single depositor and the phase stays locked (FalseQuorum immune when mass lacks diversity).

Response thresholds (H2). Topology nodes carry private θ maps; among ready tasks the scheduler can prefer the node with highest stimulus−θ surplus — specialization emerges without hardcoded roles.

Allowed vs forbidden coordination patterns

Anatomy: one scheduler tick

flowchart TB
    G[Goal] --> P[encode_task]
    P --> Q[Pending queue]
    Q --> RP[refresh_pressure]
    RP --> DEP{deps met?}
    DEP -->|no| DEFER[deferred]
    DEP -->|yes| DISPATCH[dispatch]
    DISPATCH --> HOST[RunHost]
    HOST --> OBS[observation]
    OBS --> BB[Blackboard]
    OBS --> FIELD[PheromoneField]
    OBS --> V[verify_goal]
    V --> COMP[deposit completion]
    COMP --> FIELD
    FIELD --> RP

    classDef runtime stroke:#0969da,stroke-width:2px
    classDef substrate stroke:#5b6b8c,stroke-width:2px
    classDef gate stroke:#1a7f37,stroke-width:2px

    class G,P,Q,RP,DISPATCH,HOST runtime
    class OBS,BB,FIELD substrate
    class V,COMP gate

CastellanEngine::run_goal walks this loop until the goal is satisfied, exhausted, or a step budget expires:

1. Encode — the plugin’s encode_task(goal) produces the initial TaskDescriptor.
2. Decay + refresh — the field decays one tick; refresh_pressure recomputes wake pressure for every pending task.
3. Dispatch — the ready batch (dependencies met, pressure over threshold) goes to the RunHost (in-process, mux panes, or remote).
4. Observe — host output updates the blackboard and deposits into zone(s); coordinate_from_observation applies any explicit deposits from the plugin.
5. Verify — verify_goal checks the observation against the goal; on success it deposits a completion signal so dependents wake next tick.
6. Snapshot — field state, topology, and wake stats are written into the episode JSON under .castellan/episodes/.

How operators use it

You rarely touch the substrate directly — you drive it through castellan run and read its effects back out of episode JSON and live MCP tools.

1. Run a goal and let the scheduler coordinate:

castellan run --goal "reach target" --plugin gridworld

2. Force scheduler-led multi-pane coordination (topology + pane tree recorded in the episode):

castellan run --goal "reach target" --plugin gridworld --mux

3. Inspect live substrate state while a run is active (via MCP tools, from an editor or castellan mcp client):

4. Replay a past run to see the coordination trace tick-by-tick:

castellan replay --episode .castellan/episodes/<goal-id>.json

5. Watch multiplexer pane activity feed the field — pane observations can carry pheromone_deposits:

{"pheromone_deposits": [{"zone": "pane", "signal": "activity", "amount": 0.5}]}

These deposits feed pane_status_wake_boost, which nudges wake pressure for stalled tasks whenever panes report activity — useful when a long-running shell pane is making progress but hasn’t hit a dependency signal yet.

Recipes

When a plugin has independent sub-tasks that must merge before completion, use NextAction::Delegate to spawn them and let the blackboard carry results back — don’t have the parent poll or message the children in natural language.

When you want a run to react to external pane activity (e.g. a human working in another tab), enable --mux so pane deposits land in the pane zone and boost wake pressure for dependent tasks.

When debugging “my task never wakes,” dump the episode JSON and check pending/deferred tasks against their declared dependencies — the field will not dispatch a task early no matter how urgent it looks to a human reader.

When you need deterministic, replayable coordination for CI, avoid --rlm/LLM-driven verify and stick to plugin-native verify_goal — the scheduler loop itself never calls an LLM.

Failure paths / troubleshooting

See also

• Memory architecture — where coordination state gets persisted
• Organism model — how coordination parameters get evolved
• Plugin architecture — how plugins declare zones and blackboard slots
• Multiplexer overview — pane deposits and --mux
• Quickstart — first episode