Epic: Smart Orcastrators — unify coordinator+lineage into one orchestration system

[zaridan]

Goal

Make the Orcastrator a real orchestration system with two director backends: the current LLM director and a token-free recipe director, both feeding one live Control Panel that renders the actual task DAG.

⚠️ Corrected architecture (after adversarial review — see comment below)

The original plan rested on a false premise: "recipe mode reuses the existing coordinator, mostly free." It does not. There are two unrelated systems sharing a name:

• LLM director path (ships today): pastes /orcastrate → Claude runs orca worktree create per PR-track. Pure worktree lineage. Never calls the coordinator. Mission Control discovers workers by lineage only.
• Coordinator/DAG path: dispatches tasks to terminals inside one worktree, never creates worktrees, and nothing in the Orcastrator UI reads its DB.

So "token-free recipes" + "Control Panel renders the DAG" both require bridging these worlds — the chosen "full bridge" path. Also dropped: the token-free pitch as primary rationale (the director is ~2–8% of run cost; workers dominate). Recipes are justified by determinism/reliability, not cost.

Feasibility (verified, file:line)

All additive or targeted — nothing blocked:

• addWorktree exists in main (src/main/git/worktree.ts:613); OrcaRuntimeService backs CoordinatorRuntime.
• OrchestrationDb singleton (orca-runtime.ts:2448), WAL — per-run isolation feasible.
• No resume-on-boot hook; no renderer→orchestration.run binding (both confirmed gaps, both additive).

Work breakdown (dependency-ordered)

Foundation

• Bridge F1: per-run isolation of the orchestration DB (proper clash fix) #12 — F1: per-run isolation + clash fix (scope tasks/dispatches/messages/gates per run OR per-run DB file; per-run coordinator handle; atomic run-start). Prerequisite for all.
• Bridge F2: Coordinator creates per-track worktrees (not just terminals) #13 — F2: coordinator creates per-track worktrees (lineage parent = director) — the keystone that makes coordinator work UI-visible.
• Bridge F3: Coordinator resume-on-boot (kill the zombie-director failure) #14 — F3: coordinator resume-on-boot (kills the zombie-director failure).
• Bridge F4: renderer -> main orchestration.run / taskCreate binding #15 — F4: renderer→main orchestration.run/taskCreate binding.

Observability (Control Panel, now DAG-backed)

• Sync orchestration task DAG + dispatch detail to the renderer #6 — O1: sync per-run task DAG + dispatch detail to renderer (depends F1).
• Control Panel: live DAG render in WorkspaceCard/AgentRow/AgentStateDot vocabulary #7 — O2: rewire Mission Control from pure-lineage to DAG-backed + live Control Panel render (depends O1, F2).

Recipe

• RecipeDirectorBackend: compile recipe -> task DAG -> orchestration.run, no LLM in worktree #9 — R1: RecipeDirectorBackend — worktree shell, no LLM, compile recipe → tasks → run (depends F1–F4). Now genuinely token-free.
• Starter recipes: single_worker_pr, implement_then_review, repro_fix_verify #10 — R2: starter recipes (single_worker_pr, implement_then_review, repro_fix_verify), built-in TS.
• DirectorBackend abstraction + LlmDirectorBackend (wrap current behavior) #8 + Director-type picker UI (Smart / Recipe), gated by experimentalOrchestrators #11 — R3: thin DirectorBackend abstraction + director-type picker UI (LAST — only after recipe mode proves out).

Sequencing principle

Foundation → observability → recipe → abstraction. F1 (#12) ships first and standalone — it's a real bug fix with value regardless of whether recipes ever land. Validate each layer before building the next.

Workflow

All work on the fork (zaridan/orca), pushed + tested here before anything goes upstream to stablyai/orca. Behind experimentalOrchestrators. Align the bridge design with upstream before investing the full build.

[zaridan]

Adversarial review findings (why the plan changed)

Four independent skeptics reviewed the original plan; three load-bearing claims broke. Audit trail:

1. Coordinator ≠ what the feature uses (fatal to the original framing). The LLM director never calls the coordinator; Mission Control reads lineage, not the DAG (OrchestratorMissionControl.tsx:30 "no orchestration RPC yet"). "Reuse is free" was conflating two systems. → drove the full-bridge decision (F2 Bridge F2: Coordinator creates per-track worktrees (not just terminals) #13).
2. The clash fix was insufficient + the interim guard races. run_id on tasks alone leaves dispatch_contexts/messages/decision_gates global; shared 'coordinator' handle lets one run eat another's worker_done; check-then-start is TOCTOU. → expanded F1 (Bridge F1: per-run isolation of the orchestration DB (proper clash fix) #12).
3. "Keep worktree shell, no LLM" has a lifecycle hole (headless coordinator and empty tabId are both fine — those worries refuted — but there's no resume-on-boot → zombie director). → F3 (Bridge F3: Coordinator resume-on-boot (kill the zombie-director failure) #14) + F4 (Bridge F4: renderer -> main orchestration.run / taskCreate binding #15).
4. Token-savings is a rounding error (director ~2–8% of run cost). → recipe rationale reframed to determinism, not cost.

Decision: commit to the full bridge (unify the two worlds) so token-free recipes + a live DAG Control Panel both become real. Validate layer by layer; F1 ships first and standalone.