Orchestration

Coordinate agents with Runs, tasks, supervised workers, messages, and decision gates.

Orchestration is Nethür's structured multi-agent layer: a Run (namespace + coordinator inbox), Tasks, Dispatches, supervised workers, messages, and decision gates.

Use it when you need ownership, completion tracking, or a DAG. For one-off prompts, use nethur terminal send. For full ownership handoffs without supervision, use worktree/terminal commands from the nethur-cli skill.

Core model

  • Run — durable namespace and home inbox. Never schedules or places workers.
  • Task — a work item with a spec, dependencies, and status: pending, ready, dispatched, completed, failed, or blocked.
  • Dispatch — one attempt of a task on a terminal; lifecycle authority for worker_done / heartbeat.
  • Message — inbox mail (status, dispatch, worker_done, escalation, question, heartbeat, …).
  • Decision gate — a coordinator-owned question that blocks a task until it is resolved.

Completion authority comes from the active dispatch context. Worker completion and heartbeat messages should include both taskId and dispatchId.

Task IDs printed in terminals, such as task_..., are clickable links. Clicking one asks the Nethür runtime for the task's current dispatch and focuses the assigned terminal, including when the task lives in a remote or SSH runtime.

Preferred supervised loop

bash
nethur orchestration run-create --objective "Split checkout QA and summarize blockers" --json
nethur orchestration task-create --spec "Audit billing settings for mobile layout" --task-title "Billing audit" --json
nethur orchestration worker-start --task <taskId> --worktree current --agent codex --json
# or new worktree:
nethur orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run --json
# optional per-worker model / effort (Claude, Codex, Cursor, Antigravity, Muse; not with --terminal):
nethur orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high --json

--agent takes any Nethür agent ID enabled on the worker server, for example claude, codex, cursor, antigravity, muse, opencode, or opencode2. --model accepts opaque provider model IDs for Claude, Codex, Cursor, Antigravity, and Muse (for example --agent muse --model muse-spark-1.3); OpenCode accepts a per-launch model only in an existing worktree, when the execution host verifies its CLI version and model availability; OpenCode effort remains unsupported. Other agents run the model from their own config. --effort requires --model and only applies when that agent/model supports the level. Neither flag can combine with --terminal (reuse an existing pane). Overrides apply to that launch only and show under launch.requested / launch.effective in the start receipt. Federated starts need a worker host that advertises launch-preference support.

Wait for completions (process every message in a Delivery, then ack):

bash
nethur orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
nethur orchestration check --ack <deliveryId> --wait --types worker_done,escalation,question --timeout-ms 900000 --json

Worker completion (from the worker pane; include injected IDs):

bash
nethur orchestration send \
  --type worker_done \
  --subject "Completed mobile audit" \
  --body "Fixed footer overlap; no follow-ups." \
  --task-id <taskId> \
  --dispatch-id <dispatchId> \
  --outcome succeeded \
  --files-modified "src/app/settings/Billing.tsx" \
  --json

worker_done requires --outcome succeeded|failed.

Inspect / recover:

bash
nethur orchestration worker-show --dispatch <dispatchId> --json
nethur orchestration worker-read --dispatch <dispatchId> --limit 50 --json
nethur orchestration worker-stop --dispatch <dispatchId> --json
# After an accepted worker_done: reuse the same terminal for a follow-up Dispatch, or release it
# (archives inspectable output, then closes only that coordinator-owned agent terminal):
nethur orchestration worker-release --dispatch <dispatchId> --json
# Keep a settled worker live for debugging when the user asked to retain it:
nethur orchestration worker-retain --dispatch <dispatchId> --json
# retry placement is explicit — --retry-of does not inherit --on/worktree:
nethur orchestration worker-start --task <taskId> --retry-of <dispatchId> --worktree current --agent codex --json

Do not leave completed worker terminals open just to re-read output — use worker-read after worker-release. Do not substitute a broad terminal close when release returns release_pending or release_unknown; follow the receipt's recovery action.

Federated workers (optional)

bash
nethur orchestration worker-start \
  --task <taskId> \
  --on windows \
  --worktree new-top-level \
  --repo <exact_remote_repo_selector> \
  --name remote-worker \
  --agent codex \
  --setup run \
  --json
nethur orchestration send --to dispatch:<dispatchId> --subject "Follow-up" --body "…" --json

Later commands route by Dispatch ID; do not repeat --on.

Low-level dispatch (custom topology)

bash
nethur worktree create --name billing-audit --agent codex --json
nethur terminal wait --terminal <workerHandle> --for tui-idle --timeout-ms 60000 --json
nethur orchestration dispatch --task <taskId> --to <workerHandle> --inject --json

Messaging notes

  • Default check is the bound Run's oldest unacked Delivery (FIFO). Replay until --ack.
  • --peek / --all do not consume mail.
  • Group addresses: @all, @idle, @claude, @codex, @opencode, @gemini, @droid, @grok, @cursor, @worktree:<id> — never for worker_done / heartbeat.
  • Every group except @worktree:<id> means the live Dispatches of the sender's own Run, delivered to their Dispatch mailboxes (or child Run mailboxes for nested coordinators). A sender in no Run is refused; --run must match the audience and never grants membership.
  • Run groups exclude their owning coordinator. A worker raising a blocker sends to run:<id>. @worktree:<id> includes coordinators in that workspace.
  • Quote PowerShell group addresses: --to "@all".
bash
nethur orchestration send --to @all --subject "Heads up" --body "Pausing dispatches for a review." --json
nethur orchestration send --to @idle --subject "Anyone free?" --json
nethur orchestration send --to @codex --subject "Codex workers in this Run only" --json

While a wait is active, the CLI emits small JSON heartbeat lines to stderr every 15 seconds. Stdout remains the final command result.

Worker contract

Dispatched workers receive a preamble that tells them how to communicate with the coordinator:

  • Send worker_done exactly once, even on failure, with --outcome.
  • Include a short --body summary: what was done, what was found, and what remains.
  • Include both task and dispatch IDs so stale retries cannot complete the wrong dispatch.
  • Send heartbeat messages during long active work.
  • Use nethur orchestration ask for blocking questions instead of local TUI prompts.
bash
nethur orchestration ask \
  --to <coordinatorHandle> \
  --question "Should I update the shared component or only this page?" \
  --options "shared,page-only" \
  --timeout-ms 600000 \
  --json

With --json, ask prints the standard {id, ok, result, _meta} envelope, so workers read the answer with jq -r .result.answer.

Decision gates

Use ask for worker-to-coordinator questions. Use explicit gates when the coordinator has created a task DAG and wants to block a task until a decision is recorded:

bash
nethur orchestration gate-create \
  --task <taskId> \
  --question "Merge the shared button change into the task branch?" \
  --options '["yes","no"]' \
  --json

nethur orchestration gate-resolve --id <gateId> --resolution "yes" --json

Recovery

bash
nethur orchestration dispatch-show --task <taskId> --json
nethur orchestration dispatch-show --task <taskId> --preamble --json
nethur orchestration task-list --json
nethur orchestration task-update --id <taskId> --status blocked --result '{"reason":"waiting on credentials"}' --json

Reset only when you are intentionally abandoning orchestration state:

bash
nethur orchestration reset --tasks --json
nethur orchestration reset --messages --json
nethur orchestration reset --all --json

reset affects runtime-global orchestration state. Do not run it while another coordinator is active unless that is the intended cleanup.

Choosing the right command

Use nethur terminal send for a lightweight prompt to an agent you are watching.

Use nethur orchestration worker-start (or dispatch --inject) when a worker must report worker_done, ask questions through the coordinator, and be tracked by task ID.

Use nethur orchestration run-create + tasks + workers when you want a durable Run namespace and supervised multi-agent loop — not the retired orchestration run command.

Full guide

Command flags evolve with the app. After install, agents should run:

bash
nethur skills get orchestration --full