Fleet and Orchestrator

Fleet and Orchestrator

The fleet is the set of agent workers the Code Sentinel orchestrator dispatches for a project: one slot per ready GitHub issue, each in its own git worktree and tmux session. Nautelle does not reimplement the orchestrator — it observes what the orchestrator writes, and drives it through the same mechanisms the skill itself uses. This page covers watching the fleet, steering it, the queue it draws from, and approving what it produces.

flowchart LR
  issues["GitHub issues<br/>with the ready label"] --> queue["Queue"]
  queue --> orch["Orchestrator round"]
  orch -->|dispatches| s1["Slot i42<br/>worktree + tmux"]
  orch -->|dispatches| s2["Slot i43<br/>worktree + tmux"]
  s1 --> pr1["Pull request"]
  s2 --> pr2["Pull request"]
  pr1 --> appr{"Merge approval<br/>on?"}
  pr2 --> appr
  appr -->|off| merge["Orchestrator merges"]
  appr -->|on| person["Approvals:<br/>Approve / Request changes"] --> merge

Loading

Note

The fleet path is separate from Board cards. Cards run as dedicated interactive workers outside the orchestrator; fleet slots appear on the Board as read-only cards so you can see all work in one place.

Key terms

Term	Meaning
Orchestrator	a session running /code-sentinel:orchestrator for one project
Round	one orchestrator pass over the queue
Slot	one unit of dispatched work, i<issue> or i<issue>-<part>: one worktree, one tmux session cs-<slot>
Worker	the agent session in a slot
Checkpoint	a worker report: picked up · plan ready · implementation done · pull request open · blocked · misclassified
Ready label	cs:ready by default; marks an issue dispatchable

Watch the fleet

Open Project › Fleet (/projects/<id>/fleet). The fleet is drawn as a workspace canvas: the orchestrator, its slots and planned work, with edges for delegation and dependencies. Each slot shows:

• the issue and branch, runtime and model;
• its stage and progress — picked up, plan ready, implementation done, PR open, checks green;
• the pull request and its checks;
• whether it is idle, out of quota, or waiting at a prompt.

Select a slot to open its side panel with the orchestrator ↔ worker conversation, the worktree status and the live pane.

The runner learns this from the orchestrator's structured events.jsonl and state.json. When those are missing it falls back to reading tmux sessions, worktrees, round boards and reply files, and marks those events as scraped.

Steer the orchestrator

Operators of a project control the orchestrator from the fleet page:

Action	Effect
Start / Next	launches /code-sentinel:orchestrator start or next through the project's runtime profile, in a tmux session nautelle-orch-<project>
Stop	stops the orchestrator
Status	asks the orchestrator for its status
Stop slot	stops one worker
Message worker	types a message into a worker's session; the orchestrator is told through events.jsonl

The default profile, model and permission mode are set in Project › Settings › Orchestrator. Every action is a typed runner command, checked against your project role, written to the audit log and recorded as an event. Messaging a running session must also be allowed on the machine with nautelle-runner policy set commands.slot.message true (see Installing the Runner).

Nautelle never dispatches a specific issue or changes a slot's model — the orchestrator decides.

Live pane and terminal attach

Live pane. Any project member can watch a worker's terminal, streamed read-only into the slot panel. The runner captures the pane only while someone is watching, sends only what changed, masks strings that look like secrets, and stops when the last viewer leaves. Frames are relayed, never stored.

Terminal attach. An admin can attach to a slot, the orchestrator session, a skill run, a Board card or a manual Claude Code session through a browser terminal:

1. Open the session and choose Attach.
2. The terminal opens read-only. Choose Take control to type; this needs terminal.write allowed in the runner's local policy.
3. Scroll up (mouse wheel, or swipe on a phone) to read up to 5,000 lines of history without sending input. Back to live returns to the live view.

Limits: a 15-minute idle timeout, 4 hours maximum, at most 2 attaches per runner and one read-write attach per target. Detaching never kills the session. Every attach is audited with start, end, duration and byte counts; nothing is recorded.

Queue

Project › Queue shows the project's open GitHub issues with the ready label — the orchestrator's queue (GitHub issues are the task queue). Each issue carries a computed state, the reason and what would clear it:

State	Meaning
READY	dispatchable now
IN FLIGHT	a slot is working on it
BLOCKED — work	waits on other issues
BLOCKED — person	waits on a decision
NO SPEC	the body is not complete enough to dispatch

When the orchestrator has written a fresher verdict on a round board, its verdict wins. The runner polls GitHub every 60 seconds, or the GitHub App pushes changes instantly. Operators can create an issue from the queue; it is labelled ready only when its body is complete. GitHub stays the editor for existing issues.

Approvals

Project › Approvals has two tabs.

Pull requests. By default the orchestrator merges every green pull request itself. Turn on merge approval for the project and it stops at "green and mergeable" and waits. Each waiting PR shows the worker's merge summary, checks and diff size:

• Approve — the orchestrator merges it.
• Request changes — a note goes back to the worker through the orchestrator.

Nautelle never merges a fleet PR itself, and every decision is audited.

Action requests. Decisions a Claude Code session asks a person for — a permission prompt while away mode is on, or an issue a session filed for the fleet, which waits until a person approves queuing it. Each request shows a redacted preview of the tool input. Approve or deny here, from a notification, or in Telegram. See Claude Code Integration.

Activity and history

• Activity (/activity, and per project) — one curated, filterable live feed of what happened across your projects: orchestrator and round events, slots, PRs, approvals, runs, budget alerts and audited actions.
• History (Project › History) — one row per unit of agent work (an orchestrator slot, a skill run, a scheduled run, a card round) with its outcome, pull request, tokens and API-equivalent cost. Open a run for its detail.

Both are scoped by project membership.

See also

• Board and Cards · Sessions, Usage and Budgets · Automation
• Event schema · Runner protocol

Decisions: ADR-0002 · ADR-0004 · ADR-0005 · ADR-0045 · Spec: #11, #16, #17, #18, #19, #20, #21, #29, #160, #522