[PR #121] [MERGED] feat: add features.parallel config gate for worktree spawning #146

New issue

Closed

opened 2026-02-27 10:22:24 +03:00 by kerem · 0 comments

kerem commented

2026-02-27 10:22:24 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/mikeyobrien/ralph-orchestrator/pull/121
Author: @mikeyobrien
Created: 1/26/2026
Status: ✅ Merged
Merged: 1/26/2026
Merged by: @mikeyobrien

Base: main ← Head: feature/parallel-config-gate

📝 Commits (1)

ac653a0 feat: add features.parallel config gate for worktree spawning

📊 Changes

3 files changed (+42 additions, -2 deletions)

View changed files

📝 crates/ralph-cli/src/main.rs (+9 -0)
📝 crates/ralph-core/src/config.rs (+31 -0)
📝 crates/ralph-core/src/lib.rs (+2 -2)

📄 Description

Context

The parallel worktree feature (auto-spawning loops in git worktrees when another loop holds the lock) has known bugs:

Recursive spawning issues — Worktree loops can trigger additional worktree spawns, leading to runaway token consumption
Merge queue coordination problems — The queue-based merge system doesn't always work correctly
Orphan worktrees — Ungraceful exits can leave worktrees that aren't properly cleaned up

Until these issues are resolved, users need a way to disable the feature entirely. This PR adds a config gate to do exactly that.

Summary

Adds a features.parallel config option to control whether Ralph spawns worktree loops when the lock is held by another process.

Changes

Add FeaturesConfig struct with parallel: bool field
Check config.features.parallel before spawning worktree
Error with clear message when parallel is disabled and lock is held

Usage

# ralph.yml
features:
  parallel: false  # Disable worktree spawning to avoid known bugs

Behavior

`features.parallel`	Lock available	Lock held
`true` (default)	Run as primary	Spawn worktree loop (buggy)
`false`	Run as primary	Error with clear message

Error Message

Another loop is already running (PID 12345, prompt: "...").
Parallel loops are disabled in config (features.parallel: false).
Use --exclusive to wait for the lock, or enable parallel loops.

Testing

cargo build passes
cargo test passes (all 447+ tests)
Manual QA: verified error when parallel: false and lock held
Manual QA: verified worktree spawns when parallel: true and lock held

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/mikeyobrien/ralph-orchestrator/pull/121 **Author:** [@mikeyobrien](https://github.com/mikeyobrien) **Created:** 1/26/2026 **Status:** ✅ Merged **Merged:** 1/26/2026 **Merged by:** [@mikeyobrien](https://github.com/mikeyobrien) **Base:** `main` ← **Head:** `feature/parallel-config-gate` --- ### 📝 Commits (1) - [`ac653a0`](https://github.com/mikeyobrien/ralph-orchestrator/commit/ac653a0c91af74f9f00a2a5b6a9888bb8cfd174f) feat: add features.parallel config gate for worktree spawning ### 📊 Changes **3 files changed** (+42 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `crates/ralph-cli/src/main.rs` (+9 -0) 📝 `crates/ralph-core/src/config.rs` (+31 -0) 📝 `crates/ralph-core/src/lib.rs` (+2 -2) </details> ### 📄 Description ## Context The parallel worktree feature (auto-spawning loops in git worktrees when another loop holds the lock) has **known bugs**: - **Recursive spawning issues** — Worktree loops can trigger additional worktree spawns, leading to runaway token consumption - **Merge queue coordination problems** — The queue-based merge system doesn't always work correctly - **Orphan worktrees** — Ungraceful exits can leave worktrees that aren't properly cleaned up Until these issues are resolved, users need a way to **disable the feature entirely**. This PR adds a config gate to do exactly that. ## Summary Adds a `features.parallel` config option to control whether Ralph spawns worktree loops when the lock is held by another process. ## Changes - Add `FeaturesConfig` struct with `parallel: bool` field - Check `config.features.parallel` before spawning worktree - Error with clear message when parallel is disabled and lock is held ## Usage ```yaml # ralph.yml features: parallel: false # Disable worktree spawning to avoid known bugs ``` ## Behavior | `features.parallel` | Lock available | Lock held | |---------------------|----------------|-----------| | `true` (default) | Run as primary | Spawn worktree loop (buggy) | | `false` | Run as primary | Error with clear message | ## Error Message ``` Another loop is already running (PID 12345, prompt: "..."). Parallel loops are disabled in config (features.parallel: false). Use --exclusive to wait for the lock, or enable parallel loops. ``` ## Testing - [x] `cargo build` passes - [x] `cargo test` passes (all 447+ tests) - [x] Manual QA: verified error when `parallel: false` and lock held - [x] Manual QA: verified worktree spawns when `parallel: true` and lock held --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>