Description
src/lib/orchestrator.ts has grown to 976 lines and continues to expand. It handles scheduling, job launching, merge train control, PR creation, notifications, checkpoint management, environment preparation, and tmux orchestration — a textbook god object.
This makes the codebase harder to understand, test, and extend. Each new feature (touchSet prediction, run history, smart retry) would further bloat this file.
Use Case
- Testability: Individual modules can be unit-tested in isolation without mocking the entire orchestrator.
- Maintainability: New contributors can understand one module without reading 976 lines.
- Extensibility: Phase 2/3 features (touchSet, history, retry policies) have clear homes.
Proposed Solution
Extract into focused modules while keeping the Orchestrator class as a thin coordinator:
| New Module |
Responsibility |
Approximate Lines |
src/lib/plan-manager.ts |
Plan validation, lifecycle (start/resume/cancel), state transitions |
~200 |
src/lib/job-launcher.ts |
Worktree setup, prompt file writing, tmux session creation, OMO mode handling |
~250 |
src/lib/reconciler.ts |
The reconcile loop, dependency checking, job scheduling |
~200 |
src/lib/merge-train.ts |
Already exists — ensure orchestrator delegates fully |
— |
The Orchestrator class becomes a ~150-line coordinator that wires these modules together.
Incremental approach (recommended):
- Extract
JobLauncher first (most self-contained, easiest to test).
- Extract
Reconciler next (the core loop).
- Extract
PlanManager last (most entangled with state).
- Each extraction should be a separate PR with tests.
Files Involved
src/lib/orchestrator.ts — the 976-line god objectsrc/lib/merge-train.ts — already extracted (good pattern to follow)src/lib/orchestrator-singleton.ts — may need minor updates
Additional Context
From the master audit report (Section 7: Architecture): "orchestrator.ts is 891 lines (was 829 at original audit) — god object handling scheduling, merging, PR creation, notifications, checkpoints. Has grown, not shrunk." Now at 976 lines.
This refactor should happen after the plan correctness bugs (#10, #11, #12, #13, #15) are fixed, so the expected behavior is locked in with tests first.
Description
src/lib/orchestrator.tshas grown to 976 lines and continues to expand. It handles scheduling, job launching, merge train control, PR creation, notifications, checkpoint management, environment preparation, and tmux orchestration — a textbook god object.This makes the codebase harder to understand, test, and extend. Each new feature (touchSet prediction, run history, smart retry) would further bloat this file.
Use Case
Proposed Solution
Extract into focused modules while keeping the
Orchestratorclass as a thin coordinator:src/lib/plan-manager.tssrc/lib/job-launcher.tssrc/lib/reconciler.tssrc/lib/merge-train.tsThe
Orchestratorclass becomes a ~150-line coordinator that wires these modules together.Incremental approach (recommended):
JobLauncherfirst (most self-contained, easiest to test).Reconcilernext (the core loop).PlanManagerlast (most entangled with state).Files Involved
src/lib/orchestrator.ts— the 976-line god objectsrc/lib/merge-train.ts— already extracted (good pattern to follow)src/lib/orchestrator-singleton.ts— may need minor updatesAdditional Context
From the master audit report (Section 7: Architecture): "orchestrator.ts is 891 lines (was 829 at original audit) — god object handling scheduling, merging, PR creation, notifications, checkpoints. Has grown, not shrunk." Now at 976 lines.
This refactor should happen after the plan correctness bugs (#10, #11, #12, #13, #15) are fixed, so the expected behavior is locked in with tests first.