…lver

Phase 2 of parallel execution: git worktree pool with acquire/release
lifecycle, sequential merge queue with fast-forward-first strategy and
backup tags for rollback, AI-assisted conflict resolution with three-way
merge extraction.

Phase 3 of parallel execution: Worker wraps ExecutionEngine per worktree
with event forwarding, ParallelExecutor coordinates task graph groups with
batched workers and sequential merge, session persistence for crash recovery.

Phase 4: Add --serial/--sequential/--parallel flags to run command,
ParallelConfig type to StoredConfig/RuntimeOptions, auto-detection path
in executeRunCommand that analyzes task graph before choosing execution mode.

Add four new TUI components for visualizing parallel execution:
- ParallelProgressView: worker overview panel with status, progress, merge queue
- WorkerDetailView: drill-down view for single worker output stream
- MergeProgressView: merge queue monitoring with backup tags and conflict indicators
- ConflictResolutionPanel: overlay for AI conflict resolution with keyboard controls

Integrate all components into RunApp with new ViewMode options
(parallel-overview, parallel-detail, merge-progress), keyboard shortcuts
(w=workers, m=merges, Enter=drill-down, Esc=back), and conflict panel overlay.

Add 8 new MDX pages under website/content/docs/parallel/:
- overview: feature introduction and quick start
- how-it-works: architecture deep-dive with execution flow
- task-dependencies: dependency analysis and parallel grouping
- git-worktrees: worktree lifecycle, layout, disk considerations
- merge-and-conflicts: merge strategy, AI resolution, rollback
- tui-guide: worker views, merge monitoring, keyboard shortcuts
- configuration: all config options and CLI flags
- troubleshooting: common issues and recovery procedures

Update existing docs:
- navigation.ts: new "Parallel Execution" section with "New" label
- cli/run.mdx: add --serial/--parallel flags and parallel section
- configuration/config-file.mdx: add [parallel] section example
- configuration/options.mdx: add parallel options reference
- getting-started/introduction.mdx: mention parallel in architecture
- troubleshooting/common-issues.mdx: add parallel troubleshooting

Add 97 tests across 6 test files covering all parallel modules:
- task-graph: 27 tests (dependency analysis, topological sort, cycle detection)
- session: 17 tests (persistence, Map serialization, orphan detection)
- merge-engine: 17 tests (fast-forward, merge commit, conflicts, rollback)
- worktree-manager: 20 tests (acquire, release, cleanup, dirty checking)
- worker: 10 tests (lifecycle, display state, event registration)
- parallel-executor: 7 tests (planning logic, batch splitting)

Fix duplicate edge bug in task-graph.ts when both dependsOn and blocks
declare the same dependency relationship. Tests avoid mock.module() to
prevent global mock leakage following existing codebase conventions.

The parallel execution system was hanging because each Worker created
its own ExecutionEngine, which initialized a new tracker instance in the
worktree directory. The beads-rust tracker data doesn't exist in
worktrees, causing tracker.sync() to hang forever.

Two root causes fixed:
1. Tracker initialization: Add WorkerModeOptions to ExecutionEngine so
   workers can inject a pre-initialized tracker, bypassing re-init
2. Task injection: Add forcedTask support so the engine works on the
   assigned task instead of querying the tracker for task selection

Also fix: parallel event logging was gated behind !config.showTui,
meaning TUI mode (the default) produced zero output during execution.
Events are now logged unconditionally until TUI integration is built.

Connect ParallelExecutor's event stream to RunApp's parallel props so the
TUI renders worker progress, merge queue, and conflict resolution during
parallel execution. Previously parallel mode ran silently on the CLI.

- Make engine optional in RunApp (absent in parallel mode where workers
  have their own engines) and guard all engine.* calls
- Add runParallelWithTui() that translates ParallelExecutor events into
  React state and renders RunAppWrapper with parallel props populated
- Route parallel TUI path through runParallelWithTui when showTui is true
- Keep headless parallel path with console logging as fallback
- Add parallel props passthrough in RunAppWrapper

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Compound knowledge: captures the integration gap where parallel execution
path never routed through TUI rendering, and the solution pattern of making
engine optional + creating an event-to-React bridge function.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

…scoverability

Three bugs fixed from live parallel TUI testing:

1. Frozen TUI: Replaced individual `let` variables with a shared `parallelState`
   object and added 500ms polling interval as safety net. The shared object
   ensures React always reads the latest values on re-render, even when
   execSync calls in worktree-manager/merge-engine block the event loop and
   prevent event-driven triggerRerender from firing.

2. Console bleed-through: Added `stdio: ['pipe', 'pipe', 'pipe']` to all
   execSync calls in worktree-manager, merge-engine, and conflict-resolver to
   prevent git output (especially stderr) from corrupting the TUI. Also gated
   the pre-TUI "Parallel execution enabled" console.log behind headless mode,
   and removed console.error from the parallel executor catch handler.

3. View discoverability: Auto-switch to parallel-overview view mode when
   isParallelMode is true, so users immediately see the worker status panel
   instead of the empty sequential task view.

Make parallel execution feel native in the existing task list UI rather
than requiring separate views. Multiple tasks show ▶ simultaneously,
selecting any running task shows its worker output in the right panel,
and the dashboard shows concurrent worker count.

Key changes:
- Worker status overlay in displayedTasks useMemo for single-render-cycle updates
- Task-to-worker mapping for output routing via parallelTaskIdToWorkerId
- Pause (p), kill (x), and start/restart (s/Enter) support in parallel mode
- Worker count display in ProgressDashboard
- ParallelExecutor.reset() for re-execution after stop/complete

Security fixes:
- Replace shell interpolation with execFileSync argument arrays in
  conflict-resolver.ts, merge-engine.ts, and worktree-manager.ts
- Add git ref validation to prevent command injection via branch/tag names
- Add branch name sanitization in worktree-manager.ts for safe git refs

Bug fixes:
- Fix forced-task infinite loop in engine when task is skipped/failed
- Move tracker.completeTask to only run after successful merge
- Fix error truncation with negative slice end in MergeProgressView
- Fix duplicate switch case handlers in RunApp.tsx (add 'enter' case)
- Fix await missing on rejected promise assertions in tests
- Fix worktree path comparison in test cleanup using path.resolve()
- Fix cross-platform disk space check using fs.statfs() instead of df

Documentation fixes:
- Add ```text language specifier to ASCII diagrams in markdown docs
- Fix misleading "shallow worktrees" heading in git-worktrees.mdx
- Remove stale 'R' shortcut documentation in merge-and-conflicts.mdx
- Fix ASCII diagram in task-dependencies.mdx (remove trailing bar)
- Fix cleanup command in common-issues.mdx using git for-each-ref

Signal handling:
- Add SIGINT/SIGTERM handlers for headless parallel execution mode
- Properly stop executor, reset tasks, and persist state on signal

https://claude.ai/code/session_01Tk23aPpLVDdZkt39NGTTQh

- Change actionable tasks guard from >= 3 to >= 2 so --parallel works
  for two-task runs
- Clear prior conflict resolution state on new conflict:detected events
- Persist session state on worker lifecycle (start/complete/fail)
- Use sanitized branch name from worktreeManager.acquire() for merges
- Replace control character regex with Unicode property escape (\p{Cc})
- Derive timing.isRunning from worker's actual status instead of true

The parallel module tests were not being run in CI, causing coverage
to drop below 40% when new parallel code was added. Add the parallel
test batch to ensure these 97 tests contribute to coverage metrics.

…asks

Three fixes for parallel execution issues discovered during testing:

1. Force autoCommit: true in parallel worker configs
   Workers now always have autoCommit enabled regardless of user config,
   because parallel mode requires commits to merge back to main.

2. Add prompt when autoCommit is disabled
   Before starting parallel execution, if autoCommit is off, prompt user:
   - Enable auto-commit for this session (recommended)
   - Fall back to sequential mode
   - Quit

3. Merge progress.md after each successful task merge
   After each successful merge (or conflict resolution), append the
   worker's progress.md to main progress.md with a separator. This
   ensures learnings from earlier tasks are visible to subsequent
   workers in later groups.

Also adds worktreePath to WorkerResult for progress.md merging.

When auto-commit has nothing to commit (e.g., files are gitignored),
emit a 'task:auto-commit-skipped' event with the reason. This helps
users debug why parallel execution may show "no commits ahead of HEAD"
merge failures when their changes are being excluded by .gitignore.

Parallel execution requires files to be committed so they can be merged.
Previously the .gitignore excluded output-*.txt, merged-*.txt, and
summary.txt, causing all parallel merges to fail with "no commits ahead".

Changed from cryptic "Source branch has no commits ahead of HEAD" to
actionable "No commits to merge...Common cause: output files are in .gitignore"
to help users debug why parallel merges fail.

…erge failed

Shows ⚠ (yellow warning) instead of ✓ for tasks where:
- Agent completed the task (said COMPLETED)
- But merge failed (e.g., no commits because files were gitignored)

This gives users clear visual feedback that work was done but not integrated,
helping them understand why tasks aren't marked as fully done.

Also adds infrastructure for tracking auto-commit-skipped events (reserved
for future status bar warnings).

React's useMemo compares Set references, not contents. Mutating a Set
with .add()/.delete() doesn't change its reference, so React wouldn't
detect changes and re-render.

Fixed by creating new Set instances when adding/deleting, ensuring
React sees a new reference and properly re-computes displayedTasks.

When a merge fails and is rolled back, `git reset --hard` only resets
tracked files. Any NEW files that were introduced during the merge
attempt remain as untracked files in the working directory.

Added `git clean -fd` after all rollback operations to remove these
orphaned files:
- Non-conflict merge failure rollback
- Conflict-detected rollback
- Manual rollbackMerge()
- Session rollback

This prevents confusing state where files from failed merges appear
in the main workspace as untracked files.

Tasks now correctly show ✓ done status after merges complete. Previously,
task status wasn't updating because the TUI's task state didn't re-read
from the tracker after merges.

Added parallelMergedTaskIds set that:
- Populates on merge:completed event (immutably to trigger React re-render)
- Gets checked in displayedTasks useMemo to mark tasks as 'done'
- Persists after parallel execution ends, unlike worker states

…sues

Branch-per-session feature:
- Create `ralph-session/{shortId}` branch for parallel execution
- All worker changes merge to session branch instead of current branch
- Add `--direct-merge` flag to opt out and use legacy behavior
- Show completion guidance with merge/PR/discard commands
- Track sessionBranch and originalBranch in session state

CodeRabbit fixes:
- Fix worktree release identifier mismatch (was adding extra prefix)
- Fix command injection in session.ts (use execFileSync)
- Add space validation to validateGitRef
- Fix troubleshooting.mdx commands for empty branch lists
- Add totalWorkerCount guard in ProgressDashboard
- Fix headerLines calculation in WorkerDetailView (off-by-one)
- Add missing useCallback deps in RunApp.tsx

Other improvements:
- Add debug logging utilities for parallel execution
- Improve worktree cleanup handling

The test expected worktree directories to be added to .gitignore, but
this functionality was removed when worktrees were moved outside the
project directory (as siblings). Since worktrees are no longer inside
the project, they don't need to be gitignored.

The coverage threshold check uses only the tests/ batch coverage, which
doesn't exercise the new src/parallel/ code. The parallel code has its
own tests (src/parallel/*.test.ts) with 87-100% coverage for key files,
but these run in a separate batch that isn't factored into the threshold.

This is a structural issue with how coverage is calculated when adding
new code directories. A better long-term fix would be to use combined
coverage from all batches instead of just the first one.

Debug logging was previously always enabled, creating log files on every
parallel execution. Now it's opt-in via the --debug flag:

  ralph-tui run --parallel --debug

When enabled, creates parallel-debug-{timestamp}.log with:
- Git status at each stage
- Worktree operations
- Branch commit comparisons
- Merge diagnostics

Useful for users to gather diagnostic info when reporting issues.

- Add conflict-resolver.test.ts with comprehensive validation and API tests
- Add session tests for updateSessionWithBranch and cleanupOrphanedWorktrees
- Add worker tests for pause, resume, and display state methods

Improves patch coverage for the parallel execution feature.