Orchestration — Causal Operations Atlas

The dashboard Causal Operations Atlas pairs an attention rail (live questions and approvals) with a causal canvas (run cards, DAGs, and Trace Lab) and a docked task drawer. It shows live task state pulled from each connected planner, and action buttons queue commands the planner picks up within a couple of seconds.

1. Bring A Fleet Online And Dispatch

Save an API key, then start orchestrating from the CLI or the Atlas causal canvas + Start form. See Fleet Management for connecting workers of different flavors, and Getting Started for the full first-run walkthrough.

nfltr config add-api-key "$NFLTR_API_KEY"   # from dashboard → Settings → API Keys

# Check which workers are connected and what they can run
nfltr orch fleet workers --json

# Dispatch a task contract and watch it to completion (watch is on by default)
nfltr orch start task --task-mode implement \
  --objective "Fix the nil deref in pkg/foo/bar.go reported by TestFoo_NilGuard; return a git patch" \
  --workspace-isolation per_task

Once a worker is connected and a task is dispatched, the causal canvas flips from "Waiting for first update…" to live run cards. If you do not see anything within ten seconds, confirm the worker is actually connected (nfltr orch fleet workers) and that the API key on both sides belongs to the same account. Human gates surface on the attention rail; expand a card for Trace Lab when you want wall-time or critical-path evidence.

2. Launch Your First Task

On the causal canvas Runs surface, click + Start. A small inline form opens:

• Objective — natural-language description of what the worker should do. Example: "Fix the nil deref in pkg/foo/bar.go reported by the new test in TestFoo_NilGuard; return a git patch."
• Worker — dropdown of agents you own. The dashboard reads /api/v1/my/agents so siblings of your API key all appear.
• Task mode — the contract mode the worker executes, for example implement, inspect, or review. Add workspace isolation and capability requirements to define what the coordinator should match.

When you click Start, the Atlas generates a client-side task id (prefixed dash-…) and queues a start_task command. Within ~2s the coordinator picks it up, calls orch.StartTask, and the new task appears on the causal canvas. Click a node to open the docked task drawer. Dispatching from the CLI with nfltr orch start task shows up in the same live view — both paths go through the same coordinator.

3. Read The Live View

Tasks group by lineage_root. Top-level tasks render as group headers; child tasks a planner spawned from a parent indent under them. Each row carries:

4. Steer Mid-Flight

Four controls show up inside task rows when relevant. Each one queues a command at POST /api/v1/orchestration/commands; the planner consumes it within ~2s.

The same control plane is exposed at the API level if you want to script approvals from CI:

curl -X POST https://nfltr.xyz/api/v1/orchestration/commands \
  -H "X-Api-Key: $NFLTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"dash-abc123…","type":"approve_dispatch"}'

Use Cases

Use case 1 — Repo bug fix from the dashboard

The fastest path to value. Connect a worker against your repo, then click + Start (or run nfltr orch start task) with an objective like "Add a regression test for the bug in #1234 and a minimal patch; return a git patch artifact." The worker turns up in the live view, runs to completion in its own isolated workspace, and returns a git patch artifact you can apply in your own clone:

git -C /path/to/coordinator apply < /path/to/worker/clone/$(jq -r '.result.artifacts[0].path' < result.json)

Deeper walkthrough: Local Repo Improvement with NFLTR Workers.

Use case 2 — Plan → execute → review → integrate

A planner can spawn task-mode contracts under one lineage_root for a multi-actor flow:

1. The planner decomposes the objective and dispatches one task-mode contract per slice.
2. As slices complete, the planner dispatches review or verification contracts against returned artifacts.
3. If the review passes, an integration or fan-in task combines the accepted outputs.
4. You watch the entire lineage in one collapsible group. Failed reviews show red badges and the failed artifact path; rejecting from the dashboard re-queues the slice with feedback.

Use case 3 — Approval-gated dispatch for risky operations

When you launch a task with the require_approval constraint set in the planner's policy, it parks at pending_approval=true instead of dispatching. The dashboard renders an Approve / Reject alert inline. This is how teams gate deploys, schema migrations, or anything that should not run automatically just because a planner inferred it.

Use case 4 — Mid-flight question and answer

Inside a worker's MCP session, calling ask_question suspends the task with a pending_question. The dashboard shows the question text and a small textarea. Type a one-line answer, click Answer, and the worker resumes. Useful for "Should I prefer option A or B?" decisions you do not want to encode upfront.

Use case 5 — Abort a runaway task

When a worker is stuck in a loop or burning tokens on the wrong objective, Abort is the off switch. The reason you type lands in the orchestrator's history alongside the cancel event so future replays know why the run ended.

Use case 6 — Review a completed task

Terminal-state tasks (completed or failed) get an inline Approve / Request changes / Reject row. Click any of them and the digest row's review_state + reviewer are stamped immediately, with a review event appended to the task timeline. Idempotent — clicking twice converges. Use this when a review loop hands a worker's result back to a human for sign-off.

Use case 7 — Rerun a task

The ↻ Rerun button on terminal tasks dispatches a fresh task with the same objective, worker, task mode, and optional actor metadata, plus a parent_task_id that links it back to the source. The dashboard's plan-tree view nests the rerun under the original so multi-attempt orchestrations stay legible. This is fork-from-N=0: the new task starts clean rather than resuming mid-conversation.

Use case 8 — Per-task workspace isolation

Set --workspace-isolation per_task on the dispatch (or require it as a hard contract) and each task gets a fresh, isolated workspace for the duration of that task, cleaned up on finalization — so one task's edits can never clobber another's files. See Agent Orchestration for the full workspace isolation model.

Behind The Scenes

Dispatch-level safety rails

Storage is pluggable. The hosted relay at nfltr.xyz uses a SQL store so commands and digests survive a restart. The same wire shape keeps coordinator and worker state consistent across a restart.

Troubleshooting

Next

• Agent Orchestration overview — the platform-level view: planners, workers, timelines, managed capabilities.
• Local Agent Orchestration — validate planner-worker behavior on one machine before scaling out.
• Local Repo Improvement — the canonical "fix something in your repo from a worker" walkthrough.
• Managed Capabilities — drive long-lived AI / HTTP / terminal surfaces from the dashboard as desired state.