Startup & Launcher

Unified startup architecture for all entry points.

When to Use

• Working on startup/launch code in any entry point
• Debugging doctor check failures
• Modifying pre-flight checks
• Understanding the supervisor process model
• Troubleshooting "orchestrator won't start" issues

For general orchestrator runtime issues, use troubleshooting skill.

Unified Launcher Architecture

All entry points (CLI, Control Center, MCP) share the same pre-flight checks via infra/launcher.py. Hook verification is part of the doctor checks, not the runtime startup sequence.

CLI (cmd_start)         Control Center (/control/start)     MCP (start)
       |                           |                            |
       v                           v                            v
launch_preflight_only()    launch_subprocess()          launch_subprocess()
       |                           |                            |
       +----------+----------------+----------------------------+
                  |
                  v
         _run_preflight(config)  <-- shared doctor checks
                  |
                  v
         DoctorResult (ok / warning / error)
                  |
          +-------+-------+
          |               |
    CLI: in-process   CC/MCP: supervisor.start()
    build_orchestrator()    (subprocess)

Key Functions

Control Center Auth Boundary

Control Center launches repository engines directly through launch_subprocess() and supervisor.start(). It does not execute target-repo wrapper scripts. If a target repo relies on a wrapper script to export a GitHub token from Keychain, that export is bypassed for Control Center launches.

For repo-specific GitHub auth, inspect the selected repo config itself:

repo:
  github:
    token_env: TIXMEUP_GITHUB_TOKEN
    keyring_service: tixmeup-github
    keyring_username: "${USER}"

token_env only works when the variable is already present in the Control Center process environment. Add keyring_service and keyring_username when Control Center should resolve the token from macOS Keychain without a manual env export.

LaunchResult

@dataclass
class LaunchResult:
    doctor: DoctorResult       # All check results
    launched: bool             # Whether subprocess was started
    status: str                # "ok" | "doctor_error" | "doctor_warning" | "already_running" | "launch_error"
    error: str | None          # Error message if launch_error
    supervisor: dict | None    # Supervisor info (pid, port, instance_id or instances) when available

Doctor Checks

The doctor runs a comprehensive set of checks. Hook verification uses a 2-tier system: Installation and Verification.

Check Categories

Hook Verification

1. Installation: Are hook files present? (is_installed())
2. Verification: Do hooks actually block dangerous commands? (verify_hooks())
3. AI Gate: When due, spawn supported agent CLIs to prove the end-to-end hook gate works.

Verification only runs when installation succeeds. The AI gate respects hooks.ai_gate.interval_days and hooks.ai_gate.dangerous_allow_failure.

Entry Point Flows

CLI (cmd_start in cli.py)

launch_result = launch_preflight_only(config, runner)
if launch_result.status == "doctor_error":
    # Print errors and exit
    return 1
# Continue with in-process orchestrator
orchestrator = build_orchestrator(config)
await orchestrator.startup()
await orchestrator.run_loop()

Control Center (control_start in control_api.py)

launch_result = launch_subprocess(repo_root, config, config_name)
if launch_result.status == "doctor_error":
    return JSONResponse({"error": "doctor_failed", ...}, status_code=422)
if launch_result.status == "already_running":
    return JSONResponse({"error": "already_running", ...}, status_code=409)
if not launch_result.launched:
    return JSONResponse({"error": "launch_failed", ...}, status_code=500)
return JSONResponse({"status": "started", **launch_result.supervisor})

MCP (start in mcp_server.py)

launch_result = launch_subprocess(repo_root, config, config_name)
return {"launch": launch_result.to_dict()}

Runtime Startup (StartupManager)

After the orchestrator process starts (either in-process or via supervisor), StartupManager.run_startup() handles runtime initialization:

1. Emit config event
2. Clean up stale in-progress labels
3. Clean up idle terminal sessions
4. Discover and restore running sessions
5. Check in-progress issues (orphaned labels, open PRs, partial work)
6. Recover pending code reviews
7. Recover pending tech lead reviews
8. Recover pending validation retries
9. Recover orphaned cleanups
10. Resume partial work
11. Audit and cache the queue

Key file: control/startup_manager.py

Key Files

Troubleshooting Startup Failures