What's Changed in v2.4.2
This release focuses on completion integrity, preflight validation, spec-driven pipeline alignment, and a major KISS cleanup removing ~2,500 lines of dead code and redundant presets.
Highlights
- 🔒 Loop completion now requires a proper JSONL event — agents can no longer confabulate completion by printing the completion promise string; they must emit it via
ralph emit (#141)
- 🛫
ralph preflight validates your environment before orchestration starts — catches misconfigured backends, dirty git state, and incomplete specs before wasting iterations (#146)
- 🧹 KISS cleanup across 8 items — removed chaos_mode dead code (~560 LOC), 13 redundant presets, and reduced constraint density in SOPs by 77% (253 → 59 MUSTs) (#146)
Features
- Completion only via JSONL event:
LOOP_COMPLETE is now only accepted as a structured event, preventing agents from confabulating completion (#141)
- Graceful
/stop command: New Telegram /stop and CLI ralph stop for clean loop shutdown via signal file (#141)
ralph bot token set: Secure Telegram bot token management with keychain support (#141)ralph preflight: Environment validation (backends, git state, spec completeness) that auto-runs before ralph run (#146)ralph doctor: Diagnostic command to inspect local environment, similar to brew doctor (#146)ralph tutorial: Interactive onboarding for first-time users (#146)ralph skill list: Improved skill discovery across nested directories and parent workspaces (#146)- Persistent mode:
persistent: true keeps the loop alive after LOOP_COMPLETE for daemon-style orchestration (#146)
- Self-Healer hat: Five automated recovery strategies (rollback, skip, reduce-scope, fallback, escalate) (#146)
- Spec acceptance criteria parser & test stub generation: Structured Given/When/Then extraction with 1:1 test stub mapping for TDD automation (#146)
- Spec verification backpressure gate: Blocks
build.done when spec acceptance criteria aren't satisfied by passing tests (#146)
- New backpressure gates: cargo audit, coverage, verifier quality, and performance regression (#146)
extra_instructions config: YAML anchors for sharing instruction blocks across hats (#146)- Separate
human_pending queue: Human-in-the-loop events get their own EventBus queue, preventing message drops during busy iterations (#146)
- TUI shows max iterations: Header displays
[iter 3/50] for operator visibility (#146)
--yolo flag for Codex adapter: Enables unattended Codex operation (#146)- Session recorder behind feature flag:
recording feature gate reduces default binary size (#146)
Fixes
- Fix
human.interact event file resolution: wait_for_response() now reads from the current-events marker instead of hardcoded events.jsonl, fixing responses never being received (#146)
- Fix wide character rendering in TUI:
ContentPane now uses unicode-width for proper emoji/CJK display (#146)
- Preserve TUI iteration buffers across
task.start: No longer wipes output history and iteration count on task reset (#146)
- Fix UTF-8 boundary truncation: Content truncation no longer splits multi-byte characters (#146)
- Fix nested skill discovery: Skills in nested directories and parent workspaces are now found correctly (#146)
- Allow partial merge queue ID resolution:
ralph loops merge accepts prefix matches (#146)
- Drain PTY output after exit: Last lines of agent output in TUI mode are no longer lost (#146)
- Resolve 26 clippy warnings: Accumulated pedantic warnings cleaned up across workspace (#146)
Documentation
- Fix
.agent/ paths to .ralph/agent/ in concept docs (#144) — thanks @Ahmed-Abdalla-Abdelrehim!
- Rename
interact.human → human.interact for naming consistency (#146)
- Updated installation guide, getting started tutorial, and backend configuration docs (#146)
- Added Rust code examples to API reference docs (#146)
- Added GitHub issue templates (#146)
Refactors & Cleanup
- Remove chaos_mode dead code (~560 LOC across 10 files) (#146)
- Remove 13 redundant presets, slimming from 27 to 14 core presets (#146)
- Decouple telegram from core via
RobotService trait in ralph-proto, enabling future Slack/Discord backends (#146)
- Consolidate ralph-loop + ralph-diagnostics into single ralph-operations skill (-318 LOC) (#146)
- Unify TDD skills into single test-driven-development skill with 3 input modes (-240 LOC) (#146)
- Remove unused ralph-adapters dep from ralph-tui (#146)
- Reduce SOP constraint density by 77% (code-assist: 111→32, PDD: 85→19, code-task-generator: 57→8 MUSTs) (#146)
Testing
- Massive test coverage expansion: 20+ test commits adding integration tests for preflight, run, presets, skills, tasks, web, and more (#146)
Full Changelog: https://github.com/mikeyobrien/ralph-orchestrator/compare/v2.4.1...v2.4.2
ralph-bench 2.4.2
Install ralph-bench 2.4.2
Install prebuilt binaries via shell script
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-bench-installer.sh | sh
Install prebuilt binaries into your npm project
npm install @ralph-orchestrator/[email protected]
Download ralph-bench 2.4.2
| File | Platform | Checksum |
|--------|----------|----------|
| ralph-bench-aarch64-apple-darwin.tar.xz | Apple Silicon macOS | checksum |
| ralph-bench-x86_64-apple-darwin.tar.xz | Intel macOS | checksum |
| ralph-bench-aarch64-unknown-linux-gnu.tar.xz | ARM64 Linux | checksum |
| ralph-bench-x86_64-unknown-linux-gnu.tar.xz | x64 Linux | checksum |
ralph-cli 2.4.2
Install ralph-cli 2.4.2
Install prebuilt binaries via shell script
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-cli-installer.sh | sh
Install prebuilt binaries into your npm project
npm install @ralph-orchestrator/[email protected]
Download ralph-cli 2.4.2
| File | Platform | Checksum |
|--------|----------|----------|
| ralph-cli-aarch64-apple-darwin.tar.xz | Apple Silicon macOS | checksum |
| ralph-cli-x86_64-apple-darwin.tar.xz | Intel macOS | checksum |
| ralph-cli-aarch64-unknown-linux-gnu.tar.xz | ARM64 Linux | checksum |
| ralph-cli-x86_64-unknown-linux-gnu.tar.xz | x64 Linux | checksum |
ralph-e2e 2.4.2
Install ralph-e2e 2.4.2
Install prebuilt binaries via shell script
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-e2e-installer.sh | sh
Install prebuilt binaries into your npm project
npm install @ralph-orchestrator/[email protected]
Download ralph-e2e 2.4.2
| File | Platform | Checksum |
|--------|----------|----------|
| ralph-e2e-aarch64-apple-darwin.tar.xz | Apple Silicon macOS | checksum |
| ralph-e2e-x86_64-apple-darwin.tar.xz | Intel macOS | checksum |
| ralph-e2e-aarch64-unknown-linux-gnu.tar.xz | ARM64 Linux | checksum |
| ralph-e2e-x86_64-unknown-linux-gnu.tar.xz | x64 Linux | checksum |