feat: Task Graph Executor

[mmogr]

Task Graph Executor — Orchestrator Epic

Closes #496

This PR merges the complete Orchestrator Epic into main. It introduces a local-first Director/Worker DAG execution engine that lets gglib decompose a high-level user goal into a structured task graph, execute each node in parallel with strict resource scoping, checkpoint state to SQLite for resumability, and surface the entire lifecycle through a native Tauri/React UI with optional human-in-the-loop approval gates.

All 6 phases were developed on individual feature branches, reviewed, and squash-merged into epic/orchestrator. Each phase individually passed strict Clippy (-D warnings), cargo fmt, boundary checks, and its own integration test suite before merging.

---

Phase A — Core Types & Planning (feat/orchestrator-phase-a) #490

Defines the foundational domain model that all later phases build on.

• TaskGraph / TaskNode with dependency edges, tool allowlists, and worker concurrency caps
• OrchestratorEvent discriminated union (SSE wire format) covering every lifecycle signal: planning, node lifecycle, tool calls, synthesis, HITL approval requests, and completion
• PlanningClient trait + LlamaPlanningClient implementation calling the LLM to produce a structured plan from a natural-language goal
• HitlMode enum: None | ApprovePlan | ApproveEachNode | ApproveTools
• Merged in feat(orchestrator A): ResponseFormat port, StructuredOutputError, TaskGraph domain model #497

---

Phase B — Graph Execution Engine (feat/orchestrator-phase-b) #491

The core DAG executor that turns a TaskGraph into a live SSE stream.

• Topological scheduling with configurable per-graph max_worker_concurrency
• Per-node WorkerAgent executing its goal within a strict tool allowlist; cannot call tools or access context outside its node scope
• Node outputs injected as read-only context into downstream dependents
• Streaming OrchestratorEvents over an mpsc channel — every state change (start, text delta, tool call, compaction, completion, failure) is observable in real time
• OrchestratorError hierarchy covering planning, execution, and persistence failures
• Merged in feat(orchestrator B): director plan(), CLI gglib plan, Axum SSE /orchestrator/plan, Tauri preview, eval harness #498

---

Phase C — SQLite Persistence & Resumability (feat/orchestrator-phase-c) #492

Full checkpoint/resume support backed by gglib-db.

• OrchestratorRun persisted to SQLite: run ID, status, goal, serialized graph snapshot, partial node outputs, timestamps
• RunRepository with create, update_status, save_node_output, list, get operations
• Executor checkpoints after every node completion so a crash mid-run loses at most one node
• resume_run(run_id) replays already-completed node outputs as synthetic events, then continues live execution from the first incomplete node
• REST endpoints: POST /api/orchestrator/run, GET /api/orchestrator/runs, GET /api/orchestrator/runs/:id, POST /api/orchestrator/runs/:id/resume
• Merged in feat(orchestrator): Phase C — executor, compaction, synthesis, CLI/Axum/GUI wiring (#492) #499

---

Phase D — Human-in-the-Loop Approval Gates (feat/orchestrator-phase-d) #493

Blocking approval checkpoints at configurable granularity.

• ApprovalGate middleware intercepts execution at plan, node, or tool level depending on HitlMode
• ApprovalStore maps live approval requests to oneshot channels; the executor suspends and holds the SSE stream open while waiting
• POST /api/orchestrator/approve/:id accepts { decision: approve | approve_with_edits | reject, edited_graph?, reason? }
• approve_with_edits replaces the live graph mid-run; reject terminates the run with a user-facing error message
• Run status transitions to awaiting_approval in SQLite while suspended; fully resumable after approval
• Merged in feat(orchestrator): Phase D — HITL approval gates, SQLite persistence, run-resumption (#493) #500

---

Phase E — Virtual Proxy Routing & OpenWebUI Integration (feat/orchestrator-phase-e) #494

Transparent integration with the existing proxy layer and OpenWebUI.

• Virtual model gglib-orchestrator registered in the proxy routing table
• Incoming /v1/chat/completions requests addressed to gglib-orchestrator are intercepted and routed to the orchestrator engine rather than a llama.cpp backend
• Response is re-encoded as a standard OpenAI streaming chat completion so any OpenAI-compatible client (including OpenWebUI) receives well-formed SSE without knowing about the orchestrator internals
• HITL approval requests surface as assistant messages with structured JSON, allowing approval via chat reply in OpenWebUI
• Integration tests cover end-to-end virtual model routing with SSE frame validation
• Merged in feat(proxy): Phase E — virtual model routing in the OpenAI-compatible proxy #501

---

Phase F — Native Tauri/React UI (feat/orchestrator-phase-f) #495

Full native frontend for the orchestrator, following all existing UI conventions.

• OrchestratorContext — reducer over the full OrchestratorEvent stream; state includes phase, per-node states, synthesis text, pending approval, and runs list
• useOrchestrator hook — bridges SSE → context dispatch, manages AbortController lifecycle, exposes run / resume / cancel / approve / loadRuns
• DagView — topologically-sorted indented tree of TaskGraph nodes with live status badges; no new heavy dependencies
• NodePanel — collapsible per-node panel: goal, tool allowlist, streaming text, tool call log with timing, output preview, error display
• HitlApprovalModal — plan/node/tool approval modals with plan JSON viewer, optional approve_with_edits flow with JSON validation, and reject-with-reason path
• RunsList — resumable runs entry with status filter tabs and click-to-resume
• #orchestrator hash route wired in App.tsx; HTTP transport only — no isTauriApp branching, no new #[tauri::command]
• 21 new reducer unit tests; all 606 frontend tests pass; zero TypeScript errors
• Merged in feat(orchestrator): Phase F — native frontend polish, DAG visualization, HITL modals, run management #502

---

Phase G — Hierarchical Subgraphs, Role Catalog & Team Events (feat/orchestrator-phase-g) #508

Foundation for multi-tier agent hierarchies.

• TaskNodeKind enum: Leaf (default) | Team { subgraph: Box<TaskGraph> } — serde snake_case, #[serde(default)] for backward compat with Phase F runs
• RoleId / RoleSpec / RoleCatalog — 7 built-in specialist roles (researcher, red-team, fact-checker, writer, editor, critic, synthesizer) with system prompt fragments, default tool allowlists, and temperature hints
• TeamStarted { team_id, role } / TeamSynthesized { team_id, compacted_output } SSE events
• validate_acyclic() recurses into Team subgraphs; total_node_count() aggregates across depth
• Phase F regression fixture verifies backward-compat deserialization
• Merged in feat(core): Phase G — hierarchical subgraphs, role catalog, TaskNodeKind #511

---

Phase H — Hierarchical Planner (Chief of Staff + Department Directors) (feat/orchestrator-phase-h) #506

Two-tier planning layer that decomposes a goal into departments before assigning leaf tasks.

• chief_of_staff::brief() — single structured-output LLM call returning ≤5 DepartmentBrief structs; validates, deduplicates, and filters roles to catalog entries; graceful fallback on failure
• planner::plan() — new canonical entry point; fans out one director::plan per department in parallel via JoinSet; assembles results into nested TaskGraph (Team nodes + synthesizer leaf)
• director::plan() accepts optional DepartmentBrief to inject context and round-robin assign roles to leaf nodes
• 4 integration tests: 3-dept × 4-leaf fan-out, single-dept, empty CoS fallback, round-robin role assignment
• Merged in feat(agent): Phase H — Hierarchical Planner (Chief of Staff + Department Directors) #512

---

Phase I — Executor Recursion & spawn_subteam Dynamic Interrupt (feat/orchestrator-phase-i) #504

Workers can dynamically request child sub-teams at runtime.

• spawn_subteam tool definition registered in worker tool allowlist; SpawnCapturingExecutor intercepts calls into a per-worker sink
• Post-wave spawn-request loop: optional HITL gate (ApprovalKind::SpawnSubteam), plan() call, SubteamSpawned event, recursive run_wave_loop
• max_team_depth guard (default: 9) prevents unbounded recursion; MaxDepthExceeded error variant
• Tests: 3-dept/12-leaf hierarchical run; auto-approve spawn path; HITL-gated spawn path
• Merged in feat(orchestrator): Phase I — executor recursion and spawn_subteam dynamic interrupt #513

---

Phase J — NodeBudget & warn-only RunCostEstimate (feat/orchestrator-phase-j) #509

Soft advisory budget and token-cost estimator — execution always proceeds.

• NodeBudget enum (Solo / SmallTeam / TaskForce / Department / Custom) with const upper_bound()
• RunCostEstimate { node_count, est_tokens, est_wall_seconds } SSE event emitted after PlanProposed; tracing::warn! fires only when plan exceeds budget — approve is never disabled
• estimator.rs — pure cost module, 2000 tokens/node at 50 tps, two doc-tests
• Frontend: costEstimate session field in OrchestratorContext; yellow advisory banner in HitlApprovalModal and Orchestrator page when estWallSeconds > 60 or node count > 80% of budget
• 7 new Vitest tests for banner show/hide logic; approve button always enabled
• Merged in feat(orchestrator): Phase J — NodeBudget + warn-only RunCostEstimate (#509) #514

---

Phase K — Conversational Steering & GraphDiff Preview (feat/orchestrator-phase-k) #507

Side-channel note injection during live runs and LLM-driven graph mutation with visual preview.

• GraphDiff enum (7 variants: AddNode, RemoveNode, SplitNode, RerouteEdge, SetRole, SetTools, WrapInTeam) with apply_diff clone-and-swap rollback
• NoteQueue — Arc<Mutex<VecDeque<String>>> injected per run; wave-drain loop applies queued steering notes before each wave
• POST /api/orchestrator/steer — accepts { graph, instruction }, returns { diff: GraphDiff } via LLM structured output
• POST /api/orchestrator/runs/{run_id}/note — appends instruction to in-flight run queue; 202 Accepted or 404
• SteeringPanel component — instruction textarea, diff preview with colour-coded DiffBadge (green/red/amber), Apply / Discard; applyDiff pure helper also used in HitlApprovalModal
• 9 Rust apply_diff tests (7 happy-path + 2 error); 10 Vitest component tests
• Merged in feat(orchestrator): Phase K — Conversational Steering + GraphDiff Preview #515

---

Phase L — Casting Sheet, Collapsible Team Canvas & NodePanel Quick Actions (feat/orchestrator-phase-l) #505

Frontend polish; no backend changes.

• CastingSheet — actor-card grid; recursive collectLeafNodes() traversal through Team subgraphs; 7-role icon map with User fallback; tool/dependency chips; full keyboard/ARIA accessibility
• DagView rewrite — team nodes as collapsible group headers with aria-expanded; sessionStorage persistence of expanded-team set keyed by runId
• NodePanel quick actions — 4 context-aware buttons (Add critic, Split into 3 parallel, Wrap in team, Re-run with feedback); fires /note when runId present, /steer with inline diff preview otherwise
• Orchestrator page view toggle (Team Canvas / Casting Sheet) with aria-pressed
• OrchestratorPlanPreview.tsx (legacy Phase C page) deleted
• 28 new Vitest tests across CastingSheet, DagViewTeams, NodePanelQuickActions; 651 frontend tests passing
• Merged in feat(orchestrator): Phase L — Casting Sheet, Team Canvas, NodePanel Quick Actions #516

---

Phase M — Time-Travel Rewind to a Previous Wave (feat/orchestrator-phase-m) #510

Rewind a completed run to an earlier wave checkpoint and re-execute from there.

• Every persisted event tagged with wave_index; WaveCompleted { wave_index, node_count } SSE event emitted at the end of each wave
• OrchestratorRepositoryPort::truncate_events_after_wave — new port method; SQLite implementation deletes events with wave_index > target; wave_index INTEGER NOT NULL DEFAULT 0 column with silent additive migration
• OrchestratorConfig::rewind_to_wave: Option<u32> — executor resumes wave numbering from rewind_to_wave + 1
• POST /api/orchestrator/runs/{id}/rewind — validates run is not active (409 if Running/AwaitingApproval), truncates DB, re-executes via SSE stream
• WaveScrubber component — horizontal waypoint row (W0, W1, …) from the event log; confirmation alertdialog before rewind; hidden when fewer than 2 waves exist; disabled prop blocks interaction during active run
• rewindOrchestratorRun() client helper; useOrchestrator exposes rewind(runId, waveIndex, steeringNote?)
• DB test: inserts events across 3 waves, truncates after wave 0, asserts only wave-0 events remain; 8 Vitest component tests; 659 frontend tests passing
• No breaking changes to existing runs (DEFAULT 0 handles legacy rows)
• Merged in feat(orchestrator): Phase M — time-travel rewind to a previous wave #517

---

GUI Cleanup & CLI Orchestrator Refactor (post-merge polish)

After all sub-PRs were merged into epic/orchestrator, two final workstreams cleaned up loose ends and added a first-class CLI surface for the engine.

GUI — Remove redundant top-bar button (430ddc3)

The top-bar "Orchestrator" button became redundant once the DAG renders inline inside the chat thread (Phase K/L). Removed OrchestratorButton from Header and the standalone nav route; the in-chat CouncilEventRenderer is now the single rendering surface.

CLI — 6-phase orchestrator refactor (9720ef1–d94a5fe)

Built a first-class council command family in gglib-cli that fully surfaces the DAG executor from the terminal:

Commit	What landed
9720ef1	presentation/dag.rs — shared DAG tree renderer; node_color(status) stable ANSI colours on every PlanProposed event
deb9dc6	CouncilCmd enum (Run, List, Show, Resume, Rewind); split council.rs into handlers/council/ directory module (one file per subcommand + shared approve.rs / render.rs)
880ae3a	--approval-timeout <SECS> + --approval-timeout-action <reject|approve>; [e]dit plan gate opens JSON in $EDITOR; async stdin via tokio::io::stdin() + AsyncBufReadExt
e52db27	--json flag — every CouncilEvent serialised as one JSONL line on stdout; all ANSI/progress output suppressed from stdout; requires --hitl none
7808241	presentation/input.rs background stdin router: /note <text> → NoteQueue; other lines → mpsc::UnboundedReceiver for HITL prompts; full rewind.rs (truncate events, reset nodes, pre-seed note queue, re-execute)
d94a5fe	README rewrite (new "Orchestrator (council)" section; remove stale debate-REPL docs); mod.rs architecture doc; commands.rs doc cleanup; cargo fmt

---

Quality gates (all phases)

• cargo clippy --workspace --all-targets --all-features -- -D warnings ✅
• cargo fmt --check ✅
• ./scripts/check_boundaries.sh ✅
• cargo test --workspace ✅
• npm run test:run (606 tests) ✅