Mastra Orchestrator Overview
The Mastra orchestrator is the GitHub-facing Code Assist service. In checkouts
that include the app source, it lives under apps/mastra-orchestrator/. This
X4 repository may also be used as a docs/integration checkout where the Mastra
source is mirrored or deployed elsewhere.
Mastra receives GitHub events, maintains Code Assist state, starts Codex sessions, runs deterministic tests, opens draft PRs, and posts comments/checks through a GitHub App.
Registered Workflows
| Workflow | Purpose |
|---|---|
code-assist-issue-planning | Convert GitHub issues into implementation-ready plans. |
code-assist-issue-implementation | Implement approved issue plans in bot-owned worktrees and draft PRs. |
code-assist-pr-followup | Continue implementation from PR comments, reviews, failed checks, close events, and promotion events. |
code-assist-pr-testing | Run reusable deterministic testing commands against a repo/worktree. |
code-assist-test-triage | Use read-only Codex to interpret failed tests and propose implementation fixes. |
API Routes
| Route | Meaning |
|---|---|
GET /code-assist/health | Health/configuration check. |
POST /code-assist/github/webhook | GitHub webhook entry point. |
State And Worktrees
| State | Path |
|---|---|
| App root | apps/mastra-orchestrator/ when present in the current checkout |
| Deployed app root | /srv/x4/mastra-orchestrator/app |
| Code Assist SQLite state | .code-assist/planner.sqlite |
| Implementation worktrees | .code-assist/worktrees/<repo>/<issue> |
| Output schemas | schemas/*.schema.json |
Orchestrator Boundary
Mastra coordinates. It does not replace X4 or Codex:
- GitHub events and workflow state are Mastra concerns.
- Worktree setup, git operations, sandbox startup, and deterministic tests are service concerns.
- Agentic reasoning and edits are delegated to Codex through a structured harness.
- PR evidence is posted only after deterministic execution or structured workflow state.
For X4 sandbox setup, this boundary becomes the AI Harness: X4 defines the guarded tool contract, while Mastra can run that contract as a durable backend for GitHub-driven or long-running workflows.