Orchestration

Tabs full of agents are useful until they need to work together. Who owns this task? Did that worker finish or crash? Which decision needs a person? Orchestration answers those questions inside the Rust runtime host. It does not replace your agent CLIs; it hands them work and keeps track of it. You follow and steer that work in Runs And Activity.

What Ships Today#

• Runs. A coordinator plans a run and workers carry it out, either in the run’s workspace (Shared) or each task in its own worktree with serial local integration (Isolated). A workspace has at most one unfinished run; unrelated workspaces coordinate at the same time.
• Durable ownership. Runs, tasks, and dispatches persist in the runtime SQLite database, so a restart does not forget who was doing what. Authority comes from the run, not from whichever terminal called a command.
• A short worker protocol. No accept step and no heartbeat: a worker’s first command tells Alera it started, its terminal output keeps it alive, and it finishes with one complete --summary.
• Gates. Plan approval (when you ask for it), stage gates, stalled workers, and coordinator questions are all decisions you answer from one kind of card.
• Questions and messages. Agents and you can ask a running agent a question; agents that queue input mid-turn get it at once.
• Agent profiles. User-declared launch configurations the coordinator may dispatch to.

Agent Profiles#

Profiles can be managed from Settings → Agent Profiles or the top-level alera agent-profile CLI. Each one has a name, an adapter from the built-in registry (codex, claude, copilot, cursor, agy, opencode, pi, amp, grok, fx, and related defaults), a launch configuration, a description used as a routing signal, and an optional quota group.

alera orchestration --json agent-profiles
alera agent-profile --json list
alera agent-profile create --name "Codex Sol" --agent-type codex --launch-mode command --command "codex --search"

The administrative CLI also supports show, patch-style update, removal impact, confirmed removal, complete-catalog reorder, and launching a profile in a workspace. Managed profiles accept configuration as inline JSON, a file, or standard input. Changing the adapter of an existing Managed profile requires an explicit new configuration, and reduced-protection settings require an explicit confirmation flag. A coordinator only reads the closed catalog you approved: delegate always starts a catalog profile, so a worker never runs a command the coordinator made up.

Delegate A Task#

alera orchestration --json delegate --profile "Codex Sol" --spec "Review the tests"
alera orchestration --json delegate --profile "Codex Sol" --spec "Implement the API" --new-workspace
alera orchestration task wait --id <task-id> --timeout-ms 300000

delegate creates the task, starts the profile in a new terminal (or hands the task to a running agent with --terminal), and waits until the agent is ready. It defaults --workspace from ALERA_WORKSPACE_ID; --new-workspace creates a child worktree first. Use alera orchestration current to inspect the current workspace and terminal identity.

Plan A Run#

alera orchestration --json run new --profile "Opus" --spec "Add audit logging" --template builtIn:feature-delivery --approval
alera orchestration --json run show --run <run-id>
alera orchestration run cancel --run <run-id> --reason "No longer needed"

run new is the CLI form of New Run: the coordinator reads the run’s context and proposes a plan with alera orchestration plan propose. With --approval the plan waits for you; without it the run starts at once. --isolation shared keeps workers in the workspace instead of giving each task its own worktree. See Runs And Activity for plans, gates, the timeline, and cleanup.

The Worker Side#

alera orchestration --json context
alera orchestration complete --summary "What was done and what remains"
alera orchestration escalate --subject "Blocked" --body "Missing credentials"
alera orchestration ask --to <coordinator-handle> --question "Which branch?"

A worker reads its task with context, does it, and completes once with --summary; files, artifacts, and validation are optional unless the task’s role contract asks for them. A worker with no output or command for 10 minutes is marked stalled, but it is never killed or replaced without a decision, and any later output revives it.

Questions And Messages#

ask, send, and reply carry messages between agents, and messages lists them. A question to a working agent is pasted at once only when its CLI is verified to queue input mid-turn, which none is yet; otherwise it waits for the turn to end. An agent waiting on a prompt is never typed into. alera inbox ask lets a script or another session ask from outside Alera, and Activity → Questions does the same from the app and the phone. Agents always answer with an explicit alera orchestration reply; nothing is read from their terminal.