Introduction

# Castellan

Pressure wakes agents — multiplexer, dashboard, and episode flywheel in one binary.

Quickstart →

Install

curl -fsSL https://raw.githubusercontent.com/Alphabetsoup16/Castellan/main/install.sh | bash

Castellan is the coordination runtime for multi-agent AI systems. Agents deposit into a typed blackboard and a decaying pheromone field; a pressure scheduler wakes the next agent when dependency signals clear. That is stigmergy — coordination through the environment — and it replaces a chat-router tax with geometry you can log, replay, and evolve.

• Pressure wake — deterministic scheduling from substrate signals, not a manager model picking the next agent.
• Mux + dashboard — panes and the operator UI in one binary.
• Evolve + drift — episodes improve topology; gates keep changes honest.
• RAH depth-bounded — harness-in-harness recursion with topology binding, not opaque shell-outs.

Episode flywheel

flowchart LR
    RUN[castellan run] --> LOG[.castellan/episodes]
    LOG --> EVOLVE[castellan evolve]
    EVOLVE --> GATE[castellan drift-check]
    GATE --> RUN

    classDef runtime stroke:#0969da,stroke-width:2px
    classDef evolve stroke:#d97706,stroke-width:2px
    classDef gate stroke:#1a7f37,stroke-width:2px

    class RUN,LOG runtime
    class EVOLVE evolve
    class GATE gate

1. Run — castellan run (add --mux / --rlm when you want panes)
2. Log — episode JSON under .castellan/episodes/
3. Evolve — topology mutations from the corpus
4. Gate — castellan drift-check against the verification manifest

For agents

Paste this into an agent session before it drives Castellan:

Read https://castellan-docs.pages.dev/integrations/agent-guide.html
(or the mirrored agent-guide.md). Operate via multiplexer panes + substrate
tools — not agent-to-agent chat. Prefer castellan herd status and MCP tools.

Full conventions: Agent guide. Lexicon: Conventions.

Install

Get the castellan binary on your machine and confirm the verify trio passes.

Install methods

Requires stable Rust from rustup.rs; toolchain pinned in rust-toolchain.toml.

After install script or release build, ensure castellan is on PATH:

export PATH="$PWD/target/release:$PATH"   # from repo root

Verify trio

Run these three commands after install — all should succeed:

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

Episode JSON appears under .castellan/episodes/. For full CI parity, see Verify and ./scripts/verify.sh.

Optional: mdbook (docs contributors)

cargo install mdbook mdbook-mermaid --locked
mdbook build book

Next steps

Quickstart

Install Castellan, bring up the multiplexer and dashboard, then land a first episode — under ten minutes when install works.

What you get

Binary on PATH → mux socket → dashboard → first episode JSON.

See it first

$ castellan plugin list
$ castellan run --goal "reach target" --plugin gridworld
episode satisfied

1. Install

curl -fsSL https://raw.githubusercontent.com/Alphabetsoup16/Castellan/main/install.sh | bash
castellan --version

From source: Install.

2. Mux + dashboard

castellan multiplexer ensure
castellan dashboard

Defaults:

• Socket: ~/.config/castellan/castellan.sock
• Episodes: .castellan/episodes/
• Config: castellan.toml when present

In another terminal:

castellan herd status

Quit the dashboard with q. Keybindings: Dashboard.

3. First episode through the mux

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

Episode JSON lands in .castellan/episodes/<goal-id>.json.

When an LLM/editor is wired, swap in a real goal — for example castellan run --goal "…" --plugin shell --mcp. See MCP overview and Agent guide.

Optional: offline smoke (no mux)

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

Common commands

Next steps

Daily driver

Recommended local workflow for operating Castellan — agents, panes, and the episode flywheel. For contributing to the Rust codebase, see Engineering guide and Verify before PR.

Why this loop

Mux keeps panes alive, the dashboard shows pressure and agents, run writes episodes, evolve mutates topology, drift-check gates what you trust.

Loop

castellan multiplexer ensure  →  castellan dashboard  →  castellan run  →  castellan evolve  →  castellan drift-check

1. Multiplexer — castellan multiplexer ensure starts the in-tree PTY server (~/.config/castellan/castellan.sock). Idempotent; safe at the start of every session. Use --session <name> for an isolated socket.
2. Dashboard — castellan dashboard opens the ratatui UI (agents, pressure, pane tree). Writes ~/.config/castellan/statusline.json for MCP observability. Keys: j/k select, Enter attach, r refresh, q quit — see Dashboard.
3. Run — pick a mode:

Every mode writes .castellan/episodes/<goal-id>.json. Default castellan run is a deterministic plugin loop — add --mcp / --model only when you want LLM enrichment.

4. Detach / reattach — panes persist without babysitting. Ctrl+Q detaches; later castellan herd tabs / castellan herd attach <pane-or-session>.
5. Evolve — castellan evolve --episodes 16 --workspace .castellan/episodes. Prefer --plan / --dry-run before applying; MCP exposes castellan_propose_mutation / castellan_resolve_mutation.
6. Gate — castellan drift-check against the verification manifest before you trust a topology change.

Honest scope: drift-check catches structurally invalid or manifest-violating topology. It does not grade goal quality — use episode verdicts and castellan vitals for that.

Config layers from castellan.toml when present. Episodes and archive live under .castellan/.

Operator commands

Remote / SSH

When something breaks

More symptoms: Troubleshooting. Staged diagnostics: castellan doctor --json.

Related

Troubleshooting

Common first-run failures and fixes. Prefer this page for symptoms; Daily driver for the full operator loop; Conventions for paths and lexicon.

What to check first

1. castellan --version — binary on PATH
2. castellan multiplexer ensure then castellan herd status — mux up
3. castellan doctor — staged diagnostics

castellan: command not found

cargo install --path crates/castellan-cli
# or
cargo build -p castellan-cli && export PATH="$PWD/target/debug:$PATH"

Multiplexer socket missing

castellan multiplexer ensure
# or
castellan herd server

Override socket path: export CASTELLAN_SOCKET=~/.config/castellan/castellan.sock

Episodes / doctor look in the wrong directory

Workspace data defaults resolve via resolve_workspace_data_dir (.castellan/ or legacy .flock/ when present). Override with:

export CASTELLAN_DATA_DIR=/path/to/data

Relative values are resolved against the workspace root (doctor --workspace / process cwd for run/evolve).

drift-check fails locally

./scripts/drift-guard.sh
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings

Guardrail edits require manifest updates — see governance policies.

castellan run exits immediately with plugin error

castellan plugin list
castellan plugin info gridworld

Confirm --plugin name matches registry entry. Shell plugin requires bounded argv — no shell injection.

Dashboard shows disconnected

1. Start multiplexer: castellan herd server
2. Attach session: castellan herd attach
3. Check ~/.config/castellan/statusline.json — see statusline

--json output not parseable

castellan run --json emits one CastellanEvent per line (NDJSON). Do not mix with pretty-printed episode JSON — episode file is written to .castellan/episodes/ separately.

Docs build fails

cargo install mdbook mdbook-mermaid --locked
./scripts/install-mermaid-assets.sh
mdbook build book

Related

• Verify
• CLI reference

What Castellan is / is not

Castellan is

• A coordination runtime — pressure-field scheduler, typed blackboard, episode logs
• A plugin harness boundary — CastellanPlugin::verify_goal drives the default castellan run loop
• An in-tree multiplexer — NDJSON socket API + PTY panes (MUX)
• A topology evolution loop — castellan evolve mutates wake maps from episodes
• Governance-aware — castellan.toml hooks, tool pipeline, drift-check manifest

Default castellan run uses deterministic plugins (gridworld, shell). The scheduler wakes agents from substrate signals — not a manager LLM.

Castellan is not

• A drop-in coding agent with dozens of model providers on the hot path
• A wrapper around external harness binaries — Castellan is the coordination runtime
• A meta-harness composition layer that shells out to opaque coding agents as black boxes
• A workflow DSL — coordination is the pressure field, not hand-drawn graphs
• A chat router — agent-to-agent NL handoffs are intentionally forbidden

Honest scope: Castellan optimizes multi-agent coordination geometry — scheduler ticks, pheromone deposits, topology evolution, and multiplexer panes. Vocabulary: Conventions. Landscape peers (for maintainers only): Frontier positioning.

Comparison snapshot

Honest adoption path

Castellan deliberately does not chase coding-agent feature parity — coordination runtime and honest scope are the product.

Related

• Frontier positioning
• Agent guide

Agent guide

Outcome: onboard an LLM or editor agent so it drives panes and substrate tools — not agent-to-agent chat.

Onboarding for AI agents operating Castellan panes — Claude Code, Codex, Cursor, and Pi. Paste this page (or llms.txt) into your agent context before driving Castellan.

What you are operating

Castellan is a coordination runtime, not a chat router. Agents coordinate through:

• Blackboard — typed JSON slots
• Pheromone field — decaying zone signals that wake the scheduler
• Multiplexer panes — PTY sessions with NDJSON socket control

Do not coordinate via agent-to-agent natural language. Use substrate tools and pane deposits.

Install (operator machine)

curl -fsSL https://raw.githubusercontent.com/Alphabetsoup16/Castellan/main/install.sh | bash
export PATH="$HOME/.cargo/bin:$PATH"   # if install.sh used cargo install

Verify:

castellan run --goal "reach target" --plugin gridworld
ls .castellan/episodes/

Daily-driver loop

castellan multiplexer ensure          # start socket server
castellan dashboard                   # ratatui dashboard (optional)
castellan herd status                 # agent states across panes
castellan run --goal "..." --plugin shell --mcp

Episode flywheel: castellan run → .castellan/episodes/*.json → castellan evolve → castellan drift-check.

Agent-specific pane setup

Spawn via socket API:

{"id": 1, "method": "agent.start", "params": {"name": "claude", "focus": true}}

Or CLI: castellan herd attach --pane <id> after castellan herd status.

MCP workflow (Cursor and headless agents)

1. Operator wires castellan mcp in MCP settings (Cursor setup).
2. Agent calls castellan_search_tools → castellan_describe_tool → invoke.
3. For live substrate during episodes, operator runs castellan run --mcp.

Key tools: castellan_deposit_signal, castellan_read_blackboard, castellan_topology_snapshot, castellan_multiplexer_status, castellan_recall, castellan_remember. Always call castellan_discover_tools or castellan_search_tools before invoking a tool you haven’t used yet — do not guess tool names.

Full catalog: MCP tools · MCP overview.

Socket automation (Multiplexer-shaped)

Connect to ~/.config/castellan/castellan.sock. One JSON request per line.

{"id": 1, "method": "ping", "params": {}}
{"id": 2, "method": "agent.list", "params": {}}
{"id": 3, "method": "pane.read", "params": {"pane_id": "w1:p1", "lines": 40}}
{"id": 4, "method": "events.wait", "params": {"match_event": {"agent_status": "idle"}, "timeout_ms": 60000}}

Full method table: Socket API.

Diagnosis recipes

Flags agents should know

Do not invent flags — verify with castellan --help or CLI reference.

Skills

Castellan scans .castellan/skills/ and ~/.cursor/skills/ on castellan run. Author skills as SKILL.md with frontmatter; install via Cursor skills UI or copy into project.

Honest limits

• Castellan is not OpenCode/Claude Code — no built-in 75-provider coding agent on the hot path.
• Default castellan run uses deterministic plugins; wire your LLM via MCP or panes.
• Agent-to-agent chat coordination is forbidden by design.

See What Castellan is / is not.

Cursor setup

Outcome: wire Cursor as an operator — MCP tools for field/mux, pane agents for work.

Use Castellan in Cursor via MCP (castellan mcp). ACP is available for experiments (Zed-class editors) but MCP is the primary Cursor path.

Install

git clone https://github.com/Alphabetsoup16/Castellan.git && cd Castellan
./install.sh
export PATH="$PWD/target/release:$PATH"

Wire MCP in Cursor

Add a server entry to Cursor MCP config (Settings → MCP, or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "castellan": {
      "command": "/path/to/Castellan/target/release/castellan",
      "args": ["mcp"]
    }
  }
}

Set command to your built target/release/castellan path — Cursor spawns this exact binary, so a relative path or an unbuilt release binary will fail silently in the MCP panel. Restart Cursor after editing the config; MCP servers are loaded once at startup.

Discovery flow: castellan_search_tools → castellan_describe_tool → invoke. Full catalog: MCP tools.

First smoke

Then in Cursor: open the MCP panel (Settings → MCP → castellan) and confirm the server shows connected with tools listed. Ask the agent to call castellan_discover_tools to verify the wire end-to-end.

MCP vs ACP

Failure paths

Skills and memory

Skills: .castellan/skills/ and ~/.cursor/skills/ are both scanned on castellan run.

Memory is the substrate (blackboard, field, episodes) — see Memory architecture. Vector RAG is deferred. Maintainer SQL schema and trait detail: MEMORY_ARCHITECTURE.md.

Agent onboarding

For paste-into-agent context: Agent guide.

MCP overview

Outcome: wire an editor or agent so it can deposit, read the field, and observe the mux — without inventing tool names.

Castellan exposes stigmergy, memory, and harness tools via castellan mcp (stdio JSON-RPC) and live episodes (castellan run --mcp). Both paths share one registry, so tool names, schemas, and governance behavior never drift between editor use and headless runs.

Same tools, two surfaces

castellan mcp
# or during a live episode:
castellan run --goal "…" --plugin shell --mcp

{"jsonrpc":"2.0","id":1,"method":"tools/list"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"castellan_multiplexer_status","arguments":{}}}

Start the server

castellan mcp

Wire your MCP client to stdin/stdout JSON-RPC. Same registry as live episodes — see crates/castellan-mcp/src/registry.rs.

Anatomy: discovery → describe → invoke

flowchart LR
  A[Agent starts] --> B{castellan_discover_tools<br/>or castellan_search_tools}
  B --> C[castellan_describe_tool]
  C --> D[Invoke operational tool]
  D --> E[Governance + trace]

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

  class A,B runtime
  class C,D substrate
  class E gate

1. Discover — castellan_discover_tools returns domain-indexed cards (no full schemas). Optional domain filter.
2. Search — castellan_search_tools with query narrows by intent; BM25-ranked, substring fallback for partial words.
3. Describe — castellan_describe_tool with name returns the full schema, preconditions, side effects, and examples.
4. Invoke — tools/call (stdio) or the mcp_tools observation payload (live episodes).

Meta-tools always ship full schemas in tools/list; operational tools ship compact cards to keep context small — call castellan_describe_tool before invoking one you haven’t used yet.

Full tool catalog

Verified against LIVE_TOOL_NAMES in crates/castellan-mcp/src/registry.rs — do not invent tool names; if a tool you need isn’t here, it doesn’t exist yet.

Meta tools

Operational tools

All 12 operational tools are in LIVE_TOOL_NAMES, so they work identically on castellan run --mcp.

Full schemas, examples, and design rationale: MCP tools reference.

Discovery sequence (copy-paste)

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"castellan_search_tools","arguments":{"query":"deposit","domain":"substrate"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"castellan_describe_tool","arguments":{"name":"castellan_deposit_signal"}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"castellan_deposit_signal","arguments":{"zone":"grid","signal":"coordination","amount":2.0}}}

$ printf '{"jsonrpc":"2.0","id":1,"method":"initialize"}\n' | castellan mcp
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}
$ echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"castellan_search_tools","arguments":{"query":"deposit"}}}' | castellan mcp
{"jsonrpc":"2.0","id":2,"result":{"hits":[{"name":"castellan_deposit_signal",...}]}}

Live field instrument (castellan mcp --attach)

While castellan run is active it publishes a live session under .castellan/live/ (active.json pointer, per-goal snapshot JSON, and an append-only deposit queue). The transport is a file bridge (not a Unix domain socket): the engine drains the queue at tick boundaries—the same semantics a socket would provide, without an async listener inside the sync run loop. External MCP clients hit the same field the scheduler ticks:

castellan mcp --attach auto         # bind to the active live session
castellan mcp --attach <goal_id>    # bind to a specific run

• castellan_deposit_signal enqueues into the live run; the engine drains the queue each tick, emits CastellanEvent::Deposit, and records the deposit on the episode’s instrument_summary with source: "mcp_attach".
• castellan_topology_snapshot returns the last published live snapshot (tick, topology, field zones, wake stats).
• Mutation tools (castellan_propose_mutation, castellan_resolve_mutation) are denied in attach sessions (attach_denied error).
• If no live session exists, --attach fails at startup (attach_unavailable) instead of silently degrading to a standalone engine. If the run ends while attached, calls fail with attach_lost.

Without --attach, plain castellan mcp still auto-routes deposits to an active live session when one exists (source: "external_mcp"), falling back to its own in-memory engine otherwise. castellan doctor reports the live_session stage.

Episode JSON records all MCP instrument activity:

"instrument_summary": {
  "mcp_tool_calls": 3,
  "mcp_deposits": [
    { "tick": 2, "zone": "grid", "signal": "coordination", "amount": 1.5, "source": "mcp_attach" }
  ],
  "topology_snapshots": [{ "tick": 2, "nodes": 2, "edges": 1 }]
}

Live episode example (castellan run --mcp)

{
  "mcp_tools": [
    {
      "tool": "castellan_deposit_signal",
      "args": { "zone": "grid", "signal": "coordination", "amount": 2.0 }
    }
  ]
}

Put entries under mcp_tools in a plugin’s observation payload; CastellanEngine::call_mcp_tool dispatches them against the same registry and governance pipeline as stdio.

Failure paths

Trace JSONL emits mcp_discovery for meta-tools and mcp_tool for operational calls — use --audit on castellan run to capture both.

Editor integration

• Cursor setup — wire MCP in Cursor settings
• Agent guide — onboarding for Claude/Codex/Cursor/Pi
• castellan mcp CLI page — stdio recipes

Statusline and observability

Castellan exposes complementary observability surfaces that share one schema:

1. statusline.json — ObservabilitySnapshot (file + MCP-readable)
2. castellan run --json — typed castellan-events NDJSON stream
3. castellan telemetry --json — SQLite history (sessions, vitals, cost rollups) for CI/metrics

TUI (castellan dashboard) and headless (castellan statusline refresh) write the same snapshot — no parallel JSON schemas.

statusline.json

Default path: ~/.config/castellan/statusline.json.

{
  "schema_version": 1,
  "written_at": "2026-07-18T04:00:00+00:00",
  "connected": true,
  "socket": "/Users/you/.config/castellan/castellan.sock",
  "bus": { "socket": "up", "events": "live", "panes": "socket" },
  "agents": { "total": 3, "idle": 1, "working": 1, "blocked": 0, "done": 1, "unknown": 0 },
  "selected": { "pane_id": "w1:p1", "agent": "claude", "status": "working" },
  "vitals": { "circulation_score": 0.82, "deferred_ratio": 0.1, "cold_zone_count": 0, "pane_pulse": 0.4 },
  "genome": { "genome_id": "gen-abc123", "generation": 4, "lineage_depth": 2 },
  "budget": { "mcp_headroom": 40, "zone_headroom": 12, "deferred_ratio": 0.1 },
  "session_cost": { "usd": 0.42, "tokens": 18300 },
  "live_pressure": { "pane": 0.55 },
  "plan_verify": { "passed": false, "tool": "shell", "reason_code": "missing_plan" },
  "bio": { "kind": "quorum_fired", "summary": "phase=commit ρ=0.80" },
  "topology_apply": { "tick": 3, "born": 1, "pruned": 0, "wake_threshold": 0.4 },
  "potential_delta": null,
  "telemetry": { "agent_transitions": 42 },
  "last_events": []
}

potential_delta (Φ) is omitted or null unless the wire exposes a real value — never a fake number. Footer shows Φ=— when unknown.

Dual-bus honesty (bus)

Read paths

castellan multiplexer ensure
castellan statusline refresh --once --json | jq '{schema_version, connected, bus, live_pressure}'
# MCP freshness
# castellan_multiplexer_status → { ok, stale, age_secs, status }

castellan-events schema (--json)

castellan run --json emits one serde-tagged event per line. Canonical variants include:

Multiplexer events.subscribe bridges the same schema via EmittedEvent::from_castellan_event (fields live under data).

Metrics JSON for CI

castellan telemetry --limit 20   # vitals_count, session_cost, recent_* arrays
castellan statusline refresh --json | jq '{schema_version, session_cost, live_pressure, plan_verify, bio}'

Honest gap: Thin HTTP/SSE of the same snapshot is not shipped yet — not a browser SPA. Prefer statusline.json and MCP for headless observers.

Failure paths

Related

• CLI reference
• Dashboard
• MCP overview

ACP (Agent Client Protocol)

Castellan ships an ACP v1 stdio agent via castellan acp. Editors such as Zed can spawn Castellan as an external coordination agent — scheduler-primary runs that produce episodes, not chat transcripts.

MCP remains the primary Cursor integration path. See Cursor setup.

Capabilities

Phase 3 (MOAT): mux-by-default when socket healthy; session/fork for parent-child lineage; EpisodeCheckpoint saved on every prompt.

Diagnostics

castellan acp doctor

Prints protocol version, agent capabilities, memory backend, mux health (mux_default_on, mux_effective, mux_socket_healthy), and env flags (CASTELLAN_MUX_AUTO, CASTELLAN_MUX_DISABLE, CASTELLAN_ACP_AUTO_DENY).

Zed smoke (5 steps)

1. Build Castellan: cargo build --release -p castellan-cli
2. Copy examples/zed-acp.json into your Zed settings agents list (adjust command path).
3. Open a workspace with a .castellan/ directory (or let Castellan create one on first prompt).
4. Start the Castellan agent in Zed and send: reach target with context plugin gridworld.
5. Confirm the agent returns stopReason: completed, ≥3 session/update notifications, and .castellan/episodes/<goal_id>.json exists.

Mux episodes

Mux is the default when the multiplexer socket is healthy. Explicit "mux": true in prompt context forces mux; "mux": false opts out. Rollback env vars: CASTELLAN_MUX_AUTO=0 or CASTELLAN_MUX_DISABLE=1. ACP attaches pane_tree to persisted episodes for evolve flywheel compatibility.

Session fork

{"jsonrpc":"2.0","id":2,"method":"session/fork","params":{"sessionId":"<parent-id>"}}

Returns { "sessionId": "<child-id>", "parentSessionId": "<parent-id>" }. Child inherits cwd, plugin, and latest goal from parent.

Failure paths

Limitations

• No full chat transcript replay on session/load — episode metadata only (MEMORY_ARCHITECTURE).
• External editor MCP servers are bridged for castellan_* tools only in Phase 2; shell/file tools remain editor-side.
• crates.io publish for library crates is dry-run only until the API stabilizes.

Related

• CLI reference — castellan acp
• Deployment — releases
• MCP overview

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

Organism model

What

Castellan treats a harness as a living organism, not a static config file: a genome expresses coordination parameters, circulation vitals track field health tick-by-tick, and an immune gate rejects harmful topology mutations before they reach production.

Why

This layer turns “evolve topology” from a black box into something you can inspect, quarantine, and trust. Prefer organism terms over animal-pack or feudal metaphors — lexicon.

Read this page if you’re trying to understand what castellan vitals is actually showing you, why a mutation got rejected instead of accepted, or how genome lineage relates to the topology archive.

Status: Phases 1–4 are complete — circulation, DNA lineage, immune gate, and per-zone expression are all live in castellan-evolve/castellan-runtime.

Anatomy: where organism state lives

Bio-novelty extensions (H1–H9)

Circulation vitals also expose role_entropy, role_stickiness, inflammation, and mean_corridor_length when those mechanisms fire.

Organism loop

flowchart LR
    RUN[castellan run] --> VITALS[circulation vitals]
    VITALS --> EP[episode JSON]
    EP --> EV[castellan evolve]
    EV --> IMM[immune_report]
    IMM -->|accept| ARCH[genome archive]
    IMM -->|reject| QUAR[quarantine]

    classDef runtime stroke:#0969da,stroke-width:2px
    classDef evolve stroke:#d97706,stroke-width:2px
    classDef gate stroke:#1a7f37,stroke-width:2px

    class RUN,VITALS,EP runtime
    class EV,ARCH evolve
    class IMM,QUAR gate

1. Every run expresses a CastellanGenome — the coordination and decay parameters active for that episode.
2. The PheromoneField’s circulation health lands in the episode as CirculationVitals.
3. castellan evolve mutates or crosses over (requires a Pareto front with ≥ 2 non-quarantined entries) candidate genomes, then gates every candidate through immune_report().
4. Quarantined genomes are excluded from archive.nearest() — they can never be selected as a seed for a future castellan run --seed-archive.
5. Per-zone decay gets tuned from the proposer’s cold-zone heatmap, so zones that go quiet decay differently from zones under constant pressure.

The immune gate, concretely

ImmuneReport carries two independent signals per candidate:

A genome can be accepted into the archive but still quarantined — quarantine is about seeding safety, not archive membership. Check castellan genome list output for the quarantined flag per entry.

How operators use it

1. Run a goal — a genome is expressed automatically, no flags needed:

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

2. Inspect circulation health for the most recent (or a specific) episode:

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

3. Evolve genomes from the episode corpus — this is where the immune gate runs:

castellan evolve --episodes 10 --workspace .castellan/episodes

4. List genomes and trace lineage:

castellan genome list
castellan genome lineage <genome_id>

5. Seed a new run from a surviving (non-quarantined) genome:

castellan run --goal "reach target" --plugin gridworld --seed-archive --write-back

Phase completion

flux-grid (optional, experimental)

• Feature flag: castellan-substrate/flux-grid — a vendored 64×64 Stigmergy grid.
• Not enabled in default builds. The zone-keyed PheromoneField remains the default substrate.
• Enable for experiments:

cargo build -p castellan-substrate --features flux-grid

Recipes

When a run’s fitness looks fine but the field “feels” unhealthy, check castellan vitals before trusting the number — circulation vitals surface stalls and dead zones that a single scalar fitness score can hide.

When castellan evolve keeps rejecting your best-looking candidates, dump immune_report reasoning via --plan (read-only, zero writes) before assuming the mutator is broken — the drift or immune gate may be catching a real structural problem.

When you want to know if a genome is safe to seed from, always check quarantined on castellan genome list, not just whether it’s present in the archive — presence and safety are separate signals.

When investigating a lineage regression, castellan genome lineage <id> walks parent_genome_id; note that crossover sets a full parent_ids list internally, but the CLI currently surfaces only the primary parent (see Known deferred below).

Failure paths / troubleshooting

Known deferred

• flux-grid is not wired into the swarm-demo default path.
• Full parent_ids lineage is not yet exposed by the CLI (only primary parent_genome_id).
• RAH_MAX_DEPTH cycle avoidance between castellan-evolve and castellan-rah lives in castellan-core but isn’t documented end-to-end yet.

See also

• Coordination model — the substrate whose parameters genomes express
• Topology evolution — the evolve loop that produces and gates genomes
• Evolve round-trip — seeding a run from the archive and writing fitness back
• Quickstart — first episode
• Episode flywheel on Introduction

Topology evolution

What

Evolution that changes coordination geometry — wake thresholds, topology nodes, per-zone decay — not prompt strings. castellan evolve reads real episode logs, proposes structural mutations, gates them through drift + immune checks, and keeps only genomes that measurably improve plugin-grounded fitness.

Why

Outcome: improve harness topology from episode logs under governance gates — fitness from geometry you can replay, not from rewriting prompts. Round-trip seeding: Evolve round-trip. Lexicon: Conventions.

If you’re trying to prove the evolve loop works, debug why a generation got rejected, or wire evolve into CI, this page walks the pipeline end to end.

What this proves

1. Episode logs from real castellan run / swarm-demo runs ground fitness via plugin_grounded_fitness() — not a synthetic benchmark.
2. castellan evolve --episodes 10 runs accept/reject over generations, gated by drift, convergence, and immune gates.
3. Drift gate: structurally incompatible candidates (e.g. edges referencing missing nodes) are rejected on the production path; drift_rejected and drift_violations appear in CLI JSON output when the gate fires.
4. Convergence gate (potential-game): candidates with zero decay, unreachable wake thresholds, or disconnected stigmergy topology are rejected outright, and any candidate whose potential Φ drops below the incumbent’s is rejected even when fitness improves (convergence:potential_decline); convergence_rejected and convergence_violations appear in CLI JSON.
5. Gen-0 vs gen-N fitness delta and full genome lineage are observable directly in CLI output — nothing is hidden behind an opaque score.
6. MAP-Elites (H5): behavior descriptors illuminate a grid of viable geometries (castellan genome map); multi-objective FitnessVector keeps success + circulation per cell.
7. Clonal immune memory (H8): failure antigens clone detectors into .castellan/immune_memory.json so similar failures quarantine faster than static enums alone.

Anatomy: the evolve pipeline

flowchart LR
    EP[episode corpus] --> PROP[proposer]
    PROP --> MUT[mutation candidate]
    MUT --> DRIFT{drift gate}
    DRIFT -->|fail| REJ1[rejected: drift_violations]
    DRIFT -->|pass| CONV{convergence gate}
    CONV -->|fail| REJ1B[rejected: convergence_violations]
    CONV -->|pass| IMM{immune gate}
    IMM -->|auto_reject| REJ2[rejected: quarantine candidate]
    IMM -->|pass| FIT[plugin_grounded_fitness]
    FIT --> ARCH[topology archive]

    classDef evolve stroke:#d97706,stroke-width:2px
    classDef gate stroke:#1a7f37,stroke-width:2px

    class EP,PROP,MUT,FIT,ARCH evolve
    class DRIFT,IMM gate

How operators use it

1. Build the CLI and run the scripted proof end to end:

cargo build --release -p castellan-cli
bash docs/demo/evolve-proof.sh

2. Or step through it manually — generate real episodes, then evolve from them:

castellan swarm-demo
castellan run --goal "reach target" --plugin gridworld   # repeat 3x for a small corpus
castellan evolve --episodes 10 --workspace .castellan/episodes
castellan genome list
castellan genome lineage <genome_id>

3. Do a read-only analysis pass before committing to a mutation:

castellan evolve --plan

--plan emits an evolution plan JSON (incumbent, proposed coordination, pressure summary, drift preview, fitness estimate) with zero writes — safe to run against a production archive.

4. Two-phase gated apply when you want a human or CI check between propose and apply:

castellan evolve --dry-run                      # writes .castellan/proposals/<uuid>.json, no archive writes
castellan evolve --apply-proposal <uuid>        # re-checks drift gate, then applies

5. Live pane topology apply — after field-shaped mutations, apply the seed→target delta to an in-process multiplexer pane tree (typed birth/prune, not chat routing):

castellan evolve --episodes 3 --workspace .castellan/episodes --apply-live

JSON includes live_apply (born, pruned, pane_count). When gates reject the incumbent update, --apply-live still trials the last field-shaped candidate onto live panes and writes .castellan/live/<goal>.topology_apply.jsonl (MCP attach remains instrument-only).

Mid-run drain: while a live-instrumented castellan run is active, the engine drains that JSONL on scheduler ticks (latest-wins), updates topology + wake threshold, emits topology_apply_drained / CastellanEvent::TopologyApplyDrained, and on --mux reconciles panes via RAH apply — without a separate --apply-live pass.

6. Wire the same two-phase flow through MCP (castellan_propose_mutation / castellan_resolve_mutation) when driving evolve from an editor agent instead of the CLI.

Sample output shape

{
  "generations": 10,
  "accepted": 4,
  "rejected": 6,
  "drift_rejected": 1,
  "drift_violations": [
    { "check_id": "topology_edge_refs", "message": "edge agent-1→agent-2 references missing node(s)" }
  ],
  "gen0_fitness": 0.69,
  "final_fitness": 0.74,
  "fitness_delta": 0.05,
  "field_mutations": ["birth_cold_zone", "tune_wake"],
  "instrument_informed": true,
  "seed_source": "episodes",
  "pareto_front": []
}

Recipes

When you want a fast, LLM-free CI smoke test of the evolve loop, run the fixture-backed proof rather than a live corpus:

cargo run -q -p evolve_proof

This uses tests/fixtures/evolve-episodes/ (4 gridworld episodes) — no network, no LLM, deterministic.

When a generation rejects everything, check drift_violations first — a structural issue (missing node reference, invalid zone) will reject before fitness is even computed, so a 100% rejection rate often means one bad mutation shape, not a fitness problem.

When you want continuous improvement without babysitting every generation, use --seed-archive + --write-back on production runs (see Evolve round-trip) so successful runs feed fitness back automatically.

When reviewing a mutation before it goes live, prefer --plan → --dry-run → --apply-proposal over a bare castellan evolve, so you get an inspection point between proposal and archive write.

Honest limits

Failure paths / troubleshooting

Fast-slow co-evolution

Castellan splits fast per-episode RLM remediation from slow topology evolution — two timescales on the same episode corpus, not a monolithic agent chat loop.

[coevolution]
fast_remediation = true
slow_evolve_every = 4
slow_evolve_generations = 2

Demo:

bash docs/demo/fast-slow-coevolution.sh

State is tracked in .castellan/flywheel_state.json; slow evolve emits a slow_evolve event in episode JSON when it runs.

Related

• Evolve round-trip — seeding runs from the archive and writing fitness back
• Organism model — genomes, circulation vitals, and the immune gate in depth
• Stigmergy ablation
• castellan evolve reference

Evolve → run round-trip

What

Loop: episodes → evolve → archive → seed run → write-back fitness.

Why

It’s not enough for castellan evolve to find a better genome once — the round-trip closes so a production run can seed from that genome, and its outcome feeds the archive for the next evolve pass. See Topology evolution and Organism model.

Overview

Castellan closes the loop between topology evolution and production runs in three steps:

1. castellan evolve — mutates harness topology from the episode corpus; writes .castellan/topology_archive.json.
2. castellan run --seed-archive — seeds topology/coordination from the nearest archive entry (matched by plugin + goal environment_fingerprint); logs a genome_id and a genome_seed event in the episode.
3. Write-back — after a successful run, merges the new episode’s fitness into the matching archive entry (matched by genome_id), then re-sorts the archive by success score.

Write-back is enabled automatically whenever --seed-archive is used, or explicitly with --write-back. Pass --no-write-back to disable the automatic path (useful when you want to seed from a known-good genome without letting a noisy or exploratory run pollute its fitness history).

Anatomy: what’s in an archive entry

Each TopologyEntry in .castellan/topology_archive.json carries:

flowchart LR
    EP[episode corpus] --> EV[castellan evolve]
    EV --> ARCH[topology_archive.json]
    ARCH --> SEED[castellan run --seed-archive]
    SEED --> RUN[episode: genome_seed event]
    RUN -->|Satisfied + fitness| WB[write_back_fitness]
    WB --> ARCH

    classDef evolve stroke:#d97706,stroke-width:2px
    classDef runtime stroke:#0969da,stroke-width:2px

    class EP,EV,ARCH,WB evolve
    class SEED,RUN runtime

How operators use it

1. Quick reproduce from a fixture corpus:

EVOLVE_FIX="tests/fixtures/evolve-episodes"
mkdir -p .castellan/episodes
cp "$EVOLVE_FIX"/*.json .castellan/episodes/

castellan evolve --episodes 10 --workspace .castellan/episodes
castellan run --goal "reach target" --plugin gridworld --seed-archive --json

Expect in the resulting episode JSON:

• genome_id — seeded from the nearest archive entry
• fitness — plugin-grounded success score for this run
• events[] containing a genome_seed event, and — when write-back applies — an archive_write_back event

2. Seed from a specific genome instead of “nearest”:

castellan run --goal "reach target" --plugin gridworld --genome <genome_id>

--genome and --seed-archive are mutually exclusive — pick one.

3. Seed without letting the run mutate the archive (e.g. reproducing a past result exactly):

castellan run --goal "reach target" --plugin gridworld --genome <genome_id> --no-write-back

4. Point at a non-default archive path (e.g. testing a candidate archive before promoting it):

castellan run --goal "reach target" --plugin gridworld --seed-archive --archive .castellan/topology_archive.candidate.json

Write-back semantics

• Trigger: GoalStatus::Satisfied and both genome_id and fitness present on the episode — a failed or inconclusive run never writes back.
• Merge: TopologyArchive::write_back_fitness updates the matching entry by id, then re-sorts the archive by success score so future nearest() calls prefer the freshest evidence.
• Archive path: controlled by --archive (default .castellan/topology_archive.json).

JSON events

With --json, archive write-back emits a typed archive_write_back CastellanEvent line, immediately before episode_end. Automation watching the NDJSON stream can key off this event to know the archive changed without re-reading the file.

Recipes

When proving the round-trip works end to end (e.g. for a demo or CI check), use the fixture corpus reproduction above — it’s deterministic and doesn’t depend on a live LLM or long-running episodes.

When you want continuous improvement in a daily-driver loop, always pass --seed-archive on production runs (write-back is then automatic) so every successful run compounds into the next evolve generation.

When comparing “does seeding actually help,” run the same goal once with --seed-archive and once without, then diff fitness in the two episode JSONs — the delta is the seeding effect for that goal/plugin pair.

When you need a stable baseline for regression testing, seed with an explicit --genome <id> and --no-write-back so the archive never drifts between test runs.

Failure paths / troubleshooting

Related

• Topology evolution — how the archive gets populated and gated
• Organism model — genome lineage and the immune gate
• CLI reference
• castellan run reference

Memory architecture

What

Castellan memory is the coordination substrate plus durable episode artifacts — it is not a vector store, not a conversation archive, and not RAG. There is no embedding index in the default path; “recall” means querying structured episode/checkpoint/observation records, and “remember” means persisting a typed observation, not chunking text for similarity search.

Why

Hot field state (blackboard + pheromones) must stay fast and ephemeral; warm episodes must remain replayable for evolve. Lexicon: Conventions.

If you’re deciding whether to enable SQLite, wiring castellan_recall/castellan_remember from an MCP client, or figuring out where a run’s state actually lives on disk, this page is the map.

Anatomy: hot / warm / cold layers

flowchart TB
    subgraph hot["Hot"]
        BB[Blackboard]
        FIELD[PheromoneField]
        SCHED[Scheduler]
    end

    subgraph warm["Warm"]
        EP[episodes]
        TR[traces]
        TA[topology archive]
    end

    RUN[castellan run] --> SCHED
    SCHED --> FIELD
    RUN --> BB
    RUN --> EP
    RUN --> TR
    EVOLVE[castellan evolve] --> EP
    EVOLVE --> TA
    MCP[castellan mcp] --> warm
    REPLAY[castellan replay] --> EP

    classDef runtime stroke:#0969da,stroke-width:2px
    classDef substrate stroke:#5b6b8c,stroke-width:2px
    classDef evolve stroke:#d97706,stroke-width:2px

    class RUN,REPLAY runtime
    class BB,FIELD,SCHED,MCP substrate
    class EVOLVE,EP,TR,TA evolve

On-disk layout

How operators use it

1. Default path — nothing to configure. Every run writes episode JSON automatically:

castellan run --goal "reach target" --plugin gridworld
castellan replay --episode .castellan/episodes/<id>.json
castellan memory status

2. Read live substrate state from an editor/MCP client while a run is active:

3. Switch to the SQLite backend when you want queryable aggregates instead of scanning JSON files. Add to castellan.toml:

[memory]
backend = "sqlite"
path = ".castellan/castellan.db"
mirror_json = true
auto_import = true

mirror_json (default true) keeps writing .castellan/episodes/*.json alongside SQL so tooling that reads plain JSON keeps working. auto_import (default true) imports any existing JSON corpus the first time SQLite opens.

4. Query durable memory from MCP tools once SQLite is enabled:

5. Confirm which backend is active and where the DB lives:

castellan memory status

6. Mid-episode durable checkpoints: persist scheduler state during a run so castellan run --resume survives process loss — not just episode-end snapshots.

[memory]
checkpoint_interval_ticks = 10   # 0 = episode-end only (default, backward-compatible)

Checkpoints land in .castellan/checkpoints/ and SQLite field_history when backend = "sqlite". The engine fires on_checkpoint every N ticks; CLI wires this to MemoryStore::save_checkpoint_json. Integration tests: durable_checkpoint.rs, durable_resume.rs.

Recipes

When you’re prototyping a plugin, stay on the JSON default — episodes are human-readable, diffable, and git-friendly for fixture corpora (see tests/fixtures/evolve-episodes/).

When your episode corpus grows past a few hundred runs and castellan evolve gets slow, switch to backend = "sqlite" so evolve reads SQL aggregates instead of re-parsing every JSON file.

When you need memory to survive across machines (e.g. a shared team archive), configure [memory.sync] with a Turso/libSQL URL and set sync_on_episode_end = true — tokens are referenced by env var name (turso_token_env), never stored inline in castellan.toml. On each castellan run / MCP session open, Castellan pulls newer remote episodes into the local SQLite file; after each episode ends it pushes that episode’s rows when sync_on_episode_end = true.

Check sync health:

castellan doctor --json | jq '.stages[] | select(.name=="memory_sync")'

The memory_sync stage reports reachability, last pull/push timestamps, and the last error (if any). State is stored in .castellan/sync_state.json (no tokens).

When you want a clean corpus for a benchmark run, cp a known-good fixture set into .castellan/episodes/ before castellan evolve rather than hand-editing the live archive.

What never goes in the database

Failure paths / troubleshooting

Engineering detail

Full SQL schema, the MemoryStore trait, and sync policy internals: MEMORY_ARCHITECTURE.md (maintainer spec, not a book page).

See also

• Coordination model — the hot layer this page’s “warm” tier is a snapshot of
• Topology evolution — the primary reader of the warm layer
• castellan.toml reference — full [memory] key list
• MCP tools — castellan_recall, castellan_remember, castellan_query_field_history

RLM loop

In-tree verify/act loop: castellan run --rlm.

Sandbox host (RlmSandboxHost)

Hardened process-isolated code eval ships behind the sandbox feature on castellan-rlm (enabled by default on castellan-cli via rlm-sandbox).

Configure via CASTELLAN_SANDBOX_BACKEND=process|hardened|bubblewrap or [rlm] sandbox_backend in castellan.toml. WASM requires the optional wasm-sandbox feature — not enabled by default.

Hardened process remains the default hot path. WASM ships a minimal echo guest for REPL eval wiring only — not Python parity.

REPL eval path

When an observation includes an rlm_eval block, the RLM loop executes code through the sandbox host before verify:

{
  "rlm_eval": { "code": "print(2 + 2)", "timeout_ms": 5000 },
  "rlm_eval_result": { "stdout": "4\n", "stderr": "", "exit_code": 0 }
}

Wiring:

• castellan-rlm: repl_eval_observation, run_until_satisfied(..., sandbox_host), select_sandbox_host()
• castellan run --rlm: mux RLM path uses select_sandbox_host() (hardened default)

Build / test

cargo test -p castellan-rlm --features sandbox
CASTELLAN_SANDBOX_BACKEND=bubblewrap cargo test -p castellan-rlm --features sandbox
CASTELLAN_SANDBOX_BACKEND=wasm cargo test -p castellan-rlm --features sandbox,wasm-sandbox
cargo test -p castellan-cli rlm

Multiplexer overview

Castellan ships an in-tree PTY multiplexer with a Multiplexer-shaped NDJSON socket API. One binary (castellan) serves daily-driver mux panes — workspaces, tabs, splits, agent detection — without requiring a separate external mux client binary. It is both a terminal manager you can drive by hand (castellan herd attach) and a coordination substrate the scheduler can drive automatically (castellan run --mux).

If you’re setting up a daily-driver pane layout, wiring an editor agent to report its own state, or trying to understand what --mux actually spawns, this page is the map.

Anatomy

castellan herd server  →  castellan-multiplexer (Unix socket)
        │
        ├── workspace / tab / pane tree      (session.snapshot, workspace.*, tab.*, pane.*)
        ├── pane.spawn / pane.attach          (PTY proxy, streaming)
        ├── events.subscribe / events.emit    (NDJSON EventBus — live Castellan events when socket healthy)
        └── pane.report_agent                 (hook protocol — authoritative agent state)

Pane agent status feeds the coordination substrate directly: agent_status observations can carry pheromone_deposits, which boost scheduler wake pressure on the pane zone. See Coordination model for the mechanism.

flowchart LR
    SRV[castellan herd server] --> SOCK[Unix socket]
    SOCK --> PANE[panes]
    PANE --> AGENT[agent_status]
    AGENT --> DEPOSIT[pheromone_deposits]
    DEPOSIT --> FIELD[pane zone]
    FIELD --> SCHED[scheduler wake boost]

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

    class SRV,SOCK,PANE,AGENT runtime
    class DEPOSIT,FIELD,SCHED substrate

How operators use it

1. Start the server (idempotent — spawns a daemon only if none is running):

castellan multiplexer ensure
# or, Multiplexer-shaped:
castellan herd server

Default socket: ~/.config/castellan/castellan.sock (override with CASTELLAN_SOCKET or --socket).

2. Check status — the rich agent dashboard, not just “is it up”:

castellan herd status

3. Attach interactively to a pane:

castellan herd attach                    # focused pane in first workspace
castellan herd attach --pane w1:p1       # specific pane

Detach with Ctrl+Q. Use --takeover if another client already owns input.

4. Let the scheduler drive panes automatically instead of attaching by hand:

castellan run --goal "reach target" --plugin gridworld --mux
castellan swarm-demo   # scripted multi-pane demo, no goal needed

5. Wait for a pane’s agent to go idle before sending it more work (scripting/CI):

castellan herd wait --pane w1:p1 --status idle --timeout-ms 60000

6. Run over SSH when the multiplexer lives on a remote host:

castellan herd remote user@host
# or the lower-level goal runner:
castellan remote --ssh user@host --goal "reach target" --plugin gridworld

Attach modes

Recipes

When you want one shared pane layout across a team or CI matrix, use a named session (--session <name>) so each gets its own socket and persist directory instead of colliding on the default socket.

When an editor agent should report its own state instead of relying on screen-scraping heuristics, wire pane.report_agent from a hook script — see Agent hooks for the exact NDJSON payload and shell wrapper.

When you need to restart the multiplexer without losing your pane layout, use server.live_handoff (via the socket API) rather than killing the process — layout and visible text are preserved, but note PTY processes themselves are not preserved across handoff.

When debugging “why didn’t my mux run pick up pane activity,” confirm the run actually used --mux (in-process host with topology tracking) — without it, pane deposits never reach the scheduler’s field.

When the dashboard last_events stays empty during castellan run, ensure the mux socket is healthy (castellan multiplexer ensure). Healthy sockets receive Castellan events via events.emit; panes still use the in-process host. See Statusline.

Failure paths / troubleshooting

Related

• Socket API — full NDJSON method catalog
• Agent hooks — pane.report_agent and lifecycle reporting
• Coordination model — how pane deposits feed the scheduler
• Daily driver loop
• castellan herd reference

Dashboard

castellan dashboard is the ratatui operator UI over the in-tree multiplexer — agents, pressure, pane topology, and the evolution archive in one view.

What / why

Live stigmergy control tower: field heat from deposits, plan_verify / bio / cost chips, dual-bus honesty — without embedding a PTY grid (Enter still hands off to herd attach). Headless observers use the same ObservabilitySnapshot via castellan statusline refresh or ~/.config/castellan/statusline.json.

Launch

castellan multiplexer ensure
castellan dashboard

Defaults:

Anatomy

The dashboard renders four coordinated views over one DashboardState, refreshed on demand:

Keybindings

Recipes

Daily-driver stack:

castellan multiplexer ensure
castellan dashboard

Point at a named session (multi-project):

castellan herd session list
castellan dashboard --socket ~/.config/castellan/<session>.sock

Headless history (telemetry DB, no TUI):

castellan dashboard --history --limit 20
# same as:
castellan telemetry --limit 20

Headless live snapshot (no ratatui):

castellan statusline refresh --json | jq '{schema_version, bus, live_pressure, plan_verify, bio}'

Read a previously written file:

jq '{schema_version, connected, agents, vitals}' ~/.config/castellan/statusline.json

Headless observability

TUI and statusline refresh write the same ObservabilitySnapshot — schema in Statusline. MCP castellan_multiplexer_status adds freshness (stale, age_secs).

Honest gap: Full multiplexer chrome in the ratatui dashboard is still deferred; the current surface is agents, pressure, and pane tree.

Failure paths

CI smoke

Dashboard client code is tested against a mock Unix socket:

cargo test -p castellan-dashboard --test integration

Included in ./scripts/verify.sh.

Related

• Statusline and observability
• castellan herd
• Multiplexer overview

Governance overview

Castellan ships two independent governance surfaces, and neither one routes decisions through an LLM: governance is deterministic policy plus operator-configured shell hooks.

Canon (cite; don’t redesign): dual-stack diagram in repo docs/GOVERNANCE.md — Tools (PermissionPolicy → plan_verify → hooks → execute) and Evolve (drift → Φ → fitness → immune).

1. Manifest drift-check — castellan drift-check enforces required CI checks, style files, and deprecation notices against a single source of truth (VERIFICATION_MANIFEST). See Governance policies.
2. Runtime governance — permission presets, shell command policy, spend/risk caps, and lifecycle hooks configured in layered castellan.toml. See Agent hooks.

If you’re deciding what an agent is allowed to run, why a tool call got denied, or whether your repo passes CI’s guardrail gate, this page is the starting point — the two linked pages below go deep on each surface.

Anatomy: the two surfaces

flowchart TB
    CFG[castellan.toml layers] --> PERM[permission preset]
    CFG --> SHELL[shell allow/deny lists]
    CFG --> CAP[spend + risk caps]
    CFG --> HOOKS[lifecycle hooks]

    PERM --> PIPE[ToolGovernancePipeline]
    SHELL --> PIPE
    CAP --> PIPE
    HOOKS --> PIPE

    PIPE --> RUN[castellan run / mcp]
    RUN --> AUDIT[audit JSONL]

    MANIFEST[VERIFICATION_MANIFEST] --> DRIFT[castellan drift-check]
    DRIFT --> CI[CI gate]

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

    class PERM,SHELL,CAP,HOOKS,MANIFEST,DRIFT gate
    class PIPE,RUN,AUDIT,CI runtime

Permission presets

[permissions] preset expands into a base policy before any [permissions.tools] overrides apply:

Prompt mode UX

PermissionMode::Prompt is resolved through a host permission prompter seam — not a silent deny.

Prompt decisions always emit observability (PermissionDenied / ToolDecision) — never a silent drop.

How operators use it

1. Check the current runtime governance posture:

castellan doctor --json | jq '.stages[] | select(.name=="governance_manifest")'

2. Run the manifest guardrail check (fast, no network, what CI runs):

castellan drift-check

3. Set a permission preset for daily-driver operation:

castellan config set permissions.preset balanced

4. Override a single tool’s policy without changing the whole preset:

[permissions.tools]
castellan_propose_mutation = "deny"
castellan_deposit_signal = "allow"

5. Cap spend and risk for a session in castellan.toml:

[governance]
session_spend_cap_usd = 12.5
max_risk_score = 0.85
denied_paths = ["/secret", "~/.ssh"]

6. Record every governed decision to an audit trail for a run:

castellan run --goal "reach target" --plugin shell --audit .castellan/audit.jsonl

Recipes

When onboarding a new repo or plugin, start with preset = "cautious" and loosen to balanced once you’ve watched a few runs and trust the shell/tool surface.

When running in CI or a disposable container, use preset = "permissive" but keep [shell] denied_commands non-empty — permissive changes the default, not the explicit denylist.

When you need a paper trail for a specific run (compliance, debugging a bad tool call), always pass --audit <path> — governance decisions aren’t persisted anywhere else by default.

When a PR touches CI, manifest.rs, or lint/toolchain config, run castellan drift-check locally before pushing — the same check gates CI and failures there block merge.

Failure paths / troubleshooting

Related

• Governance policies — CI guardrail manifest, PR requirements, single source of truth
• Agent hooks — castellan.toml lifecycle hooks and multiplexer agent reporting
• castellan.toml reference — full [governance], [shell], [permissions] key lists
• CLI reference
• Cursor setup

Governance policies

Policies that keep Castellan’s codebase and guardrails from drifting apart.

Verification pipeline

.github/workflows/ci.yml
        │
        ├── scripts/drift-guard.sh  →  castellan drift-check (manifest)
        └── scripts/verify.sh       →  fmt, clippy, hack, test, build, smoke

CI must call ./scripts/drift-guard.sh then ./scripts/verify.sh only. Do not add duplicate lint or test steps to the workflow — that creates anti-drift debt.

Single source of truth

When adding a new required check:

1. Add a ManifestCheck entry to manifest.rs.
2. Implement validation in run_drift_check.
3. If the check belongs in the full suite, add it to verify.sh.
4. Note the change in your PR description (required).

PR requirements

PRs that touch any of the following must include a ## Guardrails section in the description explaining what changed and why:

• scripts/verify.sh
• scripts/drift-guard.sh
• .github/workflows/**
• crates/castellan-governance/src/manifest.rs
• rust-toolchain.toml, clippy.toml, rustfmt.toml, deny.toml

PRs that change Rust style conventions must update the engineering guide in the same PR.

Drift-check command

cargo run -p castellan-cli -- drift-check
# or, after install:
castellan drift-check

Exits non-zero when any VERIFICATION_MANIFEST expectation fails. Use locally before pushing when editing guardrail files.

Python deprecation

The python/ tree is deprecated and packages were removed. python/README.md must retain a deprecation notice — drift-check enforces this when the directory exists.

Review expectations

• Guardrail changes: one maintainer approval minimum.
• Manifest changes: confirm castellan drift-check and ./scripts/verify.sh both pass in CI.
• No allow(dead_code) in crate sources without removing the check from manifest (not permitted).

Related

• Agent hooks — multiplexer lifecycle reporting
• CLI reference — castellan drift-check

Agent hooks

Castellan supports two hook surfaces: governance lifecycle hooks (configured in castellan.toml) and multiplexer agent lifecycle reporting (socket API for editor agents).

Governance lifecycle hooks (castellan.toml)

Configure deterministic shell hooks in layered config (castellan.toml, ~/.castellan/config.toml, .castellan/local.toml):

[[hooks.hooks]]
event = "SessionStart"
command = "./scripts/hooks/session-start.sh"

[[hooks.hooks]]
event = "PreToolUse"
command = "./scripts/hooks/pre-tool.sh"

[[hooks.hooks]]
event = "PostToolUse"
command = "./scripts/hooks/post-tool.sh"

[[hooks.hooks]]
event = "SessionEnd"
command = "./scripts/hooks/session-end.sh"

Accepted event / kind values: SessionStart, SessionEnd, PreToolUse, PostToolUse (snake_case aliases also work).

Each command receives a single JSON payload line on stdin:

Invocation paths

Hook commands must exit 0; non-zero exits fail the surrounding operation.

Prove-before-execute ([governance.plan_verify])

Optional Guardians-shaped gate (Meijer / metareflection pattern — not Universalis-the-language). When enabled, high-risk tools (shell / exec by default) require a verified workflow_plan certificate in the tool args envelope before side effects. Missing or failing verification ⇒ deny (fail closed). Composes under PermissionPolicy: Deny still short-circuits; plan verify does not replace Allow / Deny / Prompt.

[governance.plan_verify]
enabled = true
# high_risk_tools = ["shell", "exec"]
# allowlisted_tools = ["shell", "exec", ...]

Supply the plan on shell/MCP args as workflow_plan (or tool_workflow): ordered steps with symbolic refs (no live payloads). Research: docs/superpowers/research/2026-07-13-universalis-agent-proofs.md. Demo: docs/demo/plan-prove-before-execute.sh.

This is tool-plan safety on the PreToolUse path — distinct from evolve drift / Φ / immune gates on topology genomes. When plan verify runs on the MCP tool hot path, outcomes emit PlanVerifyPassed / PlanVerifyDenied on the live EventSink (CLI --json, mux bridge, ACP) so observers see prove-before-execute without reading audit JSONL alone.

Multiplexer agent lifecycle (socket API)

Agents (Claude Code, Codex, Cursor) can report lifecycle state to the multiplexer without relying on screen heuristics.

Socket API

{"id":"1","method":"pane.report_agent","params":{
  "pane_id": "w1:p1",
  "agent": "claude",
  "state": "working",
  "source": "hook"
}}

States: idle, working, blocked, done, unknown.

When source is hook, screen heuristics are ignored until the pane is reset.

Shell hook example

Install into your agent wrapper (~/.config/castellan/hooks/herdr-agent-state.sh — historical script name):

#!/usr/bin/env bash
# Usage: herdr-agent-state.sh <pane_id> <agent> <state>
PANE_ID="${1:?pane_id}"
AGENT="${2:?agent}"
STATE="${3:?state}"
SOCKET="${CASTELLAN_SOCKET:-$HOME/.config/castellan/castellan.sock}"
printf '%s\n' "{\"id\":\"hook\",\"method\":\"pane.report_agent\",\"params\":{\"pane_id\":\"$PANE_ID\",\"agent\":\"$AGENT\",\"state\":\"$STATE\",\"source\":\"hook\"}}" \
  | nc -U "$SOCKET"

Claude / Codex / Cursor integration

CLI wait helper

castellan herd wait --pane w1:p1 --status idle --timeout-ms 60000

Equivalent to events.wait with pane_agent_status_changed.

Environment

Related

• Socket API
• Governance policies
• castellan.toml reference

Plugin architecture

A plugin is a goal environment adapter: it encodes goals into runnable tasks, verifies observations against goals, and scores outcomes for evolution. Plugins are what make Castellan’s coordination and evolution loops generic — the scheduler, substrate, and evolve pipeline never know anything about gridworlds or shell commands specifically; they only know the CastellanPlugin trait.

If you’re integrating a new environment, debugging why fitness looks wrong for your plugin, or deciding between install and link while iterating, this page is the reference.

The trait

#![allow(unused)]
fn main() {
#[async_trait]
pub trait CastellanPlugin: Send + Sync {
    fn name(&self) -> &'static str;
    fn encode_task(&self, goal: &Goal) -> TaskDescriptor;
    async fn verify_goal(&self, goal: &Goal, observation: &serde_json::Value) -> AgentReport;
    fn fitness(&self, goal: &Goal, report: &AgentReport) -> FitnessVector;
    fn tools(&self) -> Vec<ToolSpec> { vec![] }
}
}

Supporting traits, for narrower integrations:

• GoalVerifier — verify-only surface, used by RLM loops (castellan run --rlm) that don’t need the full plugin lifecycle.

Coordination hooks (optional, provided via context at runtime — not part of the trait itself):

• PluginContext — blackboard read/write, budget snapshot.
• CoordinationContext — zone list, perception radius, deposit_signal / read_signal.

Anatomy: lifecycle

flowchart LR
    REG[register] --> ENC[encode_task]
    ENC --> SCHED[scheduler run]
    SCHED --> VER[verify_goal]
    VER --> EP[episode snapshot]
    EP --> EVOLVE[evolve fitness]

    classDef runtime stroke:#0969da,stroke-width:2px
    classDef evolve stroke:#d97706,stroke-width:2px

    class REG,ENC,SCHED,VER runtime
    class EP,EVOLVE evolve

1. Register — PluginRegistry::builtin() loads built-ins plus any manifest plugin.toml on disk.
2. Encode — encode_task(goal) produces the initial TaskDescriptor payload the scheduler dispatches.
3. Run — the scheduler enqueues the task in the plugin’s primary zone; the host executes it; observations flow back into the blackboard/field.
4. Verify — verify_goal returns an AgentReport carrying a NextAction (complete, retry, delegate, or fail).
5. Episode — the runtime writes .castellan/episodes/<goal-id>.json, including the plugin’s fitness() output.
6. Evolve — castellan evolve reads the episode corpus; the plugin name seeds the archive’s environment_fingerprint lookup for future --seed-archive runs.

Current built-in plugins

Plugin manifest (plugin.toml)

name = "gridworld"
description = "Deterministic 5x5 grid navigation simulator"
version = "0.1.0"

[zones]
primary = "grid"
default = ["grid", "goal"]

[blackboard]
slots = ["state", "last_observation"]

Manifests live at crates/castellan-plugins/<name>/plugin.toml. The registry scans that tree at init — you never hand-edit a central registry.rs to add a plugin.

How operators use it

1. List what’s registered:

castellan plugin list

2. Inspect a plugin’s manifest, zones, and blackboard schema:

castellan plugin info gridworld

3. Scaffold a new plugin from the template:

castellan plugin new myplugin
castellan plugin list
castellan run --goal "your goal" --plugin myplugin

4. Iterate on a plugin without a full reinstall — symlink instead of copy:

castellan plugin link --from ~/src/my-plugin
cargo build --release -p castellan-cli   # rebuild to register
# edit ~/src/my-plugin/src/lib.rs, rebuild — no re-link needed

5. Install a plugin from git (for sharing/distribution):

castellan plugin install --git https://github.com/example/castellan-gridworld-extra.git
cargo build --release -p castellan-cli   # rebuild to register

6. Uninstall:

castellan plugin uninstall myplugin

install deletes the copied source tree; link only removes the symlink and leaves your source directory intact.

Link vs install

castellan plugin list reports "source": "builtin" | "install" | "link" per plugin so you can tell at a glance how each one got there.

Extension points

Recipes

When building a new environment adapter, start from castellan plugin new myplugin rather than hand-rolling the manifest — the template wires up [zones]/[blackboard] correctly and registers automatically on rebuild.

When your plugin’s fitness always comes back flat, check fitness(goal, report) against the actual AgentReport.next_action values you’re returning from verify_goal — a fitness function that ignores NextAction variants will look identical across very different outcomes.

When two plugins need to share coordination state, give them overlapping default zones deliberately in each plugin.toml, but keep primary zones distinct so scheduling doesn’t collide.

When distributing a plugin to teammates, publish it as a git repo and have them castellan plugin install --git <url> rather than sharing a local path — link is a dev-loop convenience, not a distribution mechanism.

Failure paths / troubleshooting

Related

• Coordination model — zones, blackboard, and how plugin deposits reach the scheduler
• Topology evolution — how plugin fitness feeds mutation gating
• castellan plugin reference
• CLI reference

CLI overview

Castellan is a single binary (castellan) with subcommands for goal runs, evolution, multiplexer control, MCP, and diagnostics.

Precedence

Configuration resolves in this order (highest wins):

1. CLI flags — e.g. --goal, --plugin, --json
2. Environment variables — e.g. CASTELLAN_MUX_AUTO, CASTELLAN_SESSION_SPEND_CAP_USD
3. Layered config files — see castellan.toml

Output modes

One runnable recipe per mode:

# text — human terminal
castellan run --goal "reach target" --plugin gridworld

# json — typed NDJSON events for CI (episode JSON also lands in .castellan/episodes/)
castellan run --goal "reach target" --plugin gridworld --json | grep episode_end

# mcp — stdio JSON-RPC (tools/list handshake)
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}\n' | castellan mcp

# socket — multiplexer NDJSON API
castellan multiplexer server &
castellan multiplexer status

# acp — agent client protocol over stdio
castellan acp doctor

Episode JSON is always written to .castellan/episodes/<goal-id>.json on successful runs (separate from --json stdout).

Top-level commands

Other commands: multiplexer, acp, skills, episodes, recipes, drift-check, memory, integration, vitals, genome, dashboard, completions, ipc (deprecated). Run castellan <cmd> --help for flags. Recipes are defined in castellan.toml [[recipes]].

Shell completions

Completions are generated from live clap metadata so they stay in sync with the CLI:

castellan completions bash   # bash completion script
castellan completions zsh    # zsh completion script
castellan completions fish   # fish completion script

Install examples:

# bash (user-local)
mkdir -p ~/.local/share/bash-completion/completions
castellan completions bash > ~/.local/share/bash-completion/completions/castellan

# zsh
castellan completions zsh > "${fpath[1]}/_castellan"

# fish
mkdir -p ~/.config/fish/completions
castellan completions fish > ~/.config/fish/completions/castellan.fish

Re-run after upgrading castellan when subcommands or flags change.

Help snapshots

CLI help is snapshot-tested in CI. After intentional CLI changes:

UPDATE_SNAPSHOTS=1 cargo test -p castellan-cli cli_help_snapshot

See Deployment.

Recipes

castellan run

Scheduler-led goal loop with a plugin verifier. Writes episode JSON to .castellan/episodes/<goal-id>.json.

Usage

castellan run --goal <GOAL> [--plugin gridworld] [--resume [<GOAL_ID>]]
          [--rlm] [--max-steps 8]
          [--audit <PATH>] [--json] [--mcp] [--model <URL_OR_NAME>]
          [--genome <ID>] [--seed-archive] [--archive .castellan/topology_archive.json]
          [--write-back] [--no-write-back] [--mux] [--no-mux]

When resuming, --goal is optional (defaults to checkpoint description). Plugin comes from the checkpoint.

Key flags

--mux runs via MuxHarnessHost; episode JSON includes pane_tree. Mux is the default when the multiplexer socket is healthy — no CASTELLAN_MUX_AUTO=1 required. Rollback with --no-mux, CASTELLAN_MUX_AUTO=0, or CASTELLAN_MUX_DISABLE=1.

--json events

See statusline for dashboard consumption.

Recipes

Gridworld smoke (verify.sh default):

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

RLM verify/act:

castellan run --goal "reach target" --plugin gridworld --rlm --max-steps 4

Resume mid-goal:

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

Mux topology in episode:

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

Evolve round-trip:

castellan evolve --episodes 5 --workspace .castellan/episodes
castellan run --goal "reach target" --plugin gridworld --seed-archive --write-back

Related

• CLI overview
• Evolve
• MCP tools
• Daily driver

castellan evolve

Evolve harness topology from episode logs. Optional reflective Python hook; drift gate rejects incompatible mutations.

Usage

castellan evolve [--episodes 10] [--workspace .castellan/episodes] [--hook rust|seed-only] [--summarize]
castellan evolve --plan
castellan evolve --dry-run
castellan evolve --apply-proposal <UUID>

Key flags

--summarize compacts the corpus for the proposer (DRY with substrate heatmap). Drift-incompatible candidates are rejected and logged.

Plan vs dry-run vs apply

Use --plan for a pre-mutation analysis turn (incumbent, proposed coordination, pressure summary, drift preview, fitness estimate), then --dry-run + --apply-proposal (or the MCP castellan_propose_mutation / castellan_resolve_mutation pair) for the gated two-phase apply.

Recipes

Standard evolve from local episodes:

castellan run --goal "reach target" --plugin gridworld
castellan evolve --episodes 10 --workspace .castellan/episodes

Summarize only (no mutation):

castellan evolve --summarize --workspace .castellan/episodes

Seed archive then run:

castellan evolve --episodes 10
castellan run --goal "reach target" --plugin gridworld --seed-archive

Related

• Evolution concepts
• Evolve round-trip
• castellan run

castellan herd

Multiplexer UX over the in-tree PTY server — attach, status, and pane operations without raw socket JSON. The subcommand name is historical; in prose this is mux / pane control, not an animal metaphor. Verified against HerdCommands in crates/castellan-cli/src/main.rs.

Usage

castellan herd <SUBCOMMAND>

Subcommands

Run castellan herd <subcommand> --help for the current flag list — this table tracks main.rs at time of writing.

Recipes

Check multiplexer health:

castellan herd status

Attach to a running agent by name:

castellan herd agent attach claude

Explain why an agent looks stuck:

castellan herd agent explain --pane w1:p1 --verbose

Wait for an agent to go idle (scripting):

castellan herd wait --pane w1:p1 --status idle --timeout-ms 60000

Named sessions (multi-project):

castellan herd session list --json
castellan herd session attach my-project
castellan herd session stop my-project

Read-only pane observation (headless monitor):

castellan herd terminal observe --pane w1:p1 --cols 100 --rows 30

Remote mux panes over SSH:

castellan herd remote user@host --session my-project

Daily-driver stack:

castellan multiplexer ensure
castellan herd status
castellan dashboard

Failure paths

Related

• Multiplexer overview
• Socket API
• Dashboard
• Daily driver

castellan remote

Attach to the in-tree multiplexer and run a governed goal on remote panes.

Usage

castellan remote --goal <GOAL> [--plugin gridworld] [--socket <PATH>]
             [--ssh user@host] [--stub] [--audit <PATH>]

Key flags

Governance pipeline (with_governance) applies on the remote hot path.

Recipes

Local stub smoke (verify.sh):

castellan remote --stub --goal "reach target" --plugin gridworld

Remote with audit trail:

castellan remote --goal "refactor auth module" --plugin shell --audit .castellan/audit.jsonl

Related

• CLI overview
• Socket API
• Governance policies

castellan plugin

List, inspect, scaffold, install, link, and uninstall dynamic plugins.

Usage

castellan plugin list
castellan plugin info <NAME>
castellan plugin new <NAME>
castellan plugin install --from <DIR>
castellan plugin install --git <URL> [--name <NAME>]
castellan plugin link --from <DIR> [--name <NAME>]
castellan plugin uninstall <NAME>

Installed plugins register via plugins.toml and build.rs — no hand-editing registry.rs.

Link vs install

castellan plugin list reports "source": "builtin" | "install" | "link" per plugin.

Recipes

List registered plugins:

castellan plugin list

Install from local directory:

castellan plugin install --from ./my-plugin
cargo build --release -p castellan-cli   # rebuild to register

Iterate on a plugin without reinstall:

castellan plugin link --from ~/src/my-plugin
cargo build --release -p castellan-cli   # rebuild to register
# edit ~/src/my-plugin/src/lib.rs, rebuild — no re-link needed
castellan plugin uninstall my-plugin     # removes only the symlink

Install from git:

castellan plugin install --git https://github.com/example/castellan-gridworld-extra.git

Uninstall:

castellan plugin uninstall sample-plugin

Related

• Plugin architecture
• castellan run

castellan mcp

MCP stdio JSON-RPC server exposing stigmergy, memory, and harness tools from the shared registry (12 operational tools + 3 meta tools — see MCP tools reference).

Usage

castellan mcp [--attach <goal_id|auto>]

Methods: initialize, tools/list, tools/call. Same registry as castellan run --mcp live episodes — no drift between editor and headless behavior.

Attach mode (live field instrument)

--attach binds the stdio server to a running castellan run --mcp goal via the .castellan/live/ session manifest:

• --attach auto binds to the current live session; --attach <goal_id> requires that exact goal to be live.
• Fails loudly (attach failed: no live session) when nothing is running — no silent standalone fallback.
• Deposits and snapshots route into the live field with source: "mcp_attach" provenance, which lands in the episode’s instrument_summary.
• Mutation tools (castellan_propose_mutation, castellan_resolve_mutation) are denied in attach mode; attached clients are instruments, not operators.
• If the session ends mid-attach, live tools return an attach_lost error.

castellan run --goal "demo" --mcp &   # session A: live engine
castellan mcp --attach auto           # session B: attached instrument

castellan doctor reports the live session state in its live_session stage.

Error responses

castellan_search_tools queries are capped at 256 characters.

Recipes

List tools (stdio):

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | castellan mcp

Discovery flow:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"castellan_search_tools","arguments":{"query":"deposit"}}}' \
  | castellan mcp

Describe before invoking (avoid -32602):

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"castellan_describe_tool","arguments":{"name":"castellan_deposit_signal"}}}' | castellan mcp

Wire Cursor: see Cursor setup.

Related

• MCP tools reference
• MCP overview
• Agent guide

castellan telemetry

Query dashboard telemetry database — sessions, agent transitions, vitals snapshots, and per-tick cost rollups — without a TTY.

Usage

castellan telemetry [--limit 20] [--db <PATH>]
castellan dashboard --history [--limit 20]

Default DB: ~/.config/castellan/telemetry.db.

Key flags

Summary JSON includes cost_rollup_count, session_cost_usd, session_tokens, and recent_costs (from governance cost_rollup wire events recorded while the dashboard is open).

Recipes

Headless session list:

castellan telemetry --limit 5

Dashboard history JSON:

castellan dashboard --history --limit 10

Related

• Dashboard
• Statusline & observability

castellan doctor

Staged runtime diagnostics: multiplexer, governance, config layers, LLM provider, plugins, evolve archive, latest episode vitals. Verified against DoctorReport::run in crates/castellan-cli/src/doctor_cmd.rs — 12 stages, always run in this order.

Usage

castellan doctor [--workspace .] [--json]

--json does not change exit behavior — doctor always exits non-zero if any stage’s pass is false. Not every stage can fail: config/preset stages (permissions_preset, plan_verify, model_tiers, mux_default) always report informational detail with pass: true. llm_provider fails when provider = "openrouter" and no API key env is set. memory_sync fails when sync is configured without a token env. Only multiplexer_socket, governance_manifest, live_session, plugin_registry, evolve_archive, and episode_vitals can fail for other reasons.

Stages

Order matches DoctorReport::run in doctor_cmd.rs:

Recipes

Local workspace check:

castellan doctor --workspace .

CI-friendly JSON:

castellan doctor --json | jq '.stages[] | select(.pass == false)'

Human table (default):

STAGE                  STATUS DETAIL
------------------------------------------------------------------------
multiplexer_socket      PASS  socket present at /Users/you/.config/castellan/castellan.sock
mux_default             PASS  mux default on (socket_healthy=true); rollback: --no-mux, ...
governance_manifest     PASS  verification manifest OK
...

Failure paths

Related

• Verify guide
• Troubleshooting
• castellan drift-check
• castellan.toml [models]

castellan replay

Replay a saved episode JSON or audit JSONL file. --continue-run resumes from checkpoint when supported.

Usage

castellan replay <PATH> [--continue-run]

Recipes

Inspect last episode:

castellan replay .castellan/episodes/latest.json

Replay audit trail:

castellan replay .castellan/audit.jsonl

Related

• Evolve round-trip
• castellan run

Demo commands

Scheduler and RAH demos for verify.sh and local exploration.

castellan swarm-demo

Multi-pane scheduler-led coordination demo (swarm-demo is the CLI name).

castellan swarm-demo

Expects output with pane_count, mux_host, and sub_harness_depth (verify.sh smoke).

castellan rah-demo

Depth-3 RAH pane spawn demo — multiplexer + topology binding.

castellan rah-demo

Expects "pane_tree_depth": 3 and "episode_pane_tree": true.

Recipe: demo → evolve flywheel

castellan run --goal "reach target" --plugin gridworld --mux > .castellan/episodes/mux-run.json
castellan evolve --episodes 3 --workspace .castellan/episodes

Related

• Coordination model
• Multiplexer overview

CLI reference

Single binary: castellan. Paths and config use .castellan/ and castellan.toml. MCP tools are named castellan_*.

Start here: CLI overview

Also: multiplexer, dashboard, statusline, drift-check, acp, skills, episodes, recipes, config, memory, vitals, genome, completions. Run castellan <cmd> --help for flags.

Help snapshots: UPDATE_SNAPSHOTS=1 cargo test -p castellan-cli cli_help_snapshot

castellan.toml reference

Layered configuration for governance, shell policy, hooks, and MCP permissions. Schema source: crates/castellan-governance/src/config.rs.

File locations (merge order)

Later layers override earlier ones. CLI flags and environment variables override all files.

Example

[governance]
session_spend_cap_usd = 12.5
max_risk_score = 0.85
denied_paths = ["/secret", "~/.ssh"]

[shell]
allowed_commands = ["echo", "cargo", "git"]
denied_commands = ["rm", "curl"]
denied_patterns = ["sudo .*"]
max_output_bytes = 65536

[permissions]
default_mode = "ask"
[permissions.tools]
castellan_propose_mutation = "deny"
castellan_deposit_signal = "allow"

[[hooks.hooks]]
event = "PreToolUse"
command = "./scripts/hooks/pre-tool.sh"

Sections

[memory]

See Memory architecture.

[governance]

[governance.plan_verify]

See Agent hooks — prove-before-execute.

[shell]

[permissions]

Permission modes filter tools/list before exposure to MCP clients. castellan doctor reports the active preset.

[coevolution]

Fast-slow co-evolution flywheel. See Evolution.

[models]

Per-role tiers resolve through one OpenAI-compatible client factory (scheduler never routes through an LLM). Auth is env-only — never put API keys in TOML:

[models]
provider = "openrouter"
default = "openai/gpt-4o-mini"
verify = "anthropic/claude-sonnet-4"
act = "openai/gpt-4o"
# optional overrides:
# base_url = "https://openrouter.ai/api/v1"
# http_referer = "https://github.com/Alphabetsoup16/Flock"
# x_title = "Castellan"

--model / --model-tier on castellan run still override; rebuild CLI with --features llm-http for live HTTP providers.

[[recipes]]

Recipes inherit [shell] denied_commands / denied_patterns — they are not a policy bypass. Later config layers override recipes by name.

[[recipes]]
name = "gridworld-smoke"
description = "Run gridworld reach-target and write an episode JSON"
command = "castellan run --goal 'reach target' --plugin gridworld --json"

[[hooks.hooks]]

See Agent hooks.

Environment overrides

Full list: Environment variables.

Related

• Governance policies
• CLI overview

MCP tools

Castellan exposes a progressive-disclosure MCP surface: meta-tools for discovery, compact listings in tools/list, and full schemas on demand via castellan_describe_tool.

Registry: crates/castellan-mcp/src/registry.rs
Stdio server: castellan mcp
Live episodes: castellan run --mcp → CastellanEngine::call_mcp_tool
External instrument: While any scheduler run is active, castellan mcp stdio clients can deposit into the live field via .castellan/live/ (no multiplexer join required). castellan_topology_snapshot returns the published tick + topology from the active session when present.

Live-run instrument

When castellan run is active, the engine publishes a session snapshot under .castellan/live/ each scheduler tick. External MCP clients (Cursor, scripts, another agent) call castellan_deposit_signal through castellan mcp stdio — deposits append to a JSONL queue and are drained into the live PheromoneField on the next tick. Episode JSON records external_mcp_deposit events.

# Terminal A — active run
castellan run --plugin gridworld --goal "reach target"

# Terminal B — external deposit (routes to live session when active.json exists)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"castellan_deposit_signal","arguments":{"zone":"grid","signal":"coordination","amount":5.0}}}' | castellan mcp

# Topology reflects live tick state
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"castellan_topology_snapshot","arguments":{}}}' | castellan mcp

Demo: bash docs/demo/mcp-live-instrument.sh

Discovery flow

flowchart LR
    A[Agent starts] --> B[discover / search tools]
    B --> C[describe_tool]
    C --> D[Invoke tool]
    D --> E[Governance + trace]

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

    class A,B runtime
    class C,D substrate
    class E gate

1. Discover — castellan_discover_tools returns domain-indexed tool cards (no full schemas).
2. Search — castellan_search_tools with query (and optional domain) narrows by intent. Results are BM25-ranked over tool name, summary, description, and domain; when no whole term matches (partial words), substring matching kicks in. The response reports which via "ranking": "bm25" | "substring".
3. Describe — castellan_describe_tool with name returns full schema, preconditions, side effects, examples.
4. Invoke — tools/call or live mcp_tools observation payload.

Meta-tools are always listed with full schemas. Operational tools in tools/list use compact cards (call castellan_describe_tool for parameters).

Error responses

Discovery tools return "ok": false with stable error codes. Stdio server maps to JSON-RPC -32601 (not found) / -32602 (invalid params). Search queries are capped at 256 characters.

Meta tools

Operational tools

All operational tools are in LIVE_TOOL_NAMES for castellan run --mcp.

Start the server

castellan mcp

Wire your MCP client to stdin/stdout JSON-RPC. Cursor config example in Cursor setup.

Example: discovery sequence

{"name": "castellan_search_tools", "arguments": {"query": "deposit", "domain": "substrate"}}

{"name": "castellan_describe_tool", "arguments": {"name": "castellan_deposit_signal"}}

{"name": "castellan_deposit_signal", "arguments": {"zone": "grid", "signal": "coordination", "amount": 2.0}}

Example: live episode

Observation payload for castellan run --goal "..." --plugin gridworld --mcp:

{
  "mcp_tools": [
    {
      "tool": "castellan_deposit_signal",
      "args": { "zone": "grid", "signal": "coordination", "amount": 2.0 }
    }
  ]
}

Trace JSONL emits mcp_discovery for meta-tools and mcp_tool for operational calls. Governance pre/post hooks apply on the hot path.

Design principles

Adding a tool

1. Add ToolSpec in registry.rs and register in all_tool_specs().
2. Add handler in handlers.rs and route in call_tool_with_registry.
3. Add name to LIVE_TOOL_NAMES if live episodes should expose it.
4. Update this page and run cargo test -p castellan-runtime.

See also MCP overview and Agent guide.

Socket API

Castellan exposes a newline-delimited JSON (NDJSON) API over a Unix domain socket. The in-tree castellan-multiplexer server implements Castellan mux automation; castellan-herdr is the NDJSON client crate (historical name).

Source: crates/castellan-multiplexer/src/api.rs · no external mux binary required

Connect

Ensure the server is running:

castellan multiplexer ensure
# or
castellan herd server

Example request:

{"id": 1, "method": "ping", "params": {}}

Example response:

{"id": 1, "result": {"type": "pong", "version": "...", "protocol": "..."}}

Errors use {"id": ..., "error": {"code": "...", "message": "..."}}.

Method catalog

Methods marked Stream return an initial result then additional NDJSON event lines on the same connection.

CLI mapping

Agent detection

Screen heuristics detect Claude, Codex, and Cursor agent states (idle / working / blocked). Hooks via pane.report_agent provide authoritative state when integrations are installed.

Live handoff

server.live_handoff writes ~/.config/castellan/sessions/handoff.json, spawns a replacement daemon, and releases the socket. PTY processes are not preserved across handoff — layout and visible text restore only.

Testing

cargo test -p castellan-multiplexer
cargo test -p castellan-herdr
castellan multiplexer ensure
castellan herd status

See Daily driver loop for the operator workflow.

Environment variables

OpenRouter

export OPENROUTER_API_KEY=sk-or-...
# castellan.toml:
# [models]
# provider = "openrouter"
# default = "openai/gpt-4o-mini"
cargo run -p castellan-cli --features llm-http -- doctor
cargo test -p castellan-runtime --features llm-http openrouter_chat_completions_smoke -- --ignored

castellan doctor stage llm_provider reports key_present and TCP reachability — never the key value.

Upstream meeting-sched acceptance (Bet 1)

Optional LLM repro on the upstream meeting-sched fixture (govcraft_acceptance crate — historical name):

export OLLAMA_URL=http://127.0.0.1:11434
cargo test -p govcraft_acceptance --test llm_integration -- --ignored
cargo run -q -p govcraft_acceptance -- --upstream-repro

Without OLLAMA_URL, --upstream-repro emits deterministic baselines and an honest gap table (not the published 48.5% LLM band).

Session / remote

Hooks

See agent hooks for CASTELLAN_SOCKET in shell hook scripts.

Related

• castellan.toml — [models] provider seam
• CLI reference
• Multiplexer overview
• Stigmergy ablation

Engineering guide

Rust conventions for Castellan contributors. Guardrail enforcement lives in governance policies.

Toolchain

• Pin via rust-toolchain.toml
• Format: cargo fmt --all
• Lint: cargo clippy --workspace --all-targets -- -D warnings

Verification

./scripts/verify.sh --fast
./scripts/verify.sh
castellan drift-check

Details: Verify before PR. Operators who only run Castellan day-to-day should follow Daily driver instead — that path uses castellan drift-check, not ./scripts/verify.sh.

Shared Cargo target (worktrees)

Optional helper for multiple worktrees:

source scripts/dev-env.sh   # exports CARGO_TARGET_DIR to a shared directory

verify.sh defaults to $ROOT/target for isolation unless CARGO_TARGET_DIR is already set.

Crate boundaries

Docs

• Published book (book/src/) is canonical for operators — castellan-docs.pages.dev
• docs/ holds engineering specs; see docs/INDEX.md
• Do not link raw GitHub docs/ blobs from book pages — use relative book links

Agent workflows

Related

• Deployment
• Doc style

Verify before PR

Contributor gate for Castellan development. Operators running agents day-to-day should use Daily driver (castellan drift-check) instead of this script.

The single verification entry point is ./scripts/verify.sh:

Full tier always retains moat proofs: ablation decay, Φ/convergence gate, mid-run topology drain, Guardians plan_verify. Long orchestration demos (rah/swarm/mux flywheel, field/pane demos) are full-only.

./scripts/verify.sh --fast    # while coding
./scripts/verify.sh           # before PR
castellan drift-check

CI runs the full script on every PR (.github/workflows/ci.yml). Shared CARGO_TARGET_DIR across worktrees: optional source scripts/dev-env.sh (see engineering).

Documentation style

Guidelines for Castellan book pages.

Voice

• Honest scope — say what Castellan is not early
• Operator-first — copy-paste commands that produce visible artifacts
• No placeholder social proof
• Lexicon: organism + coordination field (genome, vitals, immune, stigmergy, pressure, blackboard, mux panes, dashboard). No animal pack metaphors (herd/flock/rookery) and no feudal/military castle-staff metaphors in body copy. Canonical table: Conventions.
• CLI names: keep castellan herd / swarm-demo as commands; describe them as mux UX / multi-pane demos in prose
• Peer names: no “like X / parity with Y” framing on operator pages; landscape peers stay in Frontier + COMPETITIVE_MATRIX / VENDOR
• Structure: What → Why → How → Failure paths → Next; cross-link instead of repeating essays

Formatting

• One H1 per page (mdbook enforces)
• Use > **Note** / > **Warning** admonitions
• Mermaid diagrams: use classDef + semantic classes (runtime, substrate, evolve, gate) — see Design system
• No inline style fill:#... (breaks dark mode)
• Max 3 columns in comparison tables

Links

• Relative book links only — never link to raw GitHub docs/ blobs from book pages
• Cross-link concepts ↔ reference ↔ integrations

Brand tokens

Hero line (keep in sync with DESIGN.md): Pressure wakes agents — multiplexer, dashboard, and episode flywheel in one binary.

See Design system for the full token reference, typography scale, layout, components, and Mermaid rules.

Quick palette (defined in book/theme/css/custom.css):

• --castellan-coordination — teal links and active nav
• --castellan-evolve — amber evolution accents
• --castellan-runtime / --castellan-substrate / --castellan-gate — diagram roles

Harness capability docs

• Single source: docs/harness-manifest.toml drives docs/HARNESS_FEATURES.md and the landscape table in docs/COMPETITIVE_MATRIX.md.
• Update workflow: edit the manifest, then cargo run -p harness-docs -- generate.
• CI: ./scripts/check-harness-doc-parity.sh (via verify.sh smoke-docs) fails on drift.

Related

• Engineering guide
• Deployment

Deployment

Audience: maintainers publishing docs and configuring CI.

Documentation site (mdbook → Cloudflare Pages)

Castellan docs are built with mdbook from book/ and deployed on every push to main that touches book/, docs/, or .github/workflows/docs.yml.

Local build

./scripts/build-docs-site.sh   # canonical — installs mdbook, mermaid, llms.txt, sitemap
# or manually:
cargo install mdbook mdbook-mermaid --locked   # once
mdbook build book
open book/book/index.html

Live preview:

mdbook serve book --open

./scripts/verify.sh runs scripts/smoke-docs.sh, which includes mdbook build book.

CLI help snapshots

When CLI flags or subcommands change intentionally:

UPDATE_SNAPSHOTS=1 cargo test -p castellan-cli cli_help_snapshot

verify.sh runs cli_help_snapshot tests (BL-014). MCP tool names must appear in MCP tools — enforced by scripts/check-mcp-doc-parity.sh (BL-015).

CI workflow

Workflow: .github/workflows/docs.yml

1. Install Rust toolchain and mdbook
2. ./scripts/build-docs-site.sh → output in book/book/
3. cloudflare/wrangler-action uploads book/book/ to Pages project castellan-docs

Model A (canonical): GitHub Actions direct upload — not Cloudflare Git integration. Keep CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID in GitHub secrets.

gh workflow run docs.yml   # manual deploy

Cloudflare Workers Builds (dashboard)

Production health = GitHub Actions → Deploy Docs, not the Cloudflare Workers Builds list. If the dashboard is red with “build token … deleted or rolled” while https://castellan-docs.pages.dev returns 200 and Deploy Docs is green, production is fine — disconnect Model B.

Automated in-repo: scripts/build-docs-site.sh, .github/workflows/docs.yml (Model A), .github/workflows/cf-builds-disconnect.yml (silence Model B). Root wrangler.toml is optional local assets config — it must not be paired with a connected Git repo in the dashboard.

Operator checklist:

1. Confirm CLOUDFLARE_API_TOKEN has Account → Cloudflare Pages → Edit (Model A)
2. Confirm CLOUDFLARE_ACCOUNT_ID is the 32-char account ID (sidebar), not a zone ID
3. Disconnect Workers Builds Git so only docs.yml deploys (workflow above, or dashboard Disconnect)
4. Re-create the GitHub API token if docs.yml deploy returns HTTP 403 — do not confuse that with the dashboard build token

Required GitHub secrets

Troubleshooting

Application / CLI releases

The Castellan CLI is not yet published to crates.io (API still moving). Install from source:

cargo install --path crates/castellan-cli --locked

Semver tags and CI

MSRV: rust-version = "1.75" in root Cargo.toml. Release workflow pins toolchain 1.75.

Changelog: CHANGELOG.md (Keep a Changelog format).

CI runs ./scripts/verify.sh on every PR and push to main.

Related

• Verify guide
• Governance policies

Conventions

One page freezes the vocabulary. If a term isn’t here, it’s defined where it’s used.

Canonical lexicon

Castellan docs use two metaphor families — organism (biology of a harness) and field (coordination through the environment). Product name Castellan and Castle Holdings branding stay. Body copy does not lean on animal packs or feudal/military castle staff.

Command names vs prose

castellan herd and castellan swarm-demo remain CLI subcommand names (historical product surface). In prose, describe what they do — multiplexer UX, multi-pane demo — without animal metaphor. Prefer saying “mux status” / “pane status” next to the literal command:

castellan herd status   # pane / mux status (subcommand name is historical)

Crate names (castellan-herdr) and hook scripts (herdr-agent-state.sh) stay as identifiers. Peer product names do not appear in operator prose — see Doc style.

Brand vs body copy

Names and paths

Note: Paths above are defaults. Named multiplexer sessions (--session) scope their own socket and persist directory — see Multiplexer overview.

Glossary

Page structure (Q&A order)

Prefer this order on concept and operate pages so readers get answers without hunting:

1. What — one-sentence definition
2. Why — the bet / what it replaces
3. How — commands and mechanism
4. Failure paths — symptom → cause → fix
5. Next — cross-links, not a second essay

Cut redundancy: link Daily driver / Coordination model / Organism model instead of repeating them.

Command surface at a glance

Related

• Daily driver
• What Castellan is / is not
• Doc style
• castellan.toml
• MCP tools
• Socket API

Frontier positioning

Thesis: Castellan owns stigmergic runtime coordination, verified harness recursion (RAH), and episode-grounded topology evolution — not meta-harness wrapping or workflow DSLs.

What Castellan owns

What Castellan is not competing on

Use Castellan when coordination geometry must evolve from episode logs — not when you need a drop-in single-agent coding product. Scope detail: What Castellan is / is not.

Maintainer landscape (peer names quarantined here and in docs/COMPETITIVE_MATRIX.md / docs/FRONTIER_POSITIONING.md — not sprinkled through concept pages).

Related

• What Castellan is / is not
• Stigmergy ablation

Stigmergy ablation

Method: In-tree honest proxies + upstream meeting-sched fixture. LLM repro optional via OLLAMA_URL.

Summary

Honest gap table (Bet 1)

Decay ablation: Sequential within-round booking used to mask decay (always filled all 5 slots). Fixed with parallel picks + conflict resolution: decay off collapses to one slot (~8%); decay on spreads (~42%). cargo run -q -p govcraft_acceptance -- --ablation validates ≥5% gap.

Upstream fixture

cargo run -q -p govcraft_acceptance -- --mode upstream_meeting_sched
cargo run -q -p govcraft_acceptance -- --upstream-repro

Fixture: ScheduleGeneratorConfig::easy(), seed 4242, at benches/govcraft_acceptance/fixtures/upstream_easy_seed4242.json.

Honest labeling

• In-tree proxy: benches/govcraft_acceptance and benches/stigmergy_ablation use Castellan PheromoneField + scheduler semantics.
• Upstream fixture: rooms, attendees, duration slots, overlap predicate (distinct from slot proxy).
• Not reproduced (LLM): 48.5% vs 12.6% unless --upstream-repro with OLLAMA_URL measures in-band rates.
• CI: Slot proxy + ablation in ./scripts/verify.sh; upstream mode opt-in.

Provenance

Upstream meeting-sched task shape and published LLM band cite pressure-field-experiment. Crate/binary names (govcraft_acceptance, GOVCRAFT_*) are historical identifiers.

Reproduce

cargo run -q -p stigmergy_ablation
cargo run -q -p govcraft_acceptance
cargo run -q -p govcraft_acceptance -- --mode upstream_meeting_sched
bash docs/demo/run-ablation.sh
./scripts/verify.sh

Related

• Coordination model
• Topology evolution
• Environment variables