The Orchestrator

The orchestrator is a deterministic state machine that enforces the full development lifecycle. It runs inside the daemon process and drives work from intake through shipped milestone, surfacing only meaningful decisions to the human.

How It Works

The orchestrator maintains a 10-state lifecycle:

1
2

idle → intake → triage → milestone_setup → planning → executing →
post_task → reviewing → milestone_check → milestone_complete → idle

Each state transition has enforced preconditions — the orchestrator cannot skip steps. At specific points it surfaces decisions for human approval; everything else is automatic.

Human Decision Points

There are 7 decision points per milestone:

Running the Orchestrator

To advance the orchestrator manually:

1

telesis orchestrator run

This drives the state machine forward in a loop — calling intake, planning, dispatch, review, and milestone operations as needed — until it reaches a decision point that requires human input, or returns to idle. Output shows each state transition as it happens.

The typical workflow:

1. Run telesis orchestrator run — it advances and creates a decision
2. Review the pending decision with telesis orchestrator status
3. Approve or reject: telesis orchestrator approve <id>
4. Run again: telesis orchestrator run — it picks up from where it stopped
5. Repeat until the milestone is complete

Interacting with Decisions

When the orchestrator needs your input, it sends a macOS notification and queues the decision in .telesis/decisions/.

Check status

1

telesis orchestrator status

Shows current state, active milestone, progress, and any pending decisions.

Approve a decision

1

telesis orchestrator approve <decision-id>

The decision ID is shown in the status output. Prefix matching is supported (8+ characters).

Triage approval with metadata

When approving a triage decision, you can provide milestone metadata and select which work items to include:

1
2
3
4
5

telesis orchestrator approve <id> \
  --items wi-abc123,wi-def456 \
  --milestone-name "Auth Improvements" \
  --milestone-id "0.25.0" \
  --goal "Strengthen authentication and fix password reset"

If you omit --items, all work items from intake are included. The status output shows the LLM’s suggested groupings to help you decide the scope.

Reject a decision

1

telesis orchestrator reject <decision-id> --reason "Tasks are too coarse"

The orchestrator uses your feedback to adjust (e.g., re-plan with your guidance).

Session Tracking

The orchestrator tracks agent session lifecycle across context boundaries. When a coding agent session ends — whether from context exhaustion, a hook block, a crash, or clean completion — the orchestrator records what happened so the next session can resume intelligently.

Each execution attempt records:

• Session ID — which session was active
• Start time — when the execution attempt began
• End time — when the session ended
• Exit reason — clean, hook_block, context_full, error, or unknown

Resume Briefing

When a new session needs to pick up where the last one left off:

1

telesis orchestrator resume-briefing

This inspects the orchestrator state, git workspace (staged/unstaged changes), and session history to produce a structured orientation:

• Current state and task progress
• What the last session was doing and why it ended
• Whether uncommitted changes exist (and whether they look like completed work)
• A specific recovery recommendation (e.g., “run review convergence, then commit”)

The MCP tool telesis_orchestrator_resume_briefing returns the same information as structured JSON for LLM consumption.

Restart Policies

When the daemon detects that a dispatched agent session has ended, it applies a configurable restart policy:

Configure in .telesis/config.yml:

1
2
3
4
5

daemon:
  sessionLifecycle:
    restartPolicy: auto-restart
    cooldownSeconds: 30
    maxRestartsPerMilestone: 10

Auto-restart has safety rails:

• Cooldown — minimum 30s between restarts (configurable)
• Circuit breaker — stops after 10 restarts per milestone (configurable)

Preflight Checks

The orchestrator provides preflight checks that gate git operations:

1

telesis orchestrator preflight

Checks:

• Milestone entry exists in MILESTONES.md
• Review has converged (orchestrator past reviewing state)
• Quality gates pass
• No blocking decisions pending

Exits with code 1 on failure, which blocks the hook.

Enforcement Mechanisms

Preflight is enforced through two complementary mechanisms:

Git hooks (provider-neutral): telesis hooks install adds a git pre-commit hook that runs preflight before every commit. Works with any agent — no Claude Code dependency.

1
2

telesis hooks install    # install the hook
telesis hooks uninstall  # remove it

Claude Code hooks: A hook at .claude/settings.json runs preflight before every git commit in Claude Code. The git hook and Claude Code hook coexist without conflict — the git hook defers if it detects the Claude Code hook already ran preflight.

The Claude Code hook script is at .claude/hooks/git-preflight.sh.

LLM Judgment Calls

The orchestrator makes targeted LLM calls (Haiku-class, cheap) at two points:

• Triage: suggests how to group work items into milestones
• Milestone setup: assesses whether the milestone needs a TDD

These are suggestions — the human makes the final decision via the approval flow.

Persistence and Recovery

Orchestrator state is persisted to .telesis/orchestrator.json. If the daemon crashes, the orchestrator resumes from the last saved state on restart. Decisions are persisted individually in .telesis/decisions/.

Task progress is checkpointed after each completed task — if a session dies mid-plan, the next session starts from the last completed task, not from scratch.

The telesis orchestrator status command shows dispatch session history for the current milestone, including start/end times, status, and exit reasons.

Starting the Orchestrator

The orchestrator starts automatically when the daemon starts:

1

telesis daemon start

It stops when the daemon stops, persisting final state.