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: 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/ralph-bench@2.4.2

Download ralph-bench 2.4.2

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/ralph-cli@2.4.2

Download ralph-cli 2.4.2

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/ralph-e2e@2.4.2

Download ralph-e2e 2.4.2