Room orchestrator

buddies orchestrator explicitly starts one persistent coordinator for a room. Running the ordinary buddies service still starts no model. The coordinator owns the goal and assignment graph; specialists retain their own Codex conversations and write in separate git worktrees.

Start the HTTP service, then run against a clean, committed repository:

BUDDIES_TRANSPORT=http buddies

buddies orchestrator --room project --repo /path/to/repo \
  --model YOUR_MODEL --goal 'Implement and verify the producer/consumer contract' \
  --allow-path src/producer --allow-path src/consumer \
  --check 'cargo test --locked' --max-active-specialists 2

--model is optional and otherwise uses Codex's configured model. Codex must be installed and signed in; --codex-bin can select its real executable. --url selects the shared HTTP service. Paths are explicit repository-relative files or directories, without globs, . or parent components. Repeat --allow-path and --check for additional paths and shared checks.

The stable participants are orchestrator, specialist-a, and specialist-b. The model may create additional named specialists only for independent responsibilities, with at most 16 registered roles. The service rejects live duplicate names. All participants use addressed inboxes on the same HTTP service; this command does not replicate assignments across P2P nodes.

Assignment protocol

The dynamic orchestrator_control tool proposes state transitions. The scheduler validates actor identity, ownership, dependencies and revisions before accepting them. The coordinator can assign, revise, cancel, recover, inspect and complete. Specialists can accept, checkpoint, report, fail and heartbeat their own assignments. inspect is available to every role.

Each assignment stores an ID, owner, revision, owned paths, dependencies, deadline, acceptance, worktree, baseline and result evidence. Dependencies must already exist, so the graph remains acyclic. Shared paths have one explicit owner. Reuse that assignment through revisions when its contract changes.

The states are queued, running, waiting_for_input, completed, failed and cancelled. A report does not complete an assignment: the runtime waits for the turn to finish, checks all changed paths, runs its reported acceptance checks and integrates the patch. Only verified completion releases dependencies. handled inbox receipts still mean that a message was processed.

Specialists must accept each revision before reporting its result. Results from older revisions remain unverified evidence. Revising a producer also increments and invalidates its dependent assignments; unrelated assignments keep their revision, worktree and thread. Material changes to active work require a recorded checkpoint and completion of the active turn before revision or cancellation. A new revision gets a fresh worktree; earlier effects remain inspectable.

Questions and answers travel through the durable inbox and resume the same specialist thread. An idle specialist can answer a clarification in a read-only turn after its assignment completes. Messages queue while a turn is busy; related update messages can steer the active turn. A confirmed steering rejection queues the message; uncertain dispatch stops execution rather than replaying it. Ordinary transport status does not wake the model. heartbeat updates stored activity without requesting a coordinator decision.

Integration and recovery

State lives under the repository's common git directory: buddies-orchestrator/<room-hash>/state.redb. A transactional database lock prevents two local coordinators from owning that state. state.json is an atomic, reviewable snapshot, not an editable configuration. This directory also retains specialist worktrees, per-revision patches, acceptance logs and the integration worktree. Internal commits occur only in the detached integration worktree; repository hooks are disabled for the runtime's git operations.

The coordinator completes the goal only after every required assignment is verified and specialists are idle. The runtime then runs the user's --check commands on the combined changes, validates the authorized scope again, and applies verified.patch to the original checkout. It does not commit that checkout. Its HEAD and cleanliness must still match the starting repository; otherwise the patch remains available for inspection and integration.

Restart with the same command and add --resume. Configuration and aggregate usage persist. Threads resume using their saved IDs. Interrupted work becomes uncertain and cannot run again until the coordinator inspects effects and records an explicit recover decision. Read inbox messages from an interrupted dispatch become failed receipts. Completed goals return their stored result without starting Codex.

An interrupted integration/publication can require manual inspection of retained worktrees, the saved integration HEAD, and verified.patch. A saved publication boundary with an uncertain outcome refuses automatic resume. Do not edit the state snapshot or resend work without reviewing effects. Acceptance failures before publication leave the checkout unchanged and can be addressed by revising the relevant assignments.

These worktrees and scope checks guard integration and coordination; they are not a security boundary for hostile code. Reported acceptance commands execute with the local user's permissions in an isolated worktree. Use a repository and goals you trust, as for the existing managed-agent/worker runtimes.

Budgets

Defaults are two active specialist turns, 64 model dispatches, 1 MiB of generated text, one hour of aggregate running time, dependency depth eight and 120 seconds per acceptance command. Configure them with --max-active-specialists, --max-model-calls, --max-output-bytes, --max-elapsed-secs, --max-depth and --check-timeout-secs. --debounce-ms defaults to 1000 and combines bursts before dispatch. Specialist turns waiting for input release an active slot, while their assignment stays associated with its owner.

The call budget counts host turn/start and turn/steer dispatches, including failed/uncertain dispatches. It is not a billing/token measurement of internal model requests. Output tracks generated reply/reasoning text and tool arguments. Time and usage do not reset on resume; budget exhaustion stops subprocesses and retains evidence. Graphs, role counts, revisions, input text, patches and check logs are also bounded. The App Server's native multi-agent delegation and autonomous goal continuations are disabled so specialist creation and turn dispatch stay with the scheduler.

Verification

cargo test --locked --all-targets
cargo build --locked
PYTHONDONTWRITEBYTECODE=1 python3 scripts/smoke_orchestrator.py

The deterministic experiment uses the real HTTP service, durable inbox and git worktrees with an App Server fixture. A consumer asks about a missing field, receives a recorded answer in the same thread, then accepts a material contract change after an active-turn checkpoint. Its revision-two result passes the shared check; the producer remains on revision one. The test also checks stale evidence, thread reuse, single dispatch of each revision, publication, completed resume, and interrupted recovery without duplicate execution.

This validates the runtime protocol. It does not measure a real model's cost or compare completion rates with direct peer coordination. That comparison remains an opt-in acceptance experiment using the same models and task described in the design.